OpenCode PowerPack

English · 中文

一个用于 OpenCode 的辅助插件，在 Superpowers 技能工作流之上叠加了 12 项能力：

| 工具 | 功能说明 | | --- | --- | | security_audit | 扫描工作区 diff，检测已提交密钥（精选 gitleaks 规则 + 熵值）以及注入/不安全 sink 风险。 | | code_review | 轻量级自动 diff 审查，关注正确性、设计合理性与可维护性。 | | architecture_review | 针对 diff 或整个代码库做结构性审查，关注耦合、分层、内聚、数据流、可扩展性与复杂度。 | | dependency_audit | 使用 osv-scanner、bun audit 或 npm audit 对依赖清单变更进行 SCA 审计。 | | continuous_learning | 挖掘近期 git 历史与项目配置，提炼约定并补充到 AGENTS.md。 | | verify_completion | 对已完成子任务进行结构化验收：schema、验收标准、回归检查。 | | orchestrate_swarm | 规划并行“分解 → 分发 → 聚合”工作流，并按依赖波次调度。 | | ultrawork_macro | 单一触发器，将任务路由到 Superpowers 链，并在必要时升级到 swarm。 | | refactoring | 以预览 diff 的形式提出行为保持的重构建议。 | | test_generation | 将变更的非测试行映射到覆盖缺口，并生成按风险排序的测试用例。 | | ralph_loop | 规划并跟踪 Ralph Loop：每次迭代完成一个待办项，直至 PRD 完成。 | | agent_pipeline | 为现有技能规划并聚合多智能体流水线（pipeline 或对抗式）；执行委托给 OpenCode 原生 task 工具。 |

设计

• 无构建步骤。 OpenCode 内置的 Bun 运行时会直接导入原始 .ts 文件。
• 纯核心、薄包装。 所有重型逻辑都放在 src/core/* 中，是纯函数并带单元测试；src/tools/* 只是薄的 tool() 包装，负责通过 Bun 的 $ 收集 git/fs 数据并调用核心。src/lib/* 存放共享辅助函数。
• 诚实面对智能体能力边界。 插件工具无法可靠地生成并行子智能体，也不应该——OpenCode 本身已有原生 task 工具。因此 orchestrate_swarm 只负责规划与调度；智能体通过原生 task 工具分发每一波任务。同理，ultrawork_macro 输出的是编排提示，而非直接执行整个工作流。
• 不默认通过。 verify_completion 会把代码无法判断的事项标记为 needsReview，而不是假装通过。

src/
  index.ts            # 插件入口 —— 注册 12 个工具
  core/               # 纯逻辑（单元测试）
  lib/                # 共享辅助：类型、diff 解析、熵值、路径、git I/O、审计日志、格式化
  tools/              # 薄 tool() 包装
skills/               # 每项能力对应一个 SKILL.md（由 install.sh 复制到 .opencode/skills/）
agents/               # 按技能分组的可复用子智能体提示（由 install.sh 复制到 .opencode/agents/）
rules/powerpack.md    # 贡献者规则（智能体上下文）
opencode.json         # 示例安装配置
scripts/
  install.sh          # 将 PowerPack 安装到 OpenCode 配置目录
  uninstall.sh        # 从 OpenCode 配置目录卸载 PowerPack

安装

前置条件

PowerPack 被设计为 Superpowers 技能工作流之上的辅助层。它不是一个强制的包依赖，但大多数 PowerPack 工具假定你已在 OpenCode 环境中使用 Superpowers 技能。

先安装一次插件依赖：

bun install

本地 / 开发安装

将插件入口符号链接，并把 skills 复制到 OpenCode 配置目录：

scripts/install.sh                 # 全局：~/.config/opencode
scripts/install.sh /path/to/repo   # 项目级：/path/to/repo/.opencode

然后在 opencode.json 中注册规则：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-powerpack"],
  "instructions": [".opencode/rules/*.md"]
}

对于全局安装，请将 instructions 指向 ~/.config/opencode/rules/powerpack.md 的绝对路径。

编辑配置后，退出并重启 OpenCode —— 配置在启动时加载一次，不会热重载。

验证安装

scripts/install.sh doctor                # 验证全局安装
scripts/install.sh doctor /path/to/repo  # 验证项目级安装

空运行

安装与卸载都支持 --dry-run / -n，可在不触碰文件系统的情况下预览变更：

scripts/install.sh --dry-run
scripts/uninstall.sh --dry-run /path/to/repo

卸载

从 OpenCode 配置目录移除 PowerPack：

scripts/uninstall.sh                 # 全局：~/.config/opencode
scripts/uninstall.sh /path/to/repo   # 项目级：/path/to/repo/.opencode

同时移除 PowerPack 及其审计日志：

scripts/uninstall.sh --purge

预览将要移除的内容：

scripts/uninstall.sh --dry-run /path/to/repo

验证已完全移除：

scripts/uninstall.sh doctor /path/to/repo

卸载后，从 opencode.json 中移除 PowerPack 条目并重启 OpenCode。

通过 npm 发布安装

包发布到 npm 后，可以按名称引用：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-powerpack"]
}

npm 的 plugin 引用仅安装工具。技能是从文件系统发现，而不是由插件注册——因此你必须把它们放到 OpenCode 查找的位置：.opencode/skills/<name>/SKILL.md（项目级）或 ~/.config/opencode/skills/（全局级）。可以复制或符号链接包里的 skills/ 目录，或运行 node_modules/opencode-powerpack/scripts/install.sh。上述本地安装方式已经帮你完成这些。

npx

本包不是 CLI；npx opencode-powerpack 没有意义。请通过 opencode.json 中的 plugin 字段安装并使用。

发布到 npm

从 packages/powerpack 目录执行：

npm login
npm publish

建议添加 prepublishOnly 脚本以运行 bun run check，确保只有通过检查的代码才会被发布。发布后，用户即可通过上方 plugin 字段安装。

开发

bun run typecheck   # tsc --noEmit
bun test            # 针对纯核心与工具包装的单元测试

生命周期钩子

PowerPack 在配置后会注册一个 tool.execute.after 钩子。默认关闭。

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    ["opencode-powerpack", { "lifecycle": { "securityAuditAfterExecute": true } }]
  ]
}

| 选项 | 默认值 | 作用 | | --- | --- | --- | | lifecycle.securityAuditAfterExecute | false | 在 OpenCode 内置的变更类工具（edit、write、patch、bash、multiedit）执行后，自动对工作区 diff 做一次轻量级 security_audit 扫描，并把结果追加到工具输出末尾。 |

由于当前 @opencode-ai/plugin SDK 未暴露 stop 钩子，verify_completion 的停止门通过可见输出实现：当 needsReview 为 true 时，工具会渲染 STOP: completion blocked — acceptance criteria need explicit confirmation.，tool.execute.after 钩子会前置 COMPLETION BLOCKED: verify_completion reports needsReview.。请将这些消息视为硬性停止，并显式确认或覆盖。

注意事项

• 工具不会修改你的代码；security_audit、code_review、dependency_audit、test_generation、refactoring、continuous_learning 都是只读的。verify_completion 仅在 runChecks: true 时运行你自己的 npm 脚本。
• 每次调用都会在 .opencode/powerpack/audit.jsonl 追加一条审计记录。活动日志超过 1 MiB 时会轮转；轮转日志保留 30 天后清理。
• 真正的多级 swarm 层级（worker 再生成子 worker）取决于 OpenCode 的 task_budget/深度特性；默认支持良好的是从主智能体发出的单级扇出。

许可证

MIT © 2026 lijiamin (李家民)。