claw-code 源码详细分析：子系统目录地图——几十个顶层包如何用五条轴（会话 / 工具 / 扩展 / 入口 / 桥接）读懂？

范围src/下顶层包含*/__init__.py的目录与与会话/runtime 强相关的根模块与result/01_start.md第十三节、「清单—路由—会话」叙事一致。1. 为什么用五条轴src/里同时存在大量占位包读reference_data/subsystems/*.json暴露MODULE_COUNT/SAMPLE_FILES已实现的 CLI / runtime 切片main.py、runtime.py、query_engine.py等横切类型与快照schemas、types、reference_data。若按字母表扫目录容易迷失在名字里。五条轴对应 Harness 里五条常驻问题轴核心问题典型关键词会话状态放哪、如何累计、如何落盘与回放turn、session、transcript、context、budget、denial工具命令/工具清单、路由、shim 执行边界PORTED_*、route、registry、pool、permission 过滤扩展第三方与生命周期往哪挂plugin、hook、skill入口用户/脚本从哪进、启动与交互形态CLI、entry、bootstrap、setup、UI 形态桥接与外部世界宿主、网络、代理、双栈怎么接bridge、remote、proxy、server、coordinator读法先判断「我关心哪条轴」只打开该轴下的包与根文件需要parity 对照时再点进reference_data/subsystems/同名.json。2. 轴一会话Session / Turn关心对象一轮对话的状态机、转写、持久化、用量、权限在 turn 上的投影。位置角色读懂时心里的一句话state/占位包归档里与会话/状态机相关的子树入口元数据见subsystems/state.json。query_engine.pyQueryEnginePortsubmit_message、预算/轮次闸门、与TranscriptStore同步。session_store.py磁盘 JSON 会话StoredSession、save_session/load_session。transcript.py进程内转写条目标记与截断窗口。context.py工作区上下文PortContext、归档是否在盘、文件计数。history.pybootstrap_session里逐步追加的HistoryLogMarkdown 友好。runtime.pyPortRuntime路由 → registry →QueryEnginePort→persist_session的编排核。permissions.py工具池过滤用的ToolPermissionContext与会话里的PermissionDenial配合见result/05.md。cost_tracker.py/costHook.py成本计量与钩子占位偏企业会话对账。tasks.py/task.py任务/规划结构与会话多步推理相邻。不迷路口诀凡是TurnResult、mutable_messages、.port_sessions都从这一轴进。轴二工具Commands / Tools / Executable Surface关心对象镜像清单、如何把 prompt 映射到名字、shim 执行尚非真 I/O。位置角色commands.pycommands_snapshot.json→PORTED_COMMANDS、execute_command、get_command。tools.pytools_snapshot.json→PORTED_TOOLS、execute_tool、get_tools含 MCP/simple/权限过滤。execution_registry.pyMirroredCommand/MirroredTool按名转调execute_*。tool_pool.py策略下的工具子集报告assemble_tool_pool。command_graph.py命令按source_hint分 builtin / plugin-like / skill-like。parity_audit.py清单条目数与archive_surface_snapshot分母对比见result/10.md。services/占位包归档中与「服务层/平台能力」相关子树常与工具背后真实能力对接。utils/占位包体量大MODULE_COUNT常上百多为各子系统与工具共用的杂项能力在归档中的投影读时当作基建库不要期望单文件读完。不迷路口诀凡是PORTED_*、route_prompt、exec-command/exec-tool都从这一轴进。轴三扩展Plugins / Hooks / Skills关心对象可插拔谁在生命周期里挂钩、插件包长什么样、技能如何发现。位置角色plugins/插件模型与捆绑插件在归档中的入口。hooks/生命周期钩子流水线占位。skills/可发现技能面占位。components/常作为UI/组件扩展与宿主渲染相关与「扩展面」相邻也可能与入口轴交叉。不迷路口诀凡是/plugin、hook、skill命令行或协议设计优先在这一轴找目录名与subsystems/*.json规模。轴四入口Bootstrap / CLI / UX Surface关心对象从哪启动、预取与信任、多种交互形态。位置角色cli/命令行入口面占位与根main.py形成「已实现 vs 归档镜像」对照。entrypoints/多入口形态脚本、IDE、服务的统一出口叙事。bootstrap/启动/引导子系统占位与bootstrap_graph.py、run_setup()叙事一致。main.py当前 Python CLI 真入口argparse子命令全集。setup.py/system_init.py/prefetch.py/deferred_init.py启动报告、预取、延迟初始化bootstrap_session会调用run_setup。direct_modes.py/remote_runtime.py/replLauncher.py/dialogLaunchers.py直连、远程、REPL、对话框等模式化入口多与桥接轴配合。screens/终端/界面屏相关占位。vim/编辑器Vim适配占位。keybindings/快捷键占位。outputStyles/输出风格占位。voice/语音交互占位。不迷路口诀凡是python3 -m src.main、SetupReport、slash 形态从这一轴进。轴五桥接Bridge / Remote / Host / Server关心对象宿主与代理隔离、网络/代理路径、常驻服务、多通道协调、TS/Python 过渡。位置角色bridge/宿主环境 ↔ runtime 的桥IPC/协议/编辑器与result/01_start.md中「bridge」叙述一致。remote/远程控制相关子树配合main的remote-mode/ssh-mode/teleport-mode等模拟。upstreamproxy/上游代理相关占位。coordinator/多任务/多通道协调占位。server/HTTP/SSE 等常驻服务端骨架与 Rustservercrate 可对照。native_ts/与原生 TypeScript 资产或互操作相关的过渡占位。migrations/迁移脚本/版本过渡占位。buddy//memdir//moreright/产品语义功能岛保留目录名利于parity 与子系统 JSON 一一对照读时先查subsystems/name.json的sample_files再决定深入优先级。不迷路口诀凡是「数据从哪来、包发往哪、是否过代理」从这一轴进。3. 横向地基不属于单轴尽头这些目录支撑所有轴读子系统前先建立「类型与数据从哪来」的认知位置角色schemas/数据结构/schema 占位。types/类型定义占位。constants/常量占位。reference_data/对照底稿commands_snapshot、tools_snapshot、archive_surface、subsystems/*.json见result/11.md。4. 实操如何用五条轴「落地到文件」python3 -m src.main subsystems --limit 64看port_manifest给出的顶层模块文件数判断当前哪块「长高」了。选定一轴例如先工具轴只读commands.py、tools.py、runtime.route_prompt、execution_registry.py。打开对应reference_data/subsystems/pkg.json看module_count与sample_files评估占位包在归档里的真实体量。再读该包__init__.py几乎都是同一模板ARCHIVE_NAME、MODULE_COUNT、SAMPLE_FILES、PORTING_NOTE确认尚未展开实现。与parity_audit.ARCHIVE_DIR_MAPPINGS对表顶层包名是否在 parity 期望列表里见result/10.md。5. 轴与轴的交界故意重叠处runtime.py横跨工具轴路由、registry与会话轴QueryEnginePort、持久化。permissions.py工具清单过滤工具轴 会话摘要里的拒绝累计会话轴。bootstrap_session入口setup 工具matches 会话engine 桥接叙事history 里可记路径。读代码时允许一个文件挂两条轴地图的作用是决定从哪条叙事进门。6. 小结几十个顶层包多数是parity 占位 JSON 元数据真逻辑目前集中在根模块main、runtime、query_engine、commands/tools 等。用会话 / 工具 / 扩展 / 入口 / 桥接五条轴过滤阅读范围再配合reference_data/subsystems与subsystemsCLI可以把「目录海啸」变成可计划的深入顺序。schemas/types/constants/reference_data作横向地基不强行塞进单轴避免扭曲理解。