这本书按你依次会产生的问题排，不按代码目录排。

七个部分，三十八章。每一部只回答一个问题，答完就把你交给下一部。你不必从头读到尾，但顺序是有理由的。

时间只够读两部，就读第一部和第七部：一头告诉你它是什么，一头告诉你要不要碰。

任何一个 harness，都在干同样的五件事。

模型只会文字进、文字出：读不了文件，按不下回车，也记不住上一轮。把这三样接上、让循环转起来的那层程序，就是 harness。

它不跟谁比更好用，它把 harness 本身做成了零件。

判断一个东西是不是真插件化，只有一条标准：产品自带的功能，本身是不是也是一行普通配置。

能被一个 id 定位、能被一行 disabled: true 关掉、能被别的包顶替——三条都满足才叫零件；否则「插件」只是厂商在固定内核旁边留给你的几个挂钩。

dsh 满足。每个组合的根配置文件，字面上就是一个空数组，整个产品是打在这个空数组上的若干层补丁：

官方自己在走「关掉自带功能」这条通路，一次关了 24 行。

这不是理论上可行。你跑 dsh web 时，官方的 web 组合第一件事就是把基础层里二十多个功能整块摘掉。

dsh 的组合是分层叠加的：先铺一层通用的基础配置（base），再叠一层针对 Web 界面的配置（web-app）。而 web-app 这一层干的事，主要是关行——

关掉之后不是没了，而是交给下一层：每开一个会话，再按这个会话选定的组合把需要的行装回来。同一个进程因此可以同时跑一个功能齐全的 agent 和一个只有两把工具的极简 agent。

整个系统只有三样东西：一个框架、一堆插件、一份清单。

再复杂的细节都能塞进这三个词里。读不下去的时候回到这一页。

三者的关系是：框架不知道产品是什么，插件不知道自己会被谁组合，清单才是那个做决定的人。这句话解释了本书后面几乎所有的设计选择。

三个词各自的来历留给后面：框架叫 Cordis，不是 DeepSeek 为这次发明的（附录 A），它只干三件事（第 11 章）；219 个包按什么分组见第 12 章；那份清单不是写出来的、是若干层补丁叠出来的（第 13 章），--dump-config 能把叠完的结果连同来源注释一起打印出来（10.5）。

star 很多，issue 和 PR 是 0——开发现场不在这个仓库里。

这几个数字放在一起，比任何一段评价都更能说明它现在是什么。

还有一条更有信息量：公开仓库最近一次合并来自另一个组织的 2519 号 PR，而这里的 PR 计数是 0。公开仓库更像一份单向发布的镜像。推下去有三层意思：你读到的是内部主干在某个时点的快照；这两条线此后可能已经分叉，你看不到分在哪；社区拿到的任何东西都永远滞后一截。

现在就把它写进生产，这四件事要你自己扛。

这不是免责声明，是决策依据。四条里踩中任意两条，这一轮就先别上。

四样东西你多半已经有了，key 可以等界面跑起来再补

五项清单：前四项决定装不装得上，key 那项可以留到最后。

Node.js运行时

版本必须落在 ^22.19.0 || >=24.0.0 里，这是仓库写死的引擎范围。

pnpm包管理器

两种情况才需要：从源码构建，或者用 dsh plugin 装插件。它必须在 PATH 上。

git只有克隆才用

从源码跑、或者装 git 托管的插件时需要。走 npx 那条路用不到。

一个项目目录就是工作区

你在哪个目录敲 dsh，那个目录就是默认工作区根。

一个模型 key装完再配

不用提前准备。先把界面开起来，再到设置页里填，保存后下一次请求就生效。

最快的一条路是一行命令，不用克隆仓库

装好 Node 之后，从敲下命令到看见界面，中间没有别的步骤。

本书后面每条 dsh 命令都假设它在 PATH 上，而 npx 不会把它装进去

dsh 是 @deepseek-ai/dsh 这个包声明的可执行文件。它怎么进到你的终端，决定了后面几章你要不要每次都加前缀。

本书从第 9 章起写的都是裸 dsh。没有全局装的话，把每条命令前面补上 npx @deepseek-ai/dsh 就是等价写法——dsh web 即 npx @deepseek-ai/dsh web。

从源码跑要多两步，pnpm run build 是不能省的那步

pnpm dsh 直接跑 TypeScript 入口，它不构建，也不检查产物新不新。

漏了构建，boot 阶段直接报模块解析错误，不会提示你去补。

第一次启动，它替你建好了一个组合，你什么都不用配

自动发生的只有三件事：前两件在你的家目录里，第三件在你敲命令的那个目录里。

配 key 不用重启也不用改文件，保存后下一次请求就生效

不用重启服务，不用重开会话，不用改任何文件。

key 存进去就拿不回来了，这是设计，不是限制

写入是单向的：页面能提交，不能读回。

保存之后，浏览器收到的只是一个脱敏描述符，永远拿不到明文。密钥落在 $DSH_HOME/.credentials.yaml，是 0700 目录下的 0600 文件；设置文件里只留一个指向它的凭据引用。

凭据按四层顺序解析

规则是先命中的赢——和第 13 章讲配置补丁时「越晚的层赢」正好相反。

第 1 层最高，正是 CI 和容器该走的那条：DEEPSEEK_API_KEY=… dsh …、CI secret、容器的 -e 都落在这里，不需要任何文件。它也因此是只读的。

接别的厂商分两种：目录里已经有的，和你自己的网关

两个按钮，对应两条完全不同的路径。

你手工填的模型，默认按纯文本处理

给它附一张图，请求在发出去之前就被拒绝，并且点名是哪个模型。

表单里没有这个字段。要让一个自定义厂商的视觉模型收图，得去 $DSH_HOME/settings.yaml 给那个模型补一行 input。本片段假设你已经在表单里建好了 my-gateway 这个厂商，这里只是补表单填不了的那一项。

apiKeyEnv 是按请求解析的凭据引用，机密本身不进这个文件。写在路线上的 defaultInput 是回退而不是覆盖，默认 [text]。目录内的厂商没有 models 列表可写，要收窄某个模型的模态得写在 modelOverrides 下面、按模型 id 作键。DeepSeek 自己的 chat-completions 路线本身就是纯文本，配不出图片输入。

不选工作区，会话输入框就是灰的

全新的 Web 界面没有已选工作区。这一步没人替你做。

dsh 进程当然知道自己从哪个目录启动，那个目录也确实是默认的文件系统位置。但它只是一个默认值，不等于你授权 agent 去动它。所以界面把「选定」做成一个你必须亲手完成的动作。

开一个会话，你面对的是一个会动手的 agent，不是聊天框

官方指南给的第一句话就是让它读代码库：Summarize this repository and identify its main packages。

它在会话里能做四件事

建会话时还可以挑一个会话预设：一份决定这个会话带哪些面向模型的插件的配方，随包的有四个。其中「极简模式」把系统提示固定成一句话，只带持久 bash 和 str_replace_editor，其余面向模型的插件在那个 agent 里全部不在场；而浏览器、工作区、持久化、沙箱这套宿主设施照旧。预设是写进会话日志的，重开旧会话不会换成另一份。

弹窗问你，是因为这个会话的档位是「问」

界面上是一个选择器，实际上一次选中两件事：沙箱管到哪，以及需要审批时怎么办。

三档里 read-only 适合「只让它读和分析、不许改任何文件」的场景。一次批准也只对被问的那一次操作生效。进程级的回退档位可以用环境变量 DSH_PERMISSION_MODE 改——写成 danger-full-access 会顺手把审批策略也关成 never。

第一个任务要挑一件你能当场验证的改动，不是一句「帮我看看」

四步，十分钟以内。做完你手上会有一份 git diff，那才是「它真的在干活」的证据。

命令行只有四种入口，做的其实是同一件事

选一个组合，把那棵插件树点起来。区别只在点起来之后谁接管。

这一章往后写的都是裸 dsh。没全局装的话，按 6.3 的写法在前面补 npx @deepseek-ai/dsh。

dsh 自己只认四个 flag——--profile、可重复的 --patch、--dump-config、--dump-default-config——从它不认识的第一个 token 起，后面全部原样交给启动的那个应用。所以 dsh --profile web --port 8080 里的 --port 属于 web 应用；dsh --help 打的是启动器的帮助，dsh --profile web --help 打的是 web 应用的帮助，而且什么都不会启动。

headless 跑完就退出，退出码告诉你成没成

最轻的一条脚本入口：只看退出码和 stdout。

headless 里没有设置页，key 只能从环境变量进去

这个组合不挂 Host、不挂 Web、不开端口。第 7 章那条填表路径在这里不存在。

凭据四层里第 1 层是继承的进程环境，优先级最高（7.2）。CI 的 secret、容器的 -e、上面这种一次性前缀，全都落在这一层，不需要往磁盘上写任何文件。

模型路线用的是 base 层的出厂默认：厂商 deepseek-official、模型 deepseek-v4-flash。要换成别的，去 $DSH_HOME/cordis.patch.yml（对这台机器上所有组合生效）或者组合自己的 cordis.patch.yml 里，patch agent-default-model 那一行的 provider 与 model。

web 只有三个自己的 flag，而且它故意不让你监听 0.0.0.0

默认服务在 http://127.0.0.1:3080，这是一个本机工具的默认值。

「浏览器信任围栏」是 /api 那一侧的一道检查：只接受来自被认可名字的请求。--trusted-host 就是给这一次调用临时添一个名字。

关停有确定的语义

第一次 SIGINT 或 SIGTERM 开始一段最多五秒的优雅拆卸。SIGTERM 是监管进程的普通停止请求，退出码 0；SIGINT 退 130。第二次信号立刻强制退出。

headless 不是唯一能接进程序的入口，只是最省事的那个

要在任务中途拿到事件、答审批、或者取消，就得换一条。

Python SDK 支持 Linux x64、Linux arm64 与 macOS 14 以上的 arm64，Windows 不在其中。它跑的是仓库里那个 examples/jsonrpc-agent 例子：给一个工作区、一个会话目录、一句任务，打印最终回复，同时在会话目录里留下一份 JSONL 日志。

你自己的东西全在一个目录里

默认是 ~/.dsh。知道里面有什么，就知道该去哪儿改、该备份什么。

往 skills/ 加一个技能

新建 $DSH_HOME/skills/<名字>/SKILL.md，名字用 kebab-case，frontmatter 里 name 和 description 缺一项就被跳过。目录是被监听的，不用重启：回输入框敲 /，菜单里就有它。

profile 不是一份配置档案，是一个真正的 npm 项目目录

刚建好的时候里面有三个文件，外加一个每次启动都被重写的根锚点。

启动时这四层按顺序叠

装插件就是在这个目录里跑一次 pnpm

dsh plugin 把参数原样转发给 pnpm，工作目录设成那个组合的目录。add、remove、why、update 全都照常工作。

相对路径按你敲命令的那个目录解析，不是按组合目录，所以在插件检出里 add . 装的就是这份检出。demo 这个名字没有随包模板，dsh plugin 会当场替你建出来，只叠 @deepseek-ai/dsh-base 一层。

每次成功之后，它会拿安装结果去核对那份 bundles 清单：凡是依赖包在自己的 package.json 里声明了 bundle patch 的，自动加进层列表；没声明的留成普通依赖，并给一次性的提醒；被移除的自动退出列表。

改任何一行之前，先 --dump-config 看一眼它现在长什么样

两条命令，差别在于叠不叠你自己那几层。

前者只打 bundle 层，后者再叠上组合自己的 patch、家目录的 patch 和每个 --patch 覆盖。打出来的是一份仍然合法可加载的 YAML；没命中目标的 patch 报到 stderr。

dump 的注释直接告诉你每一段出自谁、又被谁改过

这是排查「我改的那行到底生没生效」的全部依据。

连续来自同一来源的行归成一段，段前那行注释先写它们出自哪个包或哪个文件，后半句 patched by 列出改过它们的每一层，按叠加顺序。上面这段的意思是：这两行都来自 base，其中第二行被你家目录那层动过。

反过来就是排查方法：你刚改过的那一行，如果段注释里没有 patched by，说明没有任何一层动过它——多半是 id 写错了（这种情况 dump 还会往 stderr 报一条没命中），或者那份 patch 文件这次启动根本没被叠上。

从「装好了」到「看懂 patch 是怎么回事」，最短的路是跑一个官方示例

仓库 examples/ 下有六个能直接跑的例子，每个解决一个不同的问题。

这一条跑完，界面上立刻多出三个工具（建定时提醒、列出、删除）。关掉进程再普通启动，它们就没了——这就是覆盖层：一次性的、不落地的一层 patch。

接一个 MCP server 是加一行插件，不是装一个集成

出厂状态下一个 MCP server 都不装——每个 server 的命令都是沙箱之外的可信可执行代码，得由你自己点头。

三条前提：可执行文件要你自己先装好，dsh 只负责启动和停止它；stdio 的桥在启动子进程前会摘掉名字看起来像凭据的环境变量和所有 DSH_*，要传的密钥得显式写进这一行的 env；HTTP 传输则要求上游服务已经在跑。

要用一个能力，你只需要知道它叫什么名字，不需要知道谁在实现它。

一个插件被装上时，框架只递给它一个对象：ctx。这个对象同时是三样东西——服务台、清洁工、广播站。这一节只讲服务台。

服务台的用法只有一种：喊一个名字，拿到一个能干活的东西。一个插件要读文件，它写 ctx.fs。至于名字背后是本机磁盘、是沙箱、还是一台远端容器，它不知道，也不需要知道。

这像酒店前台：你不认识洗衣房的师傅，你只跟前台说「洗衣服」。哪天酒店换了一家洗衣公司，你要说的那句话一个字都不用改。

第三列是出厂组合里真正挂着的包。Windows 上第二行换成 dsh-pwsh-sandbox，靠一个平台判断二选一。

这样的名字一共 56 个，其中 26 个明确留给人换实现，本书叫它们能力接缝。

插件做的每一件事都自带撤销键，撤销按什么顺序按，框架自己知道。

ctx 的第二重身份是清洁工。这一件事决定了这套东西能不能真的热插拔。

一个插件装上之后会做很多事：登记一个工具、加一段系统提示词、开一个定时器、连一个数据库。换在别处，这些都要作者自己记住，并在卸载时反着来一遍。漏一个，就是一条幽灵监听器。

这里反过来。每一次登记，框架当场把「怎么撤销」收走，记在这个插件实例名下——一个插件在运行时的那一份实例，仓库里叫 fiber；它记着这个插件登记过什么，卸载时逆序撤回。作者从头到尾没写过一行清理代码。

同一条回滚路径服务三个场景：你改了 YAML 触发重装、依赖的服务下线了、进程要退出了。三种情况下插件的卸载过程一模一样。

事件不是发出去就不管的通知，是一条你可以站在中间的链。

ctx 的第三重身份是广播站——审批、沙箱、超时，全靠站到中间实现。

常见的事件系统是「我喊一声，谁想听谁听，我不等你」。这里最要紧的那种不是：监听器按登记顺序一层层套在真正的动作外面，像洋葱——每一层先做点事再往下交，最里面那层才是本来要发生的事。

于是链上每一层能做三件事：放行、改写、拦下。本书把这种能站在中间的事件叫拦截点（源码里的 waterfall），只能旁观的叫广播点，在 ctx 上添东西的那些方法叫注册入口。

219 个包分成三类：能力家族、产品脊柱、支撑设施。

一个包一件事，一个目录一类事。这不是文档整理出来的分类，是仓库结构本身。

上表没画进去的还有一格：packages/README.md 的总表给每个组标了「发布预期」，绝大多数写的是 stable API，只有远端沙箱那一组 e2b/ 标着 POC。要拿哪个组当依赖，先翻那一格。

一个能力家族里，跟目录同名的那个包定义能力，旁边的那些实现它。

认得这条命名规则，你不看文档也能判断出一个包是干什么的。

换实现只需要在清单里关掉一行、装上另一行。上面那个工具包一个字都不用改——它认的是名字 ctx.shell，不是某个具体实现。

没有一份默认清单躺在那里等你改——它每次启动现算。

组合的根配置是一个空数组。这不是还没写完，是设计。

组合目录下那份 cordis.yml，全文是三行注释加一对空方括号。它每次启动都会被原样覆写回去，所以在里面写什么都留不住。整棵树由补丁叠出来，包括 agent 主循环那一行。

补丁按固定顺序叠四层：先是组合 package.json 里列的各个 bundle——dsh-base 永远第一，一次插进几十行，产品的绝大部分就是这一下来的；然后是组合目录里的 cordis.patch.yml；接着是家目录的 $DSH_HOME/cordis.patch.yml；最后是命令行上每个 --patch，按你敲进去的先后。四层各自装什么，10.2 有一张完整的表。

后一层认 id 不认位置：整块换掉那行的配置，或者干脆把它关掉。

补丁的语义只有两种，一分钟能讲完。

第一种是按 id 覆盖：写上目标行的 id 和新配置，这一行的配置被整块替换。第二种是追加：往清单尾巴上插一批新行；插进来的行会立刻登记 id，所以再后面的层能接着改它。

光是 web 这一层，就用「关掉」摘掉了 24 行。为什么只有关掉、没有删除，2.2 讲过成因。

不是插件的东西可以一次数完，而且里面没有一行产品语义。

「一切皆插件」这句话值多少，全看剩下那一小撮有多小、装了什么。

这张表里没有 agent、没有会话、没有提示词、没有工具，一个都没有。产品的全部语义都在补丁层——那正是第 21 章那句「没有特权内核」的实际含义。

遥测出厂是关的，但默认端点已经写死在代码里。

这一行被刻意抬到配置层之上，值得单独说清楚。

端点不是空的：dsh-base 里写死了 https://harness-telemetry.deepseeksvc.com/v1/logs，只有 DSH_TELEMETRY_OTLP_URL 能改。代码里确实带着一条指向 DeepSeek 的默认出口，只是出厂时那条管道没打开。

你敲下的那句话，要走完五站，才轮到下一句。

每一站的产物就是下一站的输入。知道自己在第几站，比记住每个模块叫什么名字有用得多。

系统提示词不是写死的一段话，是每一步现拼出来的。

没有模板文件，也没有一个「主提示词」等着插件往里填空。它是一张注册表：谁拥有某件事实，谁就注册这一段。

section段落

一段带排序号的文本。绝大多数贡献都是这一类，比如某个工具包写自己的使用说明。

context动态上下文

每一步现求值的运行期事实。它不会进入提示词，去向见下一页。

tools工具清单

一个提供者，报出自己这一批工具的名字与参数结构。

variable变量

供段落里 {{name}} 插值。没注册过的名字、求值为空的值，当场报错，不静默留白。

排序号有三条约定的号段：−100 是固定的 harness 身份，0 是部署方写的那一段人设，100–199 留给各个工具包的使用说明。号段是全局唯一的协调手段——除此之外，各段互不知道对方存在。

上下文装不下时它不删历史，只是给旧的那一段盖一层遮罩。

日志只增不删是硬约定。压缩因此是追加一条新消息，声明「我遮住前面第 a 到第 b 段」。

换一家模型厂商，要改的只有三个地方。

差异没有散在各处。它被按在三处——两个文件加适配器类上的一个方法，其余代码对厂商一无所知。

第三项最容易被做错。常见做法是造一个「低 / 中 / 高」的通用枚举，各家再往上映射——结果必然出现悄悄降档和语义漂移。这里的选择是：档位归适配器所有，核心不枚举取值。你选了一个这个模型不支持的档位，请求在发出任何网络包之前就报错，绝不自动帮你换成相近的一档。

工具不是一段返回文本的函数，它必须交出一份结构化的值。

工具交出的是一个规范 JSON 值——只含字符串、数字、布尔、数组、对象的普通数据，不能有函数、Map 或循环引用。给模型看的那段话是另外渲染出来的。注册一个工具，要一次声明齐下面四件事。

每次调用都走同一条管线，部署策略挂在段与段之间。

超时、权限、脱敏、外部钩子——这些东西一个都不写在工具里。它们是挂在管线接缝上的独立插件。

一条策略管住所有工具，而任何一个工具都不知道这条策略存在。想给全部工具加超时，挂一个环绕插件；想让某类调用必须人批，挂一个前置监听器。两件事都不用改任何一个工具的代码。

模型被沙箱拦住后可以申请放宽，但这次放宽只对这一次调用生效。

沙箱和审批这两个旋钮本身怎么转，在第 24 章。这里只讲被它们拦下之后还剩哪条路：升级请求要同时满足四个条件才成立，缺一个就当场拒绝。

别处是消息数组说了算，这里是事件流说了算。

几家 harness 都往磁盘写 jsonl，也都能靠它续上会话。差别不在落不落盘，在约束：这里有运行期断言盯着「模型看得见的，日志里必然已经有一笔」，而且压缩只加遮罩、不删事件。

谁能进入模型看到的那条线

本仓库共声明 44 种事件类型，其中只有三种能进：user/message、assistant/message、tool/result。而且它们必须在写入时声明怎么进——是接在末尾，还是替换掉前面某一段。别的事件只落日志，模型永远看不见。插件用类型合并加进来的自定义事件，同样受这条规则管。

读回来时同样偏保守

碰到本次构建不认识的事件类型，读取端直接拒绝打开整个会话，而不是跳过它。只有写入方明确打了「可跳过」标记的纯信息记录例外。

事件在追加那一刻就被冻结校验，坏数据根本进不了日志。

校验不放在落盘的时候，放在写入内存的那一步。三道关全过才算写进去，任何一关不过，日志一个字节都不变。

过关之后才拿到序号

三道关全过，事件才被追加进日志并同步通知观察者。序号恒等于追加前的日志长度，不跳号，所以任何一条事件的位置都是可算的，不需要额外索引。观察者自己出的错会被记录并隔离，不会让一次已经提交的追加反悔。

一段真实日志长这样：一次读文件，十一行。

仓库自带的端到端快照，截短脱敏后逐行标注。这是「44 种事件类型」落到磁盘上的实际形状。

进程崩了不会丢会话，它会替你把断口补齐。

崩溃、断电、被杀进程，日志都停在半路：有一个回合没有结束标记，有工具调用没有结果。冷加载时有一段专门的修复代码无条件跑一遍，把这些断口补成一份模型能接着往下读的记录。

同一条流折出五份投影，代价是日志会长得很大。

模型看到的历史、界面看到的状态、落盘的存储、遥测导出的记录、检索用的索引——五份东西全是同一条流的折叠结果，因此不可能互相分叉。

做部署评估要的量级

仓库里签入的 74 份端到端会话快照合计约 720 KB、182 步，平均一步约 4 KB（未压缩、已打包）。按这个单价推测：一次半小时、跑一两百步的编码会话，$DSH_HOME/sessions 大约多出 0.4–0.8 MB，压缩后更小。真正会把量级拉上去的是大段工具输出，不是对话本身。

继续问下一次，是数据决定的，不是监听器决定的。

一步跑完，循环只看两个数据：这一回合有没有已经定下的结束原因，收件箱里还有没有待办输入。两个都为空才收工。

一个回合的六种结束原因

子代理不是发出去等结果，它是一段可以续聊的持久对话。

一个子代理 = 一份持久会话，外加最多一份还活着的进程内实例（它创建的后代都结束了才释放）。那份实例可以跑很多轮；进程重启后从存储里冷恢复。

子代理的权限在委派那一刻冻结，而且只会变窄。

孩子拿到一个全新的作用域，只继承父的显式沙箱设置；审批策略一律被钉成「不问」，需要人批的操作在它那里是确定性拒绝。

模型可以自己写一段脚本来编排，但那一层不是安全沙箱。

脚本是一段普通 JavaScript，跑在一个独立工作线程里；脚本里调用的几个钩子通过消息打回主进程，去起真正的子代理。模型写的是编排本身，不是一句一句的委派。

工作线程换来的两件事

一是模型写的同步计算不会卡住主事件循环；二是终止线程是真正的最终止损——脚本迟迟不肯收尾时，宿主等一段宽限期后强制收尾，并给悬空的记录补上取消标记。

同一件事有五种做法，挑错了代价是上下文和钱。

这五种不是互相替代。它们按两件事分开：编排由谁写，以及那段编排模型改不改得动。

仓库里管 run_code 这套叫 Code Mode：注册表不再把每个工具的 schema 发给模型，而是生成一段 SDK 声明，模型写 TypeScript 去调它们。纯 code 模式下它是模型唯一能直接调的工具。

代价：没有内核保护你，一行插件就能停掉整个工具派发。

这个特点第 14 章讲过，这里只算账：「什么都能替换」和「什么都能被替换掉」是同一句话。

先把最诱人的那句收紧。主循环在配置里也只是一行，能摘能换——但那一行没有契约接住你：ctx.agentLoop 标的角色是打包层，不是能力接缝。它是「一行配置」，不是「一个接缝」。

代价：读到不认识的事件类型，它宁可拒绝打开整个会话。

这个特点第 19 章讲过，这里只算账。拒绝本身是对的——静默跳过会「成功地重建出一个错误的会话」。

代价：它粗到不能只放行 git status，于是长任务里人会把它关掉。

机制在 24.1，这里只算账：克制是真的，可预见的退化也是真的。

这两个旋钮不是凭空来的：它与 Codex CLI 的沙箱模式和审批策略几乎同名同义，差别是 Codex 的审批策略还有 on-request 和 on-failure 两档。所以「这一版还没有规则表」比「刻意没有」准确——on-failure 正是为缓解第三条设计的。

换来的是一套连文档陈旧都会亮红灯的检查体系。

下面这些数字不是规模炫耀，它们是「工作量不算成本」这条前提的直接产物。

判断一个系统是不是真的插件化，只看一条：你能不能删掉它自带的东西。

扩展点多不说明问题。能不能把宿主自己的功能摘掉，才说明产品和插件站在同一个平面上。

这条通路第 02 章已经证过：整个产品叠在一个空数组根配置上，官方自己的 web 组合就在走它。这一页只做一件事——把 dsh 放回同类系统里比一比，只跟做同一件事的东西比。

前三行不是能力不足，是产品选择：可动的面越窄，官方越能保证装了别人的东西之后自己还站得住。dsh 反过来，上限抬得很高，代价是它必须假设所有插件都可信。那堵墙第 37 章正面讲。

改掉它的内置行为有四条路：一条不写代码，三条对应 ctx 上的三类调用。

认清这四条，第 31 章那张全图就只是在往里填名字。

插件分五种角色，动手前先确认自己要写的是哪一种。

这五类的写法、依赖、难度完全不同。搞混了，第一步就会走岔。

代表例子：ctx.fs、ctx.shell、ctx.llm 是能力定义；dsh-fs-sandbox、dsh-bash-sandbox、fs-e2b 是实现；tool-bash、tool-fs 是工具；timeout-policy 是策略钩子；ui-plan、ui-jobs 是界面。

那 52 个工具不会同时摆在模型面前。web 组合在基础层上一口气关掉 24 行（工具、计划模式、压缩引擎都在内），改由每次会话挂上的会话预设决定这一次露出哪些——出厂四个预设里，「极简模式」只给两个：持久 bash 和 str_replace_editor。逐条清单见附录 C。

最被低估的一类插件不注册工具、不提供服务，只挂一个监听器。

它不改任何数据结构，也不进模型看到的清单，却能实实在在改变系统的行为。

官方自己就有一批这样的包，每个只干一件事：

timeout-policy超时策略

包住工具分发，换上自己的截止信号。整包 81 行，是这类插件最好的模板。

fs-observation-policy读后写策略

监听文件写入与编辑意图，没读过的文件不许改。与文件系统的具体实现互不相干。

time-context时间上下文

在每一步之前把当前时间注进模型将要看到的消息里。

组织里最常见的需求——禁掉某些命令、按小组限制工具、把每次调用送去审计——全部落在这一类里，二十来行就能起步。

从不写代码到必须读内核，切入点排成五级台阶。

先认清自己站在哪一级，再决定这个周末要走多远。

前三级都在主机这一侧，一个下午能上线；第五级是另一个复杂度量级。

动手之前先定三件事：在哪执行、由谁拥有、怎么发布。

这三个问题决定了你写的是哪种文件、放在哪个目录、别人怎么拿到。答错一个就得返工。

让它认出你的插件，只要三样东西：一个文件、一行配置、一条命令。

不用 npm、不用打包、不用建 package.json。

配置里的插件路径必须写成绝对路径——写相对路径不是悄悄失效，是让启动直接失败。

这是新手在这条路径上最常摔的一跤。好在它摔得很响。

补丁文件只贡献配置，不会把模块解析的基准目录挪到自己身上——相对路径按组合目录算。

按组合目录找不到那个文件，启动不会带着半棵树继续跑，而是直接终止，终端上打出 dsh: plugin tree failed to load: failed to apply loader entry hello (…)。看到这条，先怀疑路径基准，别去翻插件代码。

插件「没动静」时的第一件事不是加日志，是先把组合打印一次。

大半的问题在这一步就现形了：你那行到底进没进去，一眼可见。

层标签有两种形状：bundle 那层印的是纯包名，你自己那层印的是解析后的绝对路径——不是命令行里敲的 ./scratch-plugin/…。想 grep 自己那段，按绝对路径找。

一个能用的工具，全文就这么长——四件事交给注册表就完了。

替换掉上一章那个文件的全部内容，重启就能用。没有省略。

output 不是可选的美化项，少写它，注册当场就抛错。

很多人照着别处的工具写法只填 parameters 和 execute，然后在启动阶段撞上一条看不懂的报错。就是这里。

output 里有两件事，分工很清楚：

schema规范值的形状

execute 的返回值必须符合它。每次成功返回、以及被策略替换过的返回值，都会拿它校验一遍。

render模型看到的内容

把那个规范值翻译成模型读到的文本块。它必须是纯函数，只依赖入参和这个值。

你只需要写「怎么执行」，校验、渲染、注销都不用你操心。

30.1 那段代码里，除了 output，其余三段各自在替你挡掉一类麻烦事。

parameters 顺带把类型和校验都给了你

声明完这一段，defineTool 会据此推导出 args 的类型，并在进 execute 之前替你校验模型传来的东西。模型给错参数，根本走不到你的函数里。

execute 的第二个参数带着身份与取消信号

示例里只用了 args，实际还有第二个参数 exec，带着这次调用的身份、调用方，以及一个 exec.signal。写长任务必须自己检查它——取消是协作式的，没人会替你把函数掐断。

register 的返回值让注册本身可撤销

它返回一个撤销函数，并自动挂在当前这个插件实例上。插件被卸载，这个工具就从模型的清单里消失，不需要你写任何清理代码。

第三方能挂进去的地方只有三类，先归位再翻清单。

上一部那四条路里，除了改配置那条不用写代码，剩下三条就是这一章的三页，各是一张清单。翻之前先用这张表把你要做的事归到一类——归错类，后面三页都白读。

三类的写法都是同一句——在 ctx 对象上调一个方法，拿回一个撤销函数。区别只在你站的位置：第一类是在旁边加一样东西，谁都不挡；第二类是站进别人的调用链中间，你不放行下游就不动；第三类是把某个能力的唯一实现整块顶掉，上游一行代码都不改。

往框架里注册内容，是三类里门槛最低的一类。

这一类的写法都是同一句：在 ctx 对象上调一个注册方法，拿回一个撤销函数。八个最常用的入口在下面。

挂一个监听器，就能在别人做决定之前插话。

这是第三方最被低估的一类：不注册工具、不提供服务，纯靠监听器改变行为。官方自己就有十几个这样的包，最短的八十来行。

接缝越窄越好换，难度基本等于要实现几个方法。

你不是加东西，而是把某个能力的实现整块换掉。依赖它的插件会干净地重启，接到你这一份上。

表里的外溢存储（spillStore）最容易被跳过：工具结果太大时先落到旁边的存储里，只把摘要给模型。

bundle 是你写的，profile 是用户开的，没有东西两者都是。

安装只建立在这两个概念上。两者都由一份 package.json 描述，但回答的是完全不同的问题。

最终配置由四层依次盖出来，顺序见 13.1。作为 bundle 作者你只需要记住其中一条：你贡献的是最靠前的那一层，用户在后面三层里随时能盖掉你——所以默认值要选用户大概率会保留的那种。

用户也不必手写清单。web 和 headless 两个组合首次使用时自动初始化，其余的用 dsh plugin 创建；你的安装说明只需要给一条命令。

决定它是不是插件包的，只有 package.json 里的一行。

缺了那一行，包照样装得进去，只是变成一个普通依赖：安装时打一行警告，然后什么层都不激活。

dsh.bundle.patch决定性的那一行

指向随包的补丁文件。有它才是 bundle，没有它只是依赖。

exports / files别漏东西

补丁文件既要导出、也要列进打包清单。漏了它，包装上也没有层。

从 git 装一个插件，等于允许它在你机器上执行代码。

安装命令本身很短。分歧在其中一种来源：从 git 装是唯一需要用户额外点头的路径，而这个头点下去的分量比看上去重。

第一条装包并把这一层追加进组合；第二条不启动、只打印组合出来的树。

框架必须只有一份，所以官方包一律写进 peerDependencies。

这不是风格偏好，是会不会跑起来的问题。ctx、服务和插件实例这一套，认的是「是不是同一份」，不是「长得一不一样」。

把框架包写进 dependencies，包管理器会在用户的组合目录里再装一份。于是你的服务注册进了另一棵服务树，而你依赖的能力在这棵树上根本不存在。peerDependencies（同伴依赖）的意思正好相反：这个包由宿主提供，我不自带。

最狠的两个静默失败，都出在导出方式上。

官方有一份事故复盘专门记这两条。共同点是：代码看起来正常，类型检查也过，只在真实加载路径上炸。

插件「什么都没发生」有两个成因，启动期都会当场报错。

新手最常撞的一类，但它一点都不安静：两种都让启动当场失败。

补丁按行整块替换，写漏一个字段就等于删掉它。

配置层是这套架构最强的地方，也最容易安静出错。两条规则都不报错。

有两处限制不在你的代码里，改不动，只能绕。

前面几条是你写错了。这两条不是——你写得完全正确，限制在别人的代码里。

要不要写 dsh 插件，三句话就能判断。

这一页是整章的入口。绝大多数人问「我该怎么给它写插件」的时候，其实并不需要写插件。

值得做的方向，集中在官方留白和社区没人做的交叉区。

判断标准两条：有没有现成接缝能干净地做，官方和社区是不是都还没做。

有七类方向不该动手，原因不是难，是这套结构接不住。

它们都是真需求。前六类结构上给不了；最后一类给得了，但没有契约接住你。

这十条全过了，你的插件才算能交出去。

前面几节的所有坑，压缩成一张可以逐条打勾的表。它们的共同点是：不过也不报错。

五个问题，覆盖八成的「装上了，但不对劲」。

「谁更强」问不出答案，「你要控制哪一层」才问得出来。

任何一个 agent harness 都可以拆成四层。你在哪一层需要说了算，就决定了你该选谁。

dsh 的差异只在第三层：ctx.fs、ctx.shell 被做成 26 个可整块换掉的接缝。一、二层与别家相当，第四层更弱。

它们可以待在同一条工作流里，各占一层。

仓库里真实存在把竞品当插件用的包。这是它对自己位置的声明：编排层，不是又一个终端 agent。

hooks-claude-code 和 hooks-codex 是桥接器：指向你已有的 hooks.json，让那些 shell 钩子原样跑起来。mcp-client 用的工具命名也是 mcp__<server>__<tool>，跟两家一致。已经攒下的这些资产，换过来不用重写。

它写下来的东西都不构成承诺——版本没有，文档也已经对不上了。

仓库里没有 CHANGELOG，没有任何兼容承诺，也没有划出哪些是公开 API。

发布通道本身是有的——release.yml 从 dsh-v* 标签手动触发发布，带 rc 段的版本一律进 next 标签，vendor 那条序列另有自己的标签与工作流。但那是发版机制，不是稳定性承诺。

大意：因为没有外部使用者，宁可把地基做对也不做兼容垫片；可以随意改名和重新打包，后端直接拒绝旧的磁盘格式。

文档走样已经开始了。生成的能力接缝表里，ctx.lsp 的实现写作 lsp-local、ctx.codeRuntime 写作 code-runtime-worker，而仓库里这两个包实际叫 lsp-stdio 和 code-runtime-worker-thread——改名发生在 2026-08-11，开源在两天后，文档没跟上。源码注释里还留着指向已不存在目录的链接。

把 Web 界面绑到 0.0.0.0，等于把本机 shell 开给整个网段。命令行那一层已经拦了一道——--host 0.0.0.0 会直接报错退出（9.4）；但配置层的 host 只有 127.0.0.1 和 0.0.0.0 两个合法值，改配置文件仍然绑得上。也就是说走到这一步需要一次刻意的动作，而不是手滑。

这不是猜测，是官方在自己的 README 里写明的已知限制。

大意：没有传输加密、没有身份认证、没有来源校验；绑一个非回环地址，就等于把这台服务器暴露给那个网络。

要理解这条有多重，得把它和背后的东西连起来看：连上这个端口的人，指挥的是一个握有本机 shell（ctx.shell）、能读写全盘文件（ctx.fs）、能起子进程的 agent。没有登录页，没有令牌，没有来源检查——端口通了就是全部权限。

官方把加固明确划在范围之外，说这是「面向开发者的 v1」，让你自己放到真正的反向代理后面。

现在就算清楚你要怎么退出来。

投入越深，绑住你的东西越不可迁移。这三档的差别很大，值得在动手前分清。

三档里真正决定退出难度的不是代码量，是你把多少判断写进了框架的语义。第二档的插件文件里如果只剩注册与拆卸，业务逻辑整份都能搬到别的 harness 上；第三档一旦用上 Cordis 的加载顺序、插件实例的逆序撤回、前端插槽的生命周期，这些语义在别处没有对应物，只能重写。

同一个问题问四遍，会得到四个不同的答案。

「值不值得用」没有统一答案，取决于你打算拿它干什么。

如果你还是要动手，这六条现在就做。

每一条都对应前面已经出过事的一个坑，不是泛泛的最佳实践。

这本书有五处明确的空白，现在告诉你它们在哪。

不是「暂未涉及」，是我们清楚它重要、这一版确实没做。

这 26 个位置，你可以整块换掉实现。

这 26 个的难度差得很远：sandbox、spillStore、workflowEngine 各只有一个抽象方法，fs 有十二个。想动手，就从只有一个方法的那几个挑。

仓库内置的工具一共 52 个，但没有哪套组合会装全。

要知道自己那套组合到底能看到几个：web 这一层补丁关掉了 24 行，2.2 举了其中一部分；要精确到行，读 packages/bundle/web-app/cordis.patch.yml。