Ch15 AI Provider、配置与密钥边界

Alembic 可以使用 AI，但 AI 配置不是所有仓库都拥有的能力。主 Alembic resident service 和 @alembic/agent 负责 provider-backed jobs；Codex 插件的 host-agent 路径可以利用 Codex 宿主本身，不要求插件保存第三方 API key；Dashboard 只是显示和配置入口之一。

本章讲 AI provider、配置来源、fallback、embedding 和密钥边界。目的不是列所有环境变量，而是让读者知道哪一层可以读取什么、哪一层不应该保存什么。

源码锚点：Alembic/lib/cli/AiScanService.ts、Alembic/lib/injection/modules/AiModule.ts、AlembicAgent/src/ai/AiFactory.ts、AlembicPlugin/lib/host-runtime/mcp/public-tools/contract.ts。

本章回答

• Alembic 的 AI provider 在哪里创建。
• CLI、workspace settings、environment variables 如何影响 provider。
• Codex Plugin 为什么不应拥有 resident provider 配置。
• Dashboard AI 配置 UI 的边界是什么。

主 AI 配置入口

主 CLI 提供 alembic ai status、alembic ai configure、alembic ai import-env。这些命令围绕 WorkspaceSettingsStore 工作，把 provider、model、API key、proxy、reasoning effort、embedding provider/model/base URL/key 等配置写入工作区 settings/secrets 或从环境变量导入。

ai status 会展示有效来源和 readiness。ai configure 用命令参数或 stdin 写入配置。import-env 把当前 shell 显式设置的 Alembic AI 环境变量导入工作区配置。

这条路径属于主 Alembic resident service，不属于 Codex 插件。

Agent AiFactory 创建 provider

@alembic/agent 的 AiFactory 支持 google/gemini、openai、deepseek、claude/anthropic、ollama。它可以按 ALEMBIC_AI_PROVIDER 显式选择，也可以根据 key 自动探测。若 provider 因地理限制或 provider 级错误不可用，还可以尝试 fallback provider。

它还支持独立 embedding provider：ALEMBIC_EMBED_PROVIDER、ALEMBIC_EMBED_MODEL、ALEMBIC_EMBED_BASE_URL、ALEMBIC_EMBED_API_KEY。这让生成模型和 embedding 模型可以分离。

这里的关键是：Provider 创建属于 Agent/主 resident job 的运行依赖。Core 不直接拥有 provider；Plugin 也不应该把 provider 配置写成自己的职责。

Resident job 与 host-agent path 的差别

当用户通过 Dashboard 或 CLI 启动 provider-backed bootstrap/rescan job 时，主 Alembic daemon 需要可用 AI provider。Job events、process artifacts、Agent runtime、tool calls 都在 resident service 中运行。

当用户通过 Codex 插件调用 host-agent alembic_bootstrap 或日常 public tools 时，Codex 自己是宿主 Agent。Plugin 可以返回 Mission Briefing、prime material 和 workflow refs，让 Codex 阅读和执行。这条路径不要求 Alembic resident provider key。

把这两条路径混淆，会导致错误的产品要求，例如要求 Codex 插件存第三方 AI key，或认为没有 resident AI provider 就不能做任何 Alembic 知识工作。

Plugin public contract 中的 host identity 只声明当前宿主，例如 codex 或 claude-code。它不等价于 AI provider 选择。Codex host-agent workflow 使用的是宿主已有的模型执行能力；Alembic resident provider 则由主 Alembic/Agent runtime 配置。

Dashboard 配置只是 UI 投影

Dashboard 中的 LLM config modal、AI chat、language preference、AI status 等功能通过 /api/v1/ai 与主后端交互。前端可以展示 readiness、发起保存、启动 chat/stream，但密钥存储和 provider 创建不在前端。

前端也不应该把 key 放进 localStorage 或长期可见状态。任何密钥处理都应走后端 settings/secrets contract。

配置来源优先级要可解释

AI 配置可能来自：

• 工作区 settings/secrets。
• 当前进程环境变量。
• CLI 显式参数。
• provider 默认值。
• Dashboard 后端配置接口。

状态输出必须说明来源。用户排查 provider 不可用时，第一步不是猜模型，而是看 effective provider、model、key 是否存在、config source 是哪里、是否触发 fallback、embedding 是否单独配置。

日志与错误分类

Provider 失败需要清楚分类：缺 key、未知 provider、provider probe 失败、地理限制、permission denied、rate limit/quota、网络错误、模型不可用。AiFactory 中的 geo/provider error 判断就是为了避免把不可恢复问题当普通重试。

日志不能泄露 API key。状态和 Dashboard 应展示 masked config 或 readiness，而不是原始 secret。

本章小结

Alembic 的 AI 配置属于主 resident service 和 Agent runtime 的运行边界。CLI 和 Dashboard 可以配置或展示它，Agent AiFactory 负责创建 provider 和 fallback，Core 不拥有 provider，Codex Plugin 的 host-agent 路径也不需要保存 resident provider key。

这条边界让 Alembic 同时支持本地 provider-backed jobs 和 Codex host-agent workflows，而不把密钥责任扩散到每个仓库。