ARTICLE · 1370242
第 2 篇 :预备|八个词,读完就能读源码
第 2 篇 :预备|八个词,读完就能读源码预备|八个词,读完就能读源码 第 2 篇 · 预备 · 约 7900 字 这一篇不讲 dsh 的任何机制,只讲八个词。 它们不是行业黑话。每一个都对应架构里的一个具体位置:某个东西装在哪、谁来决定、状态存在哪、命令跑在什么房间里、两件事撞上了听谁的。把词和位置对上,后面二十七篇的源码走读才不至于卡在名词上。 八个词里前六个是架构词汇,后两个是语言底子。前六个讲完你就能看懂深入卷在防什么,后两个讲完你就能看懂代码长什么样。 
八个词在架构里各管一摊 一、插座与插头:用的人只认识插座 装修时有两个世界。 世界 A,冰箱的电线和墙里的线焊死在一起。换冰箱?拆墙。六个电器六个焊点,换任何一个都是工程。 世界 B,墙上有标准插座,电器带标准插头。冰箱、洗衣机、新买的空气炸锅,只要插头符合标准,随插随换,墙永远不用动。 软件里的差别一模一样。代码里写死 这套做法行业里叫依赖注入。名字唬人,本质就一句话:用的人只认识插座,不认识插头。 dsh 的插座长这样: 角色只有三个:
可换性不靠约定,靠插座。 这是 dsh 后面所有「换一块积木就换一个产品」的前提,第 11 篇会把它讲到接缝的粒度。 插座世界能运转,靠两条规矩。 一个插座同时只许一个插头。 第二个来登记的直接报错,不是覆盖、不是排队。理由很实在:两个插头同时供电,用电的人不知道听谁的。要换,先拔旧的。这条在 dsh 里对应「加载第二个实现会 throw」。 先声明需求再开工。 插头来登记时说「我需要先有 llm 插座」,系统按依赖关系排好安装顺序,不用人脑排。这叫 inject 声明。 然后是「插件」这个词。 插件 = 插头 + 它自带的一小段安装逻辑。装上它,插座上多了能力;拔掉它,把它装的东西全数带走。 最后半句是分水岭。坏系统里,插件往墙上钉了钉子,拔掉插头钉子还在,系统被悄悄改了状态;好系统里,插件登记过「我钉了一个钉子」,拔除时按登记逐个回收。 dsh 里这三分之一套叫法要认一下:登记簿叫 effect,回收动作叫 disposer,装着这些登记的那个容器叫 fiber。 可卸载性不靠自觉,靠登记。 没有它,就没有热重载,也没有「在市场里试用完就卸掉」这种玩法——因为卸载不干净的系统,插件只敢加不敢减,几个月后没人知道哪个功能是谁带来的,也没人敢动。 举个具体情形。dsh 里所有命令都从 这是插座最值钱的地方。但它只在一种情况下成立:定义、实现、使用者三样都齐了,才算一个能换的接缝。少任何一样,换实现就得动别处——定义缺失,实现只能自己造一套;使用者绕过插座直接引用实现,换的时候还得回去改它。第 11 篇讲的就是怎么判断一个地方算不算接缝。 二、事件与瀑布:广播管通知,瀑布管决策 想象小区广播站。 物业喊一嗓子「3 号楼停水」,全小区谁装了收音机谁听到。物业不关心谁在听、有多少人在听,喊完就走。 事件就这三个特点:喊的人不认识听的人;可以很多人同时听;喊过就完,不等回复、不返回结果。 对比直接调用:直接调用是点名,我认识你,我等你办完;事件是广播,爱谁谁。大系统里广播多,因为点名会让所有模块互相认识,很快没人看得懂谁连着谁。 但广播解决不了决策。 有一天物业要定「外来车辆能不能进」。这不是广播,这是要一个明确答案,而且不同的人要依次把关:保安先查名单,物业再查业主群有没有人反对,最后门禁执行。 这就是瀑布模式。请求像水一样流过一串关卡,每关可以做四件事之一:放行(顺手改改内容)、自己拍板短路返回、交给下一关、在结果回来之后加工。 它的写法固定长这样,这是读深入卷源码的钥匙: 必须调 next,意思是不调就把后面全掐断了。 该掐的时候掐——关卡判定拒绝,直接返回理由,这叫短路,合法且有用;不该掐的时候忘了调,整条流水线悄悄死在你手里,不报错、不抛异常,只是后面的关卡和默认处理再也没跑过。 这是深入卷反复警告的头号错误,因为它的症状是「功能莫名不生效」,而不是崩溃。 dsh 用了五种喊法,混个脸熟即可,用到时回来查:
事件名不是随便起的。 还有一件容易忽略的事:监听器本身也是登记物。插件挂上一个监听器,等于在它的 effect 登记簿上又记了一笔,卸载时监听器跟着摘掉。否则会出现最难查的一类故障——插件已经卸了,事件还在往一个不存在的对象上送,报错信息指向的地方和出事的地方不是一处。 最常碰到的四个关卡: 能通知的事用广播,要答案的事用瀑布。 把决策写成广播,会得到一堆各自为政的答案;把通知写成瀑布,会得到一条谁都不敢乱动的链。 三、账本与报表:记流水,不记余额 银行卡有两种存法。 方式 A,只存一个数字:余额 5200。快,省事。 方式 B,存每一笔交易:+5000 工资、-300 外卖、-18 咖啡。余额是算出来的。 方式 A 看起来聪明,直到你问三个问题:上个月在吃饭上花了多少(答不出,原始信息已经丢了);余额怎么变成 5200 的、会不会算错(无法验证);发现三个月前有笔错账(改不了,改了余额,历史更对不上)。 银行选 B。软件存数据也一样:只存流水,状态随时可算。 这个思路叫事件溯源,本质就是记账不记余额。 光有流水账还不够,要配两条纪律。 只追加,不改写。 记错了怎么办?再记一笔更正,「上笔作废,应为 200」,而不是涂改原始那笔。因为账本的价值在于「当时记了什么」,涂改一次,之前所有账的可信度一起作废。 报表可以有很多张,流水只有一本。 余额是一种算法,月度支出统计是另一种算法;同一本账,爱算几张算几张。从账本算出报表的纯函数叫投影。 这里的不对称要记住:账本是唯一事实,报表全是从属品,可以随时重算,可以扔掉重做。 顺手学一个词:幂等。同一件事做一次和做一百次结果一样。电梯按钮幂等,按 1 次和 100 次电梯都只来一趟;转账扣款不幂等,执行两次扣两遍。 为什么在这讲它:账本加断电的世界里,经常需要「重做一遍刚才没做完的事」。只有幂等的操作才能安全重做。dsh 断电恢复时给模型的提示原话就在教这件事,只有确认操作是只读或幂等的才重试。 崩溃恢复的差别最能说明问题。程序写到一半断电,两种存法的现场完全不同:存状态的,状态文件可能写了一半,旧一半新一半,损坏,而且无法知道损坏前是什么;记流水的,账本最后一笔可能写了一半,砍掉这半笔就行,前面每笔都是完整的,恢复到上一笔完整记录就是安全点。dsh 里这个动作叫 torn-tail 修复。 具体到 dsh,一条会话账本上记的是这些:用户说了什么;模型回了什么,包括它想调哪个工具、参数是什么;工具实际跑了什么、输出是什么;这次调用是谁批的、批的时候看到的是什么;这一步用的配置是什么。它不记「当前对话内容是什么」,那是报表,随时可以算出来。 这份原料决定了排查的顺序。遇到「它为什么这么答」,先看账本里它当时看到的输入,而不是盯着屏幕上的对话猜——屏幕上是渲染出来的报表,和模型拿到的那份可能不是同一份。 存状态的系统记不住自己是怎么变成这样的。 这是第 9 篇的全部内容,这里先记住这句话就够。 四、图纸审查:把错误挪到开工之前 盖楼前图纸要过审。审查员逐条核对:这里标了承重墙,你后来画的窗户开在承重墙上,不行。问题在开工前抓住,比楼盖好了再拆便宜一万倍。 TypeScript 就是这个审查员。你在代码里标注每个东西是什么类型,它在运行之前逐条核对所有用法。把水管接到电线上?当场报错,程序根本不让跑。 dsh 全仓 TS。深入卷里出现的「编译期保证」「类型碰撞」,说的都是同一件事:错误在写代码时被抓住,而不是在用户面前爆炸。对比那些要跑到那一行才发现错了的脚本语言,差的不是安全性,是修复成本。 这里有个常被混淆的分工:类型检查发生在写代码的时候,不发生在运行的时候。运行时拿到一份坏数据,类型标注不会替你拦,它已经被编译掉了。所以这类框架两套检查都有——编译期保证「代码之间的用法没错」,运行时校验保证「外面送进来的数据没错」。前者零成本,后者有成本但必须做。dsh 的边界在进程之间、网络之间,那些地方靠运行时校验加权限,不靠类型。 TS 有个特性叫声明合并:同一个名字的接口,不同文件都可以往上添笔,最后合成一张大图。 为什么需要它:插件系统里每个插件都要能往总图上添自己那一笔——我提供的服务长这样、我发的事件长这样——而不是去改一张人人共用的中央文件。dsh 的事件词汇表就是这么由上百个插件各自添笔拼出来的。 添笔也会添出事故,这就是第 17 篇那个最硬的「为什么」。 同一栋楼,后厨的图纸和客厅的图纸都要标注同一面墙:后厨图在这面墙上标灶位,客厅图在同一面墙上标电视墙。两张图都对。但如果审查员把两张图叠成一张审,同一面墙出现两个矛盾标注,审查员罢工。 dsh 面对的就是这个局面:Host(干活的后厨进程)和 Client(浏览器客厅)对同一个名字各有一套正确的类型标注。解法笨但唯一:分两张图纸分别审,黑话叫两个 aggregate;再允许存在一张小区总平面图同时引用这两张,黑话叫 solution。总平面图不细审每面墙,所以不打架。 类型检查的价值不在多一道检查,而在于把发现错误的时间点从用户面前挪到了提交之前。 挪不动的那部分——两个进程各有一套正确标注——只能靠拆图纸解决,这是后话。 五、玻璃房与传纸条:沙箱不强制就只是建议 双击一个程序,操作系统干的事是给它一个独立房间:自己的内存,自己的门牌号(PID)。房间里的人以为自己是唯一的人。 三个日常事实决定了后面所有的工程细节。 程序可以生孩子。 你的程序启动别的程序,孩子还能再生,全家叫进程树。dsh 跑 关掉家长不等于关掉全家。 这是最容易踩的坑:杀掉 npm,它的孩子们可能变孤儿继续跑,占着端口、写着文件。要整树回收需要专门手段,每个操作系统一招,dsh 里做了三种。 房间一关灯全没。 进程一死,内存里的东西全部消失。这是为什么重要数据必须落盘,也是账本为什么是文件而不是变量。 整树回收之所以每个系统一招,是因为「一家人的范围」在各系统里的定义不同:Unix 上是进程组,可以整组发信号,但子进程自己另开一组就逃出去了;Windows 上是 Job Object,把一族进程装进去,关掉时一起灭;还有的系统只能靠父进程记账、逐个杀。这就是为什么跨平台的执行底座要把这些差异包起来,而不是写一句 kill 了事。 沙箱就是给程序盖玻璃房:只许看指定几本册子(只读目录),只许在指定桌上写字(可写目录),干别的全部被玻璃挡住。 关键词是「挡住」的方式:操作系统层面强制,不是「说好了不许」。代码里写一句「请不要访问 /etc」是建议, 现实是不同系统盖房的材料不一样:Linux 有两种、macOS 有一种、Windows 有一种,能力也不完全一样。Windows 那种盖不严,系统会诚实地告诉你「部分限制」。而玻璃房盖不起来的时候,正经系统的选择是这条命令不跑,而不是算了不盖了直接跑。 环境变量是大门口递进来的一叠纸条:去哪找程序、你家在哪,可能还有一把密钥。 纸条会被整叠传给孩子:你的程序带着纸条去启动 npm,npm 再传给它孩子,一张纸条全家都知道。所以 dsh 启动任何外部命令前先抽掉敏感纸条,名字里带 KEY、PASSWORD、SECRET、TOKEN 的全部抽走。不抽的话,一行 把三者串起来,一条命令的旅程是三件事同时发生: 沙箱要是不强制,它就只是建议。 这条线和第 19 篇的威胁模型是同一件事的两端。 六、同时发生的坏事:竞态不是代码写错 银行转账的老代码只有两步:查余额够不够 1000,够就扣 1000。 单看没毛病。现在你同时在两台手机上各转 1000,而余额只有 1000: 只有一千却转出去两千。 问题不在哪一行写错了,每一行单独看都对。问题在于两件事同时发生,而代码假设了「查完到扣之间世界不会变」。这个假设破产的瞬间叫竞态;把查和扣绑成不可分割的一步叫原子性。 大系统对付「同时发生」,朴素有效的招数就三种,dsh 全用了。 排队。 同一时刻只许一个人动这个账本,别人排队。绝不竞态,代价是慢。适合不常冲突但要绝对正确的东西,比如同一会话的写入。 状态机。 把「现在处于什么阶段」写死成有限几种状态,每种状态只允许特定动作。运行中不许再启动第二个,很多竞态在状态机面前直接不可能发生——本来是「两个动作抢」,变成「第二个动作发现状态不对,直接报错」。 快照。 做事前把要用的数据拍下来,之后世界怎么变都影响不了这一件事,变更等下一件再生效。dsh 在发模型请求前冻结这一步用什么模型、什么工具,就是这个招。 冻结的不只是模型名。工具列表、系统提示、权限策略,凡是被模型看到的东西都要跟着冻。原因很直接:模型这一步的输出接着上一步的语义来,中途把工具列表换了,它对「我能做什么」的认知和实际能做的对不上,输出了一个已经不在列表里的工具名。冻住之后,任何变更等下一步再生效——代价是配置改动有延迟,收益是每一步都可判定。 还有一个必须单独说的选边原则:fail-closed。 系统总有拿不准的时刻:审批弹窗没人应答、沙箱软件坏了、存盘失败。每个拿不准都要选边倒。fail-open 是先放行,出事再说;玩具可以,管着你电脑权限的程序不行。fail-closed 是拒绝或停下,并说明原因:电梯感应失灵就别关门,审批没人应就是不批。 dsh 选 fail-closed,并且拒绝必须带原因。因为「用户拒绝」和「审批通道坏了」是两种不同的拒绝,模型收到之后会做不同的事:前者换个方向,后者可能该停下来报告。 一个微缩案例,第 8 篇会逐行讲。 用户在按下「停止」的同一瞬间发来一条新消息。朴素的代码两头都错:把消息塞进正在死去的这一轮,消息跟着被取消,丢了;直接拒绝消息,用户输入无故消失。 dsh 的解法是状态机加快照的组合:先看停止状态分类,判定这条消息属于下一轮,再入队。顺序反过来——先入队再判断——就重新引入竞态,因为入队之后状态可能已经被别人改了。 并发问题不是「同时发生」造成的,是「代码假设了不会同时发生」造成的。 七、语言底子:TS 与 await 够用版 这两块原文各有一课,加起来近五千字。公众号里没必要铺那么开,读源码够用的部分压成一节。 TS 先认六件事:
再认三件事: await 要讲清楚,得先讲阻塞。 同步代码是一行跑完再下一行。中间要等一个慢操作,比如读文件,整个程序就停在那,这叫阻塞。 事件循环的做法是不等:登记一句「做完了叫我」,然后去干别的,做完了再回来接着跑。 回调的痛点是同一件事被拆成几段,写在不同的地方,读起来像被腰斩,还容易漏掉错误处理。 await 就是编译器替你把拆开那件事做了。写起来像同步,实际是「跑到这里让出,别人先用,回来接着跑」。 三个容易搞混的点:await 不阻塞线程,它只暂停当前这个函数;await 回来之后可能已经在另一个上下文,之前读的变量未必还成立;忘了写 await,你拿到的是一个承诺而不是结果,后面的代码会拿着一包空气继续跑。 await 不是让程序等着,是让写代码的人不用自己拆。 八、这套词汇的账单 八个概念每一个都在付代价,这些代价通常没人写在文档里。 插座让读代码要跳转。 看到 事件让调用链消失。 grep 一个函数名,找不到谁在调用它,因为没人调用,只是有人发了事件,恰好它在听。排查时必须在脑子里维持一张「谁关心这个事件」的表。 账本让文件变大。 一个会话跑久了,日志比对话本身大得多,启动要重放,压缩成了专门一章(第 9 篇后半)。而且只追加意味着磁盘只增不减,除非有明确的截断策略。 类型让编译变慢,也让改动变贵。 改一个接口字段,全仓跟着改;双 aggregate 意味着同一个名字在两处各有一份定义,读者必须知道自己在看哪一份。 沙箱让命令跑不起来。 用户看到「这条命令明明能跑」时,答案是玻璃房盖不起来,不允许裸跑。 fail-closed 会拒掉正常活。 审批没人应答就是不批,用户离开了十分钟,回来发现任务停在中间。这是设计选择,不是 bug,但感受上是成本。 排队让系统慢,快照多一份数据。 同一会话写入串行,意味着一个人慢全家慢;快照之后配置变了怎么办,是要专门定义的语义。 这些代价换来的是同一个东西:事后说得清。 每个词都在回答这个问题的某一面——当时是什么状态、谁决定的、记在哪、跑在什么房间里、两件事撞上了听谁的。 九、这张表当字典用 后面二十七篇会反复用到这八个词,遇到想不起的回来查这张表。
读完这一篇,你应该能看懂深入卷里那些句子的形状了:某个能力从哪个插座取,经过哪几道关卡,结果记进账本,命令在哪个房间里跑,两件事撞上时听谁的。 下一篇是全景,把这条链一次走完:一条消息从浏览器出发,到磁盘上的一个字节,中间经过五个地方。

import 冰箱 from "./冰箱" 是焊死,换实现就得改调用方;约定「墙上有个叫 fridge 的插座」是插座,谁要用电就找插座,不关心背后是海尔还是西门子。ctx.llm、ctx.tools、ctx.shell、ctx.sessions。代码里写 ctx.shell.run(...),它不知道背后是本地 shell 还是容器,也不需要知道。换一个 shell 实现,调用方一行不改。ctx.llmctx.shell | |||
ctx.shell 出去,背后默认是本地进程。现在要把某些命令关进容器,改的是装配:把 shell 插座上那个实现换成走容器的版本。工具代码一行不动,因为它们从来没见过「本地」这个词。async (请求, next) => {
检查或加工请求
const 结果 = await next()
加工结果
return 结果
}
agent/pre-step、tools/execute 这种带斜杠的写法是路径,斜杠前面是范围,后面是时点。这样可以用一个前缀一次听完一个范围里所有时点,不用把名字逐个列出来。agent/pre-step 负责代理认领输入前能不能改、能不能拒;agent/request 负责发给模型前改参数;tools/pre-execute / execute / post-execute 是工具执行的前中后三道;session/event 是账本每记一笔就广播出去。// A 文件:interface 食堂 { 午饭: string }
// B 文件:interface 食堂 { 晚饭: string }
// 合起来:食堂 { 午饭, 晚饭 }
npm test,npm 启动 node,node 可能再启动 worker。bwrap、Landlock、Seatbelt、Windows ACL 这些是物理隔离。echo $DEEPSEEK_API_KEY 就能让模型看到你的密钥。1. 抽纸条:敏感环境变量先抽掉
2. 进玻璃房:只能读写指定目录
3. 树登记:它和未来全部子孙挂进托管名单,结束时整树回收
手机 A:查余额 → 1000,够!
手机 B:查余额 → 1000,够!(A 还没扣)
手机 A:扣 1000 → 余额 0
手机 B:扣 1000 → 余额 -1000
名字: 类型 | ||
x?: string | ||
interface 名字 {…} | ||
List<用户> | ||
function f(){}const f = () => {} |
class 与 extends 是继承,子类拿到父类的东西再改;@名字 是装饰器,本质是贴在函数或类上的一张标签,框架靠扫描这些标签来登记「这个东西是个工具」「这个东西是条命令」;readonly 是只读,as 是「我保证它是这个类型」,! 是「我保证它不是空」。后两个是拿审查员的手按住不说话,用多了等于关掉审查。ctx.shell.run,你得去看装配才知道背后是谁。项目越大,这个跳转越频繁,最后需要一个专门的命令把装配树打出来才看得清。ctx.* | |||
agent/pre-steptools/execute | |||















































































