specops 0.2.4 → 0.3.0

package/.opencode/skills/demand-analysis/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: demand-analysis
-description: "需求分析编排 Skill — 完整的 Phase 0 流程：Brainstorm → 输入识别 → 功能拆分 → 竞品搜索 → 功能搜索 → Clone 分析 → 技术选型 → PRD 合成。编排 brainstorming、competitor-search、feature-search、repo-clone-analyze、tech-selection 五个子 skill，生成 REQUIREMENTS.md + TECH-CONTEXT.md，对接 GSD new-project。触发词：'需求分析'、'分析需求'、'analyze demand'、'拆分功能'。"
+description: "需求分析编排 Skill — 完整的 Phase 0 流程：Brainstorm → 输入识别 → 功能拆分 → 竞品搜索 → 功能搜索 → Clone 分析 → 技术选型 → 难点分析 → PRD 合成。编排 brainstorming、competitor-search、feature-search、repo-clone-analyze、tech-selection 五个子 skill，生成 REQUIREMENTS.md + TECH-CONTEXT.md，对接 GSD new-project。触发词：'需求分析'、'分析需求'、'analyze demand'、'拆分功能'、'难点分析'。"
 ---
 
 # 需求分析 Skill（编排层）
 
 <role>
-你是需求分析编排专家。你接收用户输入，按 8 个 PHASE 顺序执行完整分析链路：
+你是需求分析编排专家。你接收用户输入，按 9 个 PHASE 顺序执行完整分析链路：
 
 **你不亲自执行搜索、分析和选型 — 你调用专门的子 skill 来完成。**
 
@@ -18,7 +18,8 @@ description: "需求分析编排 Skill — 完整的 Phase 0 流程：Brainstorm
 4. 调用 `feature-search` skill 搜索开源实现
 5. 调用 `repo-clone-analyze` skill Clone 并分析参考项目
 6. 调用 `tech-selection` skill 进行技术选型
-7. 合成所有产出，生成 REQUIREMENTS.md + TECH-CONTEXT.md
+7. 难点分析：验证和发现项目技术/功能/集成难点
+8. 合成所有产出，生成 REQUIREMENTS.md + TECH-CONTEXT.md
 </role>
 
 ---
@@ -29,7 +30,7 @@ description: "需求分析编排 Skill — 完整的 Phase 0 流程：Brainstorm
 |------|------|
 | **Brainstorm 门禁** | PHASE 0 设计批准前，**禁止**进入任何后续 PHASE |
 | **子 skill 调用** | 搜索/分析/选型必须通过 `skill()` 调用，不得自行执行 |
-| **顺序执行** | PHASE 必须按 0→1→2→3→4→5→6→7 顺序执行，不得跳过 |
+| **顺序执行** | PHASE 必须按 0→1→2→3→4→5→6→7→8 顺序执行，不得跳过 |
 | **状态更新** | 每个 PHASE 转换时必须调用 specops CLI 更新状态 |
 | **全中文输出** | 所有文档、报告、状态描述均使用中文 |
 
@@ -286,9 +287,119 @@ npx specops update-operation --agent-id <id> --operation "正在进行技术选
 
 ---
 
-## PHASE 7: 合成 PRD
+## PHASE 7: 难点分析
 
-将 PHASE 0-6 的所有产出合成为两个文档：
+<difficulty_analysis>
+
+### 难点来源
+
+难点有两个来源，都要覆盖：
+
+**来源 1: 用户主动提出的难点**
+
+在 PHASE 0 Brainstorm 或任何交互中，用户可能提到「这个项目的难点是...」「我担心...会很难」。记录下来，在此阶段统一处理。
+
+**来源 2: 主动分析潜在难点**
+
+从前面所有 PHASE 的产出中提取潜在难点：
+
+| 分析维度 | 数据来源 | 难点信号 |
+|---------|---------|---------|
+| **技术难点** | PHASE 6 技术选型 | 选型中标注的风险项、技术兼容性问题、性能瓶颈 |
+| **功能难点** | PHASE 4 功能搜索 | 「未找到开源实现」的 SC 功能点 — 需完全自研 |
+| **集成难点** | PHASE 5 Clone 分析 | 参考项目间架构模式冲突、数据格式不兼容 |
+| **规模难点** | PHASE 2 功能拆分 | 复杂度标注为「高」的 SC 功能点 |
+| **未知难点** | PHASE 3 竞品分析 | 竞品普遍未解决的功能缺口（说明行业级难题） |
+
+### 每个难点的处理链
+
+对每个识别出的难点，按以下流程处理：
+
+```
+难点描述
+  │
+  ▼
+Step 1: 搜索验证（确认是否真的是难点）
+  │  使用 web search / librarian 搜索：
+  │  - "[难点关键词] solution"
+  │  - "[难点关键词] best practice"
+  │  - "[难点关键词] how to solve"
+  │  判断：这是真实存在的技术难题，还是有成熟解决方案？
+  │
+  ├─ 有成熟解决方案 ──→ Step 2a
+  └─ 无成熟解决方案 ──→ Step 2b
+
+Step 2a: 记录解决方案
+  - 方案名称 + 链接/来源
+  - 实现复杂度估算
+  - 是否需要额外依赖
+  → 输出到 REQUIREMENTS.md「已解决难点」表
+
+Step 2b: 加入项目难点清单
+  - 难点描述
+  - 风险等级：🔴 高 / 🟡 中 / 🟢 低
+  - 影响范围：哪些 SC 功能点受影响
+  - 已尝试的搜索关键词（证明确实搜索过）
+  - 建议的探索方向（不是解决方案，是可能的研究方向）
+  → 输出到 REQUIREMENTS.md「未解决难点」表
+```
+
+### 搜索策略
+
+对每个难点，至少执行以下搜索：
+
+1. **中文搜索**：`[难点关键词] 解决方案` / `[难点关键词] 最佳实践`
+2. **英文搜索**：`[difficulty keyword] solution` / `[difficulty keyword] best practice`
+3. **GitHub 搜索**：搜索相关 issue 和 discussion，看是否有人遇到并解决了同样问题
+4. **Stack Overflow**：搜索相关问答
+
+如果搜索结果模糊或不确定，**向用户确认**：
+```
+我发现 [难点描述] 有以下可能的解决方案：
+1. [方案 A] — [简要描述]
+2. [方案 B] — [简要描述]
+
+但这些方案可能不完全适用于我们的场景，因为 [原因]。
+你觉得哪个方向值得深入研究？还是标记为项目难点？
+```
+
+### 输出格式
+
+#### 已解决难点表
+
+| 难点 | 来源 | 解决方案 | 方案来源 | 实现复杂度 | 受影响 SC |
+|------|------|---------|---------|-----------|----------|
+| [描述] | 用户提出 / PHASE X | [方案名] | [链接] | 低/中/高 | SC-001, SC-003 |
+
+#### 未解决难点表（项目难点清单）
+
+| 难点 | 风险等级 | 来源 | 影响范围 | 搜索记录 | 探索方向 |
+|------|---------|------|---------|---------|---------|
+| [描述] | 🔴 高 | 用户提出 / PHASE X | SC-001, SC-003 | "keyword1 solution"→无结果, "keyword2 best practice"→不适用 | 可能需要 [研究方向] |
+
+### 反模式
+
+| 违规行为 | 严重性 |
+|---------|--------|
+| 用户提出的难点不搜索直接记录 | **严重** — 必须先搜索验证 |
+| 只搜索一次就下结论 | 高 — 至少中英文各搜一次 |
+| 不标注风险等级 | 中 |
+| 不记录搜索关键词 | 中 — 必须证明已搜索 |
+| 发现解决方案后不评估适用性 | 中 |
+
+**状态更新：**
+```bash
+npx specops advance --agent-id <id>
+npx specops update-operation --agent-id <id> --operation "正在分析项目难点..." --skill "demand-analysis"
+```
+
+</difficulty_analysis>
+
+---
+
+## PHASE 8: 合成 PRD
+
+将 PHASE 0-7 的所有产出合成为两个文档：
 
 ### 输出 1: `.specops/REQUIREMENTS.md`
 
@@ -366,7 +477,24 @@ npx specops update-operation --agent-id <id> --operation "正在进行技术选
 | 包名 | 版本 | 用途 |
 |------|------|------|
 
-## 七、建议实施路线
+## 七、难点分析
+> 来源: PHASE 7 难点分析
+
+### 已解决难点
+
+| 难点 | 来源 | 解决方案 | 方案来源 | 实现复杂度 | 受影响 SC |
+|------|------|---------|---------|-----------|----------|
+| ... | ... | ... | ... | ... | ... |
+
+### 未解决难点（项目难点清单）
+
+| 难点 | 风险等级 | 来源 | 影响范围 | 搜索记录 | 探索方向 |
+|------|---------|------|---------|---------|---------|
+| ... | ... | ... | ... | ... | ... |
+
+> ⚠️ 未解决难点需要在 GSD discuss-phase 中进一步讨论确定处理策略。
+
+## 八、建议实施路线
 ### Phase 1: MVP（预计 X 周）
 - 实现 SC-001 ~ SC-xxx
 - 核心技术: [列表]
@@ -437,7 +565,8 @@ PHASE 3: operation="正在搜索竞品..."                    skill="competitor-
 PHASE 4: operation="正在搜索开源实现..."                skill="feature-search"
 PHASE 5: operation="正在 Clone 并分析参考项目..."       skill="repo-clone-analyze"
 PHASE 6: operation="正在进行技术选型..."                skill="tech-selection"
-PHASE 7: operation="正在合成 PRD..."                    skill="demand-analysis"
+PHASE 7: operation="正在分析项目难点..."                skill="demand-analysis"
+PHASE 8: operation="正在合成 PRD..."                    skill="demand-analysis"
 ```
 
 每个 PHASE 转换时调用：
@@ -484,7 +613,10 @@ PHASE 5: skill(name="repo-clone-analyze")
 PHASE 6: skill(name="tech-selection")
   │       技术选型（含 ref.json 输入）
   ▼
-PHASE 7: 合成 PRD
+PHASE 7: 难点分析
+  │       用户提出 + 主动发现 → 搜索验证 → 分类输出
+  ▼
+PHASE 8: 合成 PRD
   │       → .specops/REQUIREMENTS.md
   │       → .specops/TECH-CONTEXT.md
   │       → 提示: /gsd-new-project --auto
@@ -511,7 +643,7 @@ PHASE 7: 合成 PRD
 |---------|--------|
 | Brainstorm 未批准就进入后续 PHASE | **致命** — 必须获得用户批准 |
 | 不调用子 skill 自己做搜索/选型/分析 | **严重** — 必须通过 skill() 调用 |
-| 跳过 PHASE 0-7 中任何一个 | **严重** |
+| 跳过 PHASE 0-8 中任何一个 | **严重** |
 | 没有识别输入类型就开始分析 | 高 |
 | 跳过功能拆分直接出文档 | 高 |
 | 子 skill 报告还没返回就开始写合成文档 | 高 — 必须等待子 skill 完成 |

package/.opencode/templates/DEBUG.md

@@ -0,0 +1,164 @@
+# 调试模板
+
+`.planning/debug/[slug].md` 的模板，活跃调试会话追踪。
+
+---
+
+## 文件模板
+
+```markdown
+---
+status: gathering | investigating | fixing | verifying | awaiting_human_verify | resolved
+trigger: "[用户原始输入]"
+created: [ISO 时间戳]
+updated: [ISO 时间戳]
+---
+
+## 当前焦点
+<!-- 每次更新时覆盖，始终反映当前状态 -->
+
+hypothesis: [当前正在测试的理论]
+test: [如何测试]
+expecting: [结果为真/假意味着什么]
+next_action: [下一步操作]
+
+## 症状
+<!-- 收集阶段写入，之后不可变 -->
+
+expected: [应该发生什么]
+actual: [实际发生什么]
+errors: [错误信息（如有）]
+reproduction: [如何触发]
+started: [何时出问题 / 一直有问题]
+
+## 已排除
+<!-- 仅追加，防止 /clear 后重复调查 -->
+
+- hypothesis: [被证伪的理论]
+  evidence: [什么证伪了它]
+  timestamp: [排除时间]
+
+## 证据
+<!-- 仅追加，调查中发现的事实 -->
+
+- timestamp: [发现时间]
+  checked: [检查了什么]
+  found: [观察到什么]
+  implication: [这意味着什么]
+
+## 解决方案
+<!-- 随理解深入覆盖 -->
+
+root_cause: [找到前为空]
+fix: [应用前为空]
+verification: [验证前为空]
+files_changed: []
+```
+
+---
+
+<section_rules>
+
+**Frontmatter (status, trigger, timestamps):**
+- `status`: 覆盖 - 反映当前阶段
+- `trigger`: 不可变 - 用户原始输入，永不改变
+- `created`: 不可变 - 设置一次
+- `updated`: 覆盖 - 每次变更时更新
+
+**当前焦点:**
+- 每次更新时完全覆盖
+- 始终反映 Claude 当前正在做什么
+- 如果 Claude 在 /clear 后读取此文件，能准确知道从哪里恢复
+- 字段: hypothesis, test, expecting, next_action
+
+**症状:**
+- 初始收集阶段写入
+- 收集完成后不可变
+- 作为我们要修复什么的参考点
+- 字段: expected, actual, errors, reproduction, started
+
+**已排除:**
+- 仅追加，永不删除条目
+- 防止上下文重置后重复调查死胡同
+- 每个条目: 假设、证伪它的证据、时间戳
+- 对跨 /clear 边界的效率至关重要
+
+**证据:**
+- 仅追加，永不删除条目
+- 调查中发现的事实
+- 每个条目: 时间戳、检查了什么、发现了什么、含义
+- 构建根本原因的论据
+
+**解决方案:**
+- 随理解深入覆盖
+- 尝试修复时可能多次更新
+- 最终状态显示确认的根本原因和已验证的修复
+- 字段: root_cause, fix, verification, files_changed
+
+</section_rules>
+
+<lifecycle>
+
+**创建:** /specops:debug 调用时立即创建
+- 用用户输入创建文件作为 trigger
+- 设置 status 为 "gathering"
+- 当前焦点: next_action = "收集症状"
+- 症状: 空，待填写
+
+**症状收集期间:**
+- 用户回答问题时更新症状部分
+- 每个问题更新当前焦点
+- 完成时: status → "investigating"
+
+**调查期间:**
+- 每个假设覆盖当前焦点
+- 每个发现追加到证据
+- 假设被证伪时追加到已排除
+- 更新 frontmatter 中的时间戳
+
+**修复期间:**
+- status → "fixing"
+- 确认时更新 Resolution.root_cause
+- 应用时更新 Resolution.fix
+- 更新 Resolution.files_changed
+
+**验证期间:**
+- status → "verifying"
+- 用结果更新 Resolution.verification
+- 如果验证失败: status → "investigating"，重试
+
+**自我验证通过后:**
+- status -> "awaiting_human_verify"
+- 在检查点中请求用户明确确认
+- 还不要将文件移到 resolved
+
+**解决时:**
+- status → "resolved"
+- 将文件移到 .planning/debug/resolved/ (仅在用户确认修复后)
+
+</lifecycle>
+
+<resume_behavior>
+
+Claude 在 /clear 后读取此文件时:
+
+1. 解析 frontmatter → 了解状态
+2. 读取当前焦点 → 准确知道在做什么
+3. 读取已排除 → 知道不要重试什么
+4. 读取证据 → 知道已经学到了什么
+5. 从 next_action 继续
+
+文件就是调试大脑。Claude 应该能从任何中断点完美恢复。
+
+</resume_behavior>
+
+<size_constraint>
+
+保持调试文件聚焦:
+- 证据条目: 每个 1-2 行，只记录事实
+- 已排除: 简短，假设 + 为什么失败
+- 不要叙述性散文，只要结构化数据
+
+如果证据增长很大 (10+ 条目)，考虑是否在兜圈子。检查已排除确保没有重复。
+
+</size_constraint>

package/.opencode/templates/UAT.md

@@ -0,0 +1,180 @@
+# UAT 模板
+
+`.planning/phases/XX-name/{phase_num}-UAT.md` 的模板，持久化的 UAT 会话追踪。
+
+---
+
+## 文件模板
+
+```markdown
+---
+status: testing | complete | diagnosed
+phase: XX-name
+source: [被测试的 SUMMARY.md 文件列表]
+started: [ISO 时间戳]
+updated: [ISO 时间戳]
+---
+
+## 当前测试
+<!-- 每次测试时覆盖，显示当前位置 -->
+
+number: [N]
+name: [测试名称]
+expected: |
+  [用户应该观察到什么]
+awaiting: 用户响应
+
+## 测试
+
+### 1. [测试名称]
+expected: [可观测行为 — 用户应该看到什么]
+result: [pending]
+
+### 2. [测试名称]
+expected: [可观测行为]
+result: pass
+
+### 3. [测试名称]
+expected: [可观测行为]
+result: issue
+reported: "[用户原话]"
+severity: major
+
+### 4. [测试名称]
+expected: [可观测行为]
+result: skipped
+reason: [跳过原因]
+
+...
+
+## 总结
+
+total: [N]
+passed: [N]
+issues: [N]
+pending: [N]
+skipped: [N]
+
+## 缺口
+
+<!-- YAML 格式供 plan-phase --gaps 消费 -->
+- truth: "[测试中的预期行为]"
+  status: failed
+  reason: "用户报告: [原话]"
+  severity: blocker | major | minor | cosmetic
+  test: [N]
+  root_cause: ""     # 诊断后填写
+  artifacts: []      # 诊断后填写
+  missing: []        # 诊断后填写
+  debug_session: ""  # 诊断后填写
+```
+
+---
+
+<section_rules>
+
+**Frontmatter:**
+- `status`: 覆盖 - "testing" 或 "complete"
+- `phase`: 不可变 - 创建时设置
+- `source`: 不可变 - 被测试的 SUMMARY 文件
+- `started`: 不可变 - 创建时设置
+- `updated`: 覆盖 - 每次变更时更新
+
+**当前测试:**
+- 每次测试转换时完全覆盖
+- 显示哪个测试活跃以及等待什么
+- 完成时: "[测试完成]"
+
+**测试:**
+- 每个测试: 用户响应时覆盖 result 字段
+- `result` 值: [pending], pass, issue, skipped
+- 如果 issue: 添加 `reported` (原话) 和 `severity` (推断)
+- 如果 skipped: 添加 `reason` (如提供)
+
+**总结:**
+- 每次响应后覆盖计数
+- 追踪: total, passed, issues, pending, skipped
+
+**缺口:**
+- 发现问题时仅追加 (YAML 格式)
+- 诊断后: 填写 `root_cause`, `artifacts`, `missing`, `debug_session`
+- 此部分直接供 /specops:plan-phase --gaps 使用
+
+</section_rules>
+
+<diagnosis_lifecycle>
+
+**测试完成后 (status: complete)，如果有缺口:**
+
+1. 用户运行诊断 (从 verify-work 提供或手动)
+2. diagnose-issues 工作流生成并行调试代理
+3. 每个代理调查一个缺口，返回根本原因
+4. UAT.md 缺口部分更新诊断结果:
+   - 每个缺口填写 `root_cause`, `artifacts`, `missing`, `debug_session`
+5. status → "diagnosed"
+6. 准备好用 /specops:plan-phase --gaps 配合根本原因使用
+
+**诊断后:**
+```yaml
+## 缺口
+
+- truth: "评论提交后立即出现"
+  status: failed
+  reason: "用户报告: 可以用但要刷新页面才显示"
+  severity: major
+  test: 2
+  root_cause: "CommentList.tsx 中 useEffect 缺少 commentCount 依赖"
+  artifacts:
+    - path: "src/components/CommentList.tsx"
+      issue: "useEffect 缺少依赖"
+  missing:
+    - "将 commentCount 添加到 useEffect 依赖数组"
+  debug_session: ".planning/debug/comment-not-refreshing.md"
+```
+
+</diagnosis_lifecycle>
+
+<lifecycle>
+
+**创建:** /specops:verify-work 开始新会话时
+- 从 SUMMARY.md 文件提取测试
+- 设置 status 为 "testing"
+- 当前测试指向测试 1
+- 所有测试 result: [pending]
+
+**测试期间:**
+- 从当前测试部分展示测试
+- 用户以通过确认或问题描述响应
+- 更新测试结果 (pass/issue/skipped)
+- 更新总结计数
+- 如果 issue: 追加到缺口部分 (YAML 格式)，推断严重程度
+- 将当前测试移到下一个 pending 测试
+
+**完成时:**
+- status → "complete"
+- 当前测试 → "[测试完成]"
+- 提交文件
+- 展示总结和下一步
+
+**在 /clear 后恢复:**
+1. 读取 frontmatter → 了解阶段和状态
+2. 读取当前测试 → 了解在哪里
+3. 找到第一个 [pending] 结果 → 从那里继续
+4. 总结显示到目前为止的进度
+
+</lifecycle>
+
+<severity_guide>
+
+严重程度从用户的自然语言推断，永远不要询问。
+
+| 用户描述 | 推断 |
+|---------|------|
+| 崩溃、错误、异常、完全失败、无法使用 | blocker |
+| 不工作、没反应、行为错误、缺失 | major |
+| 能用但...、慢、奇怪、小问题 | minor |
+| 颜色、字体、间距、对齐、视觉、看起来不对 | cosmetic |
+
+默认: **major** (安全的默认值，用户可以纠正)
+
+</severity_guide>

package/.opencode/templates/VALIDATION.md

@@ -0,0 +1,76 @@
+---
+phase: {N}
+slug: {phase-slug}
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: {date}
+---
+
+# 阶段 {N} — 验证策略
+
+> 每阶段的验证契约，用于执行期间的反馈采样。
+
+---
+
+## 测试基础设施
+
+| 属性 | 值 |
+|------|-----|
+| **框架** | {pytest 7.x / jest 29.x / vitest / go test / 其他} |
+| **配置文件** | {路径或 "无 — 波次 0 安装"} |
+| **快速运行命令** | `{quick command}` |
+| **完整套件命令** | `{full command}` |
+| **预估运行时间** | ~{N} 秒 |
+
+---
+
+## 采样频率
+
+- **每次任务提交后:** 运行 `{quick run command}`
+- **每个计划波次后:** 运行 `{full suite command}`
+- **`/specops:verify-work` 之前:** 完整套件必须全绿
+- **最大反馈延迟:** {N} 秒
+
+---
+
+## 每任务验证映射
+
+| 任务 ID | 计划 | 波次 | 需求 | 测试类型 | 自动化命令 | 文件存在 | 状态 |
+|---------|------|------|------|----------|-----------|---------|------|
+| {N}-01-01 | 01 | 1 | REQ-{XX} | unit | `{command}` | ✅ / ❌ W0 | ⬜ 待定 |
+
+*状态: ⬜ 待定 · ✅ 通过 · ❌ 失败 · ⚠️ 不稳定*
+
+---
+
+## 波次 0 要求
+
+- [ ] `{tests/test_file.py}` — REQ-{XX} 的桩
+- [ ] `{tests/conftest.py}` — 共享 fixtures
+- [ ] `{framework install}` — 如果未检测到框架
+
+*如果无需: "现有基础设施覆盖所有阶段需求。"*
+
+---
+
+## 仅手动验证
+
+| 行为 | 需求 | 为何手动 | 测试说明 |
+|------|------|---------|---------|
+| {行为} | REQ-{XX} | {原因} | {步骤} |
+
+*如果无需: "所有阶段行为都有自动化验证。"*
+
+---
+
+## 验证签核
+
+- [ ] 所有任务有 `<automated>` verify 或波次 0 依赖
+- [ ] 采样连续性: 不超过 3 个连续任务无自动化 verify
+- [ ] 波次 0 覆盖所有 MISSING 引用
+- [ ] 无 watch-mode 标志
+- [ ] 反馈延迟 < {N}s
+- [ ] frontmatter 中 `nyquist_compliant: true` 已设置
+
+**批准:** {待定 / 已批准 YYYY-MM-DD}