Claw Code 工程知识库深读：基于 AGENTS.md 的 Rust 多 crate 导航、核心符号地图与工程反模式

Claw Code 的 AGENTS.md 是一份为 AI Agent 编写、却同样适用于人类工程师的“项目知识库”，它以 2026-08-16 提交 b71afdd（main 分支）为快照，浓缩了仓库结构、任务定位表、核心符号代码地图、工程约定、反模式清单与标准命令。读完本文，你将掌握如何在这套 11 个 Rust crate 的 Cargo workspace 中快速定位“某个任务该改哪个文件”、理解巨型扁平文件的组织规律，并知道哪些操作在这个仓库中是被明确禁止的。

项目定位：Agent 管理的标本仓库，而非手工产品

AGENTS.md 在 OVERVIEW 一节开宗明义：Claw Code 是 claw CLI agent harness（Claude-Code 风格的命令行代理框架）的公开 Rust 实现，规范代码全部位于 rust/ 目录。与常规产品仓库不同，它自述为 agent-managed exhibit——即由 harness 规划、执行、验证、维护的“展品”，而不是由人手工日常操作的产品。这一点与 README.md 中的声明一致：README 明确写道该仓库“更接近博物馆展品而非产品推介”，真正的生产性开发在上游 harness 中进行。

另一个关键定位是 src/ 目录：AGENTS.md 指出它是 Python porting/parity workspace（移植与对齐工作区），不是生产代码。这解释了为什么仓库同时存在两套代码：rust/ 是唯一的权威实现，src/ 只是用于对照 TypeScript 归档做移植审计的辅助工作区（配合 src/reference_data/ 中的 29 个 JSON 子系统快照），tests/ 则用 Python 标准库 unittest 校验 src/ 与 scripts/。

仓库结构总览

AGENTS.md 的 STRUCTURE 一节给出的目录树如下，这是理解整个仓库的第一张图：

claw-code/
├── rust/      # 权威 Cargo workspace：11 个 crate，产出 `claw` 二进制
├── src/       # Python 移植工作区 + reference_data/ 对齐快照
├── tests/     # 用标准库 unittest 校验 src/ 与 scripts/
├── docs/      # g0XX 门（gate）验证地图 + 主题文档
├── scripts/   # fmt.sh、dogfood-build.sh、roadmap/board 辅助脚本
├── assets/    # 仅供 README 使用的图片
└── install.sh, Containerfile, docker-compose.yml

对照仓库实际内容可以逐条印证：rust/crates/ 下确实有 11 个 crate——api、claw-analog、claw-rag-service、commands、compat-harness、mock-anthropic-service、plugins、runtime、rusty-claude-cli、telemetry、tools；根目录的 scripts/ 下有 fmt.sh、dogfood-build.sh（自举构建脚本）、roadmap-check-ids.sh 等辅助脚本；docs/ 下则是一批以 g002～g013 命名的 gate 验证地图（如 g002-security-verification-map.md、g007-mcp-lifecycle-mapping.md），这些 gate 名称在后文的测试约定中还会出现。

WHERE TO LOOK：从任务到文件的定位表

AGENTS.md 最有实操价值的部分是 WHERE TO LOOK 表——它把“常见开发任务”直接映射到源码文件，并且给出了文件内的锚点行号。完整继承如下：

任务	位置	备注
CLI 子命令	rust/crates/rusty-claude-cli/src/main.rs	手写解析器；CliAction 枚举约 L1163；run() 中的分发逻辑约 L995 起
会话 / 权限 / MCP	rust/crates/runtime/src/	47 个扁平模块
Provider 客户端	rust/crates/api/src/providers/	anthropic.rs + openai_compat.rs
工具定义	rust/crates/tools/src/lib.rs	55 个工具的 spec 表约 L484–L1346
斜杠命令	rust/crates/commands/src/lib.rs	120+ 条斜杠命令 spec 表约 L60–L1045
插件 / hooks	rust/crates/plugins/src/	manifest 为 .claude-plugin/plugin.json
精简 agent harness	rust/crates/claw-analog/src/lib.rs	lib+bin；在 api+runtime 之上的工具循环
RAG HTTP 服务	rust/crates/claw-rag-service/src/	axum；SQLite + 可选 Qdrant
测试 mock 服务	rust/crates/mock-anthropic-service/	以 SCENARIO_PREFIX 为约定的脚本化响应
Python 移植 CLI	src/main.py	argparse：manifest、parity-audit、graphs
对齐参考库	src/reference_data/subsystems/	TS 归档的 29 个 JSON 快照

对上述锚点行号做了逐一核验，结果高度吻合：

• enum CliAction 实际定义在 main.rs 的 L1163，它声明了 DumpManifests、BootstrapPlan、Agents、Mcp、Skills、Plugins、SessionList、ResumeSession 等约 25 个变体，覆盖 CLI 的整个子命令面；
• 工具 spec 表实际由 mvp_tool_specs 函数在 L484 处开始构建，到 L1346 附近结束，是静态的 55 工具表；
• 斜杠命令表实际是 SLASH_COMMAND_SPECS 常量，从 L60 定义到 L1045 收尾，规模与“120+ 条”的表述一致；
• runtime/ 目录下确实是 47 个 .rs 模块（含 session.rs、permissions.rs、mcp_stdio.rs、hooks.rs 等），印证了“47 flat modules”的说法。

一个值得注意的细节：mock-anthropic-service 中约定的场景前缀常量定义在 mock-anthropic-service/src/lib.rs，其值为 PARITY_SCENARIO:——即测试场景通过请求体中携带该前缀来驱动脚本化响应，这是后文 mock parity 机制的入口。

CODE MAP：十个核心符号的引用地图

AGENTS.md 的 CODE MAP 用一张表列出了全仓库最重要的类型符号及其被引用次数（rg 统计，统计范围限定在 rust/crates；文档注明 rust-analyzer 的引用分析在映射时超时，故退而使用 rg 计数）：

符号	类型	位置	引用次数	职责
Session	struct	runtime/src/session.rs L117	229	会话持久化 / 生命周期
ConfigLoader	struct	runtime/src/config.rs L409	83	配置 schema / 加载
PluginManager	struct	plugins/src/lib.rs	48	插件安装 / 注册表
PermissionEnforcer	struct	runtime/src/permission_enforcer.rs L27	35	调度前置的权限门
ConversationRuntime	struct	runtime/src/conversation.rs L130	32	对话循环驱动器
McpServerManager	struct	rust/crates/runtime/src/mcp_stdio.rs L488	30	MCP JSON-RPC 进程管理
HookRunner	struct	rust/crates/runtime/src/hooks.rs L155	25	shell hook 执行
CliAction	enum	rusty-claude-cli/src/main.rs L1163	—	约 25 个子命令变体
mvp_tool_specs	fn	tools/src/lib.rs L484	—	静态 55 工具表
SLASH_COMMAND_SPECS	const	commands/src/lib.rs L60	—	120+ 斜杠命令

这张表的行号全部可以在源码中精确对上：Session 定义于 session.rs L117（同文件 L64/L72/L79 还有 SessionCompaction、SessionFork、SessionPromptEntry 等伴生类型），PermissionEnforcer 在 permission_enforcer.rs L27，ConversationRuntime 在 conversation.rs L130，McpServerManager 在 mcp_stdio.rs L488，HookRunner 在 hooks.rs L155，PluginManager 在 plugins/src/lib.rs L885。引用次数的梯度（229 → 25）本身也说明了架构重心：Session 是全仓库被触碰最多的数据结构，会话生命周期是这套 harness 的脊梁；权限、MCP、hooks 则围绕它构成执行管线——PermissionEnforcer 作为“调度前置权限门”、McpServerManager 负责 JSON-RPC 子进程、HookRunner 执行 shell hook，三者在 runtime/ 扁平模块中各司其职。

工程约定：巨型扁平文件、双输出路径与测试纪律

CONVENTIONS 一节是这个仓库最“反直觉”也最值得先读的部分，逐条继承如下（并附上可核对的证据）：

• 工作区级禁用 unsafe：unsafe_code = "forbid" 由每个 crate 通过 [lints] workspace = true 继承；clippy 配置为 all=warn、pedantic=allow。这与 rust/Cargo.toml 完全一致：[workspace.lints.rust] 下 unsafe_code = "forbid"，[workspace.lints.clippy] 下 all = { level = "warn", priority = -1 }、pedantic = { level = "allow" }，另外还放行了 module_name_repetitions、missing_panics_doc、missing_errors_doc 三项 pedantic 噪音规则。
• 版本与发布策略：Edition 2021、resolver 2、publish = false（见 rust/Cargo.toml），不固定 rust-toolchain（CI 浮动使用 stable），也没有 rustfmt.toml/clippy.toml，全部走默认配置。
• 巨型扁平文件是刻意设计：main.rs 约 19.8k 行（实测 19831 行）、tools/lib.rs 约 10.9k 行（实测 10892 行）、commands/lib.rs 约 7.2k 行（实测 7183 行）。组织方式是位置式的：类型定义 → spec 表 → 分发 → 处理器 → 文件末尾的测试。这意味着在这个仓库里“按职责拆小文件”不是贡献方向，理解文件的纵向分区才是。
• 双输出路径无处不在：每个功能同时提供 render_x 与 render_x_json 两条渲染路径，且 JSON 错误走 stdout、文本错误走 stderr——这个约定保证了脚本消费时 stdout 永远可被 JSON 解析器消化。run() 入口处甚至有针对此约定的行为：main.rs 中在解析参数前就扫描原始 argv（注释标记为 issue #824），以便在 JSON 模式下提前抑制配置弃用警告进入 stderr 的噪音。
• 测试纪律：内联 #[cfg(test)] mod tests 是主力；集成测试通过 CARGO_BIN_EXE_claw 拉起真实二进制子进程（例如 mock_parity_harness.rs、resume_slash_commands.rs 都使用 env!("CARGO_BIN_EXE_claw")），再配合 mock-anthropic-service 完成端到端验证；tempfile 用于一切临时状态；任何修改进程环境变量的测试必须通过 env_lock / test_env_lock 串行化——在 git_context.rs 中可以看到典型的 crate::test_env_lock() 用法，防止并行测试互踩环境变量。
• 注释与命名携带出处：代码注释中引用 issue 编号（如 #824、#146），gate 测试以 roadmap 门命名（如 g004_conformance.rs），与 docs/ 下的 g0XX 验证地图一一对应。
• Python 侧约定：仅用标准库，测试命令为 python -m unittest；src/ 目录同时混用驼峰（如 QueryEngine.py）与蛇形命名文件，这一点在 AGENTS.md 中也被如实记录。

反模式清单：这个仓库里被明确禁止的事

ANTI-PATTERNS 一节是贡献前必读的“负清单”，其中每一条都有仓库内的执行机制佐证：

1. 绝不 cargo install claw-code——crates.io 上的同名 crate 是弃用占位符，安装得到的是 claw-code-deprecated.exe 而非 claw 二进制，只会打印改名提示。必须从源码构建（README.md 的 Quick start 也以同样的警告开头，并指向 cargo install agent-code 作为上游二进制的替代路径）。
2. 禁用文档字符串由 CI 强制：.github/scripts/check_doc_source_of_truth.py 会扫描过期的组织链接（如旧的 github.com/Yeachan-Heo/claw-code、github.com/code-yeongyu/claw-code）、旧 Discord 邀请链接和旧资源文件名（assets/clawd-hero.jpeg）等“来源不实”字符串。
3. 弃用配置键：permissionMode 已迁移为 permissions.defaultMode；enabledPlugins 已迁移为 plugins.enabled；环境变量 RUSTY_CLAUDE_PERMISSION_MODE 已失效。修改配置相关代码时必须使用新键名。
4. 禁止直推 main：main_push_forbidden 审批范围在策略层阻塞对 main 的直接推送，所有变更走 PR 流程。
5. 自动化 lane 不得合并/关闭远端 PR 与 issue：该边界由 docs/anti-slop-triage.md 定义，是 agent 自管理模式下防止“自动化失控”的关键围栏。
6. claw init 不得生成 dontAsk 权限模式：这一回归被 output_format_contract.rs 测试钉死，防止默认输出契约被脚手架悄悄改变。
7. 文件级 #![allow(dead_code)] 是被容忍的遗留（存在于 main.rs、session_control.rs），但明确标注“不要扩大这一模式”——新代码应靠正常引用消除 dead code，而不是加允许标注。

独特风格：dogfood 构建、mock parity 与环境契约

UNIQUE STYLES 一节记录了三个只属于这个仓库的工作流：

• Dogfood 构建：scripts/dogfood-build.sh 在构建时注入 GIT_SHA，且要求 claw version 打印的来源信息必须等于当前 HEAD——即“仓库自己构建出来的二进制必须能自证版本”，这是自举一致性检查。
• Mock parity 机制：rust/mock_parity_scenarios.json 定义场景集，驱动“CLI 子进程 vs MockAnthropicService”的对比测试；mock 服务端通过 lib.rs 中的 SCENARIO_PREFIX（PARITY_SCENARIO:）识别请求所属场景并回放脚本化响应，配套执行入口为 rust/scripts/run_mock_parity_harness.sh 与 rust/scripts/run_mock_parity_diff.py，测试侧则落在 mock_parity_harness.rs。
• 配置隔离：dogfooding 时统一使用 CLAW_CONFIG_HOME=$(mktemp -d) 创建临时配置目录，避免污染真实配置。
• 环境变量契约：GIT_SHA（构建期）、CLAW_CONFIG_HOME（配置目录）、OLLAMA_HOST（本地模型 provider 覆盖）、以及各 provider 的 *_API_KEY / *_BASE_URL，构成了运行 claw 的全部环境面。

标准命令与 CI 现实

COMMANDS 一节给出的标准命令集应原样保留使用：

scripts/fmt.sh --check                 # fmt 检查（scripts/fmt.sh 不带 --check 则为应用）
cd rust && cargo clippy --workspace --all-targets -- -D warnings
cd rust && cargo test --workspace
cd rust && cargo build -p rusty-claude-cli   # 二进制：rust/target/debug/claw
python -m unittest discover -s tests   # Python 测试套件
python .github/scripts/check_doc_source_of_truth.py && scripts/roadmap-check-ids.sh   # docs/roadmap CI

NOTES 一节补充了若干容易被误解的细节，同样是导航本仓库的重要事实：

• claw 二进制来自 crate rusty-claude-cli——包名与二进制名刻意不一致，用 cargo build -p rusty-claude-cli 构建后得到的可执行文件叫 claw（这也是集成测试能用 CARGO_BIN_EXE_claw 的原因）。
• CI 触发是路径过滤的：rust-ci.yml 只在 rust/**、docs/** 及列出的元文件变更时触发。
• CI 的 clippy 任务比文档门槛更弱：CI 上不挂 -D warnings，已知既有失败被记录在 g002/g003 验证地图中；文档中声明的严格门是上面命令行里的 -D warnings 版本。
• claw acp 是状态存根而非真实 ACP 服务（README.md 亦确认其仅返回状态并以退出码 0 结束，公开 JSON 契约见 docs/g011-acp-json-rpc-status-contract.md）。
• rust/ 下提交的 harness 点目录（.clawd-agents/、.omc/、.sandbox-home/）是有意保留的 agent 运行痕迹，不要当作垃圾清理。

结语

AGENTS.md 的价值在于把“如何在这个仓库里工作”压缩成了可执行的表格与清单：WHERE TO LOOK 解决“去哪找”，CODE MAP 解决“改谁会影响谁”，CONVENTIONS 与 ANTI-PATTERNS 解决“哪些做法在这个仓库里是错的”，COMMANDS 与 NOTES 解决“怎么验证”。它本身就是“agent-managed exhibit”理念的一次落地——一份机器与人共用的项目知识快照。如果你准备在 Claw Code 中定位代码、补充测试或提交变更，按本文表格中的文件路径与行号逐一核对后再动手，是成本最低的路径。