产品文档

基本概念

Agim（阿吉姆）是一个常驻 Node.js 进程，把 IM 渠道 （微信、飞书、钉钉、邮件） 和 原生 Agent （Claude Code、Codex、OpenCode、Antigravity、Cursor，或内置的 Agim Agent，或任意 ACP 端点） 桥接到一起。 单进程，无需 Docker / Redis。

• 会话 (session) 以 platform:channel:thread 为键， 记录最近一次活跃的 agent、模型、历史消息，30 分钟无新消息自动归档。
• 意图分类器 走轻量启发式（中英双语关键词）， 无明确 /前缀 时智能选 agent，再用 sticky 锁定一段对话。
• 审批总线 拦截 agent 的工具调用（写文件、跑 shell、访问网络）， 在 IM 里推一张审批卡，用户回 y/n/all 才放行。
• 持久存储 全在 SQLite —— ~/.agim/（从 0.x 升级则继续用 ~/.im-hub/）下 jobs.db / memos.db / reminders.db / audit.db / 会话文件， 重启不丢，30 天自动修剪。
• 四种入口：IM（微信 / 飞书 / 钉钉 / 邮件）、内置 Web 控制台、 终端 TUI（agim tui，可选 agent、存档续聊）、以及通过 ACP 协议编程接入—— 共用同一套 agent 与会话后端。
• 长期记忆：每位用户的 5W1H 事实库 + 自动提炼的「记忆画像」每轮注入 prompt；默认 SQLite + FTS5，可选向量召回（本地 BGE 或 OpenAI 兼容 endpoint）做 同义 / 跨语言查询。

快速开始

完整安装路径有三种（脚本 / npm / 源码），见 安装页。 最简流程：

npm install -g agim-cli      # 需要 Node ≥ 18
agim                         # 双语方向键向导（推荐）
agim start                   # 前台启动

向导会带你过一遍：选语言 → 选启用哪些 IM → 给每个 IM 走配置（微信扫码 / 飞书 App Secret / 钉钉 ClientID …）→ 选启用哪些 agent → 配 SMTP（提醒邮件）/ 百度地图 AK（地址解析）。

IM 渠道

每个 IM 在向导里有自己的子菜单，包含状态展示、Configure / Re-configure / Remove。配置存到 ~/.agim/config.json （升级用户为 ~/.im-hub/config.json；chmod 600）。

钉钉细节：必须创建「企业内部应用」并开启 Stream 模式（不是「群聊机器人 Webhook」 —— 那个只能单向推送）。1 人企业也算，注册个人企业即可。钉钉服务端不会向 bot 投递「位置消息」，要做位置请用 /memo here 走捕获链接，或者直接打字描述地址让 agent 走百度地图 geocode。

原生 Agent

每个 agent 对应一个本地命令行程序；向导会用 <cmd> --version 探测安装状态，标记「已安装 / 未安装」并给出安装命令。

Agim Agent（系统内置）

Agim Agent 是系统内置 Agent，只需配置一个大模型 API 就能用，不必另装任何东西。它在进程内运行，直连任意 OpenAI / Anthropic 兼容后端（DeepSeek / Kimi / Qwen / GLM / Ollama / vLLM / OpenAI / Anthropic）。它和命令行 agent 共用同一套审批总线、审计、记忆与 MCP 工具，区别在于多了一组进程内的本地工具和一套针对"日常默认 agent"的可靠性保护。

工具套件

可靠性栈（四层早停 / 复盘）

Agim Agent 的多轮循环外包了四层独立检查，从机械到语义递进。命中即早停，并渲染一张结构化复盘卡（说明发生了什么 + 已执行的工具 + 建议下一步 + 切换其他 agent 的入口），而不是继续把无用输出推给你：

• 空响应补刀——一轮结束没有文本却调用过工具时，用同一模型、禁用工具再问一次，逼它把刚做的事讲清楚。
• 超迭代复盘——撞到迭代上限时不再静默截断，而是汇报进度与下一步。
• 死循环检测——同名 + 同错误 + 同输出连续三次，立即早停（纯机械比对，无额外大模型成本）。
• 偏离目标检测——工具调用积累到一定次数后，用一次廉价大模型调用判断是否还在为原始目标做事；默认仅在存在活动 /long_task 目标时启用。

后端与角色配置见下方「配置」一节的 `llmBackends` / `llmRoles`；人格写在 `~/.agim-workspaces/native/AGENTS.md`，热加载、改完无需重启。

斜杠命令

所有 IM 通用，平台无关。除 /memo 等本地命令外，多数都通过 agent 的 MCP 工具实现，因此自然语言也能触发同样的能力。

长任务与目标

IM 单条消息有 30 分钟硬上限，超时后中间状态会丢失。Agim 提供几种机制把跨越这条线的工作管起来：

• 长目标 — `/goal set <标题>` 或 `/long_task <标题>` 给当前线程设一个活动目标，每轮都注入 prompt 提醒 agent 保持方向；`/goal progress` 记进度，`/complete_goal` 收尾。每个线程同时只有一个活动目标。
• bgjob — 预估运行时间超过 10 分钟的任务，写成独立脚本交给 bgjob 后台跑（detach、断点续跑、进度落盘），不受 IM 超时影响。Agim Agent 的 `native_exec` 能识别 bgjob 调用并放行。
• /cron — cron 表达式定时跑任意已注册 agent 的预设 prompt：日报、周报、夜间批处理。
• /heartbeat — 定期触发一次 DECIDE / EXECUTE / EVALUATE 巡检，让 agent 主动判断当前线程是否有事要做。

当 Agim Agent 在长目标下空转或偏题时，「Agim Agent」一节的可靠性栈（死循环检测、偏离目标检测）会早停并复盘，而不是耗光迭代预算。

安全与审批

Agent 的工具调用默认都要过审批，敏感数据有多层拦截。这些防线在 agim 进程里强制，不依赖模型自觉：

• 审批总线 — 动文件 / 跑 shell / 走网络的工具调用推一张审批卡，回 y / n / all。超时行为可配（默认 deny；「离开模式」改 allow）。
• 敏感路径硬黑名单 — 在「只读自动放行」之前硬拒绝：env 文件、~/.ssh/、系统密码文件、agim token、AGENTS.md / CLAUDE.md、env / printenv dump、credentials.* 等，即便管理员想同意也不放行。Bash 与 native_exec 共用同一黑名单。
• 出站脱敏 — 消息发往 IM 前再扫一遍，把 token 形状的子串（agim / OpenAI / GitHub / Slack / AWS / Telegram / Discord / PEM / JWT）替换为 [REDACTED]。
• exec 沙箱 — `IMHUB_EXEC_SANDBOX=bwrap`（Linux，opt-in）让 native_exec 在 bubblewrap 命名空间里跑，可选断网。
• 平台黑名单 + Web 鉴权 — `IMHUB_PLATFORM_BLACKLIST` 在启动时硬拒绝指定 IM 平台注册；Web 控制台默认 token 鉴权，127.0.0.1 旁路。
• 管理员白名单 — `/restart` / `/stop` 等服务命令限 `IMHUB_ADMIN_USERS` 名单；首次部署用一次性 bootstrap token 自助设管理员。

配置

Agim 读三处配置源，优先级依次为：

1. ~/.agim/config.json （升级用户为 ~/.im-hub/config.json） — 主配置：启用哪些 IM、哪些 agent、默认 agent、各 IM 的凭据对象、acpAgents 列表。chmod 600，向导写入。
2. ~/.agim/env （或 ~/.im-hub/env） — 简单 KEY=value 文件，存 SMTP 凭据和百度地图 AK 等敏感环境变量。chmod 600。systemd 单元通过 EnvironmentFile= 加载。
3. process.env — 运行时进程环境，向导读取时会作为前两者的回退（systemd unit Environment= 行也走这条）。

常用环境变量：

Web 控制台

`agim` 启动时附带一个本地 Web 控制台（默认监听 127.0.0.1，端口在安装时设定，用 `/web` 查地址）。主要页面：

• 聊天 — 浏览器里直接和 agent 对话，审批卡片点击即回（点击后立即禁用按钮并显示状态，避免误以为没反应）。
• 设置 — 启用哪些 IM / agent、选默认 agent、配大模型后端、外挂 MCP、ACP 远程 agent。agent 启用项和默认 agent 的改动保存后立即生效，无需重启。
• 安全 — 把审批策略、超时行为、平台黑名单等安全开关集中到一个页面。
• 记忆 — 查看 / 编辑 / 导出长期事实库与记忆画像，可手动触发重建画像。
• Viewer — 超长回复转成 `/v/<id>` 短链在浏览器看，避免 IM 截断；支持本地代理 / cloudflared / 远程粘贴三种模式。

终端 TUI

`agim tui` 打开一个基于 Ink 的终端聊天界面：选一个 agent 在本机直接对话，不接任何 IM。适合在服务器上调试 agent 配置、临时跑一段对话，或者就把它当本地终端的 AI 助手用。会话自动存档到 AGIM_HOME 下的 tui-sessions 目录，可随时续聊。

启动

界面内命令

键位与输入语法

• Enter 发送 · Esc 取消当前回合 · ↑ / ↓ 选项 / 历史 · Tab 补全 · Ctrl-P 命令面板 · Ctrl-C 退出。
• !<cmd> — 行内执行一条 bash 命令。
• @<file> — 引用一个文件路径，agent 可自行用工具读取。

技能系统

技能（skill）是给 agent 的按需知识 / 脚本包。Agim 扫描两处：operator 自己放的 `~/.agim/skills/<name>/SKILL.md` 优先，内置的作兜底。三层渐进披露，避免一次性塞满上下文：

• 第 1 层——名称 + 描述，每轮自动进 system prompt。
• 第 2 层——SKILL.md 正文，按需用 read_skill 工具拉取。
• 第 3 层——scripts / references / assets，由正文引用后走普通文件读取。

`/skill list|show|refresh` 在 IM 里可用；Web 控制台有技能编辑器。命令行 agent 与 Agim Agent 都通过 read_skill 工具透明访问。可从 skillhub.cn（公共技能市场）发现 / 安装更多技能。

服务生命周期

三种运行模式自动识别：

• systemd — 安装脚本以 root 跑时落 /etc/systemd/system/agim.service（升级用户为 im-hub.service）。 后续用 systemctl 或 agim restart 管理。
• 后台守护进程 — agim start --bg 用 nohup + setsid + pid 文件，跨平台（Linux / macOS / WSL2）。
• 前台进程 — agim start 直接挂在你的终端上，Ctrl-C 退出。

agim status 一键探测当前是哪种模式 + pid + uptime + Web URL。

另有 agim tui 本地终端聊天界面，详见上方「终端 TUI」一节。

架构

入站消息归一化后交给 router；router 选 agent，agent 输出走出站到原 IM。

┌─ Messenger ingress ──────────────────────────────┐
│ WeChat iLink   (long-poll + image/voice/file)    │
│ Feishu         (Lark SDK WebSocket)              │
│ DingTalk       (Stream WebSocket + ASR baked in) │
│ Web Chat       (browser WebSocket)               │
│ Email          (SMTP, push-only)                 │
└───────────────────────┬──────────────────────────┘
                        │ MessageContext
                        ▼
                  Router + Session
                        │
                        ▼
                Approval bus (HITL)
                        │
                        ▼
                Agent adapters
       ┌─────────────┼─────────────────┐
   Local CLI      In-process        Remote ACP
 (Claude / Codex /  Agim Agent    (HTTP /events)
  OpenCode /        (OpenAI /
  Antigravity /      Anthropic
  Cursor)            compat)