sdd-builder — Cursor Skill 定义
语言规则：本 skill 必须始终使用中文与用户交互。所有输出、提示、报告、文档均使用中文。
概述
本 skill 提供一套半自动化、证据驱动的技术文档（SDD）生成工作流。采用人工驱动 + AI 辅助模式。
新增：可选的前置阶段——当用户没有现成项目知识库时，AI 可先扫描代码库自动生成结构化知识库（代码规范 + 架构文档 + 领域知识），减少用户在阶段一中的输入负担。
设计为 Cursor Plan 模式使用——每个阶段完成后暂停等待用户输入。
IDE 模式
在 Cursor 中激活时：
- 使用
codebase_search 进行语义搜索 - 使用
grep 进行精确匹配 - 使用
glob_file_search 定位文件 - 使用
read_file 指定行号范围读取代码收集证据 - 每个阶段完成后暂停，等待用户确认
触发方式
当用户说出以下任一关键词时激活本 skill：
- "执行代码文档梳理"
- "生成技术文档"
- "开始文档梳理工作流"
- "创建 SDD 文档"
前置阶段（知识库生成）触发：
- "生成项目知识库"
- "扫描项目代码结构"
- 或在工作流启动时由 AI 自动询问
可选工具触发：
- "执行术语梳理" / "梳理业务术语" → 读取
prompts/工具_术语梳理.md
工程识别
默认规则：
- 代码工程 = Cursor 当前工作区根目录
- 输出目录 = 用户在开始时提供（默认
./docs/sdd-kb/）
开始前必须确认：
工作流程
准备阶段
- 确认输出目录
- 检查是否需要生成项目知识库：询问用户是否已有知识库；若无则执行前置阶段
- 定位 skill 文件：从当前文件路径或常见位置
- 读取提示词文件
前置阶段：项目知识库生成（可选）
提示词文件：prompts/00-1_前置阶段_项目知识库生成.md
触发条件：用户没有现成的项目知识库（架构说明、领域知识、代码规范等）
任务目标：
- 以代码架构分析专家角色扫描项目代码结构
- 在指定目录（默认
./docs/sdd-kb/）下生成三类结构化文档： rules/：代码规范文档（代码组织结构、命名规范、设计模式、异常处理、日志规范）architecture/：架构文档（服务架构图、服务职责说明、模块划分、调用关系）domain-knowledge/：领域知识文档（业务概念索引、领域知识清单）- 所有结论标注代码位置，不确定内容标注「待确认」
输出：知识库文档（11+ 个结构化 Markdown 文件）
完成标准：
- ✅ 三个核心目录均已生成
- ✅ 所有结论已标注代码位置
- ✅ 待确认项已汇总展示
完成后暂停：等待用户检查并确认，然后进入阶段一。
阶段一：收集业务信息
提示词文件：prompts/01_阶段一_收集业务信息.md
任务目标：
- 确认输出目录
- 接收并累积记录用户提供的全部资料（文字、文档、图片、多轮补充）
- 对用户材料执行逐行逐句逐项读取，先形成阅读记录，再做归纳
- 如用户提供图片，保存到
{输出目录}/images/，维护 {输出目录}/图片分析.md - 每轮收集后必须追问是否还有补充
- 归纳并确认业务名称
- 阶段一不执行代码探索
输出：
- 配置信息（输出目录、业务名称、产物路径）
- 用户输入阅读记录（逐项摘录、数量统计、待确认点）
- 业务描述及全部补充
- 图片分析文档路径与图片清单（如有）
完成标准：
- ✅ 业务描述已提供
- ✅ 用户材料已逐项读取并形成阅读记录
- ✅ 图片已保存并更新到图片分析文档（如有）
- ✅ 用户确认没有其他补充
- ✅ 业务名称已归纳并确认
重要：阶段一完成后暂停等待用户确认
阶段二：代码探索与断点处理（循环执行）
提示词文件：prompts/02_阶段二_代码探索与断点处理.md
任务目标：
- 根据阶段一输出在代码库中查找实现逻辑
- 识别所有类型的业务入口（HTTP、MQ、定时任务、事件、回调、状态流转）
- 构建调用链和数据流
- 收集证据（文件路径 + 行号）
- 生成可证伪断言池（ENTRY- + FLOW-，每条 10 字段 + 评分）
- 循环处理断点问题和遗漏入口
输出：
- 代码探索报告（关键代码位置、方法签名、调用关系、数据流转、断点列表）
- 业务入口可证伪断言池（ENTRY-*）
- 业务流程阶段可证伪断言池（FLOW-*）
循环结束条件：
- ✅ AI 无法再提出新的断点问题
- ✅ AI 无法发现新的遗漏入口
- ✅ 断言池已闭合（无待确认项）
- ✅ 人工最终核验确认无偏差和漏洞
重要：
- 🔄 循环执行直到完成
- ✅ 问题清零 + 断言池闭合 + 人工二次确认后自动进入阶段三
- ❌ 禁止让用户在"继续阶段二"和"进入阶段三"之间二选一
阶段三：文档生成
提示词文件：prompts/03_阶段三_文档生成.md
任务目标：
- 基于所有收集的信息生成完整的 SDD 文档工作稿
- 使用模板库（默认
standard-business-template.md；API 专项用 api-focused-template.md） - 将所有证据占位符替换为实际证据（完整格式：注释标记 + 位置 + 代码 + 说明）
- 从阶段二断言池落盘断言组（禁止凭空生成新断言）
输出：
- SDD 工作稿：
{输出目录}/{业务名称}/README.md - 如业务流程复杂可分阶段保存
重要：阶段三完成后自动进入阶段四
阶段四：证据与断言验证（自动执行）
提示词文件：prompts/04_阶段四_证据与断言验证.md
任务目标：
- AI 完整通读工作稿，手动提取全部证据和断言（不依赖外部脚本）
- 证据验证：位置准确性、语义匹配、完整性
- 断言验证：业务真实性、可反证性、评分状态一致性
- 备份工作稿后净化主文档（剥离全部断言内容）
- 通读复核净化结果
输出：
- 证据验证报告（
{文档名}_evidence_validation.md） - 断言验证报告（
{文档名}_claim_validation.md） - 工作稿备份（
{文档名}_before_claim_cleanup.md） - 净化后主文档（最终交付版，无断言）
完成后暂停：等待用户查看验证结果
阶段五：人工纠偏与迭代
提示词文件：prompts/05_阶段五_人工纠偏与迭代.md
任务目标：
- 根据验证报告 + 用户反馈迭代修改文档
- 优先修复验证标记的问题
- 禁止将断言章节重新写回主文档
- 循环直到用户满意
重要：可多次迭代，如修改了证据可重新执行阶段四
阶段六：文档提纯（可选）
提示词文件：prompts/06_阶段六_文档提纯.md
任务目标：
- 对已确认文档进行提纯，12 项可选操作
- 用户选择要执行的操作
- 输出保存为
README.purified.md（原文档不变）
使用模式
模式一：完整流程（推荐）
用户：执行代码文档梳理 → AI 询问是否需要生成知识库 → 引导完成前置阶段（如需要）+ 全部六阶段。
模式二：仅生成知识库
用户：生成项目知识库 → AI 执行前置阶段，生成知识库后结束。
模式三：从指定阶段开始
用户：从阶段二开始 → AI 询问阶段一输出，然后继续。
模式四：仅执行某阶段
用户：只执行阶段二 → AI 询问输入，执行该阶段，输出报告。
阶段间暂停机制
每个阶段完成后：
- 暂停执行
- 提示用户当前阶段已完成
- 等待确认："继续"、"ok"、"好的"等
注意事项
- 人工驱动：每个阶段都需要人工提供关键信息；AI 辅助而非替代
- 证据必须：所有关键结论必须有代码证据支撑
- 迭代优化：多轮迭代是正常的，不要期望一次完美
- 断言是中间产物：仅用于验证，最终文档不保留断言内容