jasen215/dsh-continual-harness

dsh-continual-harness

英文 |

一个用于自我改进 AI 智能体的 DeepSeek Harness (DSH) 插件，通过持久记忆、周期性审查与精炼、跨会话知识共享以及失败时自动回滚来提供持续学习能力。它形成了一个 plan → validate → apply → rollback 的闭环。

该设计灵感来自 Prime Intellect 的开源 prime-agent，一个自我改进的编码 harness。

能力

单个 npm 包（dsh-continual-harness）在挂载后通过以下扩展点生效：

| 能力 | 机制 |
| --- | --- |
| 状态投影（每一步注入 harness 上下文） | agent/pre-step waterfall 监听器；当内容摘要变化时进行增量注入 |
| 审查与自动精炼 | 在轮次间隔 / 压缩结束时触发 session/event 监听器；自动运行 LLM 审查 → 计划 → 应用 |
| 手动精炼工具 | 注册 harness_refine 工具（可由 LLM 直接调用，支持回滚） |
| 手动精炼命令 | 可选的 /refine 斜杠命令，在宿主 commands 能力（@deepseek-ai/dsh-commands）存在时通过其注册 |
| 记忆生命周期 | 通过精炼元数据进行手动归档/取消归档/固定；已归档条目会从注入和技能物化中隐藏 |
| 排序注入 | 查询最新的有效直接用户消息（最多 400 字符），将标题匹配排在内容匹配之前，然后应用新鲜度/id 平局决胜和每种类型的上限 |
| 会话收尾 | 可选的 harness_wrapup 工具提供机械式的保留/提升/归档建议；提升仅为复制操作，冲突会返回确定性错误 |
| 会话内审查轨迹 | 从会话日志重建（尾部偏向截断） |
| 不变量守卫 | harness/refinement 事件验证 + 批量失败报告 |
| 显式 A/B 基准测试 | 单一 harness_benchmark 动作工具：固定冻结用例、精炼前参考快照，以及同轮参考/候选 A/B 运行，决策由代码掌控 |

架构

src/
domain.ts      事件声明合并（SessionEventMap / MessageSourceMap / cordis Events）
types.ts       HarnessState / RefinementProposal / RefinementResult 及其他类型
storage.ts     状态与历史的磁盘读写（原子写入、损坏降级、本地/全局合并、jsonl 历史）
refine.ts      校验、应用、回滚（基线冲突检测、版本递增、增长限制）
skills.ts      SKILL.md 渲染 + 文件对账（生成的 skills 是真实的 dsh skills）
render.ts      面向模型的概览 / 摘要 / 历史渲染（排序注入）
usage.ts       注入遥测键与内存使用聚合
wrapup.ts      确定性会话收尾建议（保留/提升/归档）
planner.ts     LLM 规划提示词与 JSON 解析（plan / auto-refine review 提示词）
store.ts       HarnessStore：组合存储 + 事件发布（会话事件 + agent 作用域事件）
complete.ts    completeViaAgent：通过 ctx.get('llm') 完成
benchmark.ts   基准用例/快照 + 原子基准存储持久化
evaluate.ts    隔离的逐单元执行器/评审器评估（证据 + 评分）
score.ts       代码拥有的聚合与 ACCEPTED/REJECTED 决策
tool.ts        harness_refine / harness_wrapup / harness_benchmark 工具
projection.ts  前置步骤投影（摘要去重、 注入）
driver.ts      自动精炼驱动器（轮次间隔门控 / 压缩门控 / 冷却 / 重入保护）
invariant.ts   运行时不变式插件
index.ts       插件入口与 Config
tests/           23 个测试文件，287 个用例（storage / store / refine / rules / planner / driver / approval / audit / logfile / skills / invariant / plugin integration / rank / projection / archive / usage / wrapup / benchmark / evaluate / score / isolation / tool / benchmark integration）

数据布局

/                      共享 ESP 经验根目录；默认为 ~/.dsh/harness/
harness_state.json                跨会话全局状态（ESP）
refinements.jsonl                 全局精炼历史（仅追加，ESP）
reviews.jsonl                     跨批次门控/审计历史（ESP 扩展）
continual-harness.log             continual-harness 实现日志（JSONL，0600）
continual-harness.log.1           轮转后的 continual-harness 日志
usage.events.jsonl                仅追加的注入遥测（首次访问时惰性加载到内存）
benchmark/                        显式基准存储（验证层）
cases.json                      固定基准用例（draft/frozen + 冻结材料哈希）
snapshots/.json     捕获的参考快照（只读合并后的 harness 状态）
runs.jsonl                      仅追加的 A/B 运行记录（单元 + 证据 + 代码拥有的决策）
sessions//
harness_state.json              会话本地状态（遮蔽同 id 的全局条目）
refinements.jsonl               会话精化历史

- 技能是真正的 dsh 技能： 已应用的技能编辑会具体化为 /SKILL.md 包（带有来源元数据），位于 Config.skillsDir 下，通过删除/回滚保持同步，且不会触碰同一目录中用户拥有的技能。

经验固化协议（ESP）

经验固化协议（ESP）是这组能力的协议表面，与本包的实现解耦：

| 协议元素 | 载体 | 描述 |
| --- | --- | --- |
| 经验状态模式 | harness_state.json（schemaVersion: 1） | 四类条目——prompt / memory / skill / subagent——每类带有 id / kind / version / content / updatedAt |
| 经验历史 | refinements.jsonl（仅追加） | 每次应用/回滚对应一条 RefinementResult 记录；按 id 回滚 |
| 精化事件 | 会话事件 harness/refinement（已弃用） | 由 0.3.0 及更早的构建在应用/回滚时写入；本构建从不追加它，仅为旧版兼容保留其载荷类型声明 |
| 精化通知 | 代理事件 harness/refined | 载荷 {agent, result}；可由 invariant 及其他插件订阅 |
| 经验注入 | 消息来源 plugin（form: instructions，内容标记中的 digest） | 预注入到模型上下文中；通过 digest 变化去重。已弃用的 harness-state 类型仍被识别，因此旧日志会替换其块而不是重复它 |

任何 dsh 插件都可以通过此协议读写经验（写入状态文件、追加历史、发布事件、注入消息）；本包是该协议的参考实现和主要消费者（规划 / 精化 / 投影 / 自动门控）。

挂载（dsh profile）

一行命令安装到 profile 中（已发布到 npm）：

dsh plugin --profile  add dsh-continual-harness

该包声明了 dsh.bundle，因此 dsh plugin 会将其安装为 profile
层并应用其 cordis.patch.yml。使用
dsh plugin --profile  update dsh-continual-harness@latest 更新。

手动覆盖（发布前，或固定本地检出）：将
cordis.patch.yml 应用到 profile 上，例如
~/.dsh/profiles//cordis.patch.yml；补丁层必须是
顶层 YAML 数组（insert 行追加插件条目；以 id 为目标的行覆盖现有行）：

- insert:
- id: continual-harness
name: dsh-continual-harness
config:
defaultGlobal: true

前置条件：tools、agents、session、llm、systemPrompt 能力插件必须先于本插件加载（其 inject 声明强制了这一点；挂载会推迟到它们加载完成）。

dsh 版本兼容性
已针对 dsh 0.1.2-alpha.3 验证；对等版本下限仍为 >=0.1.0-rc.6，因此较旧的 dsh 版本仍可正常工作。由于 dsh 0.1.2-alpha.3 不再在 profile bundle 内提供 @deepseek-ai/dsh-home-paths，该插件将其声明为硬依赖；@deepseek-ai/dsh-invariants 仅用于类型（开发时），运行时不需要。

配置

| 字段 | 默认值 | 描述 |
| --- | --- | --- |
| harnessRoot | dsh 数据目录 harness/ | 状态根目录（测试中为临时目录） |
| skillsDir | $DSH_HOME/skills | 技能条目物化为 dsh SKILL.md bundle 的目录（dsh 的用户技能根目录） |
| defaultGlobal | 必填 | 当工具调用省略 global 时的目标作用域 |
| maxTrajectoryChars | 12000 | 规划轨迹的最大字符数（双层信号 + 摘要汇总；取决于 plannerPrefixCache 路由） |
| plannerMaxTokens | 32000 | 规划器 LLM 调用的最大 token 数 |
| plannerPrefixCache | auto | 规划输入路由：auto（当会话显示 cacheReadTokens > 0 时使用路由 A 热会话前缀，在回复被截断时回退到路由 B）、session（始终使用路由 A）、off（始终使用路由 B 摘要） |
| plannerPrefixMaxChars | 12000 | 路由 A 会话前缀的尾部偏向字符上限（deriveMessages 文本） |
| trajectorySignalRatio | 0.5 | 路由 B 轨迹预算中逐字保留（信号层）与摘要处理的比例 |
| autoRefine | {turnInterval: 25, compact: true, cooldownMs: 1200000} | 自动精炼：轮次间隔门控、压缩结束门控、冷却时间、禁用开关 |
| requireGlobalApproval | false | 全局写入提交前需要明确的人工批准（保守模式） |
| maxInjectedEntriesPerKind | 6 | 每种类型已排序注入条目的正整数上限（步长 1，最小 1） |
| wrapupEnabled | true | 注册可选的 harness_wrapup 会话收尾工具 |
| diagnosticsEnabled | true | 在每次提交的精炼后运行应用后结构诊断 |
| securityEnabled | false | 启用本地安全（凭据模式）诊断提供程序 |
| auditReviews | true | 将每个门控裁决追加到 harness 根目录下的 reviews.jsonl |
| logToFile | true | 将 harness 日志持久化到 continual-harness.log（JSONL，0600，轮转） |
| logMaxBytes | 5242880（5 MB） | harness 日志文件的轮转上限 |
| maxEntryGrowth | 0.5 | 每次提交的条目增长比例上限；0 禁用该检查 |
| protectedKinds | ['skill'] | 自动路径不可修改的类型（保留；按条目的 protection 是强制执行的防护） |
| benchmark | {enabled: true, defaultRuns: 1, maxRuns: 3, passThreshold: 60, regressionTolerance: 0, maxFailedCells: 0} | 显式 harness_benchmark 工具：每侧每个用例的迭代次数、运行上限、仅报告通过线、非回归容差、最大失败候选单元数 |

精炼
两个入口点：harness_refine 工具（可供 LLM 调用）和 /refine 斜杠命令（当宿主提供 commands 能力时）。

harness_refine — mode: 'plan'（默认）根据指令进行规划并原子化提交；mode: 'rollback' 接受一个 rollbackId 以及显式的 --local / --global 作用域，用于回滚已提交的细化。当 requireGlobalApproval 为 true 时，全局写入需要人工批准。

/refine — 语义相同，由人工输入：

/refine --local organize my memories
/refine --global
/refine rollback  --local
/refine rollback  --global

裸 /refine 在默认作用域下进行无指令规划。输出：status、scope、refinement、applied、rejected、summary，以及启用时的 diagnostics: 行。

治理

每条写入路径都经过三道护栏：影响最小化（固定契约校验；update/delete 需要一行 reason；maxEntryGrowth 限制每次提交的增长量）、合法性硬拒绝（base_system_prompt 和受保护条目不可变；在 local 细化期间全局条目为只读），以及必要性软门控（被拒绝的审查永远不会到达存储）。每次已提交的细化都可通过 id 回滚。

全局写入默认零批准；设置 requireGlobalApproval: true 可先询问用户。实时查看插件日志：

tail -f ~/.dsh/harness/continual-harness.log

基准测试

验证层是显式且单一入口的：一个 harness_benchmark 操作工具驱动整个工作流，且从不自动触发细化——基准测试路径中没有任何东西会启动 harness_refine 或自动门控，REJECTED 决策仅被报告和记录，从不回滚。存储位于 /benchmark/ 下（参见上文的数据布局）。

最小序列为 new → add-case → freeze → capture-reference → apply refinement → run → status（冻结的用例材料不可变且经过哈希；status 列出用例、快照和最近的运行）。有两个步骤存在真正的微妙之处：

- capture-reference 必须在你想要验证的细化之前运行：候选对象随后被推导为所捕获的参考加上恰好该细化，因此在变更之后捕获会使增量无法证明。
- run 针对参考（reference_snapshot_id + refinement_id）对指定的细化进行 A/B 评估。候选对象必须是单一指定的增量——由参考加上该细化所记录的应用编辑推导而来，并在任何评估之前于代码中证明；发生漂移或多重变更的候选对象会被拒绝（benchmark:run:candidate-delta）。双方以存储顺序运行相同的冻结用例，并使用相同的 runs/provider/model。

run 返回代码所拥有的决策（src/score.ts），而非模型裁决：

{
"action": "run",
"ok": true,
"run_id": "run-...",
"refinement_id": "refine-1",
"status": "ACCEPTED",
"reference_overall": 70,
"candidate_overall": 90,
"regression_cases": [],
"failed_cells": 0,
"feedback": ["reference ok", "candidate better"],
"auto_rollback": false,
"runs": 1,
"cells": 2
}

- 每个单元格的分数为 0..100；失败的单元格带有 score: null —— 失败绝不会被计为 0 —— 并且会被排除在总体均值之外。
- passThreshold（默认 60）仅用于报告：它从不作为接受与否的门槛。只有当双方都不缺少可用单元格、候选方的失败单元格数量保持在 maxFailedCells 以内，且没有任何总体或逐用例回归超过 regressionTolerance（默认 0）时，一次运行才会被判定为 ACCEPTED。
- 每次运行都会将其完整记录（包含执行器证据的单元格 + 决策）追加到 benchmark/runs.jsonl；评估只读取捕获的快照，并且只写入该记录，绝不触碰 reviews.jsonl、harness 状态、注入遥测或技能文件。

开发

该插件是自包含的：devDependencies 固定了已发布的
@deepseek-ai/ 包（rc 版本），因此 pnpm install、pnpm run
typecheck、pnpm test 和 pnpm run build（tsc 输出
lib/types/.js + *.d.ts；"." 和 "./invariant" 导出指向这些
产物）在干净的检出中均可正常工作 —— CI 和 OIDC 发布工作流
运行相同的步骤。peerDependencies 声明了消费者
（宿主 dsh 安装）必须满足的 semver 范围。

最高到 0.3.0 的插件构建会将注入的概览记录在插件定义的
harness-state 消息源下。已发布的 Session 格式迁移仅
对平台源类型进行分类，因此一旦宿主使用支持 v3 的 dsh 读取它，
这样一条消息就会使整个存储的产物不可读（cannot safely transform unclassified message source）。
本次构建改为记录一个已分类的
plugin 源；任何代际的已存储日志都可以通过
node scripts/repair-harness-state-logs.mjs 离线修复（默认试运行；--apply
会备份每个产物并以原子方式替换它，而在
--min-age-seconds 内写入的产物会被跳过 —— 参见 --help）。

已知限制与推迟的工作

- 没有使用真实 LLM 的端到端测试：completeViaAgent 依赖于已加载的 llm 能力和提供方/模型配置；测试使用桩 Complete 覆盖规划/审查路径。真实端到端测试需要 DEEPSEEK_API_KEY。
- compaction/end 不属于该插件的类型联合；驱动程序在类型收窄后通过字符串比较触发它，而当压缩能力未加载时，该门控会被静默跳过。
- 投影去重是进程内的 WeakMap：会话重启后的第一步会重新注入（无状态且幂等，但会多一次注入）。
- 并发写入采用最后写入者胜出：多个进程同时精炼同一目录可能会相互覆盖；规划期间的基线冲突检测只能捕获读后写竞争，而无法将其串行化。
- 自动优化失败会静默降级（仅记录日志），绝不会中断会话。
- 内容收缩防护（拒绝在单次提交中将条目收缩过多的更新）是计划中的后续工作，尚未实现；目前只有 maxEntryGrowth 限制更新可使条目增长的程度。
- 专门的治理工具条目被推迟。