让编码智能体首次就能无人值守集成你的 SDK/API…

当用户抱怨编码智能体凭空编造不存在的 API、问文档是否 AI-ready、或想写 llms.txt 时，用冷启动实测 + 机器可读入口 + 页面/规范改写来提升智能体首次集成成功率。

适用场景

解决思路

1. 先做访问验证：用你关心的各智能体 user-agent 字符串去抓取一个页面和索引，记录状态码（若无法发请求就让文档负责人代跑）。CDN 默认拦截 AI 爬虫会让后续所有步骤静默失败。
2. 跑一次基线冷启动：用全新、无先验知识的智能体，来源限定为已发布表面，任务集冻结，每个任务跑一次，记录每一次纠正轮次。
3. 盘点智能体已能触达的表面：索引文件、页面的 markdown 版本、机器可读规范、带版本的入口、SDK 文档注释、终端/包管理器路径；逐个标记为存在/部分/缺失。
4. 按任务影响决定哪些进入发现清单，再按「每小时投入的回报」排序。没有冷启动失败的任务即使好修也不进清单；能破坏最高营收任务的页面优先于十个外观修复。
5. 重写失败运行实际触及的页面，套用页面规则（见下）。
6. 在规范中标注：当某个被编造的参数或错误调用可追溯到规范字段时，就地补注。
7. 发布缺失的入口，并在 README、文档导航和响应头三处宣传。只发布不宣传等于没做。
8. 用完全相同的任务集重跑并对比，迭代直到满足退出标准。
9. 若环境有持久记忆，保存任务集、表面盘点和上次得分，使下次运行对比同一基线。
10. 表面建设优先级（爬虫访问是门槛，不在菜单内，需单独决策）：按投入从低到高为 索引文件 == 全语料包 > 版本标签 > markdown 端点 > 标注过的规范文件 > SDK 文档注释 == 终端与包路径；按价值从高到低为 标注过的规范文件 > markdown 端点 > 版本标签 > SDK 文档注释 > 终端与包路径 > 索引文件 > 全语料包；按效率先做为 markdown 端点 > 标注过的规范文件 > 版本标签 > 索引文件 > SDK 文档注释 == 终端与包路径。默认从 markdown 端点和标注规范入手；当冷启动失败从「编造调用」转为「版本不匹配」时下移到版本标签；当产品有类型化 SDK 且冷启动显示智能体在读本地代码时，把 SDK 文档注释提到最前；当语料放不进上下文预算时直接删掉全语料包而不是排到最后。
11. 退出标准（全部满足才收工）：首次任务成功率无人值守达到约定目标（80% 是拉伸目标而非底线，按冷启动协议校准）；三个最高流量任务上零编造 API 表面；常规任务抓取文档不超过三份；每任务纠正轮次低于上一轮。只修文档，绝不修提示词——只有手调提示词才能通过的任务不算通过。
12. 页面规则（对每个失败运行触及的页面执行，按冷启动中出现的频率排序）：让每页自包含，重述前置条件而非回指前文；在代码片段内固定包名与版本范围，而非放在远处的安装页；用等价命令或 API 调用替代 UI 点击路径，点击路径保留为人类备选；给出完整片段：import、客户端构造、调用、await 结果、错误分支；说明片段返回或打印什么，让智能体能验证而非假设；把示意性片段明确标注为不可运行；全语料每个概念只用一个名称、一套占位符约定；把产品输出的每个错误字符串映射到原因与修复，使用到达 stderr 的原文；在页面内以机器可读方式写明所描述的版本，弃用表面在顶部标注并给出替代；把可用的调用放在前面，解释放后面。
13. 规范规则（按「每小时避免的错误调用」排序，编辑前先读规范标注规则）：1) 给每个操作一个稳定的动宾式 operationId，近乎零成本且生成器据此派生工具名；2) 收窄取值空间，优先用枚举、显式 required、default、format 关键字、带 discriminator 的 oneOf，而非自由字符串；3) 若计划转成工具，先裁剪规范：一轮开始时可用函数少于 20 个，超出则按标签或厂商扩展过滤；4) 拆分 summary 与 description：summary 一行祈使句用于选调用，description 写前置条件、副作用、幂等性、鉴权范围、速率限制及更合适的兄弟操作指引；5) 给操作本身附上各语言可运行示例，让契约与调用一次抓取到位；对冷启动反复失败的两三个操作，把示例提到第一位。注意：AsyncAPI 与裸 JSON Schema 的指导是从 OpenAPI 情形推断的，非单独取证，应用时要说明。
14. 按归属形态调整计划：维护者主导的开源项目——你控制仓库文件而非响应头或文档 CDN，优先仓库根产物、生成的规范文件、SDK 源码文档注释、随发布提交的带版本索引，并把页面规则写进贡献指南；有文档平台的商业厂商——你控制构建输出、响应头、重定向和爬虫策略，优先访问检查、markdown 端点、由文档构建生成的索引；两者共用同一套冷启动协议、任务集和页面规则，不要按归属模型重新推导。
15. 交付一份审计报告而非一堆页面编辑：1) 任务集与基线得分，记录模型与日期；2) 访问检查：哪些 user-agent 能抓哪些表面及状态码；3) 表面盘点表：表面、状态、投入、解锁什么；4) 发现项，按任务影响准入、按每小时修复量排序，每条写明失败任务、页面或规范字段、智能体实际做了什么；5) 修复计划分「本周上线」与「需要构建变更」，写明问题 8-10 的哪个回答移动了哪一项、哪些表面被直接删除；6) 重跑得分对比基线，以及仍失败什么、为什么。

适用边界 · 注意事项

• 不适用于让 AI 搜索引擎引用你（那是可见性问题，指标不同）。
• 不适用于项目自身面向贡献者的智能体指令（构建/测试/lint 约定，另有规范和工具）。
• 不适用于构建可调用的工具表面（工具服务器、函数调用 API），那是产品工作；仅「转换前裁剪规范」在范围内。