# 文档系统修复程序 ## 目的自动**修复技能**，读取最新的审核/审查报告并将修复应用于 SYS（系统设计规范）文档。此技能弥合了“doc-sys-reviewer”/“doc-sys-audit”（用于识别问题）和更正的 SYS 之间的差距，从而实现迭代改进周期。 **层**：6（系统质量改进） **上游**：SYS 文档、审核/审核报告（首选`SYS-NN.A_audit_report_vNNN.md`、`SYS-NN.R_review_report_vNNN.md` 遗留）、ADR（用于架构调整） **下游**：修复了 SYS，修复报告（`SYS-NN.F_fix_report_vNNN.md`） ** ** ## 何时使用此技能在以下情况下使用“doc-sys-fixer”： * **审核后** ：在 `doc-sys-reviewer` 识别问题后运行 * **迭代改进** ：审核的一部分 -> 修复 -> 审核周期 * **自动化管道**：用于质量关卡的 CI/CD 集成 * **批量修复** ：根据审查报告将修复应用于多个 SYS 文档 **请勿在以下情况下使用**： * 不存在审核/审核报告（首先运行 `doc-sys-audit` 或 `doc-sys-reviewer`） * 创建新的 SYS（使用 `doc-sys` 或 `doc-sys-autopilot`） * 只需要验证（使用 `doc-sys-validator`） ** ** ## 技能依赖技能|目的|使用时 ---|---|--- `文档系统审计` |标准化结果的首选来源 |输入（读取审计报告） `文档系统审阅者` |需要修复的遗留/替代问题源 |输入（阅读评审报告） `文档命名` |元素 ID 标准 |修复元素 ID `文档系统` | SYS创建规则|创建缺失的部分 `doc-adr` | ADR 对齐参考 |验证架构的可追溯性 ** ** ## 工作流程概述流程图TD A[输入：SYS 路径] --> B[查找最新审核报告] B --> C{找到评论？} C -->|否| D[首先运行 doc-sys-audit 或 doc-sys-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[写入固定SYS] L --> M[生成修复报告] M --> N{重新运行审核？} N -->|是| O[调用 doc-sys-reviewer] O --> P{分数 >= 阈值？} P -->|否，迭代次数 < max| F P -->|是|问[完成] N -->|否|问 ** ** ## 修复阶段 ### 第 0 阶段：修复结构违规（严重）修复不在嵌套文件夹中的 SYS 文档。此阶段首先运行，因为所有后续阶段都依赖于正确的文件夹结构。 **嵌套文件夹规则**：所有 SYS 文档都必须位于嵌套文件夹中，无论文档大小如何。 **所需结构**：系统类型|所需地点 ---|--- 整体| `docs/06_SYS/SYS-NN_{slug}/SYS-NN_{slug}.md` **修复操作**：问题代码 |问题 |修复行动 ---|---|--- REV-STR001 | SYS 不在嵌套文件夹中 |创建文件夹、移动文件、更新所有链接 REV-STR002 | SYS 文件夹名称与 SYS ID 不匹配 |重命名文件夹以匹配 REV-STR003 |应对 >25KB 的整体 SYS 进行分区 |手动审核标记 **结构修复工作流程**： def fix_sys_struct(sys_path: str) -> 列表[修复]: """修复 SYS 结构违规。""" 修复=[] 文件名 = os.path.basename(sys_path) 父文件夹 = os.path.dirname(sys_path) # 从文件名中提取 SYS ID 和 slug match = re.match(r'SYS-(\d+)_([^/]+)\.md', 文件名) 如果不匹配： return [] # 无法自动修复无效文件名 sys_id = 匹配.组(1) slug = match.group（2） Expected_folder = f“SYS-{sys_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(sys_path, new_path) Fixs.append(f"已将 {sys_path} 移动到 {new_path}") # 更新移动文件中的上游链接内容=路径(new_path).read_text() update_content = content.replace('../05_ADR/', '../../05_ADR/') 更新内容 = 更新内容.replace('../04_BDD/', '../../04_BDD/') 路径（新路径）.write_text（更新内容） Fixs.append(f“更新了嵌套文件夹结构的相对链接”) 返回修复 **移动后链接路径更新**：原始路径 |更新路径 ---|--- `../05_ADR/ADR-01_slug/ADR-01.md` | `../../05_ADR/ADR-01_slug/ADR-01.md` ** ** ### 第 1 阶段：创建丢失的文件创建被引用但不存在的文件。 **范围**：丢失文件 |行动|使用的模板 ---|---|--- `SYS-00_INDEX.md` |创建SYS索引|索引模板 `COMP_*.md` |创建占位符组件文档 |组件模板 `INT_*.md` |创建占位符界面文档 |界面模板参考文档 (`*_REF_*.md`) |创建占位符 |参考模板 **SYS索引模板**： --- 标题：“SYS-00：系统设计规范索引” 标签： - 系统 - 索引 - 参考自定义字段：文档类型：索引 artifact_type：系统参考层数：6 --- # SYS-00：系统设计规范索引该项目所有系统设计规范的主索引。 ## 系统组件 |系统 ID |组件|状态 |最后更新 | ADR 参考资料 | |--------|---------|--------|--------------|----------| | SYS-01 | [姓名] |草案/决赛 |年-月-日 | ADR-01、ADR-02 | ## 组件关系 |组件|取决于|依赖于 | |------------|------------|-------------| | SYS-01 | | | ## 接口目录 |接口ID |类型 |供应商|消费者 | |--------------|------|----------|----------| | INT-01 |应用程序接口 | SYS-01 | SYS-02 | --- *由 doc-sys-fixer 维护。添加新的 SYS 文件时更新。* **组件占位符模板**： --- title：“组件规格：[组件名称]” 标签： - 组件 - 系统设计 - 参考自定义字段：文档类型：组件状态：占位符创建者：文档系统修复程序 --- # 组件规格：[组件名称] > **状态**：占位符 - 需要完成 ## 1. 概述 [TODO：文档组件概述] ## 2. 职责 |责任|描述 | |----------------|-------------| | [姓名] | [它处理什么] | ## 3. 接口 |接口 |类型 |方向 |连接到 | |------------|------|------------|--------------| | [姓名] | REST/gRPC/事件 |输入/输出| [组件] | ## 4. 数据结构 [TODO：记录关键数据结构] ## 5. 架构决策 |美国存托凭证 |标题 |影响 | |-----|--------|--------| | ADR-NN | [标题]| [它如何影响这个组件] | --- *由 doc-sys-fixer 作为占位符创建。完成本文档以解决断开的链接问题。* **界面占位符模板**： --- title: "接口规范：[接口名称]" 标签： - 接口 - 系统设计 - 参考自定义字段：文档类型：接口状态：占位符创建者：文档系统修复程序 --- # 接口规范：[接口名称] > **状态**：占位符 - 需要完成 ## 1. 概述 [TODO：文档接口用途] ## 2. 协议 |属性 |价值| |----------|------| |类型 | REST / gRPC / 事件 / 消息 | |格式| JSON/Protobuf/Avro | |认证| JWT / API 密钥 / mTLS | ## 3. 操作 |运营|方法|路径/主题 |描述 | |------------|--------|------------|-------------| | [姓名] |获取/发布 | /路径| [说明] | ## 4. 数据模型 [TODO：文档请求/响应模型] --- *由 doc-sys-fixer 作为占位符创建。完成本文档以解决断开的链接问题。* ** ** ### 第 2 阶段：修复损坏的链接更新链接以指向正确的位置。 **修复操作**：问题代码 |问题 |修复行动 ---|---|--- REV-L001 |内部链接失效 |更新路径或创建目标文件 REV-L002 |外部链接无法访问 |添加警告评论，保留链接 REV-L003 |使用绝对路径|转换为相对路径 REV-L004 |缺少 ADR 追溯链接 |添加对应ADR的链接 **路径解析逻辑**： def fix_link_path(sys_location: str, target_path: str) -> str: """根据 SYS 位置计算正确的相对路径。""" # 整体 SYS: docs/06_SYS/SYS-01.md # 分区 SYS: docs/06_SYS/SYS-01_slug/SYS-01.3_section.md 如果 is_sectioned_sys(sys_location): # 需要再升一级返回“../”+calculate_relative_path(sys_location, target_path) 其他：返回计算相对路径（系统位置，目标路径） **跨层链接修复**：来源 |目标|链接模式 ---|---|--- 系统|美国存托凭证 | `../05_ADR/ADR-NN.md` 系统|需求 | `../07_REQ/REQ-NN.md` 系统|点击率| `../08_CTR/CTR-NN.md` ** ** ### 第 3 阶段：修复元素 ID 将无效的元素 ID 转换为正确的格式。 **转换规则**：图案|问题 |转换 ---|---|--- `SYS.NN.06.SS` |代码 06 对 SYS 无效 | `SYS.NN.17.SS`（组件） `COMP-XXX` |遗留模式| `系统.NN.17.SS` `INT-XXX` |遗留模式| `系统.NN.18.SS` `MOD-XXX` |遗留模式| `系统.NN.19.SS` `DEP-XXX` |遗留模式| `SYS.NN.20.SS` `FLOW-XXX` |遗留模式| `SYS.NN.21.SS` **类型代码映射**（SYS 特定的有效代码：01、05、17、18、19、20、21）：代码|元素类型 |描述 ---|---|--- 01 |功能需求|系统功能规范 05 |使用案例|系统用例 17 | 17组件|系统组成 18 |接口 |系统界面 19 | 19模块|软件模块 20 |依赖|外部依赖 21 | 21数据流|数据流规范 **无效的代码转换**：无效代码 |有效代码 |元素类型 ---|---|--- 06 | 01 |功能要求（是验收标准） 13 | 17 | 17组件（是决策上下文） 14 | 14 18 |界面（是决策声明） 22 | 22 19 | 19模块（原为功能项） **正则表达式模式**： # 查找 SYS 类型代码无效的元素 ID invalid_sys_type_06 = r'SYS\.(\d{2})\.06\.(\d{2})' replacement_06 = r'SYS.\1.01.\2' invalid_sys_type_13 = r'SYS\.(\d{2})\.13\.(\d{2})' replacement_13 = r'SYS.\1.17.\2' # 查找遗留模式 Legacy_comp = r'###\s+COMP-(\d+):' Legacy_int = r'###\s+INT-(\d+):' Legacy_mod = r'###\s+MOD-(\d+):' Legacy_dep = r'###\s+DEP-(\d+):' Legacy_flow = r'###\s+FLOW-(\d+):' ** ** ### 第 4 阶段：修复内容问题解决占位符和不完整的内容。 **修复操作**：问题代码 |问题 |修复行动 ---|---|--- REV-P001 | `[TODO]` 占位符 |手动完成标记（无法自动修复） REV-P002 | `[TBD]` 占位符 |手动完成标记（无法自动修复） REV-P003 |模板日期`YYYY-MM-DD` |替换为当前日期 REV-P004 |模板名称 `[名称]` |替换为元数据作者或标志 REV-P005 |空部分|添加最少模板内容 REV-P006 |缺少组件状态 |添加“草稿”为默认状态 **自动更换**：替换={ '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'), '[状态]': '草稿', '[版本]': '0.1', } **系统特定内容修复**：部分|缺少内容 |自动填充 ---|---|--- 状态 |空 | “草稿” 版本 |空 | “0.1” 最后更新 |空 |当前日期组件类型 |空 | “[指定类型]” ** ** ### 第 5 阶段：更新参考文献确保可追溯性和交叉引用正确。 **修复操作**：问题 |修复行动 ---|--- 创建的文件缺少`@ref:` |添加参考标签跨系统路径不正确 |更新以正确的相对路径缺少 ADR 可追溯性 |添加`@trace：ADR-NN.SS`标签缺少 REQ 前向参考 |添加`@trace：REQ-NN.SS`标签 **可追溯性矩阵更新**： ## 可追溯性 |系统元素|痕迹来自 |追踪至 |类型 | |------------|-------------|------------|-----| |系统.01.17.01 | ADR.01.14.01 | REQ.01.01.01 |组件->要求| |系统.01.18.01 | ADR.01.14.02 |点击率.01.09.01 |界面->合约| ** ** ### 第 6 阶段：处理上游漂移（自动合并）解决了自 SYS 创建以来上游源文档 (ADR) 发生更改的问题。使用基于更改百分比的分层自动合并系统。 #### 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 |找不到上游文件 |部分|错误 ** ** **上游**：ADR（架构决策记录） **下游**：REQ（需求规范） **ID 模式**：`SYS.NN.TT.SS`（文档.类型.序列） #### 分层自动合并系统等级 |变化% |行动|版本影响 ---|---|---|--- 1 级 | < 5% |自动合并添加 |补丁（+0.0.1） 2 级 | 5-15% |自动合并详细的变更日志 |次要 (+0.1.0) 第 3 级 | > 15% |归档电流，触发再生|主要 (+1.0.0) #### 变化百分比计算 defcalculate_change_percentage(upstream_diff: dict) -> float: """计算上游 ADR 修改的变化百分比。参数： upload_diff：包含添加、修改、弃用计数的字典返回：变化百分比（0.0 至 100.0） ”“” 总元素=upstream_diff.get('total_elements', 0) 如果总元素 == 0：返回 0.0 添加=upstream_diff.get('添加', 0) 修改=upstream_diff.get('修改', 0) 已弃用 = upload_diff.get('已弃用', 0) # 添加的数量少于修改的数量 Weighted_changes = (添加 * 0.5) + (修改 * 1.0) + (弃用 * 0.3) 返回最小值（100.0，（加权变化/总元素）* 100） #### 第 1 层：自动合并添加 (< 5%) **触发器**：ADR 中的少量添加，不会影响现有的 SYS 元素。 **行动**： 1.解析新的ADR决策/约束 2. 生成新的SYS元素ID（自动递增序列） 3. 在适当的部分插入新元素 4. 增加补丁版本（例如，1.0.0 -> 1.0.1） **自动生成的 ID 模式**： defgenerate_sys_id(sys_doc_num:str,type_code:str,existing_ids:list)->str: """生成下一个可用的 SYS 元素 ID。参数： sys_doc_num：文档编号（例如“01”） type_code：元素类型代码（例如，“17”表示组件）现有_ids：该类型的现有ID列表返回：下一个可用 ID（例如“SYS.01.17.13”） ”“” # 从现有 ID 中提取序列号序列= [int(id.split('.')[-1]) 为现有_ids 中的 id if id.startswith(f'SYS.{sys_doc_num}.{type_code}.')] next_seq = max(序列，默认=0) + 1 返回 f'SYS.{sys_doc_num}.{type_code}.{next_seq:02d}' # 示例：如果 SYS-01 具有 SYS.01.17.01 到 SYS.01.17.12 # 新 ID：SYS.01.17.13 **第 1 层修复报告条目**： ## 应用第 1 层自动合并 |美国存托凭证来源 |新系统元素 |部分|描述 | |------------|-----------------|---------|-------------| | ADR-05.14.01 |系统.01.17.13 |组件|新的身份验证缓存组件 | | ADR-01.14.06 |系统.01.18.08 |接口|新的事件总线接口| **版本**：1.0.0 -> 1.0.1 **变化百分比**：3.2% #### 第 2 层：自动合并变更日志 (5-15%) **触发器**：需要记录但不需要重组的适度更改。 **行动**： 1. 应用所有第 1 层操作 2. 生成详细的变更日志部分 3.更新追溯矩阵 4.向受影响的元素添加“[MODIFIED]”标记 5. 增加次要版本（例如，1.0.1 -> 1.1.0） **变更日志格式**： ## 变更日志（自动生成） ### 版本1.1.0 (2026-02-10) **上游触发器**：ADR-01.md v2.0（2026-02-09 修改） #### 添加 - SYS.01.17.13：身份验证缓存组件（来自 ADR-01.14.05） - SYS.01.17.14：速率限制组件（来自 ADR-01.14.06） - SYS.01.18.08：事件总线接口（来自ADR-01.14.07） ####修改 - SYS.01.17.03：更新了身份验证流程以包含缓存[已修改] - SYS.01.18.02：向 API 接口添加速率限制标头 [已修改] #### 已弃用 - 无 **可追溯性影响**：可能需要审查 5 个 REQ 要素 **修改的元素标记**： ### SYS.01.17.03：身份验证服务[已修改] **组件**：身份验证服务 **状态**：活跃 **修改原因**：ADR-01 添加了缓存要求 [组件详细信息...] #### 第 3 层：存档和重新生成 (> 15%) **触发器**：需要 SYS 重组的重大上游变化。 **行动**： 1.创建当前SYS版本的存档 2. 生成归档清单 3. 通过 `doc-sys-autopilot` 进行再生标记 4. 增加主要版本（例如，1.1.0 -> 2.0.0） 5. 使用“[DEPRECATED]”标记保留已弃用的元素 **存档清单格式**： { "archive_id": "SYS-01_v1.1.0_20260210", "archive_date": "2026-02-10T16:30:00", “存档版本”：“1.1.0”， “新版本”：“2.0.0”， "archive_location": "tmp/archive/SYS-01_v1.1.0_20260210/", “触发”：{ "upstream_document": "ADR-01.md", "upstream_version": "3.0", “变化百分比”：23.5， “等级”：3 }, “保留的文件”：[ “SYS-01.md”， “SYS-01.1_components.md”， “SYS-01.2_interfaces.md” ], “regenesis_required”：正确， “regenesis_command”：“/doc-sys-autopilot ADR-01 --来自存档SYS-01_v1.1.0_20260210” } **存档目录结构**： tmp/存档/SYS-01_v1.1.0_20260210/ ├── MANIFEST.json ├── SYS-01.md ├── SYS-01.1_components.md ├── SYS-01.2_interfaces.md ├── .drift_cache.json └── 变更日志.md #### 禁止删除政策自动合并期间永远不会删除元素。相反，标记为已弃用： **已弃用的元素格式**： ### SYS.01.17.05：旧版缓存服务 [已弃用] > **状态**：已弃用 - 请勿在新实现中使用 > **取代**：[SYS.01.17.13](#sys011713-authentication-cache) > **弃用日期**：2026-02-10 【原创内容保留供参考...】 **弃用跟踪**： ## 已弃用的元素 |元素 ID |已弃用 |原因 |替换为 | |------------|------------|--------|------------| |系统.01.17.05 | 2026-02-10 | ADR-01.14.05 取代 |系统.01.17.13 | |系统.01.18.03 | 2026-02-10 |界面重新设计|系统.01.18.08 | #### 增强型漂移缓存处理漂移问题后，使用合并历史更新“.drift_cache.json”： { "sys_version": "1.1.0", “sys_updated”：“2026-02-10T16:30:00”， “drift_reviewed”：“2026-02-10T16:30:00”， "upstream_type": "ADR", "downstream_type": "REQ", “upstream_hashes”：{ "../../05_ADR/ADR-01.md": "a1b2c3d4e5f6...", "../../05_ADR/ADR-01.md#decision-3": "g7h8i9j0k1l2...", “../../05_ADR/ADR-03.md”：“m3n4o5p6q7r8...” }, “合并历史记录”：[ { "merge_date": "2026-02-10T16:30:00", “等级”：2， “变化百分比”：8.5， "version_before": "1.0.1", "version_after": "1.1.0", "elements_added": ["SYS.01.17.13", "SYS.01.18.08"], "elements_modified": ["SYS.01.17.03", "SYS.01.18.02"], “elements_deprecated”：[]， "upstream_trigger": "ADR-01.md v2.0" } ], “acknowledged_drift”：[ { “文档”：“ADR-03.md”， “acknowledged_date”：“2026-02-08”， "reason": "仅供参考 - 无 SYS 影响" } ], “pending_regenesis”：空 } #### 漂移检测问题代码代码|严重性 |描述 |等级 |自动修复 ---|---|---|---|--- REV-D001 |信息 |少量 ADR 增加（< 5% 影响）| 1 |是的 REV-D002 |警告| ADR 适度变化（影响 5-15%）| 2 |是的 REV-D003 |错误 |主要 ADR 重组（影响 > 15%）| 3 |部分 REV-D004 |信息 |新 ADR 添加到项目 | 1 |是的 REV-D005 |警告| ADR 版本增加 | 1-3 | 1-3视情况而定 #### 漂移修复工作流程流程图TD A[检测 ADR 变化] --> B[计算变化%] B --> C{变化 < 5%？} C -->|是| D[第 1 层：自动合并] C -->|否| E{变化 < 15%？} E -->|是| F[第 2 层：合并 + 变更日志] E -->|否| G[第 3 层：存档 + 重新生成] D --> H[生成新 ID] H --> I[插入元素] I --> J[补丁版本++] F --> K[应用第 1 层操作] K --> L[生成变更日志] L --> M[添加修改标记] M --> N[次要版本 ++] G --> O[创建存档] O --> P[生成清单] P --> Q[再生标记] Q --> R[主要版本 ++] J --> S[更新漂移缓存] N --> S R-->S S --> T[生成修复报告] #### 漂移处理的命令选项选项|默认 |描述 ---|---|--- `--自动合并` |真实 |启用分层自动合并系统 `--merge-tier` |汽车 |强制特定层（1、2、3 或自动） `--承认漂移` |假 |交互式漂移确认模式 `--存档路径` | tmp/存档/ |第 3 级档案的位置 `--preserve-已弃用` |真实 |保留已弃用的元素（不删除政策） `--changelog-detail` |标准|变更日志详细程度（最小、标准、详细） `--通知下游` |真实 |标记 REQ 文档以供合并后审核 ** ** ## 命令用法 ### 基本用法 # 根据最新评论修复 SYS /doc-sys-fixer SYS-01 # 修复明确的审查报告 /doc-sys-fixer SYS-01 --review-report SYS-01.R_review_report_v001.md # 修复并重新运行审核 /doc-sys-fixer SYS-01 --重新验证 # 修复迭代限制 /doc-sys-fixer SYS-01 --revalidate --max-iterations 3 ### 选项选项 |默认 |描述 ---|---|--- `--审查报告` |最新 |使用的具体审查报告 `--重新验证` |假 |修复后运行审阅者 `--最大迭代次数` | 3 |最大修复审查周期 `--修复类型` |全部 |特定修复类型（以逗号分隔） `--创建缺失` |真实|创建缺失的参考文件 `--备份` |真实|修复前备份SYS `--试运行` |假 |预览修复而不应用 `--承认漂移` |假 |交互式漂移确认模式 `--更新漂移缓存` |真实|修复后更新 .drift_cache.json ### 修复类型类型 |描述 ---|--- `丢失的文件` |创建缺失的索引、组件、接口文档 `损坏的链接` |修复链接路径 `element_ids` |转换无效/旧元素 ID `内容` |修复占位符、日期、状态 `参考文献` |更新可追溯性和交叉引用 ‘漂移’ |处理上游漂移检测问题 `全部` |所有修复类型（默认） ** ** ## 输出工件 ### 修复报告 **嵌套文件夹规则**：所有 SYS 使用嵌套文件夹 (`SYS-NN_{slug}/`)，无论大小如何。修复报告与 SYS 文档一起存储在嵌套文件夹中。 **文件命名** : `SYS-NN.F_fix_report_vNNN.md` **位置**：在 SYS 嵌套文件夹内：`docs/06_SYS/SYS-NN_{slug}/` **结构**： --- 标题：“SYS-NN.F：修复报告 v001” 标签： - 系统 - 修复报告 - 质量保证自定义字段： document_type：修复报告工件类型：SYS-FIX 层数：6 父文档：SYS-NN 源评论：SYS-NN.R_review_report_v001.md fix_date: "YYYY-MM-DDTHH:MM:SS" fix_tool：文档系统修复程序修复版本：“1.0” --- # SYS-NN 修复报告 v001 ## 总结 |公制|价值| |--------|--------| |来源评论 | SYS-NN.R_review_report_v001.md | |审查中的问题 | 15 | 15 |已解决的问题 | 12 | 12 |剩余问题 | 3（需要人工审核）| |文件已创建 | 3 | |文件修改 | 4 | ## 文件已创建 |文件|类型 |地点 | |------|------|----------| | SYS-00_INDEX.md |系统索引|文档/06_SYS/ | | COMP_AuthService.md |组件占位符 |文档/00_REF/组件/ | | INT_UserAPI.md |界面占位符|文档/00_REF/接口/ | ## 应用的修复 | ＃|问题代码 |问题 |修复已应用 |文件| |---|------------|--------|-------------|-----| | 1 | REV-L001 |损坏的索引链接 |创建 SYS-00_INDEX.md | SYS-01.md | | 2 | REV-L001 |损坏的组件链接 |创建占位符 COMP 文件 | SYS-01.md | | 3 | REV-N004 |元素类型 06 无效 |转换为 01 型 | SYS-01.md | | 4 | REV-L003 |使用绝对路径|转换为相对| SYS-02.md | | 5 | REV-N004 |旧版 COMP-XXX 模式 |转换为 SYS.NN.17.SS | SYS-01.md | ## 需要人工审核的问题 | ＃|问题代码 |问题 |地点 |原因 | |---|------------|--------|----------|--------| | 1 | REV-P001 | [TODO] 占位符 | SYS-01：L67 |需要系统专业知识| | 2 | REV-D001 |检测到 ADR 漂移 | SYS-01：L145 |审查架构变更 | | 3 | REV-R001 |缺少接口合约 | SYS-01：L200 |定义 API 合约 | ## 修复后验证 |公制|之前 |之后|达美航空 | |--------|--------|--------|--------| |评论分数 | 85 | 85 94 | 94 +9 | |错误 | 4 | 0 | -4 | |警告| 6 | 3 | -3 | ## 后续步骤 1.完成COMP_AuthService.md占位符 2.完成INT_UserAPI.md占位符 3. 处理剩余的 [TODO] 占位符 4. 审查 ADR 漂移并根据需要更新系统设计 5. 运行“/doc-sys-reviewer SYS-01”来验证修复 ** ** ## 与自动驾驶仪集成该技能由审核 -> 修复周期中的“doc-sys-autopilot”调用：流程图LR 子图 Phase5[“第 5 阶段：审查和修复周期”] A[doc-sys-reviewer] --> B{分数 >= 90?} B -->|否| C[文档系统修复程序] C --> D{迭代 < 最大值？} D -->|是|一个 D -->|否| E[手动审核标志] B -->|是| F[通过] 结束 **自动驾驶仪集成点**：相|行动|技能 ---|---|--- 5a 阶段 |进行初步审查 | `文档系统审阅者` 5b 阶段 |如果发现问题，请应用修复程序 | `文档系统修复程序` 5c 阶段 |重新运行审核 | `文档系统审阅者` 5d 阶段 |重复直到通过或最大迭代 |循环 ** ** ## 错误处理 ### 恢复行动错误 |行动 ---|--- 未找到审查报告 |提示先运行 `doc-sys-reviewer` 无法创建文件（权限）|记录错误，继续其他修复无法解析审核报告 |中止并显示明确的错误消息超出最大迭代次数 |生成报告、标记以供手动审核 ### 备份策略在应用任何修复之前： 1. 在 `tmp/backup/SYS-NN_YYYYMMDD_HHMMSS/` 中创建备份 2.将所有SYS文件复制到备份位置 3. 对原始文件应用修复 4. 如果修复过程中出现错误，请从备份恢复 ** ** ## 相关技能技能|关系 ---|--- `文档系统审计` |提供首选的组合审计报告输入 `文档系统审阅者` |提供审查报告（输入） `doc-sys-自动驾驶仪` |协调审核 -> 修复周期 `文档系统验证器` |结构验证 `文档命名` |元素 ID 标准 `文档系统` | SYS创建规则 `doc-adr` |上游架构决策 `文档请求` |下游需求参考 ** ** ## 版本历史版本 |日期 |变化 ---|---|--- 2.2 | 2.2 2026-02-27 |将 frontmatter 迁移到“元数据”；更正了上游报告合同以使用审计/审查报告（首选“.A_”，“.R_”旧版）；标准化报告位置路径为“docs/06_SYS” 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（SYS.NN.TT.SS 模式）；带有 [DEPRECATED] 标记的不删除政策；存档清单创建；增强了带有合并历史记录的漂移缓存； ADR上游/REQ下游整合 1.0 | 2026-02-10 |初始技能创造； 6 阶段修复工作流程； SYS索引、组件和接口文件创建；元素ID转换（类型01、05、17、18、19、20、21）；修复了损坏的链接； ADR上游漂移处理；与自动驾驶仪集成审核->修复周期 ## 实施计划一致性 (IPLAN-004) * 将计划派生的输出视为有效的源模式，并验证实施计划范围/目标的意图保留。 * 验证上游自动驾驶仪优先级假设：`--iplan > --ref > --prompt`。 * 将计划上下文和工件输出之间的目标/范围冲突标记为需要澄清的阻塞问题。 * 不要引入旧的后备路径，例如“docs-v2.0/00_REF”。

文档系统修复程序

包含技能