personal-plugin

PM 驱动的 OpenCode 工作流插件——把"需求分析→规划→执行→审查"变成技术强制的闭环。

设计理念

问题

AI 编码工具（包括 OpenCode）默认工作流是：用户说需求 → AI 直接写代码 → 用户检查。

这有几个痛点：

• AI 可能理解错了需求就开始写，浪费算力
• 没有"先评审再开发"的约束机制，AI 会跳过需求分析直接动手
• 审查环节不可靠——AI 自己说"我检查过了"不等于真检查了
• 返工时缺少分级——一个 typo 和一个架构错误不应该走同样的修复流程

解决

personal-plugin 引入了项目经理（PM）角色，把开发拆成两个独立阶段：

1. PM-Demand（需求 PM）：先做需求分析、伪需求评估、验收标准制定。每份文档必须经过 Oracle 5 维度审查才能进入下一份。4 份文档全部审查通过后，才移交给规划。

2. PM-Review（审查 PM）：Atlas 执行完成后，PM-Review 做两阶段审查——先查规格符合性（对照验收标准），再查代码质量（五轴审查）。审查结论按 5 维客观标准判定偏差级别，路由到返工或重做。

技术强制

PM agent 的 prompt 里写了规则，但 prompt 是"建议"不是"强制"。personal-plugin 用 6 个 hook 做技术强制：

| Hook | 强制点 | |------|--------| | pm-path-validator | PM 只能写到 .omo/pm-work/ 下，命名必须符合 7 类白名单，marker 文件不可伪造 | | pm-doc-gate | 有未审查文档时不能写新文档，已审查通过（locked）的文档不可修改 | | pm-marker-creator | Oracle 输出 <review-verdict> 标记后自动创建 marker，PM 无法绕过审查 | | pm-task-guard | PM-Demand 只能 task 委派 oracle/explore/librarian/metis，不能直接启动 atlas/prometheus | | review-routing-gate | PM-Review 路由必须有据（pass-finish 需无偏差、task-rework 需具体 file:line），循环退出有上限 | | skill-permission-enforcer | 全局禁用 brainstorming（PM 全权负责需求），PM 不可加载编程类 skill |

零侵入

• 不修改 omo 源码（照抄模式/设计思路，自己写代码）
• atlas 侧零介入——Phase E 审查在 PM-Review，不依赖阻止 atlas continuation
• 规则前置到 plan（Prometheus 生成的计划自带规则要求），不注入 agent prompt
• spec-sync 复用 omo 原生 Final Wave 强制机制

安装

全局安装（推荐）

npm i -g personal-plugin
personal-plugin install

安装脚本会在 ~/.config/opencode/opencode.json 的 plugin 数组中添加 "personal-plugin@latest"。opencode 启动时自动从 npm 下载并加载插件（缓存于 ~/.cache/opencode/node_modules/）。

安装脚本不设置 default_agent。用户通过 slash command（/pm-demand、/pm-review 等）或手动切换 agent 使用。

远程一键安装

任意平台（需已安装 Node.js + npm）：

bunx personal-plugin install

Ubuntu / Linux / macOS / Windows Git Bash（仅需 Node.js + npm）：

curl -fsSL https://gitee.com/mischiefs/personal-plugin/raw/master/bootstrap.sh | bash

Windows PowerShell：

irm https://gitee.com/mischiefs/personal-plugin/raw/master/bootstrap.ps1 | iex

手动配置

如果不想运行安装脚本，也可以手动在 opencode.json 中添加：

{
  "plugin": ["personal-plugin@latest"]
}

opencode 启动时自动从 npm 安装，无需额外步骤。

验证安装

重启 opencode 后，TUI 中应可见：

• 3 个 agent：pm-demand、pm-review、prd-reviewer
• 7 个 slash command 可调用：/pm-demand、/pm-review、/demand-plan、/work-review、/pass-finish、/task-rework、/plan-redo
• skill 可加载

工作流

闭环全景

用户提出需求
     │
     ▼
┌──────────────┐
│ PM-Demand    │  需求分析、伪需求评估、验收标准、技术规范
│ (需求 PM)    │  产出 4 份文档，每份经 Oracle 审查
└──────┬───────┘
       │ demand-plan skill（携带规则清单 + Final Wave 结构要求）
       ▼
┌──────────────┐
│ Prometheus   │  基于需求文档制定分步计划
│              │  每个 task 注明规则要求 + 偏离确认
└──────┬───────┘
       │ start-work skill
       ▼
┌──────────────┐
│ Atlas        │  执行计划，委派 task 给 Sisyphus-Junior
│              │  完成后进入 Final Wave（spec-sync 检查）
└──────┬───────┘
       │ work-review skill
       ▼
┌──────────────┐
│ PM-Review    │  Phase E 两阶段审查：
│ (审查 PM)    │  阶段一：规格符合性（对照验收标准）
│              │  阶段二：代码质量（五轴审查）
└──────┬───────┘
       │
       ├─ 通过 ─→ pass-finish → 归档 → 完成
       │
       ├─ task 级偏差 ─→ task-rework → Atlas 返工（回到 PM-Review）
       │
       └─ 计划级偏差 ─→ plan-redo → Prometheus 重做计划

偏差级别判定（5 维客观标准）

PM-Review 审查后，按以下标准判定偏差路由：

| 维度 | task 级（→ task-rework） | 计划级（→ plan-redo） | |------|--------------------------|----------------------| | 影响 task 数 | 1-2 个 | ≥3 个 | | 偏差根因 | 实现代码（file:line） | 计划文档（拆解/遗漏） | | 验收标准 | 标准正确，实现未达标 | 标准未覆盖（计划遗漏） | | 修复范围 | 局部代码修改 | 需重新拆解 task | | 需求理解 | 正确，实现偏离 | 偏差，方向错误 |

循环退出

| 路径 | 上限 | 触发动作 | |------|------|---------| | task-rework | 同一 task ≤ 3 次 | 第 3 次后强制升级为 plan-redo | | plan-redo | ≤ 2 次 | 第 2 次后请求用户介入 | | 累计偏差 | ≤ 5 项 | 请求用户介入 |

移交确认

每个移交 skill 执行前，用 question 工具询问用户确认（确认/取消/修改），确保用户对工作流的关键节点保持控制权。

组件

Agent（2 个）

| Agent | 职责 | 权限 | |-------|------|------| | pm-demand | 需求分析、规范制定 | 只写 .omo/pm-work/**，bash deny，task 仅限 oracle/explore/librarian/metis | | pm-review | Phase E 审查、偏差路由 | 只写 .omo/pm-work/**，bash deny，read allow（需读代码做质量审查） |

Skill（6 个移交 + 24 个工程技能）

6 个移交 skill（工作流状态机）：

| Skill | 流向 | 触发条件 | |-------|------|---------| | demand-plan | PM-Demand → Prometheus | 4 份需求文档审查通过 | | start-work | Prometheus → Atlas | 计划就绪 | | work-review | Atlas → PM-Review | 所有 task + Final Wave F0 完成 | | pass-finish | PM-Review → 完成 | 审查通过 | | task-rework | PM-Review → Atlas | task 级偏差 | | plan-redo | PM-Review → Prometheus | 计划级偏差 |

24 个工程技能（从 agent-skills 集成，已适配 OpenCode）：spec-driven-development / test-driven-development / code-review-and-quality / incremental-implementation / planning-and-task-breakdown / doubt-driven-development / using-agent-skills / interview-me / idea-refine / debugging-and-error-recovery / code-simplification / api-and-interface-design / frontend-ui-engineering / ci-cd-and-automation / deprecation-and-migration / documentation-and-adrs / git-workflow-and-versioning / observability-and-instrumentation / performance-optimization / security-and-hardening / shipping-and-launch / source-driven-development / context-engineering / browser-testing-with-devtools

Hook（6 个，全部 PM 侧）

| Hook | 事件 | 作用 | |------|------|------| | pm-path-validator | tool.execute.before | 路径命名强制 + marker 防伪 | | pm-doc-gate | tool.execute.before | 文档审查门控（状态机：drafting→locked/rejected） | | pm-marker-creator | tool.execute.after | 解析 Oracle <review-verdict> 自动建 marker | | pm-task-guard | tool.execute.before | pm-demand 的 task 仅限 oracle/explore/librarian/metis | | review-routing-gate | command.execute.before | 偏差路由必须有据（文件存在性验证） | | skill-permission-enforcer | tool.execute.before | 禁用 brainstorming + PM 权限白名单 |

开发

# 克隆仓库
git clone https://gitee.com/mischiefs/personal-plugin.git
cd personal-plugin

# 安装依赖
bun install

# 编译
bun run build

# 运行测试（225 tests）
bun test

# 打包 tarball
bun run pack

技术栈

• Runtime：Bun
• Language：TypeScript（strict mode）
• Test：bun:test
• Build：bun build（bundled，零外部依赖）
• License：omo 照抄模式（不复制代码），Sustainable Use License 兼容

文件结构

personal-plugin/
├── src/
│   ├── hooks/          # 6 个 PM 侧 hook
│   ├── utils/          # 5 个工具函数（路径/marker/handoff/boulder/agent）
│   ├── config/         # config hook 注册逻辑
│   └── index.ts        # 插件入口
├── agent/              # 2 个 agent 定义
├── command/            # 2 个 slash command
├── skills/             # 30 个 skill（6 移交 + 24 工程技能）
├── dist/index.js       # 编译产物（预编译入库，用户无需 build）
├── install.mjs         # 安装脚本（Node.js）
├── bootstrap.sh        # Linux/macOS 一键安装
├── bootstrap.ps1       # Windows PowerShell 一键安装
└── package.json

依赖

• oh-my-openagent（omo）—— 提供 Prometheus / Atlas / Oracle / Sisyphus-Junior 等 agent + boulder-state / Final Wave 机制

personal-plugin 是 omo 的业务层补充，不替代 omo 的任何组件。