SDD + OpenSpec Scaffold

基于 SDD (Specification-Driven Development) 和 OpenSpec 的 AI 研发治理脚手架，当前版本 v2.0.17。

它不是业务应用框架，也不是单纯的提示词模板，而是一套把“需求澄清、方案设计、代码实现、验证、审查、归档”串成可执行流程的治理控制面。

一句话理解：

先用 SDD 定边界，再用 OpenSpec 管变更，最后用证据决定能否交付。

这套框架解决什么问题

很多团队在接入 AI 开发后，容易出现几类问题：

• 需求是自然语言，边界不稳定，AI 每次理解都不一样
• 代码改了，但为什么这么改、改了什么、有没有测试，很难追溯
• review 和 verify 混在一起，最后“看起来完成”但不能安全交付
• Prompt、skills、rules、memory、模型路由慢慢堆起来，越来越难治理
• 文档、脚本、运行态分散，团队成员和 Agent 都要重复理解上下文

这个脚手架的目标，就是把这些问题变成一套有权威源、有阶段、有门禁、有证据、有归档的工程流程。

当前框架的特点

1. 研发治理优先，不把 AI 当黑盒

框架把研发流程拆成固定生命周期：

explore -> propose -> apply -> verify -> review -> archive

每个阶段都有角色、输入、输出和门禁，不允许跳过 verify 直接 review，也不允许跳过 review 直接 archive。

2. 有明确的权威边界

这套系统不是“所有文件都重要”，而是有清晰权威源：

• spec/sdd/：长期稳定基线
• openspec/changes/：当前增量变更
• openspec/orchestrator.md：运行时状态权威
• openspec/harness.yaml：生命周期、gate、rollback 权威
• scripts/scheduler/model-router.yaml：模型执行路由权威

这让人和 Agent 都知道“遇到冲突时该信谁”。

3. 不是只有流程，还有证据

交付不等于“任务勾完了”。

框架把可交付定义成：

交付 = SDD 长期基线 + OpenSpec 当期增量 + 可验证证据

这意味着：

• verification-report.md 要有测试、lint、TDD、行为覆盖和遗留风险
• review-report.md 要独立存在
• archive readiness 必须检查证据和生命周期一致性

4. SuperPower 证据模型

SuperPower 是这个框架里的验证证据模型，用来回答一个很实际的问题：这次变更凭什么可以交付？

它不是一句“测试通过”，而是一组必须能被审查的证据：

• 测试证据：真实执行过的测试命令和结果
• Lint 证据：真实执行过的 lint 命令和结果
• TDD 合规：说明测试如何先于或覆盖实现
• 行为覆盖：说明关键业务行为是否被验证
• 文件映射：说明变更文件对应哪些测试或验证证据
• 遗留风险：说明还剩什么风险，以及为什么可以接受

verify 阶段会把这些内容沉淀到 verification-report.md。后续 review、trace、archive readiness 都会读取这些证据，避免把“模型说完成了”误当成“工程上可以交付”。

5. 兼容 AI，但不依赖单一模型或单一客户端

框架支持：

• 多 Agent 角色分工
• 多模型 Provider 路由
• Claude / Codex / Trae 三端同源命令
• Business Pack 按业务域绑定 skills 和规则

你可以把它理解成“AI 开发的控制面”，而不是某个模型专属工作流。

6. 运行时、调度、工具层已经拆开

从 2.0.16 开始，结构进一步清晰：

• scripts/scheduler/：阶段调度、上下文组装、模型路由
• scripts/runtime/：durable execution，保存 run / step / attempt / wait / resume
• scripts/tools/：tool / MCP integration layer

这比把所有能力都塞进一个 scheduler 更适合长期演进。

7. 支持“有审查的自我进化”

框架已经有：

• repo-learning-advisor
• memory-indexer
• context-intelligence-advisor
• loop-feedback
• governance-workbench

它适合做“自动发现候选 -> 人工确认 -> 沉淀为 skill / rule / memory”，而不是无约束地自动改规则。

8. 上下文经济是内建能力

不是把所有文档都塞给模型，而是按阶段、按业务域、按触发规则加载。

现在已经支持：

• context profile：lean / normal / deep
• reviewed summary cache
• context memory
• diff-aware 建议
• runtime truncation 审计

这让上下文“可控地大”，而不是“失控地大”。

适合什么团队

比较适合：

• 用 AI 辅助研发，但又不想牺牲工程治理的团队
• 有多角色协作需求的团队
• 需要长期沉淀业务规则、设计决策和变更证据的团队
• 想把“脚手架 + 文档 + 命令 + Agent 工作流”统一起来的团队

不太适合：

• 只想要一个超轻量 prompt 模板
• 没有变更治理需求、只做一次性原型的场景

快速开始

作为 NPM 脚手架接入

推荐使用显式初始化命令，不通过 postinstall 偷偷写项目。

# 先预览，不落盘
npx epochal-ai init --target ./my-service --dry-run --yes

# 初始化到业务项目
npx epochal-ai init --target ./my-service --yes

# 健康检查
npx epochal-ai doctor --target ./my-service

# 如初始化到了错误目录，可清理
npx epochal-ai remove --target ./my-service --dry-run --yes
npx epochal-ai remove --target ./my-service --yes

# 后续升级脚手架
npx epochal-ai upgrade --target ./my-service --dry-run --yes
npx epochal-ai upgrade --target ./my-service --yes
npx epochal-ai doctor --target ./my-service

如果在 CI 或非交互环境跳过了向导，可进入项目后手动补跑：

cd ./my-service
bash scripts/opsx.sh init

从源码或 tarball 使用

bash scripts/opsx.sh init
bash scripts/opsx.sh status

使用方法

1. 最推荐的用法：一句话需求开始

/opsx:orchestrate 我要做 xxx

系统会先做需求澄清，再自动串联完整生命周期。

适合：

• 新需求
• 跨模块变更
• 你希望框架帮你把 explore/propose/apply/verify/review 都带起来

2. 手动分阶段推进

如果你希望自己掌控节奏：

/opsx:explore <需求>
/opsx:propose <change-id>
/opsx:apply <change-id>
/opsx:review <change-id>
/opsx:archive <change-id>

适合：

• 需求还不清晰
• 已有变更单，需要从中途继续
• 想显式控制每个阶段

3. 首次业务域接入

bash scripts/opsx.sh business-pack init order \
  --name "Order Domain" \
  --owner "Order Team" \
  --keywords "order,订单" \
  --capability "order-list:Order List:order"

这会帮助你把业务域基线、规则和 skills 接进来。

4. 日常治理命令

常见入口：

bash scripts/opsx.sh status
bash scripts/opsx.sh doctor workspace
bash scripts/opsx.sh workbench status
bash scripts/opsx.sh trace <change-id>
bash scripts/opsx.sh feedback <change-id>
bash scripts/opsx.sh quality check <change-id>
bash scripts/opsx.sh evidence verify <change-id> --write-draft
bash scripts/opsx.sh context advise
bash scripts/opsx.sh learn analyze

这些命令分别解决：

• 当前运行态和变更状态
• 工作区阻塞项
• 优先级队列和下一步建议
• 单个 change 的证据/阶段/索引链路
• 失败后该回到哪个阶段
• 测试质量、文件映射和高风险证据检查
• 生成 verification 证据草稿，草稿不会自动通过
• 上下文是否过大、该怎么瘦身
• 是否有可沉淀的规则、skill、memory 候选

5. 维护者发布前检查

npm test
npm run lint
npm_config_cache=/tmp/epochal-ai-npm-cache npm pack --dry-run
node scripts/release-smoke.mjs package-contents --root .

如果本机 npm cache 有权限问题，可以像上面这样使用临时 cache。

文档入口

• 普通用户入口：docs/USER_GUIDE.md
• 维护者入口：docs/MAINTAINER_GUIDE.md
• 架构师入口：docs/ARCHITECTURE.md
• 系统设计：docs/SYSTEM_DESIGN.md
• 详细使用说明：docs/USAGE.md

目录结构

• spec/sdd/：长期稳定 SDD 基线
• spec/sdd/modules/：业务域基线和 Business Pack
• openspec/changes/：当前增量变更
• openspec/specs/：归档同步后的稳定 capability specs
• scripts/scheduler/：上下文构建、阶段调度、模型路由
• scripts/runtime/：durable execution 运行时
• scripts/tools/：tool / MCP integration layer
• .agents/：多端同源命令和 skills

版本更新

v2.0.17

• README 补充 SuperPower 证据模型说明，明确测试、lint、TDD、行为覆盖、文件映射和遗留风险的交付口径
• 日常治理命令补充 quality check 和 evidence verify --write-draft

v2.0.16

• 拆分 runtime 和 tools 层，形成 scheduler / runtime / tools 三层结构
• 引入 durable execution 抽象：run / step / attempt / wait / resume
• 新增 tool / MCP integration layer，保留旧 artifact-writer 兼容 facade
• 为大文档和关键 specs 补充 reviewed summary cache
• 优化 verify 阶段上下文，不再整份注入 harness.yaml

v2.0.15

• 强化 governance guards 和发布前治理约束
• 完成变更链路、上下文经济、repo learning、loop feedback、rollback、workbench 等治理能力的集中增强
• 完善 archive readiness、模型路由运行时修复、低摩擦持续治理相关能力

这部分主要来自 2026-06 的治理增强与修复：

• change trace
• context economy baseline
• repo learning loop
• rollback checkpoints / rollback policy hardening
• governance workbench + learning promotion
• loop feedback
• archive diagnostics / archive transaction fixes
• model routing runtime fix

v2.0.12

• 形成较完整的 v2 治理脚手架发布基础
• 包括显式 init / adopt / upgrade / remove / doctor 的 NPM 接入链路
• 打下多模型、多 Agent、OpenSpec 生命周期编排的基础

故障排查

• conflict：目标项目已有同名文件且内容不同。新项目可确认后 init --force；老系统优先 adopt。
• skip-changed：remove 发现项目文件已被改动，默认保留；确认是误初始化再 remove --force。
• blocked-locked：升级时发现业务系统私改了 LOCKED 文件；先确认是否回退本地私改，再考虑 upgrade --force。
• provider-keys warning：模型 key 缺失不会阻断初始化，但会阻断真实模型调用。
• runtime-state fail：新项目应保持空 openspec/active.json 和 idle orchestrator；已有 active change 时先完成或归档。
• npm pack cache 报错：为 npm 命令设置临时 cache，例如 npm_config_cache=/tmp/npm-cache npm pack --dry-run。

许可

MIT