pi-task：把本地模型的 coding 请求压成可恢复的 spec 流水线
本地 coding agent 的一个老问题是，模型不一定缺能力，而是缺一个稳定的工作节奏。你给它一个稍复杂的改动，它可能先读错重点，再补几个猜测，最后把一份看似完整的计划交出来。问题不只在模型大小，也在流程：一个长 prompt 同时承担澄清需求、查项目、查外部资料、做取舍、写 spec 和自我检查，任何一步飘了，后面的内容都会一起变形。
今天看的是 mjasnikovs/pi-task。它是给 Earendil 的 Pi coding agent 用的扩展，思路不是再加一个更聪明的 agent，而是给本地模型套上一条固定的任务流水线。README 把核心流程拆成 refine、research、grill、compose、critique 五个阶段：先把请求收紧，再并行查上下文，然后追问灰区，接着写 spec，最后做一次质量审查。每个阶段边界都会写入 .pi-tasks/TASK_NNNN.md，所以任务可以在崩溃、重启或取消后恢复。
按 GitHub repository page、GitHub 页面嵌入数据、README、LICENSE、Tags、Releases 页面、package.json 和 git metadata 在 2026-08-23 18:20 Asia/Shanghai 能核验的公开信息，mjasnikovs/pi-task 当前有 74 stars、5 forks。仓库主语言是 TypeScript，许可证是 AGPL-3.0-only。仓库创建于 2026-06-02 16:30:23 UTC，最近公开 push 是 2026-08-23 10:02:39 UTC，默认分支是 main。GitHub Releases 页面显示目前没有发布的 Release；最新 tag 是 v0.38.17，tag 日期 2026-08-23，对应 commit ae81dcb。npm package 名是 @mjasnikovs/pi-task，当前 package version 是 0.38.17，要求 Pi 相关 peer dependencies >=0.80.0。
项目概览
| 属性 | 详情 |
|---|---|
| 仓库 | mjasnikovs/pi-task |
| 定位 | Pi coding agent 的确定性 spec 编排扩展 |
| Stars | 74 |
| Forks | 5 |
| 主要语言 | TypeScript |
| 许可证 | AGPL-3.0-only |
| 创建时间 | 2026-06-02 16:30:23 UTC |
| 最新 push | 2026-08-23 10:02:39 UTC |
| 默认分支 | main |
| 最新 tag | v0.38.17，2026-08-23 |
| GitHub Release | 暂无已发布 Release |
| npm package | @mjasnikovs/pi-task 0.38.17 |
| 关键词 | Pi、local LLM、spec workflow、worker agents、resume、CLI |
重点不是多一个命令，而是拆掉一整块含混上下文
pi-task 的入口看起来很像普通 slash command：/task、/task-plan、/task-auto、/task-resume、/task-config。但它真正想解决的不是命令菜单，而是本地模型在长任务里容易把所有步骤混在一起的问题。
/task <prompt> 会把一次开发请求送进完整流水线。refine 阶段负责把原始请求整理成更明确的目标；research 阶段会把项目文件、API、外部资料和工具信息拆给隔离的 worker session；grill 阶段产出必须回答的澄清问题，能从上下文自动回答的就不打扰人，不能确定的才浮出来；compose 把这些信息写成实现 spec；critique 再检查 spec 是否足够清楚。
这个拆法有一个实际好处：主会话不用吞下所有原始噪音。README 里强调，网页抓取、文档查询、代码翻找会在临时 child session 里完成，主会话只拿到提炼后的结果。对本地模型尤其重要，因为上下文越乱，小模型越容易被早期错误牵着走。与其期待模型在同一个上下文里既探索又总结，不如把探索的副产物留在子会话里。
另一个细节是持久化。每个任务会落成 .pi-tasks/TASK_NNNN.md，阶段输出、决策和状态都在普通 Markdown 文件里。它不是一个只能通过 UI 看的内部数据库，而是可以读、diff、手动检查的文本。对于长时间本地 agent 工作流，这点比看起来更重要：任务跑到一半断掉时，恢复点不是一句“请继续”，而是前面阶段已经写下来的结构化状态。
它给 local LLM 补的是流程约束
很多 agent 工具喜欢强调“自主规划”，但本地模型上，自主规划往往也是失控来源。pi-task 选择把阶段顺序写死：先 refine，再 research，再 grill，再 compose，再 critique。模型可以在每个阶段里工作，但不能随意跳过阶段，也不能把 research 的猜测直接当最终 spec。
这种设计对几类任务特别有用。第一类是需求本身有灰区的改动，比如“给上传接口加限流”。如果直接让 agent 写代码，它可能先假设限流粒度、存储方式、错误响应和测试策略。/task-plan 则把规划过程显式化：它会一问一答地收集决策，允许你接受推荐、手动回答，或者在任何时候进入执行。最后只有决策部分会进入 /task，普通笔记不会被误当成需求。
第二类是跨 repo 或跨 API 的任务。research 阶段内置 web、docs、fetch 和 worker 工具，目标是让“查资料”变成独立阶段，而不是在 spec 里混入未经验证的记忆。README 里也提到，它会验证 tooling claims，避免子会话找到一个看似存在的 API 后直接污染主 spec。这个姿态很实用：AI 写错 API 名时，最麻烦的不是错本身，而是后续所有计划都围着这个错展开。
第三类是多步 feature。/task-auto 不试图一次性写完大计划，而是先拆成有序标题，再逐个标题跑完整 /task 流水线。这样每个子任务都有自己的 refine、research、grill、compose、critique，而不是共享一份越来越陈旧的大 spec。它还强调顺序执行和可恢复，这更适合本地长跑任务。
和一般 agent 编排工具的差异
Gumi 已经写过不少 agent memory、code search 和 MCP 工具，所以 pi-task 的价值不能只说“它也能让 agent 更可靠”。它更像一个贴在 Pi agent 里的 task harness，关注点是任务生命周期，而不是外部知识库或通用插件平台。
第一，它把流水线状态放在项目目录里的 Markdown 文件中。很多 agent 框架会把状态藏在自己的 session store 或 web dashboard 里，问题是你很难审计一次失败到底发生在哪里。pi-task 的任务文件虽然朴素，但符合开发者习惯：可以进 git，可以 diff，可以手动读。
第二，它有意限制每个阶段的职责。research 只做查证和提炼，grill 只负责补齐无法确定的问题，compose 才写 spec。这个边界能减少一种常见失败：模型在还没查清楚时就开始写结论，然后后面的查证只是在为结论找理由。
第三，它把本地模型的弱点当作一等约束。README 里写到 loop detector、failure classifier、stuck reply retry、command timeout、verify/enforce settings 等机制，这些不是漂亮的产品卖点，而是本地 agent 跑久以后真实会碰到的坑：卡住、重复、输出格式坏掉、命令挂起、工具结果被误解。pi-task 至少把这些情况纳入配置面，而不是假设模型永远会乖乖完成。
第四，它不是 MCP server，而是 Pi 扩展。这个边界也是 caveat：如果你不用 Pi coding agent，它不是一个可以直接接入任何 MCP client 的通用组件。它适合已经在 Pi 生态里折腾本地模型工作流的人，而不是所有 Codex、Claude Code 或 Cursor 用户。
可以怎么试
最小试法是挑一个非关键 repo，用 Pi 安装 package：
pi install npm:@mjasnikovs/pi-task然后用一个中等复杂度、但不至于真的改坏系统的任务测试 /task。比如让它为一个现有 API 写 rate limiting spec，或者让它给一个 CLI 增加配置项。重点不是马上看代码质量，而是看它产出的 .pi-tasks/TASK_NNNN.md：refine 是否把目标收紧，research 是否真的查了项目，grill 是否问到了关键灰区，compose 是否给出了可执行的 spec。
如果你更关心决策控制，可以先试 /task-plan。它适合那些你不想让 agent 自行决定的任务，比如数据库迁移方式、兼容策略、错误码设计。让模型提出问题和推荐，但由你确认关键选择，再交给 /task。这比把所有限制写进一段超长 prompt 更容易审计。
如果你想观察多任务行为，可以用 /task-auto 跑一个小 feature。不要一开始就丢给它“重构整个系统”。更合适的范围是三到五个小步骤，例如“给 CLI 增加 config file 支持，并补测试和文档”。看它如何拆标题、如何逐个执行、失败后恢复点是否清楚。
Caveats
第一，项目很年轻，而且 release 形态偏 npm/tag。仓库创建于 2026-06-02，当前 stars 只有 74，GitHub Releases 页面还没有正式 Release 条目。它适合试用和观察，不适合直接把团队关键流程押上去。
第二，它强绑定 Pi。README 写明安装需要 Earendil Pi coding agent >=0.80，package.json 里也有 Pi 相关 peer dependencies。对不用 Pi 的开发者来说，文章里的流程设计值得借鉴，但工具本身不一定能马上复用。
第三，扩展会运行代码并影响 agent 行为。它是 AGPL-3.0-only 许可证，且作为 agent 扩展进入你的本地开发环境。安装前应该读 README、LICENSE 和关键实现，最好先在 throwaway repo 或沙箱环境里试。
第四，确定性流水线不等于正确结果。它能减少“一个长 prompt 里所有事情混在一起”的失控，但不能保证 research 查全、grill 问对、spec 无误。最终仍然要看 diff、跑测试、检查外部 API 和安全边界。
总结
mjasnikovs/pi-task 有意思的地方，是它没有把可靠性完全寄托在模型变强上。它承认本地 LLM 会漂移、会卡住、会忘上下文，于是把任务拆成固定阶段，把阶段结果写进文件，把嘈杂 research 放进子会话，再把最终 spec 交回主会话。
这不是适合所有人的工具。它属于 Pi 生态，项目也还早。但如果你已经在本地模型上跑 coding agent，并且经常遇到“模型明明能写代码，却在任务组织上跑偏”的问题，pi-task 值得看一眼。它提供的不是魔法，而是一条更像工程流程的约束链。