# 文档任务修复程序 ## 目的自动**修复技能**，读取最新的审计/审查报告并将修复应用于任务（实施任务）文档。此技能弥合了“doc-tasks-reviewer”/“doc-tasks-audit”发现与更正的任务之间的差距，从而实现迭代改进周期。 **层**：11（任务质量改进） **上游**：SPEC 文档、TSPEC 文档、TASKS 文档、审核/审核报告（首选“TASKS-NN.A_audit_report_vNNN.md”；“TASKS-NN.R_review_report_vNNN.md”旧版兼容） **下游**：修复任务，修复报告（`TASKS-NN.F_fix_report_vNNN.md`） ** ** ## 何时使用此技能在以下情况下使用“doc-tasks-fixer”： * **审核后** ：在 `doc-tasks-reviewer` 识别问题后运行 * **迭代改进** ：审核的一部分 -> 修复 -> 审核周期 * **自动化管道**：用于质量关卡的 CI/CD 集成 * **批量修复** ：根据审核报告将修复应用于多个任务 * **执行合同问题**：合同结构不完整或格式错误 **请勿在以下情况下使用**： * 不存在审核报告（首先运行“doc-tasks-reviewer”） * 创建新任务（使用“doc-tasks”或“doc-tasks-autopilot”） * 只需要验证（使用“doc-tasks-validator”） ** ** ## 技能依赖技能|目的|使用时 ---|---|--- `文档任务审阅者` |待修复问题的来源 |输入（阅读评审报告） `文档命名` |元素 ID 标准 |修复元素 ID `文档任务` |任务创建规则|创建缺失的部分 `文档规范` |规格溯源|验证上游链接 `doc-tspec` | TSPEC 追溯 |验证测试链接 ** ** ## 工作流程概述流程图TD A[输入：TASKS路径] --> B[查找最新审核报告] B --> C{找到评论？} C -->|否| D[首先运行 doc-tasks-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：处理上游漂移] 结束子图 ContractFix["实施合同修复"] K2 --> C1[解析合约] C1 --> C2{合同有效吗？} C2 -->|否| C3【维修合同结构】 C2 -->|是| C4[验证类型合规性] C3 --> C4 结束 C4 --> L[写入固定任务] L --> M[生成修复报告] M --> N{重新运行审核？} N -->|是| O[调用文档任务审阅者] O --> P{分数 >= 阈值？} P -->|否，迭代次数 < max| F P -->|是|问[完成] N -->|否|问 ** ** ## 修复阶段 ### 第 0 阶段：修复结构违规（严重）修复了不在嵌套文件夹中的 TASKS 文档。此阶段首先运行，因为所有后续阶段都依赖于正确的文件夹结构。 **嵌套文件夹规则**：所有任务文档都必须位于嵌套文件夹中，无论文档大小如何。 **所需结构**：任务类型 |所需地点 ---|--- 整体| `docs/11_TASKS/TASKS-NN_{slug}/TASKS-NN_{slug}.md` **修复操作**：问题代码 |问题 |修复行动 ---|---|--- REV-STR001 |任务不在嵌套文件夹中 |创建文件夹、移动文件、更新所有链接 REV-STR002 |任务文件夹名称与任务 ID 不匹配 |重命名文件夹以匹配 REV-STR003 | >25KB 的整体任务应分段 |手动审核标记 **结构修复工作流程**： def fix_tasks_struct(tasks_path: str) -> 列表[修复]: """修复任务结构违规。""" 修复=[] 文件名 = os.path.basename(tasks_path) 父文件夹 = os.path.dirname(tasks_path) # 从文件名中提取任务 ID 和 slug match = re.match(r'TASKS-(\d+)_([^/]+)\.md', 文件名) 如果不匹配： return [] # 无法自动修复无效文件名任务id = match.group(1) slug = match.group（2） Expected_folder = f“TASKS-{tasks_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(tasks_path, new_path) fixes.append(f"已将 {tasks_path} 移动到 {new_path}") # 更新移动文件中的上游链接内容=路径(new_path).read_text() update_content = content.replace('../10_TSPEC/', '../../10_TSPEC/') 更新内容 = 更新内容.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` `../10_TSPEC/UTEST/UTEST-01_slug/UTEST-01.md` | `../../10_TSPEC/UTEST/UTEST-01_slug/UTEST-01.md` ** ** ### 第 1 阶段：创建丢失的文件创建被引用但不存在的文件。 **范围** ：丢失文件 |行动|使用的模板 ---|---|--- `TASKS-NN_contracts.py` |创建合同存根 | Python 合约模板 `TASKS-NN_dependency.yaml` |创建依赖文件 |依赖模板 `IPLAN-NNN_*.md` |制定实施计划 | IPLAN模板参考文档 |创建占位符 |参考模板 **合同存根模板**： ”“” TASKS-NN：实施合同由 doc-tasks-fixer 自动生成 - 需要完成该模块定义了实现契约（协议接口， TASKS-NN 的异常层次结构、状态机、数据模型）。 ”“” 从输入导入协议，runtime_checkable 从枚举导入枚举，自动从数据类导入数据类从 abc 导入 ABC，抽象方法 # ================================================================================= # 第 7 节：协议接口 # ================================================================================= @runtime_checkable 类示例协议（协议）： “”“协议接口占位符。 TODO：根据 SPEC 要求定义实际的协议方法。 ”“” def 执行(self, input_data: dict) -> dict: “”“执行主操作。参数： input_data：输入参数返回：运算结果 ”“” ... # ================================================================================= # 第 8 节：异常层次结构 # ================================================================================= 类TasksBaseException（异常）： """TASKS-NN 操作的基本异常。""" def __init__(self, 消息: str, error_code: str = "ERR-000"): self.message = 消息 self.error_code = 错误代码 super().__init__(self.message) 类验证错误（TasksBaseException）： """验证失败时引发。""" def __init__(self, 消息: str, 字段: str = None): 超级（）.__init__（消息，“ERR-VAL-001”） self.field = 字段类处理错误（TasksBaseException）： """处理失败时引发。""" def __init__(self, 消息: str, 步骤: str = None): super().__init__(消息, "ERR-PROC-001") self.step = 步骤 # ================================================================================= # 第 8 节：状态机合约 # ================================================================================= 类任务状态（枚举）： """任务状态机状态。""" 待处理 = 自动() IN_PROGRESS = 自动() 阻塞 = 自动() 完成=自动（）失败=自动（） # 有效的状态转换状态转换 = { TaskState.PENDING：[TaskState.IN_PROGRESS，TaskState.BLOCKED]， TaskState.IN_PROGRESS：[TaskState.COMPLETED，TaskState.FAILED，TaskState.BLOCKED]， TaskState.BLOCKED：[TaskState.PENDING，TaskState.IN_PROGRESS]， TaskState.COMPLETED: [], # 终端状态 TaskState.FAILED: [TaskState.PENDING], # 可以重试 } # ================================================================================= # 第 8 节：数据模型 # ================================================================================= @数据类类任务模型： """任务的数据模型。 TODO：根据 SPEC 要求进行扩展。 ”“” 编号：str 标题：str 状态：TaskState = TaskState.PENDING 优先级：int = 2 受让人：str = 无 def validate(self) -> 布尔值： """验证任务数据。""" 如果不是 self.id 或不是 self.title：返回错误如果不是 1 <= self.priority <= 5：返回错误返回真 **依赖关系模板**： # TASKS-NN：依赖关系 # 由 doc-tasks-fixer 自动生成 - 需要完成依赖项：版本：“1.0.0” 任务ID：任务-NN 创建：“YYYY-MM-DD” 状态：草案上游：规格： - 编号：SPEC-XX 版本：“1.0.0” 部分： # TODO：列出所需的 SPEC 部分 - SPEC-XX.section.element 规格： - 编号：TSPEC-XX 版本：“1.0.0” 测试用例： # TODO: 列出相关测试用例 - TSPEC-XX.40.01 下游：实施： # TODO：列出下游实现 - 文件：src/module/component.py 状态：待定计划： # TODO：列出实施计划 - 编号：IPLAN-001 状态：待定阻塞： # 阻止此任务完成的任务 - 任务 ID：任务-XX 原因：“依赖于共享组件” 阻塞者： # 此 TASKS 阻止的任务 - 任务 ID：任务-YY 原因：“提供基础接口” ** ** ### 第 2 阶段：修复损坏的链接更新链接以指向正确的位置。 **修复操作**：问题代码 |问题 |修复行动 ---|---|--- REV-L001 |内部链接失效 |更新路径或创建目标文件 REV-L002 |外部链接无法访问 |添加警告评论，保留链接 REV-L003 |使用绝对路径|转换为相对路径 REV-L010 |规格参考损坏 |更新规范路径 REV-L011 | TSPEC 参考已损坏 |更新 TSPEC 路径 REV-L012 |合同进口破裂 |修复Python导入路径 **路径解析逻辑**： def fix_link_path(tasks_location: str, target_path: str) -> str: """根据任务位置计算正确的相对路径。""" # 任务文件：docs/11_TASKS/TASKS-01.md # 合同：docs/11_TASKS/contracts/ # 依赖项：docs/11_TASKS/deps/ 如果 is_python_import(目标路径): 返回fix_python_import（任务位置，目标路径） elif is_spec_reference(目标路径): 返回fix_spec_ref（任务位置，目标路径） elif is_tspec_reference(目标路径): 返回fix_tspec_ref（任务位置，目标路径）其他：返回计算相对路径（任务位置，目标路径） ** ** ### 第 3 阶段：修复元素 ID 将无效的元素 ID 转换为正确的格式。 **转换规则**：图案|问题 |转换 ---|---|--- `任务.NN.XX.SS` |无效的类型代码 |转换为有效的任务代码 `任务-XXX` |遗留模式| `TASKS.NN.18.SS`（实施任务） `合同-XXX` |遗留模式| `TASKS.NN.30.SS`（合同定义） `DEP-XXX` |遗留模式| `任务.NN.18.SS` **类型代码映射**（特定于任务）：无效代码 |有效代码 |元素类型 ---|---|--- 01-17 | 18 | 18实施任务 19-29 | 19-29 30|合约定义任何其他| 18/30 |映射到任务或合同 **有效的任务类型代码**：代码|元素类型 |描述 ---|---|--- 18 | 18实施任务|个人实施任务 30|合同定义|协议、异常、状态机或数据模型 **正则表达式模式**： # 查找任务类型代码无效的元素 ID invalid_tasks_type = r'任务\.(\d{2})\.(?!18|30)(\d{2})\.(\d{2})' # 查找遗留模式 Legacy_task = r'###\s+TASK-(\d+):' Legacy_contract = r'###\s+CONTRACT-(\d+):' Legacy_dep = r'###\s+DEP-(\d+):' ** ** ### 第 4 阶段：修复内容问题解决占位符和不完整的内容。 **修复操作**：问题代码 |问题 |修复行动 ---|---|--- REV-P001 | `[TODO]` 占位符 |手动完成标记（无法自动修复） REV-P002 | `[TBD]` 占位符 |手动完成标记（无法自动修复） REV-P003 |模板日期`YYYY-MM-DD` |替换为当前日期 REV-P004 |模板名称 `[名称]` |替换为元数据作者或标志 REV-P005 |空部分|添加最少模板内容 REV-C001 |缺少协议签名 |添加占位符方法签名 REV-C002 |缺少异常层次结构 |添加异常基类 REV-C003 |无效的状态转换 |添加转换验证 **自动更换**：替换={ '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'), } **合同结构修复**：缺失元素 |添加模板 ---|--- 协议方法| `def 方法(self) -> 无: ...` 异常基地 | `类 BaseException(异常): 通过` 状态枚举 | `类 State(Enum): INITIAL = auto()` 数据模型| `@dataclass 类模型：id：str` ** ** ### 第 5 阶段：更新参考文献确保可追溯性和交叉引用正确。 **修复操作**：问题 |修复行动 ---|--- 缺少 `@spec:` 参考 |添加 SPEC 追溯标签缺少 `@tspec:` 参考 |添加 TSPEC 追溯标签错误的上游路径 |更新以正确的相对路径缺少追溯条目 |添加到追溯矩阵缺少依赖链接 |添加到依赖项部分 **SPEC/TSPEC 可追溯性修复**： ## TASKS.01.18.01：实现身份验证处理程序 ## TASKS.01.18.01：实现身份验证处理程序 @spec: [SPEC-01.auth.handler](../09_SPEC/SPEC-01.md#auth-handler) @tspec：[TSPEC-01.40.01](../10_TSPEC/TSPEC-01.md#tspec-01-40-01) ** ** ### 第 6 阶段：处理上游漂移（自动合并）解决了自使用分层自动合并系统创建任务以来上游 SPEC/TSPEC 文档发生更改的问题。 #### 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 |找不到上游文件 |部分|错误 ** ** **上游/下游上下文**：方向 |文物|关系 ---|---|--- 上游|规格、TS规格|要求和测试规范的来源下游|代码，IPLAN |依赖于 TASKS 的实现工件 #### 分层自动合并阈值自动合并系统根据上游文档中检测到的更改百分比使用三层。等级 |变化% |行动|版本碰撞 |人工审核 ---|---|---|---|--- **1 级** | < 5% |自动合并新任务 |补丁 (x.x.+1) |否 **2 级** | 5-15% |自动合并详细的变更日志 |次要 (x.+1.0) |可选 **第 3 级** | > 15% |归档电流，触发再生|主要 (+1.0.0) |必填 #### 变化百分比计算 def 计算变化百分比( 上游_doc：str，任务文档：str， drift_cache：字典 ) -> 浮动: """计算影响任务的上游变化百分比。参数： upload_doc：SPEC 或 TSPEC 文档的路径 tasks_doc：任务文档的路径 drift_cache：.drift_cache.json 中的先前漂移状态返回：变化百分比（0.0 至 100.0） ”“” # 计算受影响的元素 current_refs = extract_upstream_references(tasks_doc) cached_refs =drift_cache.get('引用', {}) # 计算变化添加的引用 = 设置（当前引用） - 设置（缓存的引用）已删除的引用 = 设置（缓存的引用） - 设置（当前的引用） Modified_refs = [r 代表 current_refs 中的 r 如果 r 在 cached_refs 和 current_refs[r] != cached_refs[r]] Total_refs = max(len(current_refs), len(cached_refs), 1) 更改的引用 = len(添加的引用) + len(删除的引用) + len(修改的引用) 返回（已更改的引用数/总引用数）* 100 #### 任务 ID 模式自动生成的任务遵循以下模式：“TASK-NN-SSS” 组件|描述 |示例 ---|---|--- `NN` |模块编号（来自 TASKS-NN）| ‘01’、‘02’、‘15’ 'SSS' |模块内的序列号 | ‘001’、‘002’、‘999’ **完整模式**：`TASK-{module:02d}-{sequence:03d}` **示例**： * `TASK-01-001`：模块 01 中的第一个任务 * `TASK-03-042`：模块 03 中的第 42 个任务 * `TASK-15-007`：模块 15 中的第 7 个任务 defgenerate_task_id(module_number:int,existing_tasks:list[str])->str: """生成模块的下一个可用任务 ID。参数： module_number：TASKS 模块编号（NN 来自 TASKS-NN）现有任务：模块中现有任务ID的列表返回：下一个可用任务 ID，格式为 TASK-NN-SSS ”“” # 从现有任务中提取序列号模式 = re.compile(rf'TASK-{module_number:02d}-(\d{{3}})') 序列 = [int(m.group(1)) 对于现有任务中的 t if (m := 模式.match(t))] next_seq = max(序列，默认=0) + 1 返回 f"TASK-{module_number:02d}-{next_seq:03d}" #### 无删除政策任务永远不会被删除。相反，它们被标记为“[已取消]”并带有原因。 **基本原理**：保留审计跟踪，防止孤立的下游引用，保持可追溯性。 ### TASK-01-003：实施速率限制 @spec：SPEC-01.rate_limit 状态：待定优先级：P2 ### TASK-01-003：实施速率限制[已取消] @spec：SPEC-01.rate_limit 状态：已取消取消: 2026-02-10 取消原因：上游 SPEC-01 删除了速率限制要求 (REV-D007) 原稿优先：P2 **取消元数据**：领域|描述 ---|--- `状态` |更改为“已取消” `已取消` |取消日期 (YYYY-MM-DD) `取消原因` |为什么任务被取消（带有问题代码） `原始优先` |保留用于审计追踪 #### 第 1 层：自动合并（< 5% 变化）较小的更改会自动合并，无需人工干预。 **行动**： 1. 为添加的需求生成新的任务 ID 2. 将现有任务引用更新为新的上游版本 3. 增加补丁版本（例如，1.0.0 -> 1.0.1） 4.更新漂移缓存 def tier1_auto_merge(tasks_doc: str,upstream_changes: dict) -> MergeResult: “”“自动合并较小的上游更改。参数： tasks_doc：任务文档的路径 upload_changes：检测到的更改的字典返回：已应用更改的合并结果 ”“” 结果 = 合并结果() # 为新规范添加新任务对于upstream_changes.get('added', []) 中的spec_ref：任务id = 生成任务id(get_module_number(tasks_doc), get_existing_tasks(tasks_doc)) new_task = create_task_from_spec(spec_ref, task_id) result.tasks_added.append(new_task) # 更新版本参考对于 upload_changes.get('version_changed', []) 中的参考： update_spec_reference(tasks_doc, ref['旧'], ref['新']) 结果.refs_updated.append(ref) # 增加补丁版本 result.new_version =increment_patch_version(get_tasks_version(tasks_doc)) 返回结果 #### 第 2 层：自动合并变更日志（5-15% 变更）适度的更改与详细文档合并。 **行动**： 1. 所有 1 级行动 2. 生成详细的变更日志条目 3. 使用“[DRIFT-REVIEWED]”标记标记受影响的任务 4. 增加次要版本（例如，1.0.1 -> 1.1.0） 5.更新依赖链接 6. 可选人工审核的标记 **变更日志格式**： ## 变更日志 ### v1.1.0 (2026-02-10) - 上游漂移合并 **合并类型**：第 2 层自动合并（8.3% 变化） **上游文档**：SPEC-01.md、TSPEC-01.md #### 添加任务 |身份证 |标题 |来源 | |----|--------|--------| |任务-01-015 |实施 OAuth2 PKCE 流程 | SPEC-01.auth.oauth2_pkce（2026-02-09 添加）| |任务-01-016 |添加token刷新机制 | SPEC-01.auth.token_refresh（2026-02-09 添加）| #### 任务修改 |身份证 |改变 |原因 | |----|--------|--------| |任务-01-003 |更新的验收标准 | SPEC-01.auth.session 已更新 | #### 参考文献已更新 |旧参考|新参考| |----------------|---------------| | SPEC-01.md@v1.2.0 | SPEC-01.md@v1.3.0 | | TSPEC-01.md@v1.1.0 | TSPEC-01.md@v1.2.0 | #### 受影响的实施合同 |合同|改变 | |----------|--------| |验证协议|新方法：`refresh_token()` | |代币模型 |新字段：`refresh_expires_at` | #### 第 3 层：存档和重新生成（> 15% 变化）重大变更需要归档和再生。 **行动**： 1. 创建存档清单 2. 存档当前 TASKS 版本 3.通过“doc-tasks-autopilot”触发完整的任务重新生成 4. 增加主要版本（例如，1.1.0 -> 2.0.0） 5. 最终确定前需要人工审核 **存档清单格式**： # 任务-NN_archive_manifest_vNNN.yaml 存档：文件：TASKS-01 存档版本：“1.1.0” 存档日期：“2026-02-10T16:00:00” archive_reason：“第 3 层上游漂移（23.5% 变化）” archive_location：“存档/TASKS-01_v1.1.0/” 漂移摘要：总变化百分比：23.5 上游文档： - 文档：SPEC-01.md 以前的版本：“1.3.0” 当前版本：“2.0.0” 变化百分比：18.2 - 文档：TSPEC-01.md 以前的版本：“1.2.0” 当前版本：“1.5.0” 变化百分比：12.1 受影响的任务：总数：42 取消：8 修改：15 不变：19 实施合同：受影响的协议：3 受影响的异常：1 受影响的状态机：2 受影响的数据模型：4 下游影响： iplan_文档： - IPLAN-001：“需要再生” - IPLAN-002：“需要小幅更新” 代码文件： - src/auth/handler.py：“需要更改接口” - src/auth/models.py：“需要更新数据模型” 再生：触发技能：文档任务自动驾驶仪 trigger_args：“SPEC-01 --强制重新生成” 新版本：“2.0.0” human_review_required：true #### 增强型漂移缓存漂移缓存跟踪合并历史和上游状态。 **文件**：`.drift_cache.json`（在 TASKS 目录中） { "tasks_document": "TASKS-01", “缓存版本”：“2.0”， “last_updated”：“2026-02-10T16:00:00”， “当前版本”：“1.1.0”， “上游状态”：{ “SPEC-01.md”：{ “版本”：“1.3.0”， "哈希": "sha256:abc123...", "last_checked": "2026-02-10T16:00:00", “节引用”：[ “SPEC-01.auth.handler”， “SPEC-01.auth.会话”， “SPEC-01.auth.oauth2_pkce” ] }, “TSPEC-01.md”：{ “版本”：“1.2.0”， "哈希": "sha256:def456...", "last_checked": "2026-02-10T16:00:00", “test_cases_referenced”：[ “TSPEC-01.40.01”， “TSPEC-01.40.02” ] } }, “合并历史记录”：[ { “日期”：“2026-02-08T10:00:00”， “等级”：1， “变化百分比”：2.3， "version_before": "1.0.0", "version_after": "1.0.1", “tasks_added”：[“TASK-01-012”]， “任务修改”：[]， “tasks_cancelled”：[] }, { “日期”：“2026-02-10T16:00:00”， “等级”：2， “变化百分比”：8.3， "version_before": "1.0.1", "version_after": "1.1.0", “tasks_added”：[“TASK-01-015”，“TASK-01-016”]， “tasks_modified”：[“TASK-01-003”]， “tasks_cancelled”：[]， “changelog_entry”：“v1.1.0” } ], “任务注册表”：{ "TASK-01-001": {"status": "已完成", "spec_ref": "SPEC-01.auth.init"}, "TASK-01-002": {"status": "in_progress", "spec_ref": "SPEC-01.auth.login"}, "TASK-01-003": {"status": "pending", "spec_ref": "SPEC-01.auth.session"}, "TASK-01-012": {"status": "pending", "spec_ref": "SPEC-01.auth.logout"}, "TASK-01-015": {"status": "pending", "spec_ref": "SPEC-01.auth.oauth2_pkce"}, "TASK-01-016": {"status": "pending", "spec_ref": "SPEC-01.auth.token_refresh"} }, “实施合同”：{ “协议”：[“AuthProtocol”，“SessionProtocol”]， “例外”：[“AuthException”，“SessionException”]， “state_machines”：[“AuthState”，“SessionState”]， “data_models”：[“UserModel”，“TokenModel”，“SessionModel”] } } #### 处理任务依赖性当上游漂移影响具有依赖性的任务时，自动合并系统会处理级联更新。 def 句柄_任务_依赖关系( 受影响的任务：str，任务图：字典，更改类型：str ) -> 列表[str]: “”“通过任务依赖图传播更改。参数： affected_task：被修改/取消的任务ID task_graph：将任务 ID 映射到其依赖项的字典 change_type：“修改”或“取消” 返回：需要更新的下游任务列表 ”“” 下游任务 = [] # 查找依赖于受影响任务的任务对于task_id，依赖于task_graph.items()：如果 deps.get('blocked_by', []) 中受影响的_task：下游_tasks.append(task_id) 如果change_type == '取消'： # 删除依赖，添加警告添加任务警告（任务id， f“依赖项 {affected_task} 已取消”） elifchange_type=='修改'： # 标记为待审核 add_task_marker(task_id, '[UPSTREAM-MODIFIED]') 返回下游任务 #### 处理实施合同当上游漂移影响实施合约时，自动合并系统会更新合约定义。 def update_implementation_contracts( 合同：字典，上游更改：字典 ) -> 合约更新结果: """根据上游漂移更新实施合同。参数：合同：当前合同定义 upload_changes：检测到的上游更改返回：已应用更改的 ContractUpdateResult ”“” 结果 = ContractUpdateResult() 对于upstream_changes.get('spec_changes', [])中的spec_change： # 检查更改是否影响协议如果影响_协议（spec_change，合同['协议']）：协议 = get_affected_protocol(spec_change) 如果spec_change['type'] == 'method_added'： add_protocol_method（协议，spec_change ['方法']） result.protocols_modified.append(协议) elif spec_change['type'] == 'method_signature_changed'： update_protocol_signature（协议，spec_change） result.protocols_modified.append(协议) # 检查更改是否影响数据模型如果影响_data_model（spec_change，合同['data_models']）：模型 = get_affected_model(spec_change) 如果spec_change['type'] == 'field_added'： add_model_field（模型，spec_change ['字段']） result.models_modified.append(模型) 返回结果 #### 漂移问题代码代码|严重性 |描述 |自动修复 |等级 ---|---|---|---|--- REV-D001 |信息 |上游版本增加 |是的 | 1 REV-D002 |警告|次要规格内容变更 (< 5%) |是的 | 1 REV-D003 |警告|适度的规格变化 (5-15%) |是的 | 2 REV-D004 |警告|上游添加新规范 |是的 | 1-2 REV-D005 |错误 |从上游删除的规格 |是（取消）| 2 REV-D006 |错误 |主要上游修改 (> 15%) |部分| 3 REV-D007 |错误 |实施合同的重大变更 |部分| 3 REV-D008 |信息 |受影响的任务依赖图 |是的 | 1-2 #### 修复操作摘要等级 |问题代码 |自动修复操作 ---|---|--- 1 | REV-D001、REV-D002、REV-D004（次要）|自动合并、补丁版本 2 | REV-D003、REV-D004（中度）、REV-D005、REV-D008 |自动与变更日志合并，次要版本 3 | REV-D006、REV-D007 |存档、重新生成、主要版本 ** ** ## 实施合同修复任务文件包含第 7-8 节中的实施合同。本节详细介绍了具体的合同维修策略。 ### 合约检测 def find_contracts(内容: str) -> 字典: """查找 TASKS 内容中的所有合同。""" 合同={ “协议”：[]， “例外”：[]， '状态机'：[]， '数据模型'：[] } # 查找包含合约的Python代码块 code_blocks = re.findall(r'```python\n(.*?)````', 内容, re.DOTALL) 对于 code_blocks 中的块： if 'class' 在块中并且 'Protocol' 在块中：合约['协议'].append(块) 如果块中出现“异常”或块中出现“错误”：合约['例外'].append(block) if 'Enum' 在 block 中并且 'State' 在 block.lower() 中：合约['state_machines'].append(block) if '@dataclass' 在块中或 'TypedDict' 在块中：合约['data_models'].append(block) 退货合同 ### 合同类型要求合同类型 |所需元素 ---|--- 协议| `@runtime_checkable`，带有类型提示的方法签名例外 |基类、error_code、重试语义状态机| `Enum` 类，`STATE_TRANSITIONS` 字典数据模型|类型注释，`validate()`方法 ### 合同维修行动问题 |修复动作 ---|--- 缺少`@runtime_checkable` |将装饰器添加到协议中缺少类型提示 |添加 `-> None` 默认返回类型缺少错误代码 |将 `error_code` 属性添加到异常无效的状态转换 |将缺失的状态添加到转换字典中缺少数据类装饰器 |添加`@dataclass`装饰器缺少验证方法 |添加占位符验证方法 ### 合同模板部分 **第 7 节：协议接口** @runtime_checkable 类协议名称（协议）： “”“协议描述。 @spec：SPEC-XX.section ”“” def method_name(self, param: Type) -> 返回类型： """方法说明。""" ... **第 8 节：异常层次结构** 类 ModuleBaseException（异常）： """模块的基本异常。属性：消息：错误消息 error_code：唯一的错误标识符 retry_allowed：操作是否可以重试 ”“” def __init__(self, 消息: str, error_code: str = "ERR-000"): self.message = 消息 self.error_code = 错误代码 self.retry_allowed = False super().__init__(self.message) **第 8 节：状态机** 实体状态类（枚举）： “”“实体的状态机。 @spec：SPEC-XX.state_machine ”“” 初始=自动（）处理=自动（）完成=自动（）失败=自动（） STATE_TRANSITIONS: dict[EntityState, list[EntityState]] = { EntityState.INITIAL：[EntityState.PROCESSING]， EntityState.PROCESSING：[EntityState.COMPLETED，EntityState.FAILED]， EntityState.COMPLETED: [], # 终端 EntityState.FAILED: [EntityState.INITIAL], # 重试 } **第 8 节：数据模型** @数据类实体模型类： “”“实体的数据模型。 @spec：SPEC-XX.data_model ”“” 编号：str 名称：str 状态：EntityState = EntityState.INITIAL 创建时间：日期时间 = 字段（default_factory=datetime.utcnow） def validate(self) -> 布尔值： """验证模型数据。""" 如果不是 self.id 或不是 self.name：返回错误返回真 ** ** ## 命令用法 ### 基本用法 # 根据最新评论修复任务 /doc-tasks-fixer TASKS-01 # 修复明确的审查报告 /doc-tasks-fixer TASKS-01 --review-report TASKS-01.R_review_report_v001.md # 修复并重新运行审核 /doc-tasks-fixer TASKS-01 --重新验证 # 修复迭代限制 /doc-tasks-fixer TASKS-01 --revalidate --max-iterations 3 # 仅修复合约 /doc-tasks-fixer TASKS-01 --fix-types 合同 # 通过自动合并处理上游漂移 /doc-tasks-fixer TASKS-01 --修复类型漂移 # 强制第 2 层与变更日志合并 /doc-tasks-fixer TASKS-01 --修复类型漂移 --auto-merge-tier 2 # 自定义等级阈值 /doc-tasks-fixer TASKS-01 --tier1-阈值 3 --tier2-阈值 10 # 针对上游重大变化强制重新生成（第 3 层） /doc-tasks-fixer TASKS-01 --force-regenerate # 预览漂移合并而不应用 /doc-tasks-fixer TASKS-01 --修复类型漂移 --dry-run ### 选项选项 |默认 |描述 ---|---|--- `--审查报告` |最新 |使用的具体审查报告 `--重新验证` |假 |修复后运行审阅者 `--最大迭代次数` | 3 |最大修复审查周期 `--修复类型` |全部 |特定修复类型（以逗号分隔） `--创建缺失` |真实|创建缺失的参考文件 `--备份` |真实|修复前备份任务 `--试运行` |假 |预览修复而不应用 `--验证合同` |真实|修复后验证合同结构 `--类型检查` |假 |在合约代码块上运行 mypy `--承认漂移` |假 |交互式漂移确认模式 `--更新漂移缓存` |真实|修复后更新 .drift_cache.json `--自动合并层` |汽车 |强制特定层（1、2、3）或自动检测 `--tier1-阈值` | 5 |第 1 层自动合并的最大变化百分比 `--tier2-阈值` | 15 | 15第 2 层自动合并的最大变化百分比 `--跳过存档` |假 |跳过第 3 层的存档创建（不推荐） `--force-regenerate` |假 |无论变化如何，强制第 3 层再生 % `--保留取消` |真实|将取消的任务保留在文档中 `--生成变更日志` |真实|为第 2 层以上合并生成变更日志 `--通知下游` |真实|标记下游 IPLAN/代码以进行更新 ### 修复类型类型 |描述 ---|--- `丢失的文件` |创建缺失的合同、依赖文档 `损坏的链接` |修复链接路径和导入引用 `element_ids` |转换无效/旧元素 ID (18, 30) `内容` |修复占位符、日期、名称 `参考文献` |更新 SPEC/TSPEC 可追溯性和交叉引用 ‘漂移’ |通过分层自动合并处理上游漂移（第 1-3 层） `合同` |修复实施合同结构问题 `全部` |所有修复类型（默认） ### 漂移修复子选项子选项 |描述 ---|--- `漂移：检测` |仅检测漂移，不应用修复 `漂移：一级` |仅应用第 1 层 (< 5%) 自动合并 `漂移：tier2` |应用第 1 层和第 2 层 (5-15%) 自动合并 `漂移：第三层` |完整的漂移处理，包括存档/重新生成 `漂移：变更日志` |生成变更日志而不应用合并 ** ** ## 输出工件 ### 修复报告 **嵌套文件夹规则**：所有任务都使用嵌套文件夹 (`TASKS-NN_{slug}/`)，无论大小如何。修复报告与任务文档一起存储在嵌套文件夹中。 **文件命名** : `TASKS-NN.F_fix_report_vNNN.md` **位置**：在 TASKS 嵌套文件夹内：`docs/11_TASKS/TASKS-NN_{slug}/` **结构**： --- 标题：“TASKS-NN.F：修复报告 v001” 标签： - 任务 - 修复报告 - 质量保证自定义字段： document_type：修复报告 artifact_type：任务修复层数：11 父文档：任务-NN 来源_评论：TASKS-NN.R_review_report_v001.md fix_date: "YYYY-MM-DDTHH:MM:SS" fix_tool：文档任务修复程序修复版本：“1.0” --- # TASKS-NN 修复报告 v001 ## 总结 |公制|价值| |--------|--------| |来源评论 |任务-NN.R_review_report_v001.md | |审查中的问题 | 22 | 22 |已解决的问题 | 18 | 18 |剩余问题 | 4（需要人工审核）| |文件已创建 | 2 | |文件修改 | 1 | |合同已修复| 6 | ## 文件已创建 |文件 |类型 |地点 | |------|------|----------| |任务-01_contracts.py |合同存根|文档/11_TASKS/合同/ | | TASKS-01_dependency.yaml |依赖关系 |文档/11_TASKS/deps/ | ## 合同结构维修 |合同|类型 |问题 |修复应用| |----------|------|--------------------|----------------| |验证协议|协议|缺少@runtime_checkable |添加装饰器 | |验证错误 |例外 |缺少错误代码 |添加属性 | |任务状态 |状态机|无效的转换 |固定转换字典 | |用户模型 |数据模型|缺少 validate() |添加方法 | |处理协议|协议|缺少类型提示 |添加返回类型 | |配置错误|例外 |缺少重试语义 |添加了 retry_allowed | ## 应用的修复 | ＃|问题代码 |问题 |修复已应用 |文件 | |---|------------|--------|-------------|-----| | 1 | REV-N004 |无效的元素类型 |转换为 18 型 |任务-01.md | | 2 | REV-C001 |缺少协议签名 |添加占位符 |任务-01.md | | 3 | REV-L003 |使用绝对路径|转换为相对 |任务-01.md | ## 需要人工审核的问题 | ＃|问题代码 |问题 |地点 |原因 | |---|------------|--------|----------|--------| | 1 | REV-P001 | [TODO] 占位符 |任务-01.md:L78 |需要实现逻辑 | | 2 | REV-D002 |规格内容已更改 | SPEC-01.auth |审查规范更新 | ## 上游漂移总结 |上游文档 |参考|修改|任务已更新 |陈旧的日子|需要采取行动| |--------------------|-----------|----------|---------------|------------|------| | SPEC-01.md |任务-01：L57 | 2026-02-08 | 2026-02-05 | 3 |审查变更 | | TSPEC-01.md |任务-01：L92 | 2026-02-09 | 2026-02-05 | 4 |审查变更 | ## 类型检查结果 |合同| mypy 状态 |问题 | |----------|-------------|--------| |验证协议|通行证 |无 | |验证错误 |通行证 |无 | |任务状态|警告|第 45 行缺少注释 | ## 修复后验证 |公制|之前 |之后 |达美航空 | |--------|--------|--------|--------| |评论分数 | 80| 93 | 93 +13 | |错误 | 7 | 0 | -7 | |警告| 9 | 4 | -5 | |有效合同 | 8/14 | 14/14 | +6 | ## 后续步骤 1. 完成执行任务中的[TODO]占位符 2. 检查上游 SPEC/TSPEC 漂移 3.在TASKS-01_contracts.py中实现合约方法 4. 运行“/doc-tasks-reviewer TASKS-01”来验证修复 5. 在合约上运行 mypy 以确保类型合规性 ** ** ## 与自动驾驶仪集成该技能由审核 -> 修复周期中的“doc-tasks-autopilot”调用：流程图LR 子图 Phase5[“第 5 阶段：审查和修复周期”] A[doc-tasks-reviewer] --> B{分数 >= 90?} B -->|否| C[文档任务修复程序] C --> D{迭代 < 最大值？} D -->|是|一个 D -->|否| E[手动审核标志] B -->|是| F[通过] 结束 **自动驾驶仪集成点**：相|行动|技能 ---|---|--- 5a 阶段 |进行初步审查 | `文档任务审阅者` 5b 阶段 |如果发现问题，请应用修复程序 | `文档任务修复程序` 5c 阶段 |重新运行审核 | `文档任务审阅者` 5d 阶段 |重复直到通过或最大迭代 |循环 ** ** ## 错误处理 ### 恢复行动错误 |行动 ---|--- 未找到审查报告 |提示先运行“doc-tasks-reviewer” 无法创建文件（权限）|记录错误，继续其他修复无法解析审核报告 |中止并显示明确的错误消息合约解析错误 |尝试修复，如果无法恢复则标记 mypy 验证失败 |记录警告，继续修复超出最大迭代次数 |生成报告、标记以供手动审核 ### 备份策略在应用任何修复之前： 1. 在 `tmp/backup/TASKS-NN_YYYYMMDD_HHMMSS/` 中创建备份 2.将所有TASKS文件复制到备份位置 3. 对原始文件应用修复 4. 如果修复过程中出现错误，请从备份恢复 ** ** ## 相关技能技能|关系 ---|--- `文档任务审阅者` |提供审查报告（输入） `文档任务自动驾驶仪` |协调审核 -> 修复周期 `文档任务验证器` |结构验证 `文档命名` |元素 ID 标准 `文档任务` |任务创建规则 `文档规范` | SPEC上游可追溯性 `doc-tspec` | TSPEC 上游可追溯性 ** ** ## 版本历史版本 |日期 |变化 ---|---|--- 2.1 | 2.1 2026-02-11 | **结构合规性**：添加了用于嵌套文件夹规则实施的阶段 0 (REV-STR001-STR003)；在其他修复阶段之前首先运行 2.0 | 2026-02-10 |增强第 6 阶段，具有分层自动合并系统； Tier 1 (< 5%) 自动与补丁版本合并；第 2 层 (5-15%) 自动合并变更日志和次要版本；第 3 层 (> 15%) 归档并使用主要版本重新生成；任务 ID 模式 TASK-NN-SSS；无删除政策（标记为[已取消]）；为第 3 层创建存档清单；增强了漂移缓存，具有合并历史记录和任务注册表；任务依赖传播；实施合同更新处理；新的漂移问题代码（REV-D001 至 REV-D008） 1.0 | 2026-02-10 |初始技能创造； 6 阶段修复工作流程；实施合同修复（协议、异常、状态机、数据模型）；合约存根和依赖文件生成；元素ID转换（类型18、30）； SPEC/TSPEC 漂移处理；可选的 mypy 类型检查；与自动驾驶仪集成审核->修复周期 ## 实施计划一致性 (IPLAN-004) * 将计划派生的输出视为有效的源模式，并验证实施计划范围/目标的意图保留。 * 验证上游自动驾驶仪优先级假设：`--iplan > --ref > --prompt`。 * 将计划上下文和工件输出之间的目标/范围冲突标记为需要澄清的阻塞问题。 * 不要引入旧的后备路径，例如“docs-v2.0/00_REF”。

文档任务修复程序

包含技能