> ## Documentation Index
> Fetch the complete documentation index at: https://agent.minimaxi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> 用 @minimax-ai/code-sdk 在 Node.js 中程序化驱动本机 MiniMax Code。

如果你已经在用 MiniMax Code CLI、编辑器集成或 Headless `mcode exec`，也可以通过 TypeScript SDK 在代码里控制它。

适合这些场景：

* 在 CI/CD 里自动修代码、跑审查或生成改动；
* 把 MiniMax Code 嵌进内部工具或你自己的 Agent；
* 用代码编排多轮 Session，而不是手写 `mcode exec` 管道。

SDK 通过本机 `mcode exec --output-format stream-json` 驱动 CLI：一次 `run()` / `runStreamed()` 对应一个 CLI 进程、一轮 Turn。当前是 Phase 1（`0.x`），API 在 `1.0` 前可能随次要版本调整。

相关页面：[Headless 与 CI](https://agent.minimaxi.com/docs/cli/automation.md)、[Python SDK](https://agent.minimaxi.com/docs/cli/sdk-python.md)。包页面：[npm `@minimax-ai/code-sdk`](https://www.npmjs.com/package/@minimax-ai/code-sdk)。

## 环境要求

| 组件 | 要求 |
| - | - |
| Node.js | `>=22.19 <23` 或 `>=24.2 <27` |
| MiniMax Code CLI（`mcode`） | `>=0.6.3`（`MIN_CLI_VERSION`） |
| 事件 `schemaVersion` | `1` |

SDK 与 CLI 分开发布。只要 CLI 满足最低版本，升级 SDK 不必同步升级 CLI。运行前需要已登录，或在数据目录里配置可用的 API Key Provider。

## 安装

```bash theme={null}
npm install @minimax-ai/code-sdk
npm install @minimax-ai/code   # 可选；全局安装的 mcode 也可以
```

`@minimax-ai/code` 是可选 peer dependency，安装时会跑原生依赖脚本。npm 11 对项目级安装会拒绝 `--allow-scripts`（`EALLOWSCRIPTS`），请先在项目 `package.json` 中批准：

```json theme={null}
{
  "allowScripts": {
    "@minimax-ai/code": true,
    "better-sqlite3": true
  }
}
```

## 快速开始

创建客户端、开启 Thread，并运行 prompt：

```ts theme={null}
import { MCode } from "@minimax-ai/code-sdk";

const mcode = new MCode({ dataDir: "/srv/mcode-data" });
const thread = mcode.startThread({
  cwd: "/path/to/repo",
  model: "minimax/MiniMax-M3",
  permission: "smart",
});

const turn = await thread.run("诊断并修复失败的 CI 任务", {
  files: ["./ci.log"],
  timeoutMs: 10 * 60_000,
});
console.log(thread.id, turn.finalResponse, turn.usage);

// 同一 Thread 继续下一轮
await thread.run("为这次修复补充单元测试");

// 用 Session id 恢复更早的对话
const resumed = mcode.resumeThread("mvs_xxx", { cwd: "/path/to/repo" });
await resumed.run("从上次停下的地方继续");
```

流式消费事件：

```ts theme={null}
const { events } = await thread.runStreamed("按计划实现改动");
for await (const event of events) {
  switch (event.type) {
    case "item.completed":
      console.log(event.item);
      break;
    case "turn.failed":
      console.error(event.status, event.error);
      break;
    default:
      // 新版 CLI 可能新增事件类型；SDK 会原样透传
      break;
  }
}
```

## CLI 查找顺序

SDK 不强制捆绑 CLI。查找顺序：

1. 构造参数 `bin`（可执行文件、JS 入口，或 `PATH` 上的命令名）；
2. 安装在 SDK 旁边的 `@minimax-ai/code`（可选 peer）；
3. `PATH` 上的 `mcode`。

`resolveFromCwd` 默认为 `false`。设为 `true` 后，还会在 SDK 本地安装之后、`PATH` 之前搜索宿主工作目录。工作目录不可信时（例如 CI 检出的 PR）请保持关闭，并传入 `bin`，或把 CLI 装在 SDK 旁边 / `PATH` 上。

每个 `MCode` 实例在首次运行前会执行一次 `mcode --version` 并缓存结果。低于 `0.6.3` 会抛出 `MCodeVersionError`。只比较 `major.minor.patch`，因此 `0.6.3-preview.N` 视为满足要求。

## `new MCode(options?)`

| 选项 | 说明 |
| - | - |
| `bin` | 显式指定 `mcode` 路径或命令名，跳过包与 `PATH` 查找 |
| `resolveFromCwd` | 是否额外从 `process.cwd()` 查找 CLI；默认 `false` |
| `dataDir` | 数据目录，传给 CLI 环境变量 `MINIMAX_DATA_DIR` |
| `env` | 子进程环境；**设置后会整体替换** `process.env`，默认使用 `process.env` |
| `configPath` | Runtime 配置文件，对应 `--config` |

`env` 不会与 `process.env` 合并。只传自定义变量会丢掉 `PATH`、`HOME` 等，可能导致 CLI 找不到 Node 或凭证。追加变量时请展开：

```ts theme={null}
const mcode = new MCode({ env: { ...process.env, FOO: "bar" } });
```

## Thread：`startThread` / `resumeThread`

Thread 选项会在该 Thread 的每一轮 Turn 传给 CLI：

| 选项 | CLI 参数 |
| - | - |
| `cwd` | `--cwd`（默认宿主进程工作目录） |
| `model` / `effort` | `--model` / `--effort` |
| `permission` | `--permission`：`smart` / `full` / `off` |
| `mode` | `--mode`：`standard` / `lightweight`；仅创建 Session 的那一轮生效 |
| `promptMode` | `--prompt-mode`：`tui` / `coding` / `work` |
| `systemPrompt` | `--system-prompt-file`（SDK 写入临时文件） |
| `appendSystemPrompt` | `--append-system-prompt-file`（SDK 写入临时文件） |

注意：

* `mode: "lightweight"` 只能用于新建 Thread；传给 `resumeThread` 会立即抛出 `MCodeInvocationError`；
* Headless 没有 `ask` 权限策略；`smart` / `full` / `off` 与 Codex 的 OS sandbox 模式不等价，SDK 不做映射；
* `thread.id` 在第一轮 Turn 发出首个事件后可用，即使该轮失败。

## `thread.run` / `thread.runStreamed`

| 选项 | 说明 |
| - | - |
| `files` | 附件，对应可重复的 `--file`；相对路径相对 `cwd` 解析 |
| `signal` | `AbortSignal`，用于取消 |
| `timeoutMs` | 传给 CLI 的 `--timeout <n>ms`；SDK 会在 `timeoutMs + 90s` 强制结束进程 |
| `maxSteps` | `--max-steps` |

行为要点：

* `run()` 仅在状态为 `succeeded` 时 resolve，返回 `Turn`（含 `finalResponse`、规范化后的 `items`、`usage`、`model`、`sessionId`、`turnId`、`durationMs` 和完整 `result`）；其他结果都会 reject；
* `runStreamed()` 原样产出 CLI 事件。`turn.failed` 是普通事件；只有进程或协议失败才会让迭代器抛错。中途 `break` 会取消本轮；
* 同一 Thread 同时只能跑一轮；并发调用抛出 `ThreadBusyError`，不会排队。

## 事件与 items

事件类型与 CLI 一致：`exec.started`、`session.started` / `session.resumed`、`turn.started`、`item.started` / `item.updated` / `item.completed`、`turn.completed`、`turn.failed`、`exec.completed`。每行 stdout 必须是 `schemaVersion === 1` 的 JSON，否则视为协议错误。

`Turn.items` 是 SDK 规范化后的结果：`agent_message`、`reasoning`、`tool_call`。按 `item.id` 合并，顺序为首次出现顺序；Turn 结束时仍未收到 `item.completed` 的项会标为 `incomplete: true`。

`usage.totalTokens = inputTokens + outputTokens`，**不包含** `cacheReadTokens` / `cacheWriteTokens`；`reasoningTokens` 可能与 `outputTokens` 重叠。

## 错误

所有错误都继承 `MCodeError`，并携带 `exitCode`、`signal` 以及 CLI stderr 末尾最多 64 KiB（`stderr`，仅供诊断）。

常见错误类：

| 错误 | 典型原因 |
| - | - |
| `MCodeInvocationError` | SDK 在启动 CLI 前拒绝的参数，或 CLI 退出码 `2` |
| `MCodeRunError` | 任务失败 / 超时 / 超限等；可能带 `status`、`category`、`result`、`retryable`、`sessionId` |
| `MCodeAbortError` | 取消（`AbortSignal`、中断流式迭代，或退出码 `130`） |
| `MCodeProtocolError` | 非 JSON stdout、缺字段、broken pipe 等 |
| `MCodeNotFoundError` | 找不到 CLI，或无法解析 launcher 的 JS 入口 |
| `MCodeVersionError` | CLI 低于 `MIN_CLI_VERSION`，或不支持的事件 `schemaVersion` |
| `ThreadBusyError` | 同一 Thread 上并发启动 Turn |

SDK 不会自动重试，以免在结果未知时重复写入。若错误带有 `sessionId`，可用 `resumeThread(error.sessionId)` 继续。

## 取消与超时

* `signal` 中止时，SDK 发送 `SIGTERM`；CLI 按取消路径收尾（最长约 60 秒），超时后 SDK 再发 `SIGKILL`；
* `timeoutMs` 由 CLI 在访问检查、会话解析和模型选择之后计时；SDK 从进程启动起计时，并在 `timeoutMs + 90s` 强制结束；
* 宿主正常退出时，SDK 会向仍在运行的 CLI 发送 `SIGTERM`，并删除临时 system prompt 目录。宿主被信号杀死时不会发出 `exit`，子进程可能残留。Phase 1 没有 `close()` / `dispose()`；
* Windows 上 Node.js 无法向子进程投递可捕获信号，`SIGTERM` 是硬终止。

推荐在宿主信号处理器里中止进行中的 Turn：

```ts theme={null}
const controller = new AbortController();
process.once("SIGTERM", () => controller.abort());
await thread
  .run(prompt, { signal: controller.signal })
  .catch(() => undefined);
```

并发多个 `exec` 共享同一数据目录的测试仍有限。更稳妥的做法是为每个 SDK 实例（或并发任务）使用独立 `dataDir`，并事先完成认证配置。

## Phase 1 暂不支持

* `outputSchema`（结构化输出约束）；
* 审批回调、运行中转向、中断后续跑、fork。

需要直接调用 CLI 或处理结构化输出时，请使用 [Headless 与 CI](https://agent.minimaxi.com/docs/cli/automation.md)。