用途:为 dotnet/runtime 起草新的 API 提案,或把模糊的 API 想法、未完善的 api-suggestion 议题整理成完整提案。核心理念是“先原型、后提案”:没有可运行原型的提案被视为推测性设计,缺乏可验证性。
主要能力与流程(6 个阶段,可按需单独运行):
- 收集输入与评估上下文:接受议题 URL、文本描述、API 草图或模糊想法;识别缺失章节、目标命名空间与库、判断设计新颖度;调研当前已有的变通做法并与用户确认是否值得推进;搜索同类提案与历史评审反馈。
- 研究:阅读框架设计指南摘要与更新 ref source 的文档,核对命名与既有 API 的一致性,检索仓库内及公开代码中的使用情况与版本可用性。
- 原型:在 api-proposal/<short-name> 分支上以单个提交实现 API 表面,包含 XML 文档与 #if 目标框架守卫,编写覆盖边界条件的测试,并系统检索仓库内的可采用位置,按已更新、候选、不适用分类。
- 评审(阻塞环节):对原型 diff 进行代码评审,修复所有错误与警告后重新测试。
- 撰写提案:结构包括背景与动机、API 提案(自 GenerateReferenceAssemblySource 提取的精确公开 API)、API 用法示例、替代设计、风险、在 dotnet/runtime 中的使用情况。要求简洁,主张须有具体场景支撑,示例必须可编译。
- 发布后处理:发布后改用第 6 阶段方式更新,避免强推导致提案引用的提交 URL 失效。
必要命令:cd src/libraries/<LibraryName>/src 后执行 dotnet msbuild /t:GenerateReferenceAssemblySource;System.Runtime 使用 dotnet build --no-incremental /t:GenerateReferenceAssemblySource。原型须先完成基线构建。
已知陷阱:冗长动机、编造使用场景、直接粘贴原始 ref 输出、示例不可编译、风险章节过度展开、为凑内容编造设计决策。
限制与未提供信息:资料未说明该技能的安装方式、收费情况、适用平台及支持的模型;部分内容在原文中被截断(如风险章节末尾)。