企业官网建设流程全解析

@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.0：Agent 工作区原生支持 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/validation（workspace 依赖），这正是 "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.ts）：

export 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 工作区里可以同时挂载 REST（OpenAPI）与事件驱动（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.14：Tailwind CSS 代码分割，为聊天 UI 首屏减负

发布说明指出："Tailwind CSS is now code-split so the Agent chat interface loads less CSS up front."（Tailwind CSS 现在被代码分割，Agent 聊天界面首屏加载的 CSS 更少。）对应 CHANGELOG 中的 PR#9086："feat: code split tailwind CSS to reduce bundle size"。

从构建脚本可以还原这条优化的实现方式（见 packages/agent-chat/package.json 的scripts）：

"build: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#8999："Include platform token in doc fetch"。

这条改动的落点可以从两处源码直接观察到：

第一处是 API 请求层的统一认证头构造（见 packages/agent-chat/src/api.ts）：

export 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: Bearer，Agent 专用密钥走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.9：Agent 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#8989："fix: 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/tools）：Agent 与用户交互的能力单元，包括get-openapi-specs-summary.ts（summarize-openapi-specs，汇总工作区各文档的路径、servers、securitySchemes 与 info，见 源码）、search-openapi-operations.ts（search-openapi-operations，按自然语言问题检索操作）、execute-request.ts（execute-request，客户端直发请求并返回Result类型的结构化错误，如FAILED_TO_FETCH、REQUEST_NOT_OK、FAILED_TO_PARSE_RESPONSE_BODY）、ask-for-authentication.ts（向用户索取认证凭据）。
• 注册表与文档入库（registry）：add-documents-to-store.ts及其测试 add-documents-to-store.test.ts，负责把平台文档 bundle 后写入@scalar/workspace-store，并恢复本地存储中的认证密钥。
• 界面组件（components/views）：请求审批流（RequestPreview/RequestApproved/RequestRejected）、响应体渲染（ResponseBody，支持媒体类型探测与文本/JSON 预览）、文档目录选择（Catalog）、搜索弹层（SearchPopover）等。
• 状态与持久化（state/plugins）：state.ts承载聊天会话状态，plugins/persistance.ts负责会话持久化。

从 CHANGELOG 还可以看到更多能力演进线索：0.4.5 引入 inline agent chat 与启停开关（PR#7995/#8002）；0.5.2 增加客户端请求工具（PR#8027）；0.5.18 提供隐藏搜索 API 的配置项（PR#8274）；0.9.14 使外部 URL 可配置（PR#8574）；0.12.26 修复了输入法合成（IME）期间误发送消息的问题，并为 NDJSON 响应提供逐条 JSON 格式化预览。

在本仓库中验证与运行

若想在本仓库中亲自体验或验证上述发布内容，有两种方式：

1. 阅读权威记录：结构化数据看 packages/agent-chat/RELEASE_NOTES.json，完整 PR 明细看 packages/agent-chat/CHANGELOG.md。
2. 运行本地 playground：@scalar/agent-chat自带演示环境（见 packages/agent-chat/playground），在仓库根目录执行pnpm install后，进入packages/agent-chat运行pnpm dev（即pnpm playground，内部执行cd playground && vite）即可启动聊天 UI 的开发服务器。

需要说明的是，该包要求 Node.js >= 22（LTS），这是 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