pi-sub-agent
将具体执行委派给 pi coding agent + ZenMux 便宜执行模型(默认强档 deepseek/deepseek-v4-pro:1M 上下文、推理型;廉价快档 inclusionai/ling-3.0-flash:256K、非思考、更省),Claude 负责任务-模型匹配判断、任务书编写、驱动(一次性 pi -p 或 tmux 交互长程)、硬超时重试、独立验收与失败裁决。含双模型选型、3D 素材来源、Spec-Driven、强类型可验证节点、推理档位开关等最佳实践。触发词:pi 委派、把执行外包给便宜模型、deepseek、deepseek-v4-pro、v4 pro 执行、ling、ling-3.0-flash、ling flash 执行、pi sub agent
wquguru · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add wquguru/skills --skill pi-sub-agent技能说明
name: pi-sub-agent description: 将具体执行委派给 pi coding agent + ZenMux 便宜执行模型(默认强档 deepseek/deepseek-v4-pro:1M 上下文、推理型;廉价快档 inclusionai/ling-3.0-flash:256K、非思考、更省),Claude 负责任务-模型匹配判断、任务书编写、驱动(一次性 pi -p 或 tmux 交互长程)、硬超时重试、独立验收与失败裁决。含双模型选型、3D 素材来源、Spec-Driven、强类型可验证节点、推理档位开关等最佳实践。触发词:pi 委派、把执行外包给便宜模型、deepseek、deepseek-v4-pro、v4 pro 执行、ling、ling-3.0-flash、ling flash 执行、pi sub agent license: MIT allowed-tools: "Read,Write,Edit,Bash,AskUserQuestion" version: "2.1.0"
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.31k" 实渲染 "$1.31b"(代码对、话报错);反过来也会报"已完成"而实际长歪。一律 Claude 亲自渲染/断言核对(§5)。
- 模糊逻辑反馈会带歪——排序"null 恒沉底"用口头描述反馈,它复现了
-cmpsign-flip 没修对;把确切比较器/数值贴给它才一次过(§4 的"确切值反馈"对 ling 是硬要求,不是可选)。 - 琐碎清理会空转——R4 打磨时一个
TS6133 未用变量让它对同一报错循环 5+ 次不收敛;盯 §3 第二种"有输出无进展"死循环,及时打断并贴确切一行修法(或按 §6 机械小修 Claude 直接接手)。 - 非思考档:无自适应推理兜底,跨多轮复杂调试更易架构漂移——这类任务优先给 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 }
}
(ZenM
阅读完整来源 ↗