# 文档请求修复程序 ## 目的自动**修复技能**，读取最新的审核报告并将修复应用于 REQ（需求规范）文档。这项技能弥合了“doc-req-reviewer”（识别问题）和更正的 REQ 之间的差距，从而实现迭代改进周期。 **层**：7（REQ 质量改进） **上游**：REQ 文档、审核报告（首选`REQ-NN.A_audit_report_vNNN.md`、`REQ-NN.R_review_report_vNNN.md` 传统兼容或`REQ-NN-SSS.R_review_report_vNNN.md`）、SYS（用于系统设计对齐） **下游**：固定 REQ，修复报告（`REQ-NN.F_fix_report_vNNN.md` 或 `REQ-NN-SSS.F_fix_report_vNNN.md`） ** ** ## 何时使用此技能在以下情况下使用“doc-req-fixer”： * **审核后** ：在 `doc-req-reviewer` 识别问题后运行 * **迭代改进** ：审核的一部分 -> 修复 -> 审核周期 * **自动化管道**：用于质量关卡的 CI/CD 集成 * **批量修复** ：根据审核报告将修复应用于多个 REQ 文档 **请勿在以下情况下使用**： * 不存在审核报告（首先运行 `doc-req-reviewer`） * 创建新的 REQ（使用 `doc-req` 或 `doc-req-autopilot`） * 只需要验证（使用 `doc-req-validator`） ** ** ## 技能依赖技能|目的|使用时 ---|---|--- `文档请求审阅者` |待修复问题的来源 |输入（阅读评审报告） `文档命名` |元素 ID 标准 |修复元素 ID `文档请求` | REQ 创建规则 |创建缺失的部分 `文档系统` | SYS对齐参考|验证系统的可追溯性 ** ** ## 工作流程概述流程图TD A[输入：REQ 路径] --> B[查找最新审核报告] B --> C{找到评论？} C -->|否| D[首先运行 doc-req-reviewer] C -->|是| E[解析评审报告] E --> F[问题分类] 子图 FixPhases["修复阶段"] F --> F0[阶段 0：修复结构违规] F0 --> G[阶段 1: 创建丢失的文件] G --> H[第 2 阶段：修复损坏的链接] H --> I[阶段 3：修复元素 ID] I --> J[第 4 阶段：修复内容问题] J --> K[第 5 阶段：更新参考文献] K --> K2[阶段 6：处理上游漂移] 结束 K2 --> L[写入固定 REQ] L --> M[生成修复报告] M --> N{重新运行审核？} N -->|是| O[调用 doc-req-reviewer] O --> P{分数 >= 阈值？} P -->|否，迭代次数 < max| F P -->|是|问[完成] N -->|否|问 ** ** ## 修复阶段 ### 第 0 阶段：修复结构违规（严重）修复不在嵌套文件夹中的 REQ 文档。此阶段首先运行，因为所有后续阶段都依赖于正确的文件夹结构。 **嵌套文件夹规则**：所有 REQ 文档都必须位于嵌套文件夹中，无论文档大小如何。 **所需结构**：需求类型 |所需地点 ---|--- 整体| `docs/07_REQ/REQ-NN_{slug}/REQ-NN_{slug}.md` **修复操作**：问题代码 |问题 |修复行动 ---|---|--- REV-STR001 | REQ 不在嵌套文件夹中 |创建文件夹、移动文件、更新所有链接 REV-STR002 | REQ 文件夹名称与 REQ ID 不匹配 |重命名文件夹以匹配 REV-STR003 |应对 >25KB 的整体 REQ 进行分段 |手动审核标记 **结构修复工作流程**： def fix_req_struct(req_path: str) -> 列表[修复]: """修复 REQ 结构违规。""" 修复=[] 文件名 = os.path.basename(req_path) 父文件夹 = os.path.dirname(req_path) # 从文件名中提取 REQ ID 和 slug match = re.match(r'REQ-(\d+)_([^/]+)\.md', 文件名) 如果不匹配： return [] # 无法自动修复无效文件名 req_id = match.group(1) slug = match.group（2） Expected_folder = f“REQ-{req_id}_{slug}” # 检查是否已经在嵌套文件夹中如果 os.path.basename(parent_folder) != Expected_folder: # 创建嵌套文件夹 new_folder = os.path.join(os.path.dirname(parent_folder), Expected_folder) os.makedirs（new_folder，exist_ok = True） # 移动文件 new_path = os.path.join(new_folder, 文件名) Shutil.move(req_path, new_path) Fixs.append(f"已将 {req_path} 移动到 {new_path}") # 更新移动文件中的上游链接内容=路径(new_path).read_text() update_content = content.replace('../06_SYS/', '../../06_SYS/') 更新内容 = 更新内容.replace('../05_ADR/', '../../05_ADR/') 路径（新路径）.write_text（更新内容） Fixs.append(f“更新了嵌套文件夹结构的相对链接”) 返回修复 **移动后链接路径更新**：原始路径 |更新路径 ---|--- `../06_SYS/SYS-01_slug/SYS-01.md` | `../../06_SYS/SYS-01_slug/SYS-01.md` ** ** ### 第 1 阶段：创建丢失的文件创建被引用但不存在的文件。 **范围**：丢失文件 |行动|使用的模板 ---|---|--- `REQ-00_INDEX.md` |创建 REQ 索引 |索引模板 `REQ-00_GLOSSARY.md` |创建需求术语表 |词汇表模板 `UC_*.md` |创建占位符用例文档 |用例模板参考文档 (`*_REF_*.md`) |创建占位符 |参考模板 **REQ 索引模板**： --- 标题：“REQ-00：需求规范索引” 标签： - 要求 - 索引 - 参考自定义字段：文档类型：索引工件类型：REQ-REFERENCE 层数：7 --- # REQ-00：需求规范索引该项目所有需求规范的主索引。 ## 功能要求 |请求 ID |模块|状态 |优先|系统参考| |--------|--------|--------|----------|----------| | REQ-01 | [姓名] |草案/批准 | P1/P2/P3 | SYS-01 | ## 非功能性需求 |请求 ID |类别 |状态 |优先| |--------|----------|--------|----------| | REQ-NFR-01 |性能|草稿| P1 | | REQ-NFR-02 |安全|草稿| P1 | ## 按优先级划分的要求 |优先|需求 ID |计数 | |----------|---------|--------| | P1（关键）| | 0 | | P2（重要）| | 0 | | P3（必备）| | 0 | ## 覆盖矩阵 |系统组件|需求范围|差距| |----------------|--------------|------| | SYS-01 | REQ-01、REQ-02 |无 | --- *由 doc-req-fixer 维护。添加新的 REQ 文档时更新。* **REQ 术语表模板**： --- 标题：“REQ-00：要求术语表” 标签： - 要求 - 词汇表 - 参考自定义字段： document_type：术语表工件类型：REQ-REFERENCE 层数：7 --- # REQ-00：要求术语表所有需求规范文档中使用的通用术语。 ## 需求类型 |术语 |定义|示例| |------|------------|---------| |法国 |功能需求|系统应验证用户身份 | | NFR |非功能性需求 |响应时间 < 200ms | |加州大学 |使用案例|用户登录流程 | |交流|验收标准 |给定/何时/然后语句 | ## 优先级 |水平|定义|服务水平协议 | |--------|------------|-----| | P1 |关键 - MVP 必备 |立即 | | P2 |重要 - 应该有 |冲刺N+1 | | P3 |锦上添花 - 可以拥有 |积压| ## 状态值 |状态 |定义|下一个状态 | |--------|------------|------------| |草稿|初始文档 |评论 | |评论 |正在接受利益相关者审查 |批准/拒绝 | |已批准 |接受实施 |已实施 | |已实施 |代码完成 |已验证 | |已验证 |测试完成 |关闭 | ## 域名术语 |术语 |定义|背景 | |------|------------|---------| | [术语] | [定义] | [使用地点] | --- *由 doc-req-fixer 维护。术语更改时更新。* **用例占位符模板**： --- title：“用例：[用例名称]” 标签： - 用例 - 要求 - 参考自定义字段： document_type：用例状态：占位符创建者：文档请求修复程序 --- # 用例：[用例名称] > **状态**：占位符 - 需要完成 ## 1. 概述 |属性|价值| |----------|------| | UC ID | UC-神经网络 | |演员 | [主要演员] | |优先| P1/P2/P3 | |状态 |占位符 | ## 2. 说明 [TODO：描述用例目的] ## 3.前提条件 | ＃|前提条件| |---|--------------| | 1 | [必须为真的条件] | ## 4. 主要流程 |步骤|演员 |系统| |------|--------|--------| | 1 | 【演员动作】| [系统回应] | ## 5. 替代流程 [TODO：记录替代方案] ## 6. 后置条件 | ＃|后置条件 | |---|---------------| | 1 | 【成功完成后的状态】 | ## 7. 验收标准 |交流ID |标准|类型 | |--------|----------|------| | AC-01 | [给定/何时/然后] |功能性| --- *由 doc-req-fixer 作为占位符创建。完成本文档以解决断开的链接问题。* ** ** ### 第 2 阶段：修复损坏的链接更新链接以指向正确的位置。 **修复操作**：问题代码 |问题 |修复行动 ---|---|--- REV-L001 |内部链接失效 |更新路径或创建目标文件 REV-L002 |外部链接无法访问 |添加警告评论，保留链接 REV-L003 |使用绝对路径|转换为相对路径 REV-L004 |缺少 SYS 可追溯性链接 |添加对应SYS的链接 **路径解析逻辑**： def fix_link_path(req_location: str, target_path: str) -> str: """根据 REQ 位置计算正确的相对路径。""" # 整体 REQ：docs/07_REQ/REQ-01.md # 分段请求：docs/07_REQ/REQ-01_slug/REQ-01-003_section.md 如果 is_sectioned_req(req_location): # 需要再升一级返回“../”+calculate_relative_path(req_location, target_path) 其他：返回计算相对路径（req_location，目标路径） **跨层链接修复**：来源 |目标|链接模式 ---|---|--- 需求 |系统| `../06_SYS/SYS-NN.md` 需求 |点击率| `../08_CTR/CTR-NN.md` 需求 |规格| `../09_SPEC/SPEC-NN.md` ** ** ### 第 3 阶段：修复元素 ID 将无效的元素 ID 转换为正确的格式。 **转换规则**：图案|问题 |转换 ---|---|--- `REQ.NN.13.SS` |代码 13 对于 REQ 无效 | `REQ.NN.01.SS`（功能要求） `FR-XXX` |遗留模式| `REQ.NN.01.SS` 'NFR-XXX' |遗留模式| `REQ.NN.27.SS` 'UC-XXX' |遗留模式| `请求.NN.05.SS` 'AC-XXX' |遗留模式| `REQ.NN.06.SS` **类型代码映射**（REQ 特定的有效代码：01、05、06、27）：代码|元素类型 |描述 ---|---|--- 01 |功能需求|系统功能规范 05 |使用案例|用户交互场景 06 |验收标准 |可测试的成功标准 27 | 27非功能性需求 |质量属性要求 **无效的代码转换**：无效代码 |有效代码 |元素类型 ---|---|--- 13 | 01 |功能需求（是决策上下文） 14 | 14 05 |用例（是决策声明） 17 | 17 01 |功能需求（是组件） 18 | 18 06 |验收标准（是接口） 22 | 22 01 |功能需求（原为功能项） **正则表达式模式**： # 查找 REQ 类型代码无效的元素 ID invalid_req_type_13 = r'REQ\.(\d{2})\.13\.(\d{2})' replacement_13 = r'REQ.\1.01.\2' invalid_req_type_14 = r'REQ\.(\d{2})\.14\.(\d{2})' replacement_14 = r'REQ.\1.05.\2' invalid_req_type_17 = r'REQ\.(\d{2})\.17\.(\d{2})' replacement_17 = r'REQ.\1.01.\2' # 查找遗留模式 Legacy_fr = r'###\s+FR-(\d+):' Legacy_nfr = r'###\s+NFR-(\d+):' Legacy_uc = r'###\s+UC-(\d+):' Legacy_ac = r'###\s+AC-(\d+):' ** ** ### 第 4 阶段：修复内容问题解决占位符和不完整的内容。 **修复操作**：问题代码 |问题 |修复行动 ---|---|--- REV-P001 | `[TODO]` 占位符 |手动完成标记（无法自动修复） REV-P002 | `[TBD]` 占位符 |手动完成标记（无法自动修复） REV-P003 |模板日期`YYYY-MM-DD` |替换为当前日期 REV-P004 |模板名称 `[名称]` |替换为元数据作者或标志 REV-P005 |空部分|添加最少模板内容 REV-P006 |缺少需求状态 |添加“草稿”为默认状态 REV-P007 |缺少优先权 |添加“P2”作为默认优先级 **自动更换**：替换={ 'YYYY-MM-DDTHH:MM:SS': datetime.now().strftime('%Y-%m-%dT%H:%M:%S'), 'YYYY-MM-DD': datetime.now().strftime('%Y-%m-%d'), 'MM/DD/YYYY': datetime.now().strftime('%m/%d/%Y'), '[当前日期]': datetime.now().strftime('%Y-%m-%dT%H:%M:%S'), '[状态]': '草稿', '[优先级]': 'P2', '[版本]': '0.1', } **特定于 REQ 的内容修复**：部分|缺少内容 |自动填充 ---|---|--- 状态 |空 | “草稿” 优先|空 | “P2” 版本 |空 | “0.1” 最后更新 |空 |当前日期验证方法|空 | “测试” ** ** ### 第 5 阶段：更新参考文献确保可追溯性和交叉引用正确。 **修复操作**：问题 |修复行动 ---|--- 创建的文件缺少`@ref:` |添加参考标签错误的交叉 REQ 路径 |更新以正确的相对路径缺少 SYS 可追溯性 |添加 `@trace: SYS-NN.SS` 标签缺少点击率前向参考 |添加 `@trace: CTR-NN.SS` 标签缺少 SPEC 前向参考 |添加`@trace：SPEC-NN.SS`标签 **可追溯性矩阵更新**： ## 可追溯性 |请求元素 |痕迹来自 |追踪至 |类型 | |------------|-------------|------------|-----| | REQ.01.01.01 |系统.01.17.01 |规格.01.01.01 |需求->规格 | | REQ.01.05.01 |系统.01.05.01 | BDD.01.09.01 |用例->行为| | REQ.01.06.01 | REQ.01.01.01 | TSPEC.01.01.01 |标准->测试规范 | ** ** ### 第 6 阶段：处理上游漂移（自动合并）解决了自 REQ 创建以来上游源文档 (SYS) 发生更改的问题。此阶段实现了分层自动合并系统，该系统根据更改幅度自动集成上游更改。 #### 6.0.1 哈希验证修复 **FIX-H001：无效的哈希占位符** 触发器：哈希包含占位符而不是 SHA-256 修复： sha256sum <上游文件路径> |切-d''-f1 使用以下命令更新缓存：`sha256:<64_hex_output>` **FIX-H002：缺少哈希前缀** 触发器：64 个十六进制字符，但缺少 `sha256:` 前缀修复：在值前面添加 `sha256:` **FIX-H003：找不到上游文件** 触发器：无法计算哈希（文件丢失）修复：设置 `drift_Detected: true`，添加到手动审核代码|描述 |自动修复 |严重性 ---|---|---|--- 固定-H001 |将占位符哈希替换为实际的 SHA-256 |是的 |错误固定-H002 |添加缺少的 sha256: 前缀 |是的 |警告固定-H003 |找不到上游文件 |部分|错误 ** ** **上游**：SYS（第 6 层 - 系统设计） **下游**：CTR（第 8 层 - 合同）、SPEC（第 9 层 - 规范） **ID 模式**：`REQ.NN.TT.SS` 其中： * `NN` = 模块编号 (01-99) * `TT` = 类型代码（01=功能、05=用例、06=验收标准、27=NFR） * `SS` = 序列号 (01-99) ** ** #### 分层自动合并阈值等级 |变化% |行动|版本碰撞 |人工审核 ---|---|---|---|--- **1 级** | < 5% |自动合并添加 |补丁（1.0 -> 1.0.1）|否 **2 级** | 5-15% |自动合并变更日志 |次要 (1.0 -> 1.1) |可选 **第 3 级** | > 15% |存档+重新生成|主要 (1.x -> 2.0) |是的 * * * #### 变化百分比计算 defcalculate_change_percentage(sys_current: str, sys_baseline: str) -> float: ”“” 计算 SYS 版本之间的变化百分比。算法： 1. 对两个文档（部分、组件、接口）进行标记 2.计算添加的token（新内容） 3.计算修改的token（改变的内容） 4.计算删除的token（删除的内容-加权2x） 5.返回：（添加+修改+2*删除）/total_baseline * 100 ”“” Baseline_tokens = tokenize_sys_document(sys_baseline) current_tokens = tokenize_sys_document(sys_current) 添加 = len(当前_令牌 - 基线_令牌) 删除 = len(baseline_tokens - current_tokens) 修改 = count_modified_tokens(baseline_tokens, current_tokens) 总基线 = len(基线令牌) 如果总基线 == 0： return 100.0 # 新文档 = 100% 更改 change_score = 添加 + 修改 + (2 * 删除) 返回（变化分数/总基线）* 100 def tokenize_sys_document(内容: str) -> 设置: """从 SYS 文档中提取有意义的标记。""" 标记=设置（） # 提取组件定义 (SYS.NN.17.SS) tokens.update(re.findall(r'SYS\.\d{2}\.17\.\d{2}', content)) # 提取接口定义(SYS.NN.18.SS) tokens.update(re.findall(r'SYS\.\d{2}\.18\.\d{2}', content)) # 提取决策参考 (SYS.NN.13.SS) tokens.update(re.findall(r'SYS\.\d{2}\.13\.\d{2}', content)) # 提取节标题 tokens.update(re.findall(r'^##+ .+$', 内容, re.MULTILINE)) 返回令牌 ** ** #### 第 1 层：自动合并添加（< 5% 变化） **触发器**：对 SYS 进行少量添加，扩展现有组件。 **行动**： 1. 识别新的SYS元素（组件、接口） 2. 使用自动分配的 ID 生成相应的 REQ 元素 3. 在适当的部分插入新的要求 4.增加补丁版本（1.0 -> 1.0.1） 5. 使用合并记录更新漂移缓存 **自动 ID 生成** : defgenerate_next_req_id(existing_ids: list, module: str, type_code: str) -> str: ”“” 生成下一个可用的 REQ ID。示例：如果 REQ.01.01.12 存在，则下一个是 REQ.01.01.13 ”“” 模式= f“REQ。{模块}。{类型代码}。” 最大序列 = 0 对于现有_ids 中的 id：如果 id.startswith(pattern): seq = int(id.split('.')[-1]) max_seq = max(max_seq, seq) next_seq = str(max_seq + 1).zfill(2) 返回f“REQ。{模块}。{type_code}。{next_seq}” # 示例：REQ.01.01.12 存在 -> 新 ID 为 REQ.01.01.13 **第 1 层合并模板**： ### REQ.01.01.13：[新要求标题] |属性|价值| |----------|------| |身份证 | REQ.01.01.13 | |状态 |草稿| |优先| P2 | |来源 | SYS.01.17.05（自动合并）| |版本已添加 | 1.0.1 | **描述**：[从 SYS 组件描述中自动提取] **验收标准**： - [ ] AC-01：[源自 SYS 接口合约] @trace：SYS.01.17.05 ** ** #### 第 2 层：自动合并变更日志（5-15% 变更） **触发器**：适度的更改，包括新的部分或修改的组件。 **行动**： 1. 执行所有第 1 层操作 2. 生成详细的变更日志部分 3. 使用“[UPDATED]”标签标记修改后的现有需求 4. 增加次要版本（1.0 -> 1.1） 5. 创建合并摘要以供可选的人工审核 **变更日志格式**： ## 变更日志（自动合并 v1.1） **合并日期**：2026-02-10T16:00:00 **来源**：SYS-01 v1.3（基线：v1.1） **变化百分比**：8.5% **层**：2（与变更日志自动合并） ### 添加的要求 |请求 ID |标题 |源 SYS 元素 | |--------|------|--------------------| | REQ.01.01.13 |新数据验证 |系统.01.17.05 | | REQ.01.01.14 |扩展日志记录 |系统.01.17.06 | ### 更新的要求 |请求 ID |更改类型 |上一页 |当前| |--------|-------------|----------|---------| | REQ.01.01.03 |优先| P3 | P2 | | REQ.01.01.07 |描述 | [截断] | [截断] | ### 已弃用（不删除） |请求 ID |原因 |取代 | |--------|--------|----------------| | REQ.01.01.02 | SYS | 中的组件被删除REQ.01.01.13 | **无删除政策**：需求永远不会被删除。相反，标记为已弃用： ### REQ.01.01.02：旧版身份验证 [已弃用] > **已弃用**：自 v1.1 起，此要求已被 REQ.01.01.13 取代。 > 原因：源组件 SYS.01.17.02 在 SYS v1.3 中被删除。 > 保留历史可追溯性。 |属性|价值| |----------|------| |身份证 | REQ.01.01.02 | |状态 | **已弃用** | |弃用日期 | 2026-02-10 | |取代 | REQ.01.01.13 | ** ** #### 第 3 层：存档和重新生成（> 15% 变化） **触发器**：SYS 中的重大架构更改需要基本的 REQ 重组。 **行动**： 1. 创建存档清单 2. 存档当前 REQ 版本 3. 通过 `doc-req-autopilot` 触发完整的 REQ 重新生成 4. 增加主要版本（1.x -> 2.0） 5. 最终确定前需要人工审核 **存档清单**： --- 标题：“REQ-01 存档清单” 存档日期：“2026-02-10T16:00:00” archive_reason：“第 3 层上游漂移（>15% 变化）” 存档版本：“1.2” 新版本：“2.0” --- # REQ-01 存档清单 ## 档案摘要 |属性|价值| |----------|------| |文件| REQ-01 | |存档版本 | 1.2 | 1.2 |存档日期 | 2026-02-10T16:00:00 | |变化百分比 | 23.7% | |触发|第 3 级上游漂移 | |上游来源| SYS-01 v2.0 | ## 存档文件 |文件|存档位置 |哈希 | |------|------------------|------| | REQ-01.md |存档/REQ-01_v1.2/ | sha256:abc123... | | REQ-01.F_fix_report_v003.md |存档/REQ-01_v1.2/ | sha256:def456... | ## 迁移注意事项 |旧的 REQ ID |状态 |新的请求 ID |笔记| |------------|--------|------------|--------| | REQ.01.01.01 |保留 | REQ.01.01.01 |没有变化| | REQ.01.01.02 |已弃用 | - |功能已删除 | | REQ.01.01.03 |合并| REQ.01.01.02 |与 REQ.01.01.04 结合 | | - |新 | REQ.01.01.10 | SYS.01.17.08 新内容 | ## 再生触发 ````bash /doc-req-autopilot SYS-01 --来自存档 REQ-01_v1.2 --目标版本 2.0 **存档目录结构**： docs/07_REQ/ ├── archive/ │ └── REQ-01_v1.2/ │ ├── ARCHIVE_MANIFEST.md │ ├── REQ-01.md │ ├── REQ-01.F_fix_report_v003.md │ └── .drift_cache.json ├── REQ-01.md（v2.0 - 重新生成）└── REQ-00_INDEX.md --- #### 增强漂移缓存与合并历史记录处理漂移问题后，更新`.drift_cache.json`： ```json { “req_version”：“1.1”， “req_updated”：“2026-02-10T16:00:00”， “drift_reviewed”：“2026-02-10T16:00:00”， “upstream_hashes”：{ "../../06_SYS/SYS-01.md": "sha256:a1b2c3d4e5f6...", “../../06_SYS/SYS-01.md#component-3”：“sha256：g7h8i9j0k1l2 ...” }, “合并历史记录”：[ { “merge_date”：“2026-02-10T16:00:00”， “等级”：2， “变化百分比”：8.5， "version_before": "1.0", "version_after": "1.1", "upstream_version": "SYS-01 v1.3", "added_ids": ["REQ.01.01.13", "REQ.01.01.14"], "updated_ids": ["REQ.01.01.03", "REQ.01.01.07"], “deprecated_ids”：[“REQ.01.01.02”] } ], “acknowledged_drift”：[ { “文档”：“SYS-01.md”， “acknowledged_date”：“2026-02-08”， "reason": "已审核 - 仅外观更改", "hash_at_acknowledgment": "sha256:xyz789..." } ], “下游通知”：{ “CTR-01”：{ “通知”：“2026-02-10T16:05:00”， “req_version”：“1.1”， “pending_review”：正确 }, “规格-01”：{ “通知”：“2026-02-10T16:05:00”， “req_version”：“1.1”， “pending_review”：正确 } } } ** ** #### 漂移问题代码（已更新）代码|严重性 |描述 |等级 |自动修复 ---|---|---|---|--- REV-D001 |信息 | SYS 少量添加 (< 5%) | 1 |是的 REV-D002 |警告| SYS 中等变化 (5-15%) | 2 |是的 REV-D003 |信息 |上游版本增加 | 1 |是的 REV-D004 |警告| SYS | 添加新组件1-2 | 1-2是的 REV-D005 |错误 |主要上游修改 (> 15%) | 3 |否（存档） REV-D006 |警告|已弃用的上游元素 | 2 |是（标记为已弃用） ** ** #### 漂移处理的命令选项 # 自动合并层级检测 /doc-req-fixer REQ-01 --自动合并 # 强制特定层（覆盖自动检测） /doc-req-fixer REQ-01 --自动合并 --force-tier 2 # 预览合并而不应用 /doc-req-fixer REQ-01 --自动合并 --dry-run # 确认漂移而不合并 /doc-req-fixer REQ-01 --acknowledge-drift # 查看合并历史记录 /doc-req-fixer REQ-01 --show-merge-history # 从存档中恢复 /doc-req-fixer REQ-01 --restore-archive v1.2 ** ** ## 命令用法 ### 基本用法 # 根据最新评论修复 REQ /doc-req-fixer REQ-01 # 修复分段 REQ /doc-req-fixer REQ-01-003 # 修复明确的审查报告 /doc-req-fixer REQ-01 --review-report REQ-01.R_review_report_v001.md # 修复并重新运行审核 /doc-req-fixer REQ-01 --重新验证 # 修复迭代限制 /doc-req-fixer REQ-01 --revalidate --max-iterations 3 ### 选项选项 |默认 |描述 ---|---|--- `--审查报告` |最新 |使用的具体审查报告 `--重新验证` |假 |修复后运行审阅者 `--最大迭代次数` | 3 |最大修复审查周期 `--修复类型` |全部 |特定修复类型（以逗号分隔） `--创建缺失` |真实|创建缺失的参考文件 `--备份` |真实|修复前备份 REQ `--试运行` |假 |预览修复而不应用 `--承认漂移` |假 |交互式漂移确认模式 `--更新漂移缓存` |真实|修复后更新 .drift_cache.json `--自动合并` |假 |启用上游漂移的分层自动合并 `--force-tier` |汽车 |强制特定合并层（1、2 或 3） `--显示合并历史记录` |假 |显示漂移缓存的合并历史记录 `--恢复存档` |无 |从存档版本恢复 REQ（例如 v1.2） `--通知下游` |真实|合并后通知 CTR/SPEC REQ 更改 ### 修复类型类型 |描述 ---|--- `丢失的文件` |创建缺失的索引、术语表、用例文档 `损坏的链接` |修复链接路径 `element_ids` |转换无效/旧元素 ID `内容` |修复占位符、日期、状态、优先级 `参考文献` |更新可追溯性和交叉引用 ‘漂移’ |处理上游漂移检测问题 `漂移_合并` |自动合并上游 SYS 更改（分层） `drift_archive` |存档当前版本以进行第 3 层更改 `弃用` |将过时的需求标记为已弃用（不删除） `全部` |所有修复类型（默认） ** ** ## 输出工件 ### 修复报告 **嵌套文件夹规则**：所有 REQ 使用嵌套文件夹 (`REQ-NN_{slug}/`)，无论大小如何。修复报告与 REQ 文档一起存储在嵌套文件夹中。 **文件命名** : `REQ-NN.F_fix_report_vNNN.md` 或 `REQ-NN-SSS.F_fix_report_vNNN.md` **位置**：REQ 嵌套文件夹内：`docs/07_REQ/REQ-NN_{slug}/` **结构**： --- 标题：“REQ-NN.F：修复报告 v001” 标签： - 要求 - 修复报告 - 质量保证自定义字段： document_type：修复报告工件类型：REQ-FIX 层数：7 父文档：REQ-NN 来源审查：REQ-NN.R_review_report_v001.md fix_date: "YYYY-MM-DDTHH:MM:SS" fix_tool：文档请求修复程序修复版本：“1.0” --- # REQ-NN 修复报告 v001 ## 总结 |公制|价值| |--------|--------| |来源评论 | REQ-NN.R_review_report_v001.md | |审查中的问题 | 18 | 18 |已解决的问题 | 15 | 15 |剩余问题 | 3（需要人工审核）| |文件已创建 | 3 | |文件修改 | 5 | ## 文件已创建 |文件 |类型 |地点 | |------|------|----------| | REQ-00_INDEX.md |需求索引 |文档/07_REQ/ | | REQ-00_GLOSSARY.md |请求术语表 |文档/07_REQ/ | | UC_UserLogin.md |用例占位符 |文档/00_REF/用例/ | ## 应用的修复 | ＃|问题代码 |问题 |修复已应用 |文件 | |---|------------|--------|-------------|-----| | 1 | REV-L001 |损坏的索引链接 |创建 REQ-00_INDEX.md | REQ-01.md | | 2 | REV-L001 |损坏的词汇表链接 |创建 REQ-00_GLOSSARY.md | REQ-01.md | | 3 | REV-L001 |损坏的用例链接 |已创建占位符 UC 文件 | REQ-01.md | | 4 | REV-N004 |元素类型 13 无效 |转换为 01 型 | REQ-01.md | | 5 | REV-N004 |旧版 FR-XXX 图案 |转换为 REQ.NN.01.SS | REQ-01.md | | 6 | REV-P007 |缺少优先权 |添加P2默认| REQ-02.md | ## 需要人工审核的问题 | ＃|问题代码 |问题 |地点 |原因 | |---|------------|--------|----------|--------| | 1 | REV-P001 | [TODO] 占位符 | REQ-01：L67 |需要领域专业知识| | 2 | REV-D001 |检测到系统漂移 | REQ-01：L145 |审查系统变更 | | 3 | REV-R001 |缺少验收标准 | REQ-01：L200 |定义可测试的标准 | ## 修复后验证 |公制|之前 |之后 |达美航空 | |--------|--------|--------|--------| |评论分数 | 82 | 82 93 | 93 +11 | |错误 | 5 | 0 | -5 | |警告| 8 | 3 | -5 | ## 后续步骤 1. 填写UC_UserLogin.md占位符 2. 处理剩余的 [TODO] 占位符 3. 添加缺失的需求验收标准 4. 检查 SYS 漂移并根据需要更新要求 5. 运行“/doc-req-reviewer REQ-01”来验证修复 ** ** ## 与自动驾驶仪集成该技能由审核 -> 修复周期中的“doc-req-autopilot”调用：流程图LR 子图 Phase5[“第 5 阶段：审查和修复周期”] A[doc-req-reviewer] --> B{分数 >= 90?} B -->|否| C[文档请求修复程序] C --> D{迭代 < 最大值？} D -->|是|一个 D -->|否| E[手动审核标志] B -->|是| F[通过] 结束 **自动驾驶仪集成点**：相|行动|技能 ---|---|--- 5a 阶段 |进行初步审查 | `文档请求审阅者` 5b 阶段 |如果发现问题，请应用修复程序 | `文档请求修复程序` 5c 阶段 |重新运行审核 | `文档请求审阅者` 5d 阶段 |重复直到通过或最大迭代 |循环 ** ** ## 错误处理 ### 恢复行动错误 |行动 ---|--- 未找到审查报告 |提示先运行 `doc-req-reviewer` 无法创建文件（权限）|记录错误，继续其他修复无法解析审核报告 |中止并显示明确的错误消息超出最大迭代次数 |生成报告、标记以供手动审核 ### 备份策略在应用任何修复之前： 1. 在 `tmp/backup/REQ-NN_YYYYMMDD_HHMMSS/` 中创建备份 2. 将所有 REQ 文件复制到备份位置 3. 对原始文件应用修复 4. 如果修复过程中出现错误，请从备份恢复 ** ** ## 相关技能技能|关系 ---|--- `文档请求审阅者` |提供审查报告（输入） `doc-req-自动驾驶仪` |协调审核 -> 修复周期 `doc-req-validator` |结构验证 `文档命名` |元素 ID 标准 `文档请求` | REQ创建规则 `文档系统` |上游系统设计 `doc-ctr` |下游合同参考 `文档规范` |下游规格参考 ** ** ## 版本历史版本 |日期 |变化 ---|---|--- 2.1 | 2.1 2026-02-11 | **结构合规性**：添加了用于嵌套文件夹规则实施的阶段 0 (REV-STR001-STR003)；在其他修复阶段之前首先运行 2.0 | 2026-02-10 | **增强型第 6 阶段自动合并系统**：分层自动合并阈值（第 1 层 <5%，第 2 层 5-15%，第 3 层 >15%）；变化百分比计算算法；针对新要求自动生成的 ID（REQ.NN.TT.SS 模式）；无删除政策 - 标记为 [DEPRECATED]；为第 3 层创建存档清单；增强了漂移缓存，具有合并历史记录和下游通知；新选项：--auto-merge、--force-tier、--show-merge-history、--restore-archive、--notify-downstream；新修复类型：drift_merge、drift_archive、deprecate；基于变更层的语义版本控制（补丁/次要/主要） 1.0 | 2026-02-10 |初始技能创造； 6 阶段修复工作流程； REQ 索引、术语表和用例文件创建；元素ID转换（类型01、05、06、27）；修复了损坏的链接； SYS上游漂流处理；支持分段 REQ 命名 (REQ-NN-SSS)；与自动驾驶仪集成审核->修复周期 ## 实施计划一致性 (IPLAN-004) * 将计划派生的输出视为有效的源模式，并验证实施计划范围/目标的意图保留。 * 验证上游自动驾驶仪优先级假设：`--iplan > --ref > --prompt`。 * 将计划上下文和工件输出之间的目标/范围冲突标记为需要澄清的阻塞问题。 * 不要引入旧的后备路径，例如“docs-v2.0/00_REF”。

文档需求修复程序

包含技能