> **系列文章**：从零实现一个通用智能体  
> **本篇主题**：模型请求、工具执行、结果回填与 turn 状态机  
> **代码版本**：mx-claw 0.1.1





## 开篇

模型只会生成文本。当它尝试修改文件、搜索代码或运行命令时，Agent 必须把这些意图转换成
受控动作，再把动作结果送回模型。一次请求可能因此经过多轮“模型响应 → 工具执行 → 工具
结果 → 下一轮模型响应”。

mx-claw 将这个过程实现为 `AgentCore.submitTurn()` 的异步事件流。方法返回的不是一段最终
文本，而是持续产生的 turn、message、tool、permission 和 usage 事件：

```ts
for await (const event of core.submitTurn(sessionId, input)) {
  render(event)
}
```

CLI、HTTP SSE 和 Web 都只是这一事件流的不同消费者。

## 进入循环前的约束

Query Loop 不允许直接启动。入口先确认三件事：

1. 已配置模型 Provider；
2. 当前会话没有本进程内的活跃 turn；
3. 当前进程成功取得跨进程会话租约。

核心判断如下：

```ts
if (this.#activeTurns.has(sessionId)) {
  throw new Error(`Session already has an active turn: ${sessionId}`)
}

const leased = await this.#store.acquireLease(
  sessionId,
  leaseOwner,
  this.#leaseTtlMs,
)
if (!leased) {
  throw new Error(`Session lease is held by another process: ${sessionId}`)
}
```

进程内集合阻止同一 Core 重叠执行，SQLite 租约阻止 CLI 与 Web 同时写一个会话。两层检查
对应两种并发范围，缺一不可。

租约不是一次性令牌。turn 执行期间会定时续租；续租失败意味着另一个执行者已经接管，当前
循环必须通过 `AbortSignal` 中止。

## Turn 的初始状态

取得租约后，会话进入 `running`，并产生 `turn.started` 事件。系统提示只在新会话首次执行
时写入：

```ts
if (messages.length === 0) {
  const systemMessage = {
    role: 'system',
    content: DEFAULT_SYSTEM_PROMPT,
  }
  await this.#store.appendMessage(sessionId, systemMessage)
  messages = [systemMessage]
}
```

Skill 索引和长期记忆也在这一阶段注入。两者只在新会话的首回合读取，之后不再随磁盘内容
实时变化。这个冻结规则让同一会话内的行为基准保持稳定。

用户消息在模型调用前落盘。即使 Provider 随后超时或断线，输入仍然保存在会话事实源中。

## 迭代预算

工具循环需要明确上限。mx-claw 的默认最大模型迭代次数是 8：

```ts
const maxIterations = Math.max(
  1,
  options.maxIterations ?? this.#defaultMaxIterations,
)

for (let iteration = 0; iteration < maxIterations; iteration += 1) {
  // 模型请求与工具执行
}

throw new Error(`Maximum agent iterations reached (${maxIterations})`)
```

达到上限被视为显式错误，不会返回一个语义模糊的“已完成”。这样可以区分两种情况：

- 模型不再请求工具，任务自然完成；
- Agent 仍在循环，但预算已经耗尽。

## 接收流式响应

Provider 通信层把 OpenAI-compatible 流转换成结构化事件。Query Loop 分别处理三类数据：

| 事件 | 处理方式 |
|---|---|
| `text.delta` | 立即产生 `message.delta`，供界面流式显示 |
| `tool_call.completed` | 收集完整工具调用，等待流结束后统一处理 |
| `usage` | 累加输入、输出和缓存 token，并计算预估成本 |

文本增量只影响界面，完整 assistant 消息在流结束后写入一次。工具是否存在以结构化
`tool_call.completed` 为准，而不是依赖 `finishReason` 的文本值。

```ts
if (chunk.type === 'text.delta') {
  assistantTextParts.push(chunk.text)
  yield await this.#createEvent(sessionId, turnId, {
    type: 'message.delta',
    messageId: assistantMessageId,
    delta: chunk.text,
  })
}
```

流结束后，文本和 tool calls 被组装成一个 assistant 消息，先持久化，再决定是否继续执行。

## 没有工具调用时

当本轮只有文本、没有工具调用，Query Loop 将会话状态改为 `idle`，保存会话，然后执行两类
后置观察：

- 从用户文本中识别显式记忆请求；
- 从成功工具轨迹中观察是否形成可复用工作流。

两类学习都只生成候选，失败也不会把已经完成的主任务改成失败。最后产生
`turn.completed` 事件并返回。

## 多个工具调用

模型可能在一个响应中返回多个工具调用。执行策略取决于工具风险：

- 全部是只读、并发安全且参数有效的工具时，可以并行执行；
- 包含写文件、命令或任何非并发安全工具时，整批调用按协议顺序串行执行。

并行资格判断如下：

```ts
if (!tool?.concurrencySafe || tool.risk !== 'read') {
  return null
}
```

并行只减少独立读取的等待时间，不改变安全边界。写操作仍保持严格顺序，避免两个工具基于
同一个旧文件内容做覆盖。

## 单个工具调用的生命周期

每个工具调用依次经过：

1. 查找工具；
2. 检查重复调用；
3. 解析 JSON 参数；
4. 执行 Zod schema 校验；
5. 生成人类可读摘要；
6. 运行 PreToolUse Hook；
7. 执行权限决策；
8. 发出 `tool.started`；
9. 执行工具；
10. 运行 PostToolUse Hook；
11. 写入 `tool.completed` 和对应 tool result。

schema 校验发生在权限判断之前。非法参数不会生成无意义的审批弹窗，也不会接触文件系统。

工具执行失败不会被直接抛给 UI。异常被转换为模型可以读取的 tool result：

```text
Tool failed: <reason>
```

这样模型可以修正参数、换一个工具或停止，而不是让整个会话因为一次工具错误失去恢复机会。

## 重复调用保护

相同工具与相同参数在同一个 turn 中第二次出现时，不会再次执行：

```ts
const duplicateKey = `${toolCall.name}\u0000${toolCall.arguments}`
if (seenToolCalls.has(duplicateKey)) {
  return 'Duplicate tool call rejected; use the previous result instead.'
}
```

该检查主要处理模型陷入重复动作的情况。读操作重复执行只是浪费上下文，写操作和命令重复
执行则可能产生真实副作用。

## 工具结果必须闭合

OpenAI-compatible API 要求每个 assistant tool call 都有对应 tool result。进程崩溃、
消费者中止或 Provider 异常都可能留下不完整历史。

下一轮请求前，`repairToolCallTranscript()` 会：

- 删除不属于当前工具段的孤立 tool result；
- 移除重复 tool result；
- 按原始 tool call 顺序补齐中断结果；
- 保留仍然有效的 assistant/tool 配对。

补齐内容明确说明执行被中断：

```text
Tool execution was interrupted before a result was recorded.
This call must be retried if still needed.
```

修复只作用于 Provider 请求视图，原始 transcript 仍然保留。

## 取消与失败

取消信号会在三个位置检查：

- 进入 turn 前；
- 每次迭代开始前；
- 流事件和工具执行过程中。

任何未恢复异常都会把会话设为 `failed`，清理待审批请求并释放租约。消费者提前停止迭代时，
`finally` 同样执行清理。

```ts
finally {
  this.#activeTurns.delete(sessionId)
  clearInterval(leaseHeartbeat)
  await this.#store.releaseLease(sessionId, leaseOwner)
}
```

这种处理保证“界面已断开”不会留下一个继续执行的后台 turn，也不会让租约永久占用会话。

## 小结

Query Loop 的核心不是 `while`，而是四个边界：

- 单会话单写者；
- 每个工具调用都有闭合结果；
- 只读调用可以并行，有副作用的调用必须串行；
- 自然完成、预算耗尽、取消和异常拥有不同的显式状态。

下一篇解释上下文管理：完整历史已经保存在 SQLite 中，模型请求为什么仍然需要压缩。

从零实现一个通用智能体（三）：Query Loop

> **系列文章**：从零实现一个通用智能体  
> **本篇主题**：`/model` 命令、Provider 配置、模型选择与 API Key 存储  
> **代码版本**：mx-claw 模型管理模块当前实现

| 项目 | 内容 |
|---|---|
| 文章类型 | 工程实现笔记 |
| 涉及模块 | `apps/cli/src/commands/model`、`packages/model-provider` |
| 关键技术 | Commander、Inquirer、TypeScript、OpenAI-compatible API、Keychain、AES-GCM |
| 阅读重点 | Provider 与模型的关系、会话级切换、API Key 安全存储 |







## 1. 背景与目标

这篇文章记录 mx-claw `/model` 命令的完整实现。内容从命令目录和数据模型开始，依次介绍
Provider 配置流程、全局默认模型、会话临时切换、动态模型发现和配置文件写入，最后重点
说明 API Key 为什么不能进入普通配置，以及系统 Keychain、外部 Secret Source 和 AES-GCM
文件回退如何衔接。

做 coding agent 到模型配置这一步，问题会突然变具体。

### 1.1 一个命令背后的四层状态

表面上 `/model` 只是让用户选个模型，但真正写起来，它至少牵扯四件事：

1. Provider 的 Base URL、认证方式和连接状态；
2. 一个 Provider 下可能有多个模型名称；
3. 哪个模型是全局默认，哪个模型只对当前会话生效；
4. API Key 到底放在哪里，怎么读，怎么写，怎么保证不进入日志和配置文件。


### 1.2 本篇范围

文章会沿着 mx-claw 当前的真实实现，从命令目录一直走到 `/models` 请求和 Secret Store。

本篇包括模型选择、Provider 切换、临时模型切换、模型发现，以及API Key存储。

## 2. 命令架构

### 2.1 命令目录

`/model` 不是一个几百行的文件，而是拆成：

```text
apps/cli/src/commands/model/
  index.ts               命令入口
  handler.ts             子命令分发
  interactive.ts         交互向导和临时切换
  provider-selection.ts  Provider/模型菜单数据
  session.ts             配置变化后的会话同步
  __tests__/
    handler.test.ts
```

### 2.2 命令入口

`index.ts` 只做一层上下文适配：

```ts
async execute(context) {
  if (!context.model) {
    writeLine(context.output, 'Model configuration is unavailable in this runtime.')
    return 'continue'
  }

  await handleModelCommand({
    args: context.args,
    confirm: context.prompts.confirm,
    core: context.core,
    discoverModels: discoverProviderModels,
    output: context.output,
    provider: context.model.provider,
    prompt: context.prompts.prompt,
    readSecret: context.prompts.readSecret,
    selectModel: context.prompts.selectModel,
    selectProviderModel: context.prompts.selectProviderModel,
    selectProvider: context.prompts.selectProvider,
    session: context.session,
    store: context.model.store,
  })
  return 'continue'
}
```

这一层不解析参数，也不写交互流程。它只负责把 REPL、Inquirer、AgentCore 和配置服务接到一起。

### 2.3 子命令分发

真正的命令分发在 `handler.ts`：

```text
/model                        配置 Provider，并选择默认模型
/model configure [provider]   显式配置 Provider
/model switch                 在当前 Provider 内临时换模型
/model default ...            修改全局默认模型
/model status                 查看状态
/model list                   查看全部模型
/model refresh [provider]     从 /models 发现模型
```

这样拆之后，命令、交互、会话同步和持久化不会搅在一起。

## 3. 数据模型设计

### 3.1 Provider 与模型分离

一开始我只有一个 `model` 字段，后来发现这个数据结构不够用。

同一个 Provider 下面经常有多个模型，比如 DeepSeek 的 `deepseek-flash` 和
`deepseek-v4-pro`。用户切换这两个模型时，不应该重新配置 API Key，也不应该重新填
Base URL。

所以 `ProviderConfig` 现在长这样：

```ts
export interface ProviderConfig {
  name: string
  kind: 'builtin' | 'custom'
  baseURL: string
  model: string
  models: string[]
  apiKey: string
  requiresApiKey: boolean
  configured: boolean
}
```

字段含义要分清：

- `baseURL`：该 Provider 的 API 地址；
- `apiKey`：只在运行时内存中出现，写 `config.json` 时会被清空；
- `models`：用户配置的可用模型名称；
- `model`：该 Provider 当前的默认模型；
- `activeProvider`：全局配置里当前生效的 Provider。

完整配置是：

```ts
export interface ModelConfig {
  version: 1
  activeProvider: string
  providers: Record<string, ProviderConfig>
}
```

### 3.2 模型 ID

模型 ID 统一成：

```text
provider/model
```

例如：

```text
openai/gpt-4o
deepseek/deepseek-reasoner
ollama/qwen2.5-coder
```

Provider 负责连接信息，模型 ID 负责具体选择。这两件事分开后，模型切换就不用碰密钥和
Base URL。

## 4. Provider 优先的配置流程

### 4.1 交互流程

我中途把交互改过一次。

最初 `/model` 直接列出全部 `provider/model`，这在 Provider 少的时候没问题，但用户看到
的是：

```text
openai/gpt-4o-mini
openai/gpt-4o
deepseek/deepseek-chat
deepseek/deepseek-reasoner
ollama/llama3.2
```

问题是一个还没配置好的 DeepSeek 模型也会混在列表里。用户很难分清自己是在“配置
Provider”，还是在“临时换模型”。

最后我把两个动作拆开。

配置 Provider：

```text
/model
```

临时换模型：

```text
/model switch
```

`/model` 的流程是：

```text
选择 Provider
  -> Base URL
  -> 模型名称列表
  -> API Key
  -> 选择默认模型
  -> 保存并生效
```

实际交互大概是这样：

```text
? Select a model provider
❯ openai
  deepseek
  ollama

Base URL [https://api.openai.com/v1]
Model names, comma-separated [gpt-4o-mini, gpt-4o]
API Key for openai (input hidden):
? Select the default model
❯ gpt-4o-mini
  gpt-4o
```

也可以绕过菜单：

```text
/model configure deepseek
```

对已经配置过的 Provider，第二次修改会先确认是否覆盖。对没配置的 Provider，不会弹
覆盖确认。

配置成功后会同时修改：

- `activeProvider`；
- 该 Provider 的 `model`；
- 当前会话模型。

但不会删除其他 Provider。`openai`、`deepseek`、`ollama` 各自保留自己的 Base URL、
模型列表和密钥。

### 4.2 一次性保存

这部分逻辑在 `configureInteractively()` 里。关键是“先把所有输入收完，再一次性保存”：

```ts
const updated = await options.store.configureProvider(
  selected,
  {
    apiKey,
    baseURL,
    model: defaultModel,
    models,
  },
  overwrite,
)
```

不要在填 Base URL 时保存一次，填模型时再保存一次，最后填 Key 又保存一次。中途取消会
留下半配置状态，后面很难判断 Provider 到底可用不可用。

## 5. 全局默认与会话切换

### 5.1 两层模型状态

这里有个很容易混掉的状态：

```text
config.activeProvider + provider.model  // 全局默认
session.model                           // 当前会话实际模型
```

我一开始让所有切换都写配置，结果用户只是临时想换个模型，下一次启动却被永久改了默认值。

### 5.2 临时切换实现

现在的规则是：

```text
/model switch
/model gpt-4o
/model use openai gpt-4o
```

只修改当前会话。

修改全局默认要用：

```text
/model default openai/gpt-4o
```

`switchModel()` 里通过 `persist` 参数区分：

```ts
if (persist) {
  const updated = await options.store.selectProvider(providerName, modelName)
  syncSessionModel(options.core, options.provider, updated, options.session.sessionId)
  writeLine(options.output, `Default model: ${providerName}/${modelName}`)
  return
}

options.provider.setConfig(config)
options.core.selectModel(options.session.sessionId, `${providerName}/${modelName}`)
```

临时切换也不会改 Provider：

```ts
if (!persist && providerName !== config.activeProvider) {
  throw new Error(
    `Temporary model switch cannot change provider ` +
      `(${config.activeProvider} -> ${providerName}). ` +
      `Use /model default to change the default provider.`,
  )
}
```

这看起来有点“限制用户”，但状态更清楚。换 Provider 和换模型本来就是两个动作。

### 5.3 current 标记的 bug

`/model switch` 菜单会给当前模型加标记：

```text
❯ deepseek-v4-pro · current
  deepseek-flash
```

第一版就有个 bug。

我先临时切到 `deepseek-v4-pro`，再次打开 `/model switch`，current 还标在
`deepseek-flash`。原因是当时 current 取的是：

```ts
config.providers[config.activeProvider].model
```

这是全局默认，不是当前会话模型。

修复后优先读 `session.model`：

```ts
// 临时切换只改 session.model；再次打开菜单时必须优先标记会话中的实际模型。
const current = modelOptions.some((option) => option.value === options.session.model)
  ? options.session.model
  : defaultModel
```


## 6. 模型来源与动态发现

当前模型目录有三路来源：

```text
内置推荐模型
  + 用户手动添加
  + Provider /models 动态发现
```

### 6.1 内置模型

内置名称写在 `defaultModelConfig()`：

```ts
{
    version: 1,
    activeProvider: "deepseek",
    providers: {
      openai: {
        name: "openai",
        kind: "builtin",
        baseURL: "https://api.openai.com/v1",
        model: "gpt-4o-mini",
        models: ["gpt-4o-mini", "gpt-4o"],
        apiKey: "",
        requiresApiKey: true,
        configured: false,
      },
      deepseek: {
        name: "deepseek",
        kind: "builtin",
        baseURL: "https://api.deepseek.com",
        model: "deepseek-flash",
        models: ["deepseek-flash", "deepseek-v4-pro"],
        apiKey: "",
        requiresApiKey: true,
        configured: false,
      },
      ollama: {
        name: "ollama",
        kind: "builtin",
        baseURL: "http://127.0.0.1:11434/v1",
        model: "llama3.2",
        models: ["qwen2.5-coder", "deepseek-r1"],
        apiKey: "",
        requiresApiKey: false,
        configured: false,
      },
    },
}
```

内置目录保证离线也能使用，不至于打开 `/model` 先等一次网络请求。

### 6.2 用户模型

用户也可以手动加：

```text
/model add-model openai gpt-custom
```

### 6.3 `/models` 动态发现

动态发现走 OpenAI-compatible 的 `/models`：

```ts
export async function discoverProviderModels(provider, options = {}) {
  const fetchImpl = options.fetchImpl ?? fetch
  const headers = { accept: 'application/json' }

  if (provider.apiKey) {
    headers.authorization = `Bearer ${provider.apiKey}`
  }

  const response = await fetchImpl(`${provider.baseURL}/models`, {
    headers,
    method: 'GET',
  })

  if (!response.ok) {
    const detail = (await response.text()).slice(0, 1_000)
    throw new Error(`Model discovery failed (${response.status}): ${detail}`)
  }

  return extractModelNames(await response.json())
}
```

刷新结果会合并，而不是覆盖：

```text
/model refresh deepseek
```

这样内置模型、用户手动模型和 API 返回模型可以同时存在。

不过动态发现也要注意，`/models` 返回的是当前 Base URL 和 API Key 对应服务真正公开的
模型。账号页面、第三方控制台、网关别名和 API 模型 ID 可能不是同一个东西。

## 7. 配置持久化

### 7.1 进程内快照

默认路径：

```text
~/.mx-claw/config.json
```

可以用 `MX_CLAW_HOME` 改目录。CLI 第一次 `load()` 后会把配置放进进程快照：

```ts
async load(): Promise<ModelConfig> {
  if (this.#config) {
    return cloneConfig(this.#config)
  }

  // 读取 config.json，查询 Secret Store，然后保存快照
}
```

这样做有两个结果：

- CLI 内修改配置，调用 `save()` 后立刻更新快照，当前会话马上生效；
- 手动修改 `config.json`，当前进程不会自动重读，需要重新打开 CLI。


### 7.2 原子写入

写配置时用临时文件加原子替换，权限固定成 `0600`：

```ts
await writeFile(temporaryPath, `${JSON.stringify(sanitizedConfig, null, 2)}\n`, {
  encoding: 'utf8',
  mode: 0o600,
})
await rename(temporaryPath, this.configPath)
await chmod(this.configPath, 0o600)
```

配置里只保存 Provider 元数据。真正写盘前，`apiKey` 会被清掉：

```ts
const sanitizedConfig = {
  ...config,
  providers: Object.fromEntries(
    Object.entries(config.providers).map(([name, provider]) => [
      name,
      { ...provider, apiKey: '' },
    ]),
  ),
}
```


## 8. API Key 安全边界

### 8.1 为什么不能写进 config.json

把 API Key 写进 `config.json` 最省事，但问题也很直接：

```json
{
  "apiKey": "sk-..."
}
```

用户发个 issue、贴个配置、备份目录、同步到网盘，Key 就出去了。

### 8.2 配置与密钥分离

就算文件是 `0600`，也不能把它当普通配置。配置需要被读取、修改、分享，密钥不应该进入
这个生命周期。

```text
config.json        Provider、Base URL、模型名称、当前选择
Secret Store       API Key
日志              不记录 Key
终端输出          只显示 [configured]
```

`ProviderConfig` 在内存里仍然有 `apiKey`，因为发请求需要它。但它不是可持久化字段。

## 9. Secret Store

### 9.1 接口设计

我抽象了一个很小的接口：

```ts
export interface SecretReader {
  readonly backendName: string
  get(key: string): Promise<string | null>
}

export interface SecretStore extends SecretReader {
  set(key: string, value: string): Promise<void>
  delete(key: string): Promise<void>
}
```

### 9.2 分层顺序

默认读取顺序：

```text
外部只读 Secret Command
  -> macOS Keychain / Linux Secret Service
  -> AES-256-GCM 加密文件
```

写入顺序：

```text
系统安全存储
  -> 不可用时回退加密文件
```

这套顺序参考了 Hermes 的外部 Secret Source，并把系统安全存储放在本地文件之前。最终做成
了适合 mx-claw 的组合。

### 9.3 macOS Keychain

macOS 上默认用 Keychain。

service 名不是写死的 `mx-claw`，而是把 `MX_CLAW_HOME` 哈希进去：

```ts
const profileHash = createHash('sha256')
  .update(homeDir)
  .digest('hex')
  .slice(0, 12)

return `mx-claw-${profileHash}`
```

这样默认目录、测试目录和不同 profile 不会互相拿到对方的 Key。

account 名使用：

```text
provider:openai
provider:deepseek
provider:ollama
```

写入时不能直接把 Key 放进 `security add-generic-password -w ...`，因为进程参数可以被
其他进程看到。

我的做法是把 Key 转 hex，通过 `security -i` 的 stdin 写：

```ts
const hexValue = Buffer.from(value, 'utf8').toString('hex')
const command =
  `add-generic-password -U ` +
  `-a ${quoteSecurityArgument(key)} ` +
  `-s ${quoteSecurityArgument(this.#service)} ` +
  `-X "${hexValue}"\n`

const result = await this.#runner('/usr/bin/security', ['-i'], {
  input: command,
})
```

`security -i` 有大约 4 KiB 的行缓冲。超长内容不再改用 argv，而是直接判定安全后端不可用，
让上层回退到加密文件。为了兼容去牺牲密钥可见性，不划算。

### 9.4 Linux Secret Service

Linux 上尝试 `secret-tool`：

```ts
secret-tool store --label "mx-claw provider:openai" \
  service mx-claw-<hash> account provider:openai
```

读取：

```text
secret-tool lookup service <service> account <key>
```

删除：

```text
secret-tool clear service <service> account <key>
```

如果系统没装 `secret-tool`，或者 Secret Service 不可用，命令失败后回退到加密文件。

Windows 先用 AES 文件。

### 9.5 AES-GCM 文件回退

回退存储由两个文件组成：

```text
secrets.json   IV、GCM tag、密文
secrets.key    32 字节随机主密钥
```

两个文件都是 `0600`。

加密使用 `aes-256-gcm`，每次写入生成新的 12 字节 IV：

```ts
const key = await this.#readKey()
const iv = randomBytes(12)
const cipher = createCipheriv('aes-256-gcm', key, iv)

const encrypted = Buffer.concat([
  cipher.update(JSON.stringify(secrets), 'utf8'),
  cipher.final(),
])

const payload = {
  version: 1,
  iv: iv.toString('base64'),
  tag: cipher.getAuthTag().toString('base64'),
  data: encrypted.toString('base64'),
}
```

GCM 除了加密，还会校验数据是否被改过。解密时：

```ts
decipher.setAuthTag(Buffer.from(payload.tag, 'base64'))
```

密文文件也采用临时文件加 rename，避免写到一半留下损坏文件。

必须说清楚：这层方案防的是“磁盘上直接出现明文 Key”，不是防同用户恶意程序。只要能读
`secrets.key` 和 `secrets.json`，就能解密。它不能替代 OS Keychain。

### 9.6 外部 Secret Command

参考 Hermes 加了只读外部来源：

```bash
MX_CLAW_SECRET_COMMAND='vault read mx-claw' mx-claw
```

helper 会收到：

```text
MX_CLAW_SECRET_KEY=provider:openai
```

它可以只输出一个值：

```text
sk-...
```

也可以输出一组：

```text
provider:openai=sk-...
provider:deepseek=sk-...
```

实现时故意只给 helper 最小环境变量：

```ts
const env = { MX_CLAW_SECRET_KEY: key }
for (const name of ['PATH', 'HOME', 'USER', 'LOGNAME', 'TMPDIR', 'LANG', 'LC_ALL']) {
  if (process.env[name]) env[name] = process.env[name]
}
```

超时 3 秒，stdout 最多 1 MiB，stderr 捕获但不回显。helper 失败时按没有值处理。

外部来源是只读的。它提供 Key 后，本地 `set()` 不会把值再复制到 Keychain 或文件里。否则
用户以为自己在用 Vault，结果磁盘上又多了一份。

## 10. API Key 输入

向导里不能把 Key 作为普通 prompt 读。`readSecret()` 使用 raw mode，不显示字符：

```text
API Key for deepseek (input hidden):
```

粘贴快捷键仍然有效，只是没有回显。粘贴完直接回车。

输出里永远只显示：

```text
API Key: [configured]
```

不会打印前缀、末尾四位或长度。

旧的快捷命令仍然兼容：

```text
/model set openai api-key <key>
```

但更推荐：

```text
/model set openai api-key
```

后者不会让 Key 进入 shell history。

## 11. Provider 就绪判断

不是有 Base URL 就算配置完成。当前判断是：

```ts
export function isProviderReady(provider: ProviderConfig): boolean {
  return Boolean(
    provider.baseURL.trim() &&
      provider.model.trim() &&
      provider.models.length > 0 &&
      (!provider.requiresApiKey || provider.apiKey.trim()),
  )
}
```

OpenAI、DeepSeek 必须有 Key；Ollama 可以没有。

如果模型刷新时 Provider 还没就绪，会直接跳过：

```text
Refresh skipped: deepseek needs configuration
```

这一步很有必要。不发请求比发一个必然 401 的请求更清楚。

## 12. 错误和状态恢复

模型请求失败不应该把 CLI 一起带走。

REPL 捕获回合异常：

```text
Request failed: ...
The session is still active. Try again or type /help.
```

Agent Core 用 `try/finally` 恢复会话状态：

```ts
try {
  for await (const chunk of provider.stream(...)) {
    // 产生流式事件
  }
} finally {
  session.runtimeState = 'idle'
  session.updatedAt = now()
}
```

Provider 抛错、消费者提前退出，会话都不能卡在 `running`。

从零实现一个通用智能体（二）：model 命令与 API Key 存储

> **系列文章**：从零实现一个通用智能体  
> **本篇主题**：分层、状态所有权、执行链路与安全边界  
> **代码版本**：mx-claw 0.1.1




## 开篇

一次普通请求在 mx-claw 中会留下完整的执行轨迹：用户消息先写入 SQLite，模型以流式响应
返回文本或工具调用，Agent Core 校验工具参数、申请权限、执行工具并把结果交还模型，直到
模型不再请求工具或达到迭代上限。

这个过程同时涉及 CLI、Web、模型 Provider、文件系统、命令进程、权限规则、长期记忆和
Skill。只要状态没有单一归属，恢复、并发和审计很快就会互相冲突。mx-claw 的架构设计从
一开始就把不同状态放到不同层：

```text
交互入口 -> Agent Core -> 工具 / 模型 / 存储
                     \-> 权限 / Hook / 沙箱
```

本文先给出系统全景。后续文章分别深入 Query Loop、上下文、工具、沙箱、权限、记忆、
Skill、SQLite 和多客户端。

## 五个基础层

mx-claw 可以按职责拆成五层。

| 层次 | 当前实现 | 主要职责 |
|---|---|---|
| 入口层 | `apps/cli`、`apps/server`、`apps/web` | 接收输入、启动进程、连接本地 API |
| 交互层 | CLI REPL、Web 会话面板 | 展示流式消息、工具状态与审批 |
| 编排层 | `AgentCore`、`SessionStore` | 会话生命周期、恢复、事件与租约 |
| 核心循环层 | `AgentCore.submitTurn()` | 模型请求、工具调用、结果回填与迭代 |
| 执行与通信层 | `builtin-tools`、`model-provider` | 文件、搜索、编辑、命令和模型 API |

权限、Hook、沙箱、记忆和 Skill 不单独占用一个顺序层，而是横切到核心循环的不同节点：

```text
模型返回工具调用
  -> schema 校验
  -> PreToolUse Hook
  -> 权限规则与人工审批
  -> 工具二次校验
  -> 沙箱命令 / 工作区文件操作
  -> tool result
  -> PostToolUse Hook
  -> 模型下一轮
```

这些横切能力共同决定一次工具调用能否执行、如何执行，以及执行后留下什么证据。

## 代码地图

核心目录与职责如下：

```text
apps/
  cli/                 CLI 入口、REPL、命令和审批展示
  server/              本地 HTTP API、SSE 与 Web 静态资源
  web/                 React 面板、会话、工作区和设置
packages/
  agent-core/          会话编排、Query Loop、压缩与恢复
  protocol/            消息、事件、工具和权限协议
  model-provider/      OpenAI-compatible 通信与密钥配置
  builtin-tools/       文件、搜索、编辑、命令和沙箱适配
  permissions/         规则、模式、命令分类和审计
  hooks/               PreToolUse / PostToolUse
  storage/             SQLite、文件存储、租约、事件和检索
  memory/              USER.md、MEMORY.md 与候选审核
  skills/              Skill catalog、提案与自主学习
  mcp/                 MCP 工具客户端
  plugins/             可信插件目录
  lsp/                 只读代码诊断
  agent-tools/         Subagent 与 worktree 委托
```

`apps/cli` 与 `apps/server` 不实现第二套 Agent 逻辑。两者都实例化 `AgentCore`，并通过同一
套协议消费事件。差别只在交互形式和进程边界。

## 一次 Turn 的实际路径

一个 turn 从 `submitTurn()` 开始。入口先取得会话的跨进程租约，然后执行以下步骤：

1. 读取并修复已存储的工具调用历史。
2. 新会话注入 system prompt、Skill 索引和长期记忆快照。
3. 把用户消息写入会话事实源。
4. 在每次模型请求前检查上下文窗口。
5. 接收文本增量、工具调用和 usage 事件。
6. 把工具调用转换成结构化 tool result。
7. 将结果重新交给模型，进入下一轮。

循环退出有两种正常方式：

- 模型返回的响应不包含工具调用；
- 达到 `maxIterations` 后显式失败。

取消、租约丢失、Provider 异常和消费者提前停止都会进入失败恢复路径。会话不会停留在
一个没有执行者的 `running` 状态。

## 状态归属

架构能否恢复，取决于每类状态是否有明确归属。

| 状态 | 唯一归属 |
|---|---|
| 消息、事件、待审批请求、租约 | SQLite 会话库 |
| 当前进程内的活跃 turn 与等待器 | `AgentCore` 内存 |
| Provider 与默认模型 | `config.json` |
| API Key | 系统安全存储或加密文件 |
| 长期语义记忆 | `memory/` 下的 Markdown 记录 |
| 程序性 Skill | `skills/active/` |
| 权限规则与审计 | SQLite 权限表 |

CLI 与 Web 可以共享数据库和磁盘状态，但各自运行独立的 Core 实例。配置在进程启动后形成
快照；一个进程修改默认 Provider，不会自动改写另一个已运行进程的内存快照。

## 五条不变量

实现中的大部分复杂度都服务于五条不变量。

### 单会话单写者

同一会话在同一时刻只能有一个 turn 执行。进程内使用 `#activeTurns`，跨进程使用 SQLite
租约。失去租约的循环会立即中止。

### 工具调用必须有结果

每个 assistant `tool_call` 都必须得到对应 tool result，包括参数错误、未知工具、权限拒绝
和执行异常。缺少结果的历史在发送给 Provider 前会被修复。

### 完整事实与模型视图分离

SQLite 保存完整 transcript。上下文压缩只改变 Provider 本轮看到的视图，不删除历史消息，
也不改写原始工具结果。

### 上下文在明确边界冻结

Skill 索引和长期记忆在会话首回合注入。会话进行中新增的 Skill 或记忆只影响后续新会话，
避免同一任务中的行为基准不断漂移。

### 审批不是最终安全边界

批准只表示该动作允许进入执行路径。工作区路径限制、灾难命令黑名单、环境变量白名单和
平台沙箱仍然生效。`allow-all` 也不能越过显式 deny 和工具内部硬校验。

## 事件模型

Agent Core 不直接更新界面。它产生带 `sessionId`、`sequence` 和 `turnId` 的有序事件：

```ts
{
  type: 'tool.started',
  sequence: 42,
  sessionId: 'session-1',
  turnId: 'turn-1',
  timestamp: '2026-10-23T00:00:00.000Z'
}
```

CLI 将事件渲染成终端输出，HTTP 服务将事件转换成 SSE，Web 按 sequence 去重并恢复。
同一套事件协议使不同界面可以观察同一个执行过程。

## 系列导航

- 第 02 篇：`/model` 命令、Provider 与 API Key 存储
- 第 03 篇：Query Loop 与工具调用状态机
- 第 04 篇：上下文压缩与冻结上下文
- 第 05 篇：工具协议与工作区边界
- 第 06 篇：命令沙箱与资源限制
- 第 07 篇：权限模式、审批与 Hook
- 第 08 篇：长期记忆与候选审核
- 第 09 篇：Skill 自主学习与人工批准
- 第 10 篇：SQLite、租约、事件与检索
- 第 11 篇：CLI、Web 与多客户端状态同步

## 小结

mx-claw 的结构不是把模型、工具和界面塞进同一个对象，而是让每一层只拥有自己能够证明的
状态。Query Loop 决定下一步，工具层约束动作，存储层保存事实，权限与沙箱决定风险边界。

下一篇从 `/model` 命令开始，解释模型连接信息和密钥为什么不进入同一份配置。