# 文档-tspec-修复程序 ## 目的自动**修复技能**，读取最新的审查报告并将修复应用于 TSPEC（测试规范）文档。此技能弥合了“doc-tspec-reviewer”（用于识别问题）和修正后的 TSPEC 之间的差距，从而实现迭代改进周期。 **层**：10（TSPEC 质量改进） **上游**：SPEC 文档、TSPEC 文档、审核/审核报告（首选“TSPEC-NN.A_audit_report_vNNN.md”；“TSPEC-NN.R_review_report_vNNN.md”旧版本兼容） **下游**：修复了 TSPEC，修复报告（`TSPEC-NN.F_fix_report_vNNN.md`） ** ** ## 何时使用此技能在以下情况下使用“doc-tspec-fixer”： * **审核后** ：在 `doc-tspec-reviewer` 识别问题后运行 * **迭代改进** ：审核的一部分 -> 修复 -> 审核周期 * **自动化管道**：用于质量关卡的 CI/CD 集成 * **批量修复** ：根据审核报告将修复应用于多个 TSPEC * **测试用例结构问题**：测试用例的结构不正确 **请勿在以下情况下使用**： * 不存在审查报告（首先运行 `doc-tspec-reviewer`） * 创建新的 TSPEC（使用 `doc-tspec` 或 `doc-tspec-autopilot`） * 只需要验证（使用 `doc-tspec-validator`） ### 报告选择优先级（确定性） 1. 选择具有最新时间戳/版本的报告。 2. 如果时间戳/版本相同，则优先选择“.A_audit_report_vNNN.md”而不是“.R_review_report_vNNN.md”。 ** ** ## 技能依赖技能|目的|使用时 ---|---|--- `doc-tspec-审计` |统一验证器+评审器包装器 |首选上游报告来源 `doc-tspec-审稿人` |待修复问题的来源 |输入（阅读评审报告） `文档命名` |元素 ID 标准 |修复元素 ID `doc-tspec` | TSPEC 创建规则 |创建缺失的部分 `文档规范` |规格溯源|验证上游链接 ** ** ## 工作流程概述流程图TD A[输入：TSPEC 路径] --> B[查找最新审核/审核报告] B --> C{找到评论？} C -->|否| D[首先运行 doc-tspec-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：处理上游漂移] 结束子图 TestCaseFix["测试用例结构修复"] K2 --> T1[解析测试用例] T1 --> T2{结构有效？} T2 -->|否| T3[修复测试用例结构] T2 -->|是| T4[验证测试覆盖率] T3 --> T4 结束 T4 --> L[写入固定 TSPEC] L --> M[生成修复报告] M --> N{重新运行审核？} N -->|是| O[调用 doc-tspec-reviewer] O --> P{分数 >= 阈值？} P -->|否，迭代次数 < max| F P -->|是|问[完成] N -->|否|问 ** ** ## 修复阶段 ### 第 0 阶段：修复结构违规（严重）修复了不在嵌套文件夹中的 TSPEC 文档。此阶段首先运行，因为所有后续阶段都依赖于正确的文件夹结构。 **嵌套文件夹规则**：所有 TSPEC 文档必须位于嵌套文件夹中，无论文档大小如何。 **所需结构**： TSPEC 类型 |所需地点 ---|--- UT测试| `docs/10_TSPEC/UTEST/UTEST-NN_{slug}/UTEST-NN_{slug}.md` 测试| `docs/10_TSPEC/ITEST/ITEST-NN_{slug}/ITEST-NN_{slug}.md` 测试| `docs/10_TSPEC/STEST/STEST-NN_{slug}/STEST-NN_{slug}.md` FTEST | `docs/10_TSPEC/FTEST/FTEST-NN_{slug}/FTEST-NN_{slug}.md` 测试测试 | `docs/10_TSPEC/PTEST/PTEST-NN_{slug}/PTEST-NN_{slug}.md` 教派测试 | `docs/10_TSPEC/SECTEST/SECTEST-NN_{slug}/SECTEST-NN_{slug}.md` **修复操作**：问题代码 |问题 |修复行动 ---|---|--- REV-STR001 | TSPEC 不在嵌套文件夹中 |创建文件夹、移动文件、更新所有链接 REV-STR002 | TSPEC 文件夹名称与 TSPEC ID 不匹配 |重命名文件夹以匹配 REV-STR003 | TSPEC >25KB 应分段 |手动审核标记 REV-STR004 | TSPEC 不在正确的子目录中 (UTEST/ITEST/STEST/FTEST) |移动到正确的子目录 **结构修复工作流程**： def fix_tspec_struct(tspec_path: str) -> 列表[修复]: """修复 TSPEC 结构违规。""" 修复=[] 文件名 = os.path.basename(tspec_path) 父文件夹 = os.path.dirname(tspec_path) # 从文件名中提取 TSPEC 类型、ID 和 slug match = re.match(r'(UTEST|ITEST|STEST|FTEST)-(\d+)_([^/]+)\.md', 文件名) 如果不匹配： return [] # 无法自动修复无效文件名 tspec_type = match.group(1) tspec_id = match.group(2) slug = match.group（3）预期文件夹 = f"{tspec_type}-{tspec_id}_{slug}" # 检查是否已位于正确子目录中的嵌套文件夹中如果 os.path.basename(parent_folder) != Expected_folder: # 在正确的子目录中创建嵌套文件夹 base_path = os.path.dirname(os.path.dirname(parent_folder)) new_folder = os.path.join（base_path，tspec_type，expected_folder） os.makedirs（new_folder，exist_ok = True） # 移动文件 new_path = os.path.join(new_folder, 文件名) Shutil.move(tspec_path, new_path) Fixs.append(f"已将 {tspec_path} 移动到 {new_path}") # 更新移动文件中的上游链接内容=路径(new_path).read_text() update_content = content.replace('../09_SPEC/', '../../../09_SPEC/') 更新内容 = 更新内容.replace('../../09_SPEC/', '../../../09_SPEC/') 路径（新路径）.write_text（更新内容） Fixs.append(f“更新了嵌套文件夹结构的相对链接”) 返回修复 **移动后链接路径更新**：原始路径 |更新路径 ---|--- `../../09_SPEC/SPEC-01_slug/SPEC-01.yaml` | `../../../09_SPEC/SPEC-01_slug/SPEC-01.yaml` ** ** ### 第 1 阶段：创建丢失的文件创建被引用但不存在的文件。 **范围**：丢失文件 |行动|使用的模板 ---|---|--- `TSPEC-NN_test_data.yaml` |创建测试数据文件 |测试数据模板 `TSPEC-NN_fixtures.yaml` |创建测试夹具文件 |夹具模板 `TSPEC-NN_matrix.md` |创建测试矩阵 |矩阵模板参考文档 |创建占位符 |参考模板 **测试数据模板**： # TSPEC-NN：测试数据定义 # 由 doc-tspec-fixer 自动生成 - 需要完成测试数据：版本：“1.0.0” tspec_id：TSPEC-NN 创建：“YYYY-MM-DD” 状态：草案数据集： # TODO: 添加测试数据集有效输入： - 编号：TD-001 描述：“有效输入数据集1” 数据： # 添加数据字段无效输入： - 编号：TD-002 描述：“输入数据集 1 无效” 数据： # 添加数据字段边缘情况： - 编号：TD-003 描述：“边缘情况数据集1” 数据： # 添加数据字段边界值： # TODO：定义测试的边界值 - 字段：示例字段分钟：0 最大：100 边界测试： - 值：-1 预期：错误 - 值：0 预期：成功 - 值：100 预期：成功 - 值：101 预期：错误 **测试夹具模板**： # TSPEC-NN：测试夹具 # 由 doc-tspec-fixer 自动生成 - 需要完成固定装置：版本：“1.0.0” tspec_id：TSPEC-NN 创建：“YYYY-MM-DD” 设置： # TODO：定义设置装置数据库： - 名称：test_db_setup 描述：“初始化测试数据库” 行动： - 操作：创建模式 - 动作：seed_data 服务： - 名称：mock_api_setup 描述：“设置模拟 API 端点” 拆解： # TODO: 定义拆卸装置数据库： - 名称：test_db_cleanup 行动： - 动作：drop_schema **测试矩阵模板**： --- 标题：“TSPEC-NN：测试矩阵” 标签： - tspec - 测试矩阵 - 第 10 层自定义字段： document_type：测试矩阵工件类型：TSPEC-MATRIX 层数：10 Parent_tspec：TSPEC-NN --- # TSPEC-NN 测试矩阵 ## 覆盖范围摘要 |要求 |测试用例|通行证 |失败|跳过|覆盖范围| |-------------|------------|------|------|------|----------| |要求-XX.YY.ZZ | TC-001、TC-002 | - | - | - | - | ## 测试用例矩阵 |测试ID |要求 |优先|类型 |状态 | |---------|-------------|----------|-----|--------| | TC-001 |要求-XX.YY.ZZ | P1 |单位|待定 | ## 环境矩阵 |环境 |操作系统 |浏览器/运行时 |状态 | |-------------|----|-----------------| --------| | CI | Linux |节点 18 |待定 | --- *由 doc-tspec-fixer 作为占位符创建。完成本文档。* ** ** ### 第 2 阶段：修复损坏的链接更新链接以指向正确的位置。 **修复操作**：问题代码 |问题 |修复行动 ---|---|--- REV-L001 |内部链接失效 |更新路径或创建目标文件 REV-L002 |外部链接无法访问 |添加警告评论，保留链接 REV-L003 |使用绝对路径|转换为相对路径 REV-L008 |测试数据参考破|更新测试数据路径 REV-L009 |夹具参考损坏|更新夹具路径 **路径解析逻辑**： def fix_link_path(tspec_location: str, target_path: str) -> str: """根据 TSPEC 位置计算正确的相对路径。""" # TSPEC 文件：docs/10_TSPEC/TSPEC-01.md # 测试数据：docs/10_TSPEC/data/ # 夹具：docs/10_TSPEC/fixtures/ 如果 is_test_data_reference(target_path): 返回fix_test_data_ref（tspec_location，target_path） elif is_fixture_reference(目标路径): 返回fix_fixture_ref（tspec_location，target_path）其他：返回计算相对路径（tspec_location，目标路径） ** ** ### 第 3 阶段：修复元素 ID 将无效的元素 ID 转换为正确的格式。 **转换规则**：图案|问题 |转换 ---|---|--- `TSPEC.NN.XX.SS` |无效的类型代码 |转换为有效的 TSPEC 代码 `TC-XXX` |遗留模式| `TSPEC.NN.40.SS`（测试用例） `TS-XXX` |遗留模式| `TSPEC.NN.41.SS`（测试套件） `TD-XXX` |遗留模式| `TSPEC.NN.42.SS`（测试数据） `TF-XXX` |遗留模式| `TSPEC.NN.43.SS`（测试夹具） **类型代码映射**（TSPEC 特定）：无效代码 |有效代码 |元素类型 ---|---|--- 01-39 | 40|测试用例不适用 | 41 | 41测试套件不适用 | 42 | 42测试数据不适用 | 43 | 43测试治具 **有效的 TSPEC 类型代码**：代码|元素类型 |描述 ---|---|--- 40 | 40 UT测试|单元测试用例规范 41 | 41测试|集成测试用例规范 42 | 42测试|烟雾测试用例规范 43 | 43 FTEST |功能测试用例规范 44 | 44测试测试 |性能测试用例规范 45 | 45教派测试 |安全测试用例规范 **正则表达式模式**： # 查找 TSPEC 类型代码无效的元素 ID invalid_tspec_type = r'TSPEC\.(\d{2})\.(?!40|41|42|43)(\d{2})\.(\d{2})' # 查找遗留模式 Legacy_tc = r'###\s+TC-(\d+):' Legacy_ts = r'###\s+TS-(\d+):' Legacy_td = r'###\s+TD-(\d+):' Legacy_tf = r'###\s+TF-(\d+):' ** ** ### 第 4 阶段：修复内容问题解决占位符和不完整的内容。 **修复操作**：问题代码 |问题 |修复行动 ---|---|--- REV-P001 | `[TODO]` 占位符 |手动完成标记（无法自动修复） REV-P002 | `[TBD]` 占位符 |手动完成标记（无法自动修复） REV-P003 |模板日期`YYYY-MM-DD` |替换为当前日期 REV-P004 |模板名称 `[名称]` |替换为元数据作者或标志 REV-P005 |空部分|添加最少模板内容 REV-T001 |缺少测试步骤 |添加占位符步骤结构 REV-T002 |缺少预期结果 |添加占位符预期结果 REV-T003 |缺少先决条件 |添加占位符先决条件 **自动更换**：替换={ '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'), } **测试用例结构修复**：缺失元素 |添加模板 ---|--- 前提条件 | `**先决条件**：[TODO：定义先决条件]` 测试步骤| `**步骤**：\n1. [TODO：添加步骤 1]\n2。 [TODO：添加步骤 2]` 预期结果 | `**预期结果**：[TODO：定义预期结果]` 优先| `**优先级**：P2`（默认）测试类型| `**类型**：功能性`（默认） ** ** ### 第 5 阶段：更新参考文献确保可追溯性和交叉引用正确。 **修复操作**：问题 |修复行动 ---|--- 缺少 `@spec:` 参考 |添加 SPEC 追溯标签缺少 `@req:` 参考 |添加 REQ 可追溯性标签（通过 SPEC）错误的上游路径 |更新以正确的相对路径缺少追溯条目 |添加到追溯矩阵 **规范可追溯性修复**： ## TC-001：用户身份验证测试 ## TC-001：用户身份验证测试 @spec: [SPEC-01.auth.login](../09_SPEC/SPEC-01.md#auth-login) @req：[REQ-01.28.01](../07_REQ/REQ-01.md#req-01-28-01) ** ** ### 第 6 阶段：处理上游漂移（自动合并）解决了自使用分层自动合并系统创建 TSPEC 以来上游 SPEC 文档发生更改的问题。 #### 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 |找不到上游文件 |部分|错误 ** ** **上游/下游上下文**： * **上游**：SPEC（第 9 层）- 测试规范源自规范 * **下游**：任务（第 11 层）/代码 - 测试通知实施任务 **漂移问题代码**（来自“doc-tspec-reviewer”）：代码|严重性 |描述 |层级映射 ---|---|---|--- REV-D001 |警告| TSPEC 后修改 SPEC 文件 |按阈值计算 REV-D002 |警告|引用规范内容发生变更 |按阈值计算 REV-D003 |信息 | SPEC文档版本增加| 1 级 REV-D004 |信息 |上游添加新规范 | 1 级或 2 级 REV-D005 |错误 |关键规格修改（>20% 变化）| 3 级 #### 分层自动合并阈值等级 |变化% |行动|版本碰撞 |需要审查 ---|---|---|---|--- **1 级** | < 5% |自动合并新测试用例 |补丁 (x.y.Z) |否 **2 级** | 5-15% |自动合并变更日志 |次要 (x.Y.0) |仅摘要 **第 3 级** | > 15% |存档+再生触发|主要 (X.0.0) |是（必填） #### 变化百分比计算 defcalculate_change_percentage(spec_before: str, spec_after: str, tspec: str) -> float: ”“” 根据以下公式计算漂移百分比： 1. 影响测试用例的规范部分更改 2.新要求需要新测试 3. 需要测试更新的修改需求 4. 删除了要求测试弃用的要求 ”“” spec_elements = extract_testable_elements(spec_before) spec_elements_new = extract_testable_elements(spec_after) tspec_coverage = extract_test_coverage(tspec) 添加=spec_elements_new-spec_elements 已删除=spec_elements-spec_elements_new 修改=检测修改（规范之前，规范之后）总元素 = len(spec_elements_new) changed_elements = len(添加) + len(删除) + len(修改) 返回 (已更改元素 / 总元素) * 100 如果总元素 > 0 否则 0 #### TSPEC 测试 ID 模式 **格式** : `{TYPE}-NN-TC-SS` 类型 |描述 |示例 ---|---|--- UT测试|单元测试| UTEST-01-TC-01 测试|集成测试| ITEST-01-TC-01 测试|系统测试| STEST-01-TC-01 FTEST |功能测试| FTEST-01-TC-01 测试测试 |性能测试| PTEST-01-TC-01 教派测试 |安全测试| SECEST-01-TC-01 其中： * `NN` = TSPEC 文档编号 (01-99) * `TC` = 测试用例标识符 * `SS` = 类型内的序列号 (01-99) **自动生成的 ID 示例**： defgenerate_test_id(tspec_num:int,test_type:str,existing_ids:list)->str: """生成下一个可用的测试 ID。""" type_prefix = test_type.upper() # UTEST、ITEST 等现有_for_type = [现有_ids中的id if id.startswith(f"{type_prefix}-{tspec_num:02d}-TC-")] 如果现有_for_type： max_seq = max(int(id.split("-")[-1]) 对于现有_for_type 中的 id) 下一个序列 = 最大序列 + 1 其他：下一个序列 = 1 返回 f"{type_prefix}-{tspec_num:02d}-TC-{next_seq:02d}" # 示例：UTEST-01-TC-13（TSPEC-01 中的第 13 个单元测试） #### 第 1 层：自动合并（< 5% 变化） **触发器**：需要额外测试覆盖范围的次要规格更新。 **行动**： 1.从SPEC中解析新的/修改的规范 2. 使用自动生成的 ID 生成新的测试用例存根 3. 在适当的部分插入测试用例 4.增加补丁版本（1.0.0 -> 1.0.1） 5. 使用合并记录更新漂移缓存 **自动生成的测试用例示例**： ## UTEST-01-TC-13：[自动生成] 验证 new_field 参数 @spec: [SPEC-01.api.new_field](../09_SPEC/SPEC-01.md#api-new-field) @drift-merge：2026 年 2 月 10 日自动合并 Tier-1 @status：PENDING_REVIEW **优先级**：P2 **类型**：单位 ### 前提条件 [TODO：根据 SPEC-01.api.new_field 定义前提条件] ### 测试步骤 |步骤|行动|预期结果 | |------|--------|-----------------| | 1 | [TODO：源自 SPEC-01.api.new_field] | [待办事项] | ### 预期结果 [TODO：根据 SPEC-01.api.new_field 定义预期结果] #### 第 2 层：自动合并变更日志（5-15% 变更） **触发器**：影响多个测试用例的中等规格更新。 **行动**： 1. 执行所有第 1 层操作 2. 生成详细的变更日志部分 3. 标记受影响的现有测试以供审查 4. 增加次要版本（1.0.0 -> 1.1.0） 5. 在修复报告中创建偏差摘要 **变更日志部分格式**： ## 漂移变更日志（第 2 层自动合并） **合并日期**：2026-02-10T16:00:00 **规格版本**：SPEC-01 v2.3.0 -> v2.4.0 **变化百分比**：8.5% **版本升级**：1.2.0 -> 1.3.0 ### 添加了新的测试用例 |测试ID |来源规格|描述 | |---------|-------------|----------| | ITEST-01-TC-08 | SPEC-01.api.batch_endpoint |批处理集成测试| | UTEST-01-TC-14 | SPEC-01.validation.new_rule |新验证规则单元测试 | ### 现有测试标记为待审核 |测试ID |原因 |需要采取行动| |---------|--------|-----------------| | UTEST-01-TC-03 |修改上游规格 |回顾预期结果 | | ITEST-01-TC-02 | API合约变更|更新测试步骤 | ### 测试已弃用（未删除） |测试ID |原因 |状态 | |--------|--------|--------| | UTEST-01-TC-05 |规格部分已删除 | [已弃用] | #### 第 3 层：存档和再生（> 15% 变化） **触发因素**：主要的 SPEC 检修需要重大的测试重组。 **行动**： 1. 创建存档清单 2. 存档当前 TSPEC 版本 3. 生成`doc-tspec-autopilot`的再生请求 4. 增加主要版本（1.0.0 -> 2.0.0） 5. 强制人工审查的标志 **存档清单格式**： # TSPEC-01_archive_manifest.yaml 存档： tspec_id：TSPEC-01 存档版本：“1.5.2” 存档日期：“2026-02-10T16:00:00” archive_reason：“第 3 层漂移 - 规格更改超过 15%” 变化百分比：23.4 上游触发：文档：SPEC-01.md 以前的版本：“2.3.0” 当前版本：“3.0.0” 修改日期：“2026-02-10T14:00:00” 存档测试：总数：25 按类型：测试：12 测试：8 测试：3 最佳测试：2 deprecated_not_deleted： - 编号：UTEST-01-TC-05 原因：“删除了规格部分 FR-001.3” Original_spec_ref：“SPEC-01.fr.001.3” - 编号：ITEST-01-TC-03 原因：“集成点已弃用” Original_spec_ref: "SPEC-01.api.legacy" 再生：触发：真 target_skill：doc-tspec-自动驾驶仪新版本：“2.0.0” keep_deprecated: 真 archive_location：“docs/10_TSPEC/archive/TSPEC-01_v1.5.2/” #### 禁止删除政策 **关键**：测试永远不会被删除，只会标记为已弃用。 **弃用格式**： ## [已弃用] UTEST-01-TC-05：验证legacy_field参数 @status：已弃用 @已弃用日期：2026-02-10 @deprecated-reason：上游 SPEC-01.fr.001.3 在 v3.0.0 中删除 @original-spec: [SPEC-01.fr.001.3](../09_SPEC/SPEC-01.md#fr-001-3)（不再存在） > **弃用通知**：此测试用例已弃用，将不会执行。 > 保留它是为了历史追溯和审计目的。 **优先级**：P2 **类型**：单位 [原始测试内容保留如下...] **弃用规则**：场景|行动|标记 ---|---|--- 规格部分已删除 |标记已弃用 | `[已弃用]` SPEC 要求已废弃 |标记已弃用 | `[已弃用]` 测试被新测试取代 |标记已弃用参考 | `[已弃用] 请参阅：NEW-TC-ID` 测试暂时禁用 |标记已跳过（未弃用）| `[跳过]` #### 增强型漂移缓存漂移缓存跟踪合并历史记录以用于审核和回滚目的。 **缓存位置**：`.drift_cache.json`（项目根或文档文件夹） **增强结构**： { “版本”：“2.0”， “last_updated”：“2026-02-10T16:00:00”， “文件”：{ “TSPEC-01”：{ “当前版本”：“1.3.0”， “last_check”：“2026-02-10T16:00:00”， “上游”：{ “规格-01”：{ “last_version”：“2.4.0”， “最后修改”：“2026-02-10T14:00:00”， "content_hash": "sha256:abc123..." } }, “合并历史记录”：[ { “merge_date”：“2026-02-10T16:00:00”， “等级”：1， “变化百分比”：3.2， "version_before": "1.2.5", "version_after": "1.2.6", “tests_added”：[“UTEST-01-TC-13”]， “测试修改”：[]， “tests_deprecated”：[]， “自动合并”：正确 }, { “merge_date”：“2026-02-08T10:00:00”， “等级”：2， “变化百分比”：8.5， "version_before": "1.1.0", "version_after": "1.2.0", “测试添加”：[“ITEST-01-TC-08”，“UTEST-01-TC-14”]， “tests_modified”：[“UTEST-01-TC-03”，“ITEST-01-TC-02”]， “tests_deprecated”：[“UTEST-01-TC-05”]， “自动合并”：正确， “changelog_ref”：“TSPEC-01.md#drift-changelog-2026-02-08” } ], “已弃用的测试”：[ { “id”：“UTEST-01-TC-05”， “弃用日期”：“2026-02-08”， "reason": "删除了规范部分 FR-001.3", "original_spec_ref": "SPEC-01.fr.001.3" } ] } } } #### 漂移修复操作摘要等级 |变化% |自动修复 |版本 |添加测试 |测试修改|测试已弃用 |存档 ---|---|---|---|---|---|---|--- 1 | < 5% |是的 |补丁|自动生成|无 |无 |否 2 | 5-15% |是的 |次要|自动生成|标记供审查|标记已弃用 |否 3 | > 15% |没有 |专业|全部再生|不适用 |保留所有|是的 **漂移标记格式**（保留用于向后兼容）： @spec: [SPEC-01.auth.login](../09_SPEC/SPEC-01.md#auth-login) ** ** ## 测试用例结构修复 TSPEC 文档包含结构化测试用例。本节详细介绍了具体的测试用例修复策略。 ### 测试用例检测 def find_test_cases(内容: str) -> 列表: """查找 TSPEC 内容中的所有测试用例。""" # 匹配测试用例标题模式 = r'##\s+(TC-\d+|TSPEC\.\d{2}\.40\.\d{2}):\s+(.+)' 返回 re.findall(模式, 内容) ### 必需的测试用例元素元素|必填 |默认值 ---|---|--- 身份证 |是的 |从模式生成标题 |是的 | “[TODO：添加标题]” 前提条件 |是的 | “[TODO：定义先决条件]” 步骤|是的 |编号占位符列表预期结果 |是的 | “[TODO：定义预期结果]” 优先|没有 | P2 类型 |没有 |功能性状态 |没有 |待定 ### 测试用例模板 ## TSPEC.NN.40.SS：[测试用例标题] **优先级**：P1 | P2 | P3 **类型**：单位 |整合|系统|性能 **状态**：待定 |进行中 |通行证 |失败|跳过 @spec: [SPEC-XX.section](../09_SPEC/SPEC-XX.md#section) ### 前提条件 1.【前提1】 2.【前提条件2】 ### 测试步骤 |步骤|行动|预期结果 | |------|--------|-----------------| | 1 | [行动1] | [预计 1] | | 2 | [行动2]| [预计2]| ### 预期结果【总体预期成果描述】 ### 测试数据 - **输入**：[输入数据参考] - **预期输出**：[预期输出参考] ### 结构修复行动问题 |修复动作 ---|--- 缺少先决条件部分 |添加带有占位符的部分缺少步骤表|添加表结构缺少预期结果 |添加带有占位符的部分格式错误的步骤表 |修复表结构缺少规格参考 |添加@spec占位符 ** ** ## 命令用法 ### 基本用法 # 根据最新评论修复 TSPEC /doc-tspec-fixer TSPEC-01 # 使用明确的审计报告修复（首选） /doc-tspec-fixer TSPEC-01 --review-report TSPEC-01.A_audit_report_v001.md # 使用明确的遗留审查报告进行修复（支持） /doc-tspec-fixer TSPEC-01 --review-report TSPEC-01.R_review_report_v001.md # 修复并重新运行审核 /doc-tspec-fixer TSPEC-01 --revalidate # 修复迭代限制 /doc-tspec-fixer TSPEC-01 --revalidate --max-iterations 3 # 仅修复测试用例结构 /doc-tspec-fixer TSPEC-01 --fix-types test_cases ### 选项选项|默认 |描述 ---|---|--- `--审查报告` |最新 |使用的具体审查报告 `--重新验证` |假 |修复后运行审阅者 `--最大迭代次数` | 3 |最大修复审查周期 `--修复类型` |全部 |特定修复类型（以逗号分隔） `--创建缺失` |真实 |创建缺失的参考文件 `--备份` |真实 |修复前备份 TSPEC `--试运行` |假 |预览修复而不应用 `--验证结构` |真实 |修复后验证测试用例结构 `--承认漂移` |假 |交互式漂移确认模式 `--更新漂移缓存` |真实 |修复后更新 .drift_cache.json ### 修复类型类型 |描述 ---|--- `丢失的文件` |创建缺失的测试数据、夹具、矩阵文档 `损坏的链接` |修复链接路径 `element_ids` |转换无效/旧元素 ID (40-43) `内容` |修复占位符、日期、名称 `参考文献` |更新 SPEC 可追溯性和交叉引用 ‘漂移’ |处理上游漂移检测问题 `测试用例` |修复测试用例结构问题 `全部` |所有修复类型（默认） ** ** ## 输出工件 ### 修复报告 **嵌套文件夹规则**：所有 TSPEC 使用嵌套文件夹 (`TSPEC-NN_{slug}/`)，无论大小如何。修复报告与 TSPEC 文档一起存储在嵌套文件夹中。 **文件命名** : `TSPEC-NN.F_fix_report_vNNN.md` **位置**：在 TSPEC 嵌套文件夹内：`docs/10_TSPEC/TSPEC-NN_{slug}/` **结构**： --- 标题：“TSPEC-NN.F：修复报告 v001” 标签： - tspec - 修复报告 - 质量保证自定义字段： document_type：修复报告工件类型：TSPEC-FIX 层数：10 父文档：TSPEC-NN 来源审查：TSPEC-NN.A_audit_report_v001.md fix_date: "YYYY-MM-DDTHH:MM:SS" 修复工具：doc-tspec-修复器修复版本：“1.0” --- # TSPEC-NN 修复报告 v001 ## 总结 |公制|价值| |--------|--------| |来源评论 | TSPEC-NN.A_audit_report_v001.md | |审查中的问题 | 20 | |已解决的问题 | 17 | 17 |剩余问题 | 3（需要人工审核）| |文件已创建 | 2 | |文件修改 | 1 | |修复测试用例 | 5 | ## 文件已创建 |文件|类型 |地点 | |------|------|----------| | TSPEC-01_test_data.yaml |测试数据|文档/10_TSPEC/数据/ | | TSPEC-01_fixtures.yaml |测试夹具|文档/10_TSPEC/装置/ | ## 测试用例结构修复 |测试用例|问题 |修复应用| |----------|------|----------------| | TC-001 |缺少先决条件 |添加占位符部分 | | TC-003 |缺少步骤表|添加表结构 | | TC-005 |格式错误的预期结果 |修复部分格式 | | TC-007 |缺少规格参考 |添加了 @spec 占位符 | | TC-009 |元素 ID 无效 |转换为 TSPEC.01.40.09 | ## 应用的修复 | ＃|问题代码 |问题 |修复已应用 |文件| |---|------------|--------|-------------|-----| | 1 | REV-N004 |无效的元素类型 |转换为 40 型 | TSPEC-01.md | | 2 | REV-T001 |缺少测试步骤 |添加表结构 | TSPEC-01.md | | 3 | REV-L003 |使用绝对路径|转换为相对| TSPEC-01.md | ## 需要人工审核的问题 | ＃|问题代码 |问题 |地点 |原因 | |---|------------|--------|----------|--------| | 1 | REV-P001 | [TODO] 占位符 | TSPEC-01.md:L78 |需要测试内容 | | 2 | REV-D002 |规格内容已更改 | SPEC-01.auth |审查规范更新 | ## 上游漂移总结 |上游文档 |参考|修改| TSPEC 更新 |陈旧的日子|需要采取行动| |--------------------|-----------|----------|---------------|------------|------| | SPEC-01.md | TSPEC-01：L57 | 2026-02-08 | 2026-02-05 | 3 |审查变更 | ## 修复后验证 |公制|之前 |之后|达美航空 | |--------|--------|--------|--------| |评论分数 | 82 | 82 94 | 94 +12 | |错误 | 6 | 0 | -6 | |警告| 8 | 3 | -5 | |有效的测试用例| 12/17 | 17/17 | 17/17 +5 | ## 后续步骤 1. 完成测试用例步骤中的[TODO]占位符 2. 检查上游 SPEC 漂移 3. 在 TSPEC-01_test_data.yaml 中填充测试数据 4. 运行“/doc-tspec-reviewer TSPEC-01”来验证修复 ** ** ## 与自动驾驶仪集成该技能由审核 -> 修复周期中的“doc-tspec-autopilot”调用：流程图LR 子图 Phase5[“第 5 阶段：审查和修复周期”] A[doc-tspec-reviewer] --> B{分数 >= 90?} B -->|否| C[doc-tspec-修复程序] C --> D{迭代 < 最大值？} D -->|是|一个 D -->|否| E[手动审核标志] B -->|是| F[通过] 结束 **自动驾驶仪集成点**：相|行动|技能 ---|---|--- 5a 阶段 |进行初步审查 | `doc-tspec-审稿人` 5b 阶段 |如果发现问题，请应用修复程序 | `doc-tspec-修复程序` 5c 阶段 |重新运行审核 | `doc-tspec-审稿人` 5d 阶段 |重复直到通过或最大迭代 |循环 ** ** ## 错误处理 ### 恢复行动错误 |行动 ---|--- 未找到审查报告 |提示先运行 `doc-tspec-reviewer` 无法创建文件（权限）|记录错误，继续其他修复无法解析审核报告 |中止并显示明确的错误消息测试用例解析错误 |尝试修复，如果无法恢复则标记超出最大迭代次数 |生成报告、标记以供手动审核 ### 备份策略在应用任何修复之前： 1. 在 `tmp/backup/TSPEC-NN_YYYYMMDD_HHMMSS/` 中创建备份 2. 将所有 TSPEC 文件复制到备份位置 3. 对原始文件应用修复 4. 如果修复过程中出现错误，请从备份恢复 ** ** ## 相关技能技能|关系 ---|--- `doc-tspec-审稿人` |提供审查报告（输入） `doc-tspec-自动驾驶仪` |协调审核 -> 修复周期 `doc-tspec-验证器` |结构验证 `文档命名` |元素 ID 标准 `doc-tspec` | TSPEC 创建规则 `文档规范` | SPEC上游可追溯性 ** ** ## 版本历史版本 |日期 |变化 ---|---|--- 2.3 | 2.3 2026-02-27 |使用“versioning_policy”将 frontmatter 标准化为“metadata”模式；将上游合同更新为审核优先（首选“.A_”）并兼容“.R_”；添加了确定性报告优先规则；更新了审计包装流程的修复程序命令和报告示例 2.2 | 2.2 2026-02-26 |添加了 PTEST（代码 44）和 SECTEST（代码 45）支持；更新了类型代码表以使用正确的测试类型名称；将 PTEST/SECTEST 添加到嵌套文件夹表中 2.1 | 2.1 2026-02-11 | **结构合规性**：添加了用于嵌套文件夹规则实施的阶段 0 (REV-STR001-STR004)；在其他修复阶段之前首先运行 2.0 | 2026-02-10 |增强的第 6 阶段，具有分层自动合并系统（第 1 层：<5% 自动合并补丁，第 2 层：5-15% 自动合并次要内容和更改日志，第 3 层：>15% 存档并重新生成主要内容）；添加了 TSPEC 的测试 ID 模式（UTEST/ITEST/STEST/FTEST/PTEST/SECTEST-NN-TC-SS 格式）；实施带有[已弃用]标记的不删除政策；增强了漂移缓存，具有合并历史记录跟踪功能；添加了第 3 层的存档清单创建；自动生成的测试 ID 支持 1.0 | 2026-02-10 |初始技能创造； 6 阶段修复工作流程；测试用例结构修复；测试数据和夹具文件生成；元素ID转换（类型40-43）； SPEC 漂移处理；与自动驾驶仪集成审核->修复周期 ## 实施计划一致性 (IPLAN-004) * 将计划派生的输出视为有效的源模式，并验证实施计划范围/目标的意图保留。 * 验证上游自动驾驶仪优先级假设：`--iplan > --ref > --prompt`。 * 将计划上下文和工件输出之间的目标/范围冲突标记为需要澄清的阻塞问题。 * 不要引入旧的后备路径，例如“docs-v2.0/00_REF”。

Doc Tspec 修复程序

包含技能