本专题共 100 篇。内容依据 官方仓库 的 README、docs/ 下的架构与子系统文档、以及 packages/ 下的源码整理。 文中出现的阈值与默认值均为源码中的默认配置， 不构成对实际运行结果的保证；star 数与 issue 数带 2026-08-16 时间锚点， 且不能由它们推导质量结论。

认识与工程门槛

README 只给了一句「Install Node.js」，而 Node 版本门槛其实只钉在那个 private 的根包上——我们扫过的 230 份 manifest 没有一份带 engines。这一组还包括两条运行路径各自的前置条件、一份笔记标着 implemented 而代码直接报错的 --host 0.0.0.0，以及一个仓库为什么要七份 vitest 配置。

Cordis 内核与「一切皆插件」

这句宣传语的技术底座是被内联进仓的 Cordis。这一组从最小插件、服务注册、事件派发一路读到 scope 继承，中间会撞上几处口径差：入门文档列四种派发模式而源码是五种，术语表说 scope 扁平不继承而源码实现了带环检测的父子链，vendor/ 里九个包的版本号跟自家 manifest 表全对不上。

架构与包体系：数字最容易在这里翻车

packages/ 下用 ls 数出 49 个目录，但工作区 glob 是两层，真实 npm 包有 219 个——写「49 个包」就错了。这一组还包括 219 个包统一的版本口径、AGENTS.md 里那两个不存在的目录、能力接缝图里四个找不到对应包的名字，以及同一个 core 被三份文档分别说成 6、7、8 个子包。

会话、上下文与压缩

一次会话从事件到投影再到落盘经过哪几层，上下文放不下时往哪溢出。这一组的四篇都落在可核对的常量上：文档写三种压缩事件而源码声明了四个，token 计量的第三种 baseline 文档没提，四个都叫 version 的数字分属四套 schema，还有一个已经从源码里消失、却还留在文档与生成脚本里的 TurnTrigger。

工具体系、执行管线与权限审批

一次工具调用从 pre-execute 到落盘经过哪些阶段，审批为什么发生在 monotonic guards 之前。这一组还包括权限预设在源码默认表与出厂组合之间的档数差、README 与源码三处不一样的命名、bash 工具在限制型执行器下多出来的两个参数，以及一个我们没能在仓库里找到的东西——默认对普通工具发起 ask 的策略插件。

LLM 适配、流式与重试

模型接入这层被切成 adapter、provider 与手写路由。要注意的是供应商清单根本不在仓库里，唯一可读的证据是 Web golden 快照里的下拉选项。这一组把重试退避、抖动与流式空闲超时的默认值逐个落到常量行上，并说明为什么这套适配层的测试行数会比源码还多。

运行时与隔离：仓库自己说「这不是安全边界」

这一组是全专题最需要冷静读的一块。仓库在三处明写隔离不是安全边界；沙箱 schema 默认 read-only 而示例组合设的是 workspace-write；run_code 的 worker.terminate() 只结束线程、它 spawn 出去的进程会活下来；负责 glob/grep 的那个包 README 自称「the unconfined spawn」。

扩展、编排与调度

写一个扩展并发布出去要遵守什么约定，skill 是什么格式，subagent 的六个 provider 里为什么只有两个能续接。这一组还包括 cookbook 写着 cron 表达式而协议里根本没有 cron、一个 README 说五个工具而源码注册七个的包，以及同一个轮次上限在包默认值与出厂组合里的两个数。

子系统逐个读 · 会话、存储与设置

一次对话在磁盘上到底留下哪些东西，事件流怎么变成你看见的那个界面，历史会话怎么被翻出来，会话标题是谁起的，遥测记了什么。这一组把 storage、persistence、session-projection、session-query、telemetry、session-title、settings、workspace 八个包逐个读了一遍。

子系统逐个读 · 执行、任务与不变式

一条 bash 命令从下发到回显走了哪几层，子进程的起管杀分别归谁，模型写的代码在哪儿跑，跑很久的活由谁托着。这一组还包括计划模式那条「不许动手」的线、goal 与计划模式的关系，以及一份写死在源码里的运行时不变式清单——那是他们把踩过的坑变成了断言。

子系统逐个读 · 交互、凭据与提示词

审批弹窗是谁发起谁应答、拒绝之后会怎样，AskUserQuestion 这条反问用户的路怎么铺，斜杠命令从注册到执行的一条线，模型跑着的时候你插一句话会发生什么。这一组还包括 API Key 存在哪、一张图怎么落盘、系统提示词是按什么顺序拼出来的。

子系统逐个读 · 网络、流式与语言服务

dsh web 起来之后都开了哪些口，一个 token 到屏幕上要经过几层，接进来的 LSP 给 Agent 带来了什么又限制了什么，以及他们为什么要自己写一套叫 Typert 的远程调用。

架构总纲：几张自动生成的全局表

host、client、runtime 三段是怎么切的，哪个包被依赖得最狠、哪个是叶子，所有能配的项在哪张表里，往磁盘写了多少种东西，一次工具调用从模型出参到结果回填的完整管线。最后一篇是他们把踩过的坑写成的编码约定。

动手改它：官方 cookbook 逐篇拆

给它加一个工具、加一个 workspace 包、接一个新模型、塞一个 vendored 包、给 Web 端加一个会话节点，各自要动哪些文件、遵守哪些约定。这一组还包括他们自己那个代码评审 skill 怎么维护，以及团队在堆叠 PR 上怎么回应评审意见。

事故复盘：四份真实案卷

一个 default export 让依赖注入静默失效、一个 JS 表达式把文件系统工具全禁掉、Web Agent 自己跟自己形成反馈闭环、Landlock 的部分强制执行被误判成子进程失败。四份复盘加一篇讲他们把哪些事写成案卷、案卷该怎么写——这是全专题最能看出工程习惯的一块。

横向对照：Claude Code、Codex 与 Pi

同一件事各家怎么做：skill 的装法与触发、权限预设与审批时机、沙箱走 Landlock 还是 bwrap 还是容器、上下文压缩会让你丢失什么、子代理的派生与回收、扩展机制、AGENTS.md 与 CLAUDE.md 的读法、想换个模型供应商各要改哪一层。只对照双方都白纸黑字写明的机制，一方查不到就明说不比；Claude Code 闭源，只用官方文档、不推断实现。三家不排名。