| 目录 | 是什么 | 通俗理解 |
|---|---|---|
packages/ | 全部插件包（几十个），按组分类 | 主车间——产品本体 |
docs/ | 架构文档、教程、参考手册 | 产品百科全书（课程结论出处） |
vendor/ | 内嵌的 Cordis 等框架源码 | 买来拆下放家里的发动机（可自行维修） |
examples/ | 可运行的组合样例 | 样板间——看别人怎么组装 |
python/ | Python SDK 与捆绑运行时 | 给 Python 程序员开的侧门 |
native/ | 原生扩展（Landlock 沙箱的 C++ 部分） | 贴近操作系统的特种零件 |
scripts/ | 仓库质检脚本（CI 门禁） | 工厂质检流水线 |
.agents/ | 智能体工作流 + Agent Notes | 工程施工日志：决策为什么这么做 |
website/ | 文档网站源码 | 百科全书的在线版 |
apps/ | 启动器（CLI 与 Web 入口） | 车钥匙和点火按钮 |
几十个包不用背，认识这几组就够（每组目录下有 README）：
| 组 | 角色 | 代表成员与通俗理解 |
|---|---|---|
core/ | 产品脊柱 | session（会话日志）、tools（工具注册表）、agent + agent-loop（智能体与驱动循环）、system-prompt——房子的承重墙 |
llm/ | 模型能力 | llm（适配器接口）+ llm-deepseek / llm-pi-ai（具体实现）——换模型就换这里 |
shell/ fs/ web/ terminal/ lsp/ | 执行能力 | 跑命令、读写文件、搜网页、持久终端、语言服务器——智能体的手脚 |
subagent/ workflow/ jobs/ | 编排能力 | 子智能体、工作流、后台任务——智能体的分身术 |
session/ | 持久化 | JSONL / SQLite 后端——对话的账本 |
interaction/ | 人机协作 | 审批、权限、命令、ask-user——智能体的请示机制 |
bundle/ | 发行组合 | dsh-base（所有 profile 的第一层）、web-app、headless——整车配置单 |
boot/ | 启动胶水 | 把插件树组装起来的引导程序 |
sdk/ acp/ | 对外接口 | JSON-RPC SDK、ACP 自动化协议——给外部程序开的驾驶接口 |
skill/ preset/ guard/ plan/ todo/ | 行为增强 | 技能系统、会话级组合、循环卫生、计划模式、任务清单 |
extensions/ | 自我修改 | 运行时检查/挂载/卸载自己的插件（L19 演示大招） |
| 你想干什么 | 去哪查 |
|---|---|
| 理解整体架构（改代码前必读） | docs/architecture.md |
| 学插件框架基础概念 | docs/cordis-primer.md + docs/cordis-tutorial/（7 章教程） |
| 动手做某件具体事（加工具/加包…） | docs/cookbook/（菜谱式步骤） |
| 用户视角用产品 | docs/user/（指南 + 开发入门） |
| 查某个子系统的类型与 API | docs/subsystems/（一子系统一页） |
| 查所有工具 / 配置项清单 | docs/tool-catalog.md / docs/config-catalog.md（源码生成） |
| 查术语定义 | docs/glossary.md |
| 了解某个决策的来龙去脉 | .agents/notes/（Agent Notes） |
| 事故复盘 | docs/postmortem/ |
xxx.md（英文）和 xxx.zh.md（中文）两版，内容对应，直接读 .zh.md 即可。# 在仓库根目录依次执行
pnpm install # ① 买齐所有食材（首次较慢）
pnpm run build # ② 把所有 TS 编译成可运行的 lib/ 产物
pnpm dsh web # ③ 用产物启动 Web UI成功后终端打印地址，浏览器打开 http://127.0.0.1:3080。此时是"还没配钥匙的车"——界面有了，模型还不能用，L08 讲怎么配。
L10 完整拆解这个组装过程，现在记住：运行中的 dsh = 一棵按配置组装出来的插件树。
packages/core/tools/README.md 一遍（混个脸熟）。docs/architecture.zh.md，只看"Where new behavior goes"表，数数有多少种扩展方式（约 20 行）。