如果把常见 coding agent 看作一辆完成度很高的车，DSH 更像一套可以替换发动机、底盘、仪表盘、驾驶规则和行车记录仪的造车平台。
SOURCE-BASED REPOSITORY FIELD GUIDE
它不是又一个
coding agent 壳。
DeepSeek Harness 更接近一套可编程的 Agent 运行时：把模型、Loop、工具、日志、权限、子代理、Web UI 与自我修改都变成可组合、可替换、可回放的插件。
CORDISeverything
is a plugin
LLMLoopToolsSessionUIPolicyis a plugin
插件注册都是 effect；卸载时能力与监听器一起撤销。
- 开发阶段
- rc.5 开发者预览
- 仓库 package.json
- 226 含 apps / packages / vendor / native
- 工具目录条目
- 52 生成的 tool catalog 统计
- 交付表面
- 5+ Web / Headless / ACP / JSON-RPC / Python
01 / EXECUTIVE VERDICT
一句话：Harness 的产品，是“组合能力”本身
Claude Code、Codex、OpenCode 与 pi 都可以写代码；DeepSeek Harness 最特别的地方，不是又多了几个工具，而是把 Agent 产品的内部结构公开为可装配的运行时。
可逆插件树
每个注册都可撤销；配置层、作用域与 realm 决定一个能力属于全局还是单个 Agent。
模型可见 ⇔ 已记录
Prompt、tool schema、用户上下文与工具结果都要能从 SessionEvent 日志重建。
运行时自修改
Agent 能生成临时 Host / Client 插件，经过审批后挂载到自己正在运行的进程。
02 / COMPOSITION MODEL
四层装配：Profile → Bundle → Patch → Agent preset
DSH 的启动不是读取一份巨型配置，而是把若干层按顺序施加到空的 Cordis entry list 上。后层按 id 替换整行配置，因此任何默认能力都能被准确覆盖。
01
决定装哪些 Bundle
Profile
用户选择的运行形态。Web 与 Headless 不是两套程序，而是不同的插件组合入口。
02
可被上层整体替换
Bundle
可分发的 Cordis 配置层。dsh-base 提供共同底座，web-app 或 headless 再覆盖表面差异。
03
配置就是装配语言
Patch
按 id 替换整行配置：Profile patch → 用户 Home patch → 临时 --patch，后者优先。
04
同进程，多种 Agent
Agent preset
每个会话加入一个常驻 Agent 组合，得到自己的 persona、工具、计划、压缩与委派能力。
registries · persistence · sandbox · approval · model route · subagent providers · API gateway
persona · tools · prompt sections · plan mode · compaction · workflow engine · skill provider
为什么 Host / Agent 两平面值得单独强调？
因为“每个会话不同能力”不等于“每个会话复制一套服务”。例如 subagent provider name 必须进程内唯一，API gateway 也要读取同一个 goal registry；它们属于 Host。相反，某个 Agent 是否看得到 goal tool、workflow tool 或特定 persona，属于 preset。仓库用 isolate realm 明确表达真正的 per-agent service lifetime。
查看标准 preset 的逐行说明03 / CAPABILITY MAP
八个真正有辨识度的设计
下面不是包名清单，而是这个仓库相对普通 coding agent 的结构性差异。可以使用页首检索缩小范围。
当前显示完整功能与提示词条目
01
PLUGIN KERNEL
连 Agent Loop 本身都是插件
模型适配器、会话日志、系统提示词、工具注册表、具体 Agent Loop、Web UI 都通过 Cordis 上下文组合，没有不可替换的“神圣核心”。
- 注册是 effect：插件卸载时工具、事件监听器和服务一起回滚。
- 扩展通常挂在事件或 Service Definition 上，不必修改默认 loop。
- HMR、隔离 realm、作用域遮蔽让同一进程可运行不同 Agent 组合。
02
EVENT SOURCING
“模型可见”必须“日志可重建”
会话不是一串临时 message，而是一份 append-only SessionEvent 日志。模型历史、回放、分叉、标题、遥测和 UI 都从同一条事件流投影。
- assistant/chunk 原样保留流式回放，assistant/message 保留组装结果与用量。
- request/header 记录系统提示词、模型配置与工具 schema，复现一次请求不靠内存猜测。
- 新增任何模型可见输入，都必须有对应 session event。
03
CAPABILITY SEAMS
能力不是一个工具，而是三角色闭环
一个完整能力由 Service Definition、Service Provider、Consumer 组成。文件系统、Shell、LSP、Web、Subagent、压缩都按同一模型拆分。
- Consumer 只依赖抽象定义，不依赖本地 provider。
- 替换 FS / subprocess provider，可把 Bash、PTY、LSP 一起搬到远端执行世界。
- 配置默认值在拥有者的 resolve 阶段显式决定，避免跨包隐式 fallback。
04
PROMPT REGISTRY
提示词是可排序、可作用域化的注册表
Persona 只是 order 0 的一个 section；文件工具、Shell、LSP、工作流、Web UI 各自拥有自己的指导语。每一步组装一次完整提示词与可见工具 schema。
- 严格 {{model}} / {{cwd}} 插值，拼错变量会在请求前失败。
- Agent 作用域可遮蔽全局 persona，工具限制与 schema 可见性同步。
- 动态上下文另存为可追踪的 user-role snapshot，避免偷偷改变系统提示词。
05
MULTI-AGENT
不是只有一种 subagent
同一个 Subagent Runtime 后面可挂本进程 spawn、带历史前缀的 fork、ACP 子进程、完整 DSH SDK 子进程，以及原生 Codex / Claude Code 产品。
- continuable 子代理有持久 id、冷恢复、follow-up、interrupt 与 report 通道。
- fork 只继承已完成 turn 的平衡事件前缀；spawn 是干净上下文。
- 外部产品桥只回传最终文本，权限、模型和认证仍由原生产品配置决定。
06
ORCHESTRATION
Todo、Goal、Workflow、Ralph 是四个不同层级
仓库刻意区分当前回合清单、跨自动回合目标、模型编写的多代理脚本，以及每轮全新上下文的 Ralph 循环，避免一个“任务”概念包打天下。
- Goal 是同会话持久目标，可自动续轮，并对 complete / blocked 有硬约束。
- Workflow 在 worker thread 执行模型写的 JS，支持 phase、并发 agent 与结构化返回。
- Ralph 的脚本由部署固定；每轮仅用结构化报告交接，工作区才是长期记忆。
07
ENFORCEMENT
安全规则不只写在提示词里
工具调用先记录，再经过 pre waterfall、单调 guard、around execute、post waterfall 与最终内容约束。审批、沙箱、read-before-edit、超时都能各守一层。
- 权限 ask 在 guard 之前解析；guard 只能 deny 或 abstain，不能放宽其他策略。
- 默认 workspace-write，危险模式才关闭审批。
- 模型被告知 edit 前先 read，同时 fs-observation-policy 在执行层真正阻止违规写入。
08
SELF MODIFICATION
Agent 可以检查并临时改写自己所在的运行时
“创造模式”让模型读取 Cordis 服务与事件目录，定义一个不可变 package 版本，获得批准后在 Host / Client 两侧启动，再停止或回滚。
- 动态定义本身不写仓库；进程重启后消失。
- Host 可接文件、命令、Session；Client 可接 Slot、主题、工具卡片与页面状态。
- 这是受限执行环境，但不是对恶意代码的安全边界，信任级别等同 Shell。
04 / CANONICAL RUNTIME
一次正规 Turn 是怎样被编排的
在 DSH 里，step 是“一次模型请求 + 它要求的工具”；turn 是从一批输入开始，经过零个或多个 step，直到系统不再欠任何后续动作。
- 01
输入进入唯一 Inbox
followup 开新 turn，steer 尽快进入下一 step，inject 只提供上下文且不会唤醒 Agent。三者拥有明确队列语义。
agent/inbox/inserted - 02
先开 Turn，再认领输入
turn/start 先落日志；Driver 认领 next-step 输入与一条 next-turn 消息。即使被拒绝，也留下一个没有 step 的可审计 turn。
turn/start - 03
agent/pre-step 决定是否进入
Hooks、压缩与上下文插件可改写完整消息批次或 reject。决定是 authoritative，不是旁路通知。
live waterfall - 04
组装 Prompt + Tools
按 Agent scope 合并 section、runtime context、变量与工具 schema；严格插值后写 request/header，保证重建。
request/header - 05
模型请求流式落盘
agent/request 与 llm/stream 都可拦截；每个 chunk 先记录，再汇总 assistant/message，保留精确回放与 usage。
assistant/chunk* - 06
有序启动、并发执行、按模型顺序收口
只读工具可在滚动池并发，变更工具形成 barrier。每个调用都先有 tool/call，再经策略链，最后记录一个权威 tool/result。
tool/call → tool/result - 07
判断是否还欠下一步
工具结果、steering、background notice、Goal driver 都可能让同一个 turn 继续下一 step；自然停止前还要经过 turn-stopping。
step/end - 08
关闭 Turn，回到 Idle
turn/end 记录 completed / aborted / error 等原因；UI、SDK、投影器只需消费同一事件流，不需要猜 Agent 内部状态。
turn/end
关键点 A失败也有完整边界
请求失败会先关闭 step，再进入 agent/request-error；只有压缩或修复确实推进了状态，才开新 turn 重试。
关键点 B并发不是 Promise.all 全开
Loop 使用 barrier 与有界滚动池；只读调用可以重叠，变更调用保持顺序，并按模型次序写入结果。
关键点 CUI 不窥探 Loop
UI / SDK 消费 session/event 与少量 live agent/* 状态；冷回放和正在运行的呈现使用同一来源。
05 / PROMPT LAB
最有意思的提示词，不是 Persona
默认身份只有一句；真正承载产品行为的是各插件拥有的短策略段、工具 schema、可追踪上下文，以及少数固定编排脚本。
提示词不是一块大字符串
−100 身份 → −98 Web / 源码方向 → 0 Persona → 99 Code Mode 约束 → 100–116 工具指导 → 150 Typed SDK → 190 结构化输出 / UI 交付提示
每个 owner 只维护自己那一段。工具卸载时，指导语也随 effect 消失；同名 scoped section 可以精确遮蔽全局 section。
把几十个原生工具折叠成一个 run_code
`run_code` is the only tool you can call directly — a tool call naming any other tool fails. Reach every tool the SDK declares below from inside the program.
随后动态生成 TypeScript 或 Python SDK：await tools.name(args)，带精确入参与返回类型。中间工具结果不进入对话，只返回程序主动 print / return 的精炼数据。这不是“让模型随便写脚本”，而是把工具调用变成可组合的数据处理程序。
工具目录保持不变，策略文本改变
The tool catalog stays the same across modes for request-cache stability… Make exit_plan_mode the only and final tool call in that assistant response.
这是很少见的 cache-aware 提示词设计：计划模式并不删除写工具，以免改变 request shape；它用更高优先级规则禁止执行，并要求最终计划只能通过 exit_plan_mode 提交审核。
AGENTS.md / CLAUDE.md 作为有来源的历史消息
More specific instructions take precedence over broader ones. They do not override system, developer, or direct user instructions.
基础链在首次请求进入日志；深入子目录后按成功的结构化文件工具触发增量发现。文件更新与删除也会生成 replacement / tombstone，而不是悄悄替换旧上下文。
子代理权限与汇报通道写得非常具体
your permission scope was fixed when you were started and cannot be widened… Deliver your result with the report tool before you finish
前一句阻止子代理不断重试需要审批的操作；后一句说明父代理不会自动收到子代理 transcript、tool output 或 reasoning，必须显式 report。这把“谁能看见什么”从实现细节提升成模型契约。
每轮重置上下文，只让结构化交接穿过
The shared workspace and its current working tree are the long-term memory and source of truth… confirm [the previous report] against the workspace.
fresh worker 不见父会话，也不见上轮 child session。它必须输出 continue / complete / blocked 的规范 JSON；complete 要有 evidence，blocked 要有具体 blocker。部署固定脚本，模型只提供 objective。
一段真正像“运行时操作手册”的系统提示词
Dynamic Cordis plugins temporarily extend the current DSH process… every side effect must be reversible.
它同时解释目标寿命、Host / Client 选择、inspect → define → run → stop / rollback 流程、版本指针、审批、纯 JS 限制、活对象不可序列化和 effect 清理。比常见的“你可以写插件”完整得多。
DESIGN PRINCIPLE
Prompt 与 enforcement 成对出现
例如 edit section 告诉模型“先读再改”，fs-observation-policy 会真的拒绝未观察文件的写入；structured_output 提示要求最终 tool call，monotonic guard 会在成功记录后阻止任何后续调用。这个仓库倾向于让提示词解释规则，让执行层证明规则。
06 / PRESETS & SELF-REFERENCE
同一个 Harness，可以长成三种完全不同的 Agent
Preset 不是 UI 上的软模式标签，而是一份真正的 agent.cordis.yml 组合；工具、提示词、服务 realm 与压缩策略都会随之变化。
P1
完整编码 Agent
标准模式
文件编辑、Shell、检索、Skills、Plan、Goal、Subagent、Workflow、Ralph、Ask User 与 Web Search。
P2
固定提示词 + 两工具
极简模式
完整 system prompt 只有 “You are a helpful software engineer assistant.”；仅暴露持久 Bash 与 str_replace_editor。
P3
标准模式 + 自修改
创造模式
增加 Cordis inspect / define / run / stop / undefine 工具，以及编写 Agent preset 的专用 Skill。
07 / MARKET MAP
与 Claude Code、Codex、OpenCode、pi 的实质差异
这不是“谁更强”的排行榜。五者优化的对象不同：产品体验、任务编排、开放模型、极简嵌入，或运行时可组合性。
当前聚焦
DeepSeek Harness
可编程 Agent 运行时 / 产品装配框架
| 对照维度 | DeepSeek Harness | Claude Code | Codex | OpenCode | pi coding agent |
|---|---|---|---|---|---|
| 核心定位它最希望你把什么当作产品中心？ | 插件化 Agent Runtime；“产品”是配置组装出来的插件树。 | Claude 原生 coding product；CLI、IDE、Web、SDK 与团队协作体验。 | 多任务 coding workbench；本地 / 云端 Agent 与工程自动化。 | 开源多模型 coding agent；通过配置和插件塑造行为。 | 最小 coding harness / SDK；默认 TUI 很薄，扩展自行长出产品。 |
| 最小扩展单元扩展从哪里进入？ | Cordis plugin：服务、事件、工具、Prompt、UI、持久化、Loop 都可贡献。 | CLAUDE.md、Skills、Hooks、MCP、Subagent、Plugin。 | AGENTS.md、Skills、MCP / App、Hooks、Plugin 与任务自动化。 | opencode.json、Agents、Skills、MCP、JS/TS Plugin hooks。 | TS extension、Skill、Prompt template、Theme、pi package。 |
| 提示词与项目规则规则怎样进入上下文？ | 有序 section + 严格变量 + 记录成事件的 runtime context；兼容 AGENTS.md / CLAUDE.md。 | CLAUDE.md / rules / memory + Skills；路径相关内容按需加载。 | AGENTS.md 层级规则 + Skills；产品拥有完整开发者 / 系统指令层。 | AGENTS.md / CLAUDE.md 兼容规则、instructions 配置、Skill tool。 | AGENTS.md / CLAUDE.md + 可替换 SYSTEM.md / APPEND_SYSTEM.md + prompt templates。 |
| 事件拦截规则是建议，还是执行链？ | typed emit / serial / waterfall；PreTool、Execute、PostTool 分层，注册随 effect 回滚。 | 30 个当前 hook events；command / HTTP / prompt / agent hook，最严格决策合并。 | 当前官方 Hook 协议；DSH 只兼容其中部分 command hook。 | Plugin events 与 tool/model transform hooks；V2 API 仍标为 beta。 | extension 监听生命周期和 tool_call，可替换工具、压缩、UI 与 provider。 |
| 多 Agent谁调度、怎样隔离？ | spawn / fork / continuable + ACP / DSH SDK / Codex / Claude providers；Workflow 与 Ralph。 | Subagents、Agent view、Agent teams、worktrees、/batch，多种协作层级。 | App 多任务与 worktrees；本地线程、云环境、后台 / 定时任务与多 Agent 协作。 | Primary / subagent 配置与 task 工具；按 Agent 设模型、工具和 permissions。 | 核心不强制；官方扩展示例展示 isolated subagent，团队可自定义。 |
| 运行时可替换性能换到多深？ | 最深：Agent Loop、Session store、Prompt、Tools、FS / subprocess、UI 都是插件。 | 开放扩展点丰富，但产品核心 loop 与 session 语义由 Claude Code 拥有。 | 开放 SDK / MCP / Skills / Hooks；核心任务与 sandbox 由 Codex 产品拥有。 | 开源且 plugin API 深，可拦截模型和工具；仍有中心化 app/session 架构。 | 非常深：extension 可替换默认工具、UI、压缩、provider；核心比 DSH 更小。 |
| 会话事实来源UI、回放和模型历史是否同源？ | 显式 append-only typed SessionEvent；model-visible ⇔ logged 是仓库硬规则。 | 产品保存 transcript / sessions，SDK 暴露消息流；不是同样的公共类型事件账本。 | Thread / turn / item 事件与本地历史由产品维护；App Server 有协议事件。 | Session / message / event API；没有 DSH 这条同等强度的仓库级可重建规则。 | 分支化 session tree、JSONL 与事件订阅；设计更贴近单 Agent 会话。 |
| 自我修改Agent 能否改变正在运行的自己？ | 显式一等能力：inspect → define immutable package → approve → run / update / rollback。 | 可写 Skills / Hooks / Plugins / settings，但通常经文件与下一次加载生效。 | 可写 Skills / Plugins / AGENTS.md；产品本身不以 live runtime plugin tree 为模型。 | 可改本地 plugin 配置并热重载部分配置；不是 session 内版本化 live package 流程。 | extension 可动态注册工具；Agent 可编辑扩展文件，但无 DSH 式版本指针与审批运行协议。 |
| 跨产品兼容它把其他 Agent 当成什么？ | 把 Codex / Claude Code 当 subagent provider，也能桥接两者的 hook 配置子集。 | 通过 MCP 连接其他工具；Agent teams 内成员仍是 Claude sessions。 | 通过 MCP / Apps / Plugins 连接外部能力；任务 Agent 仍由 Codex 运行。 | 多 provider 与 MCP 兼容优先，也读取 Claude / Agent Skills 目录。 | 模型 provider 最开放；extensions 可实现 MCP、SSH、Claude-like UX 和自定义 subagent。 |
| 成熟度与代价现在采用时真正要付出的成本。 | 开发者预览、rc.5、明确允许破坏性改动；架构表达力强，但学习与装配成本最高。 | 产品成熟、文档完整；依赖 Claude 生态与产品定义的核心行为。 | 产品和模型快速演进；任务管理强，平台能力随版本变化快。 | 开源生态活跃；V1 / V2 文档与 beta plugin API 需要留意版本。 | 核心简单、可读、可嵌入；很多高级能力要自己挑扩展或编写。 |
pi，而不是 Claude Code
pi 同样把自己称为 harness，默认四工具、核心小、extension API 深；但 DSH 更强调 typed service seams、durable event sourcing、Host / Agent 双平面和产品化 Web BFF。
Claude Code / Codex / OpenCode
它们更像用户直接工作的成品。DSH 甚至能把 Codex 与 Claude Code 作为子代理 provider，这说明其目标不是只替代它们，也包括编排它们。
“插件多”不等于“能力松散”
DSH 用事件模式、capability 三角色、source/artifact plane、runtime invariants 和文档 gates 给插件自由设了很重的工程纪律。
08 / REPOSITORY WORKFLOW
在这个仓库里，正规开发流程是什么
仓库并不鼓励“看到 loop 就改 loop”。它要求先选择正确扩展点，再把运行时、模型体验、日志、UI 和测试证据一起闭环。
- 01
定位扩展点
先读 architecture / capability map；能挂事件或 Service 就不改 agent-loop。
- 02
决定所属平面
跨会话注册表、持久化、沙箱、模型路由在 Host；单 Agent 的工具、persona、prompt section 在 preset。
- 03
补齐能力三角色
新增能力同时设计 Definition / Provider / Consumer；不同演进节奏才拆包。
- 04
让可见状态可重建
新模型输入先设计 SessionEvent，再从日志投影；opaque id 使用 branded type。
- 05
把提示词放回 owner
工具的跨调用指导归工具插件；UI 的交付格式提示归 UI renderer；persona 不做万能垃圾桶。
- 06
先决定工具 UI 意图
generic / terminal / diff / locations 在设计时确定，presentation 纯由 args / result 推导。
- 07
覆盖三层证据
能力 seam 做 unit + e2e；用户可见行为再加 keyless runnable snapshot。
- 08
同步文档与决策
README、JSDoc、架构图一起更新；非平凡变更同 PR 写 Agent Note。
- 09
只跑相关检查
按变更面选 focused tests、typecheck、build、hygiene、doc-sync 或 snapshot；CI 承担全量矩阵。
推荐入口
pnpm dsh --profile web --dump-config先看机器真正会启动的插件树；任何打印出来的 row 都可以被 profile patch、home patch 或 --patch 覆盖。
09 / ADOPTION GUIDE
它适合谁，又不适合谁
架构能力越强，抽象成本越高。正确的采用判断，应该从你要控制的层级出发。
适合采用 / 研究
- 你在做 Agent 平台、运行时、Web 产品或多模型基础设施。
- 需要一套可替换 LLM、FS、Shell、Sandbox、Subagent、Session backend 的统一框架。
- 要审计、回放、分叉、冷恢复，且要求模型看到的输入能从日志重建。
- 想把 Claude Code、Codex、ACP Agent 或另一套 DSH 当成委派后端。
- 愿意用严格包边界、JSDoc、生成目录、snapshot 与 Agent Note 换取长期可演进性。
暂时不适合
- 只想安装一个稳定、熟悉、几乎不用理解架构的日常 coding agent。
- 无法接受 pre-release 期间的破坏性重命名、磁盘格式拒绝和快速演进。
- 团队不准备维护 Cordis 配置层、跨包 contracts 与多种执行 / 持久化后端。
- 真正需求只是“四个文件工具 + 一个模型”；这时 pi 或 DSH minimal preset 更直接。
- 把动态 Cordis VM 误当恶意代码安全边界；仓库明确说它不是。
决策捷径
想要成品 Agent：先看 Claude Code / Codex / OpenCode。想要最小可嵌入核心：先看 pi。想要可以换掉 Agent 产品内部几乎每一层的装配框架：DSH 的辨识度最高。
10 / SOURCES & METHOD
这份介绍基于什么
仓库结论以 2026-08-13 本地工作树的 commit 47f9438 为基线；外部产品差异以各自官方文档或官方源码为准。快速演进功能应以链接中的最新版本为准。
DeepSeek Harness 一手资料
- Architecture整体插件树、turn flow、capability seams
- Base bundle默认 Host 组合、权限、工具与后端
- Standard preset默认 Agent plane 的真实装配
- System promptsection、变量、schema、cache 规则
- Agent lifecycleturn / step 的权威事件序列
- Tool pipeline审批、guard、执行、post 与最终结果
对照产品官方资料
- Claude Code extensionsCLAUDE.md、Skills、Hooks、MCP、Subagents、Plugins
- Claude parallel agentsSubagents、Agent view、Teams、Worktrees
- OpenAI Codex docsCodex 产品与开发工作流总览
- Codex multi-agent多 Agent 与工作树资料
- OpenCode agentsAgent、工具与权限配置
- OpenCode pluginsJS / TS 插件与事件扩展
- pi coding agent README默认工具、TUI、Skills、Extensions、SDK
证据口径
代码库数字来自本地只读统计：226 个 package.json、生成工具目录 52 条；不把它们宣传成“226 个产品包”或“默认暴露 52 个工具”。比较表把仓库明示能力与官方产品能力分开，不根据相似术语推断实现等价。本页是独立仓库导览，DeepSeek 名称与标识属于其权利人，不代表官方背书。