---
name: pi-sub-agent
description: 将具体执行委派给 pi coding agent + ZenMux inclusionai/ling-3.0-flash（廉价执行模型），Claude 负责任务匹配判断、任务书编写、驱动（一次性 pi -p 或 tmux 交互长程）、硬超时重试、独立验收与失败裁决。含 ling-3.0-flash 专属最佳实践（3D 素材来源、Spec-Driven、强类型可验证节点、混合推理开关）。方法论与坑来自实测对照实验。触发词：pi 委派、把执行外包给便宜模型、ling-3.0-flash、ling flash
license: MIT
allowed-tools: "Read,Write,Edit,Bash,AskUserQuestion"
version: "1.1.0"
---

# Pi Sub-Agent：贵模型编排，便宜模型执行

把写码/生成类执行工作委派给 `pi + zenmux/inclusionai/ling-3.0-flash`，Claude 只做编排、驱动、验收。省的不只是钱，更是 Claude 自己的上下文——执行细节全部留在 pi 会话里，Claude 只接收结论。

## 0. 先判断值不值得委派（最重要的一步）

实测结论：**执行模型能力 < 任务难度时，委派比自己写更贵**（驱动开销可达自己写的 2.4×，且质量更差）。先做任务-模型匹配：

| ling-3.0-flash 擅长（放心委派） | 弱项（不要委派，自己写或换强模型） |
|---|---|
| 逻辑/状态机、CRUD、模板化页面 | 空间几何推理（尺度归一、bbox、Raycaster 命中） |
| 结构化转换：NL→JSON、schema 约束输出（实测 100% schema 合法） | 隐式状态锚定（引用不存在的对象会编造 id） |
| 单文件自包含产物、按明确 spec 施工 | 跨多轮的复杂调试（同一 bug 两轮反馈修不好就到顶了） |
| 资源核验（会自己 curl/API 确认 URL 存在） | 开放式设计决策 |

设计任务时主动**把弱项从执行方职责里剥离**（如：空间数学放进确定性代码层，只让 ling 做 NL→命令翻译）——同一个模型，任务形状对了，成绩能从 3/5 翻到 10/10。

### 0.1 资源/3D 类任务：给素材来源，别让它手搓

从零手写几何体/材质对 ling 事倍功半，视觉难保证（官方 pitfall + 实测：SkinnedMesh 的尺度归一与 Raycaster 命中是 124B 档**系统性弱区**，两轮结构化反馈都救不回来）。正确形状是**把"找素材"写成显式步骤，直接把免费素材库入口塞进任务书**，让它只管场景逻辑与交互调度：

- **免费 3D/游戏素材来源**（可写进任务书）：
  - `https://threejsassets.com/` — three.js 就绪素材
  - `https://www.kenney.nl/` — CC0 游戏素材（模型/贴图/音效）
  - `https://github.com/Fasani/three-js-resources` — three.js 素材/工具资源索引
  - `https://github.com/KhronosGroup/glTF-Sample-Assets` — 官方 glTF 样例，raw 直链稳定可用（实测可作 rigged 替身模型）
- **别写进"免登录直链"任务书的坑**：poly.pizza 下载走 reCAPTCHA 实测 403，Sketchfab 要 OAuth。找不到特定角色的免费直链时，按规格降级用官方样例模型（如 `RobotExpressive.glb`/`RiggedFigure`）并在页面**如实标注"替代模型"**——两个模型独立搜索都收敛到"某些角色的免登录直链不存在"。
- **空间数学自己扛**：尺度归一（`updateMatrixWorld(true)` + bbox）、Raycaster 命中检测尽量放进确定性代码层或你亲自写，只让 ling 做 NL→配置/命令翻译。
- **3D 草图/运镜走 Blender MCP**：让 ling 调 Blender MCP 用基础几何体搭布局、设摄像机轨迹，产出粗模当视频生成底稿，而非死磕手写几何——这是它作为「受控草稿生成环节」的性价比甜点。

## 1. 前置检查

```bash
pi --list-models 2>/dev/null | grep -i 'ling-3' || echo "NOT-CONFIGURED"
```

`NOT-CONFIGURED` → 先跑 `/pi-setup`（其 ZenMux 套件含 ling-3.0-flash；注意其坑 9/坑 10）。

**顺带确认混合推理没被静默退化**：ling-3.0-flash 是混合推理模型，接入配置不当会退化成非思考模式、能力释放不全。`/pi-setup` 的 ZenMux 档默认 `defaultThinkingLevel: "off"`——**批量吞吐/低延迟**任务这样最省最快；但委派**需要长程自愈的编码任务**时，按需把思考调高，让它能在"写-测-喂报错"里自查纠错。

## 2. 写任务书（一次给全，不指望澄清）

ling 是非推理模型，任务书质量决定产出质量。必含五要素：

1. **目标**：一句话 + 产物形态（如"单文件 index.html，无构建步骤"）。
2. **硬性约束**：技术选型、禁止事项（如"禁止手搓几何体"）、CDN/依赖方式。
3. **资源**：外部 URL **Claude 先自己 `curl -sI -L` 验证过再写进任务书**；给错了 ling 通常能自纠（会自己查 API/分支），但会浪费轮次——把"先确认资源存在再用"写成显式步骤。
4. **验收标准**：写明你将如何验收（零 console error、截图哪些功能等），让它对着靶子施工。
5. **汇报格式**：完成后报告最终选用的资源 URL、验证方式、自检结果。

两条放大产出质量的写法：

- **施工前先对规格（Spec-Driven）**：复杂/多文件改动，先让 ling **复述任务并列出"本次要改哪些部分"**，你核对无误再放它动手——ling 上下文有限，联动修改易漏改、易架构漂移，先对齐一次比事后返工便宜。
- **优先强类型语言**：能上 TypeScript 就别用裸 JS。编译器的严格报错是 ling"写-测-喂报错"自愈闭环的**可验证节点**；缺了它，隐性 bug 下它容易方向跑偏。同理批量结构化输出用 JSON Schema/Pydantic 约束。

## 3. 驱动

### 一次性任务：`pi -p`

```bash
cd <工作目录> && timeout 600 pi --provider zenmux --model inclusionai/ling-3.0-flash -p "<任务书>"
```

**必须包硬超时**：ZenMux 偶发请求级死挂（进程 CPU 冻结、零输出，实测约 1/10 会话）。超时后先 `curl -s -o /dev/null -w '%{http_code}' https://zenmux.ai/api/v1` 确认网关可达（秒回即可，404 也算通），然后原样重跑——瞬态故障重跑通常立刻成功。最多重试 2 次。

### 多轮/长程任务：tmux 交互会话

同一会话连续多轮（保留 pi 侧上下文），Claude 轮询驱动：

```bash
tmux new-session -d -s pi-sub -x 220 -y 50 -c "<工作目录>"
tmux send-keys -t pi-sub -l 'pi'; tmux send-keys -t pi-sub Enter
# 首次启动可能出 trust-folder 提示（Enter 确认）；若 pi 被挂起（job control quirk）用 fg 恢复
# 确认状态栏显示 inclusionai/ling-3.0-flash 再发任务

tmux send-keys -t pi-sub -l '<任务书或反馈>'; tmux send-keys -t pi-sub Enter
tmux capture-pane -t pi-sub -p | tail -40   # 轮询，间隔 20-60s
```

挂死判定两条都要：
- **5 分钟零新输出** → 杀掉重开，计一次挂死；
- **有输出但无进展**（ling 会陷入重复执行相同 grep/自检命令的死循环）→ 同样按挂死处理，发一条打断消息或重开。

## 4. 修复反馈（结构化，限量）

验收失败时用结构化 bug 报告喂回：**「当前情况是…（含具体报错/截图观察），预期情况是…（引用验收标准）」**。一次只报一个问题域。**同一问题最多 2 次反馈**——2 次修不好即触发裁决（§6），继续喂只会烧 token 不会收敛。

## 5. 独立验收（绝不信任执行方自报"完成"）

ling 会自报 "All checks passed"，照单全收等于没验收。Claude 亲自跑：

1. **外链**：产物里全部外部 URL `curl -sI -L` 逐个 200。
2. **静态 review**：API 用法、回调结构、明显 bug。
3. **运行时**：web 产物起 `python3 -m http.server` + agent-browser 打开——console 零 error、截图确认功能可见、模拟点击/拖拽/按键验证交互；脚本类直接跑并断言输出。
4. 验收产物（截图、curl 结果）存盘，和结论一起写进运行日志。

ling **无原生多模态**——看不懂截图/音频，做不了视觉自检。这正是运行时/截图验收必须由 Claude 亲自跑的原因：执行方连"页面长歪了"都感知不到（实测 R1 巨人腿旁一个小蓝点、console 不报错，它照报 "All checks passed"）。

## 6. 失败裁决与记录

- 同一问题 2 次反馈未修复 → 判定**超出能力圈**：Claude 收回自己写、换强模型、或重设计任务形状（见 §0）再委派。如实记录降级原因——这是数据不是丢脸。
- 全程计量：pi 侧轮次、挂死/重试次数、Claude 侧驱动 token。事后对比"委派总成本 vs 自己写"，喂回 §0 的判断表。

## 边界

- 密钥绝不进任务书/日志（pi 配置已用惰性 shell 读）。
- 生产模式下验收通过即可交付，Claude 可在裁决后接手修码；若是对照实验/评测，执行方必须独立完成全部代码，Claude 只反馈不改码。
- tmux 会话任务结束后保留供用户复查，报告里给出 `tmux attach -t <session>`。