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.py | QueryEnginePort：submit_message、预算/轮次闸门、与TranscriptStore同步。 |
session_store.py | 磁盘 JSON 会话：StoredSession、save_session/load_session。 |
transcript.py | 进程内转写条目标记与截断窗口。 |
context.py | 工作区上下文：PortContext、归档是否在盘、文件计数。 |
history.py | bootstrap_session里逐步追加的HistoryLog（Markdown 友好）。 |
runtime.py | PortRuntime：路由 → 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.py | commands_snapshot.json→PORTED_COMMANDS、execute_command、get_command。 |
tools.py | tools_snapshot.json→PORTED_TOOLS、execute_tool、get_tools（含 MCP/simple/权限过滤）。 |
execution_registry.py | MirroredCommand/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作横向地基，不强行塞进单轴，避免扭曲理解。