# 本地模型「先发文档 → 自动拆解 → 连续执行」实操指南

> 全部结论都在本机实测过：AI 服务器 192.168.1.106，Strata 引擎 0.1.45，
> Qwen3.8-Flash-Next IQ3_S，256K 上下文。不是理论推测。
>
> **这份是给你看的快速上手。** 框架的完整逻辑、字段表、扩展方法、
> 踩坑记录在 [README.md](README.md)——那是写给接手 AI 的集成规范，
> 你要改东西时去那里查。

---

## 一、日常怎么用（记住这三行就够）

```bash
cd E:\本地模型任务策略

# 1. 写长期目标
cat > task.txt <<'EOF'
通读 demo_doc.md，输出一份配置参数速查表。
EOF

# 2. 规划（1 次短调用，产出子任务清单）
python sprint.py plan --name mytask --task-file task.txt

# 3. 执行 + 看进度
python sprint.py run    --name mytask
python sprint.py status --name mytask
```

产物全在 `runs\mytask\` 下，用完整个删掉就行。

**带长文档的任务**：不用你操心。规划器会在 `plan.json` 里自动给需要的子任务
填 `context_docs`，框架会把文档钉住读入（详见 README 第 6 节）。
想手动指定就自己编辑 `runs\<name>\plan.json`。

---

## 二、你问的三件事，答案在这里

**「我不知道任务是多大，怎么拆分？」**
不让你估。`plan` 用一次短调用把长期目标拆成子任务清单，
每个都带 `goal / reads / writes / done_when`，可直接执行也可直接验收。
你只需要把目标写成文件。

**「怎么实现自动理解？」**
拆解质量由 `prompts\planner.md` 决定。它的硬约束是：每个子任务 20 步内完成、
产出全部落盘、`done_when` 必须能靠检查文件来判断、长文档走 `context_docs`。
最后那条是关键——**可验证**。`status` 一眼看出卡在哪。

**「能不能先发文档，再说任务？」**
能，而且这是本机最大的提速点。引擎原生支持，请求体加一个字段：

```json
{"messages": [{"role": "system", "content": "..."},
              {"role": "user", "content": "<整份文档>"}],
 "strata_prefix": {"message": 1, "chars": 52519}}
```

引擎在文档末尾钉一个**永不驱逐**的 checkpoint，之后每个请求只读新增部分。

---

## 三、实测数字（为什么值得这么用）

### 文档只读一次的收益

38,902 token 文档配 5 个任务，跑两遍取第二遍：

| 形状 | 读入耗时 |
|---|---|
| **一次冷读 + 5 个短任务（文档钉住）** | **4.94 s / 7.19 s** |
| 5 个请求，每个都重贴全文，不带 pin | 42.29 s / 143.05 s |

快了 20–30 倍，而且**方差小得多**——A 组两次都稳定 5–7 s，
B 组两次差了 3.4 倍（因为它每次全量冷读，完全被机器负载牵着走）。

### 真实跑过的一轮

任务「通读 `demo_doc.md`，产出配置参数速查表」，规划器自己拆成 2 个 sprint，
44 秒跑完，11 个参数 + 6 条警告全部提取正确，`新读/轮` 从 607 降到 209。

---

## 四、三条必须记住的军规

**1. 文档发出去就别改。**
同一份文档只改 1 个字，5 个任务从 2.76 s 涨到 **146.36 s**——
每个任务重读 3.4 万 token。要改，改完再发。

**2. `chars` 是字符数，不是字节数。**
`{"strata_prefix": {"message": 1, "chars": N}}` 里的 N 用 `len(文档字符串)`。
中文文档填字节数会差 3 倍，pin 静默失效。

**3. 别信 `usage.cached_tokens`。**
本机引擎这个字段恒为 0。复用数在 `timings.cache_n`。
框架已经改对了，你自己写客户端时注意。

> 更多坑（`work/work` 双层目录、路径解析、`{"messages":2}` 会 400、
> 「重贴全文 + pin 也有效」是误判）记录在 README 第 8 节。

---

## 五、出问题时先看这三处

| 现象 | 先查 |
|---|---|
| 某 sprint 标 `failed` | `runs\<name>\sprint-XX\record.json` 的 `note` 字段 |
| 汇总行出现 `[超预算强制收尾]` | `prompt_tokens_per_turn` 定太小，或子任务拆得不够细 |
| 上下文一直在涨 | `prompts\worker.md` 的输出纪律，或 `handoff_max_tokens` |

调试命令：

```bash
python sprint.py status --name mytask      # 进度 + 累计账本
type runs\mytask\handoff.md                # 接力笔记当前内容
type runs\mytask\stats.json                # 每 sprint 的 token 账本
```

---

## 六、不想烧 GPU 就先干跑

```bash
python mock_server.py &
python sprint.py plan --config dryrun-config.json --name demo --task-file examples/demo-task.txt
python sprint.py run  --config dryrun-config.json --name demo
```

跑完把 `runs\` 删掉。这条链路能验证「prompt 加载 → JSON 解析 → 工具分发 →
账本计数」全通，只是模型是假的。

---

## 七、文件清单

| 文件 | 作用 |
|---|---|
| `sprint.py` | 框架全部逻辑（纯标准库，Python 3.8+） |
| `README.md` | **AI 集成规范**：逻辑详解、字段表、扩展方法、踩坑记录 |
| `本地模型任务拆解-实操指南.md` | 本文，人的快速上手 |
| `config.json` | 真机配置（已指向 192.168.1.106） |
| `dryrun-config.json` | 干跑配置（指向 mock） |
| `mock_server.py` | 无 GPU 干跑服务器 |
| `demo_doc.md` | 演示长文档，`context_docs` 的示例 |
| `prompts\planner.md` | 任务分解提示词 |
| `prompts\worker.md` | 输出纪律铁律 + 工具协议 |
| `prompts\wrapup.md` | 超预算强制收尾 |
| `examples\demo-task.txt` | 示例长期目标 |

---

*实测日期：2026-10-25 · 引擎 Strata 0.1.45 · 数字来自引擎自己的 timings*