5. 源码地图与推荐阅读顺序
推荐顺序不是按目录字母排序，而是按认知依赖和运行链路排序。
第一批：建立项目全景
| 文件 | 阅读目的 | 关键符号或配置 | 读完应能回答 |
|---|---|---|---|
README.md | 知道产品入口、运行方式和 preview 状态 | npx @deepseek-ai/dsh web | 这个项目如何快速启动 |
docs/cordis-primer.md | 理解 Cordis 五思想 | Service、inject、ctx.effect、四种 dispatch | 为什么“一切皆插件”能成立 |
docs/architecture.md | 理解核心包、turn flow、session log、extension points | Core packages、Turn flow、Where new behavior goes | 新功能应该挂在哪里 |
packages/core/README.md | 认识产品 API spine | ctx.sessions/llm/tools/agents/agentLoop | 六个核心服务各负责什么 |
packages/bundle/base/cordis.patch.yml | 看真实默认组合 | llm、session、tools、agent-loop、sandbox rows | 一个最小 Agent 需要哪些插件 |
apps/cli/src/bin.ts | 找到真正入口 | runProfile | CLI 如何进入 profile |
第二批：理解主执行链路
| 文件 | 阅读目的 | 关键符号或行号 | 读完应能回答 |
|---|---|---|---|
packages/core/session/src/types.ts | 理解事件词汇和 format | SessionEventMap、SurfaceEventType、SESSION_FORMAT_VERSION | 哪些事件会进入模型历史 |
packages/core/session/src/index.ts | 理解 append 和派生历史 | Session.append、deriveMessages、requestHeader | 模型上下文如何生成 |
packages/core/session/src/surface.ts | 理解 surface append/replace | deriveEventMessage、SurfaceManager | compaction 如何替换历史 |
packages/core/agent/src/runtime-types.ts | 理解 Agent 接口和事件 | Agent、PreStepDecision、agent/pre-step | UI 如何驱动 Agent |
packages/core/agent-loop/src/agent.ts | 理解 turn/step/stream/tool | ReactLoopAgent、turn()、step() | 一个请求怎样变成模型调用和工具执行 |
packages/core/agent-loop/src/index.ts | 理解创建/恢复/销毁 | AgentLoop、create/resume、setupAndPublish | Agent 生命周期如何管理 |
packages/core/agent-loop/src/tool-calls.ts | 理解工具调度和并发 | executeToolCalls | 工具如何并行或串行 |
packages/core/system-prompt/src/index.ts | 理解 prompt 和 schema 装配 | section/context/tools/variable/assemble | 插件如何给模型加上下文 |
packages/core/tools/src/index.ts | 理解工具注册和管线 | register/restrict/guard/execute | 工具如何被校验和执行 |
packages/llm/llm/src/index.ts | 理解模型流式和 adapter | registerAdapter/prepareCall/stream | 如何接入新模型厂商 |
第三批：理解组合、持久化和前端
| 文件 | 阅读目的 | 关键符号 | 读完应能回答 |
|---|---|---|---|
packages/boot/app-boot/src/profile.ts | 理解 profile/bundle/patch | loadProfile、composeEntries | 配置树如何生成 |
apps/cli/src/profile-boot.ts | 理解 runProfile 和 HMR | runProfile、composeLive | 启动时如何 mount/热更新 |
packages/session/session-persistence/src/index.ts | 理解持久化 seam | SessionPersistence | 如何换 JSONL/SQLite |
packages/session/session-persistence/src/coordinator.ts | 理解 write coordination | append、flush、resume | 会话如何可靠落盘 |
.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md | 理解浏览器插件树和对象层 | React-free object layer、slot system | Web UI 为什么这样设计 |
packages/api/session-controller/src/client/sessions/session.ts | 理解前端 Session 快照 | getSnapshot、subscribe | React 如何订阅流式状态 |
packages/client/ui-renderer/src/client/scoped-slots.tsx | 理解 slot 渲染和 uSES | useSyncExternalStore | slot 如何变成 React 树 |
docs/cookbook/extension-cookbook.md | 理解扩展点地图 | feature -> mechanism | 新功能用哪种扩展机制 |
调试时需要关注的文件
packages/core/agent-loop/src/agent.ts：断点放在turn()、preStep()、step()、buildRequest()、executeToolCalls()附近。packages/core/agent-loop/src/tool-calls.ts：观察工具组并发和结果。packages/core/session/src/index.ts：观察每次append()后seq和surface。packages/core/system-prompt/src/index.ts：观察组装出的 sections/contexts/tools/variables。packages/llm/llm/src/index.ts：观察 adapter selection 和llm/streamwaterfall。
二次开发时最可能修改的文件
- 增加工具：新建
packages/<group>/<pkg>，在src/index.ts调用ctx.tools.register()，并准备 README/tests。 - 增加模型：新建
packages/llm/<adapter>，继承LlmAdapter，调用ctx.llm.registerAdapter()。 - 增加 prompt/context：注册
ctx.systemPrompt.section/context/variable。 - 增加权限：监听
tools/pre-execute或使用ctx.tools.guard()。 - 增加 UI：在 client plugin 的
src/client/index.ts注册 slot。
暂时可以跳过的目录
vendor/：除非要深入 Cordis 本身或修改 vendored 包。website/：文档站点投影，学习架构时不是主链路。python/、native/：涉及 Python SDK 或原生 Landlock，不是理解核心 Agent 的第一优先。docs/subsystems/：可在需要查具体服务类型时再读。- 生成式 catalog：
docs/config-catalog.md、docs/tool-catalog.md等，适合查询不适合通读。