更新日志
所有包共用一个版本号。npm 包发布在 @aidy-dev 之下;Python 套件是 PyPI 上的 aidy。
0.2.0(2026-11)
Section titled “0.2.0(2026-11)”来自四个产品迁移(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、documentpart(最多 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 以前会拒绝它们。
知识库(@aidy-dev/knowledge)
Section titled “知识库(@aidy-dev/knowledge)”- 显式标题 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。
Python 套件(aidy)
Section titled “Python 套件(aidy)”SearchHit.content。- 线上格式模型在 FastAPI 的 OpenAPI 中显示真实的 camelCase JSON Schema,并且仍然省略缺失的字段。
- 用例可以编排模型链(
endpoints、每轮的endpoint),检查模型看到的内容(sees),发送 content part 和上下文,并编排普通宿主请求、原始响应体和延迟。新增用例:模型回退、额度休眠、限流、所有端点失败;宿主图片、外部图片和无视觉端点时的图片;页面上下文;结果正文;引用编号;源超时;宿主错误响应体。
0.1.0(2026-11)
Section titled “0.1.0(2026-11)”首个版本。
| 包 | 内容 |
|---|---|
@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运行在任意宿主旁边。 - 一致性用例固定运行时的每一项行为。