用途
该技能用于 TypeScript 库的 API 设计与开发者体验(DX)评估。它适用于设计 API、评审架构、评估 DX 或检查人体工学等场景,帮助开发者构建“直观、快速、安全、可组合”的库接口,并兼顾良好的默认值与逃生舱。
主要能力
技能围绕若干设计原则组织:
- 基础理念:涌现式扩展性(最佳扩展点看起来像设计良好的 API,而非插件系统)、组合优于配置(devtools(persist(fn)) 优于 { middlewares: [] })、洋葱模型(转换型中间件在最内层,观察型在最外层)。
- API 表面:3 个及以上参数使用配置对象(不用重载);独立值用扁平返回,内聚单元用命名空间返回;二法则(2 个值用元组,3 个及以上用对象);推断优于标注(若用户需要标注,说明类型没有正确流动)。
- 渐进式披露:复杂度随用例增长——零配置 → Options → 组合 → Headless → Core;逃生舱可组合,不要求重新实现默认值;显式契约,用 render props 而非隐式要求。
- 开发者体验:首次成功时间(缩短从安装到可用代码的时间)、认知负荷(更少概念优于更少按键)、可预测结果(匹配用户心智模型)、编辑器人体工学(TypeScript 推断应自然可用)。
- 冲突解决:当原则冲突时,优先级为正确性、类型安全、简洁性、一致性、包体积。
技能还列出常见反模式及其失败原因,包括函数重载、运行时插件注册、位置参数(3 个及以上)、隐式契约、按模块中间件、散弹式解析、布尔陷阱、多套竞争 API 等。
使用方式
技能提供按领域加载参考文件的指引:
- 通用 API 工作:principles.md
- TypeScript/类型:typescript.md
- 状态管理:state.md
- 中间件/插件:extensibility.md
- 避免错误:anti-patterns.md
- 库比较:libraries.md、voices.md
评审 API 与架构时,加载 review/workflow.md,其中包含评审流程与清单;此外还有 review/agents.md(子代理提示)、review/templates.md(问题格式、报告模板)、review/checklist.md(单代理快速清单)、review/example.md(完整评审示例)。
参考文件还包括 references/principles.md(核心设计与 DX 原则)、references/typescript.md(作者与消费者的类型推断模式)、references/state.md(状态管理模式与架构)、references/extensibility.md(管道、构建器、适配器、生命周期)、references/anti-patterns.md(常见错误)、references/libraries.md(参考库及其模式)、references/voices.md(实践者启发式与参考 URL)。
相关技能:构建 UI 组件用 component 技能,无障碍模式用 aria 技能,文档用 docs 技能。
适用场景
适用于设计或评审 TypeScript 库的公共 API、评估开发者体验、检查 API 人体工学、规划扩展机制(中间件、插件、管道)、以及需要统一团队 API 设计规范时。
限制
资料未提供该技能的具体安装命令、运行环境要求、收费或价格信息、支持平台及实际效果数据,这些内容暂未提供。