# 文档耳朵修复器 ## 目的自动**修复技能**，读取最新的审计/审查报告并将修复应用于 EARS（需求语法的简单方法）文档。此技能弥合了“doc-ears-reviewer”/“doc-ears-audit”（用于识别问题）和已纠正的 EARS 之间的差距，从而实现迭代改进周期。 **层**：3（EARS 质量改进） **上游**：EARS 文档、审核/审核报告（首选“EARS-NN.A_audit_report_vNNN.md”、“EARS-NN.R_review_report_vNNN.md”）、PRD（源要求） **下游**：修复了 EARS，修复报告（`EARS-NN.F_fix_report_vNNN.md`） ** ** ## 何时使用此技能在以下情况下使用“doc-ears-fixer”： * **审核后** ：在 `doc-ears-reviewer` 识别问题后运行 * **迭代改进** ：审核的一部分 -> 修复 -> 审核周期 * **自动化管道**：用于质量关卡的 CI/CD 集成 * **批量修复** ：根据审核报告将修复应用于多个 EARS **请勿在以下情况下使用**： * 不存在审核/审核报告（首先运行 `doc-ears-audit` 或 `doc-ears-reviewer`） * 创建新的 EARS（使用 `doc-ears` 或 `doc-ears-autopilot`） * 只需要验证（使用 `doc-ears-validator`） ** ** ## 技能依赖技能|目的|使用时 ---|---|--- `doc-ears-audit` |标准化结果的首选来源 |输入（读取审计报告） `doc-ears-审阅者` |需要修复的遗留/替代问题源 |输入（阅读评审报告） `文档命名` |元素 ID 标准 |修复元素 ID `doc-ears` | EARS 创建规则 |创建缺失的部分 `doc-prd-审稿人` |上游PRD验证|检查上游对齐情况 ** ** ## 工作流程概述流程图TD A[输入：EARS 路径] --> B[查找最新审计/审核报告] B --> C{找到报告？} C -->|否| D[首先运行 doc-ears-audit 或 doc-ears-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[写固定耳朵] L --> M[生成修复报告] M --> N{重新运行审核？} N -->|是| O[调用 doc-ears-reviewer] O --> P{分数 >= 阈值？} P -->|否，迭代次数 < max| F P -->|是|问[完成] N -->|否|问 ** ** ## 修复阶段 ### 第 0 阶段：修复结构违规（严重）修复了不在嵌套文件夹中的 EARS 文档。此阶段首先运行，因为所有后续阶段都依赖于正确的文件夹结构。 **嵌套文件夹规则**：无论文档大小如何，所有 EARS 都必须位于嵌套文件夹中。 **所需结构**：耳朵类型|所需地点 ---|--- 整体| `docs/03_EARS/EARS-NN_{slug}/EARS-NN_{slug}.md` **修复操作**：问题代码 |问题 |修复行动 ---|---|--- REV-STR001 | EARS 不在嵌套文件夹中 |创建文件夹、移动文件、更新所有链接 REV-STR002 | EARS 文件夹名称与 EARS ID 不匹配 |重命名文件夹以匹配 REV-STR003 |应将 >25KB 的整体 EARS 进行分段 |手动审核标记 **结构修复工作流程**： def fix_ears_struct(ears_path: str) -> 列表[修复]: """修复 EARS 结构违规。""" 修复=[] 文件名 = os.path.basename(ears_path) Parent_folder = os.path.dirname(ears_path) # 从文件名中提取 EARS ID 和 slug match = re.match(r'EARS-(\d+)_([^/]+)\.md', 文件名) 如果不匹配： return [] # 无法自动修复无效文件名 Ears_id = match.group(1) slug = match.group（2） Expected_folder = f“EARS-{ears_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(ears_path, new_path) Fixs.append(f"将 {ears_path} 移动到 {new_path}") # 更新移动文件中的上游链接内容=路径(new_path).read_text() update_content = content.replace('../02_PRD/', '../../02_PRD/') 更新内容 = 更新内容.replace('../01_BRD/', '../../01_BRD/') 路径（新路径）.write_text（更新内容） Fixs.append(f“更新了嵌套文件夹结构的相对链接”) 返回修复 **移动后链接路径更新**：原始路径 |更新路径 ---|--- `../02_PRD/PRD-01_slug/PRD-01.md` | `../../02_PRD/PRD-01_slug/PRD-01.md` `../01_BRD/BRD-01_slug/BRD-01.md` | `../../01_BRD/BRD-01_slug/BRD-01.md` ** ** ### 第 1 阶段：创建丢失的文件创建被引用但不存在的文件。 **范围**：丢失文件 |行动|使用的模板 ---|---|--- `EARS-00_GLOSSARY.md` |创建 EARS 术语表 |词汇表模板 `EARS-NN_APPENDIX_*.md` |创建附录占位符 |附录模板模式库文件 |使用 TODO 部分创建占位符 |图案模板约束文件 |创建占位符 |约束模板 **EARS 术语表模板**： --- 标题：“EARS-00：要求术语表” 标签： - 耳朵 - 词汇表 - 参考自定义字段： document_type：术语表 artifact_type：EARS-REFERENCE 层数：3 --- # EARS-00：要求术语表所有 EARS 需求文档中使用的通用术语。 ## EARS 模式术语 |术语 |定义|背景 | |------|------------|---------| |无处不在 |始终活跃的需求 |图案类型| |事件驱动|由特定事件触发 |图案类型| |不良行为 |异常处理要求 |图案类型| |国家驱动|特定状态下活跃 |图案类型| |可选功能 |有条件包含的要求 |图案类型| |复杂|多条件要求|图案类型| ## 需求关键词 |术语 |定义|背景 | |------|------------|---------| |应 |强制性要求|规范| |应该 |推荐要求|咨询 | |五月 |可选要求 |宽容 | |必须 |绝对要求 |关键| ## 域名术语 |术语 |定义|背景 | |------|------------|---------| | [术语] | [定义] | [使用地点] | **模式占位符模板**： --- 标题：“EARS 图案：[图案名称]” 标签： - 耳朵 - 模式规范 - 参考自定义字段： document_type：模式规范状态：占位符创建者：doc-ears-fixer --- # 耳朵图案：[图案名称] > **状态**：占位符 - 需要完成 ## 1. 模式概述 [TODO：文档模式概述] ## 2. 模式模板 ````文本 [TODO：定义 EARS 模式模板] ## 3\.模式示例示例 ID |要求 |图案类型 ---|---|--- 前-XX-01 | [需求示例] | [类型] ## 4\.约束条件 [TODO：文档模式约束] ** ** _由 doc-ears-fixer 作为占位符创建。完成此文档以解决损坏的链接问题。_ --- ### 第 2 阶段：修复损坏的链接更新链接以指向正确的位置。 **修复操作**： |问题代码 |问题 |修复行动| |------------|--------|------------| | REV-L001 |内部链接失效 |更新路径或创建目标文件 | | REV-L002 |外部链接无法访问 |添加警告评论，保留链接 | | REV-L003 |使用绝对路径|转换为相对路径| | REV-L004 |破碎的PRD参考|更新至正确的 PRD 路径 | **路径解析逻辑**： ````蟒蛇 def fix_link_path(ears_location: str, target_path: str) -> str: """根据 EARS 位置计算正确的相对路径。""" # 整体 EARS：docs/03_EARS/EARS-01.md # EARS 切片：docs/03_EARS/EARS-01_slug/EARS-01.3_section.md 如果 is_sectioned_ears(ears_location): # 需要再升一级返回“../”+calculate_relative_path(ears_location, target_path) 其他：返回计算相对路径（耳朵位置，目标路径） **PRD 链接修复**：耳朵类型|原文链接 |固定链接 ---|---|--- 整体| `../02_PRD/PRD-01.md` | `../02_PRD/PRD-01.md` 切片| `../02_PRD/PRD-01.md` | `../../02_PRD/PRD-01.md` ** ** ### 第 3 阶段：修复元素 ID 将无效的元素 ID 转换为正确的格式。 **转换规则**：图案|问题 |转换 ---|---|--- `EARS.NN.01.SS` |代码 01 对 EARS 无效 | `EARS.NN.25.SS`（EARS 声明） `EARS.NN.22.SS` |代码 22 对 EARS 无效 | `EARS.NN.26.SS`（约束语句） `REQ-XXX` |遗留模式| `EARS.NN.25.SS` `CON-XXX` |遗留模式| `EARS.NN.26.SS` `PAT-XXX` |遗留模式| `EARS.NN.25.SS` **类型代码映射**（EARS 特定的有效代码：25、26）：无效代码 |有效代码 |元素类型 ---|---|--- 01 | 25 | 25 EARS声明 02 | 25 | 25 EARS声明 03 | 26 | 26约束语句 05 | 25 | 25 EARS声明 06 | 26 | 26约束语句 22 | 22 25 | 25 EARS声明 33 | 33 26 | 26约束语句 **正则表达式模式**： # 查找 EARS 类型代码无效的元素 ID invalid_ears_type_01 = r'EARS\.(\d{2})\.01\.(\d{2})' replacement_01 = r'EARS.\1.25.\2' invalid_ears_type_22 = r'EARS\.(\d{2})\.22\.(\d{2})' replacement_22 = r'EARS.\1.26.\2' # 查找遗留模式 Legacy_req = r'###\s+REQ-(\d+):' Legacy_con = r'###\s+CON-(\d+):' Legacy_pat = r'###\s+PAT-(\d+):' ** ** ### 第 4 阶段：修复内容问题解决了占位符、不完整的内容和 EARS 特定的语法问题。 **修复操作**：问题代码 |问题 |修复行动 ---|---|--- REV-P001 | `[TODO]` 占位符 |手动完成标记（无法自动修复） REV-P002 | `[TBD]` 占位符 |手动完成标记（无法自动修复） REV-P003 |模板日期`YYYY-MM-DD` |替换为当前日期 REV-P004 |模板名称 `[名称]` |替换为元数据作者或标志 REV-P005 |空部分|添加最少模板内容 REV-E001 |缺少 EARS 关键字（shall/should/may）|手动审核标记 REV-E002 |无效的 EARS 模式结构 |手动审核标记 REV-E003 |缺少触发条件 |手动审核标记 **自动更换**：替换={ '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'), '[系统名称]': extract_system_name_from_metadata(), } **EARS 模式验证**：图案类型|所需结构|自动修复 ---|---|--- 无处不在 | “[系统]应[行动]” |否（标志）事件驱动| “当[触发]时，[系统]应[动作]”|否（标志）国家驱动| “当[状态]时，[系统]应[行动]”|否（标志）不需要 | “如果[条件]，则[系统]应[行动]” |否（标志）可选| “在[功能]的情况下，[系统]应[采取行动]” |否（标志） ** ** ### 第 5 阶段：更新参考文献确保可追溯性和交叉引用正确。 **修复操作**：问题 |修复行动 ---|--- 创建的文件缺少`@ref:` |添加参考标签跨 EARS 路径不正确 |更新以正确的相对路径缺少PRD可追溯性|使用“@trace: PRD-NN”添加 PRD 引用缺少追溯条目 |添加到追溯矩阵 **可追溯性格式**： @trace：PRD-01.22.01 -> EARS-01.25.01 @ref：PRD-01 第 3 节 (../02_PRD/PRD-01.md#3-功能要求) ** ** ### 第 6 阶段：处理上游漂移（自动合并）解决了自 EARS 创建以来上游 PRD 文档发生更改的问题。该阶段实现了基于漂移百分比的分层自动合并系统。 #### 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 |找不到上游文件 |部分|错误 ** ** **上游**：PRD（第 2 层） **下游**：BDD（第 4 层） **ID 模式**：“EARS.NN.TT.SS”（例如“EARS.01.25.13”） #### 漂移问题代码（来自 `doc-ears-reviewer` 检查 #9）代码|严重性 |描述 |自动修复层 ---|---|---|--- REV-D001 |警告| PRD在EARS之后修改| 1-2 级 REV-D002 |警告|引用的PRD部分内容已更改| 1-3 级 REV-D003 |信息 | PRD版本增加| 1 级 REV-D004 |信息 | PRD 新增功能 | 1-2 级 REV-D005 |错误 |关键 PRD 修改（>20% 变化） | 3 级 #### 分层自动合并系统 **等级分类**：等级 |变化% |自动合并 |版本操作 |描述 ---|---|---|---|--- 1 级 | < 5% |全自动合并|补丁（+0.0.1）|添加、阈值更新 2 级 | 5-15% |自动合并变更日志 |次要 (+0.1.0) |重大补充，微小修改第 3 级 | > 15% |存档+重新生成|主要 (+1.0.0) |结构变化，主要内容漂移 #### 变化百分比计算 def 计算漂移百分比( 上游电流：str，上游缓存：str，引用的部分：列表[str] ) -> 浮动: ”“” 计算缓存和当前上游之间的漂移百分比。参数： upload_current：当前PRD内容 upload_cached：上次同步的缓存 PRD 内容 Referenced_sections：EARS 引用的 PRD 部分列表返回：漂移百分比（0.0 - 100.0） ”“” # 仅提取引用的部分 current_sections = extract_sections（upstream_current，referenced_sections）缓存的部分 = 提取部分（upstream_cached，引用的部分） # 计算基于行的差异 diff = Unified_diff(cached_sections.splitlines(), current_sections.splitlines()) added_lines = sum(1 for line in diff if line.startswith('+') and not line.startswith('+++')) returned_lines = sum(1 for line in diff if line.startswith('-') and not line.startswith('---')) 总行数 = max(len(cached_sections.splitlines()), 1) # 加权计算：增加加权1.0，删除加权1.5 漂移分数 = (添加的行数 * 1.0 + 删除的行数 * 1.5) / 总行数 * 100 返回最小值（drift_score，100.0） def确定层(drift_percentage: float) -> int: """根据漂移百分比确定合并层。""" 如果drift_percentage < 5.0：返回1 elif 漂移百分比 <= 15.0：返回2 其他：返回3 #### 第 1 层：自动合并（< 5% 漂移） **触发条件**： * 对 PRD 部分进行了少量补充 * 阈值/限制更新 * 补充说明文字 * 无结构变化 **自动合并操作**：更改类型 |行动| ID分配 ---|---|--- 珠三角新要求 |添加 EARS 声明 |下一个连续 ID（例如“EARS.01.25.13”）更新阈值 |更新约束值 |保留现有 ID 添加说明 |附加到现有语句 |保留现有 ID **新要求的 ID 生成**： defgenerate_next_ears_id(ears_doc: str, type_code: str = "25") -> str: ”“” 生成下一个连续的 EARS ID。 ID 图案：EARS.NN.TT.SS - NN：文档编号 (01-99) - TT：类型代码（25=声明，26=约束） - SS：序列号（01-99）参数： Ears_doc：EARS 文档的路径 type_code：类型代码（“25”表示语句，“26”表示约束）返回：下一个可用的 EARS ID ”“” # 从文件名中提取文档编号 doc_num = extract_doc_number(ears_doc) # 例如，“EARS-01.md”中的“01” # 找到该类型的最高现有序列模式 = rf'EARS\.{doc_num}\.{type_code}\.(\d{{2}})' 现有_ids = re.findall(模式, read_file(ears_doc)) 如果存在_id： max_seq = max(int(seq) 表示现有_ids 中的 seq) next_seq = str(max_seq + 1).zfill(2) 其他：下一个序列=“01” 返回f“EARS。{doc_num}。{type_code}。{next_seq}” **版本更新**： # 第 1 层：增加补丁版本 # 1.0.0 -> 1.0.1 当前版本=“1.0.0” new_version =increment_version(current_version, "补丁") # "1.0.1" #### 第 2 层：与变更日志自动合并（5-15% 漂移） **触发条件**： * PRD多项新功能 * 部分重组（次要） * 需求细化 * 新的约束类别 **自动合并操作**：更改类型 |行动|文档 ---|---|--- 新功能部分|生成 EARS 报表 |变更日志条目修改要求|更新现有报表 |变更日志 + 差异新的限制|添加约束语句 |变更日志条目 **变更日志条目格式**： ## 变更日志条目（自动合并第 2 层） **日期**：2026-02-10T16:00:00 **来源**：PRD-01.md（v1.2.0 -> v1.3.0） **漂移百分比**：8.3% ### 补充 |新身份证 |声明摘要 |来源珠三角部分| |--------------------|--------------------|--------------------| |耳朵.01.25.13 |系统应支持批处理| PRD-01 第 5.2 节 | |耳朵.01.25.14 |系统应提供进度通知 | PRD-01 第 5.3 节 | |耳朵.05.01.26 |批处理操作的响应时间限制 | PRD-01 第 7.1 节 | ### 修改 |身份证 |上一页 |更新 |原因 | |----|----------|---------|--------| |耳朵.01.25.07 | “100 毫秒内”| “50 毫秒内” |性能门槛收紧| ### 禁止删除（请参阅禁止删除政策） **版本更新**： # 第 2 层：增加次要版本 # 1.0.1 -> 1.1.0 当前版本=“1.0.1” new_version =increment_version(current_version, "次要版本") # "1.1.0" #### 第 3 层：存档和重新生成（> 15% 漂移） **触发条件**： * 珠三角地区重大重组 * 功能范围变更 * 基本要求变更 * 含量漂移超过15% **归档过程**： 1. **创建存档清单**： --- 标题：“EARS-NN 存档清单” 标签： - 耳朵 - 存档 - 漂移管理自定义字段：存档日期：“2026-02-10T16:00:00” 存档版本：“1.1.0” 漂移百分比：23.5 触发：“第 3 层 - 主要漂移” upload_source: "PRD-01.md v2.0.0" --- # EARS-NN 存档清单 ## 存档详细信息 |领域 |价值| |--------|--------| |存档日期 | 2026-02-10T16:00:00 | |存档版本 | 1.1.0 | |存档位置 | `存档/EARS-01_v1.1.0_20260210/` | |漂移百分比| 23.5% | |原因 |珠三角重大重组 | ## 存档文件 |文件 |原地点 |存档位置 | |------|--------------------|------------------| | EARS-01.md |文档/03_EARS/ |存档/EARS-01_v1.1.0_20260210/ | | EARS-01.1_core.md |文档/03_EARS/EARS-01_slug/ |存档/EARS-01_v1.1.0_20260210/ | | EARS-01.2_requirements.md |文档/03_EARS/EARS-01_slug/ |存档/EARS-01_v1.1.0_20260210/ | ## 再生说明 1.运行`/doc-ears-autopilot PRD-01`生成新的EARS 2.新版本为2.0.0 3. 审查存档的报表是否有可能重用 4.更新下游BDD参考 2. **移至存档**： def archive_ears_document（ears_path：str，版本：str，drift_pct：float）-> str： ”“” 重新生成之前存档 EARS 文档。参数： Ears_path：EARS 文档的路径 version：当前正在存档的版本 drift_pct：触发存档的漂移百分比返回：存档目录路径 ”“” 时间戳 = datetime.now().strftime('%Y%m%d') archive_dir = f“存档/EARS-{doc_num}_v{版本}_{时间戳}/” # 创建存档目录 os.makedirs（archive_dir，exist_ok = True） # 复制所有 EARS 文件对于 glob 中的 Ears_file(f"{ears_dir}/EARS-{doc_num}*")： Shutil.copy2(ears_file, archive_dir) # 生成存档清单 generate_archive_manifest（archive_dir，版本，drift_pct）返回存档目录 3. **触发再生** : # 调用 doc-ears-autopilot 并增加主要版本再生参数 = { "source_prd": "PRD-01", “version_override”：“2.0.0”， “archive_reference”：archive_dir， “preserve_custom_statements”：正确 } **版本更新**： # 第 3 层：增加主要版本 # 1.1.0 -> 2.0.0 当前版本=“1.1.0” new_version =increment_version(current_version, "major") # "2.0.0" #### 禁止删除政策 **关键**：EARS 要求在自动合并期间永远不会被删除。从上游 PRD 中删除的项目被标记为已弃用。 **弃用标记格式**： ### EARS.01.25.05 [已弃用] > **弃用日期**：2026-02-10 > **原因**：从 PRD-01 v1.3.0 中删除（删除第 4.2 节） > **下游影响**：受影响的 BDD-01.2 场景 **原声明**：当用户发起导出时，系统应在 5 秒内生成 CSV 输出。 **状态**：已弃用 - 不实施。保留用于可追溯性。 **弃用跟踪**： def mark_deprecated( Ears_id：str，原因：str，上游参考：str，下游引用：列表[str] ) -> 无: ”“” 将 EARS 要求标记为已弃用而不是删除。参数： Ears_id：要弃用的 EARS ID（例如“EARS.01.25.05”）原因：弃用的原因 upload_ref：触发弃用的 PRD 引用下游_refs：受影响的下游 BDD 引用列表 ”“” deprecation_block = f""" ### {ears_id} [已弃用] > **弃用日期**：{datetime.now().strftime('%Y-%m-%d')} > **原因**：{原因} > **上游参考**：{upstream_ref} > **下游影响**：{', '.join(downstream_refs) if下游_refs else '未识别'} **状态**：已弃用 - 不实施。保留用于可追溯性。 ”“” # 插入弃用块，保留原始语句 #### 增强型漂移缓存处理漂移问题后，更新`.drift_cache.json`： { "ears_document": "EARS-01", "ears_version": "1.1.0", "ears_updated": "2026-02-10T16:00:00", “drift_reviewed”：“2026-02-10T16:00:00”， “上游”：{ “文档”：“PRD-01.md”， “版本”：“1.3.0”， “last_sync”：“2026-02-10T16:00:00” }, “下游”：{ “文档”：[“BDD-01.md”]， “notification_sent”：“2026-02-10T16:05:00” }, “部分哈希”：{ "PRD-01#section-3": "a1b2c3d4e5f6...", "PRD-01#section-5": "g7h8i9j0k1l2...", “PRD-01#section-7”：“m3n4o5p6q7r8...” }, “合并历史记录”：[ { “日期”：“2026-02-10T16:00:00”， “等级”：2， “漂移百分比”：8.3， "version_before": "1.0.1", "version_after": "1.1.0", “添加”：[“EARS.01.25.13”，“EARS.01.25.14”，“EARS.01.26.05”]， “修改”：[“EARS.01.25.07”]， “弃用”：[] } ], “acknowledged_drift”：[ { “文档”：“PRD-01.md”， “节”：“第 8 节”， “acknowledged_date”：“2026-02-08”， "reason": "信息部分 - 没有 EARS 影响" } ] } #### 漂移确认工作流程当标记了漂移但不需要 EARS 更新时： 1. 运行 `/doc-ears-fixer EARS-01 --acknowledge-drift` 2.修复程序提示：“检查 PRD-01.md 第 8 节的漂移？” 3. 用户确认无需对 EARS 进行更改 4. Fixer 添加到 `acknowledged_drift` 数组 5. 未来的审查会跳过这种漂移，直到上游再次发生变化 #### 下游通知任何自动合并后，通知下游 BDD 文档： def notify_downstream(ears_id: str, 更改: list[dict]) -> 无: ”“” 为下游 BDD 文档创建通知。参数： Ears_id：EARS 文档 ID（例如“EARS-01”）更改：自动合并期间所做的更改列表 ”“” 通知={ “类型”：“UPSTREAM_CHANGE”， “来源”：ears_id， “时间戳”：datetime.now().isoformat(), “变化”：改变， "action_required": "运行 /doc-bdd-fixer 进行同步" } # 写入.downstream_notifications.json write_notification(f"docs/04_BDD/.downstream_notifications.json", 通知) ** ** ## 命令用法 ### 基本用法 # 根据最新评论修复 EARS /doc-ears-fixer EARS-01 # 修复明确的审查报告（遗留） /doc-ears-fixer EARS-01 --review-report EARS-01.R_review_report_v001.md # 使用明确的审计报告修复（首选） /doc-ears-fixer EARS-01 --review-report EARS-01.A_audit_report_v001.md # 修复并重新运行审核 /doc-ears-fixer EARS-01 --revalidate # 修复迭代限制 /doc-ears-fixer EARS-01 --revalidate --max-iterations 3 ### 选项选项|默认 |描述 ---|---|--- `--审查报告` |最新 |要使用的特定审计/审查报告（首选`.A_audit_report`） `--重新验证` |假 |修复后运行审阅者 `--最大迭代次数` | 3 |最大修复审查周期 `--修复类型` |全部 |特定修复类型（以逗号分隔） `--创建缺失` |真实 |创建缺失的参考文件 `--备份` |真实 |修复前备份 EARS `--试运行` |假 |预览修复而不应用 `--承认漂移` |假 |交互式漂移确认模式 `--更新漂移缓存` |真实 |修复后更新 .drift_cache.json `--自动合并层` |汽车 |强制特定层（1、2、3 或自动） `--跳过存档` |假 |跳过第 3 层的归档（就地重新生成） `--通知下游` |真实 |向下游 BDD 文档发送通知 `--preserve-已弃用` |真实 |保留已弃用的项目（不删除政策） **报告选择优先级**： 1. 按时间戳选择最新报告。 2. 如果时间戳相等，则优先选择“EARS-NN.A_audit_report_vNNN.md”而不是“EARS-NN.R_review_report_vNNN.md”。 ### 修复类型类型 |描述 ---|--- `丢失的文件` |创建缺失的术语表、模式、约束文档 `损坏的链接` |修复链接路径 `element_ids` |转换无效/旧元素 ID `内容` |修复占位符、日期、名称 `参考文献` |更新可追溯性和交叉引用 ‘漂移’ |处理上游漂移检测问题 `自动合并` |对上游更改应用分层自动合并 `弃用` |将已删除的上游项目标记为已弃用 `全部` |所有修复类型（默认） ** ** ## 输出工件 ### 修复报告 **嵌套文件夹规则**：所有 EARS 都使用嵌套文件夹 (`EARS-NN_{slug}/`)，无论大小如何。修复报告与 EARS 文档一起存储在嵌套文件夹中。 **文件命名** : `EARS-NN.F_fix_report_vNNN.md` **位置**：在 EARS 嵌套文件夹内：`docs/03_EARS/EARS-NN_{slug}/` **结构**： --- 标题：“EARS-NN.F：修复报告 v001” 标签： - 耳朵 - 修复报告 - 质量保证自定义字段： document_type：修复报告工件类型：EARS-FIX 层数：3 父文档：EARS-NN 来源_评论：EARS-NN.A_audit_report_v001.md fix_date: "YYYY-MM-DDTHH:MM:SS" 修复工具：文档耳朵修复器修复版本：“1.0” --- # EARS-NN 修复报告 v001 ## 总结 |公制|价值| |--------|--------| |来源评论 | EARS-NN.A_audit_report_v001.md（或旧版“EARS-NN.R_review_report_v001.md”）| |审查中的问题 | 12 | 12 |已解决的问题 | 10 | 10 |剩余问题 | 2（需要人工审核）| |文件已创建 | 2 | |文件修改 | 4 | ## 文件已创建 |文件|类型 |地点 | |------|------|----------| | EARS-00_GLOSSARY.md |要求词汇表 |文档/03_EARS/ | | EARS-01_PATTERN_LIB.md |模式库占位符 |文档/03_EARS/ | ## 应用的修复 | ＃|问题代码 |问题 |修复已应用 |文件| |---|------------|--------|-------------|-----| | 1 | REV-L001 |损坏的词汇表链接 |创建了 EARS-00_GLOSSARY.md | EARS-01.3_constraints.md | | 2 | REV-L004 |破碎的PRD参考|更新路径为../02_PRD/PRD-01.md | EARS-01.1_core.md | | 3 | REV-N004 |元素类型 01 无效 |转换为类型 25 | EARS-01.1_core.md | | 4 | REV-L003 |使用绝对路径|转换为相对| EARS-01.2_requirements.md | ## 需要人工审核的问题 | ＃|问题代码 |问题 |地点 |原因 | |---|------------|--------|----------|--------| | 1 | REV-E001 |缺少 EARS 关键字 | EARS-01.2：L45 |所需语法 | | 2 | REV-E002 |无效的模式结构 | EARS-01.2：L120 |需要模式细化 | ## 修复后验证 |公制|之前 |之后|达美航空 | |--------|--------|--------|--------| |评论分数 | 92 | 92 97 | 97 +5 | |错误 | 2 | 0 | -2 | |警告| 4 | 1 | -3 | ## 后续步骤 1. 完成 EARS-01_PATTERN_LIB.md 占位符 2. 解决标记要求中缺失的 EARS 关键字 3. 运行“/doc-ears-reviewer EARS-01”来验证修复 ** ** ## 与自动驾驶仪集成该技能由 Review -> Fix 周期中的 `doc-ears-autopilot` 调用：流程图LR 子图 Phase5[“第 5 阶段：审查和修复周期”] A[doc-ears-reviewer] --> B{分数 >= 85?} B -->|否| C[doc-耳朵修复器] C --> D{迭代 < 最大值？} D -->|是|一个 D -->|否| E[手动审核标志] B -->|是| F[通过] 结束 **自动驾驶仪集成点**：相|行动|技能 ---|---|--- 5a 阶段 |进行初步审查 | `文档耳朵审稿人` 5b 阶段 |如果发现问题，请应用修复程序 | `文档耳朵修复器` 5c 阶段 |重新运行审核 | `文档耳朵审稿人` 5d 阶段 |重复直到通过或最大迭代 |循环 ** ** ## 错误处理 ### 恢复行动错误 |行动 ---|--- 未找到审计/审查报告 |提示先运行 `doc-ears-audit` 或 `doc-ears-reviewer` 无法创建文件（权限）|记录错误，继续其他修复无法解析报告 |中止并显示明确的错误消息超出最大迭代次数 |生成报告、标记以供手动审核未找到 PRD |记录警告，跳过与 PRD 相关的修复 ### 备份策略在应用任何修复之前： 1. 在 `tmp/backup/EARS-NN_YYYYMMDD_HHMMSS/` 中创建备份 2. 将所有 EARS 文件复制到备份位置 3. 对原始文件应用修复 4. 如果修复过程中出现错误，请从备份恢复 ** ** ## 相关技能技能|关系 ---|--- `doc-ears-audit` |首选组合审计报告输入 `doc-ears-审阅者` |提供审查报告（输入） `doc-ears-自动驾驶仪` |协调审核 -> 修复周期 `doc-ears-验证器` |结构验证 `文档命名` |元素 ID 标准 `doc-ears` | EARS创建规则 `doc-prd-审稿人` |上游 PRD 验证 ** ** ## 版本历史版本 |日期 |变化 ---|---|--- 2.2 | 2.2 2026-02-26 |将 frontmatter 迁移到“元数据”；添加了“EARS-NN.A_audit_report_vNNN.md”（首选）与旧版“EARS-NN.R_review_report_vNNN.md”的兼容性；定义的确定性优先级（最新时间戳，然后“.A_”优先于“.R_”） 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（EARS.NN.TT.SS 模式）；增强了带有合并历史记录的漂移缓存；下游BDD通知系统 1.0 | 2026-02-10 |初始技能创造； 6 阶段修复工作流程；术语表和模式文件创建； EARS 代码的元素 ID 转换 (25, 26)；修复了损坏的链接； PRD漂移检测； EARS 模式语法验证；与自动驾驶仪集成审核->修复周期 ## 实施计划一致性 (IPLAN-004) * 将计划派生的输出视为有效的源模式，并验证实施计划范围/目标的意图保留。 * 验证上游自动驾驶仪优先级假设：`--iplan > --ref > --prompt`。 * 将计划上下文和工件输出之间的目标/范围冲突标记为需要澄清的阻塞问题。 * 不要引入旧的后备路径，例如“docs-v2.0/00_REF”。

Doc 耳朵固定器

包含技能