# 开发效率指南（Development Efficiency）

> 本文档是 2026-06 → 2026-08 的历史样本（113 个会话、24,806 次迭代、6,660 万 tokens、总成本 $88.76）提炼出的效率经验；模型价格、CI 耗时和测试数量均为当时快照，不替代当前机器指标。
> 核心规则已固化到 `AGENTS.md` 的 **Development Efficiency Protocol** 章节，本文件提供完整数据、案例与检查清单。

---

## 1. 成本数据：钱到底花在哪

### 1.1 模型单价是最大的成本变量（不是 token 量）

| 模型 | 每迭代成本 | 相对成本 | 适用场景 |
|---|---|---|---|
| abs-claude-fable-5 | ~$0.124 | 3000× | 仅限复杂推理（架构设计、FFI 布局、对抗性评审） |
| deepseek-v4-pro | ~$0.0097 | 240× | 中等推理 |
| minimax-m3 | ~$0.0039 | 95× | 综合开发 |
| glm-5.2 | ~$0.0019 | 45× | 综合开发 |
| kimi-k2.7-code | ~$0.0015 | 36× | 代码任务 |
| mimo-v2.5-pro | ~$0.0006 | 15× | 执行型任务 |
| qwen3.8-max-preview | ~$0.0003 | 7× | 执行型任务 |
| dsk-deepseek-v4-flash | ~$0.0002 | 5× | 执行型任务 |
| k3 / k3[1m] | ~$0.00003 | 1× | 批量机械任务 |

**关键事实**：同样跑 600 次迭代的 harness 开发流程，用 abs-claude-fable-5 约 **$74**，用 k3[1m] 只要 **$0.02**——成本相差 **3000 倍**。所有会话的 prompt 缓存命中率均在 98-100%，缓存不是成本差异来源。

### 1.2 最贵的会话解剖

- `2026-07-06`「理解项目现状」：**$32.02**（占全部预算 36%），258 迭代，abs-claude-fable-5。任务本身合理，但模型选错。
- `2026-07-07` feishu-3：$14.03，339 迭代，含 6 次编译失败。
- `2026-07-14`「Session 1」：**唯一 error 会话**，$4.31，574 迭代，390 万 tokens，反复重试后失败退出。

---

## 2. 高效模式（怎么做又快又好）

### P1. 机械性开发任务用便宜模型
harness/spec 开发（读 spec → 改代码 → 编译 → 测试）是执行型任务。实证：442 迭代 $0.049、605 迭代 $0.067、438 迭代 $0.083 的会话都用便宜模型完成，产出质量与贵模型会话无差异。

### P2. spec/harness 驱动流程
1. **一次并行读入所有相关 spec**（一条消息 8 个 file_reader）
2. **todo_manager 拆分任务**
3. **小步实现 + 即时验证**：`git status → moon check → git commit → git push` 循环
4. **完成后归档 spec 并更新 CHANGELOG**

### P3. 动手前先确认环境和构建方式
开发前先 `moon version && uname -a`；一次 `file_reader` 读完整 Dockerfile / moon.pkg 配置，而不是猜命令。

### P4. 用 skill 委派探索
用 `code-explorer` / codebase-memory MCP / `moon ide doc` 拿项目全景，而不是手动遍历所有包。

### P5. 批量并行工具调用
把无依赖的工具调用合并到一条消息（平均 15 个调用/消息的会话效率最高），减少往返和过渡推理 token。

### P6. 探测逻辑写成脚本文件再执行
`write /tmp/probe_*.sh → bash` 把多步验证固化成脚本，可复用、不易出错。

---

## 3. 浪费陷阱（怎么做会浪费时间和 token）

### W1. 模型选错 = 最大浪费黑洞（可占预算 1/3+）
最贵模型跑执行型任务 = 白烧钱。**执行型任务永远用便宜档模型。**

### W2. 挤牙膏式 grep 探索
某会话连续 9 次 grep 同一文件的不同 API，每次只 `head -10`，才拼出全貌。对 token 而言，9 次 grep + 各自上下文重传，比 1 次 `file_reader` 读完贵得多。
**正确做法**：目标文件一次读完；精确匹配跨文件才用 grep；API 发现用 `moon ide doc`。

### W3. 重复读同一份文件（压缩后忘记已读）
- `gap-analysis` 文档单会话被完整读取 4 次（16KB × 4）。
- `brand_cell.mbt` / `tasks.js` / `chat_cell.mbt` 各被读 3-4 次。
**原因**：长会话触发上下文压缩后，模型丢失"已读"记忆。
**对策**：读过大文档立即把要点写进 todo/笔记；长任务拆短会话。

### W4. 构建命令靠猜
某会话 7 次试错（`warren build` → `ls` → `cat warren.toml` → `cat moon.pkg` → `moon build --target js` → `cat moon.pkg.json`）才知道正确构建命令。
**对策**：先读 README / AGENTS.md / moon.pkg；不确定就 `glob` 找构建脚本。

### W5. 超长会话上下文膨胀 + 失败重试双倍浪费
某会话 196 条消息、390 万 tokens、最后 error 退出。prompt tokens 从 66K 涨到 72K，每轮都在重传巨量历史。
**对策**：任务超 ~50 条消息果断拆新会话（git 提交进度后，新会话只带 spec + git 状态）。

### W6. 反复获取同一 API 文档
某会话末尾连续 4+ 次拉取同一个 `input()` 函数签名（每次返回相同内容）。
**对策**：拿到工具结果立即用自己的话总结关键签名到代码/笔记，不要用时重查。

### W7. 含糊的任务指令容易跑偏
无明确目标的会话（如「Session 1」）会自行扩张任务范围。
**对策**：任务书写明目标、边界、验收标准；超过 1 个目标就拆会话。

### W8. 编译失败循环
6 次 build-fail、339 迭代的会话证明：**不查根因就重试是烧 token 的最快方式**。
**对策**：一次失败后先读完整错误输出（`2>&1 | tail -50` 或 `--output-json | jq`），定位根因，一次修复。

---

## 4. 检查清单（每次会话开始前过一遍）

- [ ] 确认 `moon version` 与构建命令（`moon build --target native --release cmd`）
- [ ] 模型选择：任务类型是执行型 → 便宜模型；复杂推理 → 才用好模型
- [ ] 是否已读相关 spec？一次并行读完
- [ ] 目标文件用 file_reader 一次读完，不用 grep 试探
- [ ] 大文档读完立即写要点到 todo
- [ ] 编译失败 → 先读完整错误再动手
- [ ] 无依赖工具调用合并为一条消息
- [ ] 任务预计超 50 条消息 → 规划拆分会话 + git 接力

---

## 5. CI 墙钟时间去哪了（2026-09-21 实测）

一次**绿色** `CI` run（`Check · Build · Test`，总计 **19.3 min**）的逐步耗时，取自 Actions 的步骤级时间戳：

| 步骤 | 耗时 | 说明 |
|---|---|---|
| 环境/检出/apt/工具链安装/`moon update` | 0.5 min | **工具链安装只有 0.1 min**——"每次都装最新工具链很慢"的直觉被实测否定 |
| `moon check` | 0.1 min | 只做类型检查，不调用 C 编译器 |
| **`Build (native release)`** | **4.7 min** | 为 cmd 二进制编译整个模块 |
| CLI 契约探针 | 0.4 min | 含 `moon run cmd` 对比目标的预热 |
| **`Run tests (module packages)`** | **13.3 min** | 当时快照：编译测试二进制 + 执行 3818 个用例；当前数量以 `scripts/repo_stats.sh` 为准 |
| `Run lib/mcp tests` | 0.3 min | |
| 其余闸门（警告预算 / 公共 API / 台账 / eval / repo-stats） | ≈0.0 min | 复用前序编译结果或只读日志 |
| **合计** | **19.3 min** | |

**根因：瓶颈是宿主 C 编译器，不是 MoonBit 前端。** 构建期间把单个核吃到 99.9% 的进程是 `cc1`（gcc）
——moon 为每个包生成 C 再交给系统 C 编译器，而且**编译两轮**：`build/` 树给二进制、`test/` 树给测试套件。
同一份输入在每个 push 上重编，是纯重复劳动。

**处置**（`.github/workflows/ci.yml`）：

1. 按「编译器身份 × 源码内容」缓存 `_build/native/release` 与 `_build/wasm-gc`；
   `restore-keys` 只用编译器身份前缀，于是改一个包时能复用上一轮对象、只重编变化的包。
   编译器身份必须进 key：让新编译器命中旧缓存，正是该文件里 `~/.moon` 那条注释警告过的
   "陈旧工具链"陷阱。
   **注（2026-10-16 证伪）**：该缓存策略后被实测证伪——命中缓存并未省下编译，
   `Build (native release)` 仍需 316–378s，领先假设是 checkout 的 mtime 使全部对象失效
   （见 `test-report-2026-10-15.md` §11），尚未修复。
2. 编译重的步骤统一 `-j "$(nproc)"`（`moon check` / `moon build` / 两次 `moon test`）——
   moon 支持跨包并行，此前没有把核数告诉它。

**教训**：CI 慢的时候先量再改。步骤级时间戳回答"哪一步慢"，`ps` 回答"那一步里谁在吃 CPU"；
这次两个直觉（工具链安装慢、测试执行慢）都被实测否定，真正的答案在"生成 C 的编译"上。