# @fastagent/cli

`@fastagent/cli` 是 FastAgent 的公开命令行工具。你可以用它在本地运行 FastAgent、接入内置 IM 通道、安装 skills，并使用一组面向长会话和自动化场景的工程化能力，例如记忆、上下文压缩、任务调度和 sandbox 路由。
当前已 IM 通道包括完整的微信入站媒体处理、保守型非终态反馈、`/resume` 挂起恢复，以及会话内 `cron` / `send_im_media` 这类可主动回发 IM 的能力。

注意：npm 安装得到的是一个干净的 CLI/runtime 运行面，默认不预装任何 skills，也不捆绑任何第三方 MCP server / tool。内置 IM 通道和 CLI 自带能力可以直接使用；如果你需要额外的 skills 或 MCP 集成，需要在安装后自行添加或配置。

它适合这些场景：

- 把 FastAgent 作为本地 CLI agent 使用，通过ACP协议实现各类客户端。
- 通过内置 IM 通道把 FastAgent 跑成 IM 服务（内置微信接入）。
  

模型兼容：

- 支持 Kimi K2 (`kimi-k2*`) 和 Xiaomi MiMo (`mimo-v2*`) 家族模型的 OpenAI Chat Completions 兼容接口，在 thinking 多轮工具调用中保留并回放 assistant `reasoning_content`


## 能力概览

当前版本主要聚焦长会话和自动化场景下的工程化运行能力：

- 文件读取、写入和编辑（read/write/edit）
- 文件搜索与内容搜索（glob/grep）
- 命令执行与进程管理（bash/powershell）
- MCP 工具接入与 MCP 资源读取
- skills 安装、发现和调用
- 记忆：从 project / user 记忆目录召回可复用的长期信息，并在稳定回合后沉淀新的记忆
- Dream: 记忆整理，以及后台 auto-dream 记忆巩固 (支持手动/dream)
- 上下文压缩：长会话自动压缩历史上下文
- 定时任务（`cron`）：会话级持久化定时调度
- 计划清单：管理会话内的任务列表（task_**）
- 后台任务控制：查看、等待和停止子智能体 / 后台运行任务
- IM runtime：微信扫码登录、图片入模、语音转写复用、文件/视频持久化、typing状态、`/resume` 恢复、文件推送、会话内 `cron` 主动回发
- local / remote sandbox 运行模式

这些能力很多会在运行时自动生效，当前并不都会以独立子命令的形式直接暴露。

## 安装

```bash
npm install -g @fastagent/cli
```

安装完成后可直接使用：

```bash
fastagent --help
fastagent doctor
```

## 可用命令

```bash
fastagent
fastagent --channel weixin
fastagent --channel weixin --config ./fastagent.config.json
fastagent --channel weixin --output jsonl
fastagent --channel weixin --sandbox local
fastagent --channel weixin --sandbox remote --sandbox-url http://127.0.0.1:8788
fastagent config
fastagent doctor
fastagent doctor --config ./fastagent.config.json
fastagent skills add <source>
fastagent skills list
fastagent mcp list
```

当前 `fastagent` 裸命令默认显示帮助信息；如果你想直接启动一个可工作的服务入口，优先从 IM 通道开始。

## Runtime Config File

runtime 命令和 `doctor` 支持显式 JSON 配置文件：

```bash
fastagent --channel weixin --config ./fastagent.config.json
fastagent doctor --config ./fastagent.config.json
```

- 只有显式传入 `--config <path>` 时才会读取配置文件。
- 优先级固定为 `命令行参数 > 配置文件 > 环境变量`。
- `fastagent --config ...` 裸命令会报固定错误；`--config` 当前必须和 runtime 命令或 `doctor` 一起使用。
- `fastagent --channel weixin --config ...` 会读取 `gateway`、`sandbox`、`engine`、`imGateway`；`fastagent doctor --config ...` 只诊断 `sandbox.launcher`
- IM 运行时预算走统一 owner：
  `gateway.requestTimeoutMs/maxRetries`、
  `engine.turnTimeoutMs/toolExecutionTimeoutMs`、
  `imGateway.stallTimeoutMs`
- `sandbox` 整段都是可选的；只有 remote sandbox 需要从配置文件注入地址/API key，或 local sandbox 需要自定义 launcher 时才需要填写
- `sandbox.workspaceMode=host-bind` 只支持 `--sandbox local`。如果没有设置
  `sandbox.hostWorkspaceRoot`，IM 命令会默认使用 `imGateway.workspaceDir` 作为执行根。
- 当前配置示例文件是 `examples/fastagent.config.example.json`

### OpenAI Responses `supportsPreviousResponse` 说明

作用：

- 用于控制 `openai-responses` provider 是否走 `previous_response_id` anchored replay
- 不设置时，保持 `auto` 语义：CLI/IM 不显式下发该字段，交给 gateway 按 provider host 自动判断
- 设为 `true` 时，显式开启该 provider 的 stateful replay
- 设为 `false` 时，强制 full transcript replay

配置位置：

- `fastagent.config.json.gateway.supportsPreviousResponse`
- `FASTAGENT_SUPPORTS_PREVIOUS_RESPONSE=true|false`

补充：

- 示例里写成 `false` 只是保守配置示例，不代表运行时默认值
- 官方 host 在未显式关闭时默认开启
- 非官方 `openai-responses` host 在未显式开启时默认走 full transcript replay
- 如果设置了 `FASTAGENT_SUPPORTS_PREVIOUS_RESPONSE`，值必须是 `true|false|1|0`；非法值会在
  CLI runtime config 解析阶段直接报错

模型切换兼容性提示：

- `supportsPreviousResponse` 只控制 `openai-responses` provider 是否走 `previous_response_id` replay，不代表任意模型历史都能无损复用。
- 某些模型族有自己的 continuation 要求。当前已支持 `kimi-k2*` 和 `mimo-v2*` 家族模型：当 thinking 开启且进入多步 tool loop 时，后续请求需要保留 assistant turn 里的 `reasoning_content`。
- 因此，同一会话里如果从别的模型族切到 Kimi K2 / Xiaomi MiMo 家族模型，而旧历史里又包含工具调用链路，可能会因为缺少目标模型所需 continuation 而要求新会话或 `/reset`；纯文本历史通常更容易兼容。

默认 Thinking Level：

- `engine.defaultThinkingLevel` 和 `FASTAGENT_DEFAULT_THINKING_LEVEL` 用来控制 engine 默认推理强度，合法值是 `off|minimal|low|medium|high|xhigh`
- CLI 会把这个值同时投影到 ACP runtime options 和 IM env snapshot
- 如果你准备把默认模型切到 `kimi-k2*` 或 `mimo-v2*` 家族模型，又希望尽量避开 thinking continuation 历史要求，可以把默认值设成 `off`

示例最小配置（IM 通道运行）：

```json
{
  "gateway": {
    "provider": "openai",
    "model": "gpt-5.4",
    "apiType": "openai-responses",
    "baseUrl": "https://api.openai.com/v1",
    "userAgent": "fastagent-cli-example",
    "apiKey": "<your-api-key>",
    "supportsPreviousResponse": false,
    "requestTimeoutMs": 60000,
    "maxRetries": 2
  },
  "sandbox": {
    "workspaceMode": "isolated"
  },
  "engine": {
    "defaultThinkingLevel": "medium",
    "turnTimeoutMs": 180000,
    "toolExecutionTimeoutMs": 120000
  },
  "imGateway": {
    "workspaceDir": "/abs/workspace",
    "agentId": "agent-weixin-dev",
    "dataDir": "/abs/fastagent",
    "stallTimeoutMs": 900000,
    "allowAllPermissions": true
  }
}
```

local sandbox 直接在 host 工作区执行：

```json
{
  "sandbox": {
    "workspaceMode": "host-bind",
    "hostWorkspaceRoot": "/weixin-bot/workspace"
  },
  "imGateway": {
    "workspaceDir": "/weixin-bot/workspace"
  }
}
```

```bash
fastagent --channel weixin --sandbox local --config ./fastagent.config.json
```

## IM Channel

当前公开提供的内置 IM 通道是微信 `weixin`。

你可以用它把 FastAgent 作为一个微信机器人运行，支持：

- 扫码登录
- 已有登录态恢复
- 入站图片进入模型上下文，作为真实 image prompt block 参与推理
- 入站语音复用微信已提供的转写文本，不额外执行本地 STT
- 入站文件 / 视频持久化保存，当前不直接送入模型
- 文本模式输出
- 媒体/文件出站（内置send_im_media等im专有工具）

### 启动前需要的环境变量（如果不显式使用配置文件，需要设置环境变量）

必填：

```bash
# 用户工作区（项目级）
export IM_GATEWAY_WORKSPACE_DIR=/weixin-bot/workspace
# 全局/用户级数据目录
export IM_GATEWAY_DATA_DIR=/weixin-bot/data
# AI名字可任意命名
export IM_GATEWAY_AGENT_ID=weixin-bot
# 默认允许全部权限
export IM_GATEWAY_ALLOW_ALL_PERMISSIONS=true
```

LLM 最小示例：

```bash
export FASTAGENT_PROVIDER=anthropic
export FASTAGENT_MODEL=claude-opus-4-6
export ANTHROPIC_API_KEY=<your-key>
```

常见可选项：

```bash
export FASTAGENT_API_KEY=<your-key>
export FASTAGENT_API_TYPE=openai-responses
export FASTAGENT_BASE_URL=https://api.openai.com/v1
export FASTAGENT_USER_AGENT=your-app-name
export FASTAGENT_SUPPORTS_PREVIOUS_RESPONSE=false
```

`FASTAGENT_API_TYPE` 当前支持这些值：

- `anthropic-messages`
- `openai-completions`
- `openai-responses`
- `google-generative-ai`

如果不显式设置，会按 `FASTAGENT_PROVIDER` 推断：

- `anthropic` -> `anthropic-messages`
- `google` / `gemini` / `google-ai-studio` -> `google-generative-ai`
- 其他 provider 默认回落到 `openai-completions`
- 不设置 `FASTAGENT_SUPPORTS_PREVIOUS_RESPONSE` 时，运行时保持 `auto` 语义，由 gateway 自动判断
- `FASTAGENT_SUPPORTS_PREVIOUS_RESPONSE` 只在 `FASTAGENT_API_TYPE=openai-responses`
  时有意义；设为 `true` 显式启用 anchored replay，设为 `false` 强制 full transcript replay。
- `FASTAGENT_SUPPORTS_PREVIOUS_RESPONSE` 设为其他值时会直接报错，不会静默回退。

### 启动微信服务

```bash
fastagent --channel weixin
```

机器可读输出：

```bash
fastagent --channel weixin --output jsonl
```

远端 sandbox：

```bash
fastagent --channel weixin --sandbox remote --sandbox-url http://127.0.0.1:8788
```

### 使用 PM2 后台运行

如果你希望把 IM runtime 作为后台常驻服务托管，推荐使用 PM2。

先安装 PM2：

```bash
npm install -g pm2
```

建议通过 `command -v fastagent` 取得可执行文件绝对路径，并显式使用 `--interpreter none`。这样 PM2 会把 `fastagent` 当成可执行程序，而不是当前目录下的 Node.js 脚本来加载。

使用配置文件启动：

```bash
pm2 start "$(command -v fastagent)" --name fastagent-im --interpreter none -- --channel weixin --output jsonl --config ./fastagent.config.json
```

不使用配置文件时，也可以先导出必需环境变量，再启动：

```bash
export IM_GATEWAY_WORKSPACE_DIR=/weixin-bot/workspace
export IM_GATEWAY_DATA_DIR=/weixin-bot/data
export IM_GATEWAY_AGENT_ID=weixin-bot
export IM_GATEWAY_ALLOW_ALL_PERMISSIONS=true

pm2 start "$(command -v fastagent)" --name fastagent-im --interpreter none -- --channel weixin --output jsonl
```

常用管理命令：

```bash
pm2 logs fastagent-im
pm2 status
pm2 restart fastagent-im
pm2 restart fastagent-im --update-env
pm2 stop fastagent-im
pm2 delete fastagent-im
pm2 save
```

说明：

- `fastagent-im` 只是示例进程名，对应 `--name fastagent-im`；你可以按自己的部署场景改成任意更清晰的名字，例如 `weixin-bot`、`fastagent-prod`。
- `--` 后面的参数会传给 `fastagent`；如果省略它，`--channel`、`--output`、`--config` 之类的参数可能会被 PM2 自己解析掉。
- 如果你修改的是 shell 环境变量而不是 `--config` 文件，重启时使用 `pm2 restart fastagent-im --update-env` 让新环境生效。

如果你要在 npm 安装态启用 `--sandbox local`，需要满足以下其一：

- 通过 `FASTAGENT_SANDBOX_RUNTIME_BIN` 和可选 `FASTAGENT_SANDBOX_RUNTIME_ARGS` 显式指定 launcher
- 单独安装 `@fastagent/sandbox-runtime`，让包提供 `fastagent-sandbox`
- 让 `fastagent-sandbox` 已经存在于 PATH 中

你也可以先运行：

```bash
fastagent doctor
fastagent doctor --config ./fastagent.config.json
```

当前 `doctor` 会按下面的顺序检查 local sandbox launcher discoverability：

- 不带 `--config` 时：`FASTAGENT_SANDBOX_RUNTIME_BIN` -> PATH `fastagent-sandbox`
- 带 `--config <path>` 时：`config.sandbox.launcher` -> env -> PATH
- 若两者都没有，会直接提示 companion package / env 的修复方式

## Skills 命令

- `fastagent skills add <source>` 默认走 runtime 推断：
  repo-local 本地 source 会安装到当前 workspace 的 `.fastagent/skills/<name>`，
  其他 source 默认安装到 runtime-global skill root `<globalDataDir>/skills/<name>`；
  对普通 npm 安装且未显式覆盖时，通常是 `~/.fastagent/skills/<name>`
- `fastagent skills add <source> --scope project` 强制安装到当前 workspace 的 `.fastagent/skills/<name>`
- `fastagent skills add <source> --scope user` 强制安装到 runtime-global skill root `<globalDataDir>/skills/<name>`；
  对普通 npm 安装且未显式覆盖时，通常是 `~/.fastagent/skills/<name>`
- `fastagent skills add <source> --list` 只列出候选 skill，不写磁盘
- `fastagent skills list` 默认同时列出 project + user 两个 scope 的已安装 skill，并按 scope 分组显示
- `fastagent skills list --scope project|user` 只列出单一 scope 的已安装 skill
- `fastagent skills add` 不再暴露 `--yes`；当前没有 CLI-owned confirmation flow

当前常见 source 形态：

- 本地路径：已有目录优先按本地 source 处理，包括 `./skills/demo-skill`
- GitHub shorthand：`owner/repo`
- GitHub repo URL：`https://github.com/<owner>/<repo>`
- GitHub tree URL：`https://github.com/<owner>/<repo>/tree/<ref>` 或 `.../tree/<ref>/skills/...`

## MCP 命令

- `fastagent mcp list` 列出 runtime-global `settings.json.mcpServers` 里的 MCP server。
- `fastagent mcp add <name> --command <cmd> [--arg <arg>]... [--env KEY=VALUE]...`
  添加一个 runtime-global MCP server。
- `fastagent mcp remove <name>` 删除一个 runtime-global MCP server。
- 如果 `fastagent mcp add` 命中同名 server，CLI 会给出 `1. Overwrite / 2. Exit` 的显式选择，
  不会静默覆盖现有配置。
- `fastagent mcp list` 只显示 env key，不回显 env value。

## 常见用例

```bash
fastagent --help
fastagent --version
fastagent --channel weixin
fastagent --channel weixin --output jsonl
fastagent --channel weixin --sandbox local
fastagent skills add owner/repo
fastagent skills add owner/repo --list
fastagent skills add ./skills/review-pr --scope project
fastagent skills list --scope user
fastagent mcp add search --command node --arg server.js --env API_KEY=secret
fastagent mcp remove search
fastagent config
fastagent doctor
fastagent skills list
```