scalar/agent-chat 发布说明深度解读Agent 工作区的 AsyncAPI 支持、平台认证与前端打包优化【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar本指南以 Scalar 开源仓库中 packages/agent-chat/RELEASE_NOTES.md 为脉络逐条解读scalar/agent-chat组件的关键版本演进从 Agent 工作区原生支持 AsyncAPI 文档到文档加载携带平台令牌、聊天 UI 首屏 CSS 瘦身再到 credits 计费文案的优化。读者读完将理解这些发布条目的技术背景、底层实现依据以及如何在本仓库中对应源码中验证每一项改动。阅读这份发布说明的正确姿势RELEASE_NOTES.md并非手写文档其头部注释明确说明它由tooling/scripts中的release-notes-generator命令在每次发布时自动生成最新条目位于顶部真正的数据源是同目录下的 packages/agent-chat/RELEASE_NOTES.json需要结构化数据的消费者应直接导入 JSON而 Markdown 是面向人阅读的派生视图直接编辑会被下一次发布覆盖。对比两个文件可以看到一一对应的数据模型RELEASE_NOTES.json中的每个条目包含version版本号、date发布日期、title标题和content段落或链接数组Markdown 中每个## 版本号 (日期)小节正是该结构的渲染结果。因此在仓库中做版本追溯时JSON 是权威数据源Markdown 是速览视图而完整、逐 PR 的细节记录在 packages/agent-chat/CHANGELOG.md 中——本文后续对每个版本条目的“展开解读”部分均取自该文件。0.12.0Agent 工作区原生支持 AsyncAPI 文档发布说明原文指出The Agent chat UI now understands workspace documents that can be either OpenAPI or AsyncAPI, so mixed API descriptions load through the same flow.Agent 聊天 UI 现在可以识别工作区中 OpenAPI 或 AsyncAPI 两种文档混合的 API 描述可通过同一条流程加载。这是发布说明中技术含量最高的一条对应 CHANGELOG 中的两个 PR#9211将WorkspaceDocument改为OpenApiDocument与AsyncApiDocument的联合类型union使工作区文档模型从只认识 OpenAPI升级为同时认识两种 API 描述规范#9211附带的重构移除 zod 依赖改用仓库自研的验证库。从仓库结构看scalar/agent-chat的依赖清单见 packages/agent-chat/package.json中已经没有zod取而代之的是工作区包scalar/validationworkspace 依赖这正是 remove zod and use the custom validation library 的直接证据。工具入参模式均通过scalar/validation的object、string、optional、record等函数式 API 声明例如// packages/agent-chat/src/entities/tools/search-openapi-operations.ts import { object, string, type Static } from scalar/validation export const searchOpenAPIOperationsInputSchema object({ question: string(), })而execute-request工具的输入模式则展示了验证库对可选字段与嵌套记录的支持见 packages/agent-chat/src/entities/tools/execute-request.tsexport const executeClientSideRequestToolInputSchema object({ method: string(), path: string(), headers: optional(record(string(), string())), body: optional(string()), documentName: string(), documentIdentifier: string({ typeComment: Needed for legacy support for old clients }), })实践要点对使用方而言0.12.0 意味着同一个 Agent 工作区里可以同时挂载 RESTOpenAPI与事件驱动AsyncAPI两类 API 描述文档聊天 UI 无需区分来源即可加载、摘要与检索它们对二次开发者而言若需扩展新的文档类型应修改WorkspaceDocument联合类型并在文档入库流程见下文add-documents-to-store中接入对应的 bundle 解析路径。0.12.7发布收尾的依赖与稳定性修复该条目的标题是 Polish and bug fixes shipped打磨与缺陷修复已发布。CHANGELOG 给出了具体内容PR#9445将neverpanic依赖升级到 0.0.8该版本移除了 TypeScript peer dependency从而消除了安装时的 unmet peer 警告。neverpanic是仓库广泛使用的错误处理工具返回Result类型的 safe 函数包装在 agent-chat 中被loadDocument、api.ts的请求封装等核心路径使用。这一改动属于典型的发布收尾工程不引入新功能而是让依赖树更干净、安装体验更稳定。0.10.14Tailwind CSS 代码分割为聊天 UI 首屏减负发布说明指出Tailwind CSS is now code-split so the Agent chat interface loads less CSS up front.Tailwind CSS 现在被代码分割Agent 聊天界面首屏加载的 CSS 更少。对应 CHANGELOG 中的 PR#9086feat: code split tailwind CSS to reduce bundle size。从构建脚本可以还原这条优化的实现方式见 packages/agent-chat/package.json 的scriptsbuild:styles: shx cp -r src/styles dist tailwindcss --optimize -i src/style.css -o dist/style.css cat dist/vue-styles.css dist/style.css样式构建链由三条命令串联先把src/styles目录含tailwind.config.css复制到产物目录再用 Tailwind CLI 以--optimize模式把src/style.css编译为压缩后的dist/style.css最后把 Vue 组件样式文件dist/vue-styles.css追加合并。代码分割的价值在于tailwindcss --optimize会按需摇树tree-shake掉未使用的工具类而 CSS 被拆分为独立产物后聊天组件可以只请求首屏真正需要的样式块而不是一次性拉取整份 Tailwind 工具类全集。这与组件库中大量使用 Tailwind 工具类、同时又要控制包体量的诉求直接相关。实践要点scalar/agent-chat通过exports字段对外暴露多种样式入口包括./style.css、./*.css、./css/*.css、./tailwind.config.css与./vue-styles.css消费方可按需选择引入哪一份样式这正是代码分割之后对外可用的产物形态。0.10.10文档加载携带平台令牌认证请求不再失败发布说明Document fetches now include the platform token so authenticated doc requests succeed consistently.文档获取现在会携带平台令牌使经过认证的文档请求稳定成功。对应 CHANGELOG PR#8999Include platform token in doc fetch。这条改动的落点可以从两处源码直接观察到第一处是 API 请求层的统一认证头构造见 packages/agent-chat/src/api.tsexport function createAuthorizationHeaders({ getAccessToken, getAgentKey, }: { getAccessToken?: () string getAgentKey?: () string }) { const token getAccessToken?.() const agentKey getAgentKey?.() return { ...(token { Authorization: Bearer ${token} }), ...(agentKey { x-scalar-agent-key: agentKey }), } }所有createApi产生的请求search、getDocument、getKeyDocuments、getCuratedDocuments都会统一注入这套头平台访问令牌走标准Authorization: BearerAgent 专用密钥走x-scalar-agent-key。第二处是文档入库时的 bundle 加载见 packages/agent-chat/src/registry/add-documents-to-store.ts。loadDocument在调用api.getDocument拿到文档元数据后会用bundle()来自scalar/json-magic/bundle拉取并打包远程文档其中通过fetchUrls插件按域名注入带认证的请求头const token getAccessToken?.() if (token) { headers.push({ domains: [new URL(registryUrl).host], headers: { x-scalar-auth: token }, }) }实现原理fetchUrls插件支持按domains白名单匹配请求只有指向注册表域名registry host的文档引用才会带上x-scalar-auth令牌头避免令牌被误发到第三方域名。0.10.10 之前文档获取请求未包含该令牌导致受保护的私有文档在拉取外部$ref引用或文档内容时认证失败、加载不一致此次修复让认证令牌贯穿元数据接口 文档 bundle 下载全链路。0.10.9Agent credits 计费文案更清晰发布说明We updated the copy around Agent credits so free limits and usage are easier to understand in the chat UI.我们更新了 Agent credits 相关文案让免费额度与用量在聊天 UI 中更容易理解。对应 CHANGELOG PR#8989fix: language around agent credits。这是一条纯 UI/UX 修复不涉及请求逻辑只调整聊天界面中关于免费消息额度与用量说明的文案。从源码结构看与 credits 相关的界面组件集中在 packages/agent-chat/src/components 下包括FreeMessagesInfoSection.vue免费消息额度信息区、PaymentSection.vue付费/充值区块、ApprovalSection.vue审批区等。它们共同构成了聊天界面中额度提示 — 审批 — 支付的用户引导链路0.10.9 让这条链路上的措辞尤其是免费限制边界对用户更友好。从源码看 Agent Chat 的完整能力面上述发布条目只勾勒了近期演进要真正理解scalar/agent-chat是什么还需要结合 packages/agent-chat/src 的整体结构。从目录树可以清晰看到四个层次工具集entities/toolsAgent 与用户交互的能力单元包括get-openapi-specs-summary.tssummarize-openapi-specs汇总工作区各文档的路径、servers、securitySchemes 与 info见 源码、search-openapi-operations.tssearch-openapi-operations按自然语言问题检索操作、execute-request.tsexecute-request客户端直发请求并返回Result类型的结构化错误如FAILED_TO_FETCH、REQUEST_NOT_OK、FAILED_TO_PARSE_RESPONSE_BODY、ask-for-authentication.ts向用户索取认证凭据。注册表与文档入库registryadd-documents-to-store.ts及其测试 add-documents-to-store.test.ts负责把平台文档 bundle 后写入scalar/workspace-store并恢复本地存储中的认证密钥。界面组件components/views请求审批流RequestPreview/RequestApproved/RequestRejected、响应体渲染ResponseBody支持媒体类型探测与文本/JSON 预览、文档目录选择Catalog、搜索弹层SearchPopover等。状态与持久化state/pluginsstate.ts承载聊天会话状态plugins/persistance.ts负责会话持久化。从 CHANGELOG 还可以看到更多能力演进线索0.4.5 引入 inline agent chat 与启停开关PR#7995/#80020.5.2 增加客户端请求工具PR#80270.5.18 提供隐藏搜索 API 的配置项PR#82740.9.14 使外部 URL 可配置PR#85740.12.26 修复了输入法合成IME期间误发送消息的问题并为 NDJSON 响应提供逐条 JSON 格式化预览。在本仓库中验证与运行若想在本仓库中亲自体验或验证上述发布内容有两种方式阅读权威记录结构化数据看 packages/agent-chat/RELEASE_NOTES.json完整 PR 明细看 packages/agent-chat/CHANGELOG.md。运行本地 playgroundscalar/agent-chat自带演示环境见 packages/agent-chat/playground在仓库根目录执行pnpm install后进入packages/agent-chat运行pnpm dev即pnpm playground内部执行cd playground vite即可启动聊天 UI 的开发服务器。需要说明的是该包要求 Node.js 22LTS这是 0.8.0 起抬升的硬性门槛CHANGELOG PR#8322同时它依赖scalar/api-client、scalar/workspace-store等多个同仓库工作区包脱离 pnpm workspace 单独安装无法直接工作。小结把五个版本条目串起来看scalar/agent-chat的演进主线非常清晰能力面上0.12.0 让工作区从纯 OpenAPI 扩展为 OpenAPI AsyncAPI 联合支持并借机用自研验证库替代 zod统一了全仓库的输入校验范式可靠性上0.10.10 补齐了文档加载的认证令牌0.12.7 清理了依赖告警体验与性能上0.10.9 优化了 credits 文案0.10.14 通过 Tailwind CSS 代码分割降低首屏 CSS 体积。这些看似零散的发布条目恰好覆盖了一个前端聊天组件在功能、稳定、性能、商业化引导四个维度的典型迭代节奏也为在仓库中二次开发scalar/agent-chat提供了清晰的演进上下文。【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考