持续进化引擎 jasen215/dsh-continual-harness

dsh-continual-harness

一个 DeepSeek Harness (DSH) 插件，让 AI 智能体自我改进：靠持久记忆、定期复盘与精炼、跨会话知识共享、失败自动回滚，实现持续学习。它构成一条闭环：计划 → 验证 → 应用 → 回滚。

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

能力

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

| 能力 | 机制 |
| 状态投影（每一步注入 harness 上下文） | agent/pre-step waterfall 监听器；内容摘要变化时增量注入 |
| 复盘与自动精炼 | session/event 监听器，在轮次间隔 / compaction 结束时触发；自动跑 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 渲染 + 文件对账（生成的技能是真正的 dsh 技能） render.ts 面向模型的概览 / 摘要 / 历史渲染（按排名注入） usage.ts 注入遥测键与内存内用量聚合 wrapup.ts 确定性的会话收尾建议（保留/提升/归档） planner.ts LLM 规划提示词与 JSON 解析（plan / auto-refine 评审提示词） store.ts HarnessStore：存储 + 事件发布合体（会话事件 + 智能体作用域事件） complete.ts completeViaAgent：通过 ctx.get('llm') 完成补全 benchmark.ts 基准用例/快照 + 原子基准存储持久化 evaluate.ts 隔离的逐单元执行器/评审器评估（证据 + 评分） score.ts 代码侧聚合与 ACCEPTED/REJECTED 决策 tool.ts harness_refine / harness_wrapup / harness_benchmark 工具 projection.ts 前置步骤投影（摘要去重、<harness_state> 注入） 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）

数据布局

<harnessRoot>/ 共享 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/<snapshotId>.json 捕获的参考快照（只读合并后的 harness 状态） runs.jsonl 仅追加的 A/B 运行记录（单元 + 证据 + 代码侧决策） sessions/<sessionKey>/json harness_state.json 会话本地状态（覆盖同 id 的全局条目） refinements.jsonl 会话精炼历史

- 技能就是真正的 dsh 技能： 应用后的技能编辑会落地为 <name>/SKILL.md 包（带来源元数据），放在 Config.skillsDir 下，由删除和回滚保持同步，不会碰同一目录下用户自己的技能。

经验固化协议（ESP）

经验固化协议（ESP）是这套能力集的协议接口，与本包的实现解耦：

| 协议元素 | 载体 | 说明 |
| 经验状态 schema | harness_state.json（schemaVersion: 1） | 四类条目 —— prompt / memory / skill / subagent —— 每条含 id / kind / version / content / updatedAt |
| 经验历史 | refinements.jsonl（只追加） | 每次 apply/rollback 写一条 RefinementResult 记录；按 id 回滚 |
| 精炼事件 | 会话事件 harness/refinement（已弃用） | 0.3.0 及更早的构建在 apply/rollback 时写入；本构建从不追加它，只为兼容旧版本保留其 payload 类型声明 |
| 精炼通知 | 智能体事件 harness/refined | payload 为 {agent, result}；不变量和其他插件都可订阅 |
| 经验注入 | 消息来源 plugin（form: instructions，内容标记里带 digest） | 预先注入模型上下文；按 digest 变化去重。已弃用的 harness-state 类型仍会被识别，这样旧日志会替换自己的块，而不是重复注入 |

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

挂载（dsh 配置档）

一行命令装进配置档（已发布到 npm）： sh
dsh plugin --profile <name> add dsh-continual-harness

本包声明了 dsh.bundle，所以 dsh plugin 会把它作为配置档层安装，并应用它的 cordis.patch.yml。更新用
dsh plugin --profile <name> update dsh-continual-harness@latest。

手动叠加（发布前，或想固定本地 checkout）：把 cordis.patch.yml 应用到配置档上，例如 ~/.dsh/profiles/<name>/cordis.patch.yml；补丁层必须是顶层 YAML 数组（insert 行追加插件条目；按 id 定位的行覆盖已有行）： yaml
- insert:
- id: continual-harness
name: dsh-continual-harness
config:
defaultGlobal: true

按 id 定位的行会替换目标的整个 config，而不是合并，所以只改一个键也必须把依赖的键一并重写；省略的键回落到下面的默认值。覆盖一个无关的键永远不会禁用插件。
前置条件：tools、agents、session、llm、systemPrompt 这几个能力插件必须先于本插件加载（插件的 inject 声明会强制这一点；加载完成前挂载会推迟）。

dsh 版本兼容性

已针对 dsh 0.2.0-rc.2 验证——类型检查、lint、构建、完整的 651 项测试套件，以及在 0.2.0-rc.2 运行时上真实启动一个配置档——并针对 0.1.7-rc.1 用同一套测试验证通过。一个 peer 范围覆盖了从 0.1.5-rc.1 到 0.2.0-rc.2 的所有运行时（>=0.1.5-rc.1 <0.2.1），因为这个范围正是 dsh 在挂载插件或配置档 bundle 之前，于插件/运行时兼容性门禁中评估的范围。dsh 0.1.7 引入了这道门禁：当插件的 @deepseek-ai/dsh peer 不满足正在运行的版本时，它的配置档 bundle 会被跳过，所以放宽范围才能让同一份源码在旧运行时和当前运行时上都能加载。从 dsh 0.1.2-alpha.3 起，配置档 bundle 内不再提供 @deepseek-ai/dsh-home-paths，因此插件把它声明为硬依赖；@deepseek-ai/dsh-invariants 只用于类型（开发期），运行时不需要。

配置

| 字段 | 默认值 | 说明 |
| harnessRoot | dsh 数据目录 harness/ | 状态根目录（测试中为临时目录） |
| skillsDir | $DSH_HOME/skills | 技能条目落地为 dsh SKILL.md bundle 的目录（dsh 的用户技能根目录） |
| defaultGlobal | true | 工具调用省略 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） |
| injectionAnchor | stable | 注入块按什么选取：stable（会话开场请求 + 项目 cwd——整个会话都是同一批条目，话题切换后服务商缓存的前缀依然有效）或 query（根据实时提问重新选取） |
| 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 —— 语义相同，由人手动输入： sh /refine --local organize my memories /refine --global <instructions> /refine rollback <id> --local /refine rollback <id> --global

裸 /refine 在默认作用域下不带指令地制定计划。输出：status、scope、refinement、applied、rejected、summary，启用时还会多一行 diagnostics:。

治理

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

全局写入默认零批准；设置 requireGlobalApproval: true 可先询问用户。实时查看插件日志： sh tail -f ~/.dsh/harness/continual-harness.log

基准测试

校验层显式且单入口：一个 harness_benchmark 动作工具驱动整个工作流，绝不自动触发精炼——基准测试路径中没有任何东西会启动 harness_refine 或自动门禁，REJECTED 裁决只上报和记录，绝不回滚。存储位于 <harnessRoot>/benchmark/ 下（见上文数据布局）。
最小流程是 new → add-case → freeze → capture-reference → apply refinement → run → status（冻结后的用例材料不可变，且带哈希；status 会列出用例、快照和最近的运行记录）。其中两步有真正的坑：

- capture-reference 必须在你要验证的 refinement 之前运行：候选版本稍后会被推导为捕获到的 reference 加上恰好这个 refinement，所以改完再捕获，delta 就无法证明。
- run 会针对 reference（reference_snapshot_id + refinement_id）对指定的 refinement 做 A/B 评估。候选版本必须是唯一指定的 delta——由 reference 加上 refinement 记录的已应用编辑推导而来，并在任何评估之前用代码证明；一旦候选版本发生漂移或包含多处改动，就会被拒绝（benchmark:run:candidate-delta）。两侧都按存储顺序运行同一批冻结用例，使用相同的 runs/provider/model。

run 返回的是代码给出的判定（src/score.ts），不是模型裁决： json { "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
}

- 每个 cell 的分数是 0..100；失败的 cell 带 score: null——失败绝不会按 0 计入——并且会从总体均值中排除。
- passThreshold（默认 60）只用于报告：它从不作为接受与否的门槛。只有两侧都有可用 cell、候选版本的失败 cell 不超过 maxFailedCells、且总体或单个用例的回归都没有超过 regressionTolerance（默认 0）时，一次运行才会是 ACCEPTED。
- 每次运行都会把完整记录（带执行器证据的 cell + 判定）追加到 benchmark/runs.jsonl；评估只读取捕获到的快照，只写入这条记录，绝不碰 reviews.jsonl、harness 状态、注入遥测或技能文件。

Development

插件是自包含的：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 范围。

scripts/githooks/pre-commit 在每次提交时运行本地回归门禁（npm run verify，约 4 秒），这样 CI 在推送时才会发现的回归，会在提交前就被抓住；当 verify/latest.json 还不存在时，它会先引导生成该文件。.git/ 下的钩子不受版本控制，所以每个克隆都要启用一次：

git config core.hooksPath scripts/githooks

0.3.0 及之前的插件构建会把注入的概览记录在插件定义的 harness-state 消息来源。已发布的 Session 格式迁移只对平台来源种类做分类，所以只要有一条这样的消息，宿主用支持 v3 的 dsh 读取时，整个已存储的产物就会变得不可读（cannot safely transform unclassified message source）。本构建改为记录一条已分类的 plugin 来源；任何代次的已存储日志都可以离线修复，命令是 node scripts/repair-harness-state-logs.mjs（默认 dry run；--apply 会先备份每个产物，再原子替换，写入时间在 --min-age-seconds 之内的产物会被跳过——详见 --help）。

已知限制与待办工作

- 没有接真实 LLM 的端到端测试：completeViaAgent 依赖已加载的 llm 能力以及服务商/模型配置；测试用桩 Complete 覆盖规划/评审路径。真实 e2e 需要 DEEPSEEK_API_KEY。
- compaction/end 不在插件的类型联合里；驱动在类型收窄后用字符串比较触发它，而压缩能力未加载时，这道闸门会被静默跳过。
- 投影去重是进程内的 WeakMap<Agent, digest>：会话重启后的第一步会重新注入（无状态且幂等，但多一次注入）。
- 并发写入是最后写入者胜出：多个进程同时精炼同一目录可能互相覆盖；规划期间的基线冲突检测只能抓到读后写竞态，无法把它们串行化。
- 自动精炼失败会静默降级（只记日志），绝不打断会话。
- 内容收缩保护（拒绝在单次提交中把某个条目收缩过多的更新）是计划中的后续工作，尚未实现；目前只有 maxEntryGrowth 限制一次更新能让条目增长多少。
- 专用的治理工具入口推迟了。