claw-code 源码详细分析：Bootstrap Graph——启动阶段图式化之后，排障与扩展为什么会变简单？

涉及源码src/bootstrap_graph.py、src/setup.py、src/system_init.py、src/runtime.py、src/main.py、tests/test_porting_workspace.py。1. Bootstrap Graph 是什么一份“运行时故事”的最小公共语言bootstrap_graph.py给出一个非常短的阶段列表字符串元组并提供as_markdown()输出# 16:26:src/bootstrap_graph.pydefbuild_bootstrap_graph()-BootstrapGraph:returnBootstrapGraph(stages(top-level prefetch side effects,warning handler and environment guards,CLI parser and pre-action trust gate,setup() commands/agents parallel load,deferred init after trust,mode routing: local / remote / ssh / teleport / direct-connect / deep-link,query engine submit loop,))它不是“精确调用栈”而是把启动过程压缩成可讨论的阶段节点任何人在排障或扩展时都可以先回答“我现在卡在哪个阶段”。这会把讨论从“你那边怎么跑的”变成“我们在deferred init after trust之前就挂了”。2. 为什么图式化会让排障简单把故障面切成可观测的段在 claw-code 的 Python 端几条子命令本身就是“阶段探针”bootstrap-graph只输出阶段图最小故事。setup-report只跑 setup/预取/延迟初始化启动中段的可观测切片。bootstrap跑“从 context setup route shim query persist”的一轮全链路报告。remote-mode/ssh-mode/…跑“mode routing”族的模拟分支探针见result/13.md。这样排障时你不需要一次性复现“整套系统”而是可以按阶段逐段缩小范围只看阶段图是否对齐bootstrap-graph只看 setup 是否健康setup-report预取与 deferred init 的输出再看全链路是否能跑通bootstrap输出路由、shim、turn、落盘这也是为什么“阶段图”本身虽然短但很值钱它让你能把 CLI 报告组织成分段可运行的诊断面板。3. 阶段图如何与实际实现互相印证不是空口3.1 “setup() commands/agents parallel load” 在代码里的对应物setup.py的WorkspaceSetup.startup_steps()明确列出加载命令/工具快照、准备 parity hooks、信任门后的 deferred init# 19:27:src/setup.pydefstartup_steps(self)-tuple[str,...]:return(start top-level prefetch side effects,build workspace context,load mirrored command snapshot,load mirrored tool snapshot,prepare parity audit hooks,apply trust-gated deferred init,)system_init.py把这些 steps 打进# System Init报告里并同时打印已加载的 command/tool 数量# 8:23:src/system_init.pydefbuild_system_init_message(trusted:boolTrue)-str:setuprun_setup(trustedtrusted)commandsget_commands()toolsget_tools()lines[# System Init,,fTrusted:{setup.trusted},fBuilt-in command names:{len(built_in_command_names())},fLoaded command entries:{len(commands)},fLoaded tool entries:{len(tools)},,Startup steps:,*(f-{step}forstepinsetup.setup.startup_steps()),]这意味着当你怀疑“清单没加载 / 环境不对 / deferred init 未触发”不必看日志大海直接看System Init段落即可。3.2 “query engine submit loop” 的最小可复现bootstrap_session把 route、shim、QueryEnginePort的stream_submit_message/submit_message、persist_session串成一份 Markdown# 109:152:src/runtime.pydefbootstrap_session(self,prompt:str,limit:int5)-RuntimeSession:contextbuild_port_context()setup_reportrun_setup(trustedTrue)...matchesself.route_prompt(prompt,limitlimit)...stream_eventstuple(engine.stream_submit_message(...))turn_resultengine.submit_message(...)persisted_session_pathengine.persist_session()...排障时你只要跑python3 -m src.main bootstrap prompt就能看到路由命中了哪些条目Routed Matchesshim 说“会怎么执行”Command/Tool Execution流式事件顺序与 stop_reasonStream Events会话是否落盘Persisted session path阶段图让人知道该从哪一节看起例如怀疑“路由不对”就停在 Routed Matches怀疑“引擎没写入”就看 Stream Events / Turn Result。4. 为什么图式化会让扩展简单新增能力先决定“插在哪一段”扩展新能力时最容易混乱的是你不知道该把逻辑挂在启动哪一层导致初始化散落在各处难以复现、难以测试安全/信任门绕过高风险运行时状态不一致某入口有另一入口没有阶段图提供了一种强制对齐的决策框架新增预取例如读取某配置、扫描仓库索引→ 挂在top-level prefetch side effects或setup()里并在setup-report暴露。新增安全检查环境变量、系统保护→ 对应warning handler and environment guards/pre-action trust gate。新增插件/技能加载→ 对应deferred init after trust把“不可信时不执行”的语义写死。新增连接模式例如新的 remote transport→ 对应mode routing: ...先做*-mode探针再注入 bootstrap。新增会话行为压缩、结构化输出、审计事件→ 对应query engine submit loop优先保持TurnResult/ stream event 形状稳定。也就是说扩展不是“把代码塞进去就行”而是先选阶段节点再写实现。这会天然把 PR 讨论聚焦到“你为什么把它放在 deferred init 而不是 setup”。5. 工程化配套阶段图 测试门禁bootstrap-graph有专门 CLI且测试只断言标题存在确保“文档节点”长期不丢# 239:244:tests/test_porting_workspace.pygraph_resultsubprocess.run([sys.executable,-m,src.main,bootstrap-graph],checkTrue,capture_outputTrue,textTrue)...self.assertIn(Bootstrap Graph,graph_result.stdout)同理setup-report、bootstrap、各 mode 的模拟子命令也都有测试门禁形成“阶段探针”体系。阶段图越稳定这套门禁越能持续发挥作用。6. 小结Bootstrap Graph用极短的阶段列表把启动过程变成“可讨论的图节点”给排障与扩展提供最小公共语言。通过setup-report/bootstrap/*-mode等阶段探针式 CLI你可以逐段缩小故障范围而不必复现整套系统。对扩展而言阶段图强迫你先回答“插在哪段”从而减少初始化散落、信任门绕过与入口不一致。