Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

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 review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add wquguru/skills --skill pi-sub-agent

About this skill


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(廉价快档)
上下文1M256K(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 }
}

(ZenM

Read the complete source ↗