Skip to content

HOW-IT-WORKS.md

Latest commit

 

History

History
171 lines (142 loc) · 8.49 KB

HOW-IT-WORKS.md

File metadata and controls

171 lines (142 loc) · 8.49 KB

HOW IT WORKS

本项目是如何工作的——一条命令从输入到执行完毕的完整链路。

一句话

用户在 OpenCode 中输入 /opsx-ff add-user-auth，OpenCode 路由到 .opencode/commands/opsx-ff.md，该命令指示 AI 调用 openspec CLI、Superpowers skills（通过 Read）、Git 等工具，在隔离的 worktree 中完成变更的创建、实现和收尾。

执行链条

用户输入 /opsx-ff add-user-auth
        │
        ▼
┌─ OpenCode 平台 ──────────────────────────────────────────────┐
│  检测到 /opsx-ff 是 slash command                             │
│  读取 .opencode/commands/opsx-ff.md（命令入口）               │
│  把命令内容交给 AI 执行                                        │
└──────────────────────────────────────────────────────────────┘
        │
        ▼ AI（Sisyphus）按命令指示执行：
        │
  ①  git worktree add .worktrees/add-user-auth ...
  ②  cd .worktrees/add-user-auth
  ③  openspec new change "add-user-auth"
        │
        ▼
┌─ OpenSpec CLI ──────────────────────────────────────────────┐
│  读 openspec/config.yaml → schema: superpowers-bridge-opencode │
│  加载 openspec/schemas/.../schema.yaml（artifact 定义）       │
│  执行 new change 命令 → 创建变更目录                          │
└──────────────────────────────────────────────────────────────┘
        │
  ④  循环生成全部 artifacts（按依赖顺序）：
        │
        ▼
┌─ openspec instructions brainstorm --change "add-user-auth"   ┐
│  schema.yaml 的 brainstorm 段定义：                           │
│    - template: brainstorm.md（模板文件路径）                  │
│    - instruction: 载入 brainstorming skill 等                 │
│    - requires: []（无依赖，最先创建）                          │
│                                                              │
│  openspec 返回 JSON：{ template, instruction, outputPath }    │
└──────────────────────────────────────────────────────────────┘
        │
  ⑤  AI 读 template 文件，按 instruction 读 Superpowers skill，
     按 skill 内容生成 artifact 内容，写入 outputPath。
        │
  ⑥  重复 ④→⑤ 按依赖链生成全部 artifacts：
      brainstorm → proposal → specs → tasks → plan
        │
  ⑦  git add + git commit，cd 回项目根目录
     提示运行 /opsx-apply

各文件的角色

文件 谁读它 作用
.opencode/commands/opsx-*.md AI（Sisyphus） 告诉我每个 /opsx-* 命令要做什么、分几步
.opencode/skills/openspec-*-change/SKILL.md AI（通过 skill() 加载） 同上，另一种加载方式，独立于平台
AGENTS.md AI（会话启动时读） 项目级行为规则：worktree 优先、TDD 强制、子 Agent 调度映射
openspec/config.yaml openspec CLI 选择使用哪个 schema
openspec/schemas/.../schema.yaml openspec CLI + AI 定义 artifact 类型、依赖顺序、模板路径、生成指令。AI 也读 instruction 里的约束
openspec/schemas/.../templates/*.md AI 每个 artifact 的输出结构模板，AI 按模板填空
opencode.json OpenCode 平台 权限控制：AI 能读/写哪些路径、执行哪些命令

层级关系

OpenCode 平台
  识别 /opsx-* 命令，路由到命令文件
  └─ .opencode/commands/opsx-*.md
      告诉 AI 执行步骤
      ├─ openspec CLI
      │   读 config → 加载 schema → 管理 artifact 生命周期
      │   ├─ schema.yaml
      │   │   定义 artifact 链、模板路径、依赖顺序
      │   │   └─ templates/*.md
      │   │       每个 artifact 的填空结构
      │   └─ 其他：new change / status / instructions / archive
      │
      ├─ Superpowers skills（通过 Read 加载）
      │   brainstorming、writing-plans、subagent-driven-development 等方法论
      │   └─ schema.yaml 的 instruction 里指定要 Read 哪些 skill 文件
      │
      ├─ Git / worktree
      │   创建隔离分支 + 目录，所有操作在 worktree 内完成
      │
      └─ task() 子 Agent（apply 阶段）
          分解 plan.md 的微任务，并行派 deep agent 实现

命令完整生命周期

   /opsx-ff              /opsx-apply              /opsx-finish
     │                       │                       │
     ▼                       ▼                       ▼
  ┌─────────┐     ┌─────────────────────┐     ┌──────────────────┐
  │ 创建    │ ──→ │ 实现                │ ──→ │ 收尾             │
  │ worktree│     │ 并行子 Agent TDD    │     │ 测试验证         │
  │ +       │     │ + 审查              │     │ retrospective    │
  │ artifacts│     │ + openspec status   │     │ archive          │
  │         │     │ + 提交              │     │ 合并 / PR        │
  └─────────┘     └─────────────────────┘     └──────────────────┘
       │                                            │
       │ 所有操作在 feature 分支                       │ 清理 worktree
       │ main 不受影响                                 │ 删除 feature 分支

创建阶段（FF）

步骤 谁执行 产出
git worktree add AI 调 Git .worktrees/<name>/ 目录 + feature/<name> 分支
openspec new change AI 调 openspec CLI 变更目录 scaffold
openspec instructions <id> AI 调 openspec CLI 获取 artifact 模板 + 指令
Read Superpowers skill AI 读文件 方法论指导（如 brainstorming 的设计探索流程）
写 artifact 文件 AI brainstorm.md、proposal.md、specs.md、tasks.md、plan.md

实现阶段（Apply）

步骤 谁执行 产出
cd .worktrees/<name> AI 进入隔离工作区
Read implementer-prompt.md AI 构造子 Agent prompt
Read TDD SKILL.md AI 提取 RED-GREEN-REFACTOR 流程作为 prompt 前置指令
task(category="deep", ...) AI 调度 并行子 Agent 实现代码
spec + code quality 审查 AI 调 oracle 子 Agent 检查实现 vs 规格一致性
openspec status AI 调 openspec CLI 确认 artifacts 完成
git commit AI 提交变更（仍在 worktree 内）

收尾阶段（Finish）

步骤 谁执行 产出
测试套件 AI 调测试工具 验证 worktree 自身完好
Read finishing-a-development-branch skill AI 合并策略方法
openspec archive AI 调 openspec CLI 归档变更目录
git rebase + merge + worktree remove AI 合并到 main，清理 worktree

Schema 的设计作用

schema.yaml 是整个流程的核心契约文件。它定义了：

  1. artifact 类型— brainstorm、proposal、specs、tasks、plan、verify、retrospective
  2. 依赖顺序— requires: [brainstorm] 等字段，确保按序生成
  3. 模板路径— 每个 artifact 对应的 template 文件
  4. 生成指令— instruction 字段告诉 AI 如何生成该 artifact（读哪些 skill、按什么流程）
  5. apply 阶段指令— apply.instruction 定义实现阶段的全流程
  6. 验收标准— 最终产出是否符合 schema 定义

openspec config.yaml 则是指定项目用哪个 schema 的开关。

与 README 的关系

  • README.md — 项目的「正门」：怎么安装、怎么使用、有什么功能、到哪找详细文档
  • HOW-IT-WORKS.md — 项目的「引擎盖」：各组件如何协作、命令执行链路、谁读什么文件