Pi sub agent

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

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

两个执行模型，按任务选（都经 ZenMux 聚合，复用同一 ZenMux key）：

	deepseek/deepseek-v4-pro（默认/强档）	inclusionai/ling-3.0-flash（廉价快档）
上下文	1M	256K（pi 显示 262K）
推理	推理型 reasoning=true	非思考 reasoning=false（ZenMux 上 reasoning_effort=none 仍漏少量 reasoning）
多模态	无（纯文本）	无（纯文本）
计费 /M token	~$0.44 输入 / $0.87 输出	2026-07 ZenMux 促销期免费（07-23 上线，正式价待定——别把"免费/便宜N倍"写进长期结论或对外话术，随时会变）
适合	复杂调试、多轮联动、需推理的任务	结构化转换、模板化组装、照确切 spec 施工的高频快活

选型原则：任务难度高 / 要跨多轮推理纠错 → deepseek-v4-pro；任务形状规整、有强类型可验证节点、主要是"照 spec 装配" → ling-3.0-flash 更省更快。拿不准先按 §0 匹配表判断，宁可起手用强档。下文正文以 deepseek-v4-pro 为默认书写；用 ling 时叠加下面的「ling 实测画像」，纪律收得更紧。

方法论溯源（诚实标注）：本 skill 的核心方法论与多数「坑」来自 ling-3.0-flash 的实测对照实验（含 2026-07 一次 xlsx→TS 建站长程实测，见「ling 实测画像」）。deepseek-v4-pro 能力档更高，凡标 ⚠️待实测 的模型专属弱区判断是尚未在 deepseek 上独立复测的稳妥默认，按保守做法执行、别当已验证结论。与模型无关的流程纪律（Spec-Driven、独立验收、硬超时、失败裁决）与仍走 ZenMux 通道的坑（请求级死挂）对两个模型都适用。

ling-3.0-flash 实测画像（2026-07，一次干净的 xlsx→TS 数据站长程实测）

带 tsc 可验证节点、无空间几何的 TS 建站任务上，ling-3.0-flash 能产出专业成品，但短板明确、纪律要更紧：

• 强区（放心交）：结构化 NL→typed JSON + Zod/schema 校验（R0 一次过，stats 全中）；模板化组件组装；Recharts 图表配置（4 图中 3 图数值一次全对）；照 Claude 给的确切代码/比较器施工。
• 实测弱区（必须防）：
  1. 自报双向都不可信——自报 "$1.31k" 实渲染 "$1.31b"（代码对、话报错）；反过来也会报"已完成"而实际长歪。一律 Claude 亲自渲染/断言核对（§5）。
  2. 模糊逻辑反馈会带歪——排序"null 恒沉底"用口头描述反馈，它复现了 -cmp sign-flip 没修对；把确切比较器/数值贴给它才一次过（§4 的"确切值反馈"对 ling 是硬要求，不是可选）。
  3. 琐碎清理会空转——R4 打磨时一个 TS6133 未用变量 让它对同一报错循环 5+ 次不收敛；盯 §3 第二种"有输出无进展"死循环，及时打断并贴确切一行修法（或按 §6 机械小修 Claude 直接接手）。
  4. 非思考档：无自适应推理兜底，跨多轮复杂调试更易架构漂移——这类任务优先给 deepseek-v4-pro。
• 纪律加码：§0/§0.1 的"剥离空间推理/开放式设计"对 ling 收得更紧；反馈永远给确切值不给口头；每轮验收不省。

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

原则不变：执行模型能力 < 任务难度时，委派比自己写更贵（驱动开销 + 返修轮次可能反超）。deepseek-v4-pro 能力档明显高于 ling 级，这条风险显著下降，但不为零——仍先做任务-模型匹配：

放心委派	需谨慎 / 剥离弱项后再委派
逻辑/状态机、CRUD、模板化页面	复杂空间几何推理（尺度归一、bbox、Raycaster 命中）⚠️待实测
结构化转换：NL→JSON、schema 约束输出	开放式设计决策（该 Claude 定，别外包）
单文件或多文件自包含产物、按明确 spec 施工	需要跨很多轮的复杂调试（给它推理档 + 强类型可缓解，见 §1/§2）
资源核验（会自己 curl/API 确认 URL 存在）	视觉/听觉自检（无多模态，见 §5）
视觉/美术导向产物（按 §0.2 拆成"眼睛/手"后可委派）	单轮产物体量超过执行方 maxTokens（见 §2.4）

设计任务时主动把最容易翻车的部分从执行方职责里剥离或前置（如：空间数学放进确定性代码层由 Claude 预算，只让执行方做 NL→命令翻译 / 照 spec 装配）——同一个模型，任务形状对了，成绩能翻几个档。

0.1 资源/3D 类任务：复杂空间推理仍建议 Claude 预算 ⚠️待实测

两条对执行方友好的形状，共同点是不让它同时既设计几何又算空间关系：

• 要真实/复杂模型 → 别让它手搓几何，把免费素材库入口当显式步骤写进任务书，它只管加载、场景逻辑与交互调度。
• 要风格化/自建几何（如 Q 版角色、磁带机）→ 让它堆 primitive，但坐标、尺度、比例、朝向尽量由 Claude 预先算好写进 spec，执行方做"照 spec 逐件拼装"。

稳妥默认：尺度归一（updateMatrixWorld(true) + bbox）、Raycaster 命中、自适应相机距离这类确定性数学，由 Claude 预算成成品代码块贴进任务书，执行方只粘贴不改公式。deepseek-v4-pro 推理更强、也许能自己做对，但这是历史上最易翻车处；复杂几何至少让它先复述空间方案再动手（Spec-Driven，§2）。（实测教训：任务书里 Claude 写错一句 rotation.x=Math.PI/2，执行方照抄不误——spec 正确性永远是你的责任。）

• 免费 3D/游戏素材来源（可写进任务书，均于 2026-07 curl 200 复核）：
  • 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 替身模型）
• 免登录 rigged 替身模型的直链（找不到特定角色时按规格降级用，raw 直连、可跨域 fetch，2026-07 复核 200）：
  • https://raw.githubusercontent.com/mrdoob/three.js/master/examples/models/gltf/RobotExpressive/RobotExpressive.glb — 带骨骼动画的机器人
  • https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Assets/main/Models/RiggedFigure/glTF-Binary/RiggedFigure.glb — 简易 rigged 人形 用替身时在页面如实标注"替代模型"。
• 别写进"免登录直链"任务书的坑：poly.pizza 下载走 reCAPTCHA 实测 403，Sketchfab 要 OAuth——某些角色的免登录直链就是不存在。
• 3D 草图/运镜走 Blender MCP：让执行方调 Blender MCP 用基础几何体搭布局、设摄像机轨迹，产出粗模当视频生成底稿，而非死磕手写几何。

0.2 视觉/美术任务：Claude 当眼睛，pi 当手

执行方无多模态，但本 skill 总是被一个多模态 agent 调用——所以"看"这件事本来就该留在编排侧。 别因为"它看不见"就放弃委派，而是把职责切干净：

	Claude（眼睛 + 大脑）	pi 执行方（手）
需求	读参考图 → 转写成文字规格	只读文字规格，永远看不到原图
架构	定坐标系/数据流/关键不变量	照 spec 施工
每轮	起服务、渲染、截图、读图诊断 → 开数值处方（§4）	应用处方、跑 Claude 给的 harness（§2.3）
判定	唯一有权说"画面对了"的一方	明确告知"不用自己验画面，我来渲染"

• 图 → 文字规格至少要含：主色板（hex）、图层清单（天空/远景/中景/前景/道具）、构图比例、 光照色温关系、每类物件的形状拆解。写完自问一句"只看这段文字，我能画出那张图吗"—— 这份转写的质量就是产出的上限。
• 别让执行方自证画面。它不仅看不见，还会因为 shell 里的 http_proxy 把 curl localhost 跑成 502 死循环（§3）。一句"渲染验收归我"能省掉整轮空转。
• 成本要如实预期：每轮 Claude 都得读一张截图，读图 token 不可省。委派省下的是代码输出 token（一个 900 行的单文件产物，这部分是大头），不是验收成本。做经济性结论时分开记（§6）。

1. 前置检查

pi --list-models 2>/dev/null | grep -iE 'deepseek-v4-pro|ling-3.0-flash' || echo "NOT-CONFIGURED"

NOT-CONFIGURED → 目标模型未接入。经 ZenMux 接入（复用现有 ZenMux key）只需在 ~/.pi/agent/models.json 的 zenmux provider models 数组里加对应条目。强档 deepseek-v4-pro：

{
  "id": "deepseek/deepseek-v4-pro",
  "name": "DeepSeek V4 Pro (ZenMux)",
  "reasoning": true,
  "thinkingLevelMap": { "minimal":"high","low":"high","medium":"high","high":"high","xhigh":"high","max":"high" },
  "input": ["text"],
  "contextWindow": 1000000,
  "maxTokens": 32768,
  "cost": { "input": 0.435, "output": 0.87, "cacheRead": 0.003625, "cacheWrite": 0 }
}

廉价快档 ling-3.0-flash（非思考，无 thinkingLevelMap；cost 促销期为 0，正式价出来后按 catalog 回填）：

{
  "id": "inclusionai/ling-3.0-flash",
  "name": "Ling-3.0-flash (ZenMux)",
  "reasoning": false,
  "input": ["text"],
  "contextWindow": 262144,
  "maxTokens": 8192,
  "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
}

（ZenMux catalog id 与实时价用 curl -s https://zenmux.ai/api/v1/models -H "Authorization: Bearer $ZENMUX_API_KEY" 复核。若无 ZenMux key，跑 /pi-setup 配一个。）加完 pi --list-models | grep -E 'deepseek-v4-pro|ling-3.0-flash'：deepseek 应显示 context 1M / thinking yes / images no，ling 应显示 context 262K / thinking no / images no。再对目标模型发一条 pi -p "回OK" 冒烟确认联通。

推理档位：deepseek-v4-pro 是推理型，委派编码任务建议开思考（让它在"写-测-喂报错"里自查纠错）。上表 thinkingLevelMap 已把常用档位映射到 high（DeepSeek 低档位多为 null/不支持，映射到 high 最稳）。纯批量/低延迟的结构化转换任务想省 token，可临时压低。ling-3.0-flash 无思考档（ZenMux 上 reasoning=false，实测 reasoning_effort=none 仍会漏出少量 reasoning，无法完全关闭也无法调高）——它靠的是 tsc/schema 这类外部可验证节点纠错，不是内部推理，所以给它的任务务必带强类型编译或 schema 校验当兜底。

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

任务书质量决定产出质量（即便执行方会推理，仍别指望它猜你的意图）。必含五要素：

1. 目标：一句话 + 产物形态（如"单文件 index.html，无构建步骤"）。
2. 硬性约束：技术选型、禁止事项（如"禁止手搓几何体"）、CDN/依赖方式。
3. 资源：外部 URL Claude 先自己 curl -sI -L 验证过再写进任务书；把"先确认资源存在再用"写成显式步骤。
4. 验收标准：写明你将如何验收（零 console error、截图哪些功能等），让它对着靶子施工。
5. 汇报格式：完成后报告最终选用的资源 URL、验证方式、自检结果，以及是否改动了你给的成品代码/坐标（应为「无」）。

spec 的正确性是你的责任：执行方会忠实执行任务书，包括你写错的地方——它不会替你 catch spec bug。几何/坐标/朝向这类你替它算好的数，写进任务书前自己先过一遍脑子。

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

• 施工前先对规格（Spec-Driven）：复杂/多文件改动，先让它复述任务并列出"本次要改哪些部分"，你核对无误再放它动手。deepseek 有 1M 上下文，漏改风险低于 ling 级，但联动修改仍易架构漂移，先对齐一次比事后返工便宜。
• 优先强类型语言：能上 TypeScript 就别用裸 JS。编译器的严格报错是它"写-测-喂报错"自愈闭环的可验证节点。同理批量结构化输出用 JSON Schema/Pydantic 约束。
• 「替换函数/整块重写」要显式写"删除旧的 X"：实测执行方在"用新函数替换旧函数"时容易留下旧定义，JS 里重复的 function 声明是致命 SyntaxError→整页白屏。任务书里把"删除原 X"写成显式步骤；验收时优先对产物做语法检查（见 §5 第 2 条）。

2.3 没有编译器，就自己造一个可验证节点

给 ling 的核心拐杖是"强类型编译或 schema 兜底"。但有整类任务天然没有：单文件 + CDN 的 前端产物（无 tsc、无 schema，node --check 只能抓语法）、纯 canvas/WebGL 渲染、shell 胶水。 这时由 Claude 写一个无头验证脚本，当任务书的一部分交付，让它替代编译器：

// Claude 预先写好；任务书写明"只运行，不修改"
await page.goto('http://localhost:8099/');
await page.click('#btnStart');
await new Promise(r => setTimeout(r, 2000));
const probe = await page.evaluate(() => ({
  errs:  window.__errs,                              // console + pageerror 收集
  h:     [-80,-40,0,40,80].map(x => terrainH(x, 0)), // 关键函数值域探针
  calls: renderer.info.render.calls,                 // draw call 上限
}));

要点：

• 断言给数值，不给形容词：terrainH 在 x∈[-80,80] 必须落在 [-8, 30]； calls < 400；errs.length === 0。执行方要的是红/绿信号，不是审美判断。
• 把探针挂在 window 上（或导出）作为硬性接口写进 spec，否则每轮 harness 都要改。
• 无头跑 WebGL 需要 --enable-unsafe-swiftshader --use-angle=swiftshader； 帧率会掉到个位数（"滑了 5 米速度 94 km/h"就是这么来的），但画面正确性不受影响， 截图照样能用来判断渲染对不对。

2.4 产物规模 vs maxTokens：一条可以先算的硬约束

写任务书前先估产物行数，跟执行方的 maxTokens 对一下：

模型	maxTokens	单轮可写代码量（约 3 字符/token）
ling-3.0-flash	8192	~25k 字符 ≈ 600–800 行
deepseek-v4-pro	32768	~100k 字符 ≈ 2500+ 行

超了就必须提前拆，二选一：

• 拆成多文件（前端可用 <script type="module"> 引外部 .js，依然零构建），每个单元单轮写得完；
• 禁止全文件重写，任务书写死"只允许定点补丁 / 只输出改动的函数"。

不拆的后果是它中途被截断、或者自作主张精简掉一半功能还报"已完成"。 产物量级本身就是选模型的一个理由——900 行的单文件产物，光这一条就该走 deepseek 档。

3. 驱动

下方命令以 --model deepseek/deepseek-v4-pro 示例；用廉价快档时把它换成 --model inclusionai/ling-3.0-flash，其余流程一致。tmux 里也可用 --model 启动或进 pi 后 Ctrl+P 切换，发任务前先看状态栏确认是目标模型。

一次性任务：pi -p（含硬超时）

cd <工作目录> && pi --provider zenmux --model deepseek/deepseek-v4-pro -p "<任务书>"

必须包硬超时：ZenMux 偶发请求级死挂（进程 CPU 冻结、零输出，实测约 1/10 会话）。macOS 默认没有 timeout，用以下之一：

• 有 GNU coreutils：gtimeout 600 pi --provider zenmux --model deepseek/deepseek-v4-pro -p "..."
• 便携看门狗（无 coreutils）：

  pi --provider zenmux --model deepseek/deepseek-v4-pro -p "..." & PID=$!
  ( sleep 600; kill -0 $PID 2>/dev/null && kill $PID 2>/dev/null ) & WD=$!
  wait $PID; kill $WD 2>/dev/null
  

• 在本 agent 环境里：直接用 Bash 工具的 run_in_background: true 起 pi，再用 Monitor/轮询看输出——这天然带超时且不占前台。

超时后先 curl -s -o /dev/null -w '%{http_code}' https://zenmux.ai/api/v1 确认网关可达（秒回即可，404 也算通），然后原样重跑——瞬态故障重跑通常立刻成功。最多重试 2 次。

多轮/长程任务：tmux 交互会话（推荐，天然免 timeout）

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

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 确认）；确认状态栏显示 deepseek/deepseek-v4-pro 再发任务
# 若默认模型不是它：进 pi 后可 Ctrl+P 切换，或用 --model 启动：pi --provider zenmux --model deepseek/deepseek-v4-pro

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；本 agent 里可用后台循环检测 "Working..." 消失来判空闲

启动即挂起（job control quirk，实测高频）：pi 一起就被 shell 挂到后台，capture-pane 返回完全空白、trust 提示都不显示。判据：ps aux | grep '[p]i' 看到 pi 进程状态为 T（stopped）。解法：tmux send-keys -t pi-sub -l 'fg'; tmux send-keys -t pi-sub Enter 拉回前台，trust 提示随即出现。别把空白 pane 误判为启动失败去重开。

挂死判定两条都要：

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

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

验收失败时用结构化 bug 报告喂回：「当前情况是…（含具体报错/截图观察），预期情况是…（引用验收标准）」。一次只报一个问题域；坐标/数值类修复把算好的确切值直接写进反馈（执行方照抄=它的强项）。同一问题最多 2 次反馈——2 次修不好即触发裁决（§6），继续喂只会烧 token 不会收敛。

视觉缺陷必须翻译成数值处方。执行方看不见画面，"太白了""不好看"对它是纯噪音； 诊断（哪个参数错了）是 Claude 的活，它只负责施工。对照示例（均为实测）：

截图上看到的	❌ 无效反馈	✅ 数值处方
两侧白墙挡住天空	"山谷太窄"	侧壁项 0.055*d*d → Math.min(0.0062*d*d, 21)
雪面全屏死白、没有体积	"雪没层次"	HemisphereLight skyColor 0xdcecff→0x8fb9e2、intensity 1.15→1.05、toneMappingExposure 1.06→0.98
近处粒子是白色方块	"雪雾很丑"	PointsMaterial 加 64×64 径向渐变 canvas 作 map，配 depthWrite:false
角色脚下一块灰色多边形	"阴影不对"	删掉假接触阴影圆片，改依赖已启用的 shadow map

规律：处方 = 具体符号 + 旧值 → 新值。给得出这个三元组才发反馈；给不出说明诊断还没做完， 先自己再读一遍截图，别把诊断工作转嫁给执行方。

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

执行方会自报 "All checks passed / 已完成"，照单全收等于没验收。Claude 亲自跑：

1. 外链：产物里全部外部 URL curl -sI -L 逐个 200。
2. 静态 review / 语法检查：API 用法、回调结构、明显 bug；单文件 web 产物先抽出脚本体 node --check（能一秒逮到重复声明/括号不配等致命 SyntaxError——这类会让整页白屏而 console 未必立刻可见）。

   awk '/<script type="module">/{f=1;next} /<\/script>/{f=0} f' index.html > /tmp/m.mjs && node --check /tmp/m.mjs
   

3. 运行时：web 产物起 python3 -m http.server + agent-browser 打开——console 零 error、截图确认功能可见（含手机竖屏视口）、模拟点击/拖拽/按键验证交互；脚本类直接跑并断言输出。
4. 验收产物（截图、curl/node --check 结果）存盘，和结论一起写进运行日志。

deepseek-v4-pro 纯文本、无多模态（catalog input_modalities:["text"] 复核）——看不懂截图/音频，做不了视觉自检。这正是运行时/截图验收必须由 Claude 亲自跑的原因：执行方连"页面长歪了 / 磁带被挡住看不见"都感知不到，却照报"已完成"。

连它能做的文本级自检也别过度指望：执行方起本地 server 后自己 curl localhost 可能因 shell 里的 http_proxy 一路 502、卡进"反复重试 curl"的死循环（§3 第二种挂死）。别让它自证运行时——直接告诉它"不用自己验，我来渲染验收"，把轮次省下来。

视觉任务里，第 3 步不是闸门而是回路的一环。 实测一个 three.js 场景的四个缺陷里有三个 （侧壁把山谷做成峡谷、环境光导致全屏死白、无贴图粒子渲染成方块）——代码不报错、逻辑没问题、 console 干净，只有把帧渲染出来看才发现。所以别把"渲染截图"排在最后当放行检查， 要每轮都跑：执行方改完 → Claude 立刻渲染读图 → 开数值处方（§4）→ 下一轮。 跑三轮截图比读三遍代码有效得多。

6. 失败裁决与记录

• 同一问题 2 次反馈未修复 → 判定超出能力圈：Claude 收回自己写、或重设计任务形状（见 §0）再委派。如实记录降级原因——这是数据不是丢脸。
• 纯机械小修（删死代码/改一个常量）Claude 可直接接手，比再走一个委派往返更省（生产模式下，见边界）。
• 全程计量：pi 侧轮次、挂死/重试次数、Claude 侧驱动 token + deepseek 计费。事后对比"委派总成本 vs 自己写"，回填 §0 的判断表（尤其把 deepseek 的真实弱区补进 ⚠️待实测 处）。
• 视觉任务的计量要拆两笔：①执行侧代码输出 token（委派真正省下的）②Claude 侧读图 token （每轮一张截图，不可省，且随轮数线性增长）。只报总账会看不出委派到底赚没赚—— 轮数一多，②完全可能吃掉①。这也是判断"下次这类任务还委不委派"的唯一依据。

边界

• 密钥绝不进任务书/日志（pi 配置已用惰性 shell 读 ZenMux key）。
• 生产模式下验收通过即可交付，Claude 可在裁决后 / 对机械小修接手改码；若是对照实验/评测，执行方必须独立完成全部代码，Claude 只反馈不改码。
• tmux 会话任务结束后保留供用户复查，报告里给出 tmux attach -t <session>。
• 两个执行模型按开头选型表选：默认强档 deepseek-v4-pro；任务规整、有强类型可验证节点、主要是"照 spec 装配"时用廉价快档 ling-3.0-flash（叠加「ling 实测画像」的加码纪律）。全程计量时分别记录用的是哪个模型与其计费（ling 促销期为 0，正式价出来后据实回填）。