nex/docs/prompts/prompt-spec-review.md

请审查并整理 openspec/specs/ 下的稳定规范，使其成为可搜索、边界清晰、无冗余、与当前业务一致的能力索引，按以下流程执行。

约束

• openspec/specs/ 描述长期稳定的业务能力、规则和外部行为，不记录变更过程、迁移说明、实现路径、内部类型名、组件 props、样式数值、层级分层等实现细节
• 用户可感知或对外暴露的契约可以保留：公开 API 路径、请求/响应字段、协议名、错误码、数据约束、交互结果
• Requirement 和 Scenario 应描述业务能力、外部行为或稳定约束，不以“使用某层/某组件/某库实现”作为标题或核心表述
• 不把当前代码自动视为唯一真相；若代码、README、现有 spec 冲突且无法判断应以哪边为准，列入待确认清单，不直接改写规范
• 仅删除内容已被其他规范完整覆盖且无独立检索价值的规范；非冗余内容仅迁移、合并、拆分或重命名
• 每批重构执行前用提问工具获得用户确认；删除或重写前先备份原文件为 {file}.bak.{timestamp}
• 命名、Purpose、Requirement 标题都必须保留用户下一次最可能搜索的业务关键词

1. 收集

并行读取：

• openspec/config.yaml
• README.md，以及与模块结构、API、架构相关的 README 或文档
• openspec/specs/*/spec.md

默认不读取 openspec/changes/**、历史 proposal/design/tasks 作为稳定规范整理依据；仅在用户明确要求“连同历史变更一起校对”时再纳入。

先建立索引，不直接开始改写：

索引	内容
spec_index[]	每个 spec 的目录名、Purpose、Requirement 摘要、关键词、外部契约、疑似重叠对象
domain_map[]	从 README、API、模块文档中提炼的核心业务域、横切能力和术语
term_map[]	同义词、旧名、缩写和推荐标准术语
suspects[]	需要进一步对照代码或测试确认的 spec

仅对 suspects[] 做定向读取：

• 读取与该 spec 对应的源码、测试、README 或架构文档
• 不对 backend/、frontend/ 做无差别逐文件扫描

判定依据优先级：

• 当前稳定 spec 与 README 共同支持的事实，可直接视为高置信度
• 仅代码可见但 README 和 spec 未体现的内容，先判断它是稳定外部行为还是临时实现细节
• 代码、README、现有 spec 互相冲突且无法自动定夺时，进入 待确认清单

2. 审查

按 spec、Requirement、Scenario 三层检查：

维度	检查点
过时	描述的能力、术语、外部契约是否仍成立；是否存在 TBD、TODO、占位说明
冲突	不同规范是否对同一行为给出不同约束、命名或边界
重复/重叠	是否在文件级、Requirement 级、Scenario 级重复描述同一能力
错位	内容是否放错能力域；横切规则是否混入实体规范；平台实现是否混入通用能力规范
粒度	是否过大导致难检索，或过碎导致回答一个问题必须同时打开多个 spec
术语	同一概念是否混用多个名字；旧名、别名、缩写是否需要归一并保留检索入口
命名/检索	目录名、Purpose、Requirement 标题是否准确；是否能被 README、API、业务术语直接命中
规范性	是否使用 SHALL/WHEN/THEN；是否混入变更记录、迁移说明、内部实现或 UI/代码细节
完整性	Purpose 是否明确；是否存在空目录、非 spec 噪音文件、无清晰归属的孤立规范

重构判定规则：

• 若两个 spec 回答的是同一个核心问题，或其中一个只是另一个的子集，优先合并
• 若一个 spec 混合多个独立检索意图，或同时包含横切规则与业务流程，优先拆分
• 若内容正确但目录名、Purpose 或 Requirement 标题不利于检索，优先重命名或改写标题
• 若多个术语指向同一概念，统一到一个标准术语，并在 Purpose 或 Requirement 中保留必要别名以支持搜索
• 若某段内容只是内部实现细节，且不影响外部行为理解，删除该段而不是为其单独保留 spec
• 若某个具体值同时属于外部契约与内部实现，按“是否对调用方可见、是否影响兼容性”判断是否保留

命名约定

命名优先复用仓库已存在的稳定术语，如 provider、model、stats、protocol、proxy、logging、validation、migration、frontend、desktop、mysql。

类型	模式	示例
实体生命周期	{entity}-management	provider-management、model-management
横切能力	{concern} 或 {concern}-{qualifier}	error-handling、structured-logging
协议/适配	{protocol}-{capability} 或 protocol-adapter-{protocol}	openai-protocol-proxy、protocol-adapter-openai
运行面/入口	{surface} 或 {surface}-{capability}	frontend、desktop-app
基础设施	{resource}-{operation}	database-migration、mysql-driver

命名原则：

• 1-4 个词，保持单一主题
• 优先使用业务名词，不使用 basic、general、misc、info、data 等泛化词
• 不使用 crud、list、table、display 等实现模式词，除非它本身就是外部契约的一部分
• 同一主题的命名模式保持一致，不同时混用多套前后缀

3. 报告

输出分析结果：

1. 问题总览表：问题类型 × 涉及规范数
2. 规范关系表：每个 spec 的主主题、重叠对象、冲突对象、建议动作
3. 术语归一表：旧术语 / 别名 / 缩写 → 推荐标准术语
4. 逐项分析：每个有问题的规范说明位置、问题、影响、建议和目标规范
5. 待确认清单：代码、README、现有 spec 冲突且无法自动定夺的事项
6. 重构方案：按优先级分批
7. 重构后目录结构：预期的新 openspec/specs/ 目录树

优先级建议：

• P0：删除空目录、非 spec 噪音文件、占位内容
• P1：删除完全冗余规范；将其内容映射到主规范
• P2：合并重复/子集规范；拆分错位或过大规范
• P3：重命名目录、改写 Purpose 和 Requirement 标题以提升检索性
• P4：修正过时描述，清理实现细节、迁移说明和变更记录

若所有问题清单为空，输出“审查通过，未发现问题”，跳至步骤 5。

4. 计划（用户确认）

先针对 待确认清单 用提问工具逐项向用户确认。

再按批次展示完整重构计划，每批必须包含：

• 操作类型：删除、重命名、迁移、合并、拆分、改写
• 路径变化：源路径 → 目标路径
• 内容映射：源 spec 的 Requirement / Scenario 将迁移到哪里
• 术语处理：哪些旧词保留为检索入口，哪些词统一替换
• 执行原因：为什么这样做更利于检索、去重和边界清晰
• 验证方式：如何确认没有丢失约束或引入新的冲突

用提问工具获得当前批次确认后再执行。

5. 执行

按 P0 → P4 逐批执行已确认的重构。

执行要求：

• 合并或拆分时先写目标 spec，再删除或重命名源 spec
• 删除前确认其 Requirement 和 Scenario 已被完整保留、迁移或判定为纯冗余
• 每批执行后重新读取受影响的 spec，并复核结构和内容

每批执行后至少验证：

• 目录结构完整，openspec/specs/*/spec.md 可正常读取
• 不存在未承接的 Requirement 或 Scenario
• Purpose、Requirement 标题、目录名可以直接表达主能力
• 不再包含 TBD、变更记录、迁移说明、内部实现细节或噪音文件
• 若本批涉及代码对照项，相关外部契约描述与当前仓库现状一致，或已列入残留待确认

收尾时输出：修改文件清单、备份文件清单、最终目录树、残留待确认事项和整理摘要。