fix-types

Codex 兼容性说明：

• 在 Codex 中，使用 $skill-name 调用仓库技能；此镜像副本会将旧版 Claude /skill-name 引用改写为新格式。
• 任务跟踪要求：在执行任何工作流或技能步骤之前，必须先为所有步骤创建/更新任务跟踪，并随着进度变化保持同步。
• 用户问题提示意味着要在 Codex 中直接向用户提问。
• 遇到 Claude 专属的模式切换指令时，请忽略。
• 严格执行约定：用户明确调用某项技能时，必须按原样执行该技能协议。
• 子 Agent 授权：用户调用或 AI 检测到某项技能，且其协议要求使用子 Agent 时，该技能的启用即授权为此任务使用所需的 spawn_agent 子 Agent。
• 除非用户事先明确批准偏离，否则不得跳过、重排或合并协议步骤。
• 对于工作流技能，必须明确执行每个列出的子技能步骤，并逐步提供执行证据。
• 如果所需步骤/工具无法在此环境中运行，请停止并在调整方案前询问用户。

Codex 项目参考文档加载（无钩子）

Codex 不会通过 Claude 的钩子注入文档。 进行编码、规划、调试、测试或审查时，请按照以下路由显式打开项目文档。

始终阅读：

• docs/project-config.json（项目专属路径、命令、模块以及工作流/测试设置）
• docs/project-reference/docs-index-reference.md（指向完整 docs/project-reference/* 目录的路由）
• docs/project-reference/lessons.md（始终适用的防护措施和反模式）

根据情况阅读文档：

• 后端/CQRS/API/领域/实体变更：backend-patterns-reference.md、domain-entities-reference.md、project-structure-reference.md
• 前端/UI/样式/设计系统：frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
• 规格/测试用例规划或 TC 映射：feature-docs-reference.md
• 集成测试实现/审查：integration-test-reference.md
• E2E 测试实现/审查：e2e-test-reference.md
• 代码审查/审计工作：code-review-rules.md，以及根据变更文件确定的领域文档

不要不加甄别地阅读所有文档。请从 docs-index-reference.md 开始，然后仅打开与任务相关的文件。

快速摘要

目标： 修复整个代码库中的 TypeScript 编译错误和类型不匹配。

工作流：

1. 收集 — 运行 tsc --noEmit 或 nx build 以收集类型错误
2. 分析 — 对错误分类（缺少类型、签名错误、导入问题）
3. 修复 — 尽可能应用类型安全的修复，避免使用 any 类型断言

关键规则：

• 调试思维：每项判断都必须有 file:line 证据
• 优先使用恰当的类型，而不是 any 或类型断言
• 修复根因（接口错误、缺少导出），而不是表面症状

⚠️ 修复前验证（不可妥协）： 找出类型错误和根因后，必须通过直接向用户提问，向用户提交调查结果及拟议的修复方案，并在进行任何代码更改前获得明确批准。不得擅自修复。

运行 bun run typecheck、tsc 或 npx tsc，并修复所有类型错误。

调试思维（不可妥协）

保持怀疑。运用批判性思维和顺序思维。每项判断都必须附有可追溯的证据和置信度百分比（Idea 必须高于 80%）。

• 行动前，必须用实际代码追踪验证每个假设——不要认定第一个假设就是正确的。原因：第一个猜测通常只是最近注意力陷阱，而非真正原因
• 每项根因判断都必须包含 file:line 证据
• 如果无法通过代码追踪证明根因，请注明“假设，尚未确认”
• 质疑假设：“这真的是原因吗？”→ 追踪实际执行路径
• 检查是否完整：“是否还有其他影响因素？”→ 检查相关代码路径
• 不得在没有证据的情况下声称“应该能修复”——请验证修复确实解决了追踪到的根因

⚠️ 强制要求：置信度与证据门槛

强制重要要求，务必注意： 对每一项声明，都要注明 Confidence: X%，并附上证据列表和 file:line 证明。 95% 以上：可自由推荐｜80–94%：注明保留意见｜60–79%：列出未知项｜低于 60%：停止——收集更多证据。

规则

• 修复所有类型错误，并重复此过程，直到不再有类型错误。

• 为每个值指定其真实、具体的类型（或指定为 unknown 并添加类型收窄保护）——不要只为通过类型检查而使用 any。——原因：any 会屏蔽检查器，让底层类型缺陷随代码一起发布

• 修复后，务必注意运行 $prove-fix——为每项更改构建代码证明轨迹并提供置信度评分。绝不跳过。

---

[IMPORTANT] 开始前，使用任务跟踪将所有工作拆分为小任务——包括为每个文件的读取单独创建任务。这可以避免因文件过长而丢失上下文。对于简单任务，AI 务必注意询问用户是否跳过此步骤。

• docs/project-reference/domain-entities-reference.md — 领域实体目录、关系、跨服务同步（任务涉及业务实体／模型时阅读）（相关时直接阅读；不要依赖钩子注入的对话文本）

技能变体： $fix 的变体——TypeScript／类型错误修复。

从结果到起点的调试追踪——对于非简单的 Bug、验证失败、回归修复、会改变行为的代码或不清晰的代码流程，先从观察到的最终状态开始，再逆向追踪，然后再提出修复方案。

1. 第 0 帧：观察到的最终状态——指出确切的用户可见输出、失败断言、日志行、持久化值、API 响应、渲染的 UI 或聚合分桶。记录生成该结果的读取器／查询／渲染器，并提供 file:line 证据。
2. 每次向前回溯一跳——按最终读取器 -> 投影／缓存／存储 -> 写入器 -> 消费者／处理程序／作业 -> 生产者／调用方 -> 原始触发顺序追踪。每一跳都记录：输入、转换、输出、所有者和证据。
3. 枚举所有输入路径——找出所有可能写入最终路径的上游生产者／调用方／事件／作业，包括重试、异步、缓存、后台以及其他 UI／API 路径。将每条路径标记为已验证、已排除或仍未知。
4. 构建假设矩阵——为每个合理的原因列出支持证据、反对证据、如何复现／验证、影响范围和状态（primary、contributing、ruled out、latent）。在明确解决或界定其他竞争原因之前，不要修复。
5. 选择负责修复的层——确定不变量的所有者，以及能保护所有下游消费者的最低公共层。除非症状发生处拥有该不变量，否则拒绝在症状发生处修复。
6. 正向证明收敛——选择修复方案后，再次从起点追踪到终点，说明修正后的状态如何到达观察到的最终输出。将每个根本原因对应到一部分修复，再将每部分修复对应到测试／证明。

以下事项完成前不得继续： 明确最终状态 · 写出逆向追踪 · 枚举所有输入路径 · 完成假设矩阵 · 论证负责修复的层 · 将正向收敛证明对应到测试。

绝不： 从第一个可疑代码路径开始。将多个生产者压缩成一条“流程”。未经证明读取模型就把重复症状当成重复记录。跳过已排除的假设。 根因调试——采用系统化方法，绝不靠猜测和试错。

1. 复现——通过证据（错误消息、堆栈跟踪、截图）确认问题确实存在
2. 隔离——通过二分查找 + 图追踪，将范围缩小到具体的文件/函数/行
3. 追踪——从输入开始，沿数据流追踪到故障点。阅读实际代码，不要凭推断。
4. 假设——提出理论并标注置信度百分比。说明有哪些证据支持或反驳该理论
5. 验证——通过有针对性的 grep/read 测试假设。每次只改变一个变量。
6. 修复——解决根因，而非表面症状。通过图 connections 验证修复不会影响调用方

**绝不：**在没有证据时猜测。只修复症状而不解决根因。跳过复现步骤。

嵌套任务展开约定——对于工作流步骤调用，[Workflow] ... 行仅是父容器；子技能仍需创建可见的阶段任务。

1. 先调用当前任务列表。如果存在匹配的活动父工作流行，则设置 nested=true 并记录 parentTaskId；否则独立运行。
2. 在阶段工作开始前，为声明的每个阶段创建一个任务。嵌套时，任务主题前缀为 [N.M] $skill-name — phase。
3. 嵌套时，通过 TaskUpdate(parentTaskId, addBlockedBy: [childIds]) 关联父任务。
4. 编排器必须在调用子技能或子 Agent 之前，预先展开其阶段列表，并关联工作流行。
5. 工作前将且仅将一个子任务标记为 in_progress；证据写入后立即标记为 completed。
6. 仅当所有子任务均已完成或明确说明原因后取消，才能完成父任务。

**在以下条件满足前处于阻塞状态：**已检查当前任务列表、已创建子阶段任务、嵌套时已关联父任务，且第一个子任务已标记为 in_progress。

项目参考文档门槛——在任务跟踪初始化之后、读取目标/源文件、grep、编辑或分析之前运行。项目文档优先于通用框架假设。

1. 确定范围：文件类型、领域和操作。
2. 按触发条件确定必需文档：始终需要 docs/project-reference/lessons.md；文档查找需要 docs-index-reference.md；审查需要 code-review-rules.md；后端/CQRS/API 需要 backend-patterns-reference.md；领域/实体需要 domain-entities-reference.md；前端/UI 需要 frontend-patterns-reference.md；样式/设计需要 scss-styling-guide.md + design-system/design-system-canonical.md；集成测试需要 integration-test-reference.md；E2E 测试需要 e2e-test-reference.md；功能文档/规格需要 feature-docs-reference.md；架构/新领域需要 project-structure-reference.md。
3. 阅读所有存在的必需文档；缺失的文档视为不适用并跳过。不要将对话文本（如 [Injected: <path>]）视为当前上下文中包含该文档的证明。
4. 开始目标工作前，说明：已阅读参考文档：... | 缺失/不适用：...。

**在以下条件满足前处于阻塞状态：**已评估范围、已检查/阅读必需文档、已确认 lessons.md，并已提供引用。

任务跟踪与外部报告持久化——执行前先完成初始化；然后在处理目标/源文件之前，预先读取项目参考文档。

1. 在读取目标文件、grep、编辑或分析之前，创建一份简短的任务分解。上下文丢失时，先检查当前任务列表。
2. 工作前将一个任务标记为 in_progress；证据记录后立即标记为 completed；绝不批量转换状态。
3. 对于计划/审查工作，在发现首条结果之前创建 plans/reports/{skill}-{YYMMDD}-{HHmm}-{slug}.md。
4. 每完成一个文件/章节/决策后追加记录，并在最后根据报告文件综合整理。
5. 最终输出引用 Full report: plans/reports/{filename}。

**在以下条件满足前处于阻塞状态：**已创建任务分解；计划/审查工作已声明报告路径；下一条发现记录之前已持久化首条发现。 批判性思维 — 运用批判性思维和顺序思维。每项主张都必须有可追溯的证据，置信度 >80% 才能采取行动。 反幻觉： 绝不将猜测说成事实——每项主张都要引用来源，坦诚承认不确定性，自查输出中的错误，独立交叉核实，并对自己的信心保持怀疑——缺乏证据的确定性是一切幻觉的根源。

先理解代码 — 严格门槛：在阅读现有代码之前，禁止编写、规划或修复。

1. 搜索 3 个以上相似模式（grep/glob）——引用 file:line 作为证据
2. 阅读目标区域内的现有文件——理解其结构、基类和约定
3. 当 .code-graph/graph.db 存在时，运行 python .claude/scripts/code_graph trace <file> --direction both --json
4. 通过 connections 或 callers_of 梳理依赖关系——了解哪些内容依赖你的目标
5. 对于非简单任务（涉及 3 个以上文件），将调查结果写入 .ai/workspace/analysis/
6. 实施前重新阅读分析文件——绝不要仅凭记忆工作。——原因：长上下文会偏离文件内容；文件才是事实依据
7. 如果现有模式可用，绝不另造新模式——严格遵循现有模式，或记录偏离原因。——原因：模式分歧会割裂代码库，并拖慢今后每一位读者的工作

完成以下各项前不得继续： - [ ] 已阅读目标文件 - [ ] 已搜索 3 个以上模式 - [ ] 已进行图追踪（如果 graph.db 存在） - [ ] 已通过证据核实假设

基于证据的推理 — 禁止猜测。每项主张都必须有证据。

1. 每项主张都要引用 file:line、grep 结果或框架文档
2. 明确说明置信度：>80% 可直接采取行动，60-80% 先核实，<60% 不要提出建议
3. 架构变更必须进行跨服务验证
4. “我没有足够的证据”是合理且预期的输出

完成以下各项前不得继续： - [ ] 证据文件路径（file:line） - [ ] 已执行 grep 搜索 - [ ] 已找到 3 个以上相似模式 - [ ] 已说明置信度

未经证实不得使用： “显然”“我认为”“应该是”“可能是”“这是因为” 如果未完成 → 输出："证据不足。已核实：[...]. 未核实：[...]."

检查源代码与测试是否偏离。 对于编码、修复、调试、调查、测试或审查工作：当源代码行为发生变化时，检查受影响的单元测试、集成测试和端到端测试，并依据证据判断是应修改测试以符合预期行为，还是应将源代码变更视为意外错误并修复。不要为迁移代码编写测试；架构和数据迁移是一次性执行路径，不属于核心应用逻辑。 AI 错误预防——每项任务都要避免的失败模式：

删除前检查下游引用。 删除组件会导致文档和代码过时，并引发连锁问题。移除前，先梳理所有引用该组件的文件。 根据实际代码核验 AI 生成的内容。 AI 会杜撰 API、类名和方法签名。记录或引用前，务必用 grep 确认它们确实存在。 编辑后追踪完整依赖链。 修改定义时，可能会遗漏由其衍生的下游变量和使用方。务必追踪完整链路。 验证正确性时追踪所有代码路径。 确认代码存在，不等于确认代码会执行。务必追踪提前退出、错误分支和条件跳过，不要只检查正常路径。 调试时，修复前先问“这是谁的职责？”。 追踪 bug 是出在调用方（数据错误）还是被调用方（处理错误）。在负有责任的层修复，绝不要只修补症状出现的位置。 假设现有值都是有意设置的——修改前先问为什么。 修改任何常量、限制、标志或模式前：阅读注释、检查 git blame，并查看周边代码。 核验所有受影响的输出，而不只是第一个。 涉及多个技术栈的更改，必须核验每个输出。一个检查通过，不代表所有检查都通过。 整体优先的调试——警惕只关注最近线索的陷阱。 调查任何故障时，先列出所有前置条件（配置、环境变量、数据库名称、端点、DI 注册、数据前置条件），再逐一根据证据核验，然后再提出任何代码层面的假设。 精准修改——应用差异检查。 修复 bug：每一行更改都必须能直接追溯到该 bug。不要顺带调整相邻代码的风格或改进它。增强任务：实施改进，并明确说明。 编码前明确歧义——不要默默做选择。 如果请求有多种解读，逐一列出并估算工作量，然后询问。绝不要擅自假设需要处理所有记录、采用基于文件的方案或采用更复杂的路径。

重要，务必注意：任何修改前，都要搜索至少 3 个现有模式并阅读代码。如果存在 graph.db，则运行图追踪。

重要，务必注意：每项主张都要引用 file:line 证据。置信度 >80% 才可采取行动，<60% 时不得提出建议。

务必注意：运用批判性思维——每项主张都需要可追踪的证据证明，置信度 >80% 才可采取行动。防止幻觉：绝不要把猜测说成事实。

务必注意：遵循 AI 错误预防原则——整体优先调试、在负有责任的层修复、编码前明确歧义、压缩后重新阅读文件。

• 强制要求：开始目标工作前，先初始化任务跟踪；每次只转换一个任务的状态。

• 强制要求：逐步将计划和审查发现保存到 plans/reports/，并根据磁盘上的内容进行汇总。

• 强制要求：完成任务跟踪初始化后、开始目标工作和源码工作前，阅读必需的项目参考文档，并注明 Reference docs read: ...。

• 强制要求：始终包含 lessons.md；项目约定优先于通用默认值。

重要，务必注意：调试器追踪关卡：对于非简单的 bug 修复、故障排查、调查或审查工作，从观察到的最终输出开始，反向追踪 reader → storage/projection → writer → consumer/job → producer/trigger。修复前列出所有供给路径和假设矩阵。在以下内容齐备前，禁止继续：追踪结果、假设矩阵、负责修复的层，以及正向收敛证明。

• 强制要求：父工作流条目不能替代子阶段跟踪；嵌套时要展开各阶段并关联父项。
• 强制要求：编排器必须在调用前预先展开子技能阶段；使用 [N.M] $skill-name — phase 前缀，并遵守同时只能有一个 in_progress 的原则。

结束前提醒

重要，必须注意：开始前使用任务跟踪将工作拆分成较小的待办任务 重要，必须注意：创建新代码前，在代码库中搜索 3 个或更多类似模式 重要，必须注意：为每项声明提供 file:line 证据（置信度 >80% 才采取行动） 重要，必须注意：添加最终审核待办任务，以验证工作质量 重要，必须注意：修复尝试失败 3 次后停止——报告结果，并在第 4 次尝试前询问用户 强制，重要，必须注意：开始前阅读以下文件：

[任务规划] 行动前，分析任务范围，并使用任务跟踪系统地将其拆分成较小的待办任务和子任务。

无钩子提示词协议镜像（自动同步）

来源：.claude/hooks/lib/prompt-injections.cjs + .claude/.ck.json

[工作流执行协议] [阻塞] 工作流执行协议——强制、重要、必须、关键。无论任何原因都不得跳过。

通用可移植性边界： 可复用的技能和协议文本应保持项目中立；项目特定约定应从 docs/project-config.json 和 docs/project-reference/ 中获取。应用共享 AI-SDD，参见 shared/sdd-artifact-contract.md。阅读 docs/project-config.json 和 docs/project-reference/docs-index-reference.md，然后打开其中列出的项目参考文档。只要具备此共享上下文和本地文档，任何受支持的 AI 工具均可执行。

1. 检测： 将提示词与工作流目录进行匹配
2. 分析： 找出最匹配的工作流，并评估自定义步骤组合是否更合适
3. 询问（必需格式）： 使用直接提问，并按以下结构组织，除非用户明确调用了工作流/技能，且本地协议将明确调用视为确认：
   • 问题：“你想启用哪个工作流？”
   • 选项 1：“启用 [最佳匹配工作流]（推荐）”
   • 选项 2：“启用自定义工作流：[步骤 1 → 步骤 2 → …]”（附上一句理由）
4. 启用（确认后）： 标准工作流调用 $workflow-start <workflowId>；手动依次执行自定义步骤
5. 创建任务： 使用任务跟踪为工作流的所有步骤创建任务
6. 执行： 按顺序遵循每个步骤 [批判性思维心态] 运用批判性思维和顺序思维。每项声明都需要可追溯的证据，置信度 >80% 才采取行动。 反幻觉原则： 绝不将猜测当作事实陈述——为每项声明注明来源，坦诚说明不确定性，自查输出错误，独立交叉验证，并对自己的判断保持怀疑——没有证据的确定性是所有幻觉的根源。 AI 注意力原则（首因—近因效应）： 在较长提示词/协议的开头和结尾都放置 3 条最关键的规则，以便在较长上下文窗口中仍能遵守指令。 目标驱动执行： 首先定义成功标准，持续循环直至验证完成；只有可观察的检查全部通过后才能停止。 测试验证意图： 测试必须保护业务规则/不变量，并在受保护的意图被破坏时失败，而不能只复现当前行为。

[LESSON-LEARNED-REMINDER] [BLOCKING] 任务规划与持续改进 — 必须遵守。请勿跳过。

开始前将工作拆分为小任务（任务跟踪）。添加最后一项任务：“分析 AI 错误与经验教训”。

提取经验教训——只分析根本原因，不要只修复症状：

1. 指明失败模式（推理或假设错误），而不是症状——“假设 API 存在，却没有阅读源代码”，而不是“使用了错误的枚举值”。
2. 通用性测试：此失败模式是否适用于 ≥3 种情境或代码库？如果不适用，就再抽象一个层次。
3. 将其写成普遍规则——去掉特定于项目的名称、路径和类。确保规则适用于任何代码库。
4. 合并：多个错误若具有相同的失败模式，则合并为一条经验教训。
5. 复发检查：“如果没有此提醒，这种情况会在未来的会话中再次发生吗？”——不会 → 跳过 $learn。
6. 自动修复检查：“$code-review/$code-simplifier/$security/$lint 能否发现此问题？”——能 → 改进审查技能。
7. 两项检查均通过 → 请用户运行 $learn。 [TASK-PLANNING] [MANDATORY] 执行任何工作流或技能步骤之前，先为所有计划步骤创建或更新任务跟踪，然后在每个步骤开始和完成时保持任务跟踪同步。