架构
DeepSeek Harness 的轻量架构速览——Cordis 插件框架、Profile 与 Bundle、事件扩展点。这是官方 architecture.md 的精简中文导读——动手改 packages/ 之前请先读官方原文。
总览
一个正在运行的 dsh 是启动时按有序层次组合出的插件树。没有特权核心：模型适配器、工具注册表、会话日志、Agent 循环本身都是插件，在共享的 Cordis 上下文上注册服务、类型化事件与可逆副作用。
Cordis
Cordis 是 DSH 底层的插件框架。注册是随插件卸载而回滚的副作用——这就是「一切皆插件」不只是口号的原因：挂载一个插件即可扩展 DSH，任何部件都可以从配置中替换。
Profile 与 Bundle
- Profile（配置档） —— Harness home 中保存的命名组合：列出叠加的 bundle、持有外部插件与用户自己的
cordis.patch.yml。web与headless内置为模板。 - Bundle（包） —— Cordis 配置行及其代码的分发格式。每个 bundle 在
package.json的dsh字段中自我声明（dsh.profile列出 bundle；dsh.bundle指向 patch 文件）。
dsh-base 是每个 profile 的第一层（模型适配器、工具、持久化、沙箱与审批策略、设置、凭据、遥测）；dsh-web-app 增加浏览器应用；dsh-headless 增加无服务器的单次运行器。层次按序应用：profile 列出的每个 bundle → profile 的 cordis.patch.yml → home 级 patch → 任意 --patch 覆盖层。
查看你自己的插件树
(打印出的每一行都可以用你自己的 patch 替换)
$
这是理解组合机制、原型化插件最快的方式。
核心包
| 包 | 负责 | ctx 键 |
|---|---|---|
core/session | 追加式 SessionEvent 日志与内存存储 | ctx.sessions |
core/system-prompt | 提示词分段与工具 schema 组装 | ctx.systemPrompt |
core/tools | 作用域工具注册表与受保护的执行管线 | ctx.tools |
core/agent | Agent 接口、实时注册表与 agent/* 事件 | ctx.agents |
core/agent-loop | 实现该接口的默认驱动 | ctx.agentLoop |
core/scope | 按 agent 的作用域注册原语 | 库，无键 |
llm/llm | 消息与流词汇 + 适配器接缝 | ctx.llm |
事件是扩展点
事件是插件接入的方式——选择正确的事件域，是大多数改动中的第一个决策：
- 会话事件 —— 追加到日志并通过
session/event广播的持久事实。当事实必须在重载后存活时使用。 - Agent 事件（
agent/*）—— 携带活的Agent：收件箱、step、状态、请求、校验、续跑。用于观察或拦截进行中的工作。 - 能力事件 —— 把策略与适配器挂到接缝（
fs/*、tools/*、telemetry/*）上，无需导入主循环。
回合流程（turn flow）
step 是一次模型请求加上它调用的工具。turn 是零个或多个 step：在第一个输入被认领前打开，在无欠账时关闭。
认领下一步输入 + 一条排队消息
组装提示词分段 + 工具 schema
step/start
agent/request -> llm/stream -> assistant/chunk* -> assistant/message
tool/call* -> tools/execute -> tool/result*
step/end
turn/end
turn/*、step/*、user/message、assistant/*、tool/* 是持久会话事件；其余是实时扩展点。瀑布事件（agent/pre-step、agent/request、llm/stream、三个 tools/*）的监听者必须调用 next() 让权；agent/turn-stopping 是串行的，没有 next()。
会话日志与「模型可见即已记录」
会话日志是模型所看到的上下文的来源。deriveMessages() 从它投影模型历史，原始 assistant/chunk 事件保留回放与 UI 保真。Fork、续跑、转录、遥测与持久化都派生自这条流。不变量：模型可见即已记录——任何到达模型请求的东西都必须能从日志重建。
能力接缝（capability seams）
接缝 是可替换的能力，包含三个角色：声明接口的 Service Definition、实现它的 Service Provider、以及使用它的 Consumer（通常是面向模型的工具）。换一个 provider 就能改变整个产品：文件系统与子进程 provider 共享同一个执行世界，把它们的接缝指向远程沙箱，Bash、PTY 与 LSP 会一起迁移。
新行为放哪里
| 目标 | 机制 |
|---|---|
| 新增模型 provider | 在 ctx.llm 注册适配器 |
| 新增面向模型的能力 | 在 ctx.tools 注册；其 schema 加入提示词组装 |
| 新增 shell 执行 | 注册 ctx.shell 后端 |
| 新增人类命令 | 在 ctx.commands 注册；不经过模型回合直接分发 |
| 新增后台工作 | 在 ctx.jobs 注册；job_* 工具收集或停止它 |
| 新增文件系统访问或策略 | 注册 ctx.fs provider 或监听 fs/* 事件 |
下一步
- 什么是 DeepSeek Harness？ —— 从零理解这个运行时。
- 插件开发 —— 写出你的第一个插件。
- 插件注册表 —— 收录 490+ 个真实仓库。
- 更新日志 —— 跟踪版本变化。
问题或建议？官方 Discussions 是项目规范的支持渠道；Discord 里能找到活跃的社区成员。dsh.so 本身欢迎通过提交插件或反馈改进。