big-AGI 的 AIX 单调版本号滚动Roll AIX实践指南从命令到模型定义版本化体系【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGIMonotonics.Aix是 big-AGI 用于触发全量客户端数据重新校验的单调递增版本号其滚动动作通过仓库内置的 Claude Code 命令roll-aix一键完成。本文以该命令文档为主体结合src/common/app.release.ts、src/modules/llms/版本化体系与引导期重配置源码完整讲解 AIX 的含义、滚动步骤、前置检查以及它与按厂商per-vendor模型定义版本化LLM-defs-refresh的分工边界——读完你既能安全执行一次 AIX 滚动也能理解何时该滚 AIX、何时该滚 epoch的决策依据。一、AIX 单调版本号是什么在 app.release.ts 中big-AGI 集中维护着一组单调计数器// this is here to trigger revalidation of data, e.g. models refresh Monotonics: { Aix: 92, NewsVersion: 210, },Monotonics.Aix当前值为92是 AIXAI eXperience / 协议能力层的单调版本号。每次滚动加 1会强制刷新每一个客户端上的每一个 LLM 服务商。Monotonics.NewsVersion用于新闻/公告数据的重新校验与 AIX 相互独立。按 roll-aix.md 的说明AIX 滚动属于协议级变更protocol-level change的保留动作Aix被折叠进每个服务商的模型定义版本见下文llmsDefsVersionFor因此滚一次 AIX 等价于对全量客户端广播所有定义已更新。二、什么时候该滚 AIX什么时候不该滚这是理解该命令的核心边界原文档给出了明确的决策规则需要滚 AIX发生了协议级protocol-level变更需要让所有客户端、所有服务商重新校验并刷新。不再需要为模型定义更新滚 AIX模型定义更新已改为按厂商自动滚动详见 kb/modules/LLM-defs-refresh.md每个厂商有独立的版本客户端只在对应厂商定义变化时单独刷新无需全局滚动。只想强制滚动单个厂商在 llms.defs.manifest.ts 中 bump 该厂商的epoch字段_shared.epoch则用于强制滚动所有厂商。AIX 滚动必须保留给协议级变更不要把它当成模型列表更新的日常手段。从源码上看这一折叠关系由 llm.client.defs.ts 的llmsDefsVersionFor实现export function llmsDefsVersionFor(vendorId: ModelVendorId, serviceSetup: Recordstring, any | undefined): string { const bucket (vendorId openai !llmsIsNativeOpenAIHost(serviceSetup?.oaiHost || undefined)) ? _openaiCompat : vendorId; return ${LLMS_DEFS_VERSIONS[bucket]}-a${Release.Monotonics.Aix}; }即每个服务的有效版本 内容哈希版本 -a Monotonics.Aix。因此无论内容哈希是否变化Aix一旦 1所有服务的版本字符串都会变化从而全部进入刷新队列——这正是AIX 滚动刷新所有厂商的底层机制。三、执行 Roll AIX 的标准操作流程roll-aix.md是仓库内置的 Claude Code 命令位于 .claude/commands/aix/roll-aix.md被声明为disable-model-invocation: true即仅允许显式调用且约束了工具权限仅Bash(git add:*)、Bash(git status:*)、Bash(git commit:*)、Edit、Write与模型档位model: sonnet。完整流程如下1. 前置检查MUST pass or abort不满足必须中止# 检查 1必须位于 main 分支 git branch --show-current # 检查 2目标文件必须无本地改动 git status src/common/app.release.ts若当前不在main分支中止若src/common/app.release.ts存在未提交改动中止防止把无关改动混入本次提交也保证只改一行的提交是干净的。2. 执行滚动读取 app.release.ts 中当前的Monotonics.Aix值示例中为92将其递增 1示例中改为93只更新那一行不得顺带改动文件内其他内容提交git add src/common/app.release.ts git commit -m Roll AIX3. 确认提交完成后重新读取Monotonics.Aix向调用方确认新版本号。为什么前置检查如此严格从 app.release.ts 的头部注释可以看到该文件同时被前端与后端引入取决于构建时刻两端的值可能不同是所有版本信息TenantSlug、Features、TechLevels、AiFunctions、buildInfo等的集中配置面。它被前端 bundle 与后端共同读取任何无关改动混入 AIX 提交都可能造成构建期不一致的版本信息。因此只改一行 干净提交是硬性纪律。四、按厂商模型定义版本化AIX 的分工伙伴为了让读者理解为什么模型定义更新不再需要滚 AIX这里展开 LLM-defs-refresh.md 描述的核心机制——它与 AIX 滚动共同构成 big-AGI 的版本刷新体系文件角色llms.defs.manifest.ts手维护的清单声明每个厂商的定义文件归属。satisfies RecordModelVendorId, ...让新增/删除厂商在清单与生成映射未同步时直接编译报错generate-llms-defs.mjs生成器对声明文件做语义哈希、执行完整性门禁、写出映射支持--check只算不写llms.defs.versions.ts生成并提交的映射每个 bucket 一个 12 位十六进制版本如openai: 970f492bca59llm.client.defs.tsllmsDefsVersionFor(vendorId, setup)服务对比使用的有效版本折叠 AIX含自定义主机 OpenAI 特例reconfigureBackendModels.ts引导期选择性刷新逐一比对服务戳记与版本只重列不匹配者package.jsonpredev/predev-debug/prebuild串联生成器完整性失败即构建失败版本如何推导什么会滚、什么不会滚每个被声明的文件都会经过ts.transpileModule归一化删除注释、擦除类型、统一 LF 换行再做 sha256 哈希一个 bucket 的版本对其文件加epoch做哈希且每个非_sharedbucket 都会把_shared的摘要折叠进来。运行期再追加-aMonotonics.Aix即上文llmsDefsVersionFor的实现。会滚动模型表、标签、定价、zod wiretype schema、过滤/排序/变体代码、共享映射等任何运行时语义变化不会滚动注释、JSDoc、格式、空白、纯类型编辑interface、注解、import type局部变量重命名会滚可接受的误报代价仅是一次多余重列官方强制滚动手段bump 厂商epoch滚单厂商或_shared.epoch滚全部SCHEME_REV在哈希方案变化时强制滚动所有 bucket确定性哈希是源码 锁定的 typescript 版本的纯函数任意机器都能逐位复现提交的映射。启动期刷新流程ProviderBootstrapLogic→ sherpa →reconfigureBackendModels每会话一次在 capabilities 提供者确认前后端构建匹配之后执行reconfigureBackendModels.ts为后端配置的厂商幂等创建服务hasLlm*能力标志服务在刚创建或其defsV戳记与llmsDefsVersionFor(vId, setup)不一致时刷新未知厂商来自更新版本 App 的数据保持不变失配服务通过一个小型并发池4 个在途重列戳记在每次尝试之前写入因此离线 Ollama、失效 LocalAI、吊销的 key 不会每次启动都被重试而是等版本滚动或手动刷新若有任何刷新LLMs 按服务顺序重新排序并运行领域自动分配。值得注意的行为差异API key 轮换不再触发刷新旧哈希包含 env 值但定义并未变化刷新从全有或全无变成按服务同一厂商的所有实例一起刷新。五、实操从命令行验证 AIX 与版本体系验证当前 AIX 值并确认生成映射是否过期# 查看当前 AIX 值期望 92 grep -n Aix src/common/app.release.ts # 只校验不写入生成映射是否过期过期时退出码为 2 node tools/develop/gen-llms-defs/generate-llms-defs.mjs --check对一次标准 Roll AIX最终形态应是一行 diff 与一条Roll AIX提交git diff HEAD~1 -- src/common/app.release.ts # 期望输出形如- Aix: 92, / Aix: 93, git log --oneline -1 # Roll AIX发布侧注意事项来自 LLM-defs-refresh.md 的部署说明Vercel 与 Docker 构建走npm run buildprebuild会自动再生成映射因此即使提交的生成文件滞后部署产物也始终携带与编译定义一致的哈希next start不会运行生成器Docker 运行阶段已被裁剪。静态导出与无 key 构建不受影响。六、小结Roll AIX 决策速查场景手段协议级变更需要全量客户端刷新所有厂商执行 Roll AIXMonotonics.Aix1单个厂商模型定义变更正常合入对应*.models.ts版本自动滚动无需干预强制滚动单个厂商注释/类型改动也想滚bump 该厂商epoch强制滚动所有厂商bump_shared.epoch哈希方案本身变化提升生成器SCHEME_REV在 big-AGI 的工程实践中Roll AIX从高频日常操作被收敛为协议级保留动作日常模型更新由按厂商哈希版本自动完成。理解二者的分工既能避免滥用全局刷新也能在真正需要协议级失效时用一条命令、一行 diff、一次干净提交安全地完成全局版本推进。【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考