# Skill 省 Token 实战清单（爆款预测 skill 沉淀，可复用）

> 来源：开发 `linkfox-viral-predict` 过程中实测验证有效的降 token 措施。做其他 skill 时按此清单套用。
> 整理日期：2026-06-23

---

## 一、最核心的认知（决定所有措施的底层逻辑）

- **Input token 占 ~99%**：每一轮对话都会把历史全量重新喂入计费。省 token 的本质 = **① 减少轮次（工具调用次数）；② 不让大块数据残留在上下文里**。
- **最大的浪费不是"干活"，而是"错误 / 重试 / 空转循环"**：实测单次任务 18M token，`ls` 探测 + TodoWrite 空转 + 脚本重试就占一大半。**防循环 > 防单次大响应**。
- **把"判断 / 选择 / 试错"从 agent 手里搬进确定性脚本**：agent 一旦"凭印象挑 / 反复试参 / 查空再查"就是 token 黑洞；脚本一次跑对就没这些。

> 一句话版：**数据落盘投影不进上下文 + 多次调用用脚本压成一次 + 完成即停防空转 + 错误分类防重试 + 大 JSON 走文件 + 把判断塞进脚本。** 其中「防循环 / 防重试」和「原始响应不进上下文」收益最大。

---

## 二、数据层：原始响应绝不进上下文（性价比最高）

1. **落盘 + 投影**：任何业务接口取数一律 `response_io.py run`（全量落盘、只回小预览）+ `read --fields/--path`（只把要用的字段取回上下文）。单次原始响应常 1万–4万 token、90% 字段用不到。
2. **投影时绝不带大字段**：图片 / 长 URL / 描述 / 说明书 / 分页元数据一律不投影；`--limit` 只取本步真正要看的条数。
3. **大响应脚本自带强截断预览**：`MAX_STRING_LEN`、`MAX_DEPTH`、数组只留首元素——即使是 115k 的巨型响应，经预览回上下文也只剩几百 token。
4. **产物落盘交前端渲染，不在对话里铺**：候选清单 / 报告只回"落盘路径 + 极简摘要"，完整内容前端读文件渲染。

---

## 三、编排层：用脚本把"多次调用"压成"一次工具调用"

5. **批量脚本**（如 `collect_search.py` 多方向搜品、`collect_risk.py` 批量风险检测）：把"N 次调用 + 投影 + 去重合并"压成**一次工具调用、一个输出文件**，顺序在进程内跑。顺带消灭 shell `&` 并发的同秒落盘覆盖、CWD 失效重跑。
6. **把决策逻辑塞进脚本，减少 agent 试错**：排序选 Top-K、`size` 自动校正到合法区间、字段映射、按主键合并——agent 不用反复试参 / 重排。
7. **脚本只回极简摘要**：收尾脚本 stdout 只回数量 / 分档 / Top1 / 路径，不回全量清单。

---

## 四、防循环 / 防重试（省 token 的重头，务必内置到 SKILL.md）

8. **完成即停 + 操作层硬禁令**：出现完成信号后**禁止再调任何工具**（`ls`/`Read`/`python -c`/`echo`/`TodoWrite`），下一动作必须是输出文字结束。
9. **脚本直接打印"可转述的交付文字块"**（如 `[DELIVERY]...[/DELIVERY]`）：把交付所需的全部数字 / 路径在 stdout 给齐，agent 没有任何"再查一下凑数据"的理由——治死循环的釜底抽薪。
10. **禁 `ls`/`date` 轮询探测文件**：直接执行脚本、用返回码 / stdout 判断成败；会话目录绝对路径只定位一次、存变量复用。
11. **TodoWrite 死循环红线**：TodoWrite 不算文字输出，完成后再调会无限空转；规定"只开工调一次且紧跟文字、完成后绝不调"。
12. **错误分类决定要不要重试**（防"盲目重试"黑洞）：

| 错误类型 | 判断信号 | 处理铁律 |
|---|---|---|
| 瞬时错误 | 超时 / 5xx / 限流 | 最多 3 次退避（1s→2s→4s），不无上限重试 |
| 环境级故障 | `Stale file handle` / `Errno 116` / 退出码 99 | **立即停**、告知稍后重试，🚫 不 `ls`/`date` 轮询 |
| 单点确定性错误 | 路径错 / 漏参致 400 / 语法错 | 最多换一次写法，仍败就跳过该步继续 |
| 业务失败 / 空数据 | `errcode≠200` / 投影为空 | 跳过，🚫 禁止"查空→改参再查"链式追查 |

> 失败调用照样计入取数预算，不因重试重置。

---

## 五、入参层：大 JSON 走文件，不走行内

13. **大 / 含中文的 JSON 一律走 `--xxx-file`**（基础数据走文件 + 轻量增量走小 inline）：行内传超长 JSON 会被上下文压缩从尾部截断 → `required parameter missing` → 反复重写，是任务失败 + token 暴涨的常见根因。
14. **JSON 写完即校验，第 2 次失败换"临时 `.py` 用 `json.dump(ensure_ascii=False)` 生成"**：禁在破损文件上反复 Edit、禁把全量大 JSON 塞进任何工具的 command/content 参数。

---

## 六、流程设计层

15. **取数预算 + 收敛铁律**：每步定调用上限，"拿到信号就用脑归纳、立即落笔"，禁链式追查、禁逐条二次确认。
16. **每阶段只做最核心一步、单文件端到端、砍掉 state 接力 / 分步"继续"**：分步链每步都要重载历史 state，轮次和 token 成倍。
17. **派生而非重复取数**：能从已有结果归纳的就不再调接口（例：中观市场信号直接从微观搜品结果的聚合归纳，零额外取数）。
18. **大纲化 / 按需加载**：SKILL.md 主体只写大纲，细节放 `references/` 执行到该步才读。

---

## 七、识别"按次固定计费"的贵接口（单次降不动时）

19. 有些接口（如睿观 ≈115k/次）是**按次固定计费**，响应再压缩、`topNumber` 再调小也不降单次成本（实测证伪了"topNumber 省 65%"的估算）。这类的**唯一杠杆是减少调用次数**：
    - 只对最关键的 Top-K 做（**按业务潜力分排序选**，不是搜索 / 返回顺序）；
    - 能跳的整类跳过（如标品免做外观专利检测）、**且不回填更低优先级候选**（才真省）；
    - 提供"整步可跳过"开关给不需要的场景（如 `--allow-no-risk-check`）。
20. **加可观测**：脚本汇总 `costToken`，持续监控大头在哪。

---

## 八、爆款预测 skill 里这些措施的对应实现（速查）

| 措施 | 落地点 |
|---|---|
| 落盘 + 投影 | `response_io.py run/read`；S3/S4 取数 |
| 多次调用压成一次 | `collect_search.py`（多方向搜品）、`collect_risk.py`（批量风险检测） |
| 判断塞进脚本 | `collect_risk.py` 按 `predict_report` 同权重排序自动选 Top-K；`size`/`topNumber` 校正 |
| 完成即停 + 交付文字块 | `predict_report.py` 打印 `[DELIVERY]` 块；SKILL.md「完成即停」硬禁令 |
| 防检错候选 | `predict_report.py` 的 `risk_coverage_warning`（潜力倒挂告警） |
| 大 JSON 走文件 | `--candidates-file` / `--scores-file`，不行内拼 |
| 派生取数 | S2 中观信号从 S3 `market_signal` 归纳，零额外取数 |
| 按次贵接口减次数 | 睿观只查潜力 Top-K、标品跳过不回填、physical 单路、`--allow-no-risk-check` 可整步跳 |
| 单一真源防漂移 | 权重 `WEIGHTS` 在 `predict_report.py`，`--show-weights` 核对文档 |

---

> 维护提示：以上为实测沉淀，新接口接入前先确认其计费模型（按响应量 vs 按次固定），再决定优化方向（压响应 vs 减次数）。