# EXPERIMENT.md — dsh-agent-frugality 效果验证实验设计

> 原则：**先度量后干预（本插件设计哲学）**——防御效果主要靠观测验证，对照实验尽量零/低成本。
> 价格口径：本机 `dsh-model-router` 内置价格表估算（CHEAP 0.27/1.10/0.07，STRONG 0.55/2.19/0.14 每 1M tokens，in/out/cache）；实际以账单为准（2026-08 已有涨价报道）。
> 状态：Exp-1 已自动开始（本会话自插件注入起累计）。

## 一句话回答"要不要实验 & 花多少"

- **A（重复读取）与 B（门禁）**：**零 token**——插件就是度量器，台账/日志已持续记录；效果判断 = 读数据 + 简单统计。
- **C（审查 lane）**：唯一需要花 token 的对照实验，**预算 ≈ $0.1–2**（按本机价格表），半天完成。
- **可选** DEDUP 实战对照：**≈ $1–3**，或**零成本离线重放**（用现有台账估算收益上限）。
- **总预算：$0（核心验证）～ $3（全量对照）**——远低于实验价值。

## Exp-1 台账基线（✅ 零成本，进行中）

- **数据**：`$DSH_HOME/agent-frugality-ledger.jsonl` + `frugality_ledger` 工具快照
- **周期**：自然累积 3–5 个正常工作日的真实使用
- **指标**：total reads / dupReads / dupRate / dupBytes → 重复字节 ÷4 换算"可节省 tokens 上限"
- **成品**：baseline 报告（含按 agent 分布的重复率）
- **已有先例证据**：本会话实测 60% 重复率（5 reads/3 dups）；门禁 objection 2 次成功

## Exp-2 DEDUP 收益（首选：离线零成本）

- **离线法（推荐）**：用 Exp-1 台账直接估算 `DEDUP=1` 的收益上限 = Σ(dupBytes) ÷4 tokens；对照"替换后模型仍需引用上下文"的折减系数 0.6 → 净节省 ≈ 上限 ×0.6。**零 token，无任务干预**。
- **实战对照（可选）**：同批 10 个真实任务，前 5 个 DEDUP=0、后 5 个 DEDUP=1（或同任务随机分配）。
  - 每任务输入 ≈ 50K tokens（长会话）×10 = 500K；输出 ≈ 200K → 合计 ~700K tokens
  - 成本：STRONG 全主模型 ≈ 0.55×0.7 ≈ **$0.4 + 输出 $0.44 ≈ $0.9**；CHEAP 路线减半
- **验收阈值**：DEDUP=1 时重复读取率下降 ≥50% 且任务完成质量（人工抽查 5 条完成声明）无下降 → 开默认

## Exp-3 review-lane 有效性（≈ $0.1–2，半天）

- **金标准**：本插件 T10 独立审查的 **8 findings** + 自举 review 的 **9 findings** 已构成 ground truth 样本（17 条，含 severity）
- **设计**：30 份真实 diff/代码片段（可从本插件 PR 与生态项目取），**cheap model（flash）与主模型各审一遍**，对金标准比对：
  - 指标：发现率（recall vs 金标准）、误报率、**每美元发现数**（核心指标：cheap 的每美元发现数应 > 主模型）
  - 每份 review 输入 ≈ 6K（提示 + 目标 ≤12K 截断）+ 输出 ≈ 800–2000 → 单份 ≈ 8K tokens
  - 30 份 × 2 模型 × 8K = 480K tokens → CHEAP 侧 ≈ $0.13；主模型侧 ≈ $0.35 → **总计 <$0.5**
- **验收阈值**：cheap 每美元发现数 ≥ 主模型 1.5×，且金标准 recall ≥60% → review-lane 策略成立（"审查员不需要贵模型"）

## Exp-4 门禁防"水过"（≈ 零成本）

- **数据**：`agent-frugality.log` 的 `gate-object` 事件（对象ion 计数、是否最终补调 gate）
- **验证**：抽取 5 次 objection → 人工看模型补了多少步（重新验证/补充说明）；统计"完成声明但从未过 gate"的违规率（应降至 ~0）
- **周期**：随 Exp-1 一同观察，无额外消耗

## 总预算表

| 实验 | 成本（按本机价格表） | 周期 | 输出 |
|---|---|---|---|
| Exp-1 基线 | **$0** | 3–5 天自然累积 | 重复率/字节基线 |
| Exp-2 离线 | **$0** | 1 小时后 | DEDUP 收益上限 |
| Exp-2 实战（可选） | ~$0.9 | 半天 | DEDUP 干预实测 |
| Exp-3 review | ~$0.5 | 半天 | cheap-vs-strong 每美元发现数 |
| Exp-4 门禁 | **$0** | 随 Exp-1 | objection 违规率 |

**合计：$0（核心）～ $2.4（含全部对照）**

## Exp-3 review-lane 有效性（✅ 已执行，2026-08-29）

**结果（`docs/experiments/exp3-results.md`，样本 12 份/金标准 11 条，人工裁决 + 自动匹配双记录）**：

| 臂 | 模型 | recall | 误报 | 估算成本 | 每美元命中 |
|---|---|---|---|---|---|
| cheap | deepseek-v4-flash | **81.8%**（9/11） | 1 | $0.0329 | **273.2** |
| strong | deepseek-v4 | **100%**（11/11） | 0 | $0.0666 | 165.3 |

**verdict: PASS**（cheap 每美元命中 = 主模型 1.65× ≥ 1.5× 阈值；cheap recall 81.8% ≥ 60%）。产品结论：**双 lane 策略**——cheap 日常批量（每美元收益 1.65×），strong 用于关键块/发布前（cheap 的 2 个遗漏恰是 S04 字段缺失类 / S06 off-by-one 类状态一致性缺陷，flash 对其弱）。成本估算以本机价格表为准，实测账单 $0.1 级。


1. 现在：跑 `frugality_ledger` 快照 → 用已有台账做 Exp-2 离线估算（本会话数据就够演示）
2. 本周：自然累积 Exp-1/Exp-4（零成本），同时我做 Exp-3 的 30 份样本集（纯本地准备）
3. 周末：Exp-3 跑半天 → 出"每美元发现数"报告 → 决定 review-lane 是否默认开
4. 决策门：全部指标过阈值 → `DSH_FRUGALITY_DEDUP=1` + review-lane 默认开 + README 实验数据更新

## 运营模式：日常即实验（用户确认的长期策略）

**核心循环**：日常真实使用 = 实验场（台账自动记录）→ 周期快照 → 发布到仓库证明效果 → 数据驱动迭代 v0.1.x。

```
[日常使用] 本机所有会话→台账(ledger.jsonl)/事件(log)
     ↓ (定期, 建议每周/每月)
[快照生成] node scripts/experiment-report.mjs
     ↓ 产物
[发布] docs/experiments/YYYY-MM-DD-snapshot.{json,md} → git(仓库公开)
     ↓ 人读
[解读+阈值对照] 重复率<15% / 门禁违规率→0 / 每美元发现数≥1.5×
     ↓ 发现短板
[迭代] TICKETS 新增体验优化任务 → 发版 → 快照继续
```

**运营规则**：
1. **快照即证据**：每份快照带生成时间/数据窗口/插件版本；只发布真实会话数据，不编造。
2. **发布节奏**：建议每周一次快照（重活周）/ 每月一次 README 实验数据段更新；数据达到里程碑（如累计重复率/节省 token）后并入 README 徽章与「实验数据」章节。
3. **隐私纪律**：快照只含 agent 标签/工具名/字节统计，**不含内容与路径名**（SPEC §7.4）；发布前人工过目。
4. **迭代闭环**：每版 CHANGELOG 附「本版数据基线 → 改进 → 验证」三段式；实验报告同步更新。
5. **阈值触发干预**：重复率持续 >15% 一周 → 开启 DEDUP=1；门禁违规率>10% → 提高 GATE_MAX 或改 objection 文案——每次干预后留 1 周观测窗口再评估。