R1.12.1in-context usage guidance设计
准则写在使用现场比写在文档站点更可能被读到
别名: 使用现场文档 · 就地提示 · docs at point of use · in-editor docs
概念解释
使用现场的准则（in-context usage guidance）贴在调用点旁边：编辑器悬停、补全列表、检查器、画布旁的属性面板。文档站点是另一座房子，要另开标签、另搜组件名、另对版本。写在现场更可能被读到，不是因为句子写得更好，而是到达成本叠在正在写代码或改设计的那条任务里，不必切换任务。站点上的同一段话，要等有人想起「该去查一下」才会被打开。
现场不是把站点全文塞进工具提示。它是在手还放在调用点上时，能看见的那几句：这个属性现在不该开、这个组合会坏、去哪找可运行的例子。长文仍可放站点；现场负责把人留在原任务里读完关键句。
机制
人在调用点上的工作记忆已经被接口形状占满。再要求打开站点，等于插入一个新任务：找对组件、找对版本、找对段落，然后把读到的内容搬回编辑器。每一步都可能被打断，于是「稍后去看」变成「再也不看」。悬停和补全与光标同屏，阅读发生在决策尚未提交之前，误用还没写成代码。
站点还有版本漂移：书签指向的页面可能新于或旧于当前安装的包。现场文档若从同一份源生成并跟包走，光标旁看到的就是这个版本的准则。读到率由「还要走多远」决定，不由文档写了多少页决定。
边界
现场容纳不了需要对照多组件才能讲清的决策（整页信息架构、跨组件的责任划分），那些仍要离开调用点去看长文。纯视觉探索、还没有代码光标的阶段，设计工具里的检查器才是现场，编辑器悬停帮不上。离线或无语言服务的环境里，现场通道不存在，站点是唯一来源。把整章粘进工具提示会把现场变成第二座站点，到达成本以滚动的形式回来。
怎么落地
- 把调用时必须立刻知道的句子（属性含义、互斥、危险组合）写进类型旁注、补全详情和检查器，与组件同一源发布。
- 站点长文只保留现场放不下的对照和背景，并在现场放一条「打开这个版本的长文」链接，禁止只丢一个不带版本的门户地址。
- 度量现场通道的到达：补全详情是否出现、悬停是否命中当前符号，而不是只看站点浏览量。
- 验证：请一位没用过该组件的人完成一次真实调用，期间禁止打开文档站点。若他能仅靠悬停和补全避开一处已知误用，现场在工作；若他必须去搜站点才能知道那个属性不该和另一个一起开，关键句就不在现场。再对比同一句在站点与悬停的版本号：不一致即现场已断。