adspecs 0.1.12

package/skills/adspecs-prd/SKILL.md

@@ -0,0 +1,404 @@
+---
+name: "adspecs-prd"
+description: "根据自然语言功能描述创建或更新功能规格说明书。"
+argument-hint: "描述你想要生成 spec 的功能"
+compatibility: "需要 adspecs 项目结构及 docs/ 目录"
+metadata:
+  author: "Qingwen Chen"
+user-invocable: true
+disable-model-invocation: false
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+**必须** 在继续之前考虑用户输入（如果非空）。
+
+## 路径配置加载
+
+在开始执行之前，先确定输出目录：
+
+1. 检查项目根目录是否存在 `.adspecs/paths.json`
+2. 如果存在，读取其中的 `paths` 对象，提取本技能需要的配置键
+3. 如果不存在或配置键缺失，使用下方表格中的默认值
+
+| 配置键    | 默认值        | 用途                          |
+| --------- | ------------- | ----------------------------- |
+| `prd_dir` | `docs/20-prd` | PRD（产品需求说明书）输出目录 |
+
+将解析后的路径记为 `PRD_DIR`，后续步骤中引用此变量而非硬编码路径。
+
+## 执行前检查
+
+**检查扩展钩子（编写规格说明前）**:
+
+- 检查项目根目录是否存在 `.adspecs/extensions.yml`。
+- 如果存在，读取它并查找 `hooks.before_adspecs` 下的条目。
+- 如果 YAML 无法解析或无效，静默跳过钩子检查并继续正常执行。
+- 过滤掉 `enabled` 明确为 `false` 的钩子。没有 `enabled` 字段的钩子默认视为启用。
+- 对于每个剩余的钩子，**不要** 尝试解释或评估钩子的 `condition` 表达式：
+  - 如果钩子没有 `condition` 字段，或为空/null，视为可执行。
+  - 如果钩子定义了非空的 `condition`，跳过该钩子，将条件评估留给 HookExecutor 实现。
+- 从钩子命令名构造斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如：`adspecs.git.commit` → `/adspecs-git-commit`。
+- 对于每个可执行钩子，根据其 `optional` 标志输出以下内容：
+  - **可选钩子** (`optional: true`):
+
+    ```
+    ## 扩展钩子
+
+    **可选前置钩子**: {extension}
+    命令: `/{command}`
+    描述: {description}
+
+    提示: {prompt}
+    执行: `/{command}`
+    ```
+
+  - **必选钩子** (`optional: false`):
+
+    ```
+    ## 扩展钩子
+
+    **自动前置钩子**: {extension}
+    执行: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    等待钩子命令结果后再继续执行 Outline。
+    ```
+
+- 如果没有注册钩子或 `.adspecs/extensions.yml` 不存在，静默跳过。
+
+## 概述
+
+用户在触发消息中 `/adspecs-prd` 之后输入的文本**就是**功能描述。假设你在本次对话中始终可以获取到它，即使 `$ARGUMENTS` 字面上出现在下方。除非用户提供了空命令，否则不要要求用户重复输入。
+
+根据功能描述，执行以下操作：
+
+1. **生成简洁的短名称**（2-4 个词）用于功能：
+   - 分析功能描述并提取最有意义的关键词
+   - 创建一个 2-4 个词的短名称，抓住功能的本质
+   - 尽可能使用动词-名词格式（如 "add-user-auth"、"fix-payment-bug"）
+   - 保留技术术语和缩写（OAuth2、API、JWT 等）
+   - 保持简洁但足够描述性，以便一眼就能理解功能
+   - 示例：
+     - "我想添加用户认证" → "user-auth"
+     - "为 API 实现 OAuth2 集成" → "oauth2-api-integration"
+     - "为分析功能创建仪表盘" → "analytics-dashboard"
+     - "修复支付处理超时 bug" → "fix-payment-timeout"
+
+2. **识别二级模块**：
+   - 扫描 `{ARCH_DIR}/` 目录，查找 `01-*_business_scenarios.md` 或 `01-*_business_architecture.md` 文件（业务功能架构文档，两者命名均可能出现）
+   - 如果找到，读取文件内容，重点关注：
+     - **二、系统模块总览** → **2.2 子模块清单**：获取所有主模块（P00~P{N}）及其下属的二级模块（子模块，编号格式如 P03-01、P03-02、SYS-01 等)
+     - **三、各模块业务场景详述**：获取每个模块的业务场景描述（S-P{XX}-{YY} 系列）
+   - 将需求描述内容与各二级模块的名称、说明、业务场景进行语义匹配，确定需求最匹配的**二级模块编号**（如 P03-02）
+   - 匹配规则：
+     1. **精确匹配**：需求描述中明确提到某个子模块名称或编号 → 直接采用
+     2. **场景匹配**：需求描述的业务场景与某个模块下的场景（S-P{XX}-{YY}）高度吻合 → 采用该子模块编号
+     3. **语义匹配**：需求描述的核心功能与某个子模块的"说明"字段语义相近 → 采用该子模块编号
+     4. **无法匹配**：需求内容与任何二级模块都不匹配 → 使用 AskUserQuestion 让用户从二级模块列表中选择，或标记为"新模块"
+   - 将匹配到的二级模块编号记为 `MODULE_ID`（如 `P03-02`），对应的主模块编号记为 `PARENT_MODULE`（如 `P03`)
+   - 如果架构文档不存在，跳过此步骤，`MODULE_ID` 留空，输出目录不包含模块子目录
+
+3. **创建分支**（可选，通过钩子）：
+
+   如果上述执行前检查中的 `before_adspecs` 钩子运行成功，它将已创建/切换到 git 分支并输出包含 `BRANCH_NAME` 和 `FEATURE_NUM` 的 JSON。记录这些值以供参考，但分支名称**不**决定 spec 目录名称。
+
+   如果用户明确提供了 `GIT_BRANCH_NAME`，将其传递给钩子，以便分支脚本使用该确切值作为分支名称（绕过所有前缀/后缀生成）。
+
+4. **创建 spec 功能目录**:
+
+   Spec 默认存储在 `{PRD_DIR}` 目录下，除非用户明确提供了 `ADSPECS_FEATURE_DIRECTORY`。
+
+   **`ADSPECS_FEATURE_DIRECTORY` 的解析顺序**:
+   1. 如果用户明确提供了 `ADSPECS_FEATURE_DIRECTORY`（例如通过环境变量、参数或配置），直接使用它
+   2. 否则，在 `docs/` 下自动生成：
+   - 将 `.adspecs/templates/02-产品需求说明书模板.md` 复制到 `$ADSPECS_FEATURE_DIRECTORY/产品需求说明书.md` 作为起点
+   - 设置 `SPEC_FILE` 为 `$ADSPECS_FEATURE_DIRECTORY/产品需求说明书.md`
+   - 输出根目录：`{PRD_DIR}/`（由路径配置加载阶段解析，默认 `docs/20-prd/`）
+   - 如果 `MODULE_ID` 已识别（非空）：
+     - 输出子目录：`{PRD_DIR}/{MODULE_ID}/`（如 `docs/20-prd/M03-02/`）
+     - 如果子目录不存在，自动创建
+   - 如果 `MODULE_ID` 为空（架构文档不存在或无法匹配）：
+     - 直接使用 `{PRD_DIR}/<prefix>-<short-name>` 作为输出目录（例如 `003-user-auth` 或 `20260319-143022-user-auth`）
+   - 输出文件名：基于需求描述生成简洁名称，格式 `{MODULE_ID}_{short-name}_产品需求说明书.md`
+   - 完整输出路径示例：
+     - 有模块：`docs/20-prd/M03-02/{MODULE_ID}_{short-name}_产品需求说明书.md`
+     - 无模块：`docs/20-prd/{short-name}_产品需求说明书.md`
+   - 如果目录下已有同名文件，询问用户是覆盖还是重命名,还是新增版本号格式如下：
+     - 有模块：`docs/20-prd/M03-02/{MODULE_ID}_{short-name}_产品需求说明书_v{version}.md`
+     - 无模块：`docs/20-prd/{short-name}_产品需求说明书_v{version}.md`
+   - 将解析后的路径持久化到 `.adspecs/feature.json`（多功能注册表格式）：
+
+     ```json
+     {
+       "active": "<resolved feature dir>",
+       "prd": [
+         {
+           "id": "<功能ID>",
+           "directory": "<resolved feature dir>",
+           "filename": "<resolved feature filename>",
+           "name": "<功能名称>",
+           "status": "drafting",
+           "created": "<DATE>"
+         }
+       ]
+     }
+     ```
+
+     **操作方式**:
+     1. 读取现有的 `.adspecs/feature.json`（如存在）
+     2. 将新功能追加到 `prd` 数组（若 directory 已存在则跳过，避免重复）
+     3. 将 `active` 更新为当前功能目录
+     4. 写入文件（使用 2-space 缩进以保证可读性）
+
+     写入实际的解析后目录路径值（例如 `{PRD_DIR}/003-user-auth`），而非字面字符串 `ADSPECS_FEATURE_DIRECTORY`。
+     这允许下游命令（`/adspecs-plan`、`/adspecs-clarify` 等）通过 `active` 字段定位当前功能目录，而无需依赖 git 分支名称约定。
+
+     **注意**: 不要在功能目录下创建 `feature.json` 文件——所有功能追踪统一在 `.adspecs/feature.json` 中管理。
+
+   **重要**:
+   - 每次 `/adspecs-prd` 调用只能创建一个功能
+   - spec 目录名称和 git 分支名称是相互独立的 — 它们可能相同但由用户选择
+   - spec 目录和文件始终由此命令创建，而非由钩子创建
+
+5. 加载 `.adspecs/templates/02-产品需求说明书模板.md` 以了解所需的结构。
+
+6. 遵循以下执行流程：
+   1. 从参数中解析用户描述
+      如果为空：错误 "No feature description provided"
+   2. 提取描述中的关键概念
+      识别：角色、操作、数据、约束
+   3. 对于不明确的方面：
+      - 基于上下文和行业标准做出合理的推断
+      - 仅在以下情况标记为 [NEEDS CLARIFICATION: 具体问题]：
+        - 该选择显著影响功能范围或用户体验
+        - 存在多种合理的解释且含义不同
+        - 没有合理的默认值
+      - **限制：最多 3 个 [NEEDS CLARIFICATION] 标记**
+      - 按影响排序澄清优先级：范围 > 安全/隐私 > 用户体验 > 技术细节
+   4. 填写用户场景与测试部分
+      如果没有清晰的用户流程：错误 "Cannot determine user scenarios"
+   5. 生成功能需求
+      每个需求必须是可测试的
+      对未明确的细节使用合理的默认值（在假设部分记录假设）
+   6. 定义成功标准
+      创建可度量、与技术无关的成果
+      包括量化指标（时间、性能、容量）和定性测量（用户满意度、任务完成率）
+      每个标准必须可在不知道实现细节的情况下验证
+   7. 识别关键实体（如果涉及数据）
+   8. 返回：成功（spec 可进入计划阶段）
+
+7. 使用模板结构将规格说明书写入 `SPEC_FILE`，用从功能描述（参数）派生的具体细节替换占位符，同时保留章节顺序和标题。
+
+8. **规格说明书质量验证**: 在编写初始 spec 后，根据质量标准对其进行验证：
+
+   a. **创建 Spec 质量检查清单**: 在 `ADSPECS_FEATURE_DIRECTORY/checklists/prd_checklist.md` 生成检查清单文件，使用检查清单模板结构，包含以下验证项：
+
+   ```markdown
+   # 规格说明书质量检查清单：[功能名称]
+
+   **目的**: 在进入计划阶段之前验证规格说明书的完整性和质量
+   **创建日期**: [DATE]
+   **功能**: [链接到 spec.md]
+
+   ## 内容质量
+
+   - [ ] 无实现细节（语言、框架、API）
+   - [ ] 聚焦于用户价值和业务需求
+   - [ ] 为非技术利益相关者编写
+   - [ ] 所有必填章节已完成
+
+   ## 需求完整性
+
+   - [ ] 无 [NEEDS CLARIFICATION] 标记残留
+   - [ ] 需求可测试且无歧义
+   - [ ] 成功标准可度量
+   - [ ] 成功标准与技术无关（无实现细节）
+   - [ ] 所有验收场景已定义
+   - [ ] 边界情况已识别
+   - [ ] 范围界限清晰
+   - [ ] 依赖和假设已识别
+   - [ ] 一级模块名称和编号是否与 `docs\10-architecture\01-*_business_scenarios.md` 中对应的模块对齐一致性检查
+   - [ ] 二级菜单/模块划分合理性检查
+
+   ## 功能就绪
+
+   - [ ] 所有功能需求有清晰的验收标准
+   - [ ] 用户场景覆盖主要流程
+   - [ ] 功能满足成功标准中定义的可度量成果
+   - [ ] 无实现细节泄露到规格说明书中
+
+   ## 备注
+
+   - 标记为不完整的项需要在 `/adspecs-clarify` 或 `/adspecs-plan` 之前更新 spec
+   ```
+
+   b. **运行验证检查**: 对照每个检查清单项审查 spec：
+   - 对于每一项，确定其通过或失败
+   - 记录发现的具体问题（引用相关 spec 章节）
+
+   c. **处理验证结果**:
+   - **如果所有项通过**: 将检查清单标记为完成，并继续必选执行后钩子部分
+
+   - **如果有项失败（不包含 [NEEDS CLARIFICATION]）**:
+     1. 列出失败的项和具体问题
+     2. 更新 spec 以处理每个问题
+     3. 重新运行验证直到所有项通过（最多 3 次迭代）
+     4. 如果 3 次迭代后仍然失败，在检查清单备注中记录剩余问题并警告用户
+
+   - **如果 [NEEDS CLARIFICATION] 标记残留**:
+     1. 从 spec 中提取所有 [NEEDS CLARIFICATION: ...] 标记
+     2. **限制检查**: 如果超过 3 个标记，仅保留 3 个最关键的问题（按范围/安全/UX 影响），对其余做出合理推断
+     3. 对于每个需要澄清的问题（最多 3 个），以此格式向用户呈现选项：
+
+        ```markdown
+        ## 问题 [N]：[主题]
+
+        **上下文**: [引用相关 spec 章节]
+
+        **需要明确的内容**: [NEEDS CLARIFICATION 标记中的具体问题]
+
+        **建议答案**:
+
+        | 选项   | 答案             | 含义                     |
+        | ------ | ---------------- | ------------------------ |
+        | A      | [第一个建议答案] | [这对功能意味着什么]     |
+        | B      | [第二个建议答案] | [这对功能意味着什么]     |
+        | C      | [第三个建议答案] | [这对功能意味着什么]     |
+        | 自定义 | 提供你自己的答案 | [说明如何提供自定义输入] |
+
+        **你的选择**: _[等待用户回复]_
+        ```
+
+     4. **关键 - 表格格式**: 确保 markdown 表格格式正确：
+        - 使用一致的间距，管道对齐
+        - 每个单元格的内容周围应有空格：`| 内容 |` 而非 `|内容|`
+        - 标题分隔符必须至少有 3 个破折号：`|--------|`
+        - 测试表格在 markdown 预览中是否正确渲染
+     5. 按顺序编号问题（Q1、Q2、Q3 - 最多 3 个）
+     6. 在等待回复之前一起呈现所有问题
+     7. 等待用户对所有问题的选择回复（例如："Q1: A, Q2: 自定义 - [详情], Q3: B"）
+     8. 将 spec 中的每个 [NEEDS CLARIFICATION] 标记替换为用户选择或提供的答案来更新 spec
+     9. 在所有澄清解决后重新运行验证
+
+   d. **更新检查清单**: 在每次验证迭代后，以当前的通过/失败状态更新检查清单文件
+
+## 必选执行后钩子
+
+**必须在向用户报告完成之前完成本节。**
+
+检查项目根目录是否存在 `.adspecs/extensions.yml`。
+
+- 如果不存在，或 `hooks.after_adspecs` 下没有注册钩子，跳到完成报告。
+- 如果存在，读取它并查找 `hooks.after_adspecs` 下的条目。
+- 如果 YAML 无法解析或无效，静默跳过钩子检查并继续完成报告。
+- 过滤掉 `enabled` 明确为 `false` 的钩子。没有 `enabled` 字段的钩子默认视为启用。
+- 对于每个剩余的钩子，**不要** 尝试解释或评估钩子的 `condition` 表达式：
+  - 如果钩子没有 `condition` 字段，或为空/null，视为可执行。
+  - 如果钩子定义了非空的 `condition`，跳过该钩子，将条件评估留给 HookExecutor 实现。
+- 从钩子命令名构造斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如：`adspecs.git.commit` → `/adspecs-git-commit`。
+- 对于每个可执行钩子，根据其 `optional` 标志输出以下内容：
+  - **必选钩子** (`optional: false`) — **必须为每个必选钩子发出 `EXECUTE_COMMAND:`**：
+
+    ```
+    ## 扩展钩子
+
+    **自动钩子**: {extension}
+    执行: `/{command}`
+    EXECUTE_COMMAND: {command}
+    ```
+
+  - **可选钩子** (`optional: true`):
+
+    ```
+    ## 扩展钩子
+
+    **可选钩子**: {extension}
+    命令: `/{command}`
+    描述: {description}
+
+    提示: {prompt}
+    执行: `/{command}`
+    ```
+
+## 完成报告
+
+向用户报告完成情况，包含：
+
+- `ADSPECS_FEATURE_DIRECTORY` — 功能目录路径
+- `SPEC_FILE` — spec 文件路径
+- 检查清单结果摘要
+- 是否准备好进入下一阶段（`/adspecs-clarify` 或 `/adspecs-plan`）
+
+**注意:** 分支创建由 `before_adspecs` 钩子（git 扩展）处理。Spec 目录和文件创建始终由此核心命令处理。
+
+## 快速指南
+
+- 聚焦于用户需要**什么**以及**为什么**。
+- 避免描述如何实现（无技术栈、API、代码结构）。
+- 为业务利益相关者编写，而非为开发者。
+- 不要创建嵌入在 spec 中的任何检查清单。那将由单独的命令完成。
+
+### 章节要求
+
+- **必填章节**: 每个功能必须完成
+- **可选章节**: 仅在与功能相关时包含
+- 当某个章节不适用时，完全删除它（不要留下 "N/A"）
+
+### AI 生成指南
+
+从用户提示创建此 spec 时：
+
+1. **做出合理推断**: 使用上下文、行业标准和常见模式来填补空白
+2. **记录假设**: 在假设部分记录合理的默认值
+3. **限制澄清标记**: 最多 3 个 [NEEDS CLARIFICATION] 标记 - 仅用于以下关键决策：
+   - 显著影响功能范围或用户体验
+   - 存在多种合理的解释且含义不同
+   - 缺乏任何合理的默认值
+4. **按影响排序澄清优先级**: 范围 > 安全/隐私 > 用户体验 > 技术细节
+5. **像测试人员一样思考**: 每个模糊的需求都应该不通过"可测试且无歧义"的检查清单项
+6. **需要澄清的常见领域**（仅当没有合理默认值时）:
+   - 功能范围和边界（包含/排除特定用例）
+   - 用户类型和权限（如果存在多种冲突的解释可能性）
+   - 安全/合规要求（当法律/财务影响显著时）
+
+**合理默认值示例**（不要询问以下内容）:
+
+- 数据保留：该领域的行业标准实践
+- 性能目标：除非有说明，否则为标准 Web/移动应用期望值
+- 错误处理：用户友好的消息及适当的回退处理
+- 认证方式：Web 应用的标准基于会话或 OAuth2
+- 集成模式：使用项目合适的模式（Web 服务用 REST/GraphQL，库用函数调用，工具用 CLI 参数等）
+
+### 成功标准指南
+
+成功标准必须：
+
+1. **可度量**: 包含具体的指标（时间、百分比、数量、比率）
+2. **技术无关**: 不提及框架、语言、数据库或工具
+3. **以用户为中心**: 从用户/业务角度描述成果，而非系统内部
+4. **可验证**: 无需知道实现细节即可测试/验证
+
+**好的示例**:
+
+- "用户可以在 3 分钟内完成结账"
+- "系统支持 10,000 个并发用户"
+- "95% 的搜索在 1 秒内返回结果"
+- "任务完成率提升 40%"
+
+**不好的示例**（聚焦于实现）:
+
+- "API 响应时间低于 200ms"（太技术化，用"用户能瞬间看到结果"替代）
+- "数据库可处理 1000 TPS"（实现细节，用面向用户的指标替代）
+- "React 组件渲染高效"（框架特定）
+- "Redis 缓存命中率高于 80%"（技术特定）
+
+## 完成标志
+
+- [ ] 规格说明书已写入 `SPEC_FILE` 并对照质量检查清单验证通过
+- [ ] 扩展钩子已根据上述必选执行后钩子规则分发或跳过
+- [ ] 完成报告已呈现给用户，包含功能目录、spec 文件路径和检查清单结果

package/skills/adspecs-requirement-research/02-/351/234/200/346/261/202/346/235/245/346/272/220/344/270/216/351/207/207/351/233/206/350/256/260/345/275/225.md

@@ -0,0 +1,85 @@
+# 02 — 需求来源与采集记录（引导版模板）
+
+---
+
+| 项 | 值 |
+|---|---|
+| 模块编号 | 【填写：如 M1-XXX，按项目自定义编号规则】 |
+| 模块名称 | 【填写：你的模块名称】 |
+| 版本 / 阶段 | v0.1 · Elicitation（需求采集） |
+| 追溯 | → 汇入 `03` Proposal → `04` PRD |
+
+---
+
+## S-01 会议纪要 — 【填写会议主题】
+
+> **引导提问**：你们最近一次讨论这个需求的会议是什么时候？参会了哪些角色？
+
+| 项 | 内容 |
+|---|---|
+| 时间 | 【填写：如 2026-04-08 14:00-16:00】 |
+| 地点 | 【填写：如 线上会议 / XX会议室】 |
+| 参会人员 | 【填写：如 张总监（业务部）、王经理（IT部）、李产品、陈开发】 |
+
+### 痛点记录
+
+> **引导提问**：用户目前最头疼的 2~3 个问题是什么？这些问题导致了什么后果（浪费时间？出错？效率低？）
+
+| 痛点 | 优先级 | 提出人 |
+|------|--------|--------|
+| 【填写：用户当前最大的痛点是什么？】 | P0 | 【提出人】 |
+| 【填写：第二个痛点】 | P0/P1 | 【提出人】 |
+| 【填写：第三个痛点】 | P1 | 【提出人】 |
+
+### 需求记录
+
+> **引导提问**：针对上面的痛点，用户期望系统能帮他做什么？列出 3~5 条核心需求。
+
+1. **【需求1名称】**：【一句话描述这个需求要实现什么能力】
+2. **【需求2名称】**：【一句话描述】
+3. **【需求3名称】**：【一句话描述】
+4. **【需求4名称】**：【一句话描述】
+
+### 下一步行动
+
+- ☐ 【负责人】完成【什么事】（【截止日期】）
+- ☐ 【负责人】完成【什么事】（【截止日期】）
+- ☐ 【负责人】完成【什么事】（【截止日期】）
+
+---
+
+## S-02 邮件 / 聊天沟通 — 【填写沟通主题】
+
+> **引导提问**：除了会议，有没有邮件、IM 消息等补充的需求说明？把关键信息摘录下来。
+
+| 项 | 内容 |
+|---|---|
+| 发件人 / 发起人 | 【填写】 |
+| 收件人 / 接收人 | 【填写】 |
+| 时间 | 【填写】 |
+
+**问题1 — 【问题标题】：** 【描述用户反馈的具体问题和期望】
+
+**问题2 — 【问题标题】：** 【描述用户反馈的具体问题和期望】
+
+---
+
+## S-03 用户访谈 — 【填写访谈对象角色】
+
+> **引导提问**：有没有做过用户访谈？最了解业务痛点的人是谁？他怎么描述自己的日常工作和困难？
+
+| 项 | 内容 |
+|---|---|
+| 访谈对象 | 【填写：姓名（角色）】 |
+| 访谈人 | 【填写】 |
+| 时间 | 【填写】 |
+| 方式 | 【填写：线上/线下】 |
+
+| 问题 | 回答要点 |
+|------|----------|
+| Q1：平时工作中最耗时的环节？ | 【填写】 |
+| Q2：最希望系统帮你解决什么问题？ | 【填写】 |
+| Q3：目前是怎么解决这个问题的？（现有方案） | 【填写】 |
+| Q4：对新系统有什么顾虑或要求？ | 【填写】 |
+
+**总结：** 【用 2~3 句话概括访谈核心发现】

package/skills/adspecs-requirement-research/SKILL.md

@@ -0,0 +1,184 @@
+# 需求来源与采集记录
+
+> **版本**: v6.0
+> **创建日期**: 2026-05-08
+> **修订日期**: 2026-05-31
+> **用途**: 基于 spec 文件和 git 历史，生成需求采集记录，建立需求可追溯性
+
+---
+
+## 定位
+
+本技能位于需求管理链最上游，记录**需求从哪来、为什么做、怎么演变**：
+
+```
+adspecs-requirement-research（从哪来）→ wspectodemand（做什么）→ adspecs-requirement-analysis（怎么拆）→ adspecs-systemdesign（怎么建）
+```
+
+## 任务
+
+读取用户指定的 spec 文件及其 git 提交历史，生成 **1 个文件**：
+
+- **需求采集记录**（`_research.md`）— 需求来源、业务背景、功能范围摘要、变更历史、下游文档追溯
+
+本技能**不生成**需求规格说明书、功能规格说明书、需求分析文档、系统设计文档。
+
+## 输入
+
+### 必读
+
+| 序号 | 文件                                    | 用途                                                     |
+| ---- | --------------------------------------- | -------------------------------------------------------- |
+| 1    | `docs/300-specs/{用户指定的 spec 文件}` | 提取需求编号、版本、功能范围、优先级、依赖关系、业务背景 |
+| 2    | `CLAUDE.md`                             | 确定所属业务域和模块                                     |
+
+### 必须执行
+
+| 序号 | 操作                                           | 用途                         |
+| ---- | ---------------------------------------------- | ---------------------------- |
+| 3    | `git log --oneline --follow -- {spec文件路径}` | 获取变更历史、提交人、时间线 |
+
+### 参考（按需）
+
+- `docs/02-prd/{对应模块}/` 下已有的 `_demand_spec.md` / `_func_spec.md` — 下游文档追溯
+- `docs/03-systemdesign/{对应模块}/` 下已有的 `_require-analysis.md` / `_system-design.md` — 设计文档追溯
+
+## 路径配置加载
+
+在开始执行之前，先确定输出目录：
+
+1. 检查项目根目录是否存在 `.adspecs/paths.json`
+2. 如果存在，读取其中的 `paths` 对象，提取本技能需要的配置键
+3. 如果不存在或配置键缺失，使用下方表格中的默认值
+
+| 配置键                | 默认值        | 用途                 |
+| --------------------- | ------------- | -------------------- |
+| `research_output_dir` | `docs/02-prd` | 需求采集记录输出目录 |
+
+将解析后的路径记为 `RESEARCH_OUTPUT_DIR`，后续步骤中引用此变量而非硬编码路径。
+
+## 工作流程
+
+### 步骤 1：读取 spec，提取元数据
+
+从 spec 文件中提取：
+
+- 需求编号和标题（如 P01-04 产品族与产品规格）
+- spec 版本号和修订日期
+- 所属模块和业务域
+- 优先级（P0/P1/P2/P3）
+- 需求背景和业务痛点（通常在 spec 开头的概述部分）
+- 功能范围（包含/不包含）
+- 跨模块依赖（上游/下游/外部系统）
+
+### 步骤 2：获取 git 变更历史
+
+执行 `git log --oneline --follow -- {spec文件路径}`，提取：
+
+- 首次创建时间和提交人
+- 最近 5 次提交的摘要
+- 版本演进节点（如 v1.0 → v2.0 的重大变更）
+
+如果 git 历史不可用（新文件/未提交），标注"暂无 git 历史"。
+
+### 步骤 3：扫描下游文档
+
+检查 `docs/02-prd/` 和 `docs/03-systemdesign/` 下是否已有该 spec 对应的下游文档：
+
+| 文档类型       | 命名规则                | 目录                           |
+| -------------- | ----------------------- | ------------------------------ |
+| 产品需求说明书 | `*_product_spec.md`     | `docs/02-prd/{模块}/`          |
+| 功能规格说明书 | `*_func_spec.md`        | `docs/02-prd/{模块}/`          |
+| 需求分析文档   | `*_require-analysis.md` | `docs/03-systemdesign/{模块}/` |
+| 系统设计文档   | `*_system-design.md`    | `docs/03-systemdesign/{模块}/` |
+| 建表 SQL       | `*_schema.sql`          | `docs/03-systemdesign/{模块}/` |
+| 数据字典 SQL   | `*_dictionary-menu.sql` | `docs/03-systemdesign/{模块}/` |
+
+记录每个文档的**存在状态**（已生成/未生成）和文件路径。
+
+### 步骤 4：生成需求采集记录
+
+按以下 5 部分结构生成：
+
+**§1 基本信息**：需求编号、标题、所属模块、优先级、spec 版本、创建日期、修订日期
+
+**§2 需求来源与背景**：
+
+- 需求来源类型（业务驱动/技术驱动/合规驱动/用户反馈 — 从 spec 内容推断）
+- 业务痛点（从 spec 的需求背景中提取原文摘要）
+- 业务目标（从 spec 的设计目标中提取）
+- 功能范围摘要（包含/不包含，精简为要点列表）
+
+**§3 变更历史**：
+
+- spec 版本演进表（版本号 + 日期 + 变更摘要）
+- git 提交记录（最近 5 次，含提交人、时间、commit message）
+- 如有重大版本变更，说明变更内容和原因
+
+**§4 下游文档追溯**：
+
+- 下游文档引用状态表（6 类文档的存在状态和路径）
+- 跨模块依赖关系（从 spec 提取的上游/下游/外部依赖）
+
+**§5 待补充项**：
+
+- 列出需要人工补充的信息（干系人、评审记录、优先级决策依据等）
+- 每项说明为什么需要补充、从哪里获取
+
+### 步骤 5：保存文件
+
+保存到 `{RESEARCH_OUTPUT_DIR}/{module-subdir}/` 目录。
+
+## 输出
+
+### 文件命名
+
+| 文件类型     | 命名规则                        | 示例                                |
+| ------------ | ------------------------------- | ----------------------------------- |
+| 需求采集记录 | `{spec名去掉_spec}_research.md` | `p01-04_product-family_research.md` |
+
+### 保存目录映射
+
+`{RESEARCH_OUTPUT_DIR}/{module-subdir}/`，按 spec 前缀确定子目录：
+
+| spec 前缀 | 子目录         | 说明       |
+| --------- | -------------- | ---------- |
+| `p01-*`   | `mdm/`         | 主数据管理 |
+| `p02-*`   | `process/`     | 工艺管理   |
+| `p03-*`   | `order/`       | 订单管理   |
+| `p04-*`   | `aps/`         | 排产管理   |
+| `p05-*`   | `wms/`         | 仓储管理   |
+| `p06-*`   | `mes/`         | 制造执行   |
+| `p07-*`   | `srm/`         | 供应商管理 |
+| `p08-*`   | `qms/`         | 质量管理   |
+| `p09-*`   | `logistics/`   | 物流管理   |
+| `p10-*`   | `iot/`         | 物联网平台 |
+| `p11-*`   | `trace/`       | 追溯管理   |
+| `p12-*`   | `system/`      | 系统管理   |
+| `p13-*`   | `bi/`          | 数据分析   |
+| `p14-*`   | `ai/`          | AI 智能    |
+| `p15-*`   | `wms/`         | WMS 扩展   |
+| 其他      | 按所属模块命名 |            |
+
+## 质量检查
+
+- [ ] §1 基本信息完整（编号、标题、模块、优先级、版本、日期）
+- [ ] §2 需求来源有明确类型标注（业务/技术/合规/用户）
+- [ ] §2 业务痛点和目标来自 spec 原文，非 AI 臆造
+- [ ] §3 变更历史包含 git 提交记录（或标注"暂无 git 历史"）
+- [ ] §4 下游文档追溯准确（已生成/未生成状态正确）
+- [ ] §4 跨模块依赖从 spec 提取，未遗漏
+- [ ] §5 待补充项具体，说明了从哪里获取
+- [ ] 推断信息有明确标注（如"基于 spec 内容推断"）
+
+## 约束
+
+- **仅生成需求采集记录**：不生成其他类型的文档或代码
+- **基于事实**：优先使用 spec 原文和 git 历史；推断信息必须标注"推断"
+- **不虚构干系人**：spec 中未提及的人名、会议、邮件不编造，放入 §5 待补充项
+- **不展开需求内容**：本技能记录元数据和追溯信息，不重复 spec 的功能细节
+
+## 触发关键词
+
+- `adspecs-requirement-research`
+- 在对话中指定，如：`使用 adspecs-requirement-research 处理 p01-04_product-family_spec.md`