# 文档-brd-修复程序 ## 目的自动**修复技能**，读取最新的审计报告并对 BRD 文档应用修复。此技能弥合了“doc-brd-audit”（用于识别问题）和更正的 BRD 之间的差距，从而实现迭代改进周期。 **层**：1（BRD 质量改进） **上游**：BRD 文件、审计报告 (`BRD-NN.A_audit_report_vNNN.md`) **下游**：修复 BRD，修复报告 (`BRD-NN.F_fix_report_vNNN.md`) **2-技能模型**：仅存在“doc-brd-audit”和“doc-brd-fixer”。已弃用的“doc-brd-validator”和“doc-brd-reviewer”已合并到“doc-brd-audit”中。 ** ** ## 何时使用此技能在以下情况下使用“doc-brd-fixer”： * **审核后** ：在 `doc-brd-audit` 识别问题后运行（失败状态） * **迭代改进**：审计的一部分→修复→审计周期 * **自动化管道**：用于质量关卡的 CI/CD 集成 * **批量修复** ：根据审核报告将修复应用于多个 BRD **请勿在以下情况下使用**： * 不存在审计报告（首先运行 `doc-brd-audit`） * 创建新的 BRD（使用 `doc-brd` 或 `doc-brd-autopilot`） * BRD 已通过审核（分数 >= 90） ** ** ## 技能依赖技能|目的|使用时 ---|---|--- `doc-brd-审计` |要修复的问题来源（必需）|输入（读取审计报告） `文档命名` |元素 ID 标准 |修复元素 ID `doc-brd` | BRD创建规则|创建缺失的部分 **2 技能模型** : 技能|目的 ---|--- `doc-brd-审计` |所有验证 + 评分（从头开始运行） `doc-brd-修复程序` |应用审计报告中的修复（此技能） **已弃用**：“doc-brd-validator”和“doc-brd-reviewer”已合并到“doc-brd-audit”中。 **输入**：最新的`BRD-NN.A_audit_report_vNNN.md` ** ** ## 工作流程概述流程图TD A[输入：BRD 路径] --> B[查找最新审计报告] B --> C{审计发现？} C -->|否| D[首先运行 doc-brd-audit] 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[写入固定 BRD] L --> M[生成修复报告] M --> N{重新运行审核？} N -->|是| O[从头开始调用 doc-brd-audit] O --> P{分数 >= 阈值？} P -->|否，迭代次数 < max| F P -->|是|问[完成] N -->|否|问 ** ** ## 修复阶段 ### 第 0 阶段：修复结构违规（严重）修复了不在嵌套文件夹中的 BRD。此阶段首先运行，因为所有后续阶段都依赖于正确的文件夹结构。 **嵌套文件夹规则**：无论文档大小如何，所有 BRD 都必须位于嵌套文件夹中。 **所需结构**： BRD型 |所需地点 ---|--- 整体| `docs/01_BRD/BRD-NN_{slug}/BRD-NN_{slug}.md` 切片| `docs/01_BRD/BRD-NN_{slug}/BRD-NN.0_index.md`、`BRD-NN.1_*.md` 等 **修复操作**：问题代码 |问题 |修复行动 ---|---|--- REV-STR001 | BRD 不在嵌套文件夹中 |创建文件夹、移动文件、更新所有链接 REV-STR002 | BRD 文件夹名称与 BRD ID 不匹配 |重命名文件夹以匹配 REV-STR003 |应将 >25KB 的整体 BRD 进行分段 |手动审核标记 **结构修复工作流程**： def fix_brd_struct(brd_path: str) -> 列表[修复]: """修复 BRD 结构违规。""" 修复=[] 文件名 = os.path.basename(brd_path) 父文件夹 = os.path.dirname(brd_path) # 从文件名中提取 BRD ID 和 slug match = re.match(r'BRD-(\d+)_([^/]+)\.md', 文件名) 如果不匹配： return [] # 无法自动修复无效文件名 brd_id = match.group(1) slug = match.group（2） Expected_folder = f“BRD-{brd_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(brd_path, new_path) fixes.append(f"已将 {brd_path} 移动到 {new_path}") # 更新移动文件中的参考链接内容=路径(new_path).read_text() update_content = content.replace('../00_REF/', '../../00_REF/') 路径（新路径）.write_text（更新内容） Fixs.append(f“更新了嵌套文件夹结构的相对链接”) 返回修复 **移动后链接路径更新**：原始路径 |更新路径 ---|--- `../00_REF/foundation/spec.md` | `../../00_REF/foundation/spec.md` `BRD-00_GLOSSARY.md` | `../BRD-00_GLOSSARY.md` ** ** ### 第 1 阶段：创建丢失的文件创建被引用但不存在的文件。 **范围**：丢失文件 |行动|使用的模板 ---|---|--- `BRD-00_GLOSSARY.md` |创建主词汇表 |词汇表模板 `GAP_*.md` |使用 TODO 部分创建占位符 |差距模板参考文档 (`*_REF_*.md`) |创建占位符 |参考模板 **术语表模板**： --- 标题：“BRD-00：词汇表大师” 标签： - BRD - 词汇表 - 参考自定义字段： document_type：术语表 artifact_type：BRD-REFERENCE 层数：1 --- # BRD-00：主术语表所有业务需求文档中使用的通用术语。 ## 商业术语 |术语 |定义|背景 | |------|------------|---------| | MVP |最小可行产品|范围定义 | |服务水平协议 |服务水平协议|质量要求| |关键绩效指标|关键绩效指标|成功指标| ## 技术术语 |术语 |定义|背景 | |------|------------|---------| |应用程序接口 |应用程序编程接口|整合| |智威汤逊 | JSON 网络令牌 |认证| |海外开发公司 | OpenID 连接 |身份联合| ## 域名术语 |术语 |定义|背景 | |------|------------|---------| | [术语] | [定义] | [使用地点] | **差距分析占位符模板**： --- 标题：“差距分析：[模块名称]” 标签： - 差距分析 - 参考自定义字段： document_type：差距分析状态：占位符创建者：doc-brd-fixer --- # 差距分析：[模块名称] > **状态**：占位符 - 需要完成 ## 1. 当前状态 [TODO：记录当前实施状态] ## 2. 已识别的差距 |间隙 ID |描述 |优先|状态 | |--------|-------------|----------|--------| | GAP-XX-01 | [说明] | P1/P2/P3 |打开| ## 3. 补救计划 [TODO：文档修复方法] --- *由 doc-brd-fixer 作为占位符创建。完成本文档以解决断开的链接问题。* ** ** ### 第 2 阶段：修复损坏的链接更新链接以指向正确的位置。 **修复操作**：问题代码 |问题 |修复行动 ---|---|--- REV-L001 |内部链接失效 |更新路径或创建目标文件 REV-L002 |外部链接无法访问 |添加警告评论，保留链接 REV-L003 |使用绝对路径|转换为相对路径 **路径解析逻辑**： def fix_link_path(brd_location: str, target_path: str) -> str: """根据 BRD 位置计算正确的相对路径。""" # 整体 BRD：docs/01_BRD/BRD-01.md # 分段 BRD：docs/01_BRD/BRD-01_slug/BRD-01.3_section.md 如果 is_sectioned_brd(brd_location): # 需要再升一级返回“../”+calculate_relative_path(brd_location,target_path) 其他：返回计算相对路径（brd_location，目标路径） **词汇表链接修复**： BRD型 |原文链接 |固定链接 ---|---|--- 整体| `BRD-00_GLOSSARY.md` | `BRD-00_GLOSSARY.md` 切片| `BRD-00_GLOSSARY.md` | `../BRD-00_GLOSSARY.md` ** ** ### 第 3 阶段：修复元素 ID 将无效的元素 ID 转换为正确的格式。 **转换规则**：图案|问题 |转换 ---|---|--- `BRD.NN.25.SS` |代码 25 对 BRD 无效 |手动重新映射到上下文适当的有效 BRD 代码（`23`、`24`、`22`、`08` 等） `BO-XXX` |遗留模式| `BRD.NN.23.SS` `FR-XXX` |遗留模式| `BRD.NN.01.SS` 'AC-XXX' |遗留模式| `BRD.NN.06.SS` `BC-XXX` |遗留模式| `BRD.NN.03.SS` **类型代码映射**（BRD 特定）：无效代码 |有效代码 |元素类型 ---|---|--- 19 | 19 22 | 22功能项（已弃用 19） 31 | 32 | 32架构主题（已弃用 31）对于 BRD 上下文中的代码“25”，不会自动转换为固定代码；按部分语义分类并手动重新映射。 **正则表达式模式**： # 查找 BRD 类型代码无效的元素 ID invalid_brd_type_25 = r'BRD\.(\d{2})\.25\.(\d{2})' # BRD 25 型无固定替代品；需要部分感知的重新映射 # 查找遗留模式 Legacy_bo = r'###\s+BO-(\d+):' Legacy_fr = r'###\s+FR-(\d+):' ** ** ### 第 4 阶段：修复内容问题解决占位符和不完整的内容。 **修复操作**：问题代码 |问题 |修复行动 ---|---|--- REV-P001 | `[TODO]` 占位符 |手动完成标记（无法自动修复） REV-P002 | `[TBD]` 占位符 |手动完成标记（无法自动修复） REV-P003 |模板日期`YYYY-MM-DD` |替换为当前日期 REV-P004 |模板名称 `[名称]` |替换为元数据作者或标志 REV-P005 |空部分|添加最少模板内容 REV-MVP001 |缺少“2.1 MVP 假设”|添加带有假设和可测量验证信号的明确小节 REV-MVP002 |缺少“3.2 MVP 核心功能” |添加明确的小节和清单；保留现有范围详细信息 REV-MVP003 |缺少“9.1 MVP 发布标准”|添加显式的通过/不通过启动门表 REV-MVP004 |缺少“14.5 批准和签署” |添加利益相关者签核表 REV-MVP008 |缺少测试覆盖率可追溯性 |添加显式的“16.3 测试覆盖率可追溯性”视图 REV-MVP010 |缺少词汇表结构 17.1-17.6 |添加缺失的术语表小节而不删除现有术语 **自动更换**：替换={ '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'), } #### 4.1 MVP 小节语义规范化（v2.4 中的新功能）在添加新的小节之前，请检测等效标题并就地标准化以避免重复内容。必填标题 |可接受的等效模式 ---|--- `2.1 MVP 假设` | `2.1 背景和背景`, `2.1 假设` `3.2 MVP 核心特性` | `3.2 范围内项目`, `3.2 范围项目` `9.1 MVP 发布标准` | “9.1 业务验收标准”、“9.1 启动准备情况” **标准化规则**： 1. 如果存在等效标题，请将标题重命名为所需的规范标题。 2. 保留该部分下的现有表格/列表内容。 3. 仅当部分内容缺失或低于最小结构时才插入模板块。 #### 4.2 安全分段重新编号（v2.4 中的新增功能）插入缺少的所需小节编号时，请对后续同级小节执行确定性重新编号。 def renumber_sibling_headings（内容：str，section_prefix：str，insert_at：float）-> str： """在插入点之后移动同级小节编号。示例：插入 9.1 -> 现有 9.1 变为 9.2，9.2 变为 9.3。 ”“” # 1) 解析匹配 '^##\s+{section_prefix}\.\d+' 的标题 # 2) 从最高到最低分段编号进行处理 # 3) 仅增加同级>= insert_at # 4) 不要修改超出父前缀的子小节标识符返回内容 **安全限制**： * 仅适用于同一节文件内。 * 当显式交叉引用锚点被破坏时，跳过重新编号（标记手动审查）。 * 在修复报告中记录所有重新编号操作。 #### 4.3 合规合同模板（v2.5 中的新增功能）所有内容修复必须符合规范模板： * `docs_flow_framework/ai_dev_ssd_flow/01_BRD/BRD-MVP-TEMPLATE.md` * `docs_flow_framework/ai_dev_ssd_flow/01_BRD/BRD-MVP-TEMPLATE.yaml` **规范分段锚点 (MVP)** ：部分|所需的锚点 ---|--- 1 | 1.1-1.4 2 | 2.1-2.5 3 | 3.1-3.5，**3.4.1**，**3.4.2** 5 | 5.1-5.2 6 | 6.1-6.5 8 | 8.1-8.2 9 | 9.1-9.2 11 | 11 11.1-11.2 12 | 12 12.1-12.3 14 | 14 14.1-14.5 15 | 15 15.1-15.3 16 | 16 16.1-16.4 17 | 17 17.1-17.6（17.5 交叉引用，17.6 外部标准） 18 | 18 18.1-18.5 如果现有标题使用旧名称，请在验证之前规范化为模板规范标签。 ** ** ### 第 5 阶段：更新参考文献确保可追溯性和交叉引用正确。 **修复操作**：问题 |修复行动 ---|--- 创建的文件缺少`@ref:` |添加参考标签跨 BRD 路径不正确 |更新以正确的相对路径缺少追溯条目 |添加到追溯矩阵 #### 5.1 生成报告的 Markdown 标准化（v2.4 中的新增功能）标准化修复程序生成的降价伪像以减少 lint 摩擦。 **范围**： * 修复/修复验证报告标题（YAML frontmatter 下的“##”标题） * 表分隔符样式规范化 * 列表和表格周围有空行 **适用于**： * `BRD-NN.F_fix_report_vNNN.md` * 任何修复程序生成的补充说明 ** ** ### 阶段 5.5：修复置信度分类（v2.4 中的新增功能）每个修复操作都被标记为下游门控。信心|意义|典型例子 ---|---|--- `自动安全` |具有低语义风险的确定性结构/文本修复 |链接路径修正、节头标准化、ID 转换 `自动辅助` |具有部分语义假设的模板插入 |生成的启动标准表、术语表小节脚手架 `需要手动` |无法可靠地推断特定领域的内容 |未解决的 TODO/TBD、业务战略理由差距 **修复报告要求**： * 在“已应用的修复”表中添加“置信度”列。 * 包括按置信度划分的摘要计数。 ** ** ### 第 6 阶段：处理上游配置在处理漂移之前修复上游配置问题。 #### 6.0 元数据修复 **FIX-M001：添加缺少的 Deliverable_type** **触发器**：BRD 在 YAML frontmatter 中没有“deliverable_type” **修复操作**：将“deliverable_type: code”（默认）添加到“custom_fields” # 之前自定义字段： document_type: brd-文档工件类型：BRD # 之后自定义字段： document_type: brd-文档工件类型：BRD 可交付成果类型：代码 **FIX-M002：修复无效的 Deliverable_type** **触发器**：“deliverable_type”值不是以下之一：“code”、“document”、“ux”、“risk”、“process” **修复操作**：根据 BRD 内容分析建议正确的值或重置为“代码”（默认） # 之前自定义字段： Deliverable_type: 软件 # 无效 # 之后（自动检测或默认）自定义字段：可交付成果类型：代码 **基于内容的检测逻辑**： def detector_deliverable_type(brd_content: str) -> str: """从 BRD 内容中检测适当的 Deliverable_type。""" # 检查 UX 指标如果有（brd_content.lower() 中的 kw 为 ['线框'、'模型'、'用户界面'、'ui/ux'、'设计系统'] 中的 kw）：返回'ux' # 检查文档指标 if any(brd_content.lower() 中的 kw for ['用户指南', 'api 文档', '技术手册', '帮助内容'] 中的 kw): 返回“文档” # 检查风险/合规指标如果有（brd_content.lower() 中的 kw for ['风险评估'、'合规框架'、'审计跟踪'、'安全审计'] 中的 kw）：返回“风险” # 检查进程指标如果有（brd_content.lower() 中的 kw for ['工作流程自动化'、'流程改进'、'业务流程'、'操作程序'] 中的 kw）：返回“进程” # 默认为代码返回“代码” **FIX-M003：修复实例的 document_type** **触发器** ：BRD 实例具有 `document_type: template` 而不是 `document_type: brd-document` **修复操作**：更改为“brd-document” # 之前自定义字段： document_type: template # 例如错误 # 之后自定义字段： document_type: brd-文档 ** ** #### 6.1 上游配置修复 **FIX-U001：添加缺少的upstream_mode** **触发器**：BRD 在 YAML frontmatter 中没有 `upstream_mode` **修复操作**：将 `upstream_mode: "none"` 添加到 `custom_fields` # 之前自定义字段：工件类型：BRD # 之后自定义字段：工件类型：BRD 上游模式：“无” **FIX-U002：建议upstream_ref_path** **触发器**：BRD 有 `@ref:` 标签指向 `00_REF/` 但 `upstream_mode: "none"` **检测**： 1. 扫描 BRD 内容中的“@ref:”标签 2. 提取引用路径 3. 确定`00_REF/`中的公共父目录 **修复操作**：建议使用检测到的路径更新到 `upstream_mode: "ref"` # 建议的修复（需要确认）自定义字段：上游模式：“参考” 上游参考路径：“../../00_REF/source_docs/” **FIX-U003：删除无效的upstream_ref_path** **触发器** ： `upstream_mode: "none"` 但设置了 `upstream_ref_path` **修复操作**：删除 `upstream_ref_path` 字段（无论如何它都会被忽略） # 之前自定义字段：上游模式：“无” upload_ref_path: "../../00_REF/" # 忽略 # 之后自定义字段：上游模式：“无” **元数据修复代码**：代码|描述 |自动修复 ---|---|--- 固定-M001 |添加可交付类型：代码 |是的固定-M002 |修复无效的 Deliverable_type |自动检测或提示固定-M003 |将 document_type 修复为 brd-document |是的 **上游配置修复代码**：代码|描述 |自动修复 ---|---|--- 固定-U001 |添加upstream_mode：“无”|是的固定-U002 |建议upstream_mode：带有检测到的路径的“ref” |提示固定-U003 |删除不必要的upstream_ref_path |是的 ** ** #### 6.2 哈希验证修复修复了“.drift_cache.json”中阻止漂移检测正常工作的无效哈希值。 **FIX-H001：无效的哈希占位符** 领域|价值 ---|--- 触发|哈希字段包含占位符而不是实际的 SHA-256 检测|哈希匹配：`verified_no_drift`、`pending_verification`、`TBD` 或长度 != 64 hex 严重性 |错误自动修复 |是的 **检测算法**： # 检查漂移缓存中的占位符值 grep -E '"哈希":\s*"(sha256:)?(verified_no_drift|pending_verification|TBD)"' .drift_cache.json **修复操作**： # 计算上游文件的实际哈希值 HASH=$(sha256sum | cut -d' ' -f1) # 更新缓存： "hash": "sha256:$HASH" **示例**： // 之前（无效） “哈希”：“sha256：pending_verification” // 之后（有效） “哈希”：“sha256：a9ca05f4e9b2379465526221271672954feff29e40c57f2a91fe8a050eb46105” ** ** **FIX-H002：缺少哈希前缀** 领域|价值 ---|--- 触发|哈希值是 64 个十六进制字符，但缺少 `sha256:` 前缀检测|匹配不带前缀的 `^[0-9a-f]{64}$` 严重性 |警告自动修复 |是的 **修复操作**：将 `sha256:` 添加到现有哈希值 // 之前 “哈希”：“a9ca05f4e9b2379465526221271672954feff29e40c57f2a91fe8a050eb46105” // 之后 “哈希”：“sha256：a9ca05f4e9b2379465526221271672954feff29e40c57f2a91fe8a050eb46105” ** ** **FIX-H003：找不到上游文件** 领域|价值 ---|--- 触发|无法计算哈希，因为上游文件不存在检测| “upstream_ref_path”处的文件从 sha256sum 返回错误严重性 |错误自动修复 |部分 **修复操作**： 1. 日志警告：`找不到上游文件：<路径>` 2. 在缓存中设置 `drift_Detected: true` 3. 将哈希值设置为 `sha256:FILE_NOT_FOUND` 4. 添加注释到手动审核队列 ** ** **哈希修复代码摘要**：代码|描述 |自动修复 |严重性 ---|---|---|--- 固定-H001 |将占位符哈希替换为实际的 SHA-256 |是的 |错误固定-H002 |添加缺少的 sha256: 前缀 |是的 |警告固定-H003 |找不到上游文件 |部分|错误 ** ** ### 阶段 6.3：处理上游漂移（自动合并）根据更改百分比阈值自动将上游更改合并到文档中。 **注意**：此阶段仅在 `upstream_mode: "ref"` 时运行。当 `upstream_mode: "none"`（默认）时，将跳过漂移检测。 **漂移检测工作流程**：流程图TD A[检测上游变化] --> B[计算变化%] B --> C{变化分析} C -->|< 5%| D[第 1 层：自动合并] C -->|5-15%| E[第 2 层：自动合并 + 详细日志] C -->|> 15%| F[第 3 层：存档 + 重新生成] D --> D1[添加新要求] D1 --> D2[更新阈值] D2 --> D3[更新参考文献] D3 --> D4[增量补丁：1.0→1.0.1] E --> E1[添加新要求] E1 --> E2[更新阈值] E2 --> E3[更新参考文献] E3 --> E4[生成详细变更日志] E4 --> E5[增量小数：1.0→1.1] F --> F1[将当前标记为已存档] F1 --> F2[更新 frontmatter 状态] F2 --> F3[通过自动驾驶仪触发再生] F3 --> F4[主要增量：1.x→2.0] D4 --> G[更新漂移缓存] E5 --> G F4 --> G G --> H[添加到修复报告] ** ** #### 6.3.1 变化百分比计算 defcalculate_change_percentage(upstream_old: str,upstream_new: str) -> dict: ”“” 计算上游版本之间的更改百分比。返回： { 'total_change_pct': float, # 总体变化百分比 'additions_pct': float, # 添加新内容 'modifications_pct': float, # 修改现有内容 'deletions_pct': float, # 删除的内容（跟踪，未应用） 'change_type': str # '次要' | '中等' | ‘主要’ } ”“” old_lines = upload_old.strip().split('\n') new_lines = upload_new.strip().split('\n') # 使用 difflib 进行精确的变化检测导入差异库 diff = difflib.unified_diff(old_lines, new_lines) additions = sum(1 for line in diff if line.startswith('+') and not line.startswith('+++')) 删除 = sum(1 for line in diff if line.startswith('-') and not line.startswith('---')) 总行数 = max(len(旧行数), len(新行数)) Total_change_pct = ((添加 + 删除)/total_lines) * 100 如果total_lines > 0，否则为0 返回{ 'total_change_pct'：轮（total_change_pct，2）， 'additions_pct': round((additions/total_lines) * 100, 2) 如果total_lines > 0，否则为0， 'modifications_pct': round((min(添加、删除)/total_lines) * 100, 2) 如果total_lines > 0，否则为0， 'deletions_pct': round((删除/total_lines) * 100, 2) 如果total_lines > 0，否则为0， 'change_type': '次要' 如果total_change_pct < 5 否则'中等' 如果total_change_pct < 15 否则'主要' } ** ** #### 6.3.2 第 1 层：自动合并（< 5% 变化） **触发**：总变化百分比 < 5% **行动**：更改类型 |自动操作 |示例 ---|---|--- 添加新要求 |附加生成的 ID | `BRD.01.01.13` 阈值已更改 |查找和替换值 | `超时：30 → 45` 参考更新 |更新 `@ref:` 路径 |路径修正版本增加 |更新版本参考| `v1.2 → v1.3` **新要求的 ID 生成**： defgenerate_next_id（doc_type：str，doc_num：str，element_type：str，existing_ids：列表）-> str： ”“” 为新需求生成下一个顺序 ID。参数： doc_type：“BRD”、“PRD”等 doc_num：“01”、“02”等 element_type：“01”（功能）、“02”（质量）等。现有_ids：文档中现有ID的列表返回：下一个可用 ID（例如“BRD.01.01.13”） ”“” 模式= f“{doc_type}。{doc_num}。{element_type}。” 匹配 = [现有_ids 中的 id，如果 id.startswith(pattern)] 如果不匹配：返回f“{pattern}01” max_seq = max(int(id.split('.')[-1]) 用于匹配中的 id) 返回f“{模式}{str（max_seq + 1）.zfill（2）}” **新需求的自动合并模板**： ### {GENERATED_ID}：{要求标题} **来源**：从 {upstream_doc} ({change_date}) 自动合并 **要求**：{requirement_text} **验收标准**： {接受标准} **优先级**：{优先级} **版本更新**： * 增量补丁版本：`1.0`→`1.0.1` * 更新 frontmatter 中的 `last_updated` * 添加变更日志条目 ** ** #### 6.3.3 第 2 层：自动合并详细日志（5-15% 变化） **触发器**：总变化百分比在 5% 到 15% 之间 **操作**：与第 1 层相同，加上：额外行动|描述 ---|--- 详细变更日志 |逐节更改日志影响分析|哪些下游工件受到影响合并标记 | `` 注释版本历史 |详细的版本历史记录条目 **变更日志条目格式**： ## 变更日志 ### 版本 1.1 (2026-02-10T16:00:00) **上游同步**：自动合并上游文档的 8.5% 更改 |改变|来源 |部分|描述 | |--------|--------|---------|-------------| |添加| F1_IAM_技术_规范.md | 3.5 | 3.5新的密钥身份验证要求 | |更新 | F1_IAM_技术_规范.md | 4.2 |会话超时更改为 30→45 分钟 | |添加| GAP_Analysis.md | GAP-F1-07 | WebAuthn 发现新差距 | **添加新要求**： - BRD.01.01.13：密钥身份验证支持 - BRD.01.01.14：WebAuthn 后备机制 **更新阈值**： - BRD.01.02.05：session_idle_timeout：30→45 分钟 **影响**：PRD-01、EARS-01、ADR-01 可能需要审查 **版本更新**： * 增加次要版本：`1.0`→`1.1` * 更新 frontmatter 中的 `last_updated` * 添加详细的变更日志条目 ** ** #### 6.3.4 第 3 层：存档和重新生成（> 15% 更改） **触发**：总变化百分比 > 15% **行动**：步骤|行动|结果 ---|---|--- 1 |将当前版本标记为已存档 | frontmatter 状态更新 2 |创建存档副本 | `BRD-01_v1.0_archived.md` 3 |更新 frontmatter 状态 | `状态：已存档` 4 |触发自动驾驶仪再生 |新版本生成 5 |增加主要版本 | `1.x`→`2.0` **存档 Frontmatter 更新**： --- 标题：“BRD-01：F1 身份和访问管理” 自定义字段：版本：“1.2” status: "archived" # 从 'current' 更改存档日期：“2026-02-10T16:00:00” archived_reason：“upstream_drift_major” superseded_by：“BRD-01_v2.0” 上游变化百分比：18.5 --- **存档文件命名**：文档/01_BRD/BRD-01_f1_iam/ ├── BRD-01.0_index.md # 当前（v2.0） ├── BRD-01.1_core.md # 当前（v2.0） ├── .存档/ │ ├── v1.2/ │ │ ├── BRD-01.0_index.md # 已存档 v1.2 │ │ ├── BRD-01.1_core.md │ │ └── ARCHIVE_MANIFEST.md # 归档元数据 **ARCHIVE_MANIFEST.md**： # 存档清单：BRD-01 v1.2 |领域 |价值| |--------|--------| |存档版本 | 1.2 | 1.2 |存档日期 | 2026-02-10T16:00:00 | |原因 |上游漂移 > 15% (18.5%) | |取代 | v2.0 | |上游变化| F1_IAM_Technical_Specification.md（主要修订）| ## 变更摘要 |上游文档 |变化% |关键变化| |--------------------|----------|-------------| | F1_IAM_技术_规范.md | 18.5% |新的身份验证方法，修订的安全模型 | ## 下游影响再生后需要更新的文件： - PRD-01（参考BRD-01） - EARS-01（源自 PRD-01） - ADR-01（架构决策） **无删除政策**： * 标记为已删除的上游内容**不会**从文档中删除 * 相反，标有“[DEPRECATED]”状态： ### BRD.01.01.05：旧版身份验证方法 [已弃用] > **状态**：已弃用（上游已于 2026-02-10T16:00:00 删除） > **原因**：被 BRD.01.01.13 取代（密钥身份验证） > **操作**：保留以进行追溯；不实施 **原始要求**：{original_text} ** ** #### 6.3.5 漂移缓存更新处理漂移后，更新`.drift_cache.json`： { “文档版本”：“1.1”， “last_synced”：“2026-02-10T16:00:00”， "sync_status": "自动合并", “上游状态”：{ “../../00_REF/foundation/F1_IAM_Technical_Specification.md”：{ "哈希": "sha256:a1b2c3d4e5f6...", “版本”：“2.3”， “最后修改”：“2026-02-10T15:30:00”， “更改_pct”：4.2， “sync_action”：“tier1_auto_merge” }, “../../00_REF/foundation/GAP_Analysis.md”：{ “哈希”：“sha256：g7h8i9j0k1l2 ...”， “版本”：“1.5”， “最后修改”：“2026-02-10T14:00:00”， “change_pct”：8.7， “sync_action”：“tier2_auto_merge_detailed” } }, “合并历史记录”：[ { “日期”：“2026-02-10T16:00:00”， “等级”：1， “更改_pct”：4.2， “项目添加”：1， “items_updated”：2， "version_before": "1.0", “version_after”：“1.0.1” } ], “已弃用的项目”：[ { "id": "BRD.01.01.05", “deprecated_date”：“2026-02-10T16:00:00”， "reason": "上游移除", “replaced_by”：“BRD.01.01.13” } ] } ** ** #### 6.3.6 修复报告：漂移部分 **修复报告中的漂移摘要**： ## 第 6 阶段：上游漂移解决 ### 漂移分析总结 |上游文档 |变化% |等级 |采取的行动| |--------------------|----------|------|--------------| | F1_IAM_技术_规范.md | 4.2% | 1 |自动合并| | GAP_Analysis.md | 8.7% | 2 |自动合并（详细） | | F2_Session_Specification.md | 18.5% | 3 |已存档+重新生成| ### 第 1 层自动合并 (< 5%) |身份证 |类型 |来源 |描述 | |----|------|--------|-------------| | BRD.01.01.13 |添加| F1_IAM：3.5 |密钥验证支持 | | BRD.01.02.05 |更新 | F1_IAM：4.2 |会话超时 30→45 分钟 | ### 第 2 层自动合并 (5-15%) |身份证 |类型 |来源 |描述 | |----|------|--------|-------------| | BRD.01.01.14 |添加|间隙：GAP-F1-07 | WebAuthn 后备机制 | | BRD.01.07.04 |添加|间隙：GAP-F1-08 |新风险：凭证网络钓鱼 | ### 3 级档案 (> 15%) |文件|以前的版本 |新版本 |原因 | |----------|--------------------|-------------|--------| | BRD-01.2_requirements.md | 1.2 | 1.2 2.0 |上游变化18.5% | **存档位置**：`docs/01_BRD/BRD-01_f1_iam/.archive/v1.2/` ### 已弃用的项目（不删除） |身份证 |弃用日期 |原因 |替换为 | |----|-----------------|--------|-------------| | BRD.01.01.05 | 2026-02-10T16:00:00 |上游删除 | BRD.01.01.13 | ### 版本变更 |文件|之前 |之后|更改类型 | |------|--------|--------|-------------| | BRD-01.1_core.md | 1.0 | 1.0.1 |补丁（第 1 层）| | BRD-01.2_requirements.md | 1.0 | 1.1|未成年人（第 2 级）| | BRD-01.3_quality_ops.md | 1.2 | 1.2 2.0 |专业（第 3 级）| ** ** ## 命令用法 ### 基本用法 # 根据最新评论修复 BRD /doc-brd-修复程序 BRD-01 # 修复明确的审查报告 /doc-brd-fixer BRD-01 --review-report BRD-01.R_review_report_v001.md # 修复并重新运行审核 /doc-brd-fixer BRD-01 --重新验证 # 修复迭代限制 /doc-brd-fixer BRD-01 --revalidate --max-iterations 3 ### 选项选项 |默认 |描述 ---|---|--- `--审查报告` |最新 |使用的具体审查报告 `--重新验证` |假 |修复后运行审阅者 `--最大迭代次数` | 3 |最大修复审查周期 `--修复类型` |全部 |特定修复类型（以逗号分隔） `--创建缺失` |真实|创建缺失的参考文件 `--备份` |真实|修复前备份 BRD `--试运行` |假 |预览修复而不应用 `--标准化降价` |真实|规范化生成的报告 Markdown 样式 `--承认漂移` |假 |交互式漂移确认模式 `--更新漂移缓存` |真实|修复后更新 .drift_cache.json ### 修复类型类型 |描述 ---|--- `丢失的文件` |创建缺失的术语表、GAP、参考文档 `损坏的链接` |修复链接路径 `element_ids` |转换无效/旧元素 ID `内容` |修复占位符、日期、名称 `参考文献` |更新可追溯性和交叉引用 ‘漂移’ |处理上游漂移检测问题 `全部` |所有修复类型（默认） ** ** ## 报告清理政策（强制） **生成新的修复报告后，删除所有以前的修复报告。**旧报告没有任何作用，因为： * 每个修复周期都会生成一份完整的新报告 * 仅最新报告反映当前文档状态 * 多个旧报告使 BRD 文件夹变得混乱 ### 清理规则文件模式|行动|原因 ---|---|--- `BRD-NN.F_fix_report_v*.md`（旧版本）| **删除** |由新的修复报告取代 `BRD-NN.A_audit_report_v*.md` | **保留** |由“doc-brd-audit”管理 `.drift_cache.json` | **保留** |跟踪审查/修复历史元数据 ### 清理执行编写新的修复报告后，运行： # 在 BRD 文件夹中（例如 docs/01_BRD/BRD-50_octo_agent_orchestration/） BRD_FOLDER="$1" NEW_REPORT="$2" # 例如，BRD-50.F_fix_report_v003.md # 删除旧的修复报告（仅保留新的）找到“${BRD_FOLDER}”-名称“BRD-*.F_fix_report_v*.md”！ -名称“$(基本名称${NEW_REPORT})”-删除 ### 清理确认修复报告应包括清理摘要： ## 清理总结 - 删除：2 个旧修复报告（v001、v002） ** ** ## 输出工件 ### 修复报告 **嵌套文件夹规则**：所有 BRD 都使用嵌套文件夹 (`BRD-NN_{slug}/`)，无论大小如何。修复报告与 BRD 文档一起存储在嵌套文件夹中。 **文件命名** : `BRD-NN.F_fix_report_vNNN.md` **位置**：在 BRD 嵌套文件夹内：`docs/01_BRD/BRD-NN_{slug}/` **结构**： --- 标题：“BRD-NN.F：修复报告 v001” 标签： - BRD - 修复报告 - 质量保证自定义字段： document_type：修复报告工件类型：BRD-FIX 层数：1 父文档：BRD-NN 来源评论：BRD-NN.R_review_report_v001.md fix_date: "YYYY-MM-DDTHH:MM:SS" 修复工具：doc-brd-修复器修复版本：“1.0” --- # BRD-NN 修复报告 v001 ## 总结 |公制|价值| |--------|--------| |来源评论 | BRD-NN.R_review_report_v001.md | |审查中的问题 | 12 | 12 |已解决的问题 | 10 | 10 |剩余问题 | 2（需要人工审核）| |文件已创建 | 2 | |文件修改 | 4 | ## 文件已创建 |文件|类型 |地点 | |------|------|----------| | BRD-00_GLOSSARY.md |大师词汇表|文档/01_BRD/ | | GAP_Foundation_Module_Gap_Analysis.md | GAP 占位符 |文档/00_REF/基础/ | ## 应用的修复 | ＃|问题代码 |问题 |修复已应用 |文件| |---|------------|--------|-------------|-----| | 1 | REV-L001 |损坏的词汇表链接 |创建 BRD-00_GLOSSARY.md | BRD-01.3_quality_ops.md | | 2 | REV-L001 | GAP 链接损坏 |创建占位符 GAP 文件 | BRD-01.1_core.md | | 3 | REV-N004 |元素类型 25 无效 |使用节上下文手动重新映射 | BRD-01.1_core.md | | 4 | REV-L003 |使用绝对路径|转换为相对| BRD-01.2_requirements.md | ## 需要人工审核的问题 | ＃|问题代码 |问题 |地点 |原因 | |---|------------|--------|----------|--------| | 1 | REV-P001 | [TODO] 占位符 | BRD-01.2：L45 |所需领域知识 | | 2 | REV-R001 |缺少验收标准 | BRD-01.2：L120 |需要业务投入 | ## 修复后验证 |公制|之前 |之后|达美航空 | |--------|--------|--------|--------| |评论分数 | 92 | 92 97 | 97 +5 | |错误 | 2 | 0 | -2 | |警告| 4 | 1 | -3 | ## 后续步骤 1. 运行统一的 BRD 核心验证包装器： `bash ai_dev_ssd_flow/01_BRD/scripts/validate_brd_wrapper.sh docs/01_BRD --skip-advisory` 2. 完成GAP_Foundation_Module_Gap_Analysis.md占位符 3. 处理剩余的 [TODO] 占位符 4. 运行“/doc-brd-audit BRD-01”来验证修复 ** ** ## 与自动驾驶仪集成该技能由审计→修复周期中的“doc-brd-autopilot”调用：流程图LR 子图 Phase5[“第 5 阶段：审核和修复周期”] A[doc-brd-audit] --> B{分数 >= 90?} B -->|否| C[doc-brd-修复程序] C --> D{迭代 < 最大值？} D -->|是|一个 D -->|否| E[手动审核标志] B -->|是| F[通过] 结束 **自动驾驶仪集成点**：相|行动|技能 ---|---|--- 5a 阶段 |运行初步审核 | `doc-brd-审计` 5b 阶段 |如果发现问题，请应用修复程序 | `doc-brd-修复程序` 5c 阶段 |重新运行统一核心验证包装器 | `validate_brd_wrapper.sh` 5d 阶段 |重新运行审核 | `doc-brd-审计` 5e 阶段 |重复直到通过或最大迭代 |循环 ** ** ## 图合约修复规则当审阅者/审计报告包含图表合同结果时应用这些修复。问题代码 |修复行动 ---|--- REV-DC001 |插入缺少的强制性 BRD 标签：`@diagram: c4-l1` 和 `@diagram: dfd-l0` REV-DC002 |如果序列图存在，则插入一个序列契约标签：`@diagram:sequence-sync REV-DC003 |在强制图块上方添加缺少的意图标头字段：“diagram_type”、“level”、“scope_boundary”、“upstream_refs”、“downstream_refs” REV-DC004 |在描述数据边界移动的地方添加信任边界注释 **安全规则**： * 不要重写图表逻辑，除非语法无效。 * 优先对标题/标签进行最少的编辑，并保留现有的叙述语义。 ** ** ## 错误处理 ### 恢复行动错误 |行动 ---|--- 未找到审计报告 |提示先运行 `doc-brd-audit` 无法创建文件（权限）|记录错误，继续其他修复无法解析审核报告 |中止并显示明确的错误消息超出最大迭代次数 |生成报告、标记以供手动审核 ### 备份策略在应用任何修复之前： 1. 在 `tmp/backup/BRD-NN_YYYYMMDD_HHMMSS/` 中创建备份 2. 将所有 BRD 文件复制到备份位置 3. 对原始文件应用修复 4. 如果修复过程中出现错误，请从备份恢复 ** ** ## 相关技能技能|关系 ---|--- `doc-brd-审计` |提供审核报告（输入）-统一验证+评分 `doc-brd-自动驾驶仪` |协调审计 → 修复周期 `文档命名` |元素 ID 标准 `doc-brd` | BRD创建规则 **2-Skill 模型**：仅“doc-brd-audit”和“doc-brd-fixer”处于活动状态。已弃用的“doc-brd-validator”和“doc-brd-reviewer”已合并到“doc-brd-audit”中。 ** ** ## 版本历史版本 |日期 |变化 ---|---|--- 3.1| 2026-03-05 | **元数据修复**：添加了可交付类型验证修复的第 6.0 阶段（FIX-M001、FIX-M002、FIX-M003）；从内容中自动检测可交付类型（`code`、`document`、`ux`、`risk`、`process`）；修复实例的 document_type；重新编号第 6 阶段小节（6.1→6.1、6.0.1→6.2、6.1→6.3） 3.0 | 2026-03-05 | **报告清理策略**：在生成新报告后添加了对旧修复报告的强制清理；删除以前的“BRD-NN.F_fix_report_v*.md”文件；添加了清理摘要部分以修复报告 2.9 | 2.9 2026-03-01 | **2-技能模型**：更新了相关技能以仅引用“doc-brd-audit”；已弃用的“doc-brd-validator”和“doc-brd-reviewer”合并到统一审核中 2.7 | 2.7 2026-02-28 | **标准化验证器奇偶校验**：删除了`25→33`自动转换指导； BRD 中的代码“25”现在需要手动基于上下文的重新映射到有效的 BRD 代码，并与“validate_standardized_element_codes.py”对齐。 2.6 | 2.6 2026-02-27 | **哈希验证修复**：添加了第 6.0.1 节，包括 FIX-H001（通过 sha256sum 替换占位符）、FIX-H002（缺少前缀）、FIX-H003（未找到文件）；自动修复无效的哈希占位符，例如“verified_no_drift”和“pending_verification” 1.2 | 1.2 2026-02-26 | **基于统一模板的版本控制**：技能版本现在跟踪“ai_dev_ssd_flow/01_BRD/BRD-MVP-TEMPLATE”架构版本，以实现审阅者/修复者/自动驾驶仪的一致性。 2.5 | 2.5 2026-02-26 | **模板合同执行**：向 `ai_dev_ssd_flow/01_BRD/BRD-MVP-TEMPLATE.md` 添加了显式合规锚点 \+ YAML 变体；所需的小节图现在包括用于修复程序规范化和插入逻辑的 3.4.1/3.4.2、12.1-12.3 和 18.1-18.5。 2.4 | 2.4 2026-02-26 | **修复质量升级**：添加了 MVP 小节标题 (REV-MVP001/002/003) 的语义规范化、安全同级小节重新编号、REV-MVP004/008/010 的显式自动修复、生成的修复工件的降价规范化以及每个应用的修复的置信度标记（“自动安全”、“自动辅助”、“手动需要”）。 2.3 | 2.3 2026-02-25 | **模板对齐**：更新为 18 节结构，其中包括第 12 节（支持）、第 14 节（治理/批准）、第 15 节（质量保证）、第 16 节（可追溯性 16.1-16.4）、第 17 节（术语表 17.1-17.6）；添加了对缺失部分小节的修复 2.2 | 2.2 2026-02-24T21:30:00 | **上游配置修复**：为upstream_mode修复添加了阶段6.0（FIX-U001、FIX-U002、FIX-U003）；检测@ref：标签并建议upstream_mode：“ref”；当模式为“none”时清理被忽略的upstream_ref_path 2.1 | 2.1 2026-02-11 | **结构合规性**：添加了用于嵌套文件夹规则实施的阶段 0 (REV-STR001-STR003)；在其他修复阶段之前首先运行 2.0 | 2026-02-10T16:00:00 | **主要**：实施分层自动合并系统 - 第 1 层（<5%）：自动合并添加/更新；第 2 层 (5-15%)：自动合并详细变更日志；第3层（>15%）：归档当前版本并触发重新生成；无删除政策（标记为“已弃用”）；针对新要求自动生成的 ID；存档清单创建；增强了漂移缓存和合并历史记录 1.1| 2026-02-10T14:30:00 |添加了第 6 阶段：处理上游漂移 - 处理来自审阅者检查 #9 的 REV-D001-D005 问题；漂移标记插入；漂移缓存管理；确认工作流程 1.0 | 2026-02-10T12:00:00 |初始技能创造； 5 阶段修复工作流程；术语表和 GAP 文件创建；元素ID转换（类型25→33）；修复了损坏的链接；与自动驾驶仪集成审查→修复周期

Doc Brd 修复剂

包含技能