它是什么

agent-connect 跑在你自己的电脑上，把 即时通讯（飞书 / Lark） 接到 本地编程 Agent（Grok Build）：

飞书消息  →  agent-connect  →  Grok（改代码 / 跑命令）
     ↑______________ 流式回复 / 卡片 / 媒体 ______________|

• 不需要公网 IP：飞书事件走 长连接（WebSocket）
• 多项目隔离：1 Project = 1 Engine（会话、Agent 池、媒体目录互不串线）
• 同 app 单连接：相同 app_id 只建一条 WS，用 allow_chat 分群
• CLI 守护进程：前台 / 后台 / 系统服务（macOS · Linux · Windows）
• 双运行时：Node.js ≥ 20 与 Bun ≥ 1.1 均可（生产入口 dist/）

飞书是日常 UI；本机只需把 bridge 装好、挂着。

| 项目 | 定位 | |------|------| | agent-connect | IM ↔ coding agent 桥 | | GrokGo | 本地 Grok API / MCP 网关 | | cc-connect | 多 Agent / 多 IM 参考实现（Go） |

功能一览

| 能力 | 说明 | |------|------| | 多项目 Supervisor | start --all 同时托管多个 Engine | | FeishuConnectionHub | 同 app_id 单 WebSocket + ACL 扇出 | | Grok ACP | 默认 grok agent stdio；失败可回退 spawn | | 流式回复 | 合并推送；卡片失败回退纯文本 | | 媒体 | 入站 stage / 出站上传；防路径穿越 | | 权限 | allow_from / allow_chat / require_mention | | 进程治理 | 全局 process budget、ACP 空闲回收 | | 运维 | doctor · status · start --daemon · stop · service | | IM 命令 | /help /new /status /stop /whoami |

环境要求

| 依赖 | 说明 | |------|------| | Node.js ≥ 20 或 Bun ≥ 1.1 | 二选一即可跑生产路径 | | Grok Build CLI | 本机登录一次 → ~/.grok/auth.json | | 飞书 / Lark 应用 | 启用机器人；事件订阅选 长连接；事件 im.message.receive_v1 |

单元测试目前使用 bun test。仅部署运行时，可以只装 Node。

安装

从源码（推荐）

git clone https://github.com/RongleCat/agent-connect.git
cd agent-connect

# —— Node ——
npm install
npm run build
npm link

# —— 或 Bun ——
bun install
bun run build
bun link

不 link 时：

node dist/index.js --help
# Bun 开发也可：
bun run src/index.ts --help

全局包（npm scoped）

npm 上未 scoped 的 agent-connect 已被其他项目占用，本项目发布为 @ronglecat/agent-connect。CLI 命令仍是 agent-connect。

npm install -g @ronglecat/agent-connect
# 或
bun install -g @ronglecat/agent-connect

尚未发布到 npm 时，请用上方「从源码」安装。

登录 Grok

grok   # 浏览器授权 → ~/.grok/auth.json

详细平台说明（含服务、WSL、WinSW）：INSTALL.md。

60 秒上手

# 1) 健康检查
agent-connect doctor

# 2) 配置飞书（扫码新建 或 绑定已有 app）
agent-connect feishu setup --project work
# agent-connect feishu bind --project work --app 'cli_xxx:sec_xxx'

# 3) 启动
agent-connect start --all                 # 前台
agent-connect start --all --daemon        # 后台
agent-connect status
agent-connect stop

# 4) 可选：开机自启（用户级服务）
agent-connect service install
agent-connect service status

在开放平台确认：

1. 已启用 机器人
2. 事件订阅 = 使用长连接接收事件
3. 已添加 im.message.receive_v1 并发布版本
4. 机器人已加入目标会话

配置文件默认：~/.agent-connect/config.toml
完整示例：config.example.toml

命令参考

全局

| 命令 | 说明 | |------|------| | agent-connect start | 启动桥（默认读配置） | | agent-connect start --all | 启动全部项目（Supervisor） | | agent-connect start --project <name> | 只启动指定项目 | | agent-connect start --all --daemon / -d | 后台启动 | | agent-connect start --dry-run | 只校验配置，不连网 | | agent-connect start --force | 先停旧实例再启动 | | agent-connect stop | 停止 PID 跟踪的实例 | | agent-connect status | 项目 / 进程 / 服务摘要 | | agent-connect doctor | 配置、凭证（脱敏）、Grok、auth | | agent-connect version | 版本号 | | agent-connect help | 帮助 |

常用选项：

| 选项 | 说明 | |------|------| | --config <path> | 配置文件（默认 ~/.agent-connect/config.toml） | | --log-level <lvl> | debug | info | warn | error | | --log-file <path> | 日志文件（默认 ~/.agent-connect/logs/agent-connect.log） |

飞书

agent-connect feishu setup --project work              # 无凭证 → 扫码；有 --app → 绑定
agent-connect feishu new --project work                # 强制扫码新建
agent-connect feishu bind --project work --app 'cli_x:sec_y'
agent-connect feishu setup --project work --work-dir ~/code/app
agent-connect feishu setup --project work --platform-type lark

系统服务

agent-connect service install                 # macOS LaunchAgent / Linux systemd --user / Windows WinSW 定义
agent-connect service install --backend schtasks   # Windows：计划任务（无需 WinSW）
agent-connect service uninstall
agent-connect service start | stop | status
agent-connect service print                   # 生成定义到 ~/.agent-connect/service/，不启用

| 平台 | 默认方式 | |------|----------| | macOS | LaunchAgent com.agent-connect.bridge | | Linux | systemd --user → agent-connect.service | | Windows | WinSW XML；或 --backend schtasks |

模板目录：packaging/

其它

agent-connect migrate from-lark-grok   # 从旧版 ~/.lark-grok 迁移
agent-connect smoke-grok "ping"        # 本地试 Grok，不连飞书

临时 CLI 别名：lark-grok（与 agent-connect 同一入口）。

飞书里可用的斜杠命令

| 命令 | 作用 | |------|------| | /help | 帮助 | | /new | 新会话 | | /status | 当前会话 / 后端状态 | | /stop | 尝试中断当前回合 | | /whoami | 身份信息 |

配置示例

多项目、多 app（强隔离）

[[projects]]
name = "work"
allow_from = "*"
require_mention = true

[projects.agent]
type = "grok"
work_dir = "~/work"
session_backend = "acp"

[[projects.platforms]]
type = "feishu"
app_id = "cli_work_xxx"
app_secret = "..."

[[projects]]
name = "personal"
# ... 另一个 app_id

同 app、按群拆分（Shared Hub）

[[projects]]
name = "team-a"
allow_chat = "oc_group_a"

[[projects.platforms]]
type = "feishu"
app_id = "cli_shared"
app_secret = "..."
allow_chat = "oc_group_a"

[[projects]]
name = "team-b"
allow_chat = "oc_group_b"
# 相同 app_id + 不同 allow_chat

同一 app_id 只会建立一条长连接。更多字段见 config.example.toml。

数据目录

~/.agent-connect/
  config.toml              # 项目与凭证（切勿提交）
  logs/agent-connect.log
  run/agent-connect.pid    # 单实例
  service/                 # 生成的 unit / plist / WinSW
  data/sessions/           # 会话持久化

架构要点

CLI (start | service | doctor)
        │
   Supervisor ── budget · signals · FeishuConnectionHub registry
        │
   ┌────┴────┐
 Engine A   Engine B     ← 1 Project = 1 Engine
   │            │
 Agent+Session  Agent+Session
   │            │
   └────┬───────┘
        │  same app_id → ONE WebSocket
   FeishuConnectionHub

硬规则（详见 docs/architecture.md）：

1. 跨 Project 禁止共享 SessionManager、ACP 池、出站队列、媒体目录
2. 相同 Feishu app_id 必须单连接
3. 日志 不得打印 app_secret / token

安全提示

• mode = "yolo" 会自动批准 Grok 工具（含 shell）——视 bot 为可操作你电脑的远程 shell
• 生产环境请收紧 allow_from，避免 *
• 密钥只放在本机 ~/.agent-connect，永不提交仓库
• 报告漏洞见 SECURITY.md

开发

git clone https://github.com/RongleCat/agent-connect.git
cd agent-connect
bun install          # 或 npm install
bun run build
bun test             # 需 Bun
bunx tsc --noEmit
node dist/index.js --help

npm run check        # test + typecheck + build + help

贡献流程：CONTRIBUTING.md · 行为准则：CODE_OF_CONDUCT.md

文档索引

| 文档 | 内容 | |------|------| | INSTALL.md | 安装、守护进程、三端服务、排障 | | config.example.toml | 配置模板 | | docs/architecture.md | 架构与隔离 | | docs/acp.md | Grok ACP | | docs/feishu.md | 飞书说明 | | docs/acceptance.md | 验收矩阵 | | CHANGELOG.md | 变更记录 | | SECURITY.md | 安全策略 |

License

MIT © RongleCat · 铁柱AGI@cgnot996