Craft Agents v0.10.1 发布解析Claude Opus 4.8 默认化、多语言会话标题修复与 Apple Silicon 平台策略调整【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-ossv0.10.1 是 Craft Agents 桌面端的一次「小版本、大改动」迭代虽然没有新增功能特性但它在模型默认值、国际化i18n持久化、渲染层交互修复三个方向同时落地了重要改进并带来两项需要用户知悉的 Breaking Changes。本文以仓库内 apps/electron/resources/release-notes/0.10.1.md 为骨架结合 packages/shared/src/config/models.ts、packages/shared/src/config/preferences.ts、apps/electron/electron-builder.yml 等源码逐条还原每个变更背后的实现细节帮助开发者理解升级影响面并验证修复效果。版本概览一次以「默认值迁移与体验修复」为核心的迭代v0.10.1 的 Features 列表为空全部变更集中在 Improvements、Bug Fixes 与 Breaking Changes 三类模型层Claude Opus 4.8 成为默认 Opus 模型SDK 升级至 0.3.154旧型号进入迁移路径国际化层会话标题与系统提示词的语言终于跟随「设置 → 外观」中选定的 UI 语言跨重启保持一致渲染层可滚动 Markdown 预览中的文本选择高亮在滚动后不再错位平台策略macOS 停止发布 Intel (x64) 构建仅保留 Apple Silicon (arm64)配置格式旧的自由文本language偏好字段被内部受控字段uiLanguage取代。下文逐项展开并给出对应的源码与测试证据。Claude Opus 4.8 成为默认 Opus 模型升级路径与模型注册表分析变更内容本次更新将 Claude Agent SDK 升级到 0.3.154并把Claude Opus 4.8设为 Anthropic Opus 系列的新默认模型同时保留Opus 4.7可供手动选择从模型选择器中移除已废弃的 Opus 4.6已有直接走 Anthropic 通道且默认 Opus 4.7 的用户默认值自动迁移到 Opus 4.8选择了 Opus 4.5 / 4.6 的用户自动迁移到当前可用的最佳 Opus 模型。源码级佐证模型注册表与迁移映射模型注册表定义在 packages/shared/src/config/models.ts其中 Opus 4.8 与 4.7 的条目如下{ id: claude-opus-4-8, name: Opus 4.8, shortName: Opus, description: Most capable for complex work, descriptionKey: model.opusDesc, provider: anthropic, contextWindow: 1_000_000, }, { id: claude-opus-4-7, name: Opus 4.7, shortName: Opus, description: Previous Opus generation, descriptionKey: model.opusDesc, provider: anthropic, contextWindow: 1_000_000, },同文件中的DEPRECATED_MODEL_REPLACEMENTS映射则实现了「旧型号迁移到最佳可用 Opus」的语义例如claude-opus-4-5-20251101: claude-opus-4-8, claude-opus-4-6: claude-opus-4-8, anthropic.claude-opus-4-5-20251101-v1:0: anthropic.claude-opus-4-8, anthropic.claude-opus-4-6-v1: anthropic.claude-opus-4-8,注意该映射同时覆盖裸 ID 与带 provider 前缀的完整 IDanthropic.前缀说明迁移逻辑不只作用于用户选择的模型 ID也作用于模型解析与回退路径的中间表示。Bedrock 映射与 Pi 回退同文件顶部的BEDROCK_TO_BARE映射同步加入了 Opus 4.8 的 Bedrock 原生推理配置 IDUS / EU / Global 三区域如us.anthropic.claude-opus-4-8使 Bedrock 通道也能正确识别新模型并反向映射为裸 ID 做注册表查找。同时Pi 服务的模型回退处理也随本次发布同步更新对应文件 packages/shared/src/config/models-pi.ts相关迁移行为有 packages/shared/tests/models.test.ts 与 packages/shared/src/config/tests/llm-connections.test.ts 等测试覆盖。版本追踪说明需要指出的是v0.10.1 发布时升级的是 SDK 0.3.154当前仓库根目录 package.json 中anthropic-ai/claude-agent-sdk已进一步演进至 0.3.197说明后续版本在继续跟进 SDK 更新本文所述迁移机制与默认模型策略在后续版本中依然有效。会话标题尊重「设置 → 外观」语言uiLanguage 持久化机制的诞生问题根因该修复对应一个长期困扰非英语用户的回归会话标题session title和系统提示词中的 Preferred language 一行在重启后总是回到英文即使「设置 → 外观」里已选择了其他语言。根因链条如下渲染进程renderer依赖浏览器环境的localStorage恢复界面语言重启后表现正常主进程main process的 i18n 实例没有语言检测插件Node 环境里不存在localStorage且从未从磁盘重新水合re-hydrate因此始终停留在en兜底值标题生成generateTitle/refreshTitle与系统提示词的语言行读取的正是主进程的语言值于是「渲染进程是中文、主进程是英文」的割裂状态导致标题以英文生成。修复方案受控uiLanguage字段 主进程启动水合修复引入了一个内部、经过校验的uiLanguage字段由「设置 → 外观」驱动替代原先的自由文本language字段用户在设置中切换语言时渲染进程通过i18n:changeLanguageIPC 将语言码推给主进程主进程将其持久化到preferences.json的uiLanguage字段应用下次启动时主进程在启动引导阶段读取该字段并调用i18n.changeLanguage(...)完成水合升级场景下渲染进程会在首次启动时主动把自身已解析的语言推送给主进程一次从而无需用户重新选择即可学到当前语言值。源码级佐证主进程的水合逻辑位于 apps/electron/src/main/index.ts文件头部有明确注释说明设计意图import { setupI18n, i18n, SUPPORTED_LANGUAGE_CODES, type LanguageCode } from craft-agent/shared/i18n import { getPersistedUiLanguage, setPersistedUiLanguage } from craft-agent/shared/config setupI18n() const persistedUiLanguage getPersistedUiLanguage() if (persistedUiLanguage) { void i18n.changeLanguage(persistedUiLanguage) }i18n:changeLanguageIPC handler同文件ipcMain.handle(i18n:changeLanguage, ...)负责校验语言码是否属于SUPPORTED_LANGUAGE_CODES、调用setPersistedUiLanguage持久化、并重建原生菜单。偏好字段的定义与读写逻辑在 packages/shared/src/config/preferences.tsexport interface UserPreferences { // ... /** * Internal: persisted UI language code (mirrors Appearance → Language). * Maintained only by the main-process i18n:changeLanguage IPC handler. * Not user-editable; not exposed via the update_user_preferences tool. */ uiLanguage?: LanguageCode; // ... }关键函数包括getPersistedUiLanguage()读取preferences.json中的uiLanguage若字段缺失或值不在SUPPORTED_LANGUAGE_CODES内则返回undefined防御性读取setPersistedUiLanguage(code)幂等写入——值未变化时不重写文件、不更新updatedAt避免在启动同步时重复触发配置 watcher 和重复 IPCresolveTitleLanguageName()返回 UI 语言的本地化原生名称native name供标题提示词使用未持久化语言时返回undefined此时标题提示词会自动检测对话语言而不是被强制为英文。会话标题语言的解析路径从 packages/server-core/src/sessions/SessionManager.ts 可以看到标题生成generateTitle/refreshTitle通过resolveTitleLanguageName读取持久化的语言import { getPersistedUiLanguage, resolveTitleLanguageName } from craft-agent/shared/config注释明确说明会话标题语言解析必须依赖磁盘上的uiLanguage而不是i18n.resolvedLanguage——因为主进程 i18n 在启动早期异步水合若标题提前生成仍可能读到en兜底值即 issue #885 描述的场景。选择resolveTitleLanguageName而非i18n.resolvedLanguage本质上是把「语言事实来源」从易变的内存状态迁移到了稳定的磁盘状态。测试验证仓库为本次修复提供了两条独立的测试证据链apps/electron/src/main/tests/i18n-bootstrap.test.ts验证「preferences.json中有uiLanguage: hu时主进程i18n.resolvedLanguage在水合后为hu」同时验证无持久化值时主进程停留在en兜底、非法值如xx被忽略返回undefinedpackages/shared/src/config/tests/preferences-ui-language.test.ts覆盖setPersistedUiLanguage/getPersistedUiLanguage的完整读写、校验与幂等行为。文本选择高亮在预览滚动时保持对齐变更内容在可滚动的markdown-preview块max-h-[400px] overflow-auto包装容器内选中文本并追加追问后原有的黄色区间高亮及其编号角标会锚定在原始坐标上随着块内滚动与文本错位。修复方式是注册一个捕获阶段capture-phase的滚动监听器任何嵌套滚动发生时都重新计算覆盖层overlay几何位置并通过requestAnimationFrame合并的「仅坐标」快速路径避免高频重排当不存在注解时走 no-op 短路分支零开销跳过。该修复同时镜像到 viewer 的注解路径。实现要点从修复描述可以提炼三个关键设计捕获阶段监听确保在滚动目标元素自身处理滚动之前就能重算覆盖层避免时序竞争requestAnimationFrame 合并滚动事件高频触发时将多次坐标更新合并到同一帧降低主线程压力no-op 短路无注解时不执行任何计算保证对普通 Markdown 阅读场景零性能影响。Breaking Changes平台策略与配置格式的两次「断舍离」macOS 仅保留 Apple SiliconIntel (x64) 构建终止从 v0.10.1 起Craft Agents 的 macOS 版本仅发布 Apple Silicon (arm64) 构建Intel 版 Mac 不再受支持x64.dmg不再产出v0.10.0 是最后一个包含 Intel 构建的版本。Apple SiliconM 系列Mac、Windows 与 Linux 不受影响。需要留意的是当前仓库 apps/electron/electron-builder.yml 中 macOStarget仍列有arm64与x64两种架构这反映了仓库后续版本的演进状态而 v0.10.1 发布说明记录的是该版本当时的实际交付策略——以版本发布说明为准。如果你的 CI 或本地脚本仍在解析.dmg的架构命名如Craft-Agents-x64.dmg需要按此变更调整。旧的language偏好字段移除迁移到受控uiLanguage这是与前述 i18n 修复配套的破坏性变更preferences.json中原先的自由文本、用户可编辑language字段被内部受控的uiLanguage字段取代后者只能由「设置 → 外观」驱动旧配置无需用户操作配置 schema 采用 passthrough透传模式容忍未知字段且读取时会将残留的language键直接清除scrub避免其泄漏回下一次写入工具接口变更update_user_preferences工具不再接受language参数。源码级佐证读取时清除旧字段的逻辑在 packages/shared/src/config/preferences.ts 的loadPreferences()const raw readJsonFileSyncUserPreferences { language?: unknown }(PREFERENCES_FILE); // Scrub legacy free-text language field on read so it never leaks // back into a write. Old values were free-text (Hungarian, English) — // not language codes — so we drop them rather than migrate. if (raw typeof raw object language in raw) { delete (raw as { language?: unknown }).language; }Schema 校验在 packages/shared/src/config/validators.tsuiLanguage使用枚举约束并注明「内部字段、非用户可编辑」// Internal: mirrors Appearance → Language. Not user-editable. // Validated against the registry-derived supported set. uiLanguage: z.enum([...SUPPORTED_LANGUAGE_CODES] as [LanguageCode, ...LanguageCode[]]).optional(),支持的语言码集合由 packages/shared/src/i18n/languages.ts 中的SUPPORTED_LANGUAGE_CODES从 locale registry 派生保证了校验集合与实际语言包始终一致。update_user_preferences一侧的变更可见 packages/session-tools-core/src/handlers/update-preferences.ts其注释与对应测试update-preferences.test.ts均明确uiLanguage是内部字段工具调用传入该参数会被忽略。升级影响面与验证建议针对 v0.10.1建议按以下清单核对你的使用场景模型配置若你此前手动选择了 Opus 4.6升级后会自动落到 Opus 4.8若依赖 Bedrock 通道确认推理配置 ID 包含 Opus 4.8 映射见 packages/shared/src/config/models.ts 的BEDROCK_TO_BARE界面语言升级后首次启动界面语言会自动同步到主进程会话标题语言应保持与「设置 → 外观」一致且跨重启稳定。若仍有英文标题可检查~/.craft-agent/preferences.json中是否存在有效的uiLanguage字段如zh-Hans以及主进程启动日志是否完成水合平台Intel Mac 用户不应再安装 v0.10.1 及后续版本的 macOS 构建可停留在 v0.10.0 或迁移到 Apple Silicon 设备自动化工具若你的 Agent 工作流调用过update_user_preferences并传入language参数该参数现已失效需要移除。小结v0.10.1 是一次典型的「默认值迁移 体验修复」版本模型侧完成了 Opus 4.8 的默认化与旧型号迁移i18n 侧通过引入磁盘持久化的受控uiLanguage字段根治了主进程语言割裂问题渲染层修复了预览滚动时的选择高亮错位同时以两项 Breaking Changes 明确了平台边界与配置纪律。对于想深入了解实现细节的读者推荐按以下路径继续阅读源码模型注册与迁移packages/shared/src/config/models.ts语言偏好持久化packages/shared/src/config/preferences.ts主进程 i18n 水合与 IPCapps/electron/src/main/index.ts水合行为测试apps/electron/src/main/tests/i18n-bootstrap.test.ts偏好字段校验packages/shared/src/config/validators.ts会话标题语言解析packages/server-core/src/sessions/SessionManager.ts构建平台配置apps/electron/electron-builder.yml【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
