上游仓库在 docs/ 下提供了一份异常完整的文档树。本附录映射每一个顶层 Markdown 文件与子目录——覆盖范围与适合阅读对象——以便你能从本站返回到权威出处。
i18n 约定
每一份范围内的文档都以英文与简体中文维护，构成一对并附带一个翻译索引（唯一例外是 docs/cordis-api/inherited.md，仅有英文）：
<名称>.md—— 英文原文。<名称>.zh.md—— 中文翻译，忠实而非机器直译。<名称>.i18n.yaml—— i18n 配对/路径声明。
配对契约、检查、范围与豁免见 docs/i18n/README.md；如何翻译见 docs/i18n/translation-rules.md；术语权威出处是 docs/i18n/terminology.md。docs/AGENTS.md 是统辖整棵文档树的文档编写标准。
顶层概览与架构
| 仓库路径 | 覆盖内容 | 适合阅读对象 |
|---|---|---|
docs/architecture.md | 动手改动前的必读概览：Cordis、profile/bundle/补丁、核心包、事件、回合流、会话日志、接缝 | 架构概览、能力接缝 |
docs/glossary.md | 规范的一概念一术语领域词表 | 术语表附录 |
docs/cordis-primer.md | 插件作者在读取生成的引用资料前所需的 Cordis 概念 | Cordis 入门 |
docs/rescope.md | vendored @deepseek-ai/cordis* 作用域的名称映射 | 包索引 |
开发
| 仓库路径 | 覆盖内容 | 适合阅读对象 |
|---|---|---|
docs/development.md | 贡献者环境搭建教程，外加仓库布局、日常流程与 CI 组织 | 开发 |
docs/AGENTS.md | 文档编写标准：结构、Markdown 层级、预算 | 页面约定（见 docs/AGENTS.md） |
docs/testing.md | 逐层测试策略与保持测试套件有意义性的规则 | 测试 |
docs/defensive-patterns.md | 实际出现过的缺陷类规则（事件、并发、生命周期、子进程、拆解） | 开发 |
docs/event-producer-consumer.md | 每个事件的生产者与消费者的生成矩阵 | 事件 |
docs/module-graph.md | 生成的包级模块依赖图 | 包索引 |
docs/graph-atlas.md | 全部文档图的生成索引 | 架构概览 |
docs/web-styling.md | 浏览器客户端包的样式归属与组件规则 | Web UI |
目录（生成的参考）
| 仓库路径 | 覆盖内容 | 适合阅读对象 |
|---|---|---|
docs/tool-catalog.md | 每个面向模型工具的生成 schema 目录 | 工具注册表 |
docs/config-catalog.md | 生成的插件配置目录 | 配置 |
docs/persistence-catalog.md | 生成的会话持久化事件目录 | 会话 |
docs/api-gateway.md | Typert API 网关的当前状态参考（Remote 方法、Host/Client 契约） | Host API |
docs/capability-seams.md | 每个能力接缝与核心服务的生成页 | 能力接缝 |
docs/tool-execution-pipeline.md | 工具执行流水线的生成页 | 工具 |
docs/agent-lifecycle.md | 生成的 Agent 回合与步骤生命周期图 | Agent 循环 |
子系统参考（docs/subsystems/）
45 个子系统页——core、session、tools、shell、fs、subprocess、sandbox、llm-streaming、session-projection、session-query、session-telemetry、session-title、settings、credentials、persistence、approval、permission-presets、user-questions、commands、plan、goal、schedule、jobs、workflow、subagent、skills、system-prompt、compaction、spill、storage、lsp、web、web-server、terminal、feedback、extensions、client-modules、typert、invariants、scope 等。每页是针对一个包组的插件领地参考（服务、事件、配置、提供者）。
| 仓库路径 | 覆盖内容 | 适合阅读对象 |
|---|---|---|
docs/subsystems/README.md | 全部子系统参考的索引 | 子系统索引（见 docs/subsystems/README.md） |
docs/subsystems/core.md | Agent、agent-loop、system-prompt 注册表 | Agent 循环 |
docs/subsystems/session.md | 事件溯源的会话存储 | 会话 |
docs/subsystems/scope.md | 作用域注册原语 | 作用域 |
docs/subsystems/goal.md | 同会话目标与目标回合 | 目标 |
docs/subsystems/... | 每个包组一张参考页（见 README 索引） | 按子系统 |
Cordis API 与教程（docs/cordis-api/、docs/cordis-tutorial/）
vendored Cordis 框架 API 面的生成目录（context、events、fiber、registry、service，外加 inherited.md），以及一个 7 课动手教程（第一个插件 → 生命周期与 effect → 服务 → 事件 → 配置 → 组合与 HMR → 进入 harness）。
| 仓库路径 | 覆盖内容 | 适合阅读对象 |
|---|---|---|
docs/cordis-primer.md | 读取生成的引用前所需的概念入门 | Cordis 入门 |
docs/cordis-api/context.md | Cordis Context API | Cordis |
docs/cordis-api/events.md | Cordis 类型化事件 API | 事件 |
docs/cordis-api/service.md | Cordis Service API | Cordis |
docs/cordis-api/fiber.md | Cordis fiber 模型 | Cordis |
docs/cordis-api/registry.md | Cordis registry API | Cordis |
docs/cordis-api/inherited.md | 继承的生成 API 面 | Cordis |
docs/cordis-tutorial/index.md | 七课动手介绍 | Cordis 教程 |
烹饪书（docs/cookbook/）
| 仓库路径 | 覆盖内容 | 适合阅读对象 |
|---|---|---|
docs/cookbook/adding-a-package.md | 如何新增一个工作区包 | 扩展烹饪书（见 docs/cookbook/extension-cookbook.md） |
docs/cookbook/adding-a-tool.md | 工具编写参考 | 工具 |
docs/cookbook/adding-an-llm-adapter.md | 如何新增一个 LLM 适配器 | LLM |
docs/cookbook/adding-a-vendored-package.md | 如何新增一个 vendored 包 | vendored 包 |
docs/cookbook/adding-a-conversation-node.md | 新增一个 Web 客户端会话节点 | Web UI |
docs/cookbook/extension-cookbook.md | 扩展插件形态（功能 → 能力索引） | 扩展烹饪书（见 docs/cookbook/extension-cookbook.md） |
docs/cookbook/maintaining-dsh-code-review.md | 维护 dsh-code-review 技能 | 开发 |
docs/cookbook/responding-to-pr-review-on-a-stack.md | 跨堆叠 PR 链的评审回应 | 开发 |
用户指南（docs/user/）
三个子树：guide/（Web UI 使用、提供者/模型、Python SDK）、develop/（基础插件 → 服务框架 → 三角色实践），以及顶层 index.md（重定向）。
| 仓库路径 | 覆盖内容 | 适合阅读对象 |
|---|---|---|
docs/user/index.md | 重定向到 Web UI 快速上手 | 快速上手 |
docs/user/guide/index.md | 服务器启动后使用 Web UI | Web UI |
docs/user/guide/providers.md | 配置模型与提供者 | 模型 |
docs/user/guide/python-sdk.md | 使用 Python SDK 入门 | SDK |
docs/user/develop/basic/index.md | 第一个插件，并加载进 Web UI | 第一个插件（见 docs/user/develop/basic/） |
docs/user/develop/framework/index.md | Cordis 插件模型与生命周期状态机 | 开发框架（见 docs/user/develop/framework/） |
docs/user/develop/practice/index.md | 三角色能力设计：概念 + 进阶教程 | 能力接缝 |
docs/user/develop/basic/覆盖tool.md、config.md、publish.md；docs/user/develop/framework/覆盖service.md与events.md；实践目录还有一份llm-adapter.md。
事后复盘（docs/postmortem/）
| 仓库路径 | 覆盖内容 | 适合阅读对象 |
|---|---|---|
docs/postmortem/README.md | 事故复盘索引 | 事后复盘（见 docs/postmortem/README.md） |
docs/postmortem/0001-*.md | ACP 默认导出丢掉 inject | 可扩展性 |
docs/postmortem/0002-*.md | JS 表达式禁用文件系统工具 | 文件系统 |
docs/postmortem/0003-*.md | Web 智能体 GUI 反馈回路 | Web UI |
docs/postmortem/0004-*.md | Landlock 部分告示误分类子失败 | 沙箱 |
本修订版本有四个编号复盘（0001…0004）。