specops 0.2.3 → 0.2.5

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

@@ -1,25 +1,75 @@
 ---
 name: demand-analysis
-description: "需求分析编排 Skill — 识别输入类型（需求/仓库/网站），brainstorm 拆分功能点，自动调用 competitor-search、feature-search、tech-selection 三个子 skill 完成全链路分析，生成结构化需求文档。触发词：'需求分析'、'分析需求'、'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>
-你是需求分析编排专家。你接收用户输入，识别类型后执行完整分析链路：
+你是需求分析编排专家。你接收用户输入，按 9 个 PHASE 顺序执行完整分析链路：
 
-**你不亲自执行搜索和选型 — 你调用专门的子 skill 来完成。**
+**你不亲自执行搜索、分析和选型 — 你调用专门的子 skill 来完成。**
 
 你的职责是：
-1. 识别输入类型 → 产品定位 → 功能拆分
-2. 调用 `competitor-search` skill 搜索竞品
-3. 调用 `feature-search` skill 搜索开源实现
-4. 调用 `tech-selection` skill 进行技术选型
-5. 合成所有子 skill 的输出，生成最终需求文档
+0. 调用 `brainstorming` skill 澄清需求、呈现设计、获得批准
+1. 识别输入类型 → 产品定位
+2. 功能拆分（三级：MVP / 增强 / 可选）
+3. 调用 `competitor-search` skill 搜索竞品
+4. 调用 `feature-search` skill 搜索开源实现
+5. 调用 `repo-clone-analyze` skill Clone 并分析参考项目
+6. 调用 `tech-selection` skill 进行技术选型
+7. 难点分析：验证和发现项目技术/功能/集成难点
+8. 合成所有产出，生成 REQUIREMENTS.md + TECH-CONTEXT.md
 </role>
 
 ---
 
+## 硬约束
+
+| 约束 | 说明 |
+|------|------|
+| **Brainstorm 门禁** | PHASE 0 设计批准前，**禁止**进入任何后续 PHASE |
+| **子 skill 调用** | 搜索/分析/选型必须通过 `skill()` 调用，不得自行执行 |
+| **顺序执行** | PHASE 必须按 0→1→2→3→4→5→6→7→8 顺序执行，不得跳过 |
+| **状态更新** | 每个 PHASE 转换时必须调用 specops CLI 更新状态 |
+| **全中文输出** | 所有文档、报告、状态描述均使用中文 |
+
+---
+
+## PHASE 0: Brainstorm（需求澄清与设计批准）
+
+<brainstorm>
+
+**调用子 skill：**
+
+```
+skill(name="brainstorming")
+```
+
+按照 brainstorming skill 的指令执行：
+- **一次一问**：每轮只问一个澄清问题，等用户回答后再问下一个
+- 探索用户意图、需求边界、目标用户、核心场景
+- 逐步收敛，形成设计方案
+- 呈现设计方案给用户审阅
+
+**输出：**
+- 设计文档：`docs/plans/YYYY-MM-DD-<主题>-design.md`
+- 用户明确批准（"可以"、"通过"、"approved" 等肯定回复）
+
+**门禁条件：**
+- ✅ 设计文档已生成
+- ✅ 用户已明确批准设计
+- ❌ 未批准 → 继续迭代设计，不得进入 PHASE 1
+
+**状态更新：**
+```bash
+npx specops update-operation --agent-id <id> --operation "正在 Brainstorm 澄清需求..." --skill "brainstorming"
+```
+
+</brainstorm>
+
+---
+
 ## PHASE 1: 输入识别与产品定位
 
 <input_detection>
@@ -73,9 +123,15 @@ description: "需求分析编排 Skill — 识别输入类型（需求/仓库/
   5. 核心关键词：提炼 3-5 个搜索关键词（中英文各一组）
 ```
 
+**状态更新：**
+```bash
+npx specops advance --agent-id <id>
+npx specops update-operation --agent-id <id> --operation "正在识别输入类型和产品定位..." --skill "demand-analysis"
+```
+
 ---
 
-## PHASE 2: 功能拆分（Brainstorm）
+## PHASE 2: 功能拆分
 
 对产品的每个功能模块进行三级拆分：
 
@@ -98,6 +154,12 @@ description: "需求分析编排 Skill — 识别输入类型（需求/仓库/
 
 完成功能拆分后，你手上有：**产品定位 + 关键词 + SC 列表**。
 
+**状态更新：**
+```bash
+npx specops advance --agent-id <id>
+npx specops update-operation --agent-id <id> --operation "正在拆分功能模块..." --skill "demand-analysis"
+```
+
 ---
 
 ## PHASE 3: 调用竞品搜索 Skill
@@ -116,6 +178,12 @@ skill(name="competitor-search")
 
 **等待竞品搜索完成，获得竞品搜索报告后再进入下一步。**
 
+**状态更新：**
+```bash
+npx specops advance --agent-id <id>
+npx specops update-operation --agent-id <id> --operation "正在搜索竞品..." --skill "competitor-search"
+```
+
 </skill_invocation>
 
 ---
@@ -143,11 +211,50 @@ skill(name="feature-search")
 
 **等待所有功能搜索完成，获得功能搜索报告后再进入下一步。**
 
+**状态更新：**
+```bash
+npx specops advance --agent-id <id>
+npx specops update-operation --agent-id <id> --operation "正在搜索开源实现..." --skill "feature-search"
+```
+
+</skill_invocation>
+
+---
+
+## PHASE 5: 调用 Clone + 分析 Skill
+
+<skill_invocation>
+
+**现在调用仓库 Clone 分析 skill:**
+
+```
+skill(name="repo-clone-analyze")
+```
+
+调用后，按照 repo-clone-analyze skill 的指令执行：
+- 从 PHASE 3（竞品搜索）和 PHASE 4（功能搜索）的结果中筛选需要 clone 的项目
+- 排除基础框架和通用库（react、express、yargs、commander、zod 等）
+- Clone 功能参考项目（竞品、开源实现），深度分析源码
+- 生成 overview.md + index.json + ref.json
+
+**传入参数：**
+- PHASE 3 的竞品搜索报告（竞品列表 + GitHub URL）
+- PHASE 4 的功能搜索报告（开源项目列表 + GitHub URL）
+- 项目根目录路径（用于确定 `.specops/ref/` 输出目录）
+
+**等待 Clone 分析完成，获得 ref.json 后再进入下一步。**
+
+**状态更新：**
+```bash
+npx specops advance --agent-id <id>
+npx specops update-operation --agent-id <id> --operation "正在 Clone 并分析参考项目..." --skill "repo-clone-analyze"
+```
+
 </skill_invocation>
 
 ---
 
-## PHASE 5: 调用技术选型 Skill
+## PHASE 6: 调用技术选型 Skill
 
 <skill_invocation>
 
@@ -157,20 +264,144 @@ skill(name="feature-search")
 skill(name="tech-selection")
 ```
 
-调用后，按照 tech-selection skill 的指令，基于前面三个阶段的产出进行技术选型：
+调用后，按照 tech-selection skill 的指令，基于前面所有阶段的产出进行技术选型：
 - 输入 1: PHASE 1 的产品定位
 - 输入 2: PHASE 3 的竞品搜索报告（竞品技术栈数据）
 - 输入 3: PHASE 4 的功能搜索报告（推荐的开源库/框架）
+- 输入 4: PHASE 5 的 ref.json（参考项目的功能-代码索引，技术栈详情）
+
+**ref.json 为技术选型提供的额外信息：**
+- 参考项目实际使用的技术栈和依赖
+- 各功能模块的实现方式和架构模式
+- 可直接借鉴的代码路径和关键文件
 
 **等待技术选型完成，获得技术选型文档后进入合成阶段。**
 
+**状态更新：**
+```bash
+npx specops advance --agent-id <id>
+npx specops update-operation --agent-id <id> --operation "正在进行技术选型..." --skill "tech-selection"
+```
+
 </skill_invocation>
 
 ---
 
-## PHASE 6: 合成最终需求文档
+## PHASE 7: 难点分析
+
+<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 的所有产出合成为两个文档：
 
-将 PHASE 1-5 的所有产出合成为 `REQUIREMENTS.md`:
+### 输出 1: `.specops/REQUIREMENTS.md`
 
 ```markdown
 # 需求分析报告
@@ -179,6 +410,7 @@ skill(name="tech-selection")
 - 输入类型: [REQUIREMENT/REPO/REPOS/WEBSITE]
 - 分析时间: [时间戳]
 - 原始输入摘要: [一句话概括用户输入]
+- 设计文档: [docs/plans/YYYY-MM-DD-<主题>-design.md]
 
 ## 一、产品定位
 - 产品名称: ...
@@ -221,7 +453,19 @@ skill(name="tech-selection")
 ### 未找到开源实现的功能点
 - SC-xxx: 建议自行实现，参考[技术方案]
 
-## 五、技术选型
+## 五、参考项目深度分析
+> 来源: repo-clone-analyze skill
+
+### Clone 分析的项目
+| 项目 | 分析原因 | overview | index |
+|------|---------|----------|-------|
+| project-a | 竞品，核心功能参考 | .specops/ref/project-a/overview.md | .specops/ref/project-a/index.json |
+
+### 功能级索引
+- ref.json 路径: `.specops/ref/ref.json`
+- 包含功能: [功能名列表]
+
+## 六、技术选型
 > 来源: tech-selection skill
 
 | 维度 | 选型 | 版本 | 理由 |
@@ -233,7 +477,24 @@ skill(name="tech-selection")
 | 包名 | 版本 | 用途 |
 |------|------|------|
 
-## 六、建议实施路线
+## 七、难点分析
+> 来源: PHASE 7 难点分析
+
+### 已解决难点
+
+| 难点 | 来源 | 解决方案 | 方案来源 | 实现复杂度 | 受影响 SC |
+|------|------|---------|---------|-----------|----------|
+| ... | ... | ... | ... | ... | ... |
+
+### 未解决难点（项目难点清单）
+
+| 难点 | 风险等级 | 来源 | 影响范围 | 搜索记录 | 探索方向 |
+|------|---------|------|---------|---------|---------|
+| ... | ... | ... | ... | ... | ... |
+
+> ⚠️ 未解决难点需要在 GSD discuss-phase 中进一步讨论确定处理策略。
+
+## 八、建议实施路线
 ### Phase 1: MVP（预计 X 周）
 - 实现 SC-001 ~ SC-xxx
 - 核心技术: [列表]
@@ -245,25 +506,73 @@ skill(name="tech-selection")
 - ...
 ```
 
-**合成规则**:
-1. 竞品分析和功能搜索的数据**直接引用**子 skill 报告，不要重新编造
-2. 实施路线要基于功能复杂度 + 开源可用性排序（有现成开源的优先）
-3. 每个 Phase 估算时间要参考竞品规模和技术复杂度
-4. 最终输出文件写入项目的 `.specops/REQUIREMENTS.md`
+### 输出 2: `.specops/TECH-CONTEXT.md`
+
+从技术选型结果中提取，格式对齐 GSD 的 TECH-CONTEXT 模板：
+
+```markdown
+# 技术上下文
+
+## 锁定依赖
+| 包名 | 版本 | 用途 |
+|------|------|------|
+
+## 禁止模式
+| 模式 | 原因 |
+|------|------|
+
+## 编码约定
+- ...
+
+## 项目结构
+```
+
+### 下一步提示
+
+合成完成后，输出提示：
+
+```
+✅ 需求分析完成！
+
+产出文件：
+  - .specops/REQUIREMENTS.md（需求文档）
+  - .specops/TECH-CONTEXT.md（技术上下文）
+  - .specops/ref/ref.json（参考项目索引）
+  - docs/plans/YYYY-MM-DD-<主题>-design.md（设计文档）
+
+下一步：
+  /gsd-new-project --auto
+  （GSD 将读取 REQUIREMENTS.md 自动创建项目）
+```
+
+**状态更新：**
+```bash
+npx specops advance --agent-id <id>
+npx specops update-operation --agent-id <id> --operation "正在合成 PRD..." --skill "demand-analysis"
+```
 
 ---
 
-## 状态更新
+## 状态更新汇总
 
-每执行一个 PHASE，更新 `.specops/state.json` 中的当前操作：
+每执行一个 PHASE，调用 specops CLI 更新状态：
 
 ```
-PHASE 1: operation="正在识别输入类型和产品定位..."  skill="demand-analysis"
-PHASE 2: operation="正在拆分功能模块..."            skill="demand-analysis"
-PHASE 3: operation="正在搜索竞品..."                skill="competitor-search"
-PHASE 4: operation="正在搜索开源实现..."            skill="feature-search"
-PHASE 5: operation="正在进行技术选型..."            skill="tech-selection"
-PHASE 6: operation="正在合成需求文档..."            skill="demand-analysis"
+PHASE 0: operation="正在 Brainstorm 澄清需求..."       skill="brainstorming"
+PHASE 1: operation="正在识别输入类型和产品定位..."       skill="demand-analysis"
+PHASE 2: operation="正在拆分功能模块..."                skill="demand-analysis"
+PHASE 3: operation="正在搜索竞品..."                    skill="competitor-search"
+PHASE 4: operation="正在搜索开源实现..."                skill="feature-search"
+PHASE 5: operation="正在 Clone 并分析参考项目..."       skill="repo-clone-analyze"
+PHASE 6: operation="正在进行技术选型..."                skill="tech-selection"
+PHASE 7: operation="正在分析项目难点..."                skill="demand-analysis"
+PHASE 8: operation="正在合成 PRD..."                    skill="demand-analysis"
+```
+
+每个 PHASE 转换时调用：
+```bash
+npx specops advance --agent-id <id>
+npx specops update-operation --agent-id <id> --operation "当前操作" --skill "当前skill"
 ```
 
 ---
@@ -273,35 +582,72 @@ PHASE 6: operation="正在合成需求文档..."            skill="demand-analys
 ```
 用户输入
   │
-  ├─ REPOS? ──→ 并行分析各仓库 ──┐
-  ├─ REPO?  ──→ 分析单仓库 ──────┤
-  ├─ WEBSITE? → 抓取网站信息 ────┤
-  └─ TEXT ─────────────────────────┤
-                                   ↓
-                        PHASE 1: 产品定位
-                               ↓
-                        PHASE 2: 功能拆分（Brainstorm）
-                               ↓
-                        PHASE 3: skill(name="competitor-search")
-                               ↓
-                        PHASE 4: skill(name="feature-search")
-                               ↓
-                        PHASE 5: skill(name="tech-selection")
-                               ↓
-                        PHASE 6: 合成 → REQUIREMENTS.md
+  ▼
+PHASE 0: skill(name="brainstorming")
+  │       一次一问 → 设计文档 → 用户批准
+  │       输出: docs/plans/YYYY-MM-DD-<主题>-design.md
+  │
+  ├─ 未批准 → 继续迭代（不得进入后续 PHASE）
+  │
+  ▼ （批准后）
+PHASE 1: 输入识别 + 产品定位
+  │  ├─ REPOS? ──→ 并行分析各仓库 ──┐
+  │  ├─ REPO?  ──→ 分析单仓库 ──────┤
+  │  ├─ WEBSITE? → 抓取网站信息 ────┤
+  │  └─ TEXT ─────────────────────────┤
+  │                                   ▼
+  │                        产品定位表
+  ▼
+PHASE 2: 功能拆分（SC 编号 + 复杂度）
+  │
+  ▼
+PHASE 3: skill(name="competitor-search")
+  │       竞品搜索报告
+  ▼
+PHASE 4: skill(name="feature-search")
+  │       功能搜索报告
+  ▼
+PHASE 5: skill(name="repo-clone-analyze")
+  │       筛选 → Clone → 分析 → ref.json
+  ▼
+PHASE 6: skill(name="tech-selection")
+  │       技术选型（含 ref.json 输入）
+  ▼
+PHASE 7: 难点分析
+  │       用户提出 + 主动发现 → 搜索验证 → 分类输出
+  ▼
+PHASE 8: 合成 PRD
+  │       → .specops/REQUIREMENTS.md
+  │       → .specops/TECH-CONTEXT.md
+  │       → 提示: /gsd-new-project --auto
+  ▼
+传递给 GSD
 ```
 
 ---
 
+## 合成规则
+
+1. 竞品分析和功能搜索的数据**直接引用**子 skill 报告，不要重新编造
+2. 参考项目分析的数据**直接引用** ref.json 和 overview.md，不要重新编造
+3. 实施路线要基于功能复杂度 + 开源可用性排序（有现成开源的优先）
+4. 每个 Phase 估算时间要参考竞品规模和技术复杂度
+5. TECH-CONTEXT.md 的格式必须对齐 GSD 的技术上下文模板
+6. 最终输出文件写入项目的 `.specops/` 目录
+
+---
+
 ## 反模式
 
 | 违规行为 | 严重性 |
 |---------|--------|
-| 不调用子 skill 自己做搜索/选型 | **严重** — 必须通过 skill() 调用 |
-| 跳过 PHASE 3/4/5 中任何一个子 skill | **严重** |
+| Brainstorm 未批准就进入后续 PHASE | **致命** — 必须获得用户批准 |
+| 不调用子 skill 自己做搜索/选型/分析 | **严重** — 必须通过 skill() 调用 |
+| 跳过 PHASE 0-8 中任何一个 | **严重** |
 | 没有识别输入类型就开始分析 | 高 |
 | 跳过功能拆分直接出文档 | 高 |
 | 子 skill 报告还没返回就开始写合成文档 | 高 — 必须等待子 skill 完成 |
 | 功能描述太笼统没有具体 SC 编号 | 中 |
-| 不更新 state.json 状态 | 中 |
+| 不调用 specops CLI 更新状态 | 中 |
+| 不生成 TECH-CONTEXT.md | 中 |
 | 输出不是中文 | 中 |