claw-code runtime 核心 crate 深度解析：模块地图、四大不变量与工程约定

claw-code runtime 核心 crate 深度解析模块地图、四大不变量与工程约定【免费下载链接】claw-codeAn agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.项目地址: https://gitcode.com/gh_mirrors/claudeco/claw-codeclawclaw-code 项目的核心 crateruntime承载了会话持久化、权限控制、提示词组装、MCP 管道、工具侧文件操作和对话循环等全部核心职责。它以 47 个扁平模块约 330 个pub符号其中约 170 个从lib.rs平铺再导出构成整个 CLI 的执行底座。读完本文你将掌握该 crate 的完整模块导航地图、四条不可破坏的不变量invariants、严格的依赖与命名约定以及每条约束背后对应的源码证据与回归测试从而安全地在其中定位代码、阅读实现并遵循规范进行维护。1. crate 定位它负责什么runtime 位于 rust/crates/runtime 目录是claw工作区 11 个 crate 中唯一的“核心库”rusty-claude-cli (bin claw) → tools / commands / runtime / api / plugins claw-analog → api runtime即会话、权限、MCP 和对话循环的全部状态机都在 runtime 里而 CLI 二进制只负责呈现。其依赖声明见 Cargo.toml——这是理解其工程风格的关键一页[dependencies] sha2 0.10 glob 0.3 plugins { path ../plugins } regex 1 serde { version 1, features [derive] } serde_json.workspace true telemetry { path ../telemetry } tokio { version 1, features [io-std, io-util, macros, process, rt, rt-multi-thread, time] } walkdir 2 [dev-dependencies] tempfile 3依赖清单刻意保持最小只有 serde、tokio、glob、regex、sha2、walkdir 加上内部plugins/telemetry两个 crate。没有 reqwest没有 async-trait——远程调用与 SSE 解析由remote.rs和sse.rs手工实现。这意味着阅读网络相关代码时不用追踪第三方 HTTP 栈SSE 帧解析逻辑就在 rust/crates/runtime/src/sse.rs 内部。2. 模块导航地图47 个文件按职能分组源码全部平铺在src/下无子目录文档给出的分组地图如下已对照实际文件与行数核实职能分组文件关键入口会话/对话session.rs,session_control.rs,conversation.rs,compact.rs,summary_compression.rs,usage.rsSession、SessionStore、ConversationRuntime、ApiClient/ToolExecutortrait配置config.rs,config_validate.rs,bootstrap.rsConfigLoaderMCP 服务器配置枚举也在此定义MCP6 文件拆分mcp.rs,mcp_client.rs,mcp_stdio.rs,mcp_server.rs,mcp_tool_bridge.rs,mcp_lifecycle_hardened.rsMcpServerManagermcp_stdio.rsJSON-RPC 进程启动钩子/插件hooks.rs,plugin_lifecycle.rsHookRunnerhooks.rs、中止信号、健康检查、降级模式权限/安全permissions.rs,permission_enforcer.rs,policy_engine.rs,approval_tokens.rs,sandbox.rs,bash_validation.rs,trust_resolver.rsPermissionEnforcerpermission_enforcer.rs、GreenLevel、lane 决策工具/执行bash.rs,file_ops.rs,lsp_client.rsexecute_bash、*_in_workspace系列文件操作通道/工作者lane_events.rs,worker_boot.rs,task_packet.rs,task_registry.rs,team_cron_registry.rs,branch_lock.rs,stale_base.rs,stale_branch.rsLaneEvent去重/溯源、LaneBoard提示词prompt.rsSystemPromptBuilder、ContextFile、动态边界标记git/远程/认证git_context.rs,remote.rs,oauth.rs上游代理、PKCE 流程杂项json.rs,sse.rs,g004_conformance.rs,green_contract.rs,recovery_recipes.rs,report_schema.rs,trident.rsReport v1 与脱敏redaction行数最大的文件为config.rs3894 行、mcp_stdio.rs2969 行、lane_events.rs2561 行、worker_boot.rs2441 行、session.rs1961 行、conversation.rs1878 行——与实际wc -l结果完全一致。几个值得展开的入口点Session与ConversationRuntime。session.rs 中的Session结构体携带session_id、messages: VecConversationMessage、compaction: OptionSessionCompaction、fork: OptionSessionFork以及workspace_root: OptionPathBuf等字段。源码注释解释了workspace_root的必要性全局会话存储跨所有服务实例共享没有显式 workspace 绑定时并行 lane 可能竞态并报告“假成功”。conversation.rs 的ConversationRuntimeC, T则以泛型同时约束C: ApiClientconversation.rs 定义和T: ToolExecutor#L62协调模型循环、工具执行、钩子和会话更新并内置max_iterations、usage_tracker、auto_compaction_input_tokens_threshold与hook_abort_signal字段。ConfigLoader。config.rs 中定义为“发现配置文件并合并为RuntimeConfig的加载器”字段为cwd: PathBuf与config_home: PathBuf。3894 行的 config.rs 是全 crate 类型导出最重的文件MCP 服务器配置的枚举类型同样定义在这里——改配置项时先来这里找类型定义。McpServerManager。mcp_stdio.rs 中的管理器持有servers: BTreeMapString, ManagedMcpServer、unsupported_servers、tool_index: BTreeMapString, ToolRoute与next_request_id并提供了from_runtime_config与from_servers两个构造入口。MCP 被拆成 6 个文件协议、客户端、stdio 启动、服务器、工具桥、生命周期加固正是为了把最大的单文件复杂度摊开。3. 约定CONVENTIONS扁平布局与测试纪律文档列出六条约定逐条对照源码均成立一个文件一个模块扁平布局无子目录。src/下恰好 47 个.rs文件没有子目录。多数模块是私有mod x 选择性pub use。lib.rs 中有 22 个pub modbash_validation、branch_lock、config_validate、g004_conformance、green_contract、lsp_client、mcp_lifecycle_hardened、mcp_server、mcp_tool_bridge、permission_enforcer、plugin_lifecycle、recovery_recipes、sandbox、session_control、trident、stale_base、stale_branch、summary_compression、task_packet、task_registry、team_cron_registry、worker_boot其余模块只通过再导出暴露。消费方因此既可以用再导出路径也可以用限定路径。依赖最小化见第 1 节无 reqwest / async-trait。每个文件内联#[cfg(test)]测试其中 session.rs 含两个测试模块。test_env_lock()。lib.rs 提供了一个pub(crate)的静态互斥锁OnceLockMutex()用于串行化所有修改环境变量的测试——凡触碰 env 的测试必须持有该锁。trust_resolver.rs是“测试门控的公开 API”。整个实现位于#[cfg(test)]门控下却以 pub 符号被使用属于仅供测试的 API 表面阅读时不要把它当作运行时逻辑的一部分。4. 四大不变量绝不能破坏的约束文档的 INVARIANTS 一节列出了四条硬约束每条都有对应的源码位置与回归测试4.1 压缩不得拆散工具调用对compact.rs在任何情况下都不得在 assistant 消息的ToolUse块与对应的ToolResult之间下刀。compact.rs 的注释明确说明了边界判定若某条消息是ToolResult则其前一条必须是指派assistant且携带匹配ToolUse的助手消息否则视为孤儿。回归测试compaction_does_not_split_tool_use_tool_result_paircompact.rs正是为此而写断言压缩结果中不存在“有 ToolResult 却没有前序 ToolUse”的消息。4.2 构造无副作用SessionStore的构造不得创建.claw目录。session_control.rs 的测试session_store_from_cwd_is_side_effect_free_until_save直接验证了这一点SessionStore::from_cwd(workspace)之后workspace 下不得出现.clawsessions_dir()必须懒创建直到第一次 save 才落盘。4.3 工作区包含性file_ops.rs的 workspace 文件操作不得逃逸出 workspace 根目录。源码中提供了成对的受检/非受检实现read_file_in_workspace、write_file_in_workspace、edit_file_in_workspace、glob_search_in_workspace、grep_search_in_workspace见 file_ops.rs 一带。约定同时规定在 workspace 上下文中不得绕过*_in_workspace变体去调未受检版本——未受检版本仅为 bootstrap 与 workspace 外场景保留。4.4 权限判定的顺序陷阱前导只读权限令牌不得为尾随的破坏性命令“洗白”。permission_enforcer.rs 附近的硬编码回归测试read_only_rejects_command_rejects_command_chaining覆盖了典型攻击面assert!(!is_read_only_command(cat foo; rm -rf bar)); assert!(!is_read_only_command(cat foo rm -rf bar)); assert!(!is_read_only_command(ls || rm bar)); assert!(!is_read_only_command(cat foo | sh)); assert!(!is_read_only_command(echo rm bar)); assert!(!is_read_only_command(echo $(rm bar)));判定函数is_read_only_commandpermission_enforcer.rs还额外拒绝了解释器与构建驱动如python3 -c ...因为这类命令可执行任意代码不再算只读。PermissionEnforcer::check本身在 Prompt 模式下会把决策交给调用方的交互询问流程enforcer 自身没有 prompter。5. 反模式清单什么是不被允许的文档 ANTI-PATTERNS 一节给出的五条禁令全部可用源码现状验证不要扩展整文件#![allow(...)]块。以下 8 个文件第 1 行就带有遗留容忍块worker_boot.rs、mcp_tool_bridge.rs、lsp_client.rsclippy::should_implement_trait, clippy::must_use_candidate、stale_branch.rs、stale_base.rs、recovery_recipes.rscast_possible_truncation, uninlined_format_args、mcp_lifecycle_hardened.rs、session_control.rsdead_code。这是遗留容忍新增不可接受。不得添加 reqwest 或 async-trait 依赖。远程调用必须走remote.rs与sse.rs的手工 SSE/代理层。不得在src/下创建子目录。扁平模块布局是有意为之。不得在 workspace 上下文中绕过*_in_workspace文件操作变体见 4.3。不得无理由地新增pub mod导出。优先“私有 mod 从 lib.rs 选择性pub use”。6. 阅读与维护建议结合上述结构进入这个 crate 的推荐路径是先读 lib.rs 的再导出表确认目标符号走的是限定路径还是再导出再按第 2 节的分组地图定位文件行数最大的六个文件config / mcp_stdio / lane_events / worker_boot / session / conversation是主战场建议带着具体类型名如RuntimeConfig、McpServerManager、LaneEvent进入动手前先找到对应的内联#[cfg(test)]测试——每个文件自带测试模块第 4 节的四条不变量均有回归测试锚点涉及环境变量的改动记得test_env_lock()提交前遵循工作区级检查。按 rust/AGENTS.md 的规定从rust/目录执行# 格式化检查不要直接在仓库根跑 cargo fmt ../scripts/fmt.sh --check # 严格 lint比 CI 门禁更严 cargo clippy --workspace --all-targets -- -D warnings # 全量测试 cargo test --workspace工作区另有硬性 lintunsafe_code forbid不是deny无法#[allow]以及“格式化函数只接受mut impl Write、绝不直写 stdout”的 TUI 规则该规则约束 TUI 层但维护共享代码时同样适用。7. 小结runtimecrate 是一份“约束先于代码”的工程范本47 个扁平模块、最小依赖、内联测试、四条带回归测试的不变量以及一份明确到“哪个文件第 1 行有遗留 allow 块”的反模式清单。它的全部设计意图都写在 rust/crates/runtime/AGENTS.md 里并与 Cargo.toml、lib.rs 及各模块源码一一对应。理解并遵守这套地图与约束是安全修改该 crate 的前提。【免费下载链接】claw-codeAn agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.项目地址: https://gitcode.com/gh_mirrors/claudeco/claw-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考