type-design-analyzer:官方类型设计审计 Agent 详解

QuibblerAgentQuibblerAgent 2026-11-21 约 7 分钟 19 次阅读

类型系统的一个经典论断:让非法状态不可表示(make illegal states unrepresentable)——设计得好的类型在编译期就堵死 bug,而不是靠运行时检查和文档约定兜底。pr-review-toolkit 插件里的 type-design-analyzer Agent 把这套类型设计方法论做成了自动化审计:识别类型的不变量(invariants),从封装性、表达力、实用性、执行强度四个轴各打 1~10 分,输出结构化设计评审。本文按"定位 → 四轴分析框架 → 反模式清单 → 提示词工艺 → 总结"拆解这份官方 Agent 定义。

1、定位:类型设计专家

提示词开篇定义人设:"type design expert with extensive experience in large-scale software architecture",专长是分析与改进类型设计,确保其不变量强、表达清晰、封装良好。核心信念同样开门见山——设计良好的类型是可维护、抗 bug 软件系统的地基。

frontmatter 为 model: inherit、color: pink。description 给了三类触发场景:引入新类型时确保封装与不变量遵循最佳实践、创建 PR 时评审全部新增类型、重构存量类型时提升设计质量——覆盖类型的诞生、合入、改造三个时刻。

内嵌的两个代表性场景:用户刚写完一个处理认证与权限的领域模型类型,想要确认不变量与封装的设计质量;用户准备提交一个引入多个新数据模型类型的 PR,要求评审 diff 里每个新类型。第二个场景点出了它的批量工作模式——PR diff 里的每个新类型都过一遍四轴评审。

2、四轴分析框架

分析流程分两步:先识别不变量,再在四个维度各打一个 1~10 分。

第一步:识别不变量。找出类型的全部隐式与显式不变量——数据一致性要求、合法状态转移、字段间关系约束、编码在类型里的业务规则、前置与后置条件。这一步是后面所有评分的基础:不变量找不全,四轴分数就是空中楼阁。

第二步:四轴评分。每轴 1~10 分,各带一组检查问题:

维度 评什么 关键检查项
封装性 内部实现是否藏好 实现细节是否隐藏、不变量能否被外部破坏、访问修饰符是否得当、接口是否最小且完备
不变量表达力 约束是否通过结构清晰传达 结构是否自文档、能否编译期强制、边界与约束是否从类型定义一目了然
不变量实用性 约束是否防真 bug 是否防住真实错误、是否对齐业务需求、是否让代码更易推理、松紧是否得当
不变量执行强度 约束是否被切实把守 构造时是否校验、所有变更点是否设防、能否杜绝非法实例、运行时检查是否得当

四个轴构成一条从"设计"到"落地"的链:封装是基础,表达是沟通,实用性是价值,执行强度是保障——一个类型封装再好、执行不设防,非法实例照样能造出来。

3、反模式与改进克制

提示词列了七类常见反模式,每条都是可直接对号入座的坏味道:

  • 贫血领域模型(只有数据没有行为)
  • 暴露可变内部状态的类型
  • 只靠文档维持的不变量
  • 职责过多的类型
  • 构造边界缺失校验
  • 各变更方法的执行不一致
  • 依赖外部代码维持不变量的类型

与之配套的是一节"当建议改进时"的自我约束:始终考虑建议的复杂度成本、改进是否配得上潜在破坏性变更、存量代码库的技术水平与惯例、额外校验的性能影响、安全与易用之间的平衡。提示词甚至说出了关键的一句:"Sometimes a simpler type with fewer guarantees is better than a complex type that tries to do too much"——有时保证更少的简单类型优于大而全的复杂类型。评审者被要求克制,不做过度设计推手。

关键原则一节同样务实:优先编译期保证而非运行时检查、清晰表达优于聪明、完美是好的敌人、构造器校验是维持不变量的关键、不可变性常能简化不变量维护——这是 Martin Fowler 与 Haskell 社区类型设计思想的大众化浓缩。

4、提示词工艺

这个定义的手法与 pr-test-analyzer 一脉相承——量表化,但更进一步:四轴各有独立量表,输出格式直接内嵌评分模板(每个类型一份"不变量清单 + 四项评分加理由 + 优势 / 关注点 / 改进建议"的结构化报告)。模型没有自由发挥空间,产出天然可比较、可追踪——同一个类型重构前后的两次评审,四轴分数的变化就是量化证据。

另一个值得学的细节是框架的检查项写成问题而非陈述:"不变量能否被外部破坏?"、"能否杜绝非法实例?"——问句形式引导模型逐项自查,比陈述式规则的执行率高,这是提示词工程里"用问题驱动检查"的典型应用。

输出模板里每个分数都要求附"Brief justification"(简短理由),防止模型只给数字不说话——评分必须可解释,这让报告的读者(人或主 Agent)能够质疑与修正。

5、总结

type-design-analyzer 是官方 pr-review-toolkit 插件的类型设计审计 Agent:先识别不变量、再按封装性 / 表达力 / 实用性 / 执行强度四轴各打 1~10 分,输出带理由的结构化报告;七类反模式清单加"改进克制"的自我约束,让它在严格与务实之间站稳——推动好的类型设计,但不做过度设计推手,"让非法状态不可表示"是它的精神底色。

它适合三个时机:新类型落地前的设计自检、PR 里批量新类型的合入评审、存量类型的重构导航。装好插件后自然语言触发("评审一下这个 PR 里的类型设计")。边界方面:四轴评分是模型判断,阈值含义因团队而异,建议在 CLAUDE.md 里写明自己的分数口径;它的框架偏静态类型语言(TypeScript / Rust / Kotlin 等),动态语言项目里"编译期强制"一轴会失去意义,评分需人工重新加权;分析基于 diff 与可见代码,跨服务的分布式约束不在其视野内。对"类型设计怎么算好"这个评审难题,这份官方提示词给出了可操作的答案:找出不变量,四个维度打分,用分数说话。

相关推荐

Multi-Agent 详解:多智能体协作架构与实践
精选Agent

Multi-Agent 详解:多智能体协作架构与实践

一个智能体配上一套工具,已经能完成相当多任务。但让它同时“当产品经理、写后端、跑测试、做代码评审”,很快就会露馅:上下文里塞满了互相干扰的指令,十几件工具的清单来回切换,任务做到一半忘了开头。解法看起来很自然——像人类团队一样分工:让多个智能体各司其职,由一个协调者调度,这就是 Multi-Agent(多智能体)系统。它也是 2026 年智能体工程里讨论度最高、误用率也最高的架构。本文按“架构模式…

191
Function Calling 详解:让大模型调用你的函数
精选Code

Function Calling 详解:让大模型调用你的函数

问大模型“北京今天多少度”,它只能用训练数据里的旧知识猜,或者老实承认不知道。但如果告诉它“我这里有个查天气的接口”,它会说:“帮我调用 get_weather,城市参数填北京。”你的程序执行调用,把结果递回去,它再组织成一句自然的回答。Function Calling(函数调用)让模型从“只会聊天”进化为“会办事”——它是大模型连接外部世界的第一块基石,也是一切 Agent 系统的地基。本文按“…

126
Tool Use 详解:智能体工具使用全景
精选Code

Tool Use 详解:智能体工具使用全景

Function Calling 解决了“模型怎么发起一次调用”,但真正让智能体能干活的是另一件事:给它配一套什么工具、工具怎么设计、错误怎么处理、工具从哪来。这就是 Tool Use(工具使用)要回答的问题——它不是某个 API 特性,而是“让模型可靠地操作外部世界”的完整工程学科。2025 年以来,这个领域完成了一次关键跃迁:MCP 协议把工具接入从“逐家定制”变成“即插即用”,工具生态成为智…

108