git-learn/skill-workbench/docs/sm-flow/使用方式.md

SM-Flow 使用方式

本文档面向 sm-flow 的用户，说明如何启动、交互和使用 sm-flow。

快速开始

sm-flow 通过 4 个用户命令覆盖完整生命周期。你不需要了解内部阶段，只需表达意图。

命令	意图	典型场景
/sm-flow	完整流程	有粗略想法，从头规划到执行
/sm-flow explore	先聊聊	需求不清楚，带上下文探索
/sm-flow apply [change]	只执行	已有 Committed OpenSpec，直接实现
/sm-flow archive [change]	收尾	执行完了，回填 devflow + 归档

你也可以用自然语言指定阶段继续，例如：

ops-message-support 的 grill 已经做完了，继续
帮我检查一下 add-dark-mode 的 OpenSpec 对齐

sm-flow 会识别意图，自动补做最小前置检查，然后从指定阶段继续。

典型使用流程

场景 1：完整规划 → 执行 → 归档（分三次调用）

# 第一次：完整规划
/sm-flow 给站内消息加 OMC 支持
→ 走完 clarify → context → propose → grill → specify → audit → commit
→ 停在 apply 前，你说"先不执行了"

# 第二次：继续执行
/sm-flow apply ops-message-support
→ 进入 apply，执行完 tasks

# 第三次：归档
/sm-flow archive ops-message-support
→ 回填 devflow，询问是否归档 OpenSpec change

三个阶段，三次调用，每次只做一个用户意图的事。

场景 2：需求不清楚，先探索

/sm-flow explore 我们在考虑是否要重构消息队列
→ sm-flow 读取 devflow 上下文，和你讨论需求边界、风险、替代方案
→ 不生成 OpenSpec，只帮你理清思路
→ 如果讨论出明确方向，下次可以用 /sm-flow 启动完整流程

场景 3：小改动，快速模式

/sm-flow 修复按钮的拼写错误
→ sm-flow 识别为 micro 规模
→ 合并 gate：clarify+context 合并 checkpoint → propose+specify 合并 checkpoint → grill（最少 1 个问题）→ commit（简化检查）
→ 保留最关键的门控，但流程更轻量

场景 4：从中间继续

# 上次对话停在 grill 阶段
add-dark-mode 的 grill 已经做完了，继续
→ sm-flow 识别意图，自动补做 specify 的最小前置检查
→ 从 specify 阶段继续

交互模式

Human Checkpoint

sm-flow 在关键节点会暂停并询问你：

• propose 后：说明 proposal 范围、关键假设、主要风险，询问是否继续 grill
• grill 后：汇报已解决和未解决的问题、proposal 变更，询问是否继续 specify
• audit 后：说明架构风险、OpenSpec 修正点，询问是否进入 commit
• commit 后：说明 Committed OpenSpec 范围、接口影响、剩余风险，询问是否进入 apply
• archive 前：询问是否归档 OpenSpec change

你可以选择继续、暂停、或要求返回上一阶段。

Grill 阶段的一对一澄清

grill 阶段会建立一个 question pool，覆盖术语、边界、验收三个维度。问题分两类：

• evidence-driven：sm-flow 先查证代码、文档、OpenSpec 或 ADR，再向你汇报证据和结论
• user-interview：sm-flow 一次只问一个问题，等你确认后才继续

典型节奏：查证 1-2 个 evidence-driven → 汇报 → 问 1 个 user-interview → 等确认 → 继续。

自然语言交互

除了 4 个命令，你可以用自然语言与 sm-flow 交互：

# 指定 change name
继续 ops-message-support

# 指定阶段
add-dark-mode 的 specify 做完了吗？

# 指定动作
帮我检查一下 add-dark-mode 的 cross-artifact 对齐

# 混合表达
ops-message-support 的 grill 已经确认了术语和边界，继续 specify

sm-flow 会识别意图，自动编排后续阶段。

规模分档

sm-flow 根据变更规模自动分档，调整流程重量：

分档	适用场景	流程特点
micro	小改动、低风险、需求明确	gate 合并，grill 最少 1 个问题，commit 简化检查
standard	默认模式	完整 9 阶段流程
complex	高风险、跨模块、需求不清、多人协作	standard 基础上增加扩展产物（PRD/research/design/tasks/alignment）

你不需要显式指定分档，sm-flow 会在 clarify 阶段自动判断。如果判断不准，会作为 user-interview 问题等待你确认。

devflow：自动维护的项目长期记忆

sm-flow 会自动维护 devflow/ 目录作为项目长期记忆。你不需要手动管理它。

devflow/
├── projects/YYYY-MM-DD-{slug}/       ← 项目档案（brief/evidence/decisions/acceptance）
├── glossary/CONTEXT.md                ← 领域词汇表
├── compound/                          ← 跨项目知识沉淀
├── reference/                         ← 共享模板
└── index.md                           ← 项目索引

clarify → apply 期间：sm-flow 只维护 decisions.md 作为过程日志（grill 结论、关键决策、验证结果）。

archive 阶段：从 decisions.md + OpenSpec 产物提取完整档案（brief.md、evidence.md、decisions.md、acceptance.md）。

下次使用时：sm-flow 会自动读取 devflow 上下文，增强 OpenSpec 产物。术语、历史决策、验收记录不会丢失。

OpenSpec 集成

sm-flow 编排 OpenSpec 的生命周期，但不强制依赖 OpenSpec CLI：

• 优先使用 OpenSpec CLI：如果 openspec-propose、openspec-apply-change、openspec-archive-change 可用，sm-flow 会调用它们
• 内置执行协议：如果 OpenSpec CLI 不可用，sm-flow 使用内置协议接管（标注为降级执行）

Draft / Committed 分离：

• Draft OpenSpec：propose 阶段产出，是讨论对象，不是执行许可
• Committed OpenSpec：通过 commit gate 后，成为 apply 的执行依据
• apply 只执行 Committed OpenSpec：防止未经澄清的方案直接进入实现

常见问题

Q: 我需要在启动前准备什么？

不需要。sm-flow 会从你的粗略想法、issue、PRD 或已有 research 开始。如果信息不足，clarify 阶段会追问。

Q: 我可以跳过某个阶段吗？

不可以。sm-flow 的门控是硬约束（grill 至少 3 个问题、commit gate 必须通过）。但 micro 模式会合并 gate，减少流程开销。

Q: 如果 OpenSpec 不可用怎么办？

sm-flow 会使用内置执行协议接管，标注为降级执行。产物仍然写入 openspec/changes/{slug}/，只是不通过 OpenSpec CLI。

Q: devflow 和 OpenSpec 冲突怎么办？

sm-flow 会先汇报冲突，等你确认，然后修正 OpenSpec，再继续执行。devflow 是上下文，OpenSpec 是执行真理源。

Q: 我可以修改已经 commit 的 OpenSpec 吗？

可以。如果 apply 阶段发现规格遗漏、设计冲突或用户变更，sm-flow 会暂停 apply，修正 OpenSpec 后重新提交。

Q: archive 阶段会自动归档 OpenSpec 吗？

不会。archive 阶段会回填 devflow，然后询问你是否归档 OpenSpec change。在你说"是"之前，不会执行归档。

参考文档

• 设计理念：workflow.md — 当前设计理念（v4 方向）和演进历史
• 设计评审：design-review.md — 核心定位、状态评估、已确认修改方向
• 回溯分析：retrospective.md — 历史执行失败分析
• 使用问题：使用问题.md — 真实痛点收集