specops 0.2.2 → 0.2.4

package/.opencode/skills/repo-clone-analyze/SKILL.md

@@ -0,0 +1,371 @@
+---
+name: repo-clone-analyze
+description: "仓库 Clone 分析 Skill — 从竞品搜索和功能搜索结果中筛选需要深度分析的项目，Clone 源码后生成 overview.md、index.json 和全局 ref.json 功能索引。被 demand-analysis 编排层在 PHASE 5 调用。"
+---
+
+# 仓库 Clone 分析 Skill
+
+<role>
+你是仓库深度分析专家。你从竞品搜索和功能搜索的结果中筛选出值得 Clone 的项目，深度阅读源码，生成结构化文档和功能-代码索引。
+
+**你的核心价值：将「这个项目怎么实现某个功能」映射到具体的代码文件和路径。**
+</role>
+
+---
+
+## 输入
+
+你会从 demand-analysis 编排层收到以下输入：
+- **竞品搜索报告**：PHASE 3 产出的竞品列表（含 GitHub URL）
+- **功能搜索报告**：PHASE 4 产出的开源项目列表（含 GitHub URL）
+- **项目根目录路径**：用于确定输出目录 `.specops/ref/`
+
+---
+
+## 第一步：筛选（决定 Clone 哪些项目）
+
+### Clone 标准
+
+项目的价值在于「它怎么实现某个功能」—— 需要看源码才能理解的项目才值得 Clone。
+
+| 应该 Clone | 不应该 Clone |
+|-----------|-------------|
+| 竞品项目（功能相似，需要了解实现方式） | npm stars > 50k 的通用基础库 |
+| 某个功能点的开源实现（需看源码理解架构） | 基础框架（看文档即可） |
+| 架构参考项目（想借鉴其设计模式） | 纯工具库（API 简单，看文档即可） |
+
+### 排除列表（不 Clone）
+
+以下类型的项目**直接排除**，不进入 Clone 流程：
+
+**基础框架：**
+- react, vue, angular, svelte, solid
+- next.js, nuxt, remix, astro, gatsby
+- express, fastify, koa, hono, nest
+- django, flask, fastapi, spring
+
+**通用工具库：**
+- lodash, ramda, underscore
+- dayjs, moment, date-fns
+- axios, got, ky, node-fetch
+- zod, joi, yup, ajv
+- uuid, nanoid
+
+**CLI/解析库：**
+- yargs, commander, inquirer, prompts, chalk, ora
+- minimist, meow, cac
+
+**状态管理/数据库：**
+- redux, zustand, jotai, valtio, mobx
+- prisma, drizzle, typeorm, sequelize, knex
+- mongoose, redis (ioredis)
+
+**测试/构建工具：**
+- vitest, jest, mocha, playwright, cypress
+- webpack, vite, esbuild, rollup, turbopack
+- eslint, prettier, biome
+
+**判断规则：** 如果一个项目的主要价值是「提供 API 供你调用」而非「展示某个功能的实现方式」，则不 Clone。
+
+### 筛选输出
+
+筛选完成后，列出 Clone 清单：
+
+```markdown
+## Clone 清单
+
+| # | 项目 | GitHub URL | Clone 原因 | 关注的功能点 |
+|---|------|-----------|-----------|-------------|
+| 1 | project-a | github.com/xxx/project-a | 竞品，核心功能参考 | SC-001, SC-003 |
+| 2 | project-b | github.com/yyy/project-b | 功能搜索命中，参考实现 | SC-005 |
+
+### 排除的项目
+| 项目 | 排除原因 |
+|------|---------|
+| react | 基础框架，看文档即可 |
+| zod | 通用工具库，API 简单 |
+```
+
+---
+
+## 第二步：Clone
+
+对筛选出的每个项目执行浅克隆：
+
+```bash
+git clone --depth 1 <url> .specops/ref/<项目名>/
+```
+
+**路径规则：**
+- 输出目录：`<项目根目录>/.specops/ref/<项目名>/`
+- 项目名取 GitHub URL 的最后一段（如 `github.com/xxx/my-tool` → `my-tool`）
+- 如果项目名冲突，追加 owner 前缀（如 `xxx-my-tool`）
+
+---
+
+## 第三步：分析
+
+### 子 Agent 派发策略
+
+**每个项目必须派发到独立的子 agent。** 主 agent 只负责编排：筛选、派发、收集结果、生成 ref.json。
+
+**多项目时并行派发：**
+
+```
+对每个需要分析的项目:
+  task(category="quick", load_skills=["repo-clone-analyze"],
+       run_in_background=true,
+       prompt="分析位于 <repo-path> 的仓库。
+输出到：<output-dir>。
+ref.json 路径：<ref-json-path>。
+
+执行以下步骤：
+1. 初步侦察：阅读 README、依赖文件、Dockerfile、顶层目录结构、CI 配置
+2. 深度分析：阅读每个主要模块的源代码，识别用途、技术栈、依赖、架构、入口点
+3. 按 overview 模板写入 <output-dir>/overview.md
+4. 按 index schema 写入 <output-dir>/index.json（所有路径使用绝对路径）
+5. 合并到 ref.json（使用文件锁）
+
+overview.md 用中文撰写。
+index.json 中的 paths 和 key_files 的路径全部使用绝对路径。")
+```
+
+**单项目时直接分析，不派发子 agent。**
+
+### 3a. 初步侦察
+
+优先阅读以下文件建立初步认知：
+
+1. `README.md` / `README.rst` / docs 目录
+2. `package.json` / `requirements.txt` / `pyproject.toml` / `go.mod` / `Cargo.toml` / `pom.xml`
+3. `docker-compose.yml` / `Dockerfile` / `Makefile`
+4. 顶层目录结构
+5. CI/CD 配置（`.github/workflows/`、`.gitlab-ci.yml`）
+
+### 3b. 深度分析
+
+对每个主要模块/目录，阅读关键源代码文件，识别：
+
+- **用途**：该模块做什么
+- **技术与依赖**：使用的框架、库、协议
+- **架构模式**：MVC、微服务、事件驱动、插件系统等
+- **入口点**：主文件、API 路由、CLI 命令
+
+---
+
+## 第四步：输出
+
+### 4a. overview.md（每个项目一份）
+
+路径：`.specops/ref/<项目名>/overview.md`
+
+```markdown
+# <项目名称>
+
+## 项目概述
+<!-- 1-2 段：项目是什么，主要用途 -->
+
+## 技术栈
+
+| 类别 | 技术 |
+|------|------|
+| 语言 | Python 3.10+ |
+| 框架 | FastAPI |
+| 数据库 | PostgreSQL, Redis |
+
+## 架构
+<!-- 高层架构描述、数据流 -->
+
+## 核心模块
+
+### <模块名称>
+- **路径**：`src/module/`
+- **用途**：...
+- **关键技术**：...
+- **依赖**：...
+- **关键文件**：
+  - `file.py` - 描述
+
+## API / 接口
+<!-- REST 端点、CLI 命令、gRPC 服务（如适用） -->
+
+## 构建与部署
+<!-- 如何构建、测试、部署 -->
+
+## 对我们项目的参考价值
+<!-- 这个项目的哪些实现方式值得借鉴 -->
+```
+
+### 4b. index.json（每个项目一份）
+
+路径：`.specops/ref/<项目名>/index.json`
+
+将每个功能/模块映射到对应的代码路径。**所有路径必须使用绝对路径**，支持 glob 模式：
+
+```json
+{
+  "project": "<项目名>",
+  "repo_url": "<github-url>",
+  "analyzed_at": "<ISO-8601 时间戳>",
+  "modules": [
+    {
+      "name": "RAG 流水线",
+      "description": "基于检索增强生成的文档问答",
+      "paths": ["/abs/path/to/.specops/ref/ragflow/rag/**", "/abs/path/to/.specops/ref/ragflow/api/ragflow.py"],
+      "tech": ["LangChain", "Elasticsearch", "Python"],
+      "dependencies": ["elasticsearch", "langchain", "tiktoken"],
+      "key_files": {
+        "/abs/path/to/.specops/ref/ragflow/rag/pipeline.py": "RAG 主编排逻辑",
+        "/abs/path/to/.specops/ref/ragflow/rag/retriever.py": "向量存储文档检索"
+      }
+    }
+  ]
+}
+```
+
+### 4c. ref.json（全局合并索引）
+
+路径：`.specops/ref/ref.json`
+
+ref.json 是所有项目的**功能级**扁平索引，不按项目区分。`keyset` 是功能名称的数组，用于查重。每个功能名称直接作为顶层 key。
+
+**格式：**
+
+```json
+{
+  "keyset": ["RAG 流水线", "文档解析", "状态机引擎", "CLI 命令解析"],
+  "RAG 流水线": {
+    "project": "ragflow",
+    "description": "基于检索增强生成的文档问答",
+    "paths": ["/abs/path/.specops/ref/ragflow/rag/**"],
+    "tech": ["LangChain", "Elasticsearch", "Python"],
+    "dependencies": ["elasticsearch", "langchain", "tiktoken"],
+    "key_files": {
+      "/abs/path/.specops/ref/ragflow/rag/pipeline.py": "RAG 主编排逻辑",
+      "/abs/path/.specops/ref/ragflow/rag/retriever.py": "向量存储文档检索"
+    }
+  },
+  "文档解析": {
+    "project": "ragflow",
+    "description": "解析 PDF、DOCX、图片为结构化文本",
+    "paths": ["/abs/path/.specops/ref/ragflow/deepdoc/**"],
+    "tech": ["OCR", "pdfplumber", "Python"],
+    "dependencies": ["pdfplumber", "tesseract", "pillow"],
+    "key_files": {
+      "/abs/path/.specops/ref/ragflow/deepdoc/parser.py": "统一解析接口"
+    }
+  }
+}
+```
+
+---
+
+## 第五步：合并到 ref.json
+
+每个子 agent 写完 `index.json` 后，**立即**合并到 `ref.json`。不等主 agent 统一收集。
+
+### 文件锁机制
+
+多个子 agent 可能并发写入 `ref.json`，必须使用文件锁防止数据丢失。锁文件路径为 `ref.json.lock`（与 `ref.json` 同目录）。
+
+```bash
+# 获取锁（等待直到获取成功，超时 30 秒）
+while ! mkdir "<ref-json-path>.lock" 2>/dev/null; do sleep 1; done
+
+# ... 读取、合并、写回 ref.json ...
+
+# 释放锁
+rmdir "<ref-json-path>.lock"
+```
+
+使用 `mkdir` 作为原子锁操作（目录创建是原子的）。子 agent 在读取 `ref.json` 前获取锁，写回后释放锁。如果异常退出未释放锁，主 agent 在所有子 agent 完成后清理残留锁文件。
+
+### 合并流程（在锁保护下）
+
+**核心原则：只追加，不删除、不覆盖已有内容。**
+
+1. 获取文件锁
+2. 读取 `ref.json` 的**完整内容**（如不存在则创建 `{"keyset": []}`）
+3. 遍历当前项目 `index.json` 中的每个 module
+4. 取 module 的 `name`（即功能名称），检查 `keyset` 数组中是否已存在
+5. 如果已存在：在功能名后追加序号（如「RAG 流水线 2」「RAG 流水线 3」），将新名称追加到 `keyset`，并以新名称为 key 写入条目
+6. 如果不存在：将功能名称追加到 `keyset`，并新增顶层对象
+7. 将**完整的** JSON（包含所有已有条目 + 新追加条目）写回 `ref.json`
+8. 释放文件锁
+
+### 去重规则
+
+- `keyset` 是功能名称的数组，合并前逐个查询是否重复
+- 重名时追加序号：「功能名 2」「功能名 3」...
+- 序号从 2 开始，原始条目不带序号
+- 所有路径使用绝对路径
+
+---
+
+## 第六步：注入
+
+将 ref.json 路径注入到项目规范文件，使后续流程可以引用分析结果。
+
+**检测顺序**（依次检查，使用第一个找到的）：
+
+1. `.specops/REQUIREMENTS.md`
+2. `CLAUDE.md`（项目根目录）
+3. `AGENT.md`（项目根目录）
+
+**追加内容** —— 在规范文件末尾添加引用部分（如果不存在）：
+
+```markdown
+## 参考仓库
+
+分析索引：`<.specops/ref/ref.json 的绝对路径>`
+```
+
+如果该部分已存在，更新路径而不重复添加。
+
+**跳过条件**：如果没有找到任何规范文件，不要创建新文件。注入步骤可跳过（因为 demand-analysis 编排层会在 PHASE 7 合成时引用 ref.json）。
+
+---
+
+## 输出目录结构
+
+```
+.specops/
+└── ref/
+    ├── ref.json                          # 全局功能级扁平索引
+    ├── <project-a>/
+    │   ├── overview.md                   # 项目概览（中文）
+    │   ├── index.json                    # 功能-代码索引
+    │   └── <源码文件...>                  # git clone --depth 1 的内容
+    └── <project-b>/
+        ├── overview.md
+        ├── index.json
+        └── <源码文件...>
+```
+
+---
+
+## 注意事项
+
+- **每个项目一个子 agent**：多项目时不要在主 agent 中串行分析，必须并行派发
+- **深度阅读**：子 agent 必须阅读实际源代码，不能只看 README。核心价值在于将功能映射到具体文件
+- **绝对路径**：`index.json` 和 `ref.json` 中所有路径必须使用绝对路径，支持 glob 模式
+- **按功能名去重**：`ref.json` 以功能名称为 key，合并前先查询 `keyset` 数组是否已有该功能名
+- **只追加不覆盖**：`ref.json` 已有的功能条目必须完整保留，新功能只在末尾追加
+- **中文输出**：overview.md 用中文撰写，index.json 中的 name 和 description 用中文
+- **浅克隆**：使用 `--depth 1` 减少磁盘占用和克隆时间
+- **排除基础库**：严格执行排除列表，不要 Clone 通用基础库
+
+---
+
+## 反模式
+
+| 违规行为 | 严重性 |
+|---------|--------|
+| Clone 了排除列表中的基础框架/工具库 | **严重** — 浪费时间和磁盘 |
+| 不阅读源码只看 README 就生成 index.json | **严重** — 核心价值丧失 |
+| ref.json 覆盖了已有条目 | **严重** — 必须只追加 |
+| 并发写入 ref.json 不加锁 | 高 — 数据丢失风险 |
+| index.json 使用相对路径 | 高 — 后续引用会失败 |
+| 多项目串行分析不派发子 agent | 中 — 效率低下 |
+| overview.md 不是中文 | 中 |
+| 不生成 Clone 清单就直接 Clone | 中 — 缺少筛选过程 |

package/.opencode/skills/requesting-code-review/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: requesting-code-review
+description: 完成任务、实现主要功能或合并前使用，验证工作是否满足需求
+---
+
+# 请求代码审查
+
+派发 specops:code-reviewer 子 agent，在问题扩散前捕获它们。
+
+**核心原则：** 早审查，勤审查。
+
+## 何时请求审查
+
+**必须：**
+- 子 agent 驱动开发中每个任务完成后
+- 完成主要功能后
+- 合并到 main 之前
+
+**可选但有价值：**
+- 卡住时（换个视角）
+- 重构前（基线检查）
+- 修复复杂 bug 后
+
+## 如何请求
+
+**1. 获取 git SHA：**
+```bash
+BASE_SHA=$(git rev-parse HEAD~1)  # 或 origin/main
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+**2. 派发 code-reviewer 子 agent：**
+
+使用 task() 工具，类型为 specops:code-reviewer，填写 `code-reviewer.md` 中的模板
+
+**占位符：**
+- `{WHAT_WAS_IMPLEMENTED}` - 你刚构建了什么
+- `{PLAN_OR_REQUIREMENTS}` - 应该做什么
+- `{BASE_SHA}` - 起始提交
+- `{HEAD_SHA}` - 结束提交
+- `{DESCRIPTION}` - 简要摘要
+
+**3. 处理反馈：**
+- 立即修复严重问题
+- 继续之前修复重要问题
+- 记录次要问题留待后续
+- 如果审查者有误，用理由反驳
+
+## 示例
+
+```
+[刚完成任务 2：添加验证函数]
+
+你：让我在继续之前请求代码审查。
+
+BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
+HEAD_SHA=$(git rev-parse HEAD)
+
+[派发 specops:code-reviewer 子 agent]
+  WHAT_WAS_IMPLEMENTED: 会话索引的验证和修复函数
+  PLAN_OR_REQUIREMENTS: docs/plans/deployment-plan.md 中的任务 2
+  BASE_SHA: a7981ec
+  HEAD_SHA: 3df7661
+  DESCRIPTION: 添加了 verifyIndex() 和 repairIndex()，支持 4 种问题类型
+
+[子 agent 返回]：
+  优点：架构清晰，测试真实
+  问题：
+    重要：缺少进度指示器
+    次要：魔法数字（100）用于报告间隔
+  评估：可以继续
+
+你：[修复进度指示器]
+[继续任务 3]
+```
+
+## 与工作流的集成
+
+**子 Agent 驱动开发：**
+- 每个任务后审查
+- 在问题叠加前捕获
+- 进入下一个任务前修复
+
+**执行计划：**
+- 每批（3 个任务）后审查
+- 获取反馈，应用，继续
+
+**临时开发：**
+- 合并前审查
+- 卡住时审查
+
+## 红线
+
+**绝对不要：**
+- 因为"很简单"就跳过审查
+- 忽略严重问题
+- 带着未修复的重要问题继续
+- 对有效的技术反馈争辩
+
+**如果审查者有误：**
+- 用技术理由反驳
+- 展示证明其可用的代码/测试
+- 请求澄清
+
+参见模板：requesting-code-review/code-reviewer.md

package/.opencode/skills/requesting-code-review/code-reviewer.md

@@ -0,0 +1,146 @@
+# 代码审查 Agent
+
+你正在审查代码变更的生产就绪性。
+
+**你的任务：**
+1. 审查 {WHAT_WAS_IMPLEMENTED}
+2. 对照 {PLAN_OR_REQUIREMENTS}
+3. 检查代码质量、架构、测试
+4. 按严重程度分类问题
+5. 评估生产就绪性
+
+## 实现内容
+
+{DESCRIPTION}
+
+## 需求/计划
+
+{PLAN_REFERENCE}
+
+## 审查的 Git 范围
+
+**基准：** {BASE_SHA}
+**当前：** {HEAD_SHA}
+
+```bash
+git diff --stat {BASE_SHA}..{HEAD_SHA}
+git diff {BASE_SHA}..{HEAD_SHA}
+```
+
+## 审查清单
+
+**代码质量：**
+- 关注点分离是否清晰？
+- 错误处理是否恰当？
+- 类型安全（如适用）？
+- 是否遵循 DRY 原则？
+- 边界情况是否处理？
+
+**架构：**
+- 设计决策是否合理？
+- 是否考虑了可扩展性？
+- 性能影响？
+- 安全顾虑？
+
+**测试：**
+- 测试是否真正测试了逻辑（而非 mock）？
+- 边界情况是否覆盖？
+- 需要时是否有集成测试？
+- 所有测试是否通过？
+
+**需求：**
+- 是否满足计划中的所有需求？
+- 实现是否符合规格？
+- 是否有范围蔓延？
+- 破坏性变更是否有文档？
+
+**生产就绪性：**
+- 迁移策略（如有 schema 变更）？
+- 是否考虑了向后兼容？
+- 文档是否完整？
+- 是否有明显 bug？
+
+## 输出格式
+
+### 优点
+[哪些做得好？要具体。]
+
+### 问题
+
+#### 严重（必须修复）
+[Bug、安全问题、数据丢失风险、功能损坏]
+
+#### 重要（应该修复）
+[架构问题、缺失功能、错误处理不当、测试缺口]
+
+#### 次要（锦上添花）
+[代码风格、优化机会、文档改进]
+
+**每个问题包含：**
+- 文件:行号 引用
+- 什么问题
+- 为什么重要
+- 如何修复（如果不明显）
+
+### 建议
+[代码质量、架构或流程的改进建议]
+
+### 评估
+
+**可以合并吗？** [是/否/修复后可以]
+
+**理由：** [1-2 句技术评估]
+
+## 关键规则
+
+**要：**
+- 按实际严重程度分类（不是所有东西都是严重的）
+- 要具体（文件:行号，不要含糊）
+- 解释问题为什么重要
+- 肯定优点
+- 给出明确结论
+
+**不要：**
+- 没检查就说"看起来不错"
+- 把小问题标为严重
+- 对没审查的代码给反馈
+- 含糊其辞（"改进错误处理"）
+- 回避给出明确结论
+
+## 输出示例
+
+```
+### 优点
+- 数据库 schema 干净，迁移规范（db.ts:15-42）
+- 测试覆盖全面（18 个测试，所有边界情况）
+- 错误处理好，有降级方案（summarizer.ts:85-92）
+
+### 问题
+
+#### 重要
+1. **CLI 包装器缺少帮助文本**
+   - 文件：index-conversations:1-31
+   - 问题：没有 --help 标志，用户无法发现 --concurrency
+   - 修复：添加 --help 分支，附带使用示例
+
+2. **缺少日期验证**
+   - 文件：search.ts:25-27
+   - 问题：无效日期静默返回空结果
+   - 修复：验证 ISO 格式，抛出错误并附带示例
+
+#### 次要
+1. **进度指示器**
+   - 文件：indexer.ts:130
+   - 问题：长时间操作没有"X / Y"计数器
+   - 影响：用户不知道要等多久
+
+### 建议
+- 添加进度报告以改善用户体验
+- 考虑用配置文件管理排除项目（可移植性）
+
+### 评估
+
+**可以合并：修复后可以**
+
+**理由：** 核心实现扎实，架构和测试都好。重要问题（帮助文本、日期验证）容易修复，不影响核心功能。
+```