@fastagent/cli 0.5.0 → 0.5.1

package/README.md

@@ -1,29 +1,31 @@
 # @fastagent/cli
 
-`@fastagent/cli` 是 FastAgent 的公开命令行工具。你可以用它在本地运行 FastAgent、接入内置 IM 通道、安装 skills，并使用一组面向长会话和自动化场景的工程化能力，例如记忆、上下文压缩、任务调度和 sandbox 路由。当前 npm 发布面已经覆盖了最近这批 IM runtime 增强，包括更完整的微信入站媒体处理、保守型非终态反馈、`/resume` 挂起恢复，以及会话内 `cron` / `send_im_media` 这类可主动回发 IM 的能力。
+`@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 使用
-- 通过内置 IM 通道把 FastAgent 跑成 IM 服务
-- 在一个统一入口下使用文件、搜索、MCP、skills，以及记忆、上下文压缩、定时任务、计划清单和后台任务控制等工程化能力
+- 把 FastAgent 作为本地 CLI agent 使用，通过ACP协议实现各类客户端。
+- 通过内置 IM 通道把 FastAgent 跑成 IM 服务（内置微信接入）。
 
 ## 能力概览
 
 当前版本主要聚焦长会话和自动化场景下的工程化运行能力：
 
-- 文件读取、写入和编辑
-- 文件搜索与内容搜索
-- 命令执行与进程管理
+- 文件读取、写入和编辑（read/write/edit）
+- 文件搜索与内容搜索（glob/grep）
+- 命令执行与进程管理（bash/powershell）
 - MCP 工具接入与 MCP 资源读取
 - skills 安装、发现和调用
 - 记忆：从 project / user 记忆目录召回可复用的长期信息，并在稳定回合后沉淀新的记忆
-- 上下文压缩：长会话自动压缩历史上下文，优先复用 session checkpoint，必要时回退到摘要压缩
+- 上下文压缩：长会话自动压缩历史上下文
 - 定时任务（`cron`）：会话级持久化定时调度
-- 计划清单：管理会话内的任务列表
+- 计划清单：管理会话内的任务列表（task_**）
 - 后台任务控制：查看、等待和停止子智能体 / 后台运行任务
+- IM runtime：微信扫码登录、图片入模、语音转写复用、文件/视频持久化、typing状态、`/resume` 恢复、文件推送、会话内 `cron` 主动回发
 - local / remote sandbox 运行模式
-- IM runtime：微信扫码登录 / restore、图片入模、语音转写复用、文件/视频持久化、非终态进度/typing、`/resume` 恢复、`send_im_media`、会话内 `cron` 主动回发
 
 这些能力很多会在运行时自动生效，当前并不都会以独立子命令的形式直接暴露。
 
@@ -72,10 +74,9 @@ fastagent doctor --config ./fastagent.config.json
 - `fastagent --config ...` 裸命令会报固定错误；`--config` 当前必须和 runtime 命令或 `doctor` 一起使用。
 - `fastagent --channel weixin --config ...` 会读取 `gateway`、`sandbox`、`imGateway`；`fastagent doctor --config ...` 只诊断 `sandbox.launcher`
 - `sandbox` 整段都是可选的；只有 remote sandbox 需要从配置文件注入地址/API key，或 local sandbox 需要自定义 launcher 时才需要填写
-- `imGateway.channels.weixin.apiBaseUrl` 是可选项；不填时默认使用 `https://ilinkai.weixin.qq.com`
-- npm 发布包会附带整个 `examples/` 目录；当前配置示例文件是 `examples/fastagent.config.example.json`
+- 当前配置示例文件是 `examples/fastagent.config.example.json`
 
-示例配置：
+示例最小配置（IM 通道运行）：
 
 ```json
 {
@@ -87,13 +88,6 @@ fastagent doctor --config ./fastagent.config.json
     "userAgent": "fastagent-cli-example",
     "apiKey": "<your-api-key>"
   },
-  "sandbox": {
-    "remoteUrl": "http://127.0.0.1:8788",
-    "apiKey": "<sandbox-api-key>",
-    "launcher": {
-      "bin": "fastagent-sandbox"
-    }
-  },
   "imGateway": {
     "workspaceDir": "/abs/workspace",
     "agentId": "agent-weixin-dev",
@@ -115,12 +109,9 @@ fastagent doctor --config ./fastagent.config.json
 - 入站语音复用微信已提供的转写文本，不额外执行本地 STT
 - 入站文件 / 视频持久化保存，当前不直接送入模型
 - 文本模式输出
-- `jsonl` 机器输出
-- `local` / `remote` sandbox 路由
+- 媒体/文件出站（内置send_im_media等im专有工具）
 
-普通 final reply 仍以文本回复为主；媒体出站目前不是独立 CLI flag，而是通过运行时工具 `send_im_media` 和 scheduled/proactive delivery 复用同一条 IM 出站链路。
-
-### 启动前需要的环境变量
+### 启动前需要的环境变量（如果不显式使用配置文件，需要设置环境变量）
 
 必填：
 
@@ -183,6 +174,53 @@ fastagent --channel weixin --output jsonl
 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