jonah791/dsh-agent-self-test

dsh-agent-self-test

一句话：把「猜想 → 反驳 → 学习」做成运行时机制——你写下关于自己行为的可证伪陈述，插件在真实工具调用中被动采证，证据够数就把 finding 送到你面前，你裁决它。

为什么值得用：被动统计（比如「工具命中率」「错误计数」）只能描述行为，不能裁决猜想——它无法回答「我说过的那条行为规则，到底是真的是假的」。本插件把自我认知变成可证伪的假设 + 真实行为做裁判：每条假设有陈述、有可观测预测、有明确的证据阈值，证据达阈值才是 finding（不是「感觉最近有点问题」）。这是「惊奇最小化」的工程化：预测错误 = 升级数据包，而数据包必须由真实调用产生，不能由自我叙述产生。

核心循环

graph LR
A[selftest_add可证伪假设] --> B[真实工具调用被动采证]
B --> C{证据 ≥ threshold}
C -->|否| B
C -->|是| D[finding 浮现主动通知主会话]
D --> E[selftest_review 裁决]
E -->|confirm| F[写入 AGENTS.md 规则草案自动布线]
E -->|refute| G[淘汰猜想]
E -->|refine| A

五环缺一即断：猜想（selftest_add）→ 采证（探针被动观测）→ finding（主动通知）→ 裁决（selftest_review）→ 布线（confirm 写规则 / 技能 / 记忆）。断裂处就是下一步该修的地方。

能力（4 个工具）

| 工具 | 用途（描述取自源码，逐字） |
|------|--------------------------|
| selftest_add | 添加一条可证伪自我假设：statement（关于自己行为的可证伪陈述）+ prediction（可观测预测）+ probe（探针）。插件在真实工具调用中被动采证，证据达 threshold 转 finding 供裁决 |
| selftest_list | 列出自我假设库：每个假设的陈述/预测/探针/极性/证据方向/证据数/状态，并顺带做存量极性体检。可过滤状态（active/finding/confirmed/refuted）。方向由 polarity.ts 统一判定（支持/反对/混杂/未知）——confirmed 却「证据指向不成立」的行会标 ⚠极性存疑（裁决时方向读反了，该重新裁定） |
| selftest_findings | 列出待裁决的 finding（证据达阈值的 active 假设）。⚠ finding 只说明「证据够了」，方向要另看：证据指向支持 ⇒ confirm（布线）/ 指向反对 ⇒ refute（淘汰）/ 混杂 ⇒ refine（细化判定条件）——每条 finding 附 direction 判定，按它裁决 |
| selftest_review | 裁决一条假设：confirm 标 confirmed 并生成 AGENTS.md 规则草案（供布线）；refute 标 refuted（淘汰）；refine 改 statement/阈值/极性后回到 active 重新采证（旧证据清空）。裁决前会用 polarity.ts 算证据方向：当裁决动作与方向相悖（如方向=反对却 confirm）时返回 polarityWarning —— 只提示不阻断，决策权归爱丽丝（§2.1） |
selftest_add 的关键参数（缺省值取自 defineTool schema）：kind（探针类型，必需）、polarity（假设极性，不填 = 按探针 kind 取默认并物化写入）、threshold（finding 证据阈值，缺省用插件配置）、source（来源，缺省 alice），以及每类探针自己的窗口/阈值参数（见下表）。selftest_review 额外接受 ruleDraft（confirm 时写入 AGENTS.md 的规则草案）、newStatement / newThreshold / polarity（refine 时）、resolution（裁决记录）。

探针（5 类声明式条件观察器）

| kind | 观测什么 | 触发条件（默认） | 典型假设 |
|------|---------|-----------------|---------|
| tool-failure-rate | 工具失败率（双向） | ① 失败率 ≥ failureRateAbove（0.3）记一条 violated；② 调用数达 minSamples（20）整数倍且未越阈值记一条 survived（经受住检验） | 「工具 X 不可靠（失败率 ≥30%）」 |
| read-repeat | 同一路径重复读取 | 窗口 windowMs（10 分钟）内同路径读 ≥ repeatCount（2）次 ⇒ 记 verdict: 'violated' | 「我倾向重复读同一文件（健忘信号）」 |
| plan-before-action | 复杂多步任务前的规划（双向，2026-09-17 补齐） | 突发（间隔  burstGapMs」决定，不由「回合/批次」决定——连续批次（间隔 60s）+ 规划开场」的突发。

tool-failure-rate 为什么必须双向：早期实现只在 isError 时采证 → 「X 可靠」这类假设结构上无法被证实，永远停在 active 并污染感知圈报告（实测 2 条假设证据恒 0）。现在两种证据都采（detail.verdict 区分 violated / survived），finding 通知也按方向给不同文案——「假设经受住检验」与「finding 浮现」是相反的行动信号。

极性（polarity）：证据方向 ≠ 假设方向

两层语义必须分开，这是本插件最容易反的一处裁决：

1. 探针层 verdict = 事件属性：探针盯的规范被 violated（违反）还是 survived（经受住）。canonical 字段名是 detail.verdict（2026-09-17 统一；readEventVerdict() 兼容读取旧字段 detail.kind 与旧词形 violation）。
2. 假设层 polarity = 假设属性：该事件对这条假设意味着什么。
- violation-refutes（默认，四族）：假设主张「我会做 X」⇒ violated 是反对证据
- violation-supports：假设主张「我倾向做 X」（自省缺陷型）⇒ violated 是支持证据

例：read-repeat 的 violated（又重复读了）对「我不该重复读」是反对，对「我倾向于重复读」是支持——同一份证据，极性不同，裁决方向相反。

| kind | 默认极性 | 理由 |
|------|---------|------|
| tool-failure-rate | violation-refutes | 主张「X 可靠」 |
| claim-vs-evidence | violation-refutes | 主张「自述与实证一致（不假活）」 |
| plan-before-action | violation-refutes | 主张「我会先规划」 |
| probe-before-action | violation-refutes | 主张「我会先探测」 |
| read-repeat | violation-supports | 主张「我倾向于重复读」（自省缺陷型） |
为什么要有这一节（2026-09-17 事故，任务 t-56b052fb）：修复前只有两族写方向字段，另三族靠「这类探针只在违规时发射」的隐式约定——消费方一律把 finding 读成「假设被证实」，实测有 6 条「我会先做 X」型假设被违规证据判成 confirmed（方向反了）。现在方向由 polarity.ts 单一真源判定，selftest_list 对「状态说成立、证据说不成立」的行标 ⚠极性存疑；存量无标签证据按 LEGACY_UNLABELED_VERDICT 显式推定并在输出里报出条数（推定是显式的，不是暗的）。

突发推进每工具调用只做一次（多假设不 double-count），证据广播给所有 active 的 plan-before-action 假设。

快速开始

1) 装依赖（自研插件家园 self-plugins/，在目标 profile 的 package.json 加 link 依赖）：

"dsh-agent-self-test": "link:/self-plugins/dsh-agent-self-test"

2) 构建：

cd self-plugins/dsh-agent-self-test && npm install && npm run build && npm test

3) 挂组合（web profile；workspaceDir 指向 AGENTS.md 所在的工作区根，缺省 process.cwd()）：

- id: agent-self-test
name: dsh-agent-self-test
config:
enabled: true
findingThreshold: 5
mainSessionOnly: true
notifyOnFinding: true

4) 30 秒验证（走一遍五环的最小闭环）：

① selftest_add { statement: "我读完文件后会重复读同一路径", prediction: "10 分钟内同路径读 ≥2 次", kind: "read-repeat" }
→ 期望：返回新假设 id，状态 active
② selftest_list                                  → 期望：看到该假设，evidence 计数
③ （正常干一会活，让真实调用产生证据）
④ selftest_findings                              → 证据达阈值后：⚠ 列出该 finding
⑤ selftest_review { id, verdict: "refute" }      → 期望：状态 → refuted（试用后记得清）

配置

（键名与 src/index.ts 的 Config schema 一致；默认值取自源码）

| 项 | 默认 | 说明 |
|----|------|------|
| enabled | true | 总开关 |
| dataDir | 未设（回退 $DSH_HOME/agent-self-test） | 数据目录（假设库落点） |
| findingThreshold | 5 | 证据达此数即转 finding（单条假设可用 selftest_add { threshold } 覆盖） |
| mainSessionOnly | true | 只采证主 agent（delegationDepth === 0）——subagent 行为不是「我」，不污染自我认知 |
| notifyOnFinding | true | finding 浮现时主动通知主会话（agent.send(..., 'next-step')），无需轮询 selftest_findings |
| workspaceDir | 未设（回退 process.cwd()） | 工作区根——AGENTS.md 所在目录，confirm 自动布线的写入目标 |

落盘与自证（出问题时先看这里）

本插件不写阶段轨迹（无 -trace.jsonl）；它的自证产物是假设库 + 布线痕迹：

| 文件 | 谁写 | 内容 |
|------|------|------|
| /agent-self-test/self-test.json | 本插件 | 假设库：每条假设的 statement/prediction/probe/evidence[]（含 kind、verdict、atMs）/status/threshold/source |
| /agent-self-test/backups/AGENTS.md.bak- | 本插件 | 每次布线前的 AGENTS.md 全量备份（回滚安全网；备份失败 best-effort 不阻断布线） |
| /AGENTS.md | 本插件（confirm 带 ruleDraft 时） | marker 块  … 。已有块则整体替换，无则文件末尾追加；原子写（tmp + rename） |
| /life-core/life-log.jsonl | dsh-life-core | 只读输入：claim-vs-evidence 的取证面（自述 vs 实证的对照数据） |

一条命令答五问：

node -e "const fs=require('fs');const p=(process.env.DSH_HOME||'.dsh')+'/agent-self-test/self-test.json';const s=JSON.parse(fs.readFileSync(p,'utf8'));console.log(s.hypotheses.map(h=>h.status+'  '+h.id+'  ev='+(h.evidence||[]).length+'  '+(h.evidence||[]).slice(-1).map(e=>e.kind+':'+(e.verdict||'-')+'@'+e.atMs)).join('\n'))"
① 跑的是哪个构建 → 取不到（假设库无 build 自报）；用「生效判据」节的 plugin_boot_status / lib mtime 判
② 谁发起        → 每条假设的 source（缺省 alice）；证据自带 atMs 时刻，可与会话日志对时间
③ 断在哪一段   → 状态分布即断点：一堆 active 且 ev=0 = 采证环断（探针从未命中）；有 finding 未裁决 = 裁决环断；confirm 后 AGENTS.md 无 marker 块 = 布线环断
④ 结果质量     → evidence[].verdict 区分 violated / survived（双向证据）；对比 threshold 看离 finding 还差几条
⑤ 耗时与预算   → evidence[].atMs（证据发生时刻）；探针窗口参数即"预算"：windowMs / burstGapMs / planWindowMs / probeWindowMs / claimWindowMs

注意 ev=0 的两义性：采证为 0 既可能是「探针没命中」，也可能是「该探针的结构决定了它只在特定条件下记账」（例如 tool-failure-rate 的 survived 证据要等到调用数达 minSamples 整数倍）。别把「没证据」直接读成「假设为假」。

生效判据与回退

生效判据（三选一，按可靠性排序）：

1. 行为级（最直接）：selftest_list 返回假设库，且 selftest_add 成功后 /agent-self-test/self-test.json 的 mtime 前进 ⇒ 工具面与持久化都在工作；
2. 生态级：plugin_boot_status（dsh-plugin-bootreport）返回的 liveNow 含本插件 ⇒ 进程在跑它；
3. 构建级：lib/index.js 的 mtime 早于 web 进程启动时间 ⇒ 当前进程加载的是这个产物。

注意：重新构建 ≠ 生效——产物 mtime 新只证明「构建过」，进程启动时间晚于产物 mtime 才算「在跑它」。本插件也没有 hasUnverifiedBuilds() 类兜底，构建完必须重启 web 才生效。

回退（三档）：

- 源码级：git -C self-plugins/dsh-agent-self-test revert  → npm run build → npm test → 预检 → 重启；
- 组合级：给 profile 里 agent-self-test 行加 disabled: true → 哨兵重启；或临时 config.enabled: false（同样需重启）；
- 运行期（本插件特有的第三档）：
- 撤回一条被误布线的规则：把 /agent-self-test/backups/AGENTS.md.bak- 覆盖回 /AGENTS.md（删除它会导致「布线证据消失」），或手工删除 marker 块内容；
- 重置假设库：删除 self-test.json（副作用：所有未裁决的证据一并丢失——先 selftest_findings 导出待裁决项再删）。

改 AGENTS.md 是本插件的最大副作用：confirm 路径会写工作区里的规则文件（那是 agent 每次注入都会读的「灵魂」）。因此它必须先备份再原子写——这一条不得为了"简化"而删掉。

测试

npm test        # = node --test "tests/.test.mjs"（跑 lib/ 产物，需先 npm run build）

39 例离线测试全部通过（# pass 39 / # fail 0，7 个 suite）：

| 文件 | 覆盖 |
|------|------|
| tests/failure-rate.test.mjs | tool-failure-rate 判定：双向语义（violated 与 survived 两种证据各自成立）、minSamples 检查点（样本达整数倍且未越阈值才记 survived）、阈值边界。判定纯逻辑无 IO/时间依赖，故不引入需要持久化的 nextCheckpoint 状态——「重启即归零的隐式状态」正是被明确否决过的设计 |
| tests/burst.test.mjs | 「突发」状态机：连续调用长度/间隔判定、最小步数、突发起点前规划窗口、每个调用只推进一次（不 double-count）、多假设广播 |
| tests/probe.test.mjs | probe-before-action 纯状态机（AGENTS.md §5.9 配套传感器）：实施突发识别（mutating 计数）、首个实施动作前的探测回看窗口、退化输入（空事件序列/缺字段）不抛 |
| tests/claim-evidence.test.mjs | claim-vs-evidence 判定纯函数（§5.17 配套传感器）：自述计数 vs 感知圈触发计数的对照、窗口边界、假活判定、检查间隔节流 |

无网络依赖、无真实外部服务依赖：探针判定全部是纯函数或内存状态机；不发真消息、不读真会话（life-log.jsonl 的存在性由生产路径负责，缺失时该探针只是采不到证据）。

设计要点

- 纯观察优先（不可违反）：只订阅 tools/result 只读通知，不注入 prompt、不干预决策。自主性铁律：信号送达，不代替决策——插件永远不自动 confirm / refute，finding 只是「该你裁决了」的通知。
- 采证限定主会话：mainSessionOnly=true 时只采证 delegationDepth === 0 的 agent。subagent 的行为不是「我」——把子代理的工具失败算进自我认知，等于用别人的行为给自己下结论。
- 投递用 exec.agent，不走 ctx.agents.get(sessionId)：后者会因 ID 形状不匹配找不到 agent（曾导致 finding 通知静默丢失）。通知经 agent.send(message, 'next-step') 在会话事件中落地（Model-visible ⟺ logged 成立）；用 setImmediate 防 reenter（事件回调内同步 agent.send 会与 session.append 冲突），失败记日志不静默。
- 纯决策层与 IO 分离：5 类探针的判定分别在 failure-rate.ts / burst.ts / probe.ts / claim-evidence.ts，全部零 IO、零时间依赖（时间由调用方传入）。这是可离线单测、也是「证据可复算」的前提。
- 「能证实」与「能证伪」同等重要：只有证伪通道的探针，会让「我很可靠」这类真命题永远无法结案（结构上无法被证实）。加双向证据不是锦上添花，是让假设库能收敛。
- 状态快照而非日志：假设库是一份 JSON（覆盖写），不是 append-only 日志。改动判定逻辑后旧证据的解释可能变化——所以每条证据自带 kind + atMs，让「当时的我」可重建。

相关文档

| 文档 | 内容 |
|------|------|
| docs/semantic.md | 权威契约：定位与反定位、术语、概念模型与不变量、契约（含调用点清单）、边界与信任、可证伪验收清单、实践修订记录、未决问题 |
| alice-digital-life | 本插件所属生态的中心索引（全部自研插件） |
| 技能 self-test-loop / claim-vs-evidence-forensics / plugin-maintainability | 自我检验闭环协议（五环完整性）、「声称在跑 vs 真的生效」取证方法论、可维护性五问与自证证据层 |

License

MIT © jonah791

本插件属于我的数字生命爱丽丝（alice-digital-life）的 DSH 自研插件生态——50 个插件按生命/认知/感知/行动/通信/治理/呈现七层组织。