企业官网建设流程全解析

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 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, },

关键字段解析：

• id（claude-sonnet-5）：全局唯一的模型标识符，供 API 调用、配置持久化与 Bedrock 映射使用；
• name/shortName：完整显示名Sonnet 5与紧凑显示名Sonnet，后者用于模型选择器等紧凑 UI 场景。测试 packages/shared/tests/models.test.ts 验证了getModelShortName('claude-sonnet-5')返回'Sonnet'；
• descriptionKey（model.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：

从description可以看出梯队策略：Sonnet 5 定位为"主 Sonnet"，Sonnet 4.6 被标记为"上一代 Sonnet"（Previous 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 / Global

3.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 反解为裸 ID（bare ID），normalizeDeprecatedModelId()则处理历史遗留 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')

由此可以确认：应用内部统一使用裸 ID（claude-sonnet-5）作为配置与存储格式，仅在发起 Bedrock 请求时按选定区域前缀转换为对应 inference profile ID，同一模型可在不迁移数据的情况下切换区域。

四、连接默认值：Sonnet 5 进入首选梯队，默认模型仍为 Opus 4.8

4.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.197

5.1 版本与对齐目标

release notes 记录捆绑的 Claude Agent SDK 从 0.3.170 升级到0.3.197，达到Claude Code v2.1.197 的对等性（parity）。仓库中两个 package.json 确认了实际锁定版本：

• packages/core/package.json：

  "@anthropic-ai/claude-agent-sdk": "0.3.197"

• packages/shared/package.json：

  "@anthropic-ai/claude-agent-sdk": "0.3.197"

5.2 升级带来的三层收益

从 release notes 与源码结构可以归纳出这次 SDK 升级的三层价值：

1. Sonnet 5 的 CLI 侧感知：内置 CLI 自身即认识sonnet别名、上下文窗口与 effort（思考力度）默认值，确保通过 Claude Agent SDK 派生的子进程行为与模型能力一致，无需应用层额外硬编码；
2. 上游修复：包含自 0.3.170 以来的上游修复，其中明确提到Windows 平台 CLI 子进程控制台闪烁（console-flash）问题的修复，对 Windows 桌面端用户是实质体验改进；
3. 质量门槛：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 升级后如何验证

可以从三个层面验证升级是否正确落地：

1. 模型选择器：在模型选择器中应能看到Sonnet 5（短名 Sonnet），并可与Sonnet 4.6区分；
2. SDK 版本：检查node_modules/@anthropic-ai/claude-agent-sdk/package.json的版本号，应与 packages/shared/package.json 中的0.3.197一致；
3. 区域路由：若使用 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.ts：Bedrock 区域 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