开放平台的开发者手册全新版本已经上线啦！新版文档包括：快速开始、API 参考、事件订阅和 Web Widget 使用指南。
新版文档如有什么问题，欢迎大家在本社区开放平台板块——“开发者手册”标签中发布话题，期待您的宝贵意见，也期待与您多多交流~
更新内容如下：
一、 结构重组：场景驱动和任务导向 
新增《快速开始》：以一个完整的“生产单同步至飞书”业务场景为主线，串联所有概念和操作，从“我要用什么功能”转变为“我要实现什么业务”，极大降低了学习成本和上手难度，提供了端到端的指引。
内容组织： 内容围绕“场景流程 → 配置管理 → 技术细节 → 调试排错”的逻辑展开，环环相扣。 逻辑更清晰，更像一本“教程”而非“词典”，阅读和学习体验更流畅。
Web Widget使用说明优化：拥有完整的概述、Quickstart、架构、开发指南和部署流程。明确了Web Widget作为一种重要集成方式（前端插件）的独立地位，内容深度和广度大幅提升。
二、 内容深度与广度的显著增强 
| 领域 | 更新点描述 | 重要性 |
|---|---|---|
| API 调用 | 1. 明确区分两种Token：清晰阐述了标准Access Token（推荐）和永久Access Token（高风险，慎用）的区别、优缺点和适用场景。 2. 新增IP白名单功能：增强了API调用的安全性。 3. 详尽的频控策略：明确了日调用总量和分钟级并发限制的具体数值和规则。 |
强调了安全最佳实践，提供了更精细的控制能力和更明确的限流规则，帮助开发者规划更合理的调用策略，避免触发限制。 |
| 事件订阅 | 1. 详解消息体结构：清晰说明了通用消息头(headers)和消息体(payload)的规范和示例。2. 高级推送配置：新增自定义请求头、推送超时与重试策略、异步更新日志状态机制。 3. Coze平台集成指南：提供了将事件推送到飞书Coze工作流的具体配置步骤，拓展了生态集成能力。 |
使开发者能更精准地解析和处理事件，提供了更灵活、鲁棒的集成方案，满足了更复杂的业务场景需求。 |
| Web Widget | 完全重写。旧版仅为脚手架说明，新版提供了： 1. 应用场景示例：生动说明其价值（如在列表页无缝创建生产单）。 2. 核心架构详解：包括项目结构、SDK( @newcore/client)的角色和工作原理图。3. 详细开发指南：包含 manifest.json配置、组件代码逻辑（含大量代码示例）、国际化(i18n)、样式指南等。4. 完整的部署流程：从构建到上传应用的详细步骤和截图。 |
使 Web Widget 变成一个可具体落地开发的功能。提供了从零开始开发、调试到上线的完整指导，实用性极强。 |
三、 开发者体验与可用性的大幅提升 
| 方面 | 更新点描述 | benefit |
|---|---|---|
| 可视化 | 新增大量图表和截图：包括业务流程图、技术架构图、配置界面截图、效果预览图等。 | 一目了然，减少了纯文字描述的理解成本，让用户能快速确认操作界面和预期效果。 |
| 代码与示例 | 提供了极其丰富的代码示例，如事件消息体、API请求/响应、Web Widget组件代码（包括Token管理、API调用、UI渲染等）。 | 开发者可以“开箱即用”或直接参考，极大地减少了摸索时间，提高了开发效率。 |
| 调试与排错 | 新增“查看事件订阅日志”和“API调用日志”章节，并详细说明了日志重发(Resend)和强制成功(Force Success)等操作。 |
提供了强大的问题定位和补救工具，降低了运维难度。 |
如果您是从旧版迁移过来的开发者，建议您重点阅读《快速开始》以理解新思路，然后根据您的集成方式（API调用、事件订阅或 Web Widget 开发）深入阅读相应的专题文档。