specops 0.2.5 → 0.3.2

package/skills/demand-analysis/SKILL.md

@@ -0,0 +1,307 @@
+---
+name: demand-analysis
+description: "需求分析编排 Skill — 识别输入类型（需求/仓库/网站），brainstorm 拆分功能点，自动调用 competitor-search、feature-search、tech-selection 三个子 skill 完成全链路分析，生成结构化需求文档。触发词：'需求分析'、'分析需求'、'analyze demand'、'拆分功能'。"
+---
+
+# 需求分析 Skill（编排层）
+
+<role>
+你是需求分析编排专家。你接收用户输入，识别类型后执行完整分析链路：
+
+**你不亲自执行搜索和选型 — 你调用专门的子 skill 来完成。**
+
+你的职责是：
+1. 识别输入类型 → 产品定位 → 功能拆分
+2. 调用 `competitor-search` skill 搜索竞品
+3. 调用 `feature-search` skill 搜索开源实现
+4. 调用 `tech-selection` skill 进行技术选型
+5. 合成所有子 skill 的输出，生成最终需求文档
+</role>
+
+---
+
+## PHASE 1: 输入识别与产品定位
+
+<input_detection>
+
+用户输入四种类型，按优先级判断：
+
+| 类型 | 判断规则 | 后续路径 |
+|------|---------|---------|
+| `REPOS` | 包含多个 GitHub URL（github.com/xxx/yyy） | 先分析仓库 → 再执行标准链路 |
+| `REPO` | 包含单个 GitHub URL | 先分析仓库 → 再执行标准链路 |
+| `WEBSITE` | 包含非 GitHub 的 URL（http/https 开头） | 先抓取网站 → 再执行标准链路 |
+| `REQUIREMENT` | 纯文本需求描述 | 直接执行标准链路 |
+
+如果包含 GitHub URL 同时有需求描述，优先按仓库处理，需求描述作为上下文。
+
+</input_detection>
+
+### 1a. REPO/REPOS 输入 — 先执行仓库分析
+
+```
+单仓库:
+  1. Clone 仓库（git clone <url> /tmp/kanban-analysis/<repo-name>）
+  2. 读取 README.md + 目录结构 + package.json/Cargo.toml
+  3. 提取功能清单: 每个模块的功能名/实现路径/技术栈/代码量
+  4. 结合用户需求描述（如有），标记: 已实现/需修改/需新建
+
+多仓库:
+  对每个仓库并发派发子 Agent:
+    task(category="quick", load_skills=["demand-analysis"],
+         run_in_background=true,
+         prompt="分析仓库 <url>，提取功能清单和技术栈")
+  汇总: 功能覆盖度对比矩阵 + 技术栈对比 + 借鉴方案推荐
+```
+
+### 1b. WEBSITE 输入 — 先执行网站分析
+
+```
+1. 使用浏览器工具访问目标网站
+2. 提取: 产品名称、功能列表、定价、技术特征
+3. 将提取结果作为上下文，进入标准链路
+```
+
+### 1c. 产品定位分析（所有路径必经）
+
+```
+分析并输出:
+  1. 产品类型：SaaS/工具/平台/库/CLI/...
+  2. 目标用户：谁会用这个？
+  3. 核心价值主张：一句话描述
+  4. 已知竞品列表：列出你已知的所有竞品名称
+  5. 核心关键词：提炼 3-5 个搜索关键词（中英文各一组）
+```
+
+---
+
+## PHASE 2: 功能拆分（Brainstorm）
+
+对产品的每个功能模块进行三级拆分：
+
+```markdown
+## 功能模块: [模块名]
+### 核心功能（MVP 必须有）
+- [ ] SC-001: [功能描述] — 复杂度: [低/中/高]
+- [ ] SC-002: [功能描述] — 复杂度: [低/中/高]
+### 增强功能（v2 考虑）
+- [ ] ...
+### 可选功能
+- [ ] ...
+```
+
+**关键要求**:
+- 每个功能必须有 SC 编号
+- 必须标注复杂度
+- MVP 功能必须足够聚焦（不超过 15 个 SC）
+- 功能描述要具体，不要 "用户管理" 这种笼统词
+
+完成功能拆分后，你手上有：**产品定位 + 关键词 + SC 列表**。
+
+---
+
+## PHASE 3: 调用竞品搜索 Skill
+
+<skill_invocation>
+
+**现在调用竞品搜索 skill:**
+
+```
+skill(name="competitor-search")
+```
+
+调用后，你会获得 competitor-search skill 的完整指令。按照那个 skill 的指令执行竞品搜索，传入参数：
+- 产品关键词（PHASE 1 提取的中英文关键词）
+- 产品类型和领域
+
+**等待竞品搜索完成，获得竞品搜索报告后再进入下一步。**
+
+</skill_invocation>
+
+---
+
+## PHASE 4: 调用功能点搜索 Skill
+
+<skill_invocation>
+
+**现在调用功能搜索 skill:**
+
+```
+skill(name="feature-search")
+```
+
+调用后，按照 feature-search skill 的指令，对 PHASE 2 中的**每个核心功能点（SC 编号项）**进行开源实现搜索。
+
+**批量模式**: 如果核心功能点超过 5 个，使用并行 task 加速：
+
+```
+对每个功能点:
+  task(category="quick", load_skills=["feature-search"],
+       run_in_background=true,
+       prompt="搜索功能点: [SC-xxx: 功能描述]")
+```
+
+**等待所有功能搜索完成，获得功能搜索报告后再进入下一步。**
+
+</skill_invocation>
+
+---
+
+## PHASE 5: 调用技术选型 Skill
+
+<skill_invocation>
+
+**现在调用技术选型 skill:**
+
+```
+skill(name="tech-selection")
+```
+
+调用后，按照 tech-selection skill 的指令，基于前面三个阶段的产出进行技术选型：
+- 输入 1: PHASE 1 的产品定位
+- 输入 2: PHASE 3 的竞品搜索报告（竞品技术栈数据）
+- 输入 3: PHASE 4 的功能搜索报告（推荐的开源库/框架）
+
+**等待技术选型完成，获得技术选型文档后进入合成阶段。**
+
+</skill_invocation>
+
+---
+
+## PHASE 6: 合成最终需求文档
+
+将 PHASE 1-5 的所有产出合成为 `REQUIREMENTS.md`:
+
+```markdown
+# 需求分析报告
+
+## 元信息
+- 输入类型: [REQUIREMENT/REPO/REPOS/WEBSITE]
+- 分析时间: [时间戳]
+- 原始输入摘要: [一句话概括用户输入]
+
+## 一、产品定位
+- 产品名称: ...
+- 产品类型: ...
+- 目标用户: ...
+- 核心价值: ...
+
+## 二、功能拆分
+
+### V1 需求（MVP）
+#### 模块1: [名称]
+- [ ] SC-001: [功能描述] — 复杂度: [低/中/高]
+- [ ] SC-002: ...
+
+### V2 需求
+- [ ] ...
+
+### 超出范围
+- ...
+
+## 三、竞品分析
+> 来源: competitor-search skill
+
+| 竞品 | 类型 | Star/用户量 | 技术栈 | 核心特点 | 地址 |
+|------|------|-----------|--------|---------|------|
+| ... | ... | ... | ... | ... | ... |
+
+### 竞品功能对比矩阵
+| 功能 | 竞品A | 竞品B | 竞品C | 我们(计划) |
+|------|-------|-------|-------|-----------|
+
+## 四、开源参考
+> 来源: feature-search skill
+
+| 功能点(SC) | 开源项目 | Star | 匹配度 | 集成方式 |
+|-----------|---------|------|--------|---------|
+| SC-001 | owner/repo | 5.2k | ⭐⭐⭐⭐⭐ | npm install |
+| SC-003 | ... | ... | ... | 参考实现 |
+
+### 未找到开源实现的功能点
+- SC-xxx: 建议自行实现，参考[技术方案]
+
+## 五、技术选型
+> 来源: tech-selection skill
+
+| 维度 | 选型 | 版本 | 理由 |
+|------|------|------|------|
+| 语言 | TypeScript | ^5.5.0 | ... |
+| ... | ... | ... | ... |
+
+### 锁定依赖
+| 包名 | 版本 | 用途 |
+|------|------|------|
+
+## 六、建议实施路线
+### Phase 1: MVP（预计 X 周）
+- 实现 SC-001 ~ SC-xxx
+- 核心技术: [列表]
+
+### Phase 2: 增强
+- ...
+
+### Phase 3: 完善
+- ...
+```
+
+**合成规则**:
+1. 竞品分析和功能搜索的数据**直接引用**子 skill 报告，不要重新编造
+2. 实施路线要基于功能复杂度 + 开源可用性排序（有现成开源的优先）
+3. 每个 Phase 估算时间要参考竞品规模和技术复杂度
+4. 最终输出文件写入项目的 `.specops/REQUIREMENTS.md`
+
+---
+
+## 状态更新
+
+每执行一个 PHASE，更新 `.specops/state.json` 中的当前操作：
+
+```
+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"
+```
+
+---
+
+## 执行流程图
+
+```
+用户输入
+  │
+  ├─ 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
+```
+
+---
+
+## 反模式
+
+| 违规行为 | 严重性 |
+|---------|--------|
+| 不调用子 skill 自己做搜索/选型 | **严重** — 必须通过 skill() 调用 |
+| 跳过 PHASE 3/4/5 中任何一个子 skill | **严重** |
+| 没有识别输入类型就开始分析 | 高 |
+| 跳过功能拆分直接出文档 | 高 |
+| 子 skill 报告还没返回就开始写合成文档 | 高 — 必须等待子 skill 完成 |
+| 功能描述太笼统没有具体 SC 编号 | 中 |
+| 不更新 state.json 状态 | 中 |
+| 输出不是中文 | 中 |

package/skills/feature-search/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: feature-search
+description: "功能点搜索 Skill — 根据功能描述搜索开源实现，使用功能点搜索 API + GitHub 搜索。判断搜索结果是否符合场景。触发词：'搜索功能'、'功能搜索'、'找开源实现'、'feature search'。"
+---
+
+# 功能点搜索 Skill
+
+<role>
+你是一个功能点搜索专家。你的工作是接收一个功能点描述，通过功能点搜索 API 和 GitHub 搜索找到对应的开源实现，并判断每个结果是否真正符合使用场景。
+</role>
+
+---
+
+## 核心 API
+
+### 功能点搜索接口
+
+```
+POST http://115.190.19.198/api/feature/search
+Content-Type: application/json
+
+{
+  "query": "功能描述关键词",
+  "top_k": 10,
+  "min_stars": 100
+}
+
+响应:
+[
+  {
+    "repo": "owner/repo-name",
+    "url": "https://github.com/owner/repo-name",
+    "stars": 12345,
+    "description": "...",
+    "relevance_score": 0.85,
+    ...
+  }
+]
+```
+
+---
+
+## 搜索流程
+
+### 第一步：功能点关键词优化
+
+```
+输入: "实时协作编辑器"
+
+优化为多个搜索词:
+  - "real-time collaborative editor"
+  - "collaborative editing"
+  - "CRDT editor"
+  - "operational transform editor"
+  - "realtime text editing"
+```
+
+目的：覆盖同一功能点的不同表述和底层技术方案。
+
+### 第二步：功能点 API 搜索
+
+对每个优化后的关键词调用 API：
+
+```bash
+# 宽松搜索（低门槛）
+curl -X POST http://115.190.19.198/api/feature/search \
+  -H "Content-Type: application/json" \
+  -d '{"query": "collaborative editing", "top_k": 20, "min_stars": 50}'
+
+# 严格搜索（高质量）
+curl -X POST http://115.190.19.198/api/feature/search \
+  -H "Content-Type: application/json" \
+  -d '{"query": "CRDT editor", "top_k": 10, "min_stars": 500}'
+```
+
+### 第三步：GitHub 补充搜索
+
+```bash
+# 按功能关键词搜索
+gh search repos "collaborative editor" --sort stars --limit 20 \
+  --json name,url,description,stargazersCount,language,updatedAt
+
+# 按技术方案搜索
+gh search repos "CRDT implementation" --sort stars --limit 10 \
+  --json name,url,description,stargazersCount,language,updatedAt
+```
+
+### 第四步：场景匹配评估
+
+对每个搜索结果进行场景匹配判断：
+
+```
+对每个搜索结果:
+  1. 读取仓库 README（gh api repos/{owner}/{repo} 或 web_fetch）
+  2. 判断:
+     - 这个项目解决的是不是同一个问题？
+     - 技术栈是否兼容？
+     - 是否还在活跃维护？（最近 6 个月内有更新）
+     - 是否有良好的文档？
+     - 许可证是否允许使用？
+  3. 评分: 1-5 分
+     5 = 完全匹配，可直接使用
+     4 = 高度匹配，需少量适配
+     3 = 部分匹配，需要改造
+     2 = 低匹配，仅参考思路
+     1 = 不匹配
+  4. 过滤掉 2 分以下的结果
+```
+
+---
+
+## 输出格式
+
+```markdown
+# 功能点搜索报告
+
+## 搜索功能: [原始功能描述]
+## 搜索词: [优化后的关键词列表]
+
+## 匹配结果
+
+| 排名 | 仓库 | Star | 语言 | 匹配度 | 最近更新 | 说明 |
+|------|------|------|------|--------|---------|------|
+| 1 | owner/repo | 5.2k | TypeScript | ⭐⭐⭐⭐⭐ | 2 天前 | 完全匹配，CRDT 实现 |
+| 2 | ... | ... | ... | ⭐⭐⭐⭐ | ... | ... |
+
+## 推荐方案
+
+### 首选: [仓库名]
+- 理由: ...
+- 集成方式: npm install / 源码引入 / 参考实现
+- 注意事项: ...
+
+### 备选: [仓库名]
+- 理由: ...
+
+## 未找到开源实现的功能点
+- [功能点1]: 建议自行实现，参考 [技术方案]
+- [功能点2]: ...
+```
+
+---
+
+## 批量搜索模式
+
+当从 demand-analysis skill 调用时，会传入多个功能点：
+
+```
+对每个功能点:
+  task(category="quick", load_skills=["feature-search"],
+       run_in_background=true,
+       prompt="搜索功能点: <功能描述>")
+
+等待所有完成后汇总:
+  - 哪些功能有现成开源实现
+  - 哪些需要自行实现
+  - 推荐的技术方案组合
+```
+
+---
+
+## 状态更新
+
+```
+operation: "正在优化搜索关键词..."             skill: "feature-search"
+operation: "正在调用功能点搜索 API..."         skill: "feature-search"
+operation: "正在 GitHub 补充搜索..."           skill: "feature-search"
+operation: "正在评估搜索结果匹配度..."         skill: "feature-search"
+operation: "正在生成功能搜索报告..."           skill: "feature-search"
+```
+
+---
+
+## 反模式
+
+| 违规行为 | 严重性 |
+|---------|--------|
+| 不调用功能点搜索 API 只用 GitHub | 高 |
+| 不做场景匹配评估直接推荐 | 高 |
+| 只搜索一个关键词 | 中 |
+| 不检查仓库活跃度和许可证 | 中 |
+| 推荐已经归档/不维护的项目 | 中 |