article: clarify DeepSeek Harness architecture

2026-08-14 15:31:13 +08:00
parent 914387acb6
commit 9671be8129
5 changed files with 210 additions and 200 deletions
@@ -1,7 +1,7 @@
 ---
 {
-  "title": "DeepSeek Harness 通过插件组装 Agent 运行时",
+  "title": "DeepSeek Harness 用插件构建 Agent",
-  "summary": "从一个 greet 工具的完整生命周期出发，分开解释启动装配、请求调用、事件记录和协议边界，再核对 DeepSeek Harness 的架构取舍与公开评测证据。",
+  "summary": "说明 Cordis 如何装配插件，插件如何通信，服务提供方如何选择，以及插件开发、测试和发布如何进行。",
  "date": "2026-08-14",
  "updated": "2026-08-14",
  "topic": "agent-systems",
@@ -14,269 +14,279 @@
 }
 ---
-> DeepSeek Harness 目前适合进入持续观察和隔离试点。在兼容性、发布稳定性和 Agent 任务评测补齐前，它不适合作为组织级默认 Harness。
+> DeepSeek Harness 把模型、工具、会话和执行循环都做成可组合插件。它的架构值得研究，但公开证据目前只支持受限试点，不支持组织级默认采用。
-## 本文解释 DeepSeek Harness 的运行机制和采用边界
+调研冻结在 2026 年 8 月 14 日。目标代码为提交 [`47f943859bef60e4160492346772ded9b24f765a`](https://github.com/deepseek-ai/deepseek-harness/tree/47f943859bef60e4160492346772ded9b24f765a)，该提交与调研日的远端 `HEAD` 一致。本文只评价 Harness 架构、工程流程和公开评测，不评价 DeepSeek 模型能力。
-本文面向理解大模型、API 和基本工具调用，但尚不了解 Cordis 或 Agent Runtime 内部结构的读者。它回答三个问题：DeepSeek Harness 实际如何组装和运行 Agent；它与常见 coding agent 系统的关键差异是什么；当前公开证据是否足以支持观察、试点或正式采用。
+## Cordis 管理插件运行时
-调研冻结在 2026 年 8 月 14 日，目标代码固定为提交 [`47f943859bef60e4160492346772ded9b24f765a`](https://github.com/deepseek-ai/deepseek-harness/tree/47f943859bef60e4160492346772ded9b24f765a)。横向对照也固定到同日抓取的 Codex、Gemini CLI 与 OpenHands 提交。本文不评价 DeepSeek 模型能力，不使用 GitHub star 数作为成熟度证据，也不把不同项目、不同模型、不同任务下的数字拼成排行榜。
+DeepSeek Harness 的命令名是 `dsh`。它是一套 Agent 运行外壳：接收请求，调用模型，执行工具，保存会话，并向 Web、ACP 和 SDK 暴露入口。
-## DeepSeek Harness 是一套 Agent 运行外壳
+dsh 主要使用 TypeScript 编写，运行在 Node.js ESM 环境。TypeScript 让插件作者共享类型，但运行时真正加载的是 JavaScript 模块。插件通常导出 `apply(ctx, config)`，或导出一个 `Service` 子类。[根 package.json](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/package.json) [Cordis 插件教程](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/cordis-tutorial/01-first-plugin.zh.md)
-DeepSeek Harness（命令名 `dsh`）不是一个模型，也不是某个单独工具的封装。它是一个 **Agent Harness**：负责把模型、工具、会话状态、执行循环、权限策略和用户入口组装成一个可以持续运行的 Agent 应用。
+| 概念 | 作用 |
 |---|---|
 | Profile | 选择一种产品形态，例如 Web 或 headless |
 | Bundle | 提供一组可复用的默认插件 |
 | patch | 增加、替换、禁用或删除配置行 |
 | Context | 插件访问 Service、Event 和子插件的入口 |
 | Loader | 按有效配置加载插件模块 |
 | Fiber | 一次插件挂载的运行实例 |
 | Service | 插件向其他插件提供的具名能力 |
 | effect | 与 Fiber 同生共死的注册、监听器或资源 |
 | Agent loop | 在模型、工具和最终回答之间推进一次任务 |
 | SessionEvent | 记录用户消息、模型消息和工具结果等事实 |
-先建立四个最小概念：
+Cordis 负责前八项。它把配置变成一组可管理的插件实例，检查服务依赖，并在配置或依赖变化时卸载、重建相关实例。Agent loop 负责每次请求的执行。两者不在同一层。
-| 名称 | 简要定义 | 在 dsh 中负责什么 |
+## 启动和请求彼此分开
 ![配置先生成插件运行时](/articles/deepseek-harness-architecture-evaluation/dsh-startup-assembly.png)
 启动时，dsh 按顺序合并 Bundle、Profile patch、Harness home patch 和命令行 `--patch`。最终配置由带稳定 `id` 的配置行组成。后层命中同一 `id` 时，会替换该行的完整 `config`，不会做字段级深合并。[CLI 组合参考](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/apps/cli/reference/README.md)
 Loader 为每一行创建 Fiber。Fiber 指一次插件挂载的运行实例，与线程和用户请求无关。它保存配置、父 Context、依赖、状态、effect 和清理逻辑。
 Fiber 常见状态为 `PENDING → LOADING → ACTIVE → UNLOADING`。插件声明 `inject = ['tools', 'shell']` 后，缺少任一 Service 都会停在 `PENDING`。服务出现后才执行 `apply`；服务被替换或消失时，Cordis 会卸载依赖它的 Fiber，再按新依赖重建。YAML 中的先后顺序不决定启动顺序，Service 是否可用才决定。[Cordis 服务教程](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/cordis-tutorial/03-services.zh.md)
 `inject` 只声明硬依赖。插件在某项能力缺失时仍可工作，就不应把它放进 `inject`，而应在使用处调用 `ctx.get('serviceName')`。未挂载 provider 时它返回 `undefined`，Fiber 仍可保持 `ACTIVE`。硬依赖的 provider 被替换时，消费方会重载；可选依赖是否响应变化，则由插件自己的监听和调用方式决定。
 插件通过 `ctx.on()` 注册监听器、通过 `ctx.tools.register()` 注册工具，或通过 `ctx.effect()` 管理连接和定时器。这些操作都会返回或绑定清理逻辑。Fiber 卸载时，Cordis 自动撤销它们。插件树表达的正是这种所有权和生命周期关系。
 ![请求在模型和工具之间循环](/articles/deepseek-harness-architecture-evaluation/dsh-request-flow.png)
 一次请求发生在插件全部就绪之后：
 1. Web、ACP 或 SDK 把输入交给 Agent inbox。
 2. Agent loop 读取会话历史、系统提示和可用工具。
 3. 模型直接回答，或发出结构化工具调用。
 4. Tools Runtime 校验参数、执行策略和工具。
 5. 工具结果回到 Agent loop，模型继续生成。
 6. Agent loop 提交最终消息。
 `SessionEvent` 在这条链路旁边记录事实。它保存用户消息、step、模型消息、工具调用、工具结果和最终回答，用于历史、恢复、fork 和 UI 投影；工具结果仍由 Agent loop 送回模型。[会话持久化](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/session/session-persistence/README.md)
 因此，插件树、依赖图和调用链不能混为一谈：
 | 关系 | 回答的问题 | 示例 |
 |---|---|---|
-| Agent | 能接收目标、调用模型和工具、保留状态并继续工作的程序 | 一个 Agent 由模型、工具、会话和执行循环共同组成 |
+| 插件树 | 谁挂载谁，谁随谁卸载 | Loader 挂载 `tool-bash` Fiber |
-| Agent Harness | 承载 Agent 的运行外壳 | 启动组件、接收请求、管理状态、执行工具并暴露 Web/协议入口 |
+| 依赖图 | 谁必须等待哪项能力 | `tool-bash` 等待 `tools` 和 `shell` |
-| Cordis | dsh 进程内部的插件装配器和生命周期管理器 | 决定有哪些插件、依赖是否满足，以及变化时如何卸载和重建 |
+| 调用链 | 一次请求经过哪些活跃组件 | Agent loop → LLM → Tools Runtime → shell → LLM |
 | Agent loop | 一次任务中的“模型—工具—模型”循环 | 组装上下文，调用模型，执行工具，再把结果交回模型直到结束 |
-dsh 主体是 TypeScript monorepo，运行在 Node.js ESM 环境；冻结提交的根配置要求 Node.js 22.19 以上或 24 以上。Cordis 插件在运行时是由 Node 加载的 JavaScript/TypeScript 模块，通常导出 `apply(ctx, config)`。[根 package.json](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/package.json) [第一个 Cordis 插件](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/cordis-tutorial/01-first-plugin.zh.md)
+## 插件通过三类接口协作
-理解这套架构最重要的前提是把两个问题分开：**启动装配**回答“哪些组件存在、谁依赖谁、谁随谁卸载”；**请求执行**回答“用户的一条消息在已经启动的组件之间怎样移动”。Cordis 插件树主要回答前一个问题，不是用户请求的调用顺序。
+![插件通过三类接口协作](/articles/deepseek-harness-architecture-evaluation/dsh-interaction-contracts.png)
-## `greet` 工具展示了完整的插件生命周期
+Cordis 提供 Service 和 Event。dsh 在此基础上增加 Tool。三类接口解决的问题不同。
-假设现有 Profile 已经包含 LLM、工具注册表、会话、Agent loop 和 Web/ACP/SDK 入口。我们只增加一个虚构示例包 `@acme/dsh-greet-tool`，让模型能够调用 `greet`。下面代码根据官方教程的工具插件写法精简；它只演示插件机制，不是仓库已经发布的包。
+| 接口 | 调用者 | 接收者 | 适合的关系 |
 |---|---|---|---|
 | Service | 另一个插件 | 唯一服务提供方 | 需要返回值的直接调用 |
 | Event | 发布事件的插件 | 零到多个监听器 | 通知、策略和中间件 |
 | Tool | 模型 | Tools Runtime 和工具插件 | 模型发起的结构化动作 |
 **Service 连接直接调用。** 定义包声明服务名和方法，provider 实现它，consumer 通过 `ctx.<name>` 调用。consumer 依赖服务名，不依赖具体 provider 包。一个 Context 内重复注册同名 Service 会直接报错，避免两个实现静默争用。
 **Event 连接松耦合协作。** 发布者只知道事件名、参数和分发语义，不知道谁在监听。监听器通过 `ctx.on()` 注册；它属于 effect，插件卸载时自动注销。
 | 模式 | 执行方式 | 适用场景 |
 |---|---|---|
 | `emit` | 同步通知所有监听器 | 无返回值广播 |
 | `parallel` | 并发执行并等待全部结果 | 相互独立的异步任务 |
 | `serial` | 依次执行，首个有效结果结束 | 异步查询或策略裁决 |
 | `bail` | `serial` 的同步形式 | 同步查询或短路 |
 | `waterfall` | 监听器包装、修改或短路下一层 | 请求改写、guard 和中间件 |
 `waterfall` 的关键是 `next()`。监听器调用 `next()` 才会继续后续链路；不调用就会短路。选择错误的模式会改变执行顺序和失败语义，所以 Event 契约不只有参数类型，还必须说明分发模式。
 **Tool 连接模型调用。** 插件用 `defineTool` 注册名称、描述、输入 Schema、输出 Schema 和 handler。模型只看到公开 Schema。调用进入 Tools Runtime 后，依次经过 `tools/pre-execute`、审批与 guard、`tools/execute`、handler、`tools/post-execute` 和结果固化。[Tools Runtime](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/core/tools/README.md)
 TypeScript 接口只提供编译期检查，运行时会被擦除。交互由四层共同保障：
 1. Definition package 固定名称、方法和类型。
 2. Cordis 检查 Service 唯一性、`inject` 依赖和生命周期。
 3. Tools Runtime 用 Schema 校验模型输入和输出。
 4. 文档、组合测试和 snapshot 检查类型无法表达的行为语义。
 代码里的 `interface` 也不一定都是“给其他插件的 API”。判断方式如下：
 | 定义位置 | 主要对象 | 含义 |
 |---|---|---|
 | `declare module ... interface Context` | Service consumer | `ctx` 上存在什么服务 |
 | `declare module ... interface Events` | 事件发布者和监听器 | 事件名、参数和返回值 |
 | 插件导出的 `Config` | Profile 和部署者 | 这个插件接受什么配置 |
 | `defineTool` 的 Schema | 模型和 Tools Runtime | 模型可以传什么、得到什么 |
 | 普通内部 `interface` | 当前包实现 | 可能只是内部数据结构 |
 只有前四类可能构成跨插件或外部契约。是否公开还要看它是否从 Definition package 导出，并在 subsystem 文档中出现。
 ## 配置决定服务提供方
 官方 shell 链路可以完整说明插件之间怎样协作。它分为 Definition（契约）、Provider（提供方）和 Consumer（使用方）三层。
 Definition 包 `@deepseek-ai/dsh-shell` 定义 `ctx.shell`：
 ```ts
-import type { Context } from '@deepseek-ai/cordis'
+declare module '@deepseek-ai/cordis' {
-import { defineTool } from '@deepseek-ai/dsh-tools'
+  interface Context {
    shell: ShellExecutor
  }
 }
-export const inject = ['tools']
+export abstract class ShellExecutor extends Service {
-
+  constructor(ctx: Context) {
-export function apply(ctx: Context) {
+    super(ctx, 'shell')
-  ctx.tools.register(defineTool({
+  }
-    name: 'greet',
+  abstract resolve(request: ShellExecRequest): ShellExecSpec
-    description: 'Greet the named person.',
+  abstract run(spec: ShellExecSpec): Promise<ShellRunResult>
    parameters: {
      name: { type: 'string', required: true },
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    execute: async ({ name }) => `Hello, ${name}!`,
  }))
 }
 ```
-把它加入 Profile 的 `cordis.patch.yml`：
+Provider 实现这项服务。默认基础 Bundle 在非 Windows 环境挂载 `@deepseek-ai/dsh-bash-sandbox`；`@deepseek-ai/dsh-bash-local` 是另一种实现。两者最终都注册名为 `shell` 的 Service。
-```yaml
+Consumer `@deepseek-ai/dsh-tool-bash` 不导入具体 provider。它只导入 Definition 包中的类型，并声明服务依赖：
- insert:
+
-    - id: greet-tool
+```ts
-      name: '@acme/dsh-greet-tool'
+export const inject = ['tools', 'shell', 'systemPrompt', 'shellEnv']
 ctx.tools.register(defineTool({
  name: 'bash',
  execute: async (args) => {
    const spec = ctx.shell.resolve(args)
    return ctx.shell.run(spec)
  },
 }))
 ```
-这个工具从配置到卸载会经历六个连续阶段。
+默认 Profile 的关键配置是：
-### 配置先决定要挂载的插件
+```yaml
 - id: bash-sandbox
  name: '@deepseek-ai/dsh-bash-sandbox'
-dsh 不会直接把某一个 YAML 文件原样交给 Cordis。它先读取 Profile 指定的有序 Bundle，依次应用各 Bundle 的 patch，再叠加 Profile 自身 patch、Harness home patch 和本次命令行 `--patch`，最终得到一组有效配置行。`greet-tool` 是其中一行；它的 `id` 是稳定身份，`name` 指向要加载的模块。[CLI 组合参考](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/apps/cli/reference/README.md)
+- id: tool-bash
  name: '@deepseek-ai/dsh-tool-bash'
 ```
-如果后层 patch 命中同一个 `id`，该行的 `config` 会整体替换，不是字段级深合并。这里的配置合成只回答“本次启动要挂载什么”，尚未执行任何用户请求。
+这条链路可以读成一句话：Profile 选择 provider，provider 注册 `shell`，Cordis 让 consumer 等待 `shell`，consumer 只调用 `ctx.shell`。因此它没有硬编码 `dsh-bash-local` 或 `dsh-bash-sandbox`。
-### Loader 创建 Fiber，`inject` 决定插件何时启动
+用户可以查看实际挂载结果，但目前没有一条命令直接输出完整的 `Service → Provider → 配置来源` 映射：
-启动器创建根 `Context` 并挂载 Loader。Loader 解析 `@acme/dsh-greet-tool`，为这次插件挂载创建一个 Fiber。Fiber 不是线程或操作系统进程，而是 **一个插件实例的运行时句柄**：它记录父上下文、配置、依赖、状态、注册的 effect 和清理过程。
+1. `dsh --profile web --dump-default-config` 查看 Profile 默认配置。
 2. `dsh --profile web --patch ./extra.yml --dump-config` 查看叠加 patch 后的有效配置和来源注释。
 3. 运行时 plugin inventory 查看模块名、启用状态和 Fiber phase。
 4. 对照 Definition 或 subsystem 文档，确认该模块注册了哪项 Service。
-插件导出了 `inject = ['tools']`，所以 Cordis 会检查名为 `tools` 的 Service 是否已经存在。若不存在，Fiber 保持 `PENDING`，不会调用 `apply`；当 `ctx.tools` 出现后，Fiber 进入 `LOADING`，执行 `apply(ctx)`，完成后进入 `ACTIVE`。因此 YAML 中哪一行写在前面并不决定启动顺序，服务依赖才决定。[Cordis 服务教程](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/cordis-tutorial/03-services.zh.md)
+`dump-config` 解决“配置选择了什么”，inventory 解决“当前启动了什么”。inventory 不保留完整配置来源，也不直接反推 Service provider。这是当前排障能力的明确缺口。[Plugin inventory](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/host/plugin-inventory/README.md)
-`apply` 中的 `ctx.tools.register(...)` 把 `greet` 的名称、参数 schema、返回值渲染和执行函数注册到工具运行时。该注册本身属于一个 effect；Cordis 会记住对应的 disposer，以便插件卸载时自动注销工具。[进入 Harness 教程](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/cordis-tutorial/07-into-the-harness.zh.md)
+## 插件接入遵循公开契约
-### 用户请求进入已经启动的 Agent
+开发新插件应先确定自己使用哪类扩展接口，再查对应的 Definition 和生成文档，无需遍历所有实现包。
-用户通过 Web、ACP 或 SDK 输入“向 Ada 问好”。入口适配器把消息交给对应 Agent 的 inbox。Agent loop 取得待处理输入，从会话日志派生历史，加入系统提示和当前可用工具 schema，然后进入一个 model step。此时 `greet` 已经是工具列表中的一项；Cordis 不再决定模型是否调用它，Cordis 只保证工具已经正确注册。
+| 目标 | 首选接入点 |
 |---|---|
 | 替换一项核心能力 | 实现对应 Service Definition |
 | 监听或改变现有流程 | 订阅 Event 或 waterfall |
 | 增加模型可调用动作 | 注册 Tool |
 | 组合已有能力 | 编写 Profile 或 patch |
 | 接入外部工具服务器 | 使用 MCP client |
 | 从外部控制 Agent | 使用 ACP 或 SDK |
-模型可以直接回答，也可以产生工具调用。这个例子中，模型返回 `greet({"name":"Ada"})`，于是 Agent loop 把调用交给统一 Tools Runtime。
+仓库提供三类索引：`cordis-surface` 文档列出 Service；`event-producer-consumer` 列出事件、分发模式、发布者和监听器；`tool-catalog` 列出模型可见 Tool Schema。高级 Cordis 组合还提供 `cordis_inspect_list/query`，可从当前仓库和运行时服务存储中查询 Service、Event、Tool 和 Slot。它们比遍历每个插件 README 更适合作为入口，但仍需要阅读目标 Definition 的语义和测试。
-### 工具调用经过统一执行管线
+一个正常的自定义插件流程是：
-工具调用不会从模型直接跳进示例函数。标准路径依次经过 `tools/pre-execute`、审批、guard、`tools/execute`、工具本体、`tools/post-execute` 和结果固化。若某项策略返回 `ask`，但当前入口没有可用审批 answerer，系统会拒绝而不是静默放行。[Tools README](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/core/tools/README.md)
+1. 选择 Service、Event 或 Tool，不另造重复接口。
 2. 导入 Definition 包，只依赖公开类型和服务名。
 3. 声明 `inject`，并为配置定义运行时 Schema。
 4. 把监听器、工具和资源注册为 effect。
 5. 用 patch 挂载插件，先检查 `--dump-config`。
 6. 通过 inventory 确认 Fiber 已进入 `ACTIVE`。
 7. 增加单元测试和一次真实组合测试。
 8. 为会影响模型或用户的行为增加 keyless snapshot。
-`greet` 执行后返回 `Hello, Ada!`。Tools Runtime 将结果交回 Agent loop，Agent loop 再把它放入下一次模型请求。模型据此生成最终回答，例如“已向 Ada 问好”。这就是 Agent loop 所负责的“模型 → 工具 → 模型”循环。
+动态 `cordis_define/run` 适合在当前进程里试验，但定义只存在于内存。进程重启后会消失，也不会生成插件包、安装依赖或写入 Profile。正式接入仍要落到插件包、配置和测试。
-### SessionEvent 在旁路记录执行事实
+外部边界与进程内插件也应分开理解：Cordis 是进程内组合机制；Web 使用 HTTP 与 WebSocket；ACP 使用基于 stdio 的 newline-delimited JSON-RPC；SDK 使用项目自己的 line JSON-RPC 2.0；MCP 把外部工具注册进 Tools Runtime。MCP 当前主要桥接 Tool，Cordis 插件仍由进程内模块接口管理。[ACP](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/acp/acp/README.md) [SDK 协议](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/sdk/protocol/README.md) [MCP client](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/mcp/mcp-client/README.md)
-用户消息、step 开始、模型消息、工具调用、工具结果和最终回答会分别追加为 `SessionEvent`。它不是调用链中的“下一台服务器”，也不负责把工具结果转发给模型；它是执行过程中形成的 durable fact。模型历史、resume、fork、轨迹视图、持久化和 UI 投影都从同一事实源派生。[持久化说明](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/session/session-persistence/README.md)
+## 重启取决于变更类型
-如果进程在工具调用期间中断，恢复逻辑会检查日志：工具尚未真正开始，可以安全标记失败；工具可能已经产生副作用但没有留下结果，则标记“结果未知”，提示模型先验证外部状态，避免盲目重试。这解释了事件日志为什么与执行链同样重要，但二者仍是不同关系。
+Profile 和 Harness home 的 `cordis.patch.yml` 会被监听。有效配置变化会事务式重算，相关 Fiber 和 effect 随之卸载或重建，通常不需要重启整个 dsh 进程。
-### 配置或依赖变化会触发自动撤销
+代码变更只有在挂载 `@deepseek-ai/cordis-plugin-hmr` 并覆盖目标路径时才会热替换。Web 客户端插件还需要 `pnpm run dev:web` 重建前端 bundle。生产环境升级 npm 包时，不能假设 HMR 一定覆盖新文件；除非部署明确启用了完整 watcher 链，否则应重启进程。
-Fiber 的主要状态为 `PENDING → LOADING → ACTIVE → UNLOADING`，加载失败时进入 `FAILED`。如果 `tools` Service 暂时消失，已经激活的 `greet-tool` 会卸载自己的 effect，回到等待依赖的状态；服务恢复后重新加载。如果配置行被删除，旧 Fiber 完成清理后进入 `DISPOSED`，不能再次启动。HMR 则卸载旧实例，再根据新模块挂载替代实例。[Cordis 生命周期教程](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/cordis-tutorial/02-lifecycle-and-effects.zh.md) [组合与 HMR](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/cordis-tutorial/06-composition-and-hmr.zh.md)
+HMR 的行为是卸载旧 Fiber、加载新模块，再重建依赖方。前端新模块加载失败时，Fiber 会进入 `FAILED`，不会自动回滚到旧代码。因此关键插件更新仍需保留固定版本、健康检查和回退方案。[组合与 HMR](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/cordis-tutorial/06-composition-and-hmr.zh.md)
-卸载时，`greet` 的工具注册、事件监听、子插件和通过 `ctx.effect()` 管理的定时器或连接都会执行 disposer。插件不需要在每个退出分支手工寻找自己曾经注册的对象。这个“注册与撤销属于同一生命周期”是 Cordis 最核心的工程价值。
+## 改动经过仓库质量链
-完整过程可以概括为：**配置决定挂载 `greet-tool`；`inject` 让它等待 `tools`；Fiber 激活后注册工具；Agent loop 在一次请求中让模型调用它；SessionEvent 记录事实；依赖或配置变化时 effect 自动撤销。**
+![代码改动先经过仓库质量链](/articles/deepseek-harness-architecture-evaluation/dsh-contribution-flow.png)
-## Profile 会被逐层合成为运行中的插件
+仓库同时约束单包行为、真实组合、跨平台兼容和发布产物。
-![启动装配会创建 Fiber 并等待服务依赖；这不是请求调用顺序](/articles/deepseek-harness-architecture-evaluation/dsh-startup-assembly.svg)
+代码按责任分区：`packages/*/*` 保存官方 Service、provider 和 consumer；`apps/*` 保存 CLI 与 Web 产品入口；`docs/` 和 `.agents/notes/` 保存公开契约与设计记录；`scripts/` 和 `.github/workflows/` 保存生成器、门禁和 CI。修改一项能力时，应从所属 package 开始，再同步它的 README、JSDoc、测试和必要的 Agent Note。[仓库布局](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/AGENTS.md)
-这张图只回答启动问题。可以把它拆成配置层和运行时层。
+| 阶段 | 主要要求 |
 |---|---|
 | 本地改动 | 同步代码、README、JSDoc、测试和 Agent Note |
 | 定向验证 | `pnpm run test` 跑单元测试；模型、协议或用户行为增加 `test:snapshot` |
 | 组合验证 | 产品可见插件要经 Loader、应用或进程入口验证，不能只手工构造 `ctx.plugin` |
 | 其他检查 | 按改动运行 `typecheck`、`lint`、`doc-sync`、`build`；真实 provider 才选 `test:e2e` |
 | Git hooks | pre-commit 检查翻译、lint、空白和生成文件；pre-push 执行 typecheck |
 | 内部 PR | 拆分独立改动；非 Draft PR 关联同仓 Issue，填写变更、验证和标签 |
 | CI | static、逐文件 100% coverage、snapshot、Node 兼容、Python、Wine 和 Windows |
 | 合并 | 聚合 `all checks passed`，进入 master 工作流 |
 | 发布 | 先构建和打包全部 DSH 成员，再验证安装产物；发布由 tag 和 environment 人工触发 |
-### Bundle、Profile 和 patch 共同产生有效配置
+逐文件 100% coverage 只是一项仓库门槛。行为质量还依赖真实组合测试和 keyless snapshot。真实 API e2e 使用密钥，只在可信事件运行；fork 和 Dependabot 会跳过，避免泄露 secret。[开发指南](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/development.md)
- **Bundle** 是可复用的默认插件组合，例如一组基础服务和工具。它贡献配置行或 patch，但运行时不会把整个 Bundle 当成不可拆的黑盒。
+公开工作流只能证明 CI 已配置。required checks、reviewer 数量、merge method 和发布 environment 审批名单没有从公开仓库设置中取得，本文将它们标为未知。
 - **Profile** 是一种产品或运行形态的入口。它选择有序 Bundle，并附加自己的 patch，例如组合 Web 或 headless 版本。
 - **Harness home patch** 是用户或部署环境的持久覆盖。
 - **CLI `--patch`** 是本次启动最后应用的临时覆盖。
-合成结果是一组带 `id` 的配置行。每行通常包含 `name`、`config`、`inject` 和 `disabled` 等字段。稳定 `id` 让 Loader 判断一项变化是在更新已有节点，还是删除旧节点后增加新节点。
+本轮按要求没有重新运行 Harness 本地测试。上表描述冻结仓库定义的开发流程，不代表本轮测试已经通过。
-### Context、Loader 和 Fiber 管理运行实例
+## 外部贡献只能独立发布
-根 `Context` 是进程内能力和事件的访问入口；Loader 根据有效配置加载模块，并把每次挂载变成 Fiber。官方教程支持函数、带 `apply` 的对象和 `Service` 子类三种插件形态。`apply(ctx, config)` 只描述插件向当前上下文贡献什么，启动器和 Loader 负责实际挂载。[第一个 Cordis 插件](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/cordis-tutorial/01-first-plugin.zh.md)
+当前 [`CONTRIBUTING.md`](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/CONTRIBUTING.md) 明确说明项目仍处早期，暂不接受外部 Pull Request。官方建议外部开发者创建独立插件仓库，并使用 GitHub topic `dsh-plugin` 供用户发现。
-Fiber 负责把一次插件应用变成可观察、可等待、可失败、可卸载的运行实例。它记录所需 Service 的具体实现；提供方变化时，Cordis 可以比较依赖并只重载受影响的插件，而不是重启整个进程。
+现在可以让 Codex 在 fork 或独立仓库中完成插件、测试、文档和补丁，也可以准备一份可供维护者参考的变更记录。创建本地分支和提交需要用户明确授权；推送 fork 或创建 PR 还需要已登录的 GitHub 身份、目标仓库权限和外部写入授权。官方仓库当前不接受外部 PR，具备工具权限也不能绕过这项政策。
-### Service 和 `inject` 管理服务依赖
+如果目标是扩展 dsh，当前可执行路径是：基于公开 Definition 开发独立插件，锁定兼容提交，完成组合测试，发布自己的包和 `dsh-plugin` 仓库。只有官方重新开放外部 PR 后，主仓贡献链才成立。
-Service 是插件提供给其他插件的具名能力，例如 `ctx.llm`、`ctx.tools` 和 `ctx.sessions`。消费者声明 `inject: ['tools']`，只表示“我需要工具服务”，不绑定某一个具体提供包。部署可以替换 provider，而消费插件代码无需改变。
+## 公开评测仍然不足
-`inject` 是硬依赖：缺失时 Fiber 保持 `PENDING`。可选能力则不应写入 `inject`，而是在使用处通过 `ctx.get(...)` 探测。服务名称共享一个命名空间，这也意味着大型部署必须治理名称、提供方和配置来源。
+本文把“公开 Agent 评测”限定为同时给出任务或数据集、指标与分母、已测量结果。在冻结范围内，没有发现 SWE-bench、Terminal-Bench、AgentBench 或 GAIA 等 Agent 任务的公开成绩。
-## 一条消息会在已经启动的组件之间流转
+[`BENCHMARK.md`](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/BENCHMARK.md) 只说明怎样用 Python SDK 启动 minimal agent，并为独立任务设置 workspace 和 session ID。它提供评测接入口，没有给出评测结果。
-![一次 greet 请求会在已经启动的组件之间流转，SessionEvent 位于记录旁路](/articles/deepseek-harness-architecture-evaluation/dsh-greet-request.svg)
+仓库包含工程评测资产：
-这张图只回答运行问题。系统已经完成装配，因此请求链中不再出现 Profile、Bundle 和 Loader：
+| 资产 | 指标 | 当前证据 |
 1. Web、ACP 或 SDK 入口把用户输入交给 Agent inbox。
 2. Agent loop 取得输入，组装系统提示、历史和工具 schema。
 3. Agent loop 调用 LLM；模型可以直接回答或请求工具。
 4. 工具调用进入统一 Tools Runtime，经过策略、审批、guard 和执行阶段。
 5. 工具结果回到 Agent loop，再进入下一次模型 step。
 6. 模型生成最终消息，Agent loop 提交结果并在没有待处理工作时回到 idle。
 dsh 同时存在两类容易混淆的“事件”。`SessionEvent` 是写入会话日志的 durable fact，承担重建、恢复和投影；`agent/pre-step`、`agent/request`、`tools/pre-execute` 等 live event 或 waterfall 是运行时扩展点，插件可以监听、修改、放行或短路当前过程。前者回答“发生过什么”，后者参与“现在怎样继续执行”。
 ## 插件树、依赖图和调用链表示三种不同关系
 | 关系 | 它回答的问题 | `greet` 例子 |
 |---|---|---|
-| 插件父子与生命周期 | 谁由谁挂载，父节点卸载时谁一起清理 | Loader 挂载 `greet-tool` Fiber；删除配置时旧实例被清理 |
+| Web 长历史 runner | 侧边栏、长对话、轨迹和 soak 的 wall time、p95 等 | 有脚本，未发现正式结果 |
-| Service 依赖 | 谁必须等待谁，提供方变化时谁需要重载 | `greet-tool` 通过 `inject` 等待 `tools` |
+| reasoning chunk 压力 | 10 万 chunk；主线程和交互延迟门槛 250 ms | 有断言，未发现官方汇总 |
-| 请求调用 | 一条消息在运行时经过哪些已经激活的组件 | Agent loop → LLM → Tools → `greet` → LLM |
+| CI runner benchmark | 不同平台和 core 数下的检查耗时 | 用于 CI 容量，与 Agent 能力评测无关 |
 | 单元、snapshot、e2e | 类型、行为、组合和真实 API 链路 | 证明工程链路，不证明任务成功率 |
-所谓“Cordis 插件树”首先是一套运行实例的所有权结构；再叠加 `inject` 后，形成服务依赖图。一次请求的调用链则发生在这些实例都准备好之后。三者可能涉及相同插件，但箭头含义不同，不能用一棵树同时表示。
+缺失的评测至少包括：固定模型和预算下的任务成功率、工具调用正确率、权限拒绝与恢复率、断点恢复正确率、长会话质量、插件组合兼容性，以及相同任务上的对照 Harness。没有这些结果，就不能从高覆盖率推导出 Agent 效果。
-## Web、ACP、SDK、MCP 和 Cordis 连接不同边界
+## 当前只适合受限试点
-![Web、ACP、SDK、MCP 和 Cordis 连接不同边界](/articles/deepseek-harness-architecture-evaluation/dsh-protocol-boundaries.svg)
+| 阶段 | 当前判断 | 条件 |
 先看进程边界，再看协议名称：Web、ACP 和 SDK 把请求从外部送入 Agent；MCP 把外部工具送入 Tools；Cordis 位于 dsh 的 Node.js 进程内部，负责组件装配，不是远程协议。
 | 接入面 | 连接方向与载体 | 解决的问题 |
 |---|---|---|
-| Cordis 插件 | dsh 进程内的 ESM 模块：`apply`、Service、Event、effect | 增加或替换模型、工具、会话、策略、loop 和 UI 组件 |
+| 架构观察 | 通过 | 源码和文档足以解释主要机制 |
-| Web | 浏览器 → dsh 为 HTTP POST；dsh → 浏览器为 WebSocket 事件 | 产品 UI、会话展示和交互操作 |
+| 受限试点 | 有条件通过 | 固定提交、隔离 workspace、低风险任务、明确权限和回退 |
-| ACP | 外部 Agent Client ↔ dsh，newline-delimited JSON-RPC over stdio | 创建会话、发送 prompt、取消和一次性权限回答的基线自动化 |
+| 组织级采用 | 不通过 | 缺少稳定发布、迁移承诺、安全审查和目标任务评测 |
 | Python / TypeScript SDK | 评测器或程序 ↔ dsh，项目自有 line JSON-RPC 2.0 over stdio | 批量任务、自动化和 benchmark runner |
 | MCP client | dsh ↔ 外部 MCP Server，stdio 或 Streamable HTTP | 发现外部工具并注册为 `mcp__<server>__<tool>`；当前只桥接 Tools |
-Profile、Bundle 和 patch 不在表中，因为它们是部署配置方式，不是通信协议。ACP 也不等于完整 Web 产品面：它只暴露自动化基线；SDK 线协议当前没有版本协商和单 prompt 取消；MCP 当前不桥接 Resources 和 Prompts。[ACP 协议契约](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/acp/acp/README.md) [SDK 线协议](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/sdk/protocol/README.md) [Web Connection](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/client/connection/README.md) [MCP client](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/mcp/mcp-client/README.md)
+DeepSeek Harness 当前标注 Developer Preview，会主动发生兼容性变化；会话格式仍为 v0；调研日未见正式 GitHub Release。这些事实不否定架构价值，但会放大插件兼容、会话迁移和运维成本。
-## DeepSeek Harness 的主要价值来自扩展边界和生命周期管理
+合理的下一步是选择一个低风险任务做隔离试点：固定版本；保留 `workspace-write + ask`；逐项确认 shell、文件、Web 和外部服务是否真的进入审批策略；保存有效配置和 plugin inventory；把升级、会话导出和插件回退都当作可能失败的步骤。
-1. **最值得关注的是扩展边界。** dsh 允许替换的不只包括工具和模型适配器，还包括会话、Agent loop、工具注册表、策略、持久化和 UI。Profile、Bundle 与 patch 可以逐层改写配置，比“在固定 Agent 核心外围加插件”更激进。
+只有在固定任务集上取得可复现结果，并补齐安全、发布和迁移责任后，才应重新讨论默认采用。
 2. **Cordis 解决的是组合变化。** Fiber、Service、`inject` 和 effect 让插件能随配置与依赖变化安全地加载、等待、卸载和重建；它并不替代 Agent loop。
 3. **Agent loop、工具管线和事件日志形成执行主链。** loop 决定下一步，Tools 执行动作，SessionEvent 保留可恢复事实；三者职责分开。
 4. **工程质量证据多于效果证据。** 仓库有高覆盖率单元测试、keyless snapshot、真实 API e2e 入口、Web 性能/压力 runner 和 CI runner benchmark；但在冻结范围内没有发现公开的 Agent 任务成功率成绩。
 5. **现在的合理动作是观察或隔离试点。** Developer Preview、兼容性主动破坏、会话格式 v0、无正式 GitHub Release，以及缺少可复现的目标任务评测，都会阻断生产级采用。
-## 这种设计同时带来可替换性、可恢复性和安全边界
+## 结论基于冻结源码
 ### Profile 和插件可以替换运行时结构
 许多 Agent 产品把模型、会话和 loop 固定在核心，只开放工具、MCP、Skill 或 Hook。dsh 把替换面进一步下沉：可以用不同 Profile 组成 Web 或 headless 产品，也可以替换会话后端、工具策略、模型适配器乃至 Agent loop。对于需要研究不同上下文策略、执行器、持久化或交互面的团队，这能减少 fork 主干的压力。
 代价是配置态数量迅速增加。某个行为可能来自 Bundle 默认值、Profile patch、home patch、命令行 overlay 或运行时插件；“一切可替换”会把复杂度从代码分支转移到组合、来源追踪和兼容性验证。官方 plugin inventory 甚至明确说明它不记录条目由哪个 Bundle、Profile 或 override 引入，也不能直接修改插件，这意味着生产排障仍需要更强的配置溯源工具。[Plugin inventory](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/host/plugin-inventory/README.md)
 ### 事件日志让执行、恢复和观察共享事实
 事件溯源避免了“模型看到的历史、UI 显示的历史、持久化记录”长期漂移。工具调用、结果、权限变化和 turn 边界都可以成为 durable fact；模型上下文只从带 surface 语义的事件派生。这个约束对恢复尤其重要，因为系统可以识别未闭合的调用并合成明确错误状态。
 但事件溯源不能自动解决格式演进。当前 `SESSION_FORMAT_VERSION = 0`，持久化协调器会拒绝无法升级的旧格式或更新格式；在 Developer Preview 阶段，这意味着长生命周期会话不应被当作稳定资产。试点需要固定提交，并接受迁移、导出或放弃历史的可能性。
 ### 安全策略可以组合，但不会自动覆盖所有工具
 默认权限预设把 `workspace-write + ask` 与 `danger-full-access + never` 组合成两个选择，审批缺失时 fail-closed；这比把“是否询问”散落在每个工具内更清晰。[Permission presets](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/subsystems/permission-presets.md)
 需要注意的是，策略 seam 只有在工具主动接入或部署增加 `tools/pre-execute` 策略时才生效。官方 Web 工具说明明确指出，它的两个工具本身不会请求 `ctx.approval`，也没有持久 URL 或域名授权；需要确认的部署必须另外挂载策略。[Web tool](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/web/tool-web/README.md) 因此，不能仅凭“系统有 approval 与 sandbox 包”推断所有能力都受到同等保护。
 ## 使用和扩展 DeepSeek Harness 仍有明显门槛
 体验入口很短：官方给出的 Web 启动方式是 `npx @deepseek-ai/dsh web`，默认监听 `127.0.0.1:3080`。如果从源码开发，则需要 Node.js `^22.19.0` 或 `>=24.0.0`、仓库锁定的 pnpm 11.7，完成依赖安装和构建后再通过 `pnpm dsh web` 启动。[README](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/README.md) [开发指南](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/development.md)
 扩展有两条路径。已有能力的轻量改造，可以先用 `dsh --profile web --dump-config` 查看最终配置，再按配置行 ID 用 patch 整体替换；新增模型、工具、策略、会话后端或 loop，则需要实现 Cordis 插件，把它加入 Bundle/Profile，并同时处理服务依赖、事件或 waterfall、effect 清理和测试。后者不是“放入一个脚本即可”的低成本插件：当前项目仍处于 Developer Preview，配置 inventory 又不能完整回答某一行由哪层引入，因此试点需要固定提交、锁定插件版本，并为每个自定义插件建立组合测试和升级回滚检查。
 ## DeepSeek Harness 暴露了更多运行时替换点
 下表比较的是同一生命周期上的架构边界，不是产品效果排名。冻结版本分别为 [Codex `053dda6`](https://github.com/openai/codex/tree/053dda6b897887c0bbd8efa5d4952a4380dbb5e4)、[Gemini CLI `1ac3377`](https://github.com/google-gemini/gemini-cli/tree/1ac3377395868295e128b96726d605a900b5946b) 与 [OpenHands `4f465f3`](https://github.com/All-Hands-AI/OpenHands/tree/4f465f3ccada5271a3bbe4a0148941b0c40d243b)。
 | 维度 | DeepSeek Harness | Codex | Gemini CLI | OpenHands |
 |---|---|---|---|---|
 | 首要形态 | Web、headless、SDK/ACP 由 Profile 组合 | 本地 coding agent，CLI/IDE/App 共用核心与 app-server | terminal-first CLI，CLI 与 core 分包 | Agent Server/Runtime 加 Web/Canvas 与云服务 |
 | 扩展边界 | 模型、会话、loop、工具、策略、UI 都可配置替换 | Skills、MCP、Hooks、工具和客户端协议扩展，核心 loop 更集中 | Extensions、MCP、Hooks、Policy Engine、工具注册 | Skills/MCP/工具集、Agent SDK、Runtime/Cloud 服务 |
 | 会话语义 | append-only SessionEvent，history 派生，支持 resume/fork/repair | thread/turn/item 持久化，支持 resume/fork/interrupt | CLI/core 管理会话历史与 checkpoint/resume | Conversation/Event 由 Agent Server 管理，Runtime 承担执行状态 |
 | 工具安全 | guarded pipeline；ask 缺通道 fail-closed；沙箱与审批可组合 | OS sandbox、approval policy 与权限 profile 是产品核心能力 | sandbox、policy engine 与交互批准围绕 terminal tool | 以隔离 Runtime/sandbox 与服务端执行边界为主 |
 | 主要取舍 | 最大可替换性，同时承担配置态和插件兼容复杂度 | 集成一致性与产品化成熟度 | 终端体验、Gemini 集成与扩展生态 | 隔离运行环境、长任务与服务化编排 |
 dsh 试图把 Harness 自身变成可动态组合的研究与产品平台。如果团队只需要一个成熟 coding agent，深度可替换性未必能抵消兼容与运维成本；如果团队正在建设多种执行器、策略、持久化或交互形态，它提供了值得借鉴的边界设计。
 ## 公开证据尚不能证明 Agent 任务效果
 ### 冻结范围内没有公开的 Agent 任务成绩
 本文把“公开 Agent 能力评测结果”限定为同时具有明确任务或数据集、指标与分母、已测量结果。按此口径，在冻结提交的 README、`BENCHMARK.md`、文档、工作流和相关文件中，没有发现 SWE-bench、Terminal-Bench、AgentBench 或 GAIA 等任务的公开成绩。
 [`BENCHMARK.md`](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/BENCHMARK.md) 只有一条运行说明：通过 Python SDK 启动 `jsonrpc-agent` minimal variant，并为独立任务使用不同 workspace 与 session ID。它是 benchmark 接入口，不是评测方案或成绩。这个结论严格限于 2026 年 8 月 14 日的冻结仓库与官方公开页面；准确表述是“在该范围内未发现”，不是“项目从未评测”。
 ### 仓库包含三类工程评测资产
 | 类型 | 任务与指标 | 是否有仓库内正式成绩 | 能说明什么 |
 |---|---|---|---|
 | Web 长历史性能 | 1,000 个侧边栏会话、500-turn 历史、2,100 行轨迹、100-turn soak；记录 wall/task/script/style、首 chunk、p95 等 | 未发现提交的正式运行结果 | Web UI 在高基数历史下的性能分析能力 |
 | reasoning chunk 压力 | 100,000 个 chunk；最大主线程延迟与计划交互延迟门槛均为 250 ms | runner 有断言，未发现官方发布结果 | 流式 reasoning 渲染的响应性 |
 | CI runner benchmark | 不同 Linux/Windows core 数下的 typecheck、文档构建和聚合 gate | 未发现结果汇总 | CI 容量与拓扑选择，不是 Agent 能力 |
 仓库还包含单元测试、keyless snapshot、Web Chromium snapshot、真实组合测试与可选真实 API e2e。开发文档强调 CI 对 package source 执行逐文件 100% coverage，但也明确指出 coverage 只是必要条件，不能单独证明行为质量。[开发指南](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/development.md)
 ### 本地验证只能说明工程链路可以运行
 冻结提交曾在 macOS arm64 上完成 typecheck；针对 Agent loop、工具管线、会话持久化和用户审批的 35 个测试文件、890 个用例通过；10 万 chunk 压力用例在补齐 Playwright Chromium 后通过，一次观测到的最大主线程延迟约 40.4 ms、计划交互延迟约 1.4 ms，低于仓库 250 ms 门槛。
 这些结果只证明该提交在单台机器上的构建合约、定向组件测试与一次前端压力复现。没有运行真实模型任务、全量测试、Docker、跨平台矩阵或同任务对照；长历史性能脚本没有完成。因此它们不能填补 Agent 任务效果证据的缺口，也不应升级为官方成绩。
 ## 当前证据只支持观察和隔离试点
 | 门槛 | 当前状态 | 证据 | 判断 |
 |---|---|---|---|
 | 观察 | 文档、源码和入口足以形成机制判断 | 架构文档、源码、冻结提交 | **通过** |
 | 隔离试点 | 需要固定版本、一次性 workspace、低风险任务、明确权限与恢复方案 | 构建/定向测试通过；权限与恢复机制可审计 | **有条件通过** |
 | 组织级采用 | 需要兼容/迁移承诺、目标任务复现评测、安全审查、升级回滚和责任人 | Developer Preview、格式 v0、无正式 Release、未发现公开 Agent 任务成绩 | **不通过** |
 截至调研日，官方 README 明确标注 Developer Preview 并预告兼容性破坏；[GitHub Releases](https://github.com/deepseek-ai/deepseek-harness/releases) 页面没有正式 Release。版本与发布状态本身不否定技术价值，但会显著增加升级、会话迁移和插件兼容成本。
 如果进入隔离试点，建议固定 `47f9438` 或新选定提交，使用可丢弃 workspace，保留默认 `workspace-write + ask`，逐项确认 Web、文件、shell 与外部服务能力是否真正接入审批策略，并把会话导出与版本切换当作可失败项。试点只能回答“它是否适合我们的具体任务和运维方式”，不能用一次成功演示替代采用评审。
 ## 团队现在适合进行受限试点
 现在可以把 dsh 纳入架构观察清单，并安排一个受限试点；不应直接替换现有生产 Harness。观察重点应放在三处：插件树对多产品形态的复用是否真的降低 fork 成本；事件日志能否让恢复、审计和 UI 投影保持一致；工具策略在自定义插件和 Web 能力接入后是否仍然 fail-closed。
 从“试点”升级到“采用评估”至少要看到三项变化：项目给出更稳定的发布与迁移政策；在固定模型、工具、预算和任务集下产生可复现的目标任务结果；团队完成插件供应链、权限、数据与回滚审查。任一项缺失，都应继续停留在观察或隔离环境。
 ## 本文结论来自冻结源码和公开资料
 - 目标仓库：[deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)
 - 冻结提交：[`47f943859bef60e4160492346772ded9b24f765a`](https://github.com/deepseek-ai/deepseek-harness/tree/47f943859bef60e4160492346772ded9b24f765a)
- 主要官方文档：[README](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/README.md)、[Architecture](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/architecture.md)、[Persistence](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/session/session-persistence/README.md)、[Tools](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/core/tools/README.md)、[Benchmark entry](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/BENCHMARK.md)
+- 主要资料：[README](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/README.md)、[Architecture](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/architecture.md)、[Tools](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/core/tools/README.md)、[Persistence](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/session/session-persistence/README.md)、[Development](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/development.md)、[Contributing](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/CONTRIBUTING.md)
- 证据等级：官方声明与源码文档、冻结源码、仓库测试/CI、边界执行结果、明确标注的推断；不同等级不互相替代。
+- 已核验：冻结源码、官方文档、仓库测试与 CI 配置、调研日远端 `HEAD`
- 未核验：真实模型端到端效果、生产负载、跨版本迁移、第三方插件生态质量、组织级安全与运维成本。
+- 未核验：真实模型端到端效果、生产负载、在线保护设置、跨版本迁移和第三方插件质量