跳转到内容

更新日志

所有包共用一个版本号。npm 包发布在 @aidy-dev 之下;Python 套件是 PyPI 上的 aidy。

来自四个产品迁移(Acahti、Pipetil、kunzhiyuan 和本站)中发现的缺口。aidy 尚在 1.0 之前,次版本可能有破坏性变更,下面先列出全部破坏性变更。

  • aidy.citation 改为 {messageId, citations: [{n, hit}]}:每个被引用的结果放在回答所写的编号下。原来是按顺序排列的 {messageId, hits},[11] 或 [2][4] 会链接到错误的结果。ThreadState.citations 保存 Citation[](@aidy-dev/client)。
  • aidy.model.retry 增加 endpoint 和 fallback。
  • 模型链。 不在同一端点上重试的失败(400、401、403、404 等 4xx,额度类响应,429,重试次数用完)都会让该端点休眠,并交给下一个端点。休眠中的端点会被跳过,只有没有可用端点时才返回 model_unavailable;所有端点都在休眠时,不再重试被限流的端点。见模型。
  • SearchHit 增加只给模型看的 content;FederatedHit 和引用中的结果不含它。fuse 返回 FusedHit(含 content)。
  • 搜索操作 默认超时 2 秒,x-aidy.timeoutSeconds 最大 10;更大的值是目录错误。
  • @aidy-dev/client:ClientOptions.baseUrl 表示 aidy 的挂载位置,可选(默认 '');RunRequest.message 为 string | ContentPart[];UserItem.attachments 必有;ModelEndpointUpdate.id 必填。
  • @aidy-dev/react:locale 可以是任意字符串,Locale 类型已移除(由 Strings 和 locales 取代)。
  • CLI:内置的 whoami 改名为 status。
  • 存储:新增必须实现的方法 putFeedback、listFeedback 和 deleteSettings;SQL 迁移 002_feedback。
  • 一致性测试运行器:RuntimeEnv.model 改为 RuntimeEnv.endpoints。

运行时(@aidy-dev/core、@aidy-dev/spec)

Section titled “运行时(@aidy-dev/core、@aidy-dev/spec)”
  • 宿主任务:POST /aidy/v0/generate,用 op 为 generate 的 Aidy-Host-Assertion 签名,接受 {instructions?, input, schema?, maxOutputTokens?},返回 {text} 或 {object}(按 schema 校验,修正一次,仍不符合则 422 invalid_output),使用同一条模型链,没有工具和会话。见宿主任务。
  • 模型链:额度类响应(402,或响应体含 quota、insufficient、exhausted、401008)休眠 6 小时,429 休眠 60 秒,其他 5 分钟,可按端点用 cooldownSeconds: {quota, rateLimit, error} 覆盖。端点可设置 temperature 和 maxOutputTokens。每个实例一条模型链,由运行和宿主任务共用。
  • 图片与附件:用户消息接受 AG-UI 的 text、image、document part(最多 10 个附件)。宿主上的图片以用户凭据获取并内联(最大 5 MB),其他 URL 原样传递;图片只发给视觉端点,其他端点收到一条说明。文本类文档以文本读取。每个附件都会连同 URL 告知模型。见用户消息。
  • 页面上下文:运行的 AG-UI context 加入该运行的系统提示词(最多 16 条、8000 个字符)。
  • 异步指令:instructions 可以是身份的异步函数。
  • 搜索:按源设置超时(x-aidy.timeoutSeconds、SearchSource.timeoutMs);结果的 content 通过 search 工具和 MCP 交给模型,从不出现在 /search 和引用中。
  • 工具错误:宿主调用失败时,模型会在 error.detail 中收到宿主脱敏后的错误响应体(最多 4 KB)。
  • 反馈:PUT /aidy/v0/threads/{id}/messages/{messageId}/feedback(up 或 down,可附评论),以及供管理员使用的 GET /aidy/v0/feedback。
  • 信息:GET /aidy/v0/info 返回助手的 name。
  • 设置:DELETE /aidy/v0/settings 恢复配置中的模型;secret 可以是列表以便轮换(第一个加密,全部可解密,旧设置会重新加密);无法解密的设置返回 503 settings_unreadable。
  • 宿主断言 绑定到 aidy 的公开源加路径,因此延迟任务和宿主任务在代理后面也能工作。
  • 没有请求体的请求(DELETE、取消运行)不再需要 Content-Type;有请求体时必须是 JSON。
  • 生成的文档:skill.name(产品名不是 ASCII 时也是合法的 slug),以及 skill.cli: {command, package?, install?},会出现在 /skill.md 和 /llms.txt 中。
  • 密钥:新增 importSigningKey 和 portableJwk;importPublicKeys 接受 Node 导出的 JWK(带 alg),workerd 以前会拒绝它们。
  • 显式标题 id ## Title {#anchor} 用于设置锚点,并会从标题中去掉。
  • 结果以 content 携带分块正文。

客户端与 React(@aidy-dev/client、@aidy-dev/react)

Section titled “客户端与 React(@aidy-dev/client、@aidy-dev/react)”
  • 客户端:run(threadId, {message, context?, resume?})、attachmentPart、attachmentsOf、info、setFeedback、listFeedback、resetSettings、baseUrl。
  • AidyProvider:upload(附件按钮、拖放、粘贴;对话中显示缩略图)、context、locale 和 strings(导出 Strings 和 locales;未知语言回退为英文),以及从 GET /info 读取的助手名称。
  • AidyDock 按 client 的 baseUrl 记住打开状态和当前对话,并支持受控的 open/onOpenChange 和 threadId/onThreadChange。
  • SearchPalette:受控的 open/onOpenChange、useSearchPalette()、onAsk,以及通过 strings(type.<type>)设置类型名称。
  • 回答下方的赞和踩,可附评论;ModelSettings 增加“恢复默认”,新增的行会得到 id。
  • 每个组件在侧边栏之外使用时也带有 .aidy-root 主题,样式不再依赖会被 CSS reset(Tailwind preflight)去掉的浏览器默认样式。

见 React。

CLI 与服务端(@aidy-dev/cli、@aidy-dev/server)

Section titled “CLI 与服务端(@aidy-dev/cli、@aidy-dev/server)”
  • 从环境变量读取凭据(AIDY_HOST/AIDY_TOKEN,或用 aidy brand --env-host --env-token 指定品牌自己的变量名);命令行参数优先于环境变量,环境变量优先于已保存的登录;来自环境变量的 token 从不写入磁盘,也从不打印。
  • aidy brand --host 改为可选。
  • 宿主命令优先于同名内置命令,内置命令仍可通过 aidy:<name> 调用。
  • 每个命令都支持 --help。
  • aidy keys generate 和 aidy-server keys 生成可移植的 JWK。
  • 服务端环境变量:AIDY_SKILL_NAME、AIDY_CLI_COMMAND、AIDY_CLI_PACKAGE、AIDY_CLI_INSTALL、AIDY_PREVIOUS_SECRET。

见 CLI 和部署。

  • SearchHit.content。
  • 线上格式模型在 FastAPI 的 OpenAPI 中显示真实的 camelCase JSON Schema,并且仍然省略缺失的字段。
  • 用例可以编排模型链(endpoints、每轮的 endpoint),检查模型看到的内容(sees),发送 content part 和上下文,并编排普通宿主请求、原始响应体和延迟。新增用例:模型回退、额度休眠、限流、所有端点失败;宿主图片、外部图片和无视觉端点时的图片;页面上下文;结果正文;引用编号;源超时;宿主错误响应体。

首个版本。

包 内容
@aidy-dev/spec 与语言无关的契约:x-aidy 目录读取、委托断言、搜索融合和 AG-UI profile 的 schema。
@aidy-dev/core 运行时及其 Web 标准的 fetch 处理函数(createAidy):会话、运行、审批、表单、resolve、链式调用、AG-UI 事件、MCP、联合搜索、设置和生成的文档。另含 MemoryStore 和 SqlStore。
@aidy-dev/sql SqlDriver 契约,Postgres、SQLite 和 Cloudflare D1 驱动,以及迁移执行器。
@aidy-dev/documents 生成 skill.md、llms.txt、操作参考和 CLI 命令名。
@aidy-dev/knowledge Markdown 导入、按标题分块和 BM25 检索,提供 embedder 时加上向量检索;作为名为 knowledge 的搜索来源。
@aidy-dev/client HTTP API 的类型化客户端,以及把 AG-UI 事件归约为会话状态的 reducer。
@aidy-dev/react AidyDock、AidyThread、ApprovalCard、AidyForm、SearchPalette、HelpViewer 和 ModelSettings。
@aidy-dev/server aidy-server 命令(serve、keys),通过环境变量配置,在任意语言的宿主旁运行 aidy;用于 Express 和 node:http 的 nodeHandler;Docker 镜像 ghcr.io/aidy-dev/aidy-server。
@aidy-dev/cli aidy 命令:任何 aidy 宿主的通用 MCP 客户端,另有 check、skill、llms、reference、docs、keys generate 和 brand。
aidy(PyPI) Python 宿主套件:op(),用于 FastAPI 的 AidyHost 和 AidyCall,verify_assertion、check_call,以及 Identity 和搜索模型。需要 Python 3.12+。
  • 目录。 在 OpenAPI 3.1 操作上使用 x-aidy,严格校验,按 HTTP 方法推断默认值,支持 identity、search 和 form 三种角色。见 x-aidy。
  • 委托。 对宿主的每次调用都携带用户自己的凭据和一个 EdDSA Aidy-Assertion,绑定方法、URL 和请求体。TypeScript 和 Python 均提供宿主侧校验,并以共享测试向量检验。
  • 审批。 写操作默认 approval: always。审批绑定到冻结参数的哈希(RFC 8785),15 分钟后过期,最多执行一次。
  • 表单、resolve 与链式调用。 宿主表单(role: form)和模型的 request_input;名称或 id 解析;用 next 定义后续调用。
  • 延后任务。 操作返回 202 {"aidyTask"},由宿主用 Aidy-Host-Assertion 完成。
  • AG-UI 1.0 事件流及 aidy profile:每个会话单调递增的 seq,用 Last-Event-ID 回放,运行的生命周期长于连接。见 事件。
  • MCP 服务位于 /mcp:默认只读,写操作需要 elicitation 确认;配置后提供 OAuth 受保护资源元数据。
  • CLI 在运行时根据宿主的 MCP 工具生成,支持品牌化封装。
  • 生成的文档:/skill.md、/llms.txt 和操作参考。
  • 联合搜索覆盖每个 role: search 操作和知识库,按倒数排名融合合并,回答中附带引用。
  • 模型链支持 OpenAI 兼容、OpenAI 和 Anthropic provider 以及任意 AI SDK 模型,遇到 402 和 429 时冷却,管理员设置加密存储。
  • 运行环境:嵌入 Node 或 Cloudflare Workers 上的 JavaScript 宿主,或用 aidy-server 运行在任意宿主旁边。
  • 一致性用例固定运行时的每一项行为。
  • Hono 和 Express 适配包:按 Hono 和 Express 指南,用 createAidy 和 nodeHandler 内嵌 aidy。
  • Go 宿主套件。目前只有 Python 宿主套件。
  • 通过 PUT /aidy/v0/settings 管理知识库设置:设置只包含模型链。
  • Helm chart。