用途
该技能用于审查 TypeSpec 仓库的 Pull Request,依据项目自身强制执行的规则检查代码差异,而不是泛泛而谈的风格建议。核心约束是:每条评论必须指向改动代码中的具体问题,并引用使其成为问题的规则或代码(如策略章节、配置文件、指南或相关文件行号);若无法引用,则不应发布该评论。
主要能力
1. 破坏性变更与公开接口
按 Tier 0-3 判断每项改动触及的层级,再判断是否破坏现有 spec 或消费者。新增语法、类型或能力不算破坏;改变已有行为才算。
- Tier 0:语言语法/语义、类型图(Type)、默认 TypeKit、导出的辅助函数与访问器函数。需标记:原本有效的 spec 现在解析不同、失败或产生不同类型图;导出被删除/重命名或签名改变;已有输入运行时结果改变;Type 上字段被删除或改用途。策略允许给 Type 增加必填字段,但会破坏下游构造,应指出。
- Tier 1:AST(Node、SyntaxKind)。追加枚举成员和新增联合变体是允许的(TypeScript 穷尽性报错明确不算破坏)。需标记:枚举成员被插入而非追加导致重新编号、节点种类被删除、已有节点形状改变。
- Tier 2:checker、symbols、@internal / /internals / /experimental 导出、模板声明、stdout/stderr 输出。不算破坏;仅当此处改动静默改变可观察行为时提及。
- Tier 3:formatter 与 emitter 输出。语义等价的输出变化不算破坏。
- Bug 例外:技术上破坏但修复明显非预期行为的不算破坏性变更,但必须明确说明。
若判定为破坏性变更却没有对应 breaking changeset,这是审查中价值最高的发现,应首先提出。
2. Changeset(.chronus)
有效的 changeKind 值恰为:internal、fix、dependencies、feature、deprecation、breaking。其他(feat、docs、patch、minor、major)均无效。kind 必须与事实相符:新能力为 feature,修复为 fix,按第 1 节属破坏性的为 breaking。每个包、每种变更类型各一条;一条 entry 同时捆绑一个包的 feature 和另一个包的 fix 必须拆分。packages 必须准确列出受影响的包。每个有用户可见变更的包都需要 entry;缺失即为发现项。但需注意 .chronus/config.yaml 中的排除项:/.md、测试文件及 packages//test/ 不需要 changeset,因此仅文档或仅测试的改动没有 entry 是合理的。消息质量要求:从用户视角描述变更;仅当面向多领域包的次要领域时使用 [方括号] 领域标签(如 [converter]、[formatter]),不用泛化的 core - 前缀;feature entry 包含简短示例代码块,简单 fix 不需要。
3. 编译器 API 使用
判断改动是否按编译器期望的方式使用 TypeSpec 编译器 API,而不仅是能否通过类型检查。
- 诊断目标决定能否被抑制:以 NoTarget 报告的诊断永远无法被抑制(packages/compiler/src/core/program.ts 中 target === NoTarget 会在 #suppress 查找前提前返回),severity: "error" 的诊断同样永远无法被抑制(抑制会产 suppress-error)。因此用户应能静默的诊断必须是 warning 并携带真实节点/类型目标。任何在真实输入上解析为 NoTarget 的目标都应标记为“实际不可抑制”。
- 选最精确的目标,按顺序回退:问题类型 → 服务命名空间 → program.getGlobalNamespaceType() → 仅对确实全程序性、无节点可指的错误使用 NoTarget。
- 不要假设程序有 service:listServices(program) 返回可能为空的数组,对仅模型或无 service 的程序 [0] 为 undefined。任何可能返回 undefined 的查找同理,需追问该情况下诊断是否仍可达、可抑制。
- severity 变化有控制流后果:error 会通过 program.hasError() 阻止输出;降为 warning 意味着下游在之前从未见过的状态下运行,需确认继续路径安全且符合预期。
- 诊断规范:通过库的 reportDiagnostic/createDiagnostic 及目录条目和稳定 code 报告,绝不为用户错误抛异常;变更后消息文本必须仍与行为一致。
- 优先稳定公开 API:使用导出辅助函数和 TypeKit,而非 checker、symbols 或 AST(Tier 2);使用 resolvePath/joinPaths 而非 node:path;遍历类型时用 isTemplateDeclaration 排除模板声明。
4. 测试
每个新代码路径、分支、诊断和公开 API 都需要在包内 test/** 中就近添加测试;新行为无测试即为发现项。复用包共享 tester(如 packages/http/test/test-host.ts、packages/compiler/test/tester.ts);在新测试文件中内联 createTester(...) 会重复库/导入设置并产生漂移,应指出并指向既有模块。用 @typespec/compiler/testing 的 expectDiagnostics / expectDiagnosticEmpty 断言诊断,而非手写 program.diagnostics.some(...) 之类检查。测试必须驱动真实入口($onEmit、装饰器、emitter 运行),而非重实现逻辑或孤立调用辅助函数。若测试从 src 导入辅助函数,确认该符号确实在那里导出。测试必须有意义:若改动被回滚应当失败;仅冒烟运行或不断言新行为具体内容的测试应标记。除正常路径外还需覆盖错误与诊断路径、空/匿名形式、模板及负向用例,包括第 3 节识别的回退分支。任何削弱既有覆盖的行为(.skip/.only、删除断言、放宽 matcher 以通过改动)都应标记。
5. Emitter 输出稳定性
针对 packages/{openapi3,openapi,json-schema,http,http-server-*}:无法解释的快照变化是首要风险。每个变化的快照都必须是改动的有意且已解释的结果;与特性无关的 spec 出现快照差异意味着现有用户输出改变,应提出。内联与提升、组件命名、声明创建的变化必须对既有命名类型保持行为,仅影响真正的新输入。匿名/空名类型内联,命名类型提升且无键冲突。$ref 与组件键正确性:名称校验相对 ref 生成的顺序调整不得静默丢弃此前报错的校验;若这是有意修复,需说明并有 changeset。Emitter 必须防御性处理新类型图形状(新节点种类、新联合变体),而非崩溃。
使用方式
作为技能使用:对给定 PR 的代码差异逐项对照上述规则审查,每条评论一个议题、锚定问题行,陈述问题、引用规则(策略章节、.chronus/config.yaml、指南)或相关 file:line,并给出具体修复建议,一到两句话,无前言、不复述 diff。不重复其他评论已提出的点。优先关注正确性、兼容性和覆盖度;次要建议仅在可操作且具体时提出。
适用场景
适用于 microsoft/typespec 仓库的 PR 审查,覆盖 pnpm 工作区包(packages/compiler、packages/http、packages/openapi3、packages/json-schema、packages/versioning 等)、语言 emitter 包(packages/http-client-{csharp,java,python})、.chronus/changes/** 及其测试。对语言 emitter 包,第 1 节 tier 策略不适用于其内部 API,其自身规则在 .github/instructions/*.instructions.md 中优先,但第 2、3、4 节仍适用于所有位置。
限制
不评论:生成产物(pnpm-lock.yaml、generator/ 下生成的 Python/C#/Java 代码、tests/generated/、website/src/content/docs/docs/libraries/*/reference/** 下生成的参考文档);prettier(pnpm format)与 oxlint 负责的格式化和 lint 问题;命名/风格偏好;改动之外的未变代码。需参考并引用:breaking-change-policy.mdx、.chronus/config.yaml、.github/copilot-instructions.md、被触及包中的同类测试,以及 @typespec/compiler 和 @typespec/compiler/testing 的公开 API。