请审查并整理 `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`、变更记录、迁移说明、内部实现细节或噪音文件 - 若本批涉及代码对照项,相关外部契约描述与当前仓库现状一致,或已列入残留待确认 收尾时输出:修改文件清单、备份文件清单、最终目录树、残留待确认事项和整理摘要。