@walke/opencode-pm-workflow

@walke/opencode-pm-workflow 是一个可发布的 OpenCode 插件包，用于把项目任务从"长期停留在需求层"推进到可验证的开发执行闭环。

当前发布版本：1.0.2。

适用场景

本工具有两种使用模式，请按你的需求选择：

关键边界：真实多 agent 分派必须在 OpenCode 进程里运行。pm-workflow 本身不实现 LLM runtime / tool 协议 / 子进程编排，这些都来自 OpenCode。pmw CLI 提供"独立可用的诊断与审计工具子集"，不能脱离 OpenCode 完成 dispatch。

项目定位

pm-workflow 不只是一个提示词 Skill，而是一个 OpenCode 扩展运行时。它提供：

• 状态与阶段机：自动判断项目当前所处阶段（idea/spec/plan/dev/review/release）
• Gate 系统：约束不安全推进，确保必要的 spec/plan/review 不被跳过
• 智能调度：按任务特征自动分派到合适的专业 agent
• 执行编排：PM 主协调，handoff 压缩，结果评估，受控自动续跑
• 诊断与工具：状态查询、健康检查、执行回执、权限管理

Command Lanes

插件提供 4 条 Command Lane 入口，用于不同审慎级别的调度预览：

核心工作流原则

pm-workflow 采用**"稳定任务域 + 外部 agent 定义绑定"**的双层模型：

• commander 是统一主协调入口
• command lanes 是 UX facade，不是第二套 runtime
• Analyzer 负责语义判断，Registry 负责 agent 定义绑定，Runtime 负责执行编排
• 新增 agent 不等于新增语义角色

核心流转：

需求压缩 → 开发实现 → 测试验证 → 发布摘要

安装

npm install @walke/opencode-pm-workflow

OpenCode 接入

推荐使用 OpenCode 官方 npm plugin 配置方式：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@walke/opencode-pm-workflow"]
}

OpenCode 会在启动时自动安装并缓存 npm plugin。仅在需要本地调试包入口时，再使用本地插件文件引用 server / TUI 子路径：

// plugins/pm-workflow-plugin.ts
export { default } from "@walke/opencode-pm-workflow/server";

// plugins/pm-workflow-plugin-tui.ts
export { default } from "@walke/opencode-pm-workflow/tui";

注意：不要同时加载源码入口、dist 入口和兼容壳，避免插件重复注册。

初次模型配置

推荐让用户和 AI 通过模板完成配置：复制 pm-workflow.models.example.json 的内容，参考其中 agent_profiles 段对每个 agent 的 role / model_traits / fallback_traits 说明，填好 default_model、default_fallback_model 或各 agent 的模型映射。每个字段同时支持完整模型 ID 和关键词（含数组形式），例如 ["claude-opus", "gpt-5.5", "gpt-5.4"]。然后让 AI 读取该模板：AI 会按 _resolve_strategy 把关键词解析为全局清单中存在的完整模型 ID（数组按顺序，第一个命中的关键词就停；多源命中时按 provider_priority tiebreak），并在写入前把展开结果展示给你确认，再合并到 ~/.config/opencode/pm-workflow.config.json 或当前项目 .pm-workflow/config.json。

模板会指导 AI 只从 OpenCode 全局 provider.*.models 清单校验模型，并同步写入 agent model、fallback_models 与 fallback.chains。

当前文档结构

本项目的现行文档已收敛为 README + 4 篇主文档：

发布前验证

npm run verify-release

发布

npm version patch --no-git-tag-version
npm run verify-release
npm publish --access public

发布后确认：

npm view @walke/opencode-pm-workflow version

缓存自愈

OpenCode 会把 npm plugin 缓存在 ~/.cache/opencode/packages/（Kilo 场景还会有 ~/.cache/kilo/packages/）。如果日志里出现旧版 mkdir '/.pm-workflow' failed，或插件缓存版本落后于 CLI，可运行：

pmw repair opencode-cache

该命令会把旧/坏的 pm-workflow plugin 缓存安全改名为 .bak-<timestamp>，下次完全重启 OpenCode 时由 OpenCode 重新安装当前版本。

Change Log