@dsh-enhanced/assistant-evolution
审批门控的行为自演化。助理观察自己在重复情境下的结果，当证据足够时提出一条行为规则，经 owner 批准后该规则才作为顾问性上下文影响后续会话。owner 可随时通过二次审批撤销 exact rule；可选的低风险自治通道也只能撤回一条已证实无效的 exact rule，二者都不能创建、修改或扩权。
这不是"让模型自己改自己"。它的价值在于把"经验"变成可审计、可撤销、可解释的持久对象：每条规则都能回答"依据哪些结果、谁批准的、有没有真的变好"。
兼容性
已针对 DeepSeek Harness 0.1.2-rc.1 验证。详见仓库兼容性基线。
安装
dsh plugin --profile <name> add @dsh-enhanced/assistant-evolution
依赖 @dsh-enhanced/assistant-policy 与 @dsh-enhanced/assistant-evaluation。未组合 Policy 或权威
Evaluation 账本时拒绝加载，而不是降级为无治理运行。
@dsh-enhanced/assistant-delivery 是可选 peer：存在时，插件从当前 Agent 的 authenticated owner route
派生 principal，并让 Policy 在创建提案的同一事务中保存 dispatch；不存在时只允许可信 headless 调用方
通过 Service API 显式传 principal。模型工具永远不能选择 principal 或审批期限。
独立 supervised-growth analyst 必须有 Delivery owner route，因此不使用 headless 降级。规则结算时生成的
application receipt 即使 Delivery 暂时不可用也会留在 Evolution 自己的 durable outbox，恢复后原位更新原审批卡。
该 presentation 不是公开 Delivery service 方法：Delivery 只向当前 Evolution producer generation 签发私有、
可撤销的进程内 capability。registration 不进入 Agent、tool schema、proposal payload 或 read API；服务替换、
卸载或 disposer 后旧 capability 立即失效，durable outbox 只会等待有效的新 registration 重试。
@dsh-enhanced/assistant-automations 也是可选 peer：仅当 Evaluation receipt 引用 automation run 时，
Evolution 才要求它提供并重新验证 exact production-run proof。普通非自动化 Evaluation 投影不依赖它。
默认 Cordis patch 会为完整 supervised-growth 组合声明该顺序依赖。
闭环
Evaluation 客观/验证结果 → 计算候选 → 提案 → owner 批准 → 提交规则 → 注入为顾问上下文
↑ │
└──── 后续可信结果继续被观察 ──→ evidence retire / owner undo / 自动 rollback ┘
关键阶段都有独立边界：
- 观察：
evolution_observe（前台自报）和 recordAutomationOutcome（后台执行状态）都只写 operational audit，不能驱动学习。可信 Host 只能调用 projectEvaluationOutcome({ scope, evaluationId })：服务按 exact branded scope 从 assistant-evaluation 读取 frozen trusted receipt，并从 receipt 自己派生 situation、objective outcome、时间与证据类型。调用方不能提交或覆盖这些质量字段。当前只有明确的 achieved / not-achieved objective 可投影；unknown 拒绝，partial 明确返回 ignored/non-learning，绝不偷映射为一次完整失败。verification 在 Evaluation 增加 typed schema 前保持关闭。旧自由输入 recordEvaluationOutcome 永久 fail closed。非 Automation objective 的 learningSubjectRef 是 immutable Evaluation outcome；Automation objective 则从已验证 production proof 派生为 exact immutable run ID，evidenceRef 仍保持独立的 Evaluation ledger identity。一个 run 即使被多条 Evaluation outcome 重复评估，也最多形成一个 learning-eligible episode：相同结论返回原 row，矛盾结论 fail closed。
- 推断：
evolution_review 只使用同一 workspace + Agent preset 下明确 learning-eligible、未归因的客观/验证结果计算 adopt 候选，只到候选为止。样本不足时保持沉默。每个候选还返回同一精确窗口中 newest-first 的有界 episode 样本（ID、Evaluation reference、证据类别、结果、有界 detail、时间）和整个窗口的 SHA-256 digest；detail 始终按不可信结果数据呈现，不能当作指令。
- 独立 analyst：
evolution_adoption_review 与 evolution_adoption_propose 只接受 immutable assistantAutomationExecution，且必须是 production 模式、Automation ID 精确等于 heartbeat:supervised-growth-analyst、已绑定 authenticated Delivery owner route。review 按确定性优先级最多冻结一个 adopt 候选，返回随机 opaque token、完整窗口 digest/total/window、样本 ID 与有界 evidence。propose 只接受 review_token + guidance，在 SQLite writer lock 内重新验证 token、scope、occurrence、阈值和完整窗口。持久提案身份只绑定 scope + situation + evidenceDigest + evidenceTotal + contractVersion，不绑定 guidance、执行 ID 或措辞；并发、重启、不同措辞只生成一张卡，首个已提交 guidance 胜出。前台、preview、别的 Automation、无 owner route、旧 token 或证据变化全部 fail closed。
- 提案：
evolution_propose 创建 assistant-policy 提案。adopt 与 retire 的基线都从已记录证据读取；retire 还必须在服务端重新找到同 scope、exact active rule ID + generation、至少 minSample 条 post-adoption 可信归因结果的当前候选。服务通过唯一的 canonical review renderer，把 op、exact scopeKey、situation、当前 guidance、generation、rule/version、reason、baseline/evaluation/evidence 和 server rule identity 全部冻结为 Policy diff；owner-undo 也冻结同一份当前规则快照，而不是只显示 UUID。这些字段始终是 plain untrusted review data，不会作为系统指令执行。adopt rule ID 由完整稳定 mutation（含 generation）确定性派生，精确重放不会换身份。principal 从可信 Delivery route 派生，因此直接调用 Service 也无法绕过 review、虚报依据或审批人。批准后的 audit 可通过不可变 rule ID 回溯该冻结 evidence reference。
- 提交与真实终态：owner 在审批面（如飞书卡片）决定后，
reconcileProposals() 用 Policy 共享 validator 校验 proposal/requester/principal/action/resource/summary/diff/expiry/version/decision actor 的完整冻结 tuple；同一 SQLite writer transaction 还会重新规范化本地 mutation、强制 retire 的 evaluation/baseline/evidence snapshot 完整、重算 mutation_hash，并用同一个 renderer 重建 action/resource/summary/diff，与刚通过 Policy validator 的 expectation 及库内 expectation 精确重绑定。即使 Policy 已批准，legacy 无证据行、JSON 字段剥离、同步改写 JSON+hash，或 retire/adopt 换 op 都会持久化为 conflicted，绝不应用规则。该事务同时生成 domain-authoritative applied / rejected / expired / conflicted receipt，冻结 local/policy proposal、operation、exact rule/version/status、terminalAt 与 SHA-256 digest。独立 application outbox 通过 Delivery 的 approval-application:<policyProposalId> presentation 原位更新 approval-card:<policyProposalId>；Delivery 失败不回滚规则，崩溃后重放同 revision/digest，且从不把 Policy approved 自己显示成已应用。
- owner 即时撤销：
evolution_undo 只接收 rule_id + expected_version + operation_id，不接收 principal、reason、guidance 或权限字段。当前 Agent 提供 exact workspace + preset，Delivery 的 authenticated owner route 提供 principal；工具只创建独立 evolution.owner-undo Policy 审批，不能自行决定。owner 批准后，reconcileProposals() 对冻结 scope/rule/version 做 CAS 并立即 retire；无需回归样本，因为这是 owner 撤回自己的既有批准。错误 owner、跨 scope、旧 version、被另一张卡抢先结算的旧卡都拒绝或落为 conflicted。精确 operation replay 返回同一 durable proposal/rule receipt，重启后也可继续结算。
- 低风险回滚（默认关闭）：
evolution_rollback 只接收 rule_id + expected_version。启用 autonomousRollback 且 Policy 对 exact {action: rollback, resource: evolution/rule:<id>} 放行后，Host 在 BEGIN IMMEDIATE 内重新读取同 scope、exact rule ID + generation 的可信 post-exposure 证据；只有样本达到 minSample、失败率达到 retireFailureRate，并且没有优于 adoption baseline 时才 retire。reason、risk=low、完整窗口 digest 和有界 episode ID 均由 Host 生成并与规则 compare-and-set、audit 在同一事务提交。它不能 adopt、改 guidance、改 Policy、选择证据或降低门槛。
supervised-growth/v2 的固定 Host 控制面无需伪造 Agent，也不读取 session header：Host 先用
canonicalEvolutionHostScope({ workspace, preset }) 创建冻结 branded scope，再调用
hostCandidates、hostListRules 或 singular hostRollbackOne。每次调用必须携带 authenticated owner
principal + operationId，服务会用固定 background Policy subject
dsh-enhanced-assistant-recovery 对 exact workspace/action/resource 授权。复制/序列化 scope 会移除 brand
并 fail closed。Host rollback 与模型入口复用同一事务门，因此只有 exact exposure receipt 归因的
quality-eligible Evaluation evidence 可触发；recordAutomationOutcome 的 operational 行永远不算。
三条结构性安全边界
这三条不是文档承诺，而是有测试守护的结构约束：
- 不能自我批准或自我扩展。服务没有
decideProposal。任何 adopt / guidance 变化只能由 owner 在 policy 账本上决定，本插件只能读取该决定。可选 rollback 只能删除 exact 旧 guidance，不能授予新行为。
- 不能扩权。guidance 以数据形式注入，且
assistant-policy 从不读取规则表。规则能改变"怎么做"，永远不能改变"允许做什么"——每次工具调用仍独立授权。
- 不能原地改写。改变行为是 retire-then-adopt，两步各自审批。原地修订会让旧批准悄悄覆盖新内容。
此外：同一 workspace + Agent preset + situation 至多一条 active 规则（唯一索引保证），因此一个 Agent scope 内注入的 guidance 不会自相矛盾，也不会泄漏到其他 workspace。
每次 adopt 生成新的不可变 UUID rule ID，并按同 scope + situation 单调递增 generation。retire 后重新
adopt 不会复用旧 ID；重新积累基线时也只看 retirement timestamp 之后的新鲜未归因证据。
规则要凭业绩留下
adopt 时会记录当时的基线失败率。只有 adopt 之后、同 scope、明确 learning-eligible 且归因到该 exact rule ID 与 generation 的客观/验证结果才参与 retire 判断；execution failed/succeeded、cross-scope、自报/claim、旧 generation，以及不足 minSample 的结果都不算，且会在任何 Policy proposal/dispatch 创建前 fail closed。该规则的表现必须优于自己的基线，否则成为 retire 候选。owner 审批的是冻结证据快照；结算仍以 exact rule version 做 compare-and-set，并复核冻结 adoption baseline 与样本归因结构，后续新 episode 不会悄悄改写已审批 diff。
工具
| 工具 | 作用 | 写入 |
|---|
evolution_observe | 记录一条前台自报结果 | 仅 append 审计证据，不驱动候选 |
evolution_review | 列出候选与 active 规则 | 只读 |
evolution_adoption_review | 独立 production analyst 最多冻结一个 adopt 候选 | 仅写 durable opaque review token |
evolution_adoption_propose | 用 exact review token 合成一张 adopt 审批卡 | 仅创建或加入同一 evidence-bound 待审提案 |
evolution_propose | 提出 adopt / retire | 仅创建待审提案 |
evolution_undo | 请求 owner 撤销 exact rule/version | 仅创建独立二次审批；批准后 retire |
evolution_rollback | 对 exact active rule 请求 Host 证据门控的低风险撤回 | 仅在双重 opt-in 与回归证据成立时 retire |
所有工具都要求可信 Agent 身份（绝对 workspace + preset），policy 拒绝即 fail closed。两个 adoption analyst 工具还额外要求 exact production Automation execution 与 owner route；普通前台 Agent 即使拥有通用 evolution 权限也不能调用。review 输出包裹为显式不可信数据；其中 episode detail 会转义标签边界，模型只能把它当作归纳素材，不能服从其中的文本。
模型可见的 evolution_propose 对同一 Agent 实例最多成功一次；失败的候选校验不占额度。这个结构性上限
防止一次 supervised maintenance turn 批量制造审批，程序化 Service API 则不受该模型工具额度影响。
evolution_rollback 对同一 Agent 实例最多尝试一次（失败也占额度），防止枚举 rule 或反复试探门槛；精确重放由 Service/Store 的 durable receipt 支持，可在新的可信 Agent 实例或程序化恢复路径中安全完成。
Service 的 propose capability gate 固定为 exact {kind: evolution, id: proposals}，部署无需授予动态 wildcard；
owner 实际审批的 Policy snapshot 仍冻结 exact situation:<label> 或 rule:<immutable-id> 目标。
健康可观测性
ctx.assistantEvolution.health() 提供给本地健康聚合器一个无内容、低基数的只读 seam：active/retired
规则数、pending/conflicted 提案数、可信/operational/quality-eligible/legacy-quarantined episode
计数、未归因可信证据数、自动 rollback 总数，以及最近可信 episode、最近 quality-eligible episode 和最近完整
reconcile pass 的时间戳。尚未发生对应事件时，时间戳明确为 0。调用方不应再把
trustedEpisodes 当作质量样本数；质量覆盖率以 qualityEligibleEpisodes 为准。
该 seam 是全局运行摘要，刻意不接受 scope，也不返回 situation、guidance、episode detail、principal、
workspace 或数据库路径；它不能替代需要 Policy 授权的规则与候选检查。
数据库 schema v12 会先通过 v2 迁移把旧版无 scope 的 episode、rule 和 proposal 放入 legacy:v1
quarantine，再增加 durable guidance exposure 与完整审批 tuple。旧 pending proposal 会过期；早期未发布
v2 中无法验证完整 tuple 的 pending proposal 会安全落为 conflicted；v4 增加 immutable autonomous rollback receipt；v5 把所有旧 episode 标为 legacy-unknown 且 learning_eligible=0，并把所有基于旧证据尚未结算的 pending Evolution proposal 标为 conflicted。v6 先以 (scope, immutable Evaluation ref) 建立唯一身份；v7 重建 episode CHECK，使权威投影具有独立的 evaluation provenance。v8 新增独立 learning_subject_ref 和数据库唯一约束 (scope, learning_subject_ref)，从结构上阻止同一 Automation run 被多条 Evaluation outcome 放大样本数，同时不偷换 evidence_ref 的 Evaluation 语义。v7 旧 learning row 无法事后证明其 Automation run identity，因此迁移时一律保守降为 legacy-unknown + learning_eligible=0，并把受影响 scope 的 pending proposal 标为 conflicted；operational audit 不受影响。旧版 binary automation failure 或重复 Evaluation 结果都不能污染候选、adoption、延迟激活或 rollback。旧规则不会作为 wildcard 注入。
迁移和 episode/proposal settlement 使用 SQLite writer transaction；多进程同时打开、重放或提交时只有一个
winner，其余读取 winner 并做精确幂等比较。
v9 开始只接受 Evaluation 的 versioned task projection；v10 增加按 production occurrence 冻结的 analyst review ledger；v11 增加与 proposal settlement 同事务提交的 application receipt 和独立 presentation outbox。v12 为 task projection、analyst review 和候选证据加入 authoritative scope watermark 与完整 task-revision tuple：所有依赖证据的创建或结算都必须在 Evaluation 的 trusted writer fence 内重新证明；缺少这组冻结证据的旧 pending proposal 一律转为 conflicted，不会在稍后被批准时应用。旧终态在启动时会补投 outbox，新终态不会依赖 pending-proposal 扫描。
跨 Evolution/Policy 数据库创建审批时，Evolution 先持久化本地 intent，再调用 Policy 的原子
recoverOrCreateProposal(notAfter)：同一 writer transaction 内只会恢复 exact proposal、在绝对截止时间前创建，
或在截止后永久 tombstone 该 idempotency key。这样 lookup/create 竞争和重启都不会续期或留下 orphan approval card。
配置
| 字段 | 默认值 | 作用 |
|---|
databasePath | 必填 | SQLite 绝对路径 |
evaluationWindow | 20 | 每个 situation 参与判断的最近 episode 数 |
minSample | 5 | 产生候选所需的最小样本 |
adoptFailureRate | 0.4 | 达到该失败率才考虑 adopt |
retireFailureRate | 0.4 | 达到该失败率考虑 retire |
maxCandidates | 10 | 单次 review 候选上限 |
maxEvidenceSamples | 8 | 每个候选返回的 newest-first 不可信 episode detail 样本上限；digest 始终覆盖整个判断窗口 |
maxInjectedRules | 12 | 每会话注入规则数上限 |
maxGuidanceBytes | 4096 | 注入块字节上限（按规则边界截断） |
maxRuleGuidanceBytes | 2048 | 单条 guidance 字节上限 |
defaultProposalTtlMs | 900000 | 提案默认有效期 |
reconcileIntervalMs | 15000 | 提交延迟审批的轮询间隔；0 关闭定时器 |
reconcileLimit | 50 | 每轮检查的待决提案上限 |
autonomousRollback | false | 是否启用仅能 retire exact guidance 的低风险代码通道；仍需 Policy 单独允许 exact rollback action |
与 assistant-automations 的可选联动
若同时安装 @dsh-enhanced/assistant-automations，后台运行结束会成为可信的运行审计，但不会自动成为质量证据。Evolution 只在
agent/session-start guidance 注入成功之后，持久化 exact
sessionId + workspace + Agent preset + situation + ruleId + generation receipt。Automations 必须在 runner
返回 actual session ID 后调用 captureAutomationExposure(...)；缺 receipt、错 session/scope、未实际注入，
或同 situation 存在多代 receipt 时都返回 undefined，绝不根据“当前 active rule”猜归因。
该绑定是单向、可选、结构化的：automations 不依赖本插件，没有 recorder 或 recorder 抛错时运行完全不受影响。cancelled 不计入——它不说明方法好坏，计入会污染失败率。
后台入口 recordAutomationOutcome 刻意最小：只能追加 operational audit。只有 payload 的
automationId/sessionId/ruleId/guidanceVersion 与 durable receipt 完整一致时才写入可信规则归因；否则
ruleId 仅作为 claim 留档。无论 execution 是 succeeded 还是 failed，该入口都固定
learningEligible=false。权威 Evaluation 必须经独立的 projectEvaluationOutcome 入口，由服务读取
exact trusted receipt 并派生 objective evidence，才能参与统计。若 receipt 引用 automation run，Evolution 还会直接向
Automations 校验 production-only immutable proof，并把 exact immutable run ID 写成独立学习主体；多条 Evaluation row 不会把一个 run 重复计数。Recovery 或其他 caller 的转述不算。它不能 adopt / retire / 读取规则。因此 automation 依然无法在没有 owner
决定的情况下改变自己的行为。
Automation Agent 的 Host execution context 若明确为 preview，Evolution 在 agent/session-start 不注入
active guidance，也不写 exposure receipt；只有明确 production 或缺失 automation context 的普通前台会话
可进入注入路径。未知/畸形的未来 mode 按非 production fail closed。
成功注入的 receipt 也让同一 session 在正常重启/resume 后不重复注入同一 immutable generation。新代规则
可作为增量 guidance 注入；若旧规则已经进入该 session 的 LLM 历史，插件无法从上游不可变历史中物理删除
它，但 retired guidance 不会再次注入，也不会再为新 outcome 生成可信归因。
生产 Automation 注入时，exact automation:<id> 规则会在 maxInjectedRules 的全局切片之前置顶；即使
scope 内已有超过 12 条 active rule，目标规则仍会进入有界 guidance block 并写入 exposure receipt。普通
foreground 会话继续按 situation 稳定排序并受相同 rule-count/byte 上限约束。若 session-start 早于
Automation execution context 安装，post-setup injectAutomationGuidance 会依据 durable exposure 优先补入尚未
注入的 exact rule，不会因一次较早的全局切片而永久失去归因。
权限与非目标
- 文件系统：只读写配置的 SQLite 数据库及其 WAL/SHM 辅助文件。
- 网络、子进程、凭据、浏览器、安装脚本：无。
- 不修改 Skill、prompt 模板、插件代码或 policy 规则。"自演化"仅限经批准的顾问性 guidance。
- 不做向量检索、自动遗忘、跨设备同步、多用户 ACL。
- guidance 会进入模型上下文：不要在 guidance 中写入密钥或敏感数据。
- 自动 rollback 是收缩行为能力的安全阀，不是通用“AI 自批”入口；部署若启用，Policy 只应授予
rollback，不要把它复用为 adopt、权限或外部副作用授权。
- Host 控制面还需 Policy 明确允许 background subject
dsh-enhanced-assistant-recovery 的 inspect 和按需 rollback；仅拿到 Cordis service 引用不等于获得权限。
整体目标 v3 验收通过 Evaluation 以 goal-outcome subject 投影，不能与步骤验收合并。schema 15 迁移保留旧 task learning state/revisions、retract 与 episode 关联；整体成功仍只是该次独立观测，不代表能力提升已通过比较基线。
