typescript-skills

TypeScript 规则路由器

核心原则。 打开一个主题，而不是九个。使用这项技能的代价，就是它让你阅读的内容。

• 这是此软件包中唯一可发现的技能。 其下所有内容都是参考资料。
• 内部的 INDEX.md 不是技能。 切勿调用主题名称。请阅读该主题对应的确切路径。
• skill:// 是此软件包的参考记法，不是协议。如果某个执行环境无法识别它，请将其转换为等效的文件路径，并直接阅读目标文件。
• 你是在进行中的工作里打开了此内容。 这些说明是为了帮助你完成该工作，不是用来替代它。开始前先说明你原本在做什么，完成后再回到原来的工作。

首先打开一个主题

将任务与左栏匹配，并打开对应的索引。

• 报告的 lint 或编译器诊断应从其他位置着手。 首先阅读 skill://typescript-skills/references/diagnostics-to-rules.md，然后阅读其中指出的规则。

• 只有当任务确实跨越边界时，才添加第二个主题。

• 不要默认加载所有主题。 这个路由器正是为了避免这种浪费。

• 阅读每一行，然后按匹配项采取行动，优先处理最难撤销的操作。 阅读一行不会造成代价；遗漏的那一行，正是覆盖不全之处。 | 如果任务涉及…… | 请阅读此主题索引 | | --- | --- | | 可能缺失的值，或用于守护该值的 ?. 和 ?? | skill://typescript-skills/typescript-coding-standards/INDEX.md | | 代替类型的 any、unknown 或类型断言 | skill://typescript-skills/typescript-coding-standards/INDEX.md | | 对联合类型使用 switch，却没有穷尽性检查 | skill://typescript-skills/typescript-coding-standards/INDEX.md | | 在第二个调用方出现前就添加抽象、类或泛型 | skill://typescript-skills/typescript-coding-standards/INDEX.md | | 有人想拆分的长函数，或函数内部混杂不同抽象层级 | skill://typescript-skills/typescript-coding-standards/INDEX.md | | 无法确定的名称，无论是类、错误还是字段的名称 | skill://typescript-skills/typescript-coding-standards/INDEX.md | | 新旧结构及其切换逻辑并存 | skill://typescript-skills/typescript-coding-standards/INDEX.md | | SDK、提供方或生成的类型渗透到业务逻辑中 | skill://typescript-skills/typescript-boundaries/INDEX.md | | 将 API 请求或响应结构用作领域类型 | skill://typescript-skills/typescript-boundaries/INDEX.md | | 它们之间存在映射器、转换器或翻译器 | skill://typescript-skills/typescript-boundaries/INDEX.md | | 在使用依赖的位置构造依赖，而不是将其传入 | skill://typescript-skills/typescript-composition/INDEX.md | | 在运行时选取工厂或单例，或生命周期无人管理 | skill://typescript-skills/typescript-composition/INDEX.md | | 在启动流程之外读取 process.env | skill://typescript-skills/typescript-configs/INDEX.md | | 配置值未经类型检查就被解析、设置默认值或暴露 | skill://typescript-skills/typescript-configs/INDEX.md | | 每个进程都会加载一个配置对象，但只有其中一个进程需要该值 | skill://typescript-skills/typescript-configs/INDEX.md | | 功能标志或正在进行的配置迁移 | skill://typescript-skills/typescript-configs/INDEX.md | | 执行分支时没有留下日志或跟踪信息 | skill://typescript-skills/typescript-observability/INDEX.md | | 日志只说明发生了什么，却没说明该如何处理 | skill://typescript-skills/typescript-observability/INDEX.md | | 在字面量、日志或配置默认值中出现密钥、凭据或令牌 | skill://typescript-skills/typescript-security/INDEX.md | | 日志或调试信息打印了标头、负载或完整请求 | skill://typescript-skills/typescript-security/INDEX.md | | 值已写入后才进行脱敏，或凭经验随意选择加密方式 | skill://typescript-skills/typescript-security/INDEX.md | | 测试断言的是模拟调用，而不是行为 | skill://typescript-skills/typescript-testing/INDEX.md | | 边界契约没有测试覆盖 | skill://typescript-skills/typescript-testing/INDEX.md | | 覆盖率数字或门槛发生变化 | skill://typescript-skills/typescript-testing/INDEX.md | | 重构开始前没有特征测试 | skill://typescript-skills/typescript-testing/INDEX.md | | 本应使用结果类型却用了 throw，或反之 | skill://typescript-skills/typescript-error-handling/INDEX.md | | 错误跨越边界时未说明是否可重试 | skill://typescript-skills/typescript-error-handling/INDEX.md | | catch 吞掉了错误原因 | skill://typescript-skills/typescript-error-handling/INDEX.md | | Promise.all、顺序执行的 await，或未等待的 Promise | skill://typescript-skills/typescript-async/INDEX.md | | 在 finally 或 using 中执行清理，或响应发出后仍有工作在运行 | skill://typescript-skills/typescript-async/INDEX.md | | AbortSignal 清理、重试与退避，或 SIGTERM 关闭流程 | skill://typescript-skills/typescript-async/INDEX.md |

默认立场。

• 一次只打开一个主题，最多九个。 只有任务跨越了实际边界时，才打开第二个。
• 遵循仓库已有的约定，除非某条规则旨在保护更强的不变量。
• 只有确有需要时才添加结构，并由主题自身的规则说明何时添加。

决胜规则

只有真正存在歧义的情况才适用此处。 其他情况都按上文处理。

情况	首选	次选
提供方响应的形状进入业务逻辑	skill://typescript-skills/typescript-boundaries/INDEX.md	编码规范，用于命名
在启动时选择提供方	skill://typescript-skills/typescript-composition/INDEX.md	若提供方形状跨越边界向内传递，则参考边界主题
配置中出现机密来源指针	skill://typescript-skills/typescript-security/INDEX.md	配置主题，用于解析和暴露
将开发环境值用作代码默认值	skill://typescript-skills/typescript-security/INDEX.md	仅在涉及非机密行为默认值时参考配置主题
对已解析或未知数据应用类型断言	skill://typescript-skills/typescript-coding-standards/INDEX.md	解析器形状参考配置主题，传输数据参考边界主题
宽泛的配置对象进入功能模块	skill://typescript-skills/typescript-configs/INDEX.md	若涉及框架组装，则参考组合主题
阶段比较用于选择资源	skill://typescript-skills/typescript-configs/rules/feature-decisions.md	skill://typescript-skills/typescript-configs/rules/validation-vs-verification.md
日志或跟踪属性可能包含机密	skill://typescript-skills/typescript-security/INDEX.md	诊断数据形状参考可观测性主题
行为变更前先进行重构	skill://typescript-skills/typescript-testing/INDEX.md	相关设计主题
重试循环也会重试调用方错误	skill://typescript-skills/typescript-error-handling/rules/error-classification.md	重试机制参考 skill://typescript-skills/typescript-async/rules/retry-and-backoff.md
处理程序向客户端返回 SDK 错误形状	skill://typescript-skills/typescript-error-handling/rules/error-boundary-contract.md	入站映射参考边界主题
catch 返回备用结果但没有任何信号	skill://typescript-skills/typescript-error-handling/rules/error-boundary-contract.md	信号形状参考可观测性主题

路由约定

• 所选主题索引负责其领域内的路由。
• 规范规则文件负责设计决策。
• 具名诊断通过 skill://typescript-skills/references/diagnostics-to-rules.md 路由。
• 关于编写约定，请阅读 skill://typescript-skills/references/authoring-checklist.md。
• 尚未解决的事项位于仓库根目录下的 docs/typescript-skills/。