摘要：DeepSeek Harness（dsh）是一个以"一切皆插件"为架构信条的 Agent 开发框架，其底层由仅约 2000 行 TypeScript 的元框架 Cordis 承担"微内核"角色。本文以完整源码索引为证据，逐一剖析 Cordis 的插件规范五要素——Plugin、Context、Service、Typed Events、Effects——在 Harness 中的真实落地形态，并提炼出六个关键架构实践：能力接缝三层模式、事件即系统契约、双端跨界复用、运行时自我修改、声明式组合语言、以及"插件结构即工程结构"。文章最终论证：Cordis 之于 dsh，不仅是"软件总线"，更是让 Agent 系统获得可演化、可自举能力的"进化底座"。

一、一个 2000 行内核，如何撑起一个 Agent 操作系统？

It uses an architecture where everything is a plugin, powered by Cordis.

二、微内核策略：为什么 DeepSeek 选择"vendor 而非依赖"

2.1 vendor 目录：九个包的"框架族"

2.2 内嵌而非引用的深层原因

• 深度定制：作为整个系统的微内核，任何语义调整（如作用域链、生命周期时序）都会波及全部 54 个包组。vendor使DeepSeek可以像维护自家代码一样修改内核，并通过rescope脚本与verify-runtime-closure等门禁保证一致性。
• 版本钉死与供应链控制：pinned source +pnpm-workspace.yaml的 overrides/patches，配合verify-cordis-config.ts等源码门禁，确保"内核不变式"在每次构建中都被校验。
• 生态基座：vendor的9个包构成了完整的"框架族"——schemastery为每个插件提供 Schema 校验，loader/include提供声明式组装，hmr提供热更新。DeepSeek 不是重新发明轮子，而是把轮子焊进自家底盘。

三、插件规范五要素：从概念到Harness的实证落地

3.1 Plugin 与 Plugin Registry：54 个包群的注册表

3.2 Context：插件的"工作台"，以及被 dsh 扩展出的"作用域链"

• dsh-agent：提供 "process-local initiator scope"——每个Agent在其作用域内启动；
• dsh-subagent-spawn-in-process/dsh-subagent-fork-in-process创建"全新的子作用域"或"继承父历史的作用域"；
• 子代理、终端、持久化shell（ctx.terminals的 "exact-Agent ownership"）都以作用域为单位声明归属。

3.3 Service：能力接缝（Capability Seam）

• 第①层（Definition）声明"能力存在什么"，通常作为一个注册表/契约插件存在；
• 第②层（Provider）通过ctx注册具体实现——一个能力可以有多个并存的实现（如 bash 有 local 与 sandbox 两种执行器）；
• 第③层（Tool）则是"模型可见面"，把内部服务调用翻译为模型可调用的工具 schema。

• dsh-bash-sandbox "wraps argv through ctx.sandbox"——shell 执行器注入沙箱服务；
• dsh-lsp-stdio" over ctx.fs + ctx.subprocess"——LSP 后端同时注入文件系统与子进程两个服务；
• dsh-tool-bash-persistent "over one owner-scoped persistent ctx.terminals shell"。

3.4 Typed Events：事件的"系统词汇表"与横切关注点

• dsh-agent：agent/*事件词汇表；
• dsh-tools：工具执行的pre / execute / post-execute事件；
• dsh-fs：fs/*策略事件；
• dsh-compaction：compaction/*事件词汇表；
• dsh-command-feedback：feedback/record事件；
• dsh-llm-retry：通过agent/request-error瀑布实现提供商级重试策略。

3.5 Effects 与 Fiber：生命周期状态机与"零垃圾"卸载

• 热更新：vendor 的cordis-plugin-hmr+dsh-client-hmr（浏览器端插件热重载）、dsh-app-boot的"config-only HMR"——只有副作用可逆，热重载才可能安全；
• 有序关停：apps/cli的process-shutdown.ts是"有界/升级式进程退出控制器"（SIGINT=130、SIGTERM=0）；
• 确定性清理：dsh-terminal明确要求 "awaited cleanup"（等待式清理），dsh-session-persistence有 "write coordination"。

四、Cordis机制在Harness中的具体工程形态

4.1 服务定义与提供者分离 → 可替换性

4.2 声明式组合语言：cordis.yml、Profile、Preset与Patch 层

• apps/cli 支持--profile、--patch、--dump-config，profile-boot.ts负责"解析 profile、叠加 patch 层、挂载插件树"；
• apps/cli/config/agent-presets/ 内置四个 Agent 预设（code/、cordis/、minimal/、standard/），每个预设 =agent.cordis.yml+preset.yml；
• vendor 的cordis-plugin-include提供配置包含与补丁叠加（applyEntryPatches、!!js方言）；
• dsh-app-boot 实现"快照感知配置、settle-tree 启动"，配置变更可通过 HMR 生效。

4.3 双端插件化：同一个插件模型跨越进程边界

• 宿主端（packages/host/）：dsh-host-apiproxy（类型化 API 网关）、dsh-host-webserver、dsh-host-frontend-static、dsh-host-directory-picker（原生/浏览/自适应三种后端）——全是 Cordis 插件；
• 浏览器端（packages/client/，@deepseek-ai/dsh-client-*）：dsh-client-web是"两阶段启动（模块面 + 插件面）"的浏览器内核；dsh-client-modules模拟 Node的ESM loader；dsh-client-hmr在浏览器里实现插件热重载；数十个dsh-client-ui-*组件本身就是浏览器端插件；
• 类型化RPC：typert/家族（generator/loader/registry/protocol）通过@Remote/@RemoteScope生成跨端服务描述，使宿主端ctx.typert Gateway与浏览器端ctx.remote的服务调用类型安全。

4.4 运行时自我修改：把"插件系统"交给 Agent 自己

• dsh-cordis-host-runner：定义注册表 +node:vm沙箱 + "request-run 往返"（ctx.dynamicCordisRunner）——把 Agent 写出的插件定义在 VM 中求值并实时挂载；
• dsh-cordis-client-runner：浏览器端对应物，把定义求值为真实浏览器插件；
• dsh-tool-cordis：对模型暴露"运行时检查 + 动态包"工具；
• dsh-client-ui-cordis：帧级面板与只读定义卡片。

4.5 可观测与不变式：插件结构即工程结构

• dsh-invariants：（runtime-diagnostics/invariants）提供可配置不变式注册表（ctx.invariants），每个包都发布一个./invariant伴生模块——插件结构成了挂载运行时断言的统一位置；
• scripts/ 中约 150 个门禁脚本，包括verify-package-invariants.ts、verify-runtime-closure.ts、verify-cordis-config.ts等，在CI层校验"插件世界"的完整性；
• 生成式文档（gen-cordis-catalog.ts、gen-cordis-api.ts、gen-module-graph.ts）直接从源码产出docs/cordis-api/、config-catalog.md、module-graph.md——文档结构由插件结构自动推导，杜绝文档漂移。

4.6 测试与演示即插件：test-support 与 examples

五、收益分析：插件化构建兑现了哪些架构承诺

六、代价与挑战：硬币的另一面

• vendor的维护成本：18 处本地修改 +rescope-vendor.ts+ 同步流程，意味着每次上游 Cordis 升级都是一次移植手术；索引明确标注 "Do not edit vendor/*/src/ casually"。
• 兼容性风险：0.1.0-rc.5 处于 developer preview，索引声明 "compatibility-breaking changes expected"——插件契约（Service 签名、事件词汇表）的任何变更都会波及 54 个包。
• 复杂性的上移：微内核把复杂性从内核转移到了组合层——composition.md（生成的 dsh-base 插件树 Mermaid 图）、verify-runtime-closure.ts、knip.json死代码分析等，都是为驾驭这种组合复杂性而生的"制动器"。
• 认知门槛：dsh 用docs/cordis-primer.md（Cordis教程）与 7 章cordis-tutorial（01-first-plugin → 07-into-the-harness）来降低插件作者的入门成本——这本身就说明"插件心智"是需要系统培养的。

七、结论：Cordis之于dsh，是"软件总线"，更是"进化底座"

• Context与Fiber：定义了组件的边界与生命周期；
• Plugin Registry：是管理所有组件的目录；
• Service与inject：定义了组件间"接口/实现/依赖"的语法；
• Typed Events：定义了组件间"通知/响应"的语法；
• Effects：定义了"可逆性"这一让热插拔与自修改成为可能的根本属性。