Product Analysis

DeepSeek Harness · 阶段 04 · 产品架构

阶段 04 · 产品架构

DeepSeek Harness 架构拆解

从配置叠层、Cordis 插件树、Agent Loop、能力 Seam 到仅追加会话事件流，拆开这台可换零件的 Agent 运行机。

ARCHITECTURE VERDICT

先说结论：它不是一个固定的 Agent，而是一台“可换零件的 Agent 运行机”

DeepSeek Harness 的架构主轴是：Cordis 插件树负责组装，Agent Loop 负责推进，Session Event Log 负责记忆与回放，Capability Seams 负责替换模型、工具、沙箱和 UI。它把传统 Agent 框架里写死的能力拆成插件，通过服务、事件和配置叠层组合成不同运行形态。

已确认E-002 最小内核Cordis

只管插件加载、卸载与依赖，不承载具体 Agent 能力。

已确认E-009 状态真源Append-only Log

模型可见内容、工具调用、轮次与步骤都从同一事件流派生。

已确认E-004 产品形态4 种预设模式

标准、PTC、极简、创造模式，本质是不同插件组合。

已确认E-016 成熟度开发者预览

核心 API 仍快速演进，官方明确提示会有破坏性变更。

架构关键词：插件化微内核、配置即组装、事件溯源、运行时可拦截、能力提供方可替换、本地优先。
EVIDENCE SCOPE

查看范围与证据边界

本报告于 2026-08-23 只读取证。查看了官网首页、官方 Quickstart、数据处理说明、安全政策、GitHub README、仓库架构文档、会话/工具/Agent/LLM/API Gateway 子系统文档与根目录 package.json。未实际安装或运行 Harness，未触发模型调用、工具执行和插件安装。

已确认

直接可见

产品定位、入口、运行模式、配置组合、核心包职责、事件域、轮次流程、Session 事件结构、本地优先与安全建议。

合理推断

基于公开实现推导

架构优势、复杂度迁移、企业落地阻力、插件生态治理重点与运维观测压力。

未知

本轮没有验证

真实运行性能、并发上限、长会话存储成本、插件兼容性、故障注入表现、各操作系统沙箱强度。

核心来源：官网 · 架构文档 · Quickstart · GitHub 仓库

PRODUCT DOMAINS

六个核心功能域

从产品视角看，DeepSeek Harness 不是“聊天 + 工具”两层结构，而是六个互相咬合的域。

01 运行时组装域

对象：Profile、Bundle、Patch、Plugin Tree。

作用：从空树开始叠加 dsh-base、Web/Headless 组合包、用户 patch 与命令行 overlay，得到本次真正启动的配置树。E-006

02 Agent 执行域

对象：Agent、Inbox、Turn、Step、Agent Loop。

作用：领取输入、组装请求、调用模型、执行工具、判断是否继续下一步或结束轮次。E-008

03 能力插件域

对象：模型适配器、工具、Skills、沙箱、终端、文件系统、子 Agent、Goals、Jobs。

作用：用 Service Definition / Provider / Consumer 三角色构成可替换 seam。E-010

04 会话与轨迹域

对象：SessionEvent、RequestHeader、Message Surface、Trajectory。

作用：以仅追加日志记录模型所见与执行事实，并支持派生历史、回放、恢复和分叉。E-003E-011

05 交互与接入域

对象：Web UI、Headless Runner、CLI、Python SDK、Client Connection、Remote API。

作用：把同一运行时能力暴露给浏览器、命令行与自动化调用方。E-005E-012

06 治理与执行环境域

对象：Workspace、Approval Policy、Sandbox、Credentials、Telemetry、Persistence。

作用：限定 Agent 能看什么、做什么、在哪执行、如何持久化与审计。E-005E-013E-014

END-TO-END FLOW

一条任务如何穿过 Harness

以下主链把用户交互、控制流、工具流、状态流和产物流放在一起。关键分界是：配置先决定“这次有哪些能力”，事件流再记录“这些能力具体做了什么”。

  1. 01
    启动与组装

    dsh web 选择 Web profile；Bundle、profile patch、home patch 和 --patch 按顺序叠加，形成插件树。

    E-006 · 配置流
  2. 02
    依赖就绪

    Cordis 按依赖加载插件；插件向共享 ctx 注册服务、事件监听与副作用，卸载时撤销。

    E-002 / E-010 · 控制流
  3. 03
    用户准备环境

    在 Web UI 配置模型、选择 workspace；未选工作区时输入框不可用。模型路由可即时生效。

    E-005 · 用户交互流
  4. 04
    输入进入 Inbox

    新消息唤醒 Agent Loop，先写入 turn/start，再领取下一步输入和一条排队消息。

    E-008 · 状态流
  5. 05
    构造模型请求

    agent/pre-step 可改写或拒绝输入；系统提示词片段与工具 schema 被组装，请求头与路由上下文写入日志。

    E-007 / E-011 · 上下文流
  6. 06
    模型流式输出

    agent/request → llm/stream，原始 chunk 与组装后的 assistant message 依次落为持久事件。

    E-008 / E-009 · 模型流
  7. 07
    工具受控执行

    工具调用进入 pre-execute → execute → post-execute 流水线；权限策略可要求人工审批，沙箱/文件系统/终端提供方决定实际执行世界。

    E-005 / E-008 / E-010 · 动作流
  8. 08
    继续或收束

    工具若仍欠一次请求，或 Inbox 收到新输入，则进入下一 Step；否则 agent/turn-stopping → turn/end。

    E-008 · 状态机
  9. 09
    展示、恢复与复用

    UI/Trajectory 从同一 Session Event Log 渲染；恢复、fork、transcript、遥测和持久化都从事件流派生。

    E-003 / E-009 · 资产与观察流
合理推断 真正的控制中心不是某个“超级 Agent”。下一步由 Agent Loop、Inbox 欠账、事件拦截器和工具结果共同决定；配置树决定它们是否存在、由谁实现。
LAYER MODEL

分层架构：从界面一路拆到执行世界

交互与接入层Web UICLIHeadlessPython SDK把会话与运行时暴露给人或自动化
Profile / 配置组合层Bundlescordis.patch.yml--patch overlayPreset决定本次运行时有哪些插件
Cordis 插件内核LoaderDependency GraphLifecycleContext只管理插件，不承载 Agent 业务能力
Agent 控制层InboxAgent RegistryTurn / StepAgent Loop领取任务、推进模型与工具循环
能力 Seam 层System PromptToolsLLM AdapterSubagent / Goals / Jobs定义、提供、消费可替换能力
执行世界与治理层Workspace / FSShell / TerminalSandboxApproval / Credentials决定动作落在哪里、受什么限制
事件与数据层Session LogPersistenceTrajectoryTelemetry把模型可见内容和执行事实统一为可回放记录
已确认关系公开事实上的架构归纳
CONTEXT & DATA

核心数据不是“聊天记录”，而是可重建运行的事件账本

SessionEvent 是完整交互历史的唯一真源。模型历史并不另存一份，而是从日志派生；请求配置、系统提示词、工具 schema、模型路由、原始流片段、工具调用与结果都能被定位到具体 Turn / Step。

Profile Snapshot插件树与能力边界
配置
Request Header模型配置 + System Prompt + Tool Schemas
进入
Session Event LogTurn / Step / Message / Tool / Context
派生
ProjectionsLLM History / UI / Trajectory / Replay / Fork
核心实体公开语义关键关系事实等级
Profile具名运行时组装按序引用多个 Bundle，并拥有个人 patch已确认 E-006
Plugin导出 apply(ctx) 的能力单元注册 Service、Event Listener、Effect；可声明依赖已确认 E-001 / E-010
Agent活跃执行实例拥有作用域 Context、Inbox、Step 与状态已确认 E-007 / E-008
Session仅追加事件日志包含多个 Turn；可恢复、fork、回放已确认 E-009 / E-011
Turn从领取输入到不再欠工作包含 0..N 个 Step已确认 E-008
Step一次模型请求及其要求的工具调用属于一个 Turn，产出 message 与 tool events已确认 E-008
RequestHeader可重建的请求信封记录模型调用配置、系统提示词与工具 schema已确认 E-011
ToolCall / Result动作请求与模型可见结果以 callId 成对，经过执行流水线已确认 E-008 / E-011
WorkspaceAgent 文件系统工作根Web UI 启动任务前必须选中已确认 E-005
Approval / Sandbox高风险动作的人机门与执行约束约束工具和子进程，不应只靠 Prompt已确认 E-005 / E-010
SYSTEM MAP

产品全景架构主图

主图同时画出组件、调用、配置、事件、状态与失败门。实线为官方文档明确关系；虚线为基于公开结构的归纳。

调用 / 写入 / 注册派生 / 归纳建议治理增强
DeepSeek Harness 全景架构 从交互接入、配置组合、Cordis 内核、Agent Loop、能力插件、执行世界到会话事件流的分层关系。 ACCESSCOMPOSEKERNELCONTROLCAPABILITYWORLDEVENT DATA Web UITrajectory / Settings CLIdsh web / profile Headlessone-shot runner SDK / ClientPython / Remote API Profile → Bundles → profile patch → home patch → --patch配置叠层生成本次 Cordis 插件树 CORDIS KERNELLoader · Dependency Graph · Lifecycle · Shared Context · Services · Events Agent Registry + Inbox输入 / 注入 / 续跑 AGENT LOOPTurn → Step → Request → Tool → Continue / Stop Interception Eventspre-step / request / stopping System Promptfragments + schema Tool Registryscoped + gated LLM Runtimeadapter seam Subagent / Goalsdelegation + continuation Jobs / Skillsbackground + context Workspace / FSfiles + policy Shell / Terminalprocess world Sandboxwrap execution Approvalhuman gate Model ProvidersDeepSeek / compatible APPEND-ONLY SESSION EVENT LOGPersistence · Derived History · Trajectory · Replay · Fork · Telemetry UI 从事件流派生恢复 / fork 重新进入执行
已确认E-010关键设计：文件系统与进程提供方共享“执行世界”。把它们换到远程沙箱，Bash、PTY、LSP 等消费方可以跟着迁移，而不是为每个工具单独写远程分支。
AS-IS

当前架构：四个强点，三个代价

强点

已确认

能力可替换，不需改主干

模型、工具、沙箱、存储、循环、调度与 UI 都能由插件提供；Profile 与 Patch 负责组装。

已确认

运行可重建

请求头、模型可见上下文、消息、工具调用和结果进入同一日志，减少“UI 显示一套、模型实际看了另一套”的黑箱。

已确认

扩展点有明确归属

持久事实用 Session Events；活跃工作用 Agent Events；能力策略用 fs/tools/telemetry 等事件域。

已确认

本地优先，治理点可插拔

默认本地处理与存储，同时把 sandbox、approval、credentials、telemetry 作为独立能力装配。

代价

合理推断

复杂度从源码迁到配置图

插件越多，排查“到底加载了谁、谁覆盖了谁”越重要；--dump-config 会成为基本运维能力。

合理推断

事件契约是新耦合点

插件虽然松耦合，但都依赖服务键、事件顺序、waterfall 的 next() 传递以及可重建性不变量。

已确认

预览期兼容风险高

官方明确表示核心插件和基础 API 会持续迭代，并会出现破坏兼容性的变更。

TO-BE

如果拿去做企业级 Agent 平台，优先补的不是“更多插件”

现有架构已经给了可插拔点。企业化更需要把“能组合”升级为“可治理地组合”。

01
建议设计

插件供应链与兼容矩阵

为 Plugin / Bundle 增加签名、来源、权限声明、依赖锁定、版本兼容和回滚策略；开发者预览阶段尤其需要。

02
建议设计

Profile 变更的可视化 Diff

把最终配置树、覆盖来源、服务提供方和事件监听顺序做成可读视图，降低配置叠层的排障成本。

03
建议设计

策略即代码的审批与沙箱基线

围绕工具类别、路径、网络域、命令风险和数据敏感度定义强制策略，不让安全只停留在 Prompt 与用户自觉。

04
建议设计

长会话成本与数据保留

为 append-only 日志建立分层存储、压缩、脱敏、保留期与可验证删除策略，同时保住回放与审计能力。

05
建议设计

运行级质量门

把“任务完成”拆为模型声明、工具结果、文件/测试/业务状态验证三个层级，并在 Trajectory 中显示证据。

RISK REGISTER

架构风险排序

优先级风险触发机制影响证据强度建议检测/控制
P0不可信插件获得高权限插件可以注册工具、事件与执行环境能力本地文件、进程、凭据与网络暴露已确认 E-014来源签名、权限清单、隔离运行、默认拒绝高风险能力
P0提示注入穿透到工具执行Agent 会读取外部内容并代表用户执行操作误删、泄露、越权动作已确认 E-014内容与指令分层、工具策略门、敏感操作人工确认
P1配置叠层漂移Bundle + 多级 patch + overlay 覆盖环境间行为不一致、难复现合理推断 E-006锁定 Profile 快照、展示来源 Diff、运行记录绑定配置摘要
P1API / 插件兼容性断裂开发者预览期快速迭代第三方插件升级后失效已确认 E-016能力版本协商、兼容测试矩阵、灰度更新与回滚
P1事件日志增长与敏感数据沉积模型所见与工具结果均进入仅追加日志存储成本、隐私与删除困难合理推断 E-009 / E-013保留策略、字段级脱敏、压缩归档、租户密钥与删除证明
P2拦截器顺序造成隐性行为waterfall 事件依赖监听器调用 next()请求被改写、短路或策略绕过合理推断 E-008事件链可视化、顺序单测、短路原因强制落日志
P2外部 Provider / MCP 数据外传用户可配置外部模型、网络工具、MCP 和插件数据离开本地边界已确认 E-013出站域白名单、数据分类、调用前提示、可审计连接清单
TRACEABILITY

架构组件—证据追溯表

编号来源页面/位置支持结论等级
E-001Harness 官网首屏与“设计思路”模型、工具、技能、会话、沙箱、存储、循环、调度、UI 均由插件提供，通过 Cordis 服务与事件协作已确认
E-002Harness 官网“Cordis 内核”Cordis 只负责插件加载、卸载和依赖，不承载具体 Agent 能力已确认
E-003Harness 官网“每一次运行都有迹可循”系统提示词、思维链、工具调用与结果、子 Agent 调度、上下文注入写入仅追加会话日志；Trajectory 支持来源查看已确认
E-004Harness 官网“多种运行模式”标准、PTC、极简、创造四种模式及其工具边界已确认
E-005官方 Quickstart配置模型 / 选择工作区 / 运行任务模型路由即时可用；workspace 是任务前置；Agent 可读写文件、运行命令、委派、维护计划；策略需要时先询问审批已确认
E-006官方架构文档Profile 与组合包运行实例是插件树；Bundle、profile patch、home patch、--patch 按序叠加已确认
E-007官方架构文档核心包session、system-prompt、tools、agent、agent-loop、scope、llm 的职责与 ctx 键已确认
E-008官方架构文档事件 / 轮次流程Session、Agent、Capability 三类事件域，以及 turn/step/model/tool 的完整流转已确认
E-009官方架构文档会话日志模型可见即已记录；历史、fork、恢复、transcript、遥测和持久化从事件流派生已确认
E-010官方架构文档能力 seam / 新行为归属Seam 的 Definition、Provider、Consumer 三角色，以及模型、工具、shell、sandbox、UI 等扩展点已确认
E-011Session 子系统文档SessionEventMap / RequestHeader仅追加事件词汇、消息 surface、请求信封、路由上下文与 callId 配对已确认
E-012API Gateway 文档组件职责 / 运行时调用Host/Client Remote、严格描述符与 schema、Connection carrier、RPC 信任边界已确认
E-013数据处理说明全文产品本地优先；默认本地处理与存储；外部模型、网络工具、MCP、插件可能向外部服务传输数据已确认
E-014安全使用政策安全建议建议 VM/容器、有限权限、人工确认、可信插件与防提示注入已确认
E-015根 package.jsonengines / workspaces / scriptsNode 版本边界、TypeScript/pnpm monorepo、Host/Client/Web 构建与测试门已确认
E-016官方 README开发者预览当前处于开发者预览，快速迭代，未来会有破坏兼容性的变更已确认
OPEN QUESTIONS

仍然未知，不能从文档硬猜

未知

性能与规模

没有跑基准，不能确认并发 Agent 数、事件写入吞吐、长会话恢复时延与 Web UI 大轨迹渲染上限。

未知

默认持久化实现

公开架构确认存在持久化 seam，但本轮未逐个验证 profile 实际选用的后端、压缩与保留策略。

未知

跨平台沙箱等价性

能确认 sandbox 是可替换后端，不能确认 macOS、Windows、Linux 在默认 profile 下提供相同隔离强度。

未知

插件市场治理

能看到社区插件入口，未看到完整的审核、签名、恶意撤回、评分和兼容性认证机制。

阅读建议：把本报告当作“公开架构的产品级还原”，不是生产性能背书。真要选型，下一步应做一次本地安装 + 固定 Profile 的故障与权限测试。