范围 ：
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 等常驻服务端骨架；与 Rust server crate 可对照。 |
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作 横向地基，不强行塞进单轴，避免扭曲理解。