Craft Agents v0.10.5 升级指南Claude Sonnet 5 接入与 Claude Agent SDK 0.3.197 全面解析【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss导读本文基于 Craft Agents 开源仓库的 v0.10.5 发布说明apps/electron/resources/release-notes/0.10.5.md深入拆解本次版本的核心变更Anthropic 新一代 Sonnet 模型claude-sonnet-5的接入方式、1M 上下文窗口与 Bedrock 多区域推理路由的实现细节以及捆绑 Claude Agent SDK 从 0.3.170 到 0.3.197 的升级影响。读完本文你将理解该版本在模型注册表、连接默认值、SDK 对齐三个层面的完整改动并能从源码级证据掌握验证与升级方法。一、版本概览一次聚焦模型能力的增量发布v0.10.5 是 Craft Agents 的一次聚焦型增量发布全部变更围绕Claude Sonnet 5展开无 Bug 修复、无破坏性变更Breaking Changes: None。核心变更可归纳为下表变更维度内容影响范围新增模型claude-sonnet-52026-06-30 发布进入模型选择器模型注册表、选择器 UI上下文窗口1M token较 Sonnet 4.6 的 200K 提升 5 倍长文档、大仓库处理能力思考能力支持自适应思考adaptive thinking推理任务模型梯队Sonnet 5 成为主 SonnetSonnet 4.6 保留为上一代模型列表排序Bedrock 路由US / EU / Global 三区域 inference profile 全部接线Amazon Bedrock 连接连接默认值Anthropic 与 Bedrock 连接均加入 Sonnet 5 优先级新建连接默认选择默认模型保持不变Opus 4.8升级用户无感知SDK 升级Claude Agent SDK 0.3.170 → 0.3.197内置 CLI 能力与修复值得注意的设计取向默认模型未随新模型发布而切换这与仓库中连接默认值优先选择现代、稳定模型的既有策略一致确保升级路径平稳。二、Claude Sonnet 5 的源码级接入模型注册表与选择器2.1 注册表定义Craft Agents 以 packages/shared/src/config/models.ts 中的MODEL_REGISTRY作为所有模型的单一事实来源Single Source of Truth。Sonnet 5 的定义如下{ id: claude-sonnet-5, name: Sonnet 5, shortName: Sonnet, description: Best combination of speed and intelligence, descriptionKey: model.sonnetDesc, provider: anthropic, contextWindow: 1_000_000, },关键字段解析idclaude-sonnet-5全局唯一的模型标识符供 API 调用、配置持久化与 Bedrock 映射使用name/shortName完整显示名Sonnet 5与紧凑显示名Sonnet后者用于模型选择器等紧凑 UI 场景。测试 packages/shared/tests/models.test.ts 验证了getModelShortName(claude-sonnet-5)返回SonnetdescriptionKeymodel.sonnetDesc多语言描述文案的 i18n 翻译键UI 优先解析t(descriptionKey)未命中时回退到description字段contextWindow: 1_000_000即 1M token 上下文窗口与 release notes 描述一致supportsThinking未显式设置时默认true即支持思考/推理力度调节对应 release notes 中的adaptive thinking能力。2.2 与前代模型的定位差异对比同一注册表中的 Sonnet 4.6字段claude-sonnet-5claude-sonnet-4-6nameSonnet 5Sonnet 4.6shortNameSonnetSonnetdescriptionBest combination of speed and intelligencePrevious Sonnet generationcontextWindow1,000,000200,000从description可以看出梯队策略Sonnet 5 定位为主 SonnetSonnet 4.6 被标记为上一代 SonnetPrevious Sonnet generation两者共享model.sonnetDesc翻译键。上下文窗口从 200K 提升到 1M意味着同一会话可承载约 5 倍于前的上下文量对大型代码库分析、长文档审查类任务有直接收益。2.3 选择器与展示层的联动shortName相同意味着在模型选择器中两者都显示为 Sonnet但完整名称区分Sonnet 5与Sonnet 4.6。测试 packages/shared/tests/models.test.ts 明确验证了选择器的关键行为expect(getModelIdByShortName(Sonnet)).toBe(claude-sonnet-5); expect(getModelDisplayName(claude-sonnet-5)).toBe(Sonnet 5); expect(getModelContextWindow(claude-sonnet-5)).toBe(1_000_000);即按短名 Sonnet 解析时会命中新一代的claude-sonnet-5保证用户以短名切换模型时默认落到最新主力型号。三、Amazon Bedrock 多区域推理路由US / EU / Global3.1 三区域 Inference Profile 映射Sonnet 5 在 Bedrock 侧并非只接入单一入口而是完整覆盖 AWS 的三类区域级推理配置inference profile。映射定义在 packages/shared/src/config/models.ts 的BEDROCK_TO_BARE表中该表与 packages/shared/src/config/llm-connections.ts 中的BEDROCK_MODEL_MAP保持同步// US inference profile IDs (primary) us.anthropic.claude-sonnet-5: claude-sonnet-5, // EU inference profile IDs eu.anthropic.claude-sonnet-5: claude-sonnet-5, // Global inference profile IDs global.anthropic.claude-sonnet-5: claude-sonnet-5, // Base IDs (no region prefix) anthropic.claude-sonnet-5: claude-sonnet-5,命名规则解读us.anthropic.claude-sonnet-5美国区域推理配置主配置eu.anthropic.claude-sonnet-5欧盟区域推理配置面向数据驻留合规要求global.anthropic.claude-sonnet-5全球区域推理配置anthropic.claude-sonnet-5无区域前缀的基础 ID。bedrockToBareId()负责将 Bedrock 原生 ID 反解为裸 IDbare IDnormalizeDeprecatedModelId()则处理历史遗留 ID 的归一化。3.2 区域路由的行为验证packages/shared/src/config/tests/llm-connections.test.ts 中的专项测试完整覆盖了 Sonnet 5 的正反向映射expect(toBedrockNativeId(claude-sonnet-5)).toBe(us.anthropic.claude-sonnet-5) expect(toBedrockNativeId(claude-sonnet-5, eu)).toBe(eu.anthropic.claude-sonnet-5) expect(toBedrockNativeId(anthropic.claude-sonnet-5)).toBe(us.anthropic.claude-sonnet-5) expect(fromBedrockNativeId(us.anthropic.claude-sonnet-5)).toBe(claude-sonnet-5) expect(fromBedrockNativeId(eu.anthropic.claude-sonnet-5)).toBe(claude-sonnet-5) expect(fromBedrockNativeId(global.anthropic.claude-sonnet-5)).toBe(claude-sonnet-5)由此可以确认应用内部统一使用裸 IDclaude-sonnet-5作为配置与存储格式仅在发起 Bedrock 请求时按选定区域前缀转换为对应 inference profile ID同一模型可在不迁移数据的情况下切换区域。四、连接默认值Sonnet 5 进入首选梯队默认模型仍为 Opus 4.84.1 首选默认模型优先级在 packages/shared/src/config/llm-connections.ts 的PI_PREFERRED_DEFAULTS中claude-sonnet-5已加入 Anthropic 与 Amazon Bedrock 两个 provider 的首选顺序anthropic: [claude-opus-4-8, claude-opus-4-7, claude-fable-5, claude-sonnet-5, claude-sonnet-4-6, claude-haiku-4-5], amazon-bedrock: [claude-opus-4-8, claude-opus-4-7, claude-sonnet-5, claude-sonnet-4-6, claude-haiku-4-5],该表的作用机制见getDefaultModelsForConnection()Pi SDK 返回的模型列表是字母序的历史遗留模型可能排在最前此表通过优先级排序确保新建连接时getDefaultModelForConnection()能选中现代、稳定的模型。匹配逻辑同时处理直接匹配pi/{id}裸 ID与 Bedrock 反解匹配将us.anthropic.claude-sonnet-5反解为claude-sonnet-5后再比对注释中明确说明这是为了兼容 Bedrock 返回的pi/us.anthropic.claude-opus-4-8这类带前缀 ID。4.2 默认模型保持不变的工程考量尽管 Sonnet 5 进入首选梯队并排在第 4 位Anthropic与第 3 位Bedrock但claude-opus-4-8始终排在首位这正是 release notes 中默认模型不变Opus 4.8的实现基础。这种新模型可选、但不强制替换默认的策略避免了升级后用户会话行为突变。五、Claude Agent SDK 升级0.3.170 → 0.3.1975.1 版本与对齐目标release notes 记录捆绑的 Claude Agent SDK 从 0.3.170 升级到0.3.197达到Claude Code v2.1.197 的对等性parity。仓库中两个 package.json 确认了实际锁定版本packages/core/package.jsonanthropic-ai/claude-agent-sdk: 0.3.197packages/shared/package.jsonanthropic-ai/claude-agent-sdk: 0.3.1975.2 升级带来的三层收益从 release notes 与源码结构可以归纳出这次 SDK 升级的三层价值Sonnet 5 的 CLI 侧感知内置 CLI 自身即认识sonnet别名、上下文窗口与 effort思考力度默认值确保通过 Claude Agent SDK 派生的子进程行为与模型能力一致无需应用层额外硬编码上游修复包含自 0.3.170 以来的上游修复其中明确提到Windows 平台 CLI 子进程控制台闪烁console-flash问题的修复对 Windows 桌面端用户是实质体验改进质量门槛release notes 明确说明完整类型检查与共享测试套件全部通过Full typecheck and shared test suites pass clean升级经过验证而非盲目 bump。5.3 SDK 在架构中的位置从源码结构看Claude Agent SDK 位于 packages/shared/src/agent 模块中claude-agent.ts是默认的 Claude Agent 后端实现见 backend/factory.ts 中 ClaudeAgent (Anthropic) - Default, using anthropic-ai/claude-agent-sdk 的注释平台原生二进制由 backend/internal/runtime-resolver.ts 按平台解析claude-agent-sdk-darwin-${arch}、claude-agent-sdk-win32-${arch}、claude-agent-sdk-linux-${arch}。SDK 版本升级直接影响的是这一条默认推理链路。六、Release Notes 在应用中的分发机制理解 v0.10.5 的变更还需要知道这份文档本身是如何进入应用的。仓库中 packages/shared/src/release-notes/index.ts 负责 release notes 的完整生命周期6.1 加载与同步流程const CONFIG_DIR join(homedir(), .craft-agent); const RELEASE_NOTES_DIR join(CONFIG_DIR, release-notes);来源打包资源目录中的release-notes/*.md即本仓库的 apps/electron/resources/release-notes 目录找不到时回退到process.cwd()/resources/release-notes初始化initializeReleaseNotes()在应用启动时执行由 apps/electron/src/main/index.ts 调用将打包的 Markdown 同步到用户目录~/.craft-agent/release-notes/Docker/远程服务器场景未设置CRAFT_BUNDLED_ASSETS_ROOT同样可用版本解析parseVersion()直接从文件名取版本号如0.10.5.md→0.10.5排序与截断compareSemver()按语义化版本降序排列最新在前getReleaseNotesList()最多返回最近 10 条。6.2 渲染入口apps/electron/src/main/handlers/system.ts 通过getCombinedReleaseNotes()与getLatestReleaseVersion()向渲染进程提供数据getCombinedReleaseNotes()会将多条 notes 以---分隔合并为单一 Markdown若内容未以#开头则自动注入版本标题。也就是说你在应用关于/更新界面看到的 v0.10.5 说明正是由本仓库这份 Markdown 经过上述管线渲染出来的。七、升级与验证7.1 升级路径由于 v0.10.5 无破坏性变更Breaking Changes: None、无 Bug 修复已有用户升级后无需调整配置默认模型保持 Opus 4.8既有连接配置不受影响。新模型仅作为新增可选项出现在模型选择器中。7.2 升级后如何验证可以从三个层面验证升级是否正确落地模型选择器在模型选择器中应能看到Sonnet 5短名 Sonnet并可与Sonnet 4.6区分SDK 版本检查node_modules/anthropic-ai/claude-agent-sdk/package.json的版本号应与 packages/shared/package.json 中的0.3.197一致区域路由若使用 Amazon Bedrock 连接切换 US/EU/Global 推理区域后发起对话观察实际请求的 inference profile ID 前缀us./eu./global.。7.3 回归验证入口仓库提供了与本次变更直接相关的测试可作为回归验证依据packages/shared/tests/models.test.ts模型注册表、短名解析、显示名、上下文窗口1_000_000断言packages/shared/src/config/tests/llm-connections.test.tsBedrock 区域 ID 正反向映射测试。八、小结Craft Agents v0.10.5 是一次小而完整的模型能力发布在模型注册表层面新增claude-sonnet-5并赋予 1M 上下文窗口在 Bedrock 层面完整接线 US/EU/Global 三区域推理路由在连接层将 Sonnet 5 纳入首选默认梯队同时保持默认模型 Opus 4.8 不变在运行时层面将 Claude Agent SDK 升至 0.3.197达到 Claude Code v2.1.197 对等性并携带 Windows 子进程控制台修复。所有变更均有源码与测试佐证升级路径无破坏性是理解 Craft Agents 模型接入架构注册表 → 区域映射 → 连接默认值 → SDK 运行时的一个完整样例。【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考