stepwise 0.5.0 更新方案

临时文档 · 2026-10-30 · 来源：本机 pi 会话的分析结论（pi-desktop Stepwise 0.5.0 与本机 stepwise 的对比）

零、你提的问题

  1. 在这里实现 0.5.0 的功能，同时把本机 stepwise 独有的功能整合进 0.5.0。
  2. 要和这里的其他 skill（iter-mgt、site-builder、site-test、web-research）结合。
  3. 我能不能更新这里的 stepwise skill？
  4. 给出大致的工作项、成本和风险分析。
简短回答：可以更新，但要换个地方改。本机的 stepwise 不归 skill_mgt 管，而是在一个多台机器共用的 git 仓库里。这一点决定了整个方案怎么做。

一、能不能改这里的 stepwise

事实说明
/root/.agents/skills 实际是一个链接，指向 /opt/pi-agent-skills/skills生效目录就是这个 git 仓库的工作区
仓库远端是 github.com/alangao2025-dev/pi-agent-skills按仓库 README，所有机器都从这里 git pull，改动发布后全部机器一起更新
本机 gh 已登录 alangao2025-dev，就是仓库所有者技术上有提交和推送权限
skill_mgt 的 README 写着“上层管理员负责，不要改”指的就是这个仓库
仓库里 iter-mgt/、web-research/ 是未跟踪文件它们是 skill_mgt/sync.sh 复制进来的，其他机器上没有
docs/stepwise-usage.md 写明本机版本由 Windows 版 0.4.0 改造而来里面的“与 Windows 版的差异”表正好可以当这次的移植清单

结论：

二、整合思路：以 0.5.0 为底，补回本机差异，再接上其他 skill

A. 采用 0.5.0 原有的功能

B. 补回本机的改动

  1. 目录结构：两个 skill 目录，脚本放在 stepwise-run/scripts/，修正脚本里查 kinds.json 的路径（0.5.0 写死为 ../skills/ref/kinds.json）
  2. 不用 asktool，改为一条消息列出全部问题
  3. 子代理用 Agent 工具（general-purpose），cheap 档模型用 ds/deepseek-v4-flash（0.5.0 写的 custom/… 在这里调用不到）
  4. 里程碑结束不重置上下文
  5. 验收只用 Debian 上已有的工具，不用浏览器（按 debian-env.md）
  6. 自动触发、面向不懂技术的用户；没有设计文档时代写（design-template.md）
  7. pi-cloud 任务面板：task-panel.mjs 接回脚本。原来 4 个调用点重新对应（cmdArchive 改为 close），docs/impl 判断改为 Execution_Plans，一个项目有多个计划时每个计划对应一个面板任务

C. 接上其他 skill

skill怎么整合
iter-mgt迭代编号用同一套：stepwise 的 ITER-01 和 iter-mgt 的 ITER1 二选一，建议跟 iter-mgt 用 ITER1。iter-mgt 登记实施计划时，改为登记已关闭的 Execution_Plans/<迭代>/<计划>；关闭迭代前检查总清单里这个迭代的计划都已关闭；冻结范围加上 Execution_Plans/<迭代>/；design 计划产出的需求和设计文档放到 docs/<迭代>/ 下，自动登记成交付物版本
site-builder / site-testdev 计划保留“是否发布、是否测试”的提问和对应步骤；test 类型先不做，以后可以用 site-test 实现 kind-test.md
web-research需要联网核对时（写 research.md）改为加载 web-research，不再记为“未核对”

三、工作项、成本和风险

工作项

#工作项预计代理时间
1准备：拉开发副本、建分支、备份现有版本和 ~/.pi/agent/stepwise 索引；决定 iter-mgt、web-research 是否也提交进仓库10 分钟
2整理目录结构、修正 kinds.json 路径、改 frontmatter 和脚本路径写法20 分钟
3合并 stepwise-plan 正文：0.5.0 + B4–B6 + site-builder / site-test / web-research40 分钟
4合并 stepwise-run 正文：0.5.0 + B2–B4 + 发布、测试步骤30 分钟
5改脚本：迭代编号规则、接回 task-panel、适配多计划45 分钟
6改 iter-mgt：登记、关闭检查、冻结范围、design 产出登记；同步更新它的测试60 分钟
7新写 stepwise 冒烟测试：临时项目里跑 dev、design 各一遍完整流程，加上 LEGACY、并发和依赖、任务面板文件45 分钟
8联调：iter-mgt 开迭代 → stepwise 计划 → 关闭计划 → iter-mgt 关闭迭代30 分钟
9文档：stepwise-usage.md 差异表、仓库 README、skill_mgt README 和 sync.sh、CHANGELOG20 分钟
10发布：合并到 main、push、本机 /reload 验证，通知其他机器10 分钟
合计约 5 小时

成本

风险

风险影响应对
其他机器上还有进行中的 docs/impl 旧计划升级后这些计划变成只读，不能继续执行发布前通知大家先做完或归档；或加一个 migrate 命令把旧计划迁过来（另加约 1 小时）
推送后所有机器一起更新出问题会影响所有机器测试全部通过后再合并；先打 tag stepwise-0.4-local 方便回退
在线上目录 /opt/pi-agent-skills 里直接改正在跑的会话会读到改了一半的文件只在开发副本里改
task-panel 接口由 pi-cloud 定义多计划时面板显示可能不对第 5 项按 pi-cloud docs/TASKS.md 核对，必要时请 pi-cloud 那边确认
以后 pi-desktop 再发新版本机改动又要合并一遍改动尽量集中、写进差异表；仓库保留原包分支 upstream/stepwise，以后用 git 合并
改迭代编号规则和 0.5.0 原版的计划不兼容用 kinds.json 或配置项控制，不写死在代码里
skill_mgt 和 /opt 仓库的分工本来就混在一起以后容易同步错第 9 项写清分工：stepwise、site-* 在 /opt 仓库改，skill_mgt 只管自己的 skill

四、开工前需要你确认

  1. 你有没有 alangao2025-dev/pi-agent-skills 的维护权？有就按上面的方式开发并推送；没有就最后交一个 PR 分支。
  2. 迭代编号统一成 ITER1（跟 iter-mgt）还是 ITER-01？建议 ITER1。
  3. iter-mgt 和 web-research 要不要正式提交进 /opt 仓库？建议提交，stepwise 要依赖它们。
  4. 旧计划只做提醒，还是加 migrate 迁移命令？建议先只提醒，确实需要再加。

附：两版差异

方面本机现有版本0.5.0
打包格式pi skill：两个目录，各有 SKILL.md 和 ref/pi-desktop 插件：manifest.json；正文 skills/stepwise-plan.md、skills/stepwise-run.md，共用 skills/ref/；脚本在插件根目录 scripts/
计划存放只有一个计划，在 docs/impl/，archive 到 docs/impl-archive/Execution_Plans/ITER-01/Impl_Plan_YYYYMMDD/，多迭代多计划，close 原地关闭
计划类型只有开发计划dev、design；test 占位
新增命令—init、doccheck、close、总清单、并发提示、计划依赖
旧计划—docs/impl/ 下的旧计划只读，输出 LEGACY
项目文件不改首次 init 在 AGENTS.md / CLAUDE.md 写入固定区块
触发方式自动判断，用户不需要说特定的话用户要说“做开发计划”“stepwise 计划”等
没有设计文档代写设计文档停下，让用户先准备
发布与测试对接 site-builder / site-test，有运行环境约束没有
任务面板task-panel.mjs 对接 pi-cloud没有
提问方式一条消息列出全部问题asktool（这里没有）
cheap 模型ds/deepseek-v4-flashcustom/deepseek-v4-flash