English summary · 项目概览 · 源码索引 · 参与贡献
从源码理解 Agent Harness：怎样组合能力、执行任务，以及留下可复核的记录。
DeepSeek Harness Analysis 是面向 Agent 系统开发者、技术决策者与开源贡献者的中文证据链手册。围绕 DeepSeek Harness，它提供五个核心章节、六篇专题深挖和框架／编码 Agent 产品比较，帮助读者把架构解释与具体实现对应起来。
本仓库保存分析文档、证据记录和校验脚本；运行 DeepSeek Harness 应用请使用上游仓库。本手册是由 yang0228 维护的独立项目，不隶属于 DeepSeek，也不是其官方文档、支持渠道或安全响应方。
从这里开始：在线阅读，无需安装 · 本地核验证据，可选 · 运行上游应用。
固定分析基线： DeepSeek Harness commit f3803c96974ad4a94195fb97e5c637e9c2a3afe3。上游事实、作者推论和限定条件均围绕这一源码快照组织；它不代表上游当前版本。核验日期：2026-10-28；源码版本：0.2.2-alpha.2。完整元数据见 evidence/baseline.json，变更见本次升级记录。
先看应用怎样装配，再看运行时怎样协作。Application Profile 组合应用，Agent Preset 组合每个 Agent 的能力；模型适配器、Agent loop、工具服务与 Session Event Log 都由插件提供。Desktop 在独立 Host 中复用 Web 应用。
图中的分组表示组合与协作关系，不表示进程或安全隔离；可替换能力也不意味着运行中的组件可以任意热替换。继续阅读组合与生命周期架构、能力与组合归属和应用与 Session 的组合层；Desktop 的启动、认证和端口见独立 Host。
以“读取一个文件并解释内容”为例：用户提交任务，模型选择工具，Harness 执行调用并记录结果，模型再根据结果继续回答。下图展开一次工具调用成功、随后模型给出最终答复的简化路径。
- Turn 是一次任务推进的外层单位，Step 包含一次模型请求及其工具处理。 一个 Turn 可以有零个或多个 Step，具体条件见下方专题。
- 工具调用经过策略、可选审批和执行管线。 拒绝、取消和异常有各自的分支；图中展示的是成功路径。
- 持久日志用于重建历史，实时事件用于在途协调与显示。 实时事件不会自动成为持久记录；响应流在结算前发生进程崩溃，不保证可恢复。
零 Step 的条件见 Turn 与 Step，执行分支见工具执行与 PTC，事件类型与结算规则见 Session Event Log。
按目标选择入口：阅读手册不需要安装环境；本地核验和运行上游应用是两项独立操作。
直接打开项目概览，再按需要阅读架构和能力矩阵。想先判断结论是否可信，可以从下方证据链示例开始。在线阅读无需 Git、Node.js 或模型 API key。
适合准备贡献或复核引用的读者。需要 Git，以及 Node.js ^22.19.0 || >=24.0.0；校验脚本没有第三方依赖，不需要模型 API key，也不会启动 DeepSeek Harness。
展开：获取手册、运行测试并核验固定源码
1. 获取手册并运行测试。 在未包含同名目录的位置执行：
git clone https://github.com/yang0228/deepseek-harness-analysis.git &&
cd deepseek-harness-analysis &&
npm test成功时测试摘要中的 fail 为 0。测试检查证据 schema、导航、校验器及仓库约定，不会启动 DeepSeek Harness 或调用模型。
2. 获取固定上游源码并核验引用。 完成上一步后，在同一手册目录执行；源码保存在相邻的新目录 deepseek-harness-source：
handbook_root="$PWD" &&
git clone https://github.com/deepseek-ai/deepseek-harness.git "$handbook_root/../deepseek-harness-source" &&
git -C "$handbook_root/../deepseek-harness-source" checkout --detach f3803c96974ad4a94195fb97e5c637e9c2a3afe3 &&
npm run verify -- --source "$handbook_root/../deepseek-harness-source"上游目录须处于该固定提交且工作树干净；只为核验证据时，无需在上游安装依赖或构建。验证成功后，npm 脚本信息下方会输出：
{
"ok": true,
"inspectedUpstream": true,
"claimCount": 83
}若已有符合条件的上游 checkout，可直接运行 npm run verify -- --source /上游目录的绝对路径，跳过第二次 clone。校验器检查基线、引用和已记录观察；结论的语义、来源权威性和限定语仍需阅读源码核对。
这是独立于阅读和证据核验的操作。可复现的入门路径提供前置条件、独立实验目录和 Harness Home 设置；以下链接直达对应步骤。
运行前请读安全说明： 固定基线处于开发者预览阶段，允许破坏性变更，未经过安全审计，也不应视为生产就绪。请阅读固定提交的上游 SAFETY.md，使用最小权限，并按所选 Provider 配置凭据。上游运行示例按源码审查，不能视为本手册已经完成的实机体验记录。
| 想做什么 | 选择哪条路径 | 需要留意什么 |
|---|---|---|
| 体验 Web UI | 路径 1：打包 Web UI | 浮动 npm 包跟随 registry，未必等于本手册的固定源码。 |
| 复现本手册的分析对象 | 路径 2：固定源码构建 | checkout 到固定 commit，再安装依赖、构建并启动。 |
| 执行一次命令行任务 | 路径 3：Headless | 接续已经构建的固定源码环境。 |
| 在 TypeScript 应用中调用 Agent | 路径 4：TypeScript SDK | 使用对应 SDK 依赖；按示例启动并回收运行时。 |
| 在 Python 应用中调用 Agent | 路径 5：Python SDK | 使用对应 SDK 与捆绑运行时；按示例启动并回收。 |
结论能否从代码核实？以 DSH-ARCH-007 为例，直接打开下表的固定源码，无需先搜索 JSON：
所有进入模型请求的输入都可由追加式 Session Event Log 重建。
| 核查点 | 直接打开证据 | 重点看什么 |
|---|---|---|
| 上游规定了什么？ | 架构规则，第 122–130 行 | 模型可见输入必须可由日志重建；新增模型输入需要对应 Session 事件。 |
| 请求配置与工具定义从哪里恢复？ | EpochHeader 字段，第 240–256 行 |
请求头记录调用配置和工具定义；系统提示属于消息历史。 |
| 日志怎样变成模型消息？ | deriveEventMessage() 实现，第 120–150 行 |
用户消息、工具结果等可以投影为模型消息；任务边界和失败尝试等仅留在日志。 |
一个可直接复核的例子： 在最后一个链接中，user/message 分支返回消息数据，未形成模型消息的日志事件返回 null。这说明“有日志记录”不等于“会发送给模型”；该函数展示消息投影的一条实现路径，不单独证明所有插件都遵守整个日志规则。
适用范围： 不是每次 UI／CLI 交互都已进入模型请求，实时事件也不等于持久日志。该 Claim 在正式记录中标为 upstream-fact／verified／released；released 不等于生产就绪。
自动校验的范围： 本地核验检查固定基线、引用路径与行号、已记录观察等；它不会替代对代码语义的判断，也不表示已运行所有 Provider 或插件。完整解释见 Session Event Log。
更多规则见证据方法；从上游文件反查分析结论，使用证据反向索引。
以下五项机制都有对应 Claim。正式分类、证据信心、成熟度和限定语由差异化机制评估与 evidence/claims.json共同给出。
| 机制 | 帮助理解的问题 | 同时阅读的限制 |
|---|---|---|
| 全插件组合 | 除工具之外，哪些产品能力可以通过组合替换？ | 不表示运行中的组件能任意热替换。 |
| 生命周期拥有的 Effect | 卸载与重载时，谁负责清理注册和资源？ | 自动清理关系只覆盖通过生命周期 API 登记的副作用。 |
| 类型化事件与模型输入日志 | 怎样观察运行过程并重建模型历史？ | 持久重建依赖 durable Session Event Log，live 总线本身不持久。 |
| 每 Session 的 Agent Preset | 同一 Host 怎样承载不同能力组合？ | Session 开始 Turn 后组合固定，不能任意换装工具。 |
| Programmatic Tool Calling | 怎样用模型生成的程序组合多次工具调用？ | 子调用仍走受保护管线；本手册没有量化速度、成本或质量收益。 |
展开：普通工具调用与 PTC 的交互差异
假设读取两个文件后汇总内容，以下只比较两种可能的调用组织方式，不代表所有普通调用都必须逐次往返：
| 组织方式 | 示例过程 |
|---|---|
| 模型逐次决定下一项调用 | 模型请求读 A → 工具结果返回模型 → 模型请求读 B → 工具结果返回模型 → 汇总。 |
| PTC 程序组合调用 | 模型提交一段 run_code 程序 → 程序调用读 A、读 B 并处理结果 → 向模型返回所需内容。 |
PTC 默认每次运行创建新 Node 进程，也可显式配置按 Agent 保留内存的模式；所有模式都受会话文件策略约束，内存不随 Session 恢复或 Fork。普通工具调用也可以在一次模型响应中包含多次调用。PTC 的特点是把部分中间控制流交给程序表达；每次子调用仍受策略、取消、并发和资源约束。完整机制见注册工具与 Programmatic Tool Calling。
- 应用与预设组合：Profile 名录迁入 official-bundles；Minimal 增加 read_image 与 compaction，Standard 的插件管理工具按 profileContext 启用。
- 工具执行与 PTC：按 Scope 选择 native/PTC executor，条件工具按 Step 准入；Node PTC 默认新进程，可显式启用保留内存的 REPL 或 Script。
- SDK 集成：新增显式持久会话恢复、客户端审批和原生用户提问；区分恢复历史、等待任务和恢复外部进程。
- 能力矩阵与编排机制：Schedule 覆盖完整 SDK；补充独立 child Preset、macOS CUA 与 Sandbox 额外写入目录的限制。
- Session 生命周期：模型选择在组装前固定，Projection handle 在注册移除后仍可读取；普通 Fork 与 subagent 的 parentSession 含义分开。上游运行要求提高至 Node.js >=24.9.0。
| 你的目标 | 建议顺序 | 读完能回答什么 |
|---|---|---|
| 快速建立全貌 | 项目概览 → 能力与组合归属 → 入门路径 | 它是什么，能力在哪启用，从哪里运行？ |
| 理解系统机制 | 架构 → 差异化机制 → 下方专题 | 插件、事件日志、工具和 Agent 怎样协作？ |
| 审核证据链 | 证据方法 → 源码索引 → 术语表 | 每个结论来自哪里，有什么限定？ |
| 比较框架与产品 | 比较方法 → Agent 框架／编码 Agent 产品 | 同类对象的机制与产品表面有哪些差异？ |
| 专题 | 重点问题 |
|---|---|
| Cordis 插件生命周期 | 加载、依赖、Effect 与卸载清理。 |
| 应用与 Session 的组合层 | Application Profile、Bundle、Agent Preset 与 Scope 的不同职责。 |
| Session Event Log | 追加记录、投影、恢复与 Fork。 |
| 工具与 PTC | 注册、执行管线、程序化调用与约束。 |
| 本地 Sandbox | 不同执行环境的隔离范围与限制。 |
| Subagent、Goal、Plan mode 与 Workflow | 委托、目标、计划状态和脚本编排分别由谁负责？ |
- 事实错误、上游漂移或分析建议，可以通过 Issue Forms 反馈；请附相关 Claim 和源码位置。
- 修改前阅读参与贡献，保留 Claim 分类、不可变来源和限定语，并运行本仓库测试与证据校验。
- 一般问题见支持范围；DeepSeek Harness 安装、配置和产品使用问题转向上游仓库的当前支持渠道。
- 本仓库的安全问题按 SECURITY.md 私密报告；上游安全问题按其当前公开渠道处理。
- 引用使用
CITATION.cff中的首选信息，并注明分析基线f3803c96；其中的版本字段为snapshot-f3803c96。
维护者：@yang0228。