STDD 生命周期 —— Skill 程序与项目文档的双轨划分
STDD 涉及两条独立演进的生命周期轨道：① Skill 程序（AI 框架加载的执行引擎）和 ② 项目文档（具体项目的 STDD 实例状态）。理解这两者的关系是理解 STDD 跨框架切换、版本管理、多项目协同的关键。
第一轨：STDD Skill 生命周期（程序本体）
Skill 是 STDD 的执行引擎 —— 从仓库克隆到 AI 框架的那份程序代码。它的生命周期独立于任何项目。
1.1 安装阶段
- 从
github.com/leonai42/stdd克隆仓库 - 安装依赖（pyyaml / pytest 等）
- 注册到 AI 框架的 skill 系统（Hermes: 创建 SKILL.md；OpenCode: 拷贝到项目目录）
- 验证可用（
stdd --version）
安装位置决定了 Skill 的生命周期范围：
| 框架 | 安装位置 | 生命周期范围 |
|---|---|---|
| Hermes | 全局 skill 目录（框架主目录下） | 一次安装，所有项目共用 |
| OpenCode | 项目目录内 | 每个项目独立安装和持有 |
| Claw | 项目目录内 | 每个项目独立安装和持有 |
1.2 版本演进
- STDD 自身版本号（当前 V2.3），记录在 CHANGELOG.md
- 版本迭代周期由上游仓库决定
- Skill 程序版本与框架版本无关 —— 用户可自行决定何时更新 Skill
- 无标准 Release 机制，版本检测依赖 CHANGELOG 头部解析
1.3 跨框架部署差异
- Hermes 模式：全局一份 Skill 程序，
stdd init在项目目录创建实例。Skill 与实例是调用关系，升级 Skill 所有项目即时受益 - OpenCode / Claw 模式：Skill 程序整体拷贝到项目目录。每项目一份独立副本，升级需逐一处理。版本漂移不可控
1.4 升级策略
- 原则：禁止自动升级。升级是赋权行为（授权），用户可能不想升级
- 推荐做法：AI 检测到版本差异时告知用户，由用户决定是否升级。AI 可提议但不可擅自执行
- 版本感知交互：用户说"用 STDD V2.5 的流程做 xxx" → AI 查 Skill 版本 → 若不符则提议升级 → 用户授权后执行 → 继续任务
- 向下兼容：新版本 Skill 应能读取旧版本项目文档
第二轨：项目内 STDD 文档生命周期（实例状态）
项目文档是 STDD 在具体项目中的实例化 —— 通过 stdd init 创建，承载开发过程中所有阶段产物和状态信息。
2.1 初始化 —— init
- 在项目根目录执行
stdd init，产生.stdd/目录（配置 + 技能引用）和changes/目录（变更实例容器） - init 本质是"安装赋权" —— 给项目挂载 STDD 实例
- 项目初始化后，后续使用不再需要 init
- 理想体验：用户说"用 STDD 开发 xxx"，AI 自动检测是否已 init，若无则自动完成
2.2 变更生命周期 —— new → 执行 → deliver
- 启动变更：
stdd new <change-name>→ 创建变更目录changes/<change-name>/ - 六阶段执行：
P1 UNDERSTAND → proposal.md → Gate 1 确认
P2 SPEC → design.md + specs/*.md + test-plan.md → Gate 2 确认
P3 SLICE → tasks.md + slices.md
P4 BUILD → TDD 实现代码
P5 VERIFY → test-report.md + 11 类失败模式检查 → Gate 3 确认
P6 DELIVER → archive + merge specs + git tag- 归档：
stdd archive <change-name>结束变更生命周期 - 中止：
stdd abort <change-name>放弃变更 - 回滚：
stdd rollback <change-name>从 archive 恢复
2.3 状态文档体系
项目目录下的 STDD 实例文件结构：
项目根目录/
.stdd/ # init 产生的配置目录
config.yaml # 项目级 STDD 配置
skills/ # 各阶段 skill 引用
templates/ # 文档模板
standards/ # 语言规范
changes/
<change-name>/
.stdd-state.yaml # 当前阶段、Gate 状态、版本快照 ★
proposal.md # P1 产物
design.md # P2 产物
specs/ # P2 产物（行为规格）
*.md
test-plan.md # P2 产物（测试方案）
tasks.md # P3 产物
slices.md # P3 产物
test-report.md # P5 产物
design-adjustments.md # P4-P5 产物核心设计：.stdd-state.yaml 是状态的枢纽 —— 记录当前阶段、Gate 状态、STDD 版本号。它的存在使得跨框架切换、跨 session 续电成为可能。
2.4 跨框架切换 —— 文档作为状态载体
项目文档生命周期的核心价值：同一个项目的 STDD 实例可以在不同 AI 框架间无缝迁移。
AI 框架变换 项目文档（不变）
Hermes ————→ .stdd/ + changes/ ————→ OpenCode
│ │
│ 加载 Skill V2.3 │ 加载 Skill V2.5
│ 读取 .stdd-state.yaml │ 读取 .stdd-state.yaml
│ 发现：P2 完成，Gate 2 已确认 │ 发现：P2 完成，Gate 2 已确认
│ 进入 P3 SLICE │ 进入 P3 SLICE
└──────── 同一状态，不同引擎 ──────────────┘切换条件：
- 项目文档格式与版本号兼容（向下兼容假设成立）
- 新框架安装了 STDD Skill（版本可以不同）
- 新 AI 能读取
.stdd-state.yaml恢复上下文
三、双轨关系
3.1 调用关系而非安装关系
理想架构下，Skill 程序与项目文档是调用关系：
Skill 程序（AI 框架的全局资产） 项目文档（项目根的独立资产）
┌────────────┐ ┌──────────────┐
│ Hermes │ ──调用──→ │ .stdd/ │
│ 加载 │ │ changes/ │
│ 执行 │ ←──产物── │ propsal.md │
│ 无状态 │ │ design.md │
└────────────┘ │ specs/ │
↓ 切换框架 │ state.yaml │
┌────────────┐ └──────────────┘
│ OpenCode │ ──调用──→ ↑ ↑
│ 加载 │ │ 文档承载状态 │
│ 执行 │ │ 不绑定框架 │
└────────────┘ └───────────────┘3.2 一对多关系
- 一个 Skill 程序 → 多个项目实例：全局更新一次 Skill，所有项目即时受益（Hermes 模式）
- 多个 Skill 版本 → 同一项目文档：项目文档格式稳定后，新旧版本 Skill 应能处理同一份文档
3.3 独立演进
- Skill 版本升级不应要求重新 init 项目实例
- 项目文档格式演进应保持向后兼容
- Skill 生命周期受上游仓库管控，项目文档生命周期受开发者管控 —— 两者互不锁死
四、总结
| 维度 | Skill 程序 | 项目文档 |
|---|---|---|
| 本质 | 执行引擎 | 实例状态 |
| 安装方式 | 克隆 + 注册到 AI 框架 | stdd init |
| 版本管理 | STDD 版本号（全局） | state.yaml 记录的 Skill 版本快照 |
| 升级影响 | 全局升级后所有项目可用 | 不需升级，保持向下兼容 |
| 生命周期结束 | 从 AI 框架卸载 Skill | archive 或删除 .stdd/ |
| 跨框架迁移 | 需在新框架重新安装 | 文档直接携带，无需变更 |
一句话总结：Skill 程序是引擎，项目文档是状态。引擎可以有多个版本、部署在多个框架；状态绑在项目里，跟着项目走。两者解耦，STDD 才能真正实现"一次编程，到处运行"。