# Brain+Hands 成本效益实验报告

> 这是本插件 v1.1 的设计依据。三个新能力（状态文件注入、自动验收、递归查找）
> 都来自这份实验暴露的问题。
>
> 计价基准：DeepSeek V4.1-Flash-1017 官方人民币价（空闲时段）
> - 缓存未命中输入 ¥1.00 / 百万 token
> - 缓存命中输入 ¥0.02 / 百万 token
> - 输出 ¥4.00 / 百万 token
> - 高峰时段全部 ×2

---

## 一、实验设计

### 变量控制

| 维度 | 控制方式 |
|---|---|
| 任务提示词 | 两轮任务部分完全一致，仅「工作方式」不同 |
| 会话状态 | 均为全新创建（depth=0），无历史污染 |
| 模型 | 主模型 aliyun/deepseek-v4.1-flash-1017 |
| 计价 | 同一价格表，空闲时段 |
| 统计口径 | input / cache_read / output 三项分别记录 |

### 三组对照

| 实验 | 任务类型 | 测试对象 | A 组 | B 组 |
|---|---|---|---|---|
| 1 | 构建型 | 从零写 2.6 MB 项目 | Brain+Hands | 纯主模型 |
| 2 | 分析型·小库 | 340 KB / 8,853 行 | Brain+Hands | 纯主模型 |
| 3 | 分析型·大库 | Django 18.6 MB / 529K 行 | Brain+Hands | 纯主模型 |

### 关键设计说明

早期实验存在严重缺陷，本报告只采用修正后的数据（详见第五节）。

---

## 二、实验 1：构建型任务

### 任务

从零设计并实现原创项目 Flowforge（分布式数据管道编排引擎），要求 ≥40 个源文件、真实实现（状态机/重试/并发控制）、附带 pytest 测试、`import` 可验证。

### 数据

| | A 组 Brain+Hands | B 组 纯主模型 |
|---|---|---|
| 主会话轮数 | 171 | 157 |
| 派生会话 | 36 个 hand | 15 个 subagent |
| 缓存未命中 | 351,053 | 1,570,730 |
| 缓存命中 | 39,631,360 | 43,815,936 |
| 输出 | 216,869 | 584,193 |
| **成本** | **¥2.0112** | **¥4.7838** |

> A 组的 36 个 hand 共消耗 1,925,692 token，全部走免费池（grok / 书生），不计费。
> B 组的 15 个 subagent 使用主模型，全部计费。

### 产出质量

| 指标 | A 组 | B 组 | 优势 |
|---|---|---|---|
| 文件数 | 97 | 106 | B +9% |
| 行数 | 15,396 | 21,371 | B +39% |
| 类 | 146 | 192 | B +32% |
| 函数 | 960 | 1,253 | B +31% |
| 测试函数 | 190 | 332 | B +75% |
| pytest 结果 | 155 全绿 | 231 全绿 | 平 |
| 实体实现率 | 99% | 99% | 平 |
| docstring 覆盖 | 46% | 25% | **A +84%** |
| 最大单文件 | 25 KB | 38 KB | A 组织更优 |
| import 验证 | OK | OK | 平 |

### 结论

```
成本：A 组省 58%
规模：B 组多产 39%
质量：A 组 docstring 覆盖率高 84%，文件组织更好
```

**单位成本对比**

| 口径 | A 组 | B 组 | 差异 |
|---|---|---|---|
| 每千行代码 | ¥0.131 | ¥0.224 | A 省 42% |
| 每 MB 代码 | ¥3.94 | ¥6.13 | A 省 36% |

---

## 三、实验 2：分析型任务（小库）

### 任务

分析 proj2 项目（41 文件 / 8,853 行 / 340 KB / 800 个函数），找出被定义但从未被调用的函数。
客观答案：**449 个**。

### 数据

| | A 组 | B 组 |
|---|---|---|
| 轮数 | 8 | 11 |
| 工具 | bash + delegate_deepseekv4 | 仅 bash |
| 缓存未命中 | 16,098 | 9,605 |
| 缓存命中 | 119,808 | 195,072 |
| 输出 | 2,713 | 4,963 |
| **成本** | **¥0.0293** | **¥0.0334** |
| 答案 | 449 ✓ | 449 ✓ |

### 结论

```
成本差距仅 12%，基本持平
A 组多花在派单 brief（新入 16K vs 9.6K）
B 组多花在自己读取（缓存 195K vs 120K）
两相抵消
```

---

## 四、实验 3：分析型任务（大库）

### 任务

分析 Django 源码（2,937 文件 / 529,340 行 / 18.6 MB），统计 public 函数总数与 top3 文件。
客观答案：**28,998**；top3 为 `tests/admin_views/tests.py: 521`、`tests/queries/tests.py: 344`、`tests/admin_scripts/tests.py: 276`。

### 数据

| | A 组 | B 组 |
|---|---|---|
| 轮数 | 6 | 5 |
| 工具 | bash 4 / delegate 2 / write 1 | bash 3 / write 1 |
| 缓存未命中 | 6,283 | 3,651 |
| 缓存命中 | 94,720 | 75,264 |
| 输出 | 4,234 | 1,759 |
| **成本** | **¥0.0251** | **¥0.0122** |
| 答案 | 28,998 ✓ | 28,998 ✓ |

### 关键发现：hand 分片不可靠

A 组执行记录原文：

> `django/` 分片 hand 返回 6723 与本地复核完全一致；
> **`tests/` 分片 hand 只扫了 312 个文件（实际 2011），数据作废**

```
hand 漏扫 85% 的测试文件，且自身未察觉
    ↓
主模型不得不自己全量重做
    ↓
派 hand 的开销 + 返工开销 = 双倍成本
```

### 结论

```
B 组省 51%
hand 分片在此场景是净亏损：花了钱，数据还不可用
```

### 意外发现：库大小不影响主模型成本

| 库规模 | B 组成本 |
|---|---|
| 340 KB | ¥0.0334 |
| 18.6 MB | **¥0.0122** |

大 55 倍的库，成本反而更低。原因：主模型用一次性 `ast` 脚本，读取由 shell 完成，context 只接收几行汇总。

**成本由「工具使用策略」决定，不由「数据规模」决定。**

---

## 五、结论修正记录

### 早期错误结论

实验初期得出过两个错误结论：

| 错误结论 | 测量值 | 错误原因 |
|---|---|---|
| 「分析型任务 hand 省 70 倍」 | 5,740 vs 402,115 | ① 在主会话内测增量，受 888M 缓存历史污染；② 对照组是脚本模拟，非真实 agent |
| 「构建型任务 hand 贵 9 倍」 | 40.2M vs 4.4M | 只比较主模型 token 数，未换算成金额，未计入 hand 免费这一事实 |

### 修正后的正确结论

```
构建型任务：hand 省 58%（而非贵 9 倍）
分析型小库：几乎持平（hand 省 12%）
分析型大库：纯主模型省 51%（而非 hand 省 70 倍）
```

### 修正方法

1. 所有实验改用**全新会话**（消除历史污染）
2. 所有对照改为**真实 agent 执行**（而非脚本模拟）
3. 统一按**人民币金额**比较（而非 token 数量）

---

## 六、总览

| 实验 | 任务 | A 组 Brain+Hands | B 组 纯主模型 | 谁更省 |
|---|---|---|---|---|
| 1 | 构建 2.6 MB 项目 | ¥2.0112 | ¥4.7838 | **A 省 58%** |
| 2 | 分析 340 KB 代码 | ¥0.0293 | ¥0.0334 | A 省 12% |
| 3 | 分析 18.6 MB 代码 | ¥0.0251 | ¥0.0122 | **B 省 51%** |

### 决策规则

| 任务特征 | 建议 | 依据 |
|---|---|---|
| 大量写代码、从零构建 | **用 hand** | 省 58%，docstring 质量高 84% |
| 批量读代码、统计、抽取 | **自己干** | 省 51%，一次 ast 搞定 |
| 需要语义理解的代码审查 | 用 hand，但必须验证覆盖 | 主模型上下文装不下 |
| 超长文档总结 | 用 hand | 主模型会截断 |
| 小规模分析（<500 KB） | 都行 | 差距 12%，可忽略 |

### hand 使用注意事项

1. **必须验证覆盖度**：在 brief 里写明总文件数，要求 hand 回报实际处理数，不匹配则重做
2. **必须用同步模式**：`run_in_background: false`，否则结果可能丢失
3. **不适合数据完整性要求高的任务**：实测 hand 会漏扫 85% 文件且不自知
4. **适合可容错的生成任务**：写代码、写文档，错了可以补

---

## 七、附：工具与数据

```
workspace/
├── watch.py                    会话 token 统计（基线对比模式）
├── monitor.py                  持续监控时间序列
├── toggle_hands.py             brain-hands 插件开关
├── session_stat.py             单会话统计
├── exp_round1.json             实验 1 数据
├── django_truth.json           实验 3 客观答案
├── out_exp_handson/            实验 1 A 组产出（97 文件 / 15,396 行）
└── out_exp/                    实验 1 B 组产出（106 文件 / 21,371 行）
```