Imported from DavidMusk93/recallfs (
AGENTS.md). Install upstream withnpx skills add DavidMusk93/recallfs. Copyright stays with the author.
RecallFS · Agent Rules
本仓库是工程知识库 + 算法训练营。Agent 在此工作必须遵守下列规则。
0. 学习产出的价值（硬约束）
RecallFS 的价值不是为文章或论文制作一次性 demo，而是探索机制、验证边界，并 沉淀可复用的工程知识与资产。demo 只能是回答某个窄问题的实验手段，不能被当作 所有学习任务的默认终点。
| 原则 | 要求 |
|---|---|
| 目标决定产物 | 先判断用户需要概念解释、可复现实验、benchmark、library、tool、runbook 还是 production 组件，再选择交付形态；不得机械套用 demo 目录。 |
| 通用优先 | 当机制具有跨场景复用价值时，优先提炼稳定的数据模型、接口、ownership、错误语义和扩展边界，避免把示例输入类型、单一 workload 或文章中的偶然实现固化进核心。 |
| 生产要求不是演示要求 | 用户要求 production ready 时，demo 或 happy-path prototype 不算完成。必须提供可消费的 API、版本/兼容策略、资源与并发边界、持久化/恢复语义、故障注入、独立 oracle、回归门禁和运维说明。 |
| 证据约束结论 | 只声明证据实际覆盖的保证。未做真实故障、目标机 benchmark、并发验证或兼容测试时，必须把它写成明确边界，不得用“production ready”标签替代证据。 |
| 沉淀而非堆砌 | source、exploration 和 demo 是过程材料；最终产物要把可迁移的机制、失败教训和决策理由固化到可复用 library/tool/design/skill，并纳入索引、测试和维护责任。 |
判断标准：如果删除文章链接后，产物只能作为截图或玩具运行，而不能被另一个 项目通过清晰接口复用，则学习任务尚未完成。
1. 改动及时提交（硬约束）
| 规则 | 说明 |
|---|---|
| 单分支 | RecallFS 仅使用一个分支，即 master；所有改动直接提交并推送到 master，不得创建或保留其他分支。发现其他分支时，必须先确认其提交已被 master 包含，再删除该分支。 |
| 及时 commit | 完成一个可独立描述的单元（骨架 / 单题 / 一项 workflow 优化 / 一批 docs）后 立即 git commit，不要攒大批未提交改动。 |
| 粒度 | 一步一提交；message = short subject + 空行 + long details（完整句子）。 |
| 及时 push | commit 后 尽快 git push origin master。推送失败（如 SSH key）须在回复里明确说明，不得假装已推送。 |
| 不混装 | 骨架与业务题、无关重构不要塞进同一 commit。 |
| 可提交内容 | 算法模块 learning/algorithms/（含 progress、patterns、单题 notes/html/rs）、skills、AGENTS、rules、designs 等长期沉淀 应入库。 |
| 勿提交 | target/、.tmp/、密钥、大体积无关二进制；遵守 .gitignore。 |
| docs 例外 | 根 rules.md 写「部分 docs 可不进 git」：指远端业务仓同步的噪音文档；本仓库主动写的 learning/skill/design 不在此列，要提交。 |
推荐节奏：
改完一个单元 → git status/diff → commit → push → 再开下一单元2. 仓库地图
| 路径 | 角色 |
|---|---|
rules.md |
全局工程与学习态度 |
skills/ |
通用 agent 技能 |
projects/ |
业务系统文档镜像；含可运行小工具（如 xiaohei-local） |
designs/ |
跨项目设计 |
learning/algorithms/ |
LeetCode 算法训练（见该目录 AGENTS.md） |
.grok/skills/leetcode/ |
/leetcode workflow skill |
.trae/skills/html-report/ |
自包含技术 HTML 报告的生成与浏览器验收入口 |
.trae/skills/apple-design/ |
HTML/UI 的排版、材质、反馈与无障碍设计原则 |
.trae/skills/fixed-point-optimization/ |
定点数优化场景发现、数值证明、codegen 与 benchmark 门禁 |
3. 算法训练摘要
详情：learning/algorithms/AGENTS.md 与 WORKFLOW.md。
- 仅 leetcode.cn 免费题；语言 Rust only。
- 触发：
/leetcode <n>/workflow @leetcode <n>。 - 教学闸门：
learn.html未通过前不贴完整 AC 代码。 - HTML：场景 + 多解法 + 统一提交测验；禁止 placeholder 泄题。
4. 网络
下载慢 / GitHub 超时：用户 skill network-accel（socks5h://127.0.0.1:2080 或国内镜像）。
5. 工具与记忆
- LLVM 编译器：需要 LLVM 编译器时，下载固定版本的 Zig，并使用
zig cc/zig c++作为 LLVM frontend；记录 Zig 版本、下载制品 SHA-256 和完整编译参数，不得用未声明的系统 Clang 静默替代。 - C 正确性工具链：C 代码必须先使用 FIL-C 编译和测试；FIL-C 用于验证被执行路径的功能正确性、内存安全和未定义行为边界，不作为完整证明或性能基线。将 FIL-C 及其宿主适配封装在仓库
.tmp/fil-c/，不得提交编译器、VM 镜像或构建产物；若当前平台不能原生运行 FIL-C，使用其官方支持的隔离 Linux 环境，不得静默降级为系统 Clang。 - C benchmark 工具链：性能测试必须在目标机器上切换到原生 C 编译器，并使用适合该机器和生产语义的最佳优化配置；默认至少包含
-O3 -march=native -mtune=native -DNDEBUG，工具链稳定支持时再启用 LTO。benchmark 前仍须通过 FIL-C 正确性验证；优化构建必须保留始终启用的结果校验和可观察 sink，并通过反汇编或负向测试确认待测工作未被 DCE、循环交换或合并。测量时固定 CPU/NUMA，记录 CPU 拓扑、编译器版本、完整 flags、source/binary digest、频率策略和重复次数，并用 wall time 与硬件计数器交叉验证；PMU 不可用时须记录原因，退化为拓扑 + wall time 证据，不得静默换用 VM、模拟器或安全插桩计数。不得把 FIL-C、VM、模拟器或安全插桩运行时间当作目标 CPU 的性能结论。 - 工具实现：有长期复用价值的工具优先使用 Rust 实现，并按领域放入
tools/$domain/；工具二进制和临时输出写入.tmp/。 - 唯一跨会话记忆源：nmem 保存跨会话的经验、设计理由和决策历史；active tracked design 约束当前实现目标，不再将其他记忆文件作为长期沉淀。
- 格式化写入：写入 nmem 前先组织标题、结论、背景、约束、证据和后续动作；复杂流程使用
text代码块中的 ASCII graph，图内不得使用 CJK、全角符号或 Unicode box drawing。 - Immutable memory：已写入的记忆不可原地改写或删除。新认识应创建为新记忆，并通过
EVOLVES或显式语义关系（如supports、depends_on、contradicts）连接已有记忆。
6. Docs 作为 Agent Context
复杂设计文档遵循 designs/agent-ready-docs.md。
- 分型权威：
AGENTS.md约束 policy，active design 描述目标行为， source/schema/migration/tests 描述当前可执行行为，runtime evidence 描述带 revision 与环境的真实观察，历史 study/incident 只对其记录时点负责。冲突是 drift，必须调查，不得静默选择一方。 - 显式 DAG：新建或实质修改的复杂文档声明稳定
doc_id、kind、status、authority、applies_to、depends_on、supersedes和verified_by。 仓库相对路径精确解析；doc ID 通过扫描 frontmatter 唯一解析。缺失、重复或 循环引用在 mutation 前阻断。Agent 按显式依赖拓扑读取；推断出的依赖只能作为 漏边诊断。在 linter 落地前手工执行并记录该校验。 - 语义锚点：行为文档必须包含 concrete worked example、边界/失败语义和 带稳定 ID 的 reconciliation anchors；能自动化的 anchor 应进入测试或探针， 关键行为至少保留一个不与实现同源生成的 oracle。
- 受限生成：generated paths 必须是规范化、仓库相对且互不重叠的路径，
clean_root位于 tracked outputs 外；拒绝..、仓库根目录、symlink escape 和 maintained paths overlap。clean generation 后记录 path/digest manifest， promotion 只能修改声明的 outputs。满足独立验收和禁止手改约束后，代码才可 视为 disposable build product；其余 tracked code 均是 maintained source。 - 薄 prompt：提示 Agent 指向 governing doc 路径与执行协议，不复制完整
设计正文。交付字段必须恰好为
docs_read、anchor_results、ambiguities、changed_artifacts、verification_evidence、successor_id。successor_id是未解决工作的下一个持久 run/task/doc 标识；没有后继时为none。 - 边界：nmem 保存跨会话理由和历史，active tracked design 约束实现目标。 两者冲突时必须报告，不得静默覆盖；tracked decision 变化后追加一条关联旧记录 的 immutable evolved memory。
7. 行为
- 结论先行；复杂流程用 ASCII graph；对比用表格。
- Review 时限：所有 review 必须在 10 分钟内完成。
- HTML 报告交付门禁：生成或修改通用技术 HTML 报告时必须加载
html-report；专项 workflow 的显式增量合同优先于通用合同。报告默认单文件、自包含、证据优先。交付前必须通过真实 HTTP URL 的桌面与 390px 浏览器验收；存在表格时运行 skill 内置 table probe，页面级横向溢出、列语义或内容锚点错误均不得提交。 - 定点优化门禁：发现或提出 fixed-point、magic division、multiply-shift、multiply-high、量化、range mapping、modular reduction 或 decimal scaled integer 优化时必须加载
fixed-point-optimization。没有 hotspot baseline、range/scale/rounding/overflow/error 合同、正确性证据、最终 binary codegen 与目标机 benchmark，不得宣称性能收益或提交手写 magic constant。 - 架构文档交付门禁：
projects/<project>/docs/中的架构分析必须放在对应项目目录。所有 ASCII graph 必须置于text代码块，图内只允许可打印 ASCII 字符与换行，标签使用英文，不得混入 CJK、全角符号或 Unicode box drawing；提交前运行rustc tools/verify_ascii_graphs.rs -o .tmp/verify-ascii-graphs && .tmp/verify-ascii-graphs --ruler <markdown-file>，以校验多竖线图的固定列锚点并用列标尺复核其余箭头和边界。涉及 Cloudflare Tunnel 等托管隧道的对比，必须说明原生能力、为补齐差距额外引入的组件，以及安全/可用性责任边界。 - 不发明「已 AC / 已 push」；无浏览器代操作 leetcode 登录态。