docs(ai): 新增 OpenCode superpowers 文章并更新侧边栏
This commit is contained in:
@@ -0,0 +1,109 @@
|
||||
# OpenCode Superpowers Overview Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Add one new blog post that summarizes `obra/superpowers` (OpenCode-first) + update the AI/OpenCode sidebar entry, matching this blog's writing style.
|
||||
|
||||
**Architecture:** One new Markdown article under `src/ai/` plus a small ordering update in `src/.vuepress/sidebar.ts`. Use upstream README as the source-of-truth for workflow + install commands.
|
||||
|
||||
**Tech Stack:** VuePress v2 + vuepress-theme-hope, Markdown, TypeScript config.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Gather upstream command strings + permalinks
|
||||
|
||||
**Files:**
|
||||
- Read: `~/.config/opencode/superpowers/README.md`
|
||||
|
||||
- [ ] **Step 1: Get upstream repo HEAD SHA (for permalinks)**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
git -C "$HOME/.config/opencode/superpowers" rev-parse HEAD
|
||||
```
|
||||
|
||||
Expected: prints a 40-char SHA.
|
||||
|
||||
- [ ] **Step 2: Identify exact upstream snippets to copy**
|
||||
|
||||
From upstream `README.md`:
|
||||
|
||||
- Installation commands (Claude Code official + marketplace, Cursor, Codex, OpenCode, Gemini)
|
||||
- Update command (Claude Code)
|
||||
- Verify Installation paragraph
|
||||
- Basic Workflow list
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Create the new overview post
|
||||
|
||||
**Files:**
|
||||
- Create: `src/ai/opencode-superpowers-overview.md`
|
||||
|
||||
- [ ] **Step 1: Add frontmatter + title + `<!-- more -->`**
|
||||
|
||||
Requirements:
|
||||
|
||||
- Chinese
|
||||
- Major headings `## 一、二、三...`
|
||||
- Use `---` thematic breaks between major sections
|
||||
|
||||
- [ ] **Step 2: Add sections per spec**
|
||||
|
||||
Include:
|
||||
|
||||
- What it is (1 screen)
|
||||
- Upstream Basic Workflow (7 steps; step 4 includes "subagent-driven-development or executing-plans")
|
||||
- Skill map (if/then) + links to existing posts:
|
||||
- `src/ai/opencode-superpowers.md`
|
||||
- `src/ai/opencode-skills-playbook.md`
|
||||
- Install/Verify/Update quick reference with strict fenced-block counts:
|
||||
- 5 install blocks (Claude/Cursor/Codex/OpenCode/Gemini)
|
||||
- 1 verify block (2 lines)
|
||||
- 3 update blocks (Claude/OpenCode/Gemini)
|
||||
- Cursor + Codex updates as plain text notes (no fenced blocks)
|
||||
|
||||
---
|
||||
|
||||
### Task 3: Update sidebar order
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/.vuepress/sidebar.ts`
|
||||
|
||||
- [ ] **Step 1: Insert new link under AI -> OpenCode**
|
||||
|
||||
Insert before the existing:
|
||||
|
||||
- `text: "superpowers"`
|
||||
- `link: "opencode-superpowers.md"`
|
||||
|
||||
New item:
|
||||
|
||||
- `text: "superpowers-总览"`
|
||||
- `link: "opencode-superpowers-overview.md"`
|
||||
|
||||
Ensure final order:
|
||||
|
||||
1) `opencode.md`
|
||||
2) `opencode-tui.md`
|
||||
3) `opencode-superpowers-overview.md`
|
||||
4) `opencode-superpowers.md`
|
||||
5) `opencode-skills-playbook.md`
|
||||
|
||||
---
|
||||
|
||||
### Task 4: Verify build
|
||||
|
||||
**Files:**
|
||||
- None
|
||||
|
||||
- [ ] **Step 1: Run production build**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
npm run docs:build
|
||||
```
|
||||
|
||||
Expected: `success VuePress build completed`.
|
||||
@@ -0,0 +1,211 @@
|
||||
# OpenCode Superpowers Overview Blog Post - Design
|
||||
|
||||
**Date:** 2026-03-16
|
||||
|
||||
**Goal:** Write one blog post that summarizes https://github.com/obra/superpowers in my blog style, with OpenCode as the primary viewpoint, plus a short install/verify/update quick reference for other platforms.
|
||||
|
||||
**Audience:** Self-use / quick reference. Readers already use terminals and can run commands. Minimal storytelling, maximal usability.
|
||||
|
||||
**Non-Goals:**
|
||||
- Rewriting all upstream docs.
|
||||
- Duplicating detailed OpenCode install steps already covered in `src/ai/opencode-superpowers.md`.
|
||||
- Teaching Git basics or agent fundamentals.
|
||||
|
||||
---
|
||||
|
||||
## Placement
|
||||
|
||||
- New article path: `src/ai/opencode-superpowers-overview.md`
|
||||
- Sidebar: `src/.vuepress/sidebar.ts` under AI -> OpenCode
|
||||
|
||||
**Modify file:** `src/.vuepress/sidebar.ts`
|
||||
- Ordering inside the OpenCode group (final):
|
||||
- `opencode.md`
|
||||
- `opencode-tui.md`
|
||||
- `opencode-superpowers-overview.md` (new)
|
||||
- `opencode-superpowers.md`
|
||||
- `opencode-skills-playbook.md`
|
||||
|
||||
**Exact sidebar edit:** in `src/.vuepress/sidebar.ts` under `"/ai/"` -> `text: "OpenCode"` -> `children`, insert a new item before the existing `superpowers` link:
|
||||
|
||||
- `text: "superpowers-总览"`
|
||||
- `link: "opencode-superpowers-overview.md"`
|
||||
|
||||
Insertion point must be immediately before the existing item:
|
||||
|
||||
- `text: "superpowers"`
|
||||
- `link: "opencode-superpowers.md"`
|
||||
|
||||
---
|
||||
|
||||
## Content Outline (Blog Style)
|
||||
|
||||
### Frontmatter
|
||||
|
||||
- `title`: OpenCode Superpowers：框架总览与上手路线
|
||||
- `icon`: `mdi:rocket-launch-outline`
|
||||
- `date`: 2026-03-16
|
||||
- `category` (YAML list):
|
||||
- `AI`
|
||||
- `开发工具`
|
||||
- `tag` (YAML list):
|
||||
- `OpenCode`
|
||||
- `Superpowers`
|
||||
- `Skills`
|
||||
- `工作流`
|
||||
|
||||
### Required Structure (match this blog)
|
||||
|
||||
The actual blog post must use:
|
||||
|
||||
- `#` title + `<!-- more -->`
|
||||
- Markdown thematic breaks (`---`) between major sections (these are NOT the frontmatter `---` delimiters)
|
||||
- Major headings as `## 一、二、三...` (Chinese numbered)
|
||||
|
||||
Heading format requirement:
|
||||
|
||||
- Use `## 一、...` `## 二、...` ... (Chinese numeral + `、`)
|
||||
|
||||
Recommended outline:
|
||||
|
||||
- `## 一、它是什么（1 屏）`
|
||||
- `---`
|
||||
- `## 二、上游 Basic Workflow（按上游 7 步原样列出）`
|
||||
- `---`
|
||||
- `## 三、技能选择速查（if/then + 指路）`
|
||||
- `---`
|
||||
- `## 四、安装与验证速查（OpenCode 为主 + 其他平台命令速查）`
|
||||
- `---`
|
||||
- `## 五、更新与排障（按平台）`
|
||||
|
||||
### Intro (1 screen)
|
||||
|
||||
- Superpowers = skills + initial instructions + workflow discipline.
|
||||
- Key value: forces an agent to ask, plan, verify; not "jump to code".
|
||||
|
||||
### Upstream "Basic Workflow" (match upstream)
|
||||
|
||||
The section title must clearly say this list is the upstream default workflow.
|
||||
|
||||
Upstream list (7 items) - item text and order must match upstream README "The Basic Workflow" section:
|
||||
|
||||
1) `brainstorming`
|
||||
2) `using-git-worktrees`
|
||||
3) `writing-plans`
|
||||
4) `subagent-driven-development` (or `executing-plans`)
|
||||
5) `test-driven-development`
|
||||
6) `requesting-code-review`
|
||||
7) `finishing-a-development-branch`
|
||||
|
||||
After the list, add a short "常用配套" note (not part of the upstream numbered workflow):
|
||||
|
||||
- `systematic-debugging`
|
||||
- `verification-before-completion`
|
||||
|
||||
Each step gets 1-2 lines in Chinese explaining "this step prevents X" (keep skill names in backticks unchanged).
|
||||
|
||||
Note: upstream step 4 includes `executing-plans` as the no-subagent option; keep the step title aligned with upstream wording, then explain when to use each.
|
||||
|
||||
### 3. Skill Map (quick decision)
|
||||
|
||||
Tiny "if/then" list for choosing a skill, and then point readers to `src/ai/opencode-skills-playbook.md` for full step-by-step.
|
||||
|
||||
Also address naming/prefix confusion explicitly:
|
||||
|
||||
- Load by the exact name shown in your environment.
|
||||
- If your environment shows `superpowers/<name>`, load with prefix; otherwise load the bare name.
|
||||
|
||||
Link to existing posts (avoid duplication):
|
||||
|
||||
- `src/ai/opencode-superpowers.md` (installation / verification / Windows gotchas)
|
||||
- `src/ai/opencode-skills-playbook.md` (scenarios with steps)
|
||||
|
||||
### 4. Installation Quick Reference (multi-platform)
|
||||
|
||||
Keep it short: minimal command(s) + one link to details.
|
||||
|
||||
**Source of truth requirement:** all install/update commands must be copied verbatim from upstream `obra/superpowers` docs (no guessing).
|
||||
|
||||
For each command block, add one upstream source link pointing to the exact upstream section you copied from.
|
||||
|
||||
Prefer GitHub permalinks pinned to a commit SHA (so the post stays verifiable even if upstream changes).
|
||||
|
||||
Fallback: if you cannot determine a SHA in the current environment, link to the upstream file on `main` and label it as "un-pinned".
|
||||
|
||||
**Anti-duplication guardrail (OpenCode):**
|
||||
|
||||
- Do NOT include OpenCode manual symlink/junction steps in this post.
|
||||
- Only include the upstream one-liner (Fetch and follow...) and link to `src/ai/opencode-superpowers.md` for the full manual steps.
|
||||
|
||||
Do NOT copy the one-sentence "Clone ... then symlink ..." quick install from `docs/README.opencode.md` into this overview post.
|
||||
|
||||
The post must include these platform commands (verbatim from upstream at a pinned SHA):
|
||||
|
||||
- Claude Code: official marketplace install + update
|
||||
- Cursor: plugin install command as shown in upstream README (typically `/add-plugin superpowers` in Cursor Agent chat)
|
||||
- Codex: install instruction (points to upstream `.codex/INSTALL.md`)
|
||||
- OpenCode: install instruction (points to upstream `.opencode/INSTALL.md`) + link to `src/ai/opencode-superpowers.md`
|
||||
- Gemini CLI: extension install + update
|
||||
|
||||
Add a dedicated "Verify Installation" subsection (inspired by upstream): start a new session, ask for a task that should trigger a skill, confirm it auto-invokes.
|
||||
|
||||
Make verify copy-pastable:
|
||||
|
||||
- Example verification prompt (copy-paste): `帮我做一个需求拆解，但先选择并加载一个合适的 superpowers skill 再继续。`
|
||||
- Expected: the assistant triggers a skill workflow (asks clarifying questions / produces a plan) instead of jumping straight to implementation.
|
||||
|
||||
**Command blocks requirement (actionability):**
|
||||
|
||||
- Provide one fenced block per platform (`text` or `bash`). Inside the block, include ONLY copy-pastable commands/instructions. Put the platform label outside the fenced block.
|
||||
|
||||
Make the block structure explicit:
|
||||
|
||||
- Exactly 5 install blocks (Claude Code / Cursor / Codex / OpenCode / Gemini CLI)
|
||||
- Exactly 3 update blocks (Claude Code / OpenCode / Gemini CLI)
|
||||
- Cursor + Codex updates are short plain-text notes (no code block)
|
||||
- Exactly 1 verify block (shared across platforms):
|
||||
- line 1: copy/paste verification prompt
|
||||
- line 2: what to look for
|
||||
|
||||
No extra fenced blocks are allowed inside Install/Update/Verify sections beyond the counts listed (notes must be plain text outside fences).
|
||||
Other sections may use fenced blocks if needed, but this post should keep them minimal.
|
||||
|
||||
### 5. Updating / Troubleshooting
|
||||
|
||||
Make this actionable by platform (1 line update + 1 line verify):
|
||||
|
||||
Important constraint: do not introduce inline commands here. All install/update commands must live inside the fenced command blocks defined in the "Command blocks requirement" section.
|
||||
|
||||
"Restart OpenCode" must be written as an exact action: fully quit the running opencode process (TUI/CLI) and launch it again.
|
||||
|
||||
Also include update notes to complete the "by platform" promise:
|
||||
|
||||
- Cursor: short note about Cursor plugin update mechanism; if unsure, reinstall using the same install command from the install blocks, then verify by triggering a skill.
|
||||
- Codex: short note that re-running the same upstream Codex install instruction is equivalent to updating, then verify by triggering a skill.
|
||||
|
||||
Troubleshooting should be short and point to existing detailed sections in `src/ai/opencode-superpowers.md`.
|
||||
|
||||
Duplication guardrail (enforced): the overview post may include the upstream OpenCode one-liner install instruction + a link to `src/ai/opencode-superpowers.md`, but must not reproduce the full manual symlink walkthrough.
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
- Upstream: https://github.com/obra/superpowers
|
||||
- Upstream OpenCode doc: https://github.com/obra/superpowers/blob/main/docs/README.opencode.md
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- File exists: `src/ai/opencode-superpowers-overview.md`
|
||||
- Contains: frontmatter + `#` title + `<!-- more -->`
|
||||
- Structure: uses `---` separators and `## 一/二/三...` numbered headings
|
||||
- Includes exactly 5 install fenced blocks, exactly 3 update fenced blocks, and exactly 1 verify fenced block, per the "Command blocks requirement" section
|
||||
- Each install/update command block has a nearby upstream source link.
|
||||
- Preferred: a GitHub permalink pinned to a commit SHA
|
||||
- Fallback: an "un-pinned" link to `main` clearly labeled
|
||||
- Upstream workflow section matches upstream 7-step basic workflow (and separates "配套技能" clearly)
|
||||
- Does not repeat manual OpenCode symlink steps; instead links to `src/ai/opencode-superpowers.md`
|
||||
- Sidebar updated: `src/.vuepress/sidebar.ts` includes `opencode-superpowers-overview.md` under AI -> OpenCode in the specified final order
|
||||
- Build passes: `npm run docs:build`
|
||||
@@ -245,6 +245,18 @@ export default sidebar({
|
||||
text: "opencode-tui",
|
||||
link: "opencode-tui.md",
|
||||
},
|
||||
{
|
||||
text: "superpowers-总览",
|
||||
link: "opencode-superpowers-overview.md",
|
||||
},
|
||||
{
|
||||
text: "superpowers",
|
||||
link: "opencode-superpowers.md",
|
||||
},
|
||||
{
|
||||
text: "skills-使用方案汇总",
|
||||
link: "opencode-skills-playbook.md",
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
|
||||
311
src/ai/opencode-skills-playbook.md
Normal file
311
src/ai/opencode-skills-playbook.md
Normal file
@@ -0,0 +1,311 @@
|
||||
---
|
||||
title: OpenCode Superpowers：编码 + 写博客 skills 使用方案（自用版）
|
||||
icon: mdi:checklist
|
||||
date: 2026-03-16
|
||||
category:
|
||||
- AI
|
||||
- 开发工具
|
||||
tag:
|
||||
- OpenCode
|
||||
- Superpowers
|
||||
- Skills
|
||||
- 工作流
|
||||
---
|
||||
|
||||
# OpenCode Superpowers：编码 + 写博客 skills 使用方案（自用版）
|
||||
|
||||
这篇不解释太多背景，目标是：我在写博客和写代码时，如何用 Superpowers
|
||||
这套 skills 把工作流“固定下来”，减少跑偏与返工。
|
||||
|
||||
<!-- more -->
|
||||
|
||||
---
|
||||
|
||||
## 一、先记住一句话：先定方向，再列步骤，最后做验证
|
||||
|
||||
我把 skills 当成“工作流开关”，只要记住这 3 句就够用了：
|
||||
|
||||
- 不确定怎么做：`brainstorming`（先把方向定清楚）
|
||||
- 知道要做什么但步骤多：`writing-plans`（把步骤写成清单）
|
||||
- 说“做完了”之前：`verification-before-completion`（把验证跑完再收工）
|
||||
|
||||
后面所有场景，基本都是这 3 个的排列组合。
|
||||
|
||||
---
|
||||
|
||||
## 二、最小前提：你得先能加载到这些 skills
|
||||
|
||||
我默认你已经按 Superpowers 的方式装好（仓库 + 插件 + skills symlink），并且
|
||||
OpenCode 已重启。
|
||||
|
||||
在对话里直接加载某个 skill（注意：这里的名字通常不带 `superpowers/` 前缀）：
|
||||
|
||||
```text
|
||||
use skill tool to load brainstorming
|
||||
```
|
||||
|
||||
如果你想确认当前可用 skills，可以让 OpenCode 输出“当前环境已暴露的技能列表”。
|
||||
|
||||
---
|
||||
|
||||
## 三、三种场景：按步骤直接照做
|
||||
|
||||
下面每个场景我都写成“第 1 步 / 第 2 步 / 第 3 步...”。
|
||||
你只要把 `use skill tool to load ...` 复制到 OpenCode 里就行。
|
||||
|
||||
---
|
||||
|
||||
## 四、场景 1：写新项目（从 0 到能跑）
|
||||
|
||||
目标：把事情做成，而不是先把代码写漂亮。
|
||||
|
||||
第 1 步：先把需求说清楚（brainstorming）
|
||||
|
||||
这一部的目的：把“我想做什么”说成“我到底要交付什么”，避免一上来就写错方向。
|
||||
|
||||
```text
|
||||
use skill tool to load brainstorming
|
||||
```
|
||||
|
||||
我常用输入：
|
||||
|
||||
```text
|
||||
我要做一个新项目：<一句话描述>。
|
||||
|
||||
请你：
|
||||
1) 只问我 1 个最关键澄清问题
|
||||
2) 给 2-3 种方案对比（含取舍）
|
||||
3) 给你推荐的方案（写清楚为什么）
|
||||
```
|
||||
|
||||
第 2 步：把落地步骤写成清单（writing-plans）
|
||||
|
||||
这一部的目的：把任务拆成你能按部就班执行的步骤，并且每一步都有验证方法。
|
||||
|
||||
```text
|
||||
use skill tool to load writing-plans
|
||||
```
|
||||
|
||||
我会要求它至少写清：
|
||||
|
||||
- 要建/要改哪些文件（精确路径）
|
||||
- 每一步怎么验证（命令）
|
||||
|
||||
第 3 步：按计划执行（executing-plans）
|
||||
|
||||
这一部的目的：按清单逐步推进，避免“想到哪改到哪”，也方便中途停下来复盘。
|
||||
|
||||
```text
|
||||
use skill tool to load executing-plans
|
||||
```
|
||||
|
||||
第 4 步：跑验证，确认真能用（verification-before-completion）
|
||||
|
||||
这一部的目的：用实际命令证明项目能跑/能构建，而不是凭感觉说完成。
|
||||
|
||||
```text
|
||||
use skill tool to load verification-before-completion
|
||||
```
|
||||
|
||||
第 5 步：收尾（finishing-a-development-branch）
|
||||
|
||||
这一部的目的：决定怎么合并/怎么交付/怎么清理临时分支，让工作可结束、可回滚。
|
||||
|
||||
```text
|
||||
use skill tool to load finishing-a-development-branch
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、场景 2：改已有项目（新增/修 bug/重构）
|
||||
|
||||
这个场景的关键是：先判断你现在是哪一类工作。
|
||||
|
||||
第 1 步：先选“起手 skill”（二选一）
|
||||
|
||||
这一部的目的：先选对“模式”。改功能和排障的思路完全不同，起手选错会浪费时间。
|
||||
|
||||
- 需求/改功能（容易跑偏）：用 `brainstorming`
|
||||
|
||||
```text
|
||||
use skill tool to load brainstorming
|
||||
```
|
||||
|
||||
- 报错/构建失败/线上行为不对：用 `systematic-debugging`
|
||||
|
||||
```text
|
||||
use skill tool to load systematic-debugging
|
||||
```
|
||||
|
||||
第 2 步：把修改拆成可执行清单（writing-plans）
|
||||
|
||||
这一部的目的：把改动限制在可控范围里，避免无意改到无关文件。
|
||||
|
||||
```text
|
||||
use skill tool to load writing-plans
|
||||
```
|
||||
|
||||
第 3 步：如果是“新增功能 / 修 bug”，优先用 TDD（test-driven-development，可选但推荐）
|
||||
|
||||
这一部的目的：先把预期行为写成测试（或可复现步骤），让修改有明确的对错标准。
|
||||
|
||||
```text
|
||||
use skill tool to load test-driven-development
|
||||
```
|
||||
|
||||
第 4 步：按计划执行（executing-plans）
|
||||
|
||||
这一部的目的：按步骤做小改动、频繁验证，减少一次性大改带来的风险。
|
||||
|
||||
```text
|
||||
use skill tool to load executing-plans
|
||||
```
|
||||
|
||||
第 5 步：完成前必须验证（verification-before-completion）
|
||||
|
||||
这一部的目的：在提交/合并前用证据确认“真的修好/真的没破坏”。
|
||||
|
||||
```text
|
||||
use skill tool to load verification-before-completion
|
||||
```
|
||||
|
||||
第 6 步：需要更稳就做一次评审（requesting-code-review，可选）
|
||||
|
||||
这一部的目的：让 AI 用审查视角检查逻辑、边界、改动范围，帮你补漏。
|
||||
|
||||
```text
|
||||
use skill tool to load requesting-code-review
|
||||
```
|
||||
|
||||
第 7 步：收尾（finishing-a-development-branch）
|
||||
|
||||
这一部的目的：把任务“结束干净”：合并策略明确、分支/工作区清理到位。
|
||||
|
||||
```text
|
||||
use skill tool to load finishing-a-development-branch
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、场景 3：写博客到当前这个博客（VuePress）
|
||||
|
||||
目标：按我博客风格产出一篇能构建通过的文章。
|
||||
|
||||
第 1 步：先把文章的边界定清楚（brainstorming）
|
||||
|
||||
这一部的目的：确定文章要写给谁、要解决什么问题、最终交付什么文件。
|
||||
|
||||
```text
|
||||
use skill tool to load brainstorming
|
||||
```
|
||||
|
||||
我常用输入：
|
||||
|
||||
```text
|
||||
把这篇文章整理到我的 VuePress 博客（当前仓库）里。
|
||||
|
||||
要求：
|
||||
1) 中文，偏实战
|
||||
2) 要有 frontmatter + <!-- more -->
|
||||
3) 命令块可复制，少废话
|
||||
4) 产物：1 篇 Markdown + 如需要更新 sidebar
|
||||
5) 验收：npm run docs:build 通过
|
||||
```
|
||||
|
||||
第 2 步：先写提纲 + 文件清单（writing-plans）
|
||||
|
||||
这一部的目的：先把结构定住（标题/小节/命令块），写作时不跑题。
|
||||
|
||||
```text
|
||||
use skill tool to load writing-plans
|
||||
```
|
||||
|
||||
第 3 步：按清单写文章/改 sidebar（executing-plans）
|
||||
|
||||
这一部的目的：按提纲逐段落地，并确保目录/导航能找到文章。
|
||||
|
||||
```text
|
||||
use skill tool to load executing-plans
|
||||
```
|
||||
|
||||
第 4 步：构建验证（verification-before-completion）
|
||||
|
||||
这一部的目的：用构建结果证明“文章不会把站点打挂”。
|
||||
|
||||
```text
|
||||
use skill tool to load verification-before-completion
|
||||
```
|
||||
|
||||
对本仓库最关键的验收命令就是：
|
||||
|
||||
```bash
|
||||
npm run docs:build
|
||||
```
|
||||
|
||||
第 5 步：需要更稳就让它做一次“编辑校对”（requesting-code-review，可选）
|
||||
|
||||
这一部的目的：检查表达是否清晰、命令是否危险/错误、是否遗漏验收。
|
||||
|
||||
```text
|
||||
use skill tool to load requesting-code-review
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、并行提效（可选）：任务隔离 + 多任务并发
|
||||
|
||||
如果你同时推进多个任务（例如：写两篇文章 + 修一个构建问题），建议用这两件事：
|
||||
|
||||
1) `using-git-worktrees`：把任务隔离到不同 worktree，避免 diff 越滚越大。
|
||||
2) `dispatching-parallel-agents`：把互不依赖的子任务拆开并行跑。
|
||||
|
||||
加载方式：
|
||||
|
||||
```text
|
||||
use skill tool to load using-git-worktrees
|
||||
use skill tool to load dispatching-parallel-agents
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 八、附录：我常复制的提示词块
|
||||
|
||||
### 6.1 整理外部文章到博客
|
||||
|
||||
```text
|
||||
请把这篇文章整理成我的博客风格（VuePress）。
|
||||
|
||||
要求：
|
||||
1) 中文输出，分段用 ---，小节用“## 一/二/三”。
|
||||
2) 必须包含 frontmatter（title/date/category/tag/icon）和 <!-- more -->。
|
||||
3) 内容偏实战：命令、坑点、验证步骤优先。
|
||||
4) 不要照搬原文结构，按“我会怎么用”重组。
|
||||
5) 产物是 1 篇 Markdown（给出建议文件名）。
|
||||
```
|
||||
|
||||
### 6.2 改代码前先要执行计划
|
||||
|
||||
```text
|
||||
先不要改代码。
|
||||
请输出一个可执行的实施计划：
|
||||
- 要改的文件路径清单
|
||||
- 每一步做什么
|
||||
- 每一步如何验证（命令）
|
||||
- 最后必须给出完整的验收命令集合
|
||||
```
|
||||
|
||||
### 6.3 构建失败/运行报错时的排障输入
|
||||
|
||||
```text
|
||||
我遇到一个错误，请按系统化排障流程来。
|
||||
|
||||
复现步骤：
|
||||
1) ...
|
||||
2) ...
|
||||
|
||||
期望行为：...
|
||||
实际行为：...
|
||||
|
||||
错误输出（完整粘贴）：
|
||||
...
|
||||
```
|
||||
207
src/ai/opencode-superpowers-overview.md
Normal file
207
src/ai/opencode-superpowers-overview.md
Normal file
@@ -0,0 +1,207 @@
|
||||
---
|
||||
title: OpenCode Superpowers：框架总览与上手路线
|
||||
icon: mdi:rocket-launch-outline
|
||||
date: 2026-03-16
|
||||
category:
|
||||
- AI
|
||||
- 开发工具
|
||||
tag:
|
||||
- OpenCode
|
||||
- Superpowers
|
||||
- Skills
|
||||
- 工作流
|
||||
---
|
||||
|
||||
# OpenCode Superpowers：框架总览与上手路线
|
||||
|
||||
Superpowers 不是“又一套提示词”，而是一套给编码代理用的开发方法：
|
||||
强制先澄清、先写计划、再执行、最后验证。
|
||||
|
||||
这篇以 OpenCode 为主视角，把上游仓库 `obra/superpowers` 的核心要点整理成一篇
|
||||
可直接照着用的速查。
|
||||
|
||||
<!-- more -->
|
||||
|
||||
---
|
||||
|
||||
## 一、它是什么（1 屏）
|
||||
|
||||
一句话：Superpowers = skills 库 + 强制工作流 + 初始指令注入，让代理按流程做事。
|
||||
|
||||
它主要解决三类问题：
|
||||
|
||||
1. 还没想清楚就开写：越写越偏，返工成本高。
|
||||
2. 任务太大没拆分：改动越滚越大，diff 失控。
|
||||
3. 没验证就宣布完成：靠感觉收工，最后还是你来擦屁股。
|
||||
|
||||
上游仓库：`https://github.com/obra/superpowers`
|
||||
|
||||
---
|
||||
|
||||
## 二、上游 Basic Workflow（按上游 7 步列出）
|
||||
|
||||
下面这一段的“步骤名称与顺序”对齐上游 README 的 `The Basic Workflow`。
|
||||
我在每一步后面加一行白话解释，方便快速理解。
|
||||
|
||||
1. **brainstorming** - Activates before writing code. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. Saves design document.
|
||||
白话：先问清楚需求边界，给方案对比，并写成可复用的设计稿，避免直接开写。
|
||||
|
||||
2. **using-git-worktrees** - Activates after design approval. Creates isolated workspace on new branch, runs project setup, verifies clean test baseline.
|
||||
白话：把任务隔离到独立分支/工作区，避免污染主分支，也方便并行做多个任务。
|
||||
|
||||
3. **writing-plans** - Activates with approved design. Breaks work into bite-sized tasks (2-5 minutes each). Every task has exact file paths, complete code, verification steps.
|
||||
白话：把“要做什么”拆成清单：改哪些文件、每一步怎么验收，尽量 2-5 分钟一个小步。
|
||||
|
||||
4. **subagent-driven-development** or **executing-plans** - Activates with plan. Dispatches fresh subagent per task with two-stage review (spec compliance, then code quality), or executes in batches with human checkpoints.
|
||||
白话：按计划执行。能并行就并行（子代理），不行就分批执行并留检查点。
|
||||
|
||||
5. **test-driven-development** - Activates during implementation. Enforces RED-GREEN-REFACTOR: write failing test, watch it fail, write minimal code, watch it pass, commit. Deletes code written before tests.
|
||||
白话：先让测试失败，再写最小实现让它通过；不写测试的代码宁可删掉重来。
|
||||
|
||||
6. **requesting-code-review** - Activates between tasks. Reviews against plan, reports issues by severity. Critical issues block progress.
|
||||
白话：每个阶段都做一次对计划的审查，避免悄悄偏离。
|
||||
|
||||
7. **finishing-a-development-branch** - Activates when tasks complete. Verifies tests, presents options (merge/PR/keep/discard), cleans up worktree.
|
||||
白话：收尾：验证、决定合并方式、清理分支/工作区。
|
||||
|
||||
来源（上游 README）：
|
||||
`https://github.com/obra/superpowers/blob/363923f74aa9cd7b470c0aaa73dee629a8bfdc90/README.md#L101`
|
||||
|
||||
常用配套（不在上面 7 步编号里，但非常高频）：
|
||||
|
||||
- `systematic-debugging`：遇到错误/异常时，用系统化方式定位根因。
|
||||
- `verification-before-completion`：在你说“完成了”之前，用证据证明它真的完成了。
|
||||
|
||||
---
|
||||
|
||||
## 三、技能选择速查（我实际怎么选）
|
||||
|
||||
我自己选 skill 很简单：先选模式，再推进。
|
||||
|
||||
- 不确定需求边界、方案不明确：先用 `brainstorming`。
|
||||
- 目标明确但步骤多：用 `writing-plans` 把执行清单写出来。
|
||||
- 执行过程中卡住（构建失败/行为异常）：切到 `systematic-debugging`。
|
||||
- 准备说“好了”：用 `verification-before-completion` 跑验证再收工。
|
||||
|
||||
关于加载 skill 的名字：以你当前环境输出为准。
|
||||
如果你的环境里显示 `superpowers/<name>`，就带前缀加载；否则加载裸名。
|
||||
|
||||
本博客里我已经把 OpenCode 的安装与“场景化步骤卡片”写成两篇：
|
||||
|
||||
- 安装/验证/排障：`opencode-superpowers.md`
|
||||
- 编码 + 写博客的步骤卡片：`opencode-skills-playbook.md`
|
||||
|
||||
---
|
||||
|
||||
## 四、安装与验证速查（OpenCode 为主 + 其他平台）
|
||||
|
||||
### 4.1 安装（每个平台 1 个命令块）
|
||||
|
||||
Claude Code：
|
||||
|
||||
```text
|
||||
/plugin install superpowers@claude-plugins-official
|
||||
/plugin marketplace add obra/superpowers-marketplace
|
||||
/plugin install superpowers@superpowers-marketplace
|
||||
```
|
||||
|
||||
来源：
|
||||
`https://github.com/obra/superpowers/blob/363923f74aa9cd7b470c0aaa73dee629a8bfdc90/README.md#L31`
|
||||
|
||||
Cursor：
|
||||
|
||||
```text
|
||||
/add-plugin superpowers
|
||||
```
|
||||
|
||||
来源：
|
||||
`https://github.com/obra/superpowers/blob/363923f74aa9cd7b470c0aaa73dee629a8bfdc90/README.md#L55`
|
||||
|
||||
Codex：
|
||||
|
||||
```text
|
||||
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md
|
||||
```
|
||||
|
||||
来源：
|
||||
`https://github.com/obra/superpowers/blob/363923f74aa9cd7b470c0aaa73dee629a8bfdc90/README.md#L65`
|
||||
|
||||
OpenCode：
|
||||
|
||||
```text
|
||||
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md
|
||||
```
|
||||
|
||||
来源：
|
||||
`https://github.com/obra/superpowers/blob/363923f74aa9cd7b470c0aaa73dee629a8bfdc90/README.md#L75`
|
||||
|
||||
如果你要按“手动 clone + symlink”方式装（含 Windows 权限坑），直接看：`opencode-superpowers.md`。
|
||||
|
||||
Gemini CLI：
|
||||
|
||||
```bash
|
||||
gemini extensions install https://github.com/obra/superpowers
|
||||
```
|
||||
|
||||
来源：
|
||||
`https://github.com/obra/superpowers/blob/363923f74aa9cd7b470c0aaa73dee629a8bfdc90/README.md#L85`
|
||||
|
||||
### 4.2 验证（1 个命令块，两行）
|
||||
|
||||
```text
|
||||
帮我做一个需求拆解，但先选择并加载一个合适的 superpowers skill 再继续。
|
||||
预期：它会先进入某个 skill 的流程（提澄清问题/给计划/要求验证），而不是直接开写。
|
||||
```
|
||||
|
||||
参考来源（上游 Verify Installation 段落）：
|
||||
`https://github.com/obra/superpowers/blob/363923f74aa9cd7b470c0aaa73dee629a8bfdc90/README.md#L97`
|
||||
|
||||
---
|
||||
|
||||
## 五、更新与排障（按平台）
|
||||
|
||||
### 5.1 更新（3 个命令块）
|
||||
|
||||
Claude Code：
|
||||
|
||||
```text
|
||||
/plugin update superpowers
|
||||
```
|
||||
|
||||
来源：
|
||||
`https://github.com/obra/superpowers/blob/363923f74aa9cd7b470c0aaa73dee629a8bfdc90/README.md#L165`
|
||||
|
||||
OpenCode：
|
||||
|
||||
```bash
|
||||
cd ~/.config/opencode/superpowers
|
||||
git pull
|
||||
```
|
||||
|
||||
来源（上游 OpenCode 文档 Updating 段落）：
|
||||
`https://github.com/obra/superpowers/blob/363923f74aa9cd7b470c0aaa73dee629a8bfdc90/docs/README.opencode.md#L193`
|
||||
|
||||
更新后要彻底退出并重启 OpenCode（把正在运行的 opencode 进程关掉，再重新启动）。
|
||||
|
||||
Gemini CLI：
|
||||
|
||||
```bash
|
||||
gemini extensions update superpowers
|
||||
```
|
||||
|
||||
来源：
|
||||
`https://github.com/obra/superpowers/blob/363923f74aa9cd7b470c0aaa73dee629a8bfdc90/README.md#L91`
|
||||
|
||||
Cursor：通常按 Cursor 的插件更新机制自动更新；不确定时可以按“安装命令”重装一次，然后按第 4 节的验证方式确认技能会触发。
|
||||
|
||||
Codex：通常重新执行一次上游 Codex 安装指令即可视为更新，然后按第 4 节的验证方式确认技能会触发。
|
||||
|
||||
### 5.2 OpenCode 常见排障入口
|
||||
|
||||
如果你是 OpenCode 用户，遇到下面这类问题：
|
||||
|
||||
- 插件似乎没加载
|
||||
- skills 找不到
|
||||
- Windows symlink/junction 权限报错
|
||||
|
||||
建议直接看我这篇的“验证与排障”段落：`opencode-superpowers.md`。
|
||||
225
src/ai/opencode-superpowers.md
Normal file
225
src/ai/opencode-superpowers.md
Normal file
@@ -0,0 +1,225 @@
|
||||
---
|
||||
title: OpenCode + Superpowers：技能插件安装与用法
|
||||
icon: mdi:power-plug
|
||||
date: 2026-03-16
|
||||
category:
|
||||
- AI
|
||||
- 开发工具
|
||||
tag:
|
||||
- OpenCode
|
||||
- Superpowers
|
||||
- 插件
|
||||
- Skills
|
||||
---
|
||||
|
||||
# OpenCode + Superpowers：技能插件安装与用法
|
||||
|
||||
Superpowers 是一套给 OpenCode 增强“技能（skills）体系”的插件与技能包：
|
||||
把常用的提示词/工作流封装成可复用技能，并在每次对话时自动注入必要的引导上下文。
|
||||
|
||||
<!-- more -->
|
||||
|
||||
---
|
||||
|
||||
## 一、它解决什么问题
|
||||
|
||||
在 OpenCode 里你当然可以直接对话、直接改代码；但当你需要把一套稳定的工作方式
|
||||
（例如：代码审查、需求拆解、写作规范、某语言最佳实践）复用到每个项目时，skills
|
||||
会更顺手。
|
||||
|
||||
Superpowers 主要提供：
|
||||
|
||||
- 一个 OpenCode 插件：启动时自动注入 superpowers 的引导上下文。
|
||||
- 一组技能：通过 OpenCode 的 `skill` 工具发现/加载。
|
||||
- 适配逻辑：把部分为其他代理写的技能说明，映射到 OpenCode 的工具体系。
|
||||
|
||||
---
|
||||
|
||||
## 二、快速安装（把话直接丢给 OpenCode）
|
||||
|
||||
如果你希望“让 OpenCode 帮你完成安装”，可以直接在对话里说：
|
||||
|
||||
```text
|
||||
Clone https://github.com/obra/superpowers to ~/.config/opencode/superpowers, then create directory ~/.config/opencode/plugins, then symlink ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js to ~/.config/opencode/plugins/superpowers.js, then symlink ~/.config/opencode/superpowers/skills to ~/.config/opencode/skills/superpowers, then restart opencode.
|
||||
```
|
||||
|
||||
你也可以按下面手动安装（更可控，适合第一次装）。
|
||||
|
||||
---
|
||||
|
||||
## 三、手动安装（macOS / Linux）
|
||||
|
||||
前置条件：
|
||||
|
||||
- 已安装 OpenCode
|
||||
- 已安装 Git
|
||||
|
||||
执行：
|
||||
|
||||
```bash
|
||||
# 1) 安装（或更新）
|
||||
if [ -d ~/.config/opencode/superpowers ]; then
|
||||
cd ~/.config/opencode/superpowers && git pull
|
||||
else
|
||||
git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
|
||||
fi
|
||||
|
||||
# 2) 创建目录
|
||||
mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills
|
||||
|
||||
# 3) 清理旧链接（重复安装时安全）
|
||||
rm -f ~/.config/opencode/plugins/superpowers.js
|
||||
rm -rf ~/.config/opencode/skills/superpowers
|
||||
|
||||
# 4) 建立链接
|
||||
ln -s ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js ~/.config/opencode/plugins/superpowers.js
|
||||
ln -s ~/.config/opencode/superpowers/skills ~/.config/opencode/skills/superpowers
|
||||
```
|
||||
|
||||
然后重启 OpenCode。
|
||||
|
||||
---
|
||||
|
||||
## 四、手动安装（Windows）
|
||||
|
||||
Windows 的重点在“符号链接权限”。你需要满足其一：
|
||||
|
||||
- 启用 Developer Mode（开发者模式），或
|
||||
- 用管理员权限运行终端。
|
||||
|
||||
建议优先用 PowerShell（命令更清晰）。
|
||||
|
||||
### 4.1 Command Prompt（管理员）
|
||||
|
||||
```bat
|
||||
:: 1) 安装
|
||||
git clone https://github.com/obra/superpowers.git "%USERPROFILE%\\.config\\opencode\\superpowers"
|
||||
|
||||
:: 2) 创建目录
|
||||
mkdir "%USERPROFILE%\\.config\\opencode\\plugins" 2>nul
|
||||
mkdir "%USERPROFILE%\\.config\\opencode\\skills" 2>nul
|
||||
|
||||
:: 3) 清理旧链接
|
||||
del "%USERPROFILE%\\.config\\opencode\\plugins\\superpowers.js" 2>nul
|
||||
rmdir "%USERPROFILE%\\.config\\opencode\\skills\\superpowers" 2>nul
|
||||
|
||||
:: 4) 插件 symlink（需要开发者模式或管理员）
|
||||
mklink "%USERPROFILE%\\.config\\opencode\\plugins\\superpowers.js" "%USERPROFILE%\\.config\\opencode\\superpowers\\.opencode\\plugins\\superpowers.js"
|
||||
|
||||
:: 5) skills 用 junction（通常更稳）
|
||||
mklink /J "%USERPROFILE%\\.config\\opencode\\skills\\superpowers" "%USERPROFILE%\\.config\\opencode\\superpowers\\skills"
|
||||
```
|
||||
|
||||
### 4.2 PowerShell（管理员或开发者模式）
|
||||
|
||||
```powershell
|
||||
# 1) 安装
|
||||
git clone https://github.com/obra/superpowers.git "$env:USERPROFILE\\.config\\opencode\\superpowers"
|
||||
|
||||
# 2) 创建目录
|
||||
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\\.config\\opencode\\plugins" | Out-Null
|
||||
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\\.config\\opencode\\skills" | Out-Null
|
||||
|
||||
# 3) 清理旧链接
|
||||
Remove-Item "$env:USERPROFILE\\.config\\opencode\\plugins\\superpowers.js" -Force -ErrorAction SilentlyContinue
|
||||
Remove-Item "$env:USERPROFILE\\.config\\opencode\\skills\\superpowers" -Force -ErrorAction SilentlyContinue
|
||||
|
||||
# 4) 插件 symlink
|
||||
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\\.config\\opencode\\plugins\\superpowers.js" -Target "$env:USERPROFILE\\.config\\opencode\\superpowers\\.opencode\\plugins\\superpowers.js" | Out-Null
|
||||
|
||||
# 5) skills junction
|
||||
New-Item -ItemType Junction -Path "$env:USERPROFILE\\.config\\opencode\\skills\\superpowers" -Target "$env:USERPROFILE\\.config\\opencode\\superpowers\\skills" | Out-Null
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、验证安装是否成功
|
||||
|
||||
macOS / Linux：
|
||||
|
||||
```bash
|
||||
ls -l ~/.config/opencode/plugins/superpowers.js
|
||||
ls -l ~/.config/opencode/skills/superpowers
|
||||
```
|
||||
|
||||
Windows（Command Prompt）：
|
||||
|
||||
```bat
|
||||
dir /AL "%USERPROFILE%\\.config\\opencode\\plugins"
|
||||
dir /AL "%USERPROFILE%\\.config\\opencode\\skills"
|
||||
```
|
||||
|
||||
看到 `<SYMLINK>` 或 `<JUNCTION>` 即表示链接生效。
|
||||
|
||||
---
|
||||
|
||||
## 六、开始使用：列出并加载技能
|
||||
|
||||
### 6.1 列出当前可用 skills
|
||||
|
||||
在 OpenCode 中让它调用原生 `skill` 工具：
|
||||
|
||||
```text
|
||||
use skill tool to list skills
|
||||
```
|
||||
|
||||
### 6.2 加载某个技能
|
||||
|
||||
```text
|
||||
use skill tool to load superpowers/brainstorming
|
||||
```
|
||||
|
||||
加载后，你可以直接让它按该 skill 的工作方式来执行任务（例如：先问澄清问题、再拆
|
||||
步骤、再写代码/写文档）。
|
||||
|
||||
---
|
||||
|
||||
## 七、skills 的来源与优先级（理解后更好排查）
|
||||
|
||||
OpenCode 会从这些位置发现 skills（优先级从高到低）：
|
||||
|
||||
1. 项目内：`.opencode/skills/`
|
||||
2. 个人目录：`~/.config/opencode/skills/`
|
||||
3. Superpowers：`~/.config/opencode/skills/superpowers/`（通常是 symlink 指向仓库里的 `skills/`）
|
||||
|
||||
你可以把团队约定写成“项目 skill”，把通用习惯写成“个人 skill”。
|
||||
|
||||
---
|
||||
|
||||
## 八、更新与常见问题
|
||||
|
||||
### 8.1 更新
|
||||
|
||||
```bash
|
||||
cd ~/.config/opencode/superpowers
|
||||
git pull
|
||||
```
|
||||
|
||||
更新后重启 OpenCode。
|
||||
|
||||
### 8.2 插件没生效
|
||||
|
||||
排查顺序建议：
|
||||
|
||||
1. 插件文件是否存在：`~/.config/opencode/superpowers/.opencode/plugins/superpowers.js`
|
||||
2. 链接是否正确：`~/.config/opencode/plugins/superpowers.js`
|
||||
3. 看日志（更直接）：
|
||||
|
||||
```bash
|
||||
opencode run "test" --print-logs --log-level DEBUG
|
||||
```
|
||||
|
||||
### 8.3 Windows 报 `Cannot find module`
|
||||
|
||||
常见原因是 Git Bash 下 `ln` 行为不符合预期（可能变成复制文件）。
|
||||
建议直接用 `mklink` + `/J`（junction），按本文 Windows 安装步骤重建链接。
|
||||
|
||||
---
|
||||
|
||||
## 九、结语
|
||||
|
||||
如果你已经把 OpenCode 用在日常开发里，Superpowers 的价值在于：
|
||||
把“可复用的工作流”变成技能，并且跨项目一致。
|
||||
|
||||
> 参考文档（原文）：
|
||||
> https://github.com/obra/superpowers/blob/main/docs/README.opencode.md
|
||||
Reference in New Issue
Block a user