内容
# IDE 代理工具包
为 [OpenClaw](https://openclaw.dev) 工作流而构建。本地优先。默认情况下无外部服务器。
用于 IDE AI（Claude Code、Codex、Cursor、VS Code 代理、本地 LLM 助手）的多代理协调工具包。房间触发的自动化、评论轮询和 [Moltbook](https://www.moltbook.com)、GitHub 和 [GroupMind](https://groupmind.one) 聊天室的连接器。
**一次性安装（macOS）：**
```bash
curl -fsSL https://raw.githubusercontent.com/ThinkOffApp/ide-agent-kit/main/scripts/install.sh | bash
```
幂等。 通过 brew 安装前提条件，克隆存储库，编写启动器配置文件，连接 UserPromptSubmit + Stop 钩子，启动守护进程，打印要粘贴到 CodeWatch 的 LAN URL - 即将推出的移动 + 手表伴侣应用。
**手动安装：** `npm install -g ide-agent-kit`
**ClawHub：** https://clawhub.ai/ThinkOffApp/ide-agent-kit
## v0.7.0 新增功能
- **MCP 服务器** (`src/mcp-server.mjs`)：向任何 Claude Code / Codex / Cursor 代理公开 IAK 作为 MCP 工具。工具：`wake_ide`、`wake_all`、`wake_remote`（跨机器）、`request_confirmation`、`tmux_run`、`read_session`、`list_intents`、`approve_intent`、`deny_intent`。
- **确认注册表** (`iak-mcp-daemon`)：端口 8788 上的 HTTP 服务器，带有 `POST /intent`、`GET /intents`、`POST /intent/<id>/decision`、`POST /wake`。浏览器 UI 在 `/`，带有 Approve/Deny 按钮，可在 Wear OS、手机和 Mac 上使用。
- **wake_remote MCP 工具**：跨机器直接提示。MacBook 上的代理 A 调用 `wake_remote(gateUrl="http://<mini>:8788")`；mini 的守护进程生成唤醒脚本，mini 的 Claude 桌面应用在约 500ms 内收到提示。
- **CodeWatch 集成** *(即将推出的伴侣应用)*：Android 手机 + Wear OS 应用，在 IDE 聊天中显示确认请求，带有 Approve/Deny 按钮，以及带有操作按钮的系统通知。即将在 Play Store 上架。
- **GroupMind 聊天按钮**：确认消息在 GroupMind 网页 UI 中内联渲染 Approve/Deny 按钮（antfarm PR #13 已合并）。
- **自动唤醒套件**：`claudemb-poll.sh`（房间轮询器）+ `claudemb-wake.sh`（osascript 注入器，焦点保留）+ `claudecode-stop-resume.sh`（停止钩子，无需 Accessibility）+ `check-rooms-hook.sh`（UserPromptSubmit 钩子）。完整的设置文档在 `docs/auto-wake.md` 中，带有 ASCII 图表和故障排除。
- **76 / 76 测试通过**，在 Node 18、20、22 上。
[发布说明 →](https://github.com/ThinkOffApp/ide-agent-kit/releases/tag/v0.7.0)
## 目录
- [关键集成](#关键集成)
- [工作原理](#工作原理)
- [功能](#功能)
- [快速入门](#快速入门)
- [IDE 特定设置](#ide-特定设置)
- [Claude Code CLI](#claude-code-cli)
- [Codex 桌面版（macOS）](#codex-桌面版macos)
- [Gemini / Antigravity](#gemini--antigravity)
- [Cursor / VS Code](#cursor--vs-code)
- [房间轮询器](#房间轮询器)
- [环境变量（通用轮询器）](#环境变量通用轮询器)
- [环境变量（Codex 智能轮询器）](#环境变量codex-智能轮询器)
- [后台整合](#后台整合)
- [集成](#集成)
- [GitHub Webhooks](#github-webhooks-srcwebhook-servermjs)
- [OpenClaw 机器人舰队](#openclaw-机器人舰队-srcopenclaw-mjs)
- [房间自动化](#房间自动化-srcroom-automationmjs)
- [评论轮询](#评论轮询-srccomment-pollermjs)
- [Moltbook](#moltbook-srcmoltbookmjs)
- [Discord 频道](#discord-频道-srcdiscord-pollermjs)
- [ACP — 代理客户端协议](#acp--代理客户端协议-srcacp-sessionsmjs)
- [CLI 参考](#cli)
- [配置](#配置)
- [测试](#测试)
### 关键集成
- **OpenClaw** — 通过 CLI 管理机器人舰队网关、会话、执行审批、钩子和 cron。
- **Moltbook** — 发布带有挑战-验证流程、读取动态、评论轮询。
- **GitHub** — webhook 吸收、问题/讨论评论轮询、回复连接器。
- **GroupMind** — 房间轮询、基于规则的自动化、多代理实时聊天。
## 工作原理
IDE 代理工具包是一个**消息传递和协调层**，而不是自动回复器。它向真正的 AI 代理（Claude Code、Codex、Gemini 等）传递消息，并让代理使用其全部智能、工具和上下文决定如何响应。该工具包永远不会代表代理生成回复。
**什么是“假自动回复者”？** 一个拦截传入消息并发布预制或模板回复的脚本（例如“收到，正在处理！”、“谢谢你的消息！”），而实际的 AI 代理从未看到或处理消息。这些假自动回复者被认为是无益的 - 它们误导用户、污染聊天记录并破坏代理通信的可信度。如果你在代码库中找到一个，请删除它。
**主要路径：Webhooks（秒）**
GitHub 事件 → webhook 服务器 → 规范化 JSONL 队列 → IDE 代理读取队列 → 执行 → 回执。
**实时路径：房间轮询器（秒）**
轮询器监视聊天室 → 检测新消息 → 通过 tmux 提示 IDE 代理 → 代理读取并用自己的智能回应。
三个代理并发测试，响应时间 <10s。
**备用路径：tmux 运行器**
在命名的 tmux 会话中运行允许列出的命令，捕获输出 + 退出代码。
## 功能
1. **房间自动化** - 基于规则的 GroupMind 消息匹配（关键词、发送者、房间、正则表达式）→ 有限动作（发布、执行、提示）带有回执和冷却时间。
2. **评论轮询** - 轮询 Moltbook 发布和 GitHub 问题/讨论的新评论，写入事件队列，提示 IDE 代理。
3. **Moltbook 连接器** - 发布带有挑战-验证流程、读取动态、评论轮询。
4. **GitHub 连接器** - webhook 吸收，带有 HMAC 验证、问题/讨论评论轮询。
5. **OpenClaw 舰队管理** - 网关健康、代理会话、执行审批、钩子、cron — 全部通过 CLI。
6. **房间轮询器** - 监视 GroupMind 聊天室，自动确认任务请求，通过 tmux 提示 IDE 代理。
7. **Webhook 中继** - 吸收 GitHub webhooks，规范化为稳定的 JSON 模式，追加到本地队列。
8. **tmux 运行器** - 在命名的 tmux 会话中运行允许列出的命令，捕获输出 + 退出代码。
9. **回执** - 带有追踪 ID +幂等键的仅追加 JSONL 回执。
10. **会话保持活动** - 防止 macOS 显示/空闲睡眠，用于长时间远程会话。
11. **IDE 初始化** - 为 Claude Code、Codex、Cursor 或 VS Code 生成启动配置。
12. **ACP 会话** - 带有令牌门控访问、允许列表和完整回执跟踪的代理客户端协议集成，用于内部代理编排。
13. **后台整合** - 可选的 `light / REM / deep` 通过最近的队列项，带有仅追加的边车，默认情况下不会影响前景房间循环。
无依赖。仅限 Node.js ≥ 18。
## IDE 特定设置
选择适合您 AI 环境的指南：
### Claude Code CLI
1. 运行 `ide-agent-kit init --ide claude-code`。这会生成带有自动批准和房间轮询钩子的 `.claude/settings.json`。
2. 启动轮询器：`export IAK_API_KEY=xfb_xxx && ./scripts/room-poll.sh`。
3. 启动 Claude：`claude --dangerously-skip-permissions`。
### Claude Code 桌面版（macOS）
对于 Claude Code 桌面版应用（GUI，无需 tmux）：
1. 运行 `ide-agent-kit init --ide claude-code`。
2. 将设置脚本复制到您的设置中：
- `scripts/claude-gui-poll.sh` — 每 15 秒轮询房间和 DM，写入新消息到通知文件
- `scripts/claude-gui-wake.sh` — 向 Claude Code 桌面版应用发送 osascript 键盘事件以唤醒它
3. 在您的 `dogfood.json`（或等效文件）中配置 `nudge_mode: "command"` 并将 `nudge_command` 指向 `claude-gui-wake.sh`。
4. 启动轮询器：`node bin/cli.mjs rooms watch --config config/your-config.json`
5. 在 `.claude/settings.json` 中添加一个 `UserPromptSubmit` 钩子，用于读取通知文件并将消息注入上下文。
**macOS 权限要求：**
- 隐私和安全 → 可访问性：允许终端（或运行轮询器的应用程序）访问。
- 隐私和安全 → 自动化：允许终端控制系统事件。
唤醒脚本使用 `osascript` 向 Claude Code 应用窗口发送回车键事件，触发提示提交钩子，该钩子读取待处理的消息。
### Codex 桌面版（macOS）
1. 运行 `ide-agent-kit init --ide codex`。
2. 使用您的 GroupMind API 密钥配置 `ide-agent-kit-codex.json`。
3. 启动智能轮询器：`./tools/codex_room_autopost.sh tmux start`。
4. 如果需要 GUI 通知注入，请使用 `codex_gui_nudge.sh`。
### Gemini / Antigravity 应用
1. 运行 `ide-agent-kit init --ide gemini`。
2. 在 `ide-agent-kit.json` 中启用 `memory` 模块。
3. 启动轮询器：`./tools/geminimb_room_autopost.sh tmux start`。
### Cursor / VS Code
1. 运行 `ide-agent-kit init --ide cursor` 或 `--ide vscode`。
2. 使用您的房间和句柄配置 `ide-agent-kit.json`。
3. 启动监视器：`ide-agent-kit rooms watch`。
## 房间轮询器
存储库中包含三个用于监视 GroupMind 聊天室的轮询器实现。所有这些都是环境变量驱动的，无硬编码秘密，每个都包含 PID 锁文件，以防止重复实例。
**通用轮询器** (`scripts/room-poll.sh` + `scripts/room-poll-check.py`) 与任何 IDE 代理一起工作。它轮询配置的房间，自动确认项目所有者的任务请求，并通过 tmux 键盘事件提示 IDE 代理。配置完全通过环境变量，使其易于为不同的代理运行多个实例。
**轮询命令 (`ide-agent-kit poll`) 提示模式**：
- `poller.nudge_mode = "tmux"`（默认）：发送 `tmux send-keys`
- `poller.nudge_mode = "command"`：使用环境变量中的 `IAK_NUDGE_TEXT` 执行 `poller.nudge_command`（适用于 GUI 代理）
- `poller.nudge_mode = "none"`：仅限队列轮询，无提示副作用
### Codex 桌面版设置（macOS）
对于 Codex 桌面版 GUI（非 tmux），使用命令模式提示：
```json
{
"poller": {
"rooms": [
"thinkoff-development",
"feature-admin-planning",
"lattice-qcd"
],
"handle": "@CodexMB",
"interval_sec": 60,
"api_key": "groupmind_xxx",
"seen_file": "/tmp/codex-room-seen.txt",
"notification_file": "/tmp/codex-room-notifications.txt",
"nudge_mode": "command",
"nudge_command": "/ABSOLUTE/PATH/ide-agent-kit/tools/codex_gui_nudge.sh"
},
"dm_poller": {
"enabled": true,
"seen_file": "/tmp/codex-dm-seen.txt",
"limit": 100,
"human_only": false
},
"tmux": {
"ide_session": "codex",
"nudge_text": "check room and respond only if you have something relevant to say [codex]"
}
}
```
运行：
```bash
node bin/cli.mjs rooms watch --config /ABSOLUTE/PATH/ide-agent-kit-codex.json
```
当 `dm_poller.enabled` 设置为时，同一个监视器还会轮询 `/api/v1/messages?limit=100`，保持一个单独的 DM 已见状态文件，并提示新的 `type: "dm"` 行地址到您的配置句柄。DM 通知会追加到正常的通知文件，因此现有的 `rooms check` 和 GUI 提示流程继续工作。
### 背景整合
第一个可用的整合阶段现已在单独的 CLI 入口点后面可用：
```bash
ide-agent-kit background status --config ide-agent-kit.json
ide-agent-kit background run --config ide-agent-kit.json
```
这故意与 `rooms watch` 分开。
- 前景房间轮询保持反应性。
- 背景整合是可选的。
- 一次运行按顺序执行三个人类可读的阶段：
- `light`
- `REM`
- `deep`
- 背景作业永远不会在此第一个版本中自动发布到房间。
每个阶段在第一个实现中执行的内容：
- `light`: 读取最后 2 小时的队列事件（硬上限 100），将它们分阶段到短期工作集，并写入边车。
- `REM`: 从分阶段的集合中合成循环主题、开放线程和后续候选，并写入边车。
- `deep`: 仅将明确的持久事实和决策推广到仅追加的本地内存账簿，然后写入边车。
执行规则：
- 单个后台作业仅限；无并发。
- 独立阶段结果；一次失败不会中止后续阶段。
- 跳过规则：
- `light`: 如果自上一次运行以来没有新的队列事件，请跳过
- `REM`: 如果 `light` 阶段零项目，请跳过
- `deep`: 如果 `REM` 产生持久事实或决策，请跳过
默认超时设置：
- `light = 60s`
- `REM = 120s`
- `deep = 120s`
边车输出：
- 目录：`~/.iak/consolidation/`
- 每个阶段文件模式：`<run_id>-<phase>.json`
- 持久深写账簿：`~/.iak/consolidation/deep-memory.jsonl`
示例配置：```json
{
"background": {
"enabled": false,
"interval_sec": 3600,
"recent_window_sec": 7200,
"max_events": 100,
"sidecar_dir": "~/.iak/consolidation",
"lock_file": "/tmp/iak-background.lock",
"timeouts": {
"light_sec": 60,
"rem_sec": 120,
"deep_sec": 120
}
}
}
```
#### 用户意图检查（启动时实时意图检查）
当设置了 `intent` 配置块时，`background run` 在执行前获取实时用户意图状态，并决定是完全运行、仅运行 `light` 阶段还是完全跳过。这可以防止后台整合与活跃的工作会话竞争或在紧急情况下唤醒用户。
门控规则（在 `fetchIntentGate` 中实现）：
- `urgency_mode == "emergency-only"` → **完全跳过**（不运行任何阶段）
- `overall_state == "working"` 且 `reachability_mode == "desktop"` 或 `mobile_full_focus` → **仅限 light**（跳过 REM 和 deep）
- `overall_state` 为 (`meeting_people`, `outdoors`, `exercising`) → **仅限 light**
- `overall_state` 为 (`sleeping`, `resting`, `unknown`, `transitioning`) → **完全梦游**（允许所有阶段）
传递 `--force` 命令行参数以绕过门控并无论实时意图如何都运行所有阶段：
```bash
ide-agent-kit background run --config ide-agent-kit.json --force
```
### 通用轮询器环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `IAK_API_KEY` | （必填） | GroupMind API 密钥 |
| `IAK_ROOMS` | `thinkoff-development,feature-admin-planning,lattice-qcd` | 监视的房间 |
| `IAK_SELF_HANDLES` | `@claudemm,claudemm` | 代理自己的句柄（跳过自己的消息） |
| `IAK_TARGET_HANDLE` | `@claudemm` | 用于确认消息的句柄 |
| `IAK_OWNER_HANDLE` | `petrus` | 仅从此用户自动确认 |
| `IAK_TMUX_SESSION` | `claude` | 提示的 tmux 会话 |
| `IAK_POLL_INTERVAL` | `10` | 轮询之间的秒数 |
| `IAK_ACK_ENABLED` | `1` | 自动确认任务请求 (`1`/`0`) |
| `IAK_NUDGE_TEXT` | `check rooms` | 新消息时发送到 tmux 的文本 |
| `IAK_LISTEN_MODE` | `all` | 过滤器：`all`, `humans`, `tagged`, 或 `owner` |
| `IAK_BOT_HANDLES` | （空） | `humans` 模式下的机器人句柄以逗号分隔 |
| `IAK_FETCH_LIMIT` | `20` | 每次轮询每个房间的消息数 |
### Codex 智能轮询器环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `ANTIGRAVITY_API_KEY` | （除非设置了另一个候选项，否则必填） | GroupMind API 密钥 |
| `API_KEY_ENV_CANDIDATES` | `ANTIGRAVITY_API_KEY` | 检查 API 密钥的以逗号分隔的环境变量列表 |
| `AGENT_HANDLE` | `@antigravity` | 视为自己的句柄，并检测提及 |
| `POLLER_NAME` | `antigravity` | 用于日志记录、tmux 会话默认值和临时状态文件名 |
| `ROOMS` | `thinkoff-development,feature-admin-planning,lattice-qcd` | 以逗号分隔的监视房间列表 |
| `POLL_INTERVAL` | `8` | 轮询之间的秒数 |
| `FETCH_LIMIT` | `30` | 每个房间请求的消息数 |
| `MENTION_ONLY` | `0` | 导入模式：`0` 所有消息，`1` 仅限提及 |
| `SMART_MODE` | `1` | 启用 `codex exec` 真实响应生成 |
| `STATE_PREFIX` | `antigravity` | 锁定/已见/确认的临时文件的前缀，以便多个轮询器不会发生冲突 |
| `CODEX_WORKDIR` | 仓库根目录 | `codex exec` 的工作目录 |
| `CODEX_APPROVAL_POLICY` | `on-request` | Codex 智能回复的审批策略 |
| `CODEX_SANDBOX_MODE` | `workspace-write` | Codex 智能回复的沙盒模式 |
| `MAX_REPLY_AGE_SEC` | `900` | 跳过超过此年龄的旧消息 |
| `SKIP_PRESTART_BACKLOG` | `1` | 跳过进程启动前较旧的消息 |
注意：翻译时保留了技术名词和代码段落。
意图套件（）
用户意图套件（User Intent Kit，简称UIK）使代理程序（agents）能够感知用户的当前状态和。从v0.9.0版本开始，被集成到此仓库的`packages/user-intent-kit`目录下（仍然在npm上单独发布为`user-intent-kit`Python/Swift/Kotlin端口）。IAK通过`ent.mjs`直接使用它，该文件根据`配置块构建客户端：
```json
{
": {
"baseUrlhttps://groupmind.one1",
"apiKey": "<X-API the intent API>",
userId": "pet "deviceIdmac-mini",
"": "@claudemm",
"suppress_nud true
}
}
```
在存在此配置块时，以下所有内容将自动激活（在不存在时保持惰
- **后台 — `background run`合并运行前检查（参见上面的UIK- **事件丰富** — 进入的房间/直接获取完整的意图快照，位于 `intent` ，带有 30 秒的缓存，因此消息突发仅需一次 API 调用，而不是每个事件一次。
- **提示抑制** — `rooms watch` 仍然将每个消息写入通知文件，但在 `derived.urgency_mode` 为 `emergency-only` 时跳过 tmux/command 设置 `"suppress_nudges": false` 以选择退出。所有检查均失败打开：如果意图 API 关闭行为与以前一样。
intent` CLI** — `ide-agent-kit intent <get|derived|state|heartbeat|daemon在无需单独检出的情况下检查和发布状态。
的丰富 sidecar 时，它会在每个传入的上查询 Intent API，以获取用户设备、活动代理生行为信号的实时快照。
意图载荷
- **`devices`** 和 **`agents`**：哪些代理实例当前在线，以及它们最近的活动时间戳stale_devices`** / **`stale_agents`**和代理已保持其预期心跳窗口。
- **`derived.urg`**：计算出的紧急程度级别（`normal`、`focus`、`emergency-only代理可以使用它来决定是否打断用户或批量- **`derived.available_modalities`**：当前可用的例如 `["read"]`、`["read","]`），以便代理可以选择文本、语音输出。
- **`derived_device`**：用户活动的设备，或 `null` 如果没有明显的首选设备。
- **`derived.suppress_audio`**：是否应根据抑制音频通知。
代理可以使用这些信号来调整其，代理可能会在 `urgency_mode` 为 `-only` 时跳过发布非紧急状态更新，或者suppress_audio` 为 true 时将输出路由到文本而不是音频。
意图数据从 GroupMind API 的 `GET /intent/{userId}` 处获取，并注入到队列事件中的 `intent` 键下，`provider: "group。
#### 发布状态侧）
读取意图只是循环的一半。要在仪表板上保持您自己的设备和代理槽位活跃，请将内置发布者进程运行：bash
ide-agent-kit --config ide-agent # 使用 config.intent.*
npx uik-daemon # 独立等，INTENT_* 环境变量
```
IDE 代理用户意图工具为一起部署：IA消耗意图状态进行 gating，UIK 发布您自己的心跳。没有守护进程槽位将会过代理将把您线。
建议使用 v0.2.版本用于`uik-daemon`二进制文件。v0.2.0引入了守护进程，v0.2.1修复了示例文件中的静默退出问题，v0.2.2添加了心跳间隔上的代理状态重新发布，以便在守护进程运行时槽位0.2.2之前的守护进程正确发布设备状态，但位仍在其TTL后### 丰富要启用 sidecar（内存和意图）， `ide-agent-kit 中添加以下块```json
{
"intent": {
"": "https://groupmind.one/api/v1apiKey": "groupmind_your_key",
userId": "_id"
},
memory_api": {
"baseUrl": "http://127.0.0:37777/api "token": "your_mem_token"
}
}
```
*注意：存在并在配置，但它是可选的。如果省略 `intent` 块，队列事件将回退位符 `intent载荷，并且不会 UIK 数据。*
后，每个队列房间事件都可以扩展为：
- `intent`: 由 `GET /intent/{userId}` 返回的完整 JSON 有效，加上 `provider: ""`。
- `memory_context.raw`: Claude-M搜索返回的文本。
- `en_errors`: 调用任一上游服务时遇到的模式问题。
当前的 Claude-Mem 上下文是基于消息驱动每个传入的房间 sidecar 使用消息正文作为搜索查询，并调用```text
GET {memory_api.baseUrl}/search/observations?query=<message body>&limit=3
Authorization: Bearer <memory_api.token>
```
响应应为样式的 JSON：
```json
{
": [
{": "text", "text": "..." }
```
所有返回的` 条目为 `"text"`被复制到 `.raw` 中。这是的 Claude-Mem 观察结果线程回队列事件下游代理使用的方法事件示例：
{
"kind": "groupmind.message.created",
"payload": {
"body": "can we ship the release notes today?",
"room": "-development"
},
intent": {
_id": "pet "derived": {
"urgency_modeergency-only"
},
"provider": "groupmind"
},
"memory_context": {
"raw": [
"Recent Claude-Mem observation text"
]
},
"enrichment_errors": []
}
```
### 验证丰富
在调试轮询器之前，两个上游集成：
```bash
# 1. 意图 HTTP 200curl -i \
"Authorization:mind_your_key "https://.one/api/v1/intour_user_id 2. Claude 查找应返回 HTTP 200 JSON，带有 数组
curl -i -H "Authorization your_claude_mem \
"http://127.0.0.1:37777/api/search/observations?query=release%20notes&limit=3"
```
从 Petrus 机器上的最新本地验证，针对 `v0.6.1` 进行验证：
- `GET /intent/petrus` 在 `2026-04-08` 返回 `200`，带有 `agents=[claudemb, claudemm]` 和 `devices=[macbook, mac-mini]`，二者在 UIK v0.2.2 部署后均活跃且无空闲槽位。
- `GET /api/search/observations=thinkoff&3` 在 `2026-03-31` 返回 `200`（自 v0.5.0 以来，claude-mem 路径未更改）。
## 集成
### MCP 服务器（`src/mcp-server.mjs`）
将 IAK 的 tmux 支持的唤醒/列出/运行基元作为 MCP 工具公开，以便任何 MCP 感知客户端（Claude Desktop/Code、Cursor、自定义代理）可以直接驱动代理舰队，而无需重新实现 tmux send-keys。
公开的工具（stdio
| 参数 | 备注 --- | --- || `wake` | `session`text?`（默认为 rooms"`） | 在命名的 tm话中发送提示按 Enter。 |
list_sessions （无） |上每个活动的 tm话及其附加状态计数。 |
|ake_all` |?`（默认为 `"check rooms"`） | 向 IAK 已知的每个会话发送相同的提示（每个/失败）。通过 `mcp.sessions: ["...", ...]` 配置。回退到 `tmux.ide_session` + `tmux.default_session`。 |
| `read_session` | `session`，`lines?`（默认为 50） | 命名的会话的 `tmux capture-pane` — 查看代理对 `wake_ide` 的响应。 |
| `tmux_run` | `cmd`，`session?`，`cwd?`，`timeoutSec?` | 在 tmux 会话中运行命令。** `tmux.allow非空或设置mcp.allow_un true` 时才** 否则完全中省略（关闭失败）。与 CLItmux run`相同的允许列表。 MCP 特定配置键
添加到 `ide-agent`（或通过 `--config` 传递的自定义配置文件路径）：
```jsonc
{
"mcp": {
// `wake_all` 应针对的会话的显式列表。
// 如果省略，则回退到 [tmux.ide_session, tmux.default_session]。
"sessions": ["claudemb", "antigravity", "codex"],
// 设置为 true 以公开具有无允许列表过滤器的 tmux_run — 任何命令都会运行。
// 默认：false。仅在具有受信任客户端的受信任主机上使用。
"allow_unrestricted": false,
// 用户确认流程（request_confirmation、list_intents、
// approve_intent、deny_intent 工具）。仅当配置至少一个通道时注册工具。
"": {
" 8788 // /intent/:decision 的 HTTP 端 "host":0.0.1", //主机（除非，否则保持本地）
_token": "", HTTP 端点的可选 "callback "http://...", 监视/聊天回呼的 URL；://host:port
"room": "", // 在 GroupMind 房间（使用 poller.api_key）
"_gate_url": "http://family@localhost:/intent",
watch_gate_token": "" // CLAWWATCH_GATE 的 bearer
}
}
```
### 确认流程（`request_confirmation` 工具）
当配置了 `mcp` 时，会出现四个额外的工具：
| 工具 | 参数 | 备注 |
| --- | --- | --- |
| `request_confirmation` | `prompt`，`session?`，`channels?`，`timeoutSec?`，`from` | 向 GroupMind 和/或 发布“批准”/“拒绝”提示并阻塞，直到用户决定或超时。返回 `{decision: "approve"\|"deny"}` 或 `{status: "timeout", id}`。`fromHandle` 默认为 `poller.handle` 以进行正确的代理归属。 |
| `list_intents` | （无） | 所有意图 — 待处理和最近决定的。 |
| `approve_intent` | `id` | 手动解决待处理意图（例如 MCP 重叠）。 |
| `deny_intent` | `id` | |
非 MCP 代理可以通过 CLI 使用相同的共享确认守护进程：
```bash
node bin/cli.mjs confirm request \
--config /path/to/ide-agent-kit.json \
--prompt "Approve destructive command?" \
--session codex \
--channels groupmind \
--from @CodexMB \
--wait
node bin/cli.mjs confirm list --config /path/to/ide-agent-kit.json
```
请求命令发布到实时守护进程的 `/intent` 端点，因此 CodeWatch 轮询 `/intents` 会在匹配的 IDE 通道（例如 `session=codex...` 映射到 `@CodexMB`）和手机/手表“批准”/“拒绝”按钮解决相同的意图。`--wait` 会阻塞直到决策或超时。
端到端：
1. MCP 感知代理调用 `request_confirmation({prompt: "Drop production DB?"})`。
2. IAK MCP 服务器发布到 GroupMind 房间（/approve <id> / /deny <id> 快速回复）和 CLAWWATCH_GATE（带有“批准”/“拒绝”按钮的 Android 交互式通知，振动手表）。
3. 用户在手表上点击“批准”/“拒绝” — 的通知操作发布到 `http://<callback_base>/intent/<id>/decision`，带有 `{decision: "approve"}`。
4. MCP 工具的阻塞 `request_confirmation` 调用使用决策解析. 代理根据决策继续（或不继续）。
独立运行：
```bash
node bin/iak-mcp.mjs # 默认配置
node bin/iak-mcp.mjs --config/to/config.json
npm run mcp # 通过 package.json 脚本
```
与 Claude Desktop / Code 集成：
```json "mcpServers": {
"": {
"command": "node",
"args":absolute/path/to/ide-agent-kit/bin/icp.mjs }
}
}
后：重启 MCP 客户端。上述四个工具选择器中，可以直接调用。
### Webhooks（`hook-server.m）
接收 GitHub webhook 事件，验证 HMAC 签名，将其规范化为稳定的 JSON 模式，并追加到L 队列。可选地，在事件到达时提示 tmux 会话。
支持的事件：`pull_request.opened`、`pull_request.synchronize`、`pull_request.closed`、`push`、`issue_comment.created`、`issues.opened`。
```bash
webhook 服务器
node bin/cli.mjs serve --port 8787 配置 GitHub webhook 发送到：
http://your-host:8787/webhook配置中 密钥以进行 HMAC 验证
# webhook 也接受以下# http-host:8787
```
配置键：`listen.port`hook_secret`、`github.event_kinds`、`queue.path`。
Claw 机器人舰队（`src/openclaw-*.mjs`）
用于通过其 CLI 管理 [OpenClaw](https://openclaw.dev) 多代理机器人舰队的五个模块。由于 OpenClaw 网关使用 WebSocket（而非 HTTP）进行 RPC，因此所有模块都使用 `openclaw` CLI，可选地通过 SSH 进行跨用户设置。
**为什么这** OpenClaw 代理作为长期运行，具有自己的模型、内存和工具访问权限代理工具包了这些代理 IDE 工作流之间的差距 — 允许房间消息触发代理操作，代理之间流动的回执，以及从单个 CLI 进行舰队操作。
**网关** 模块（`src/openclaw-gateway.mjs`）处理启动、停止和重启 OpenClaw 网关，包括深度健康检查。使用它来确保在触发自动化舰队已启动。
```bash
# 检查网关健康状况
node bin/cli.mjs gateway health
node bin/cli.mjs gateway health-deep
# 列出活动代理
node bin/cli.mjs gateway agents
# 重启网关（例如，配置更改后）
node bin/cli.mjs gateway config-patch --json '{"key": "value"}'
```
**会话** 模块（`src/openclaw-sessions.mjs`）向代理发送消息并列出活动会话。使用它进行代理到代理的通信 — 例如，请求一个代理审查另一个代理的工作。
```bash
# 向特定代理发送消息
node bin/cli.mjs gateway trigger --agent ether --message "review PR #6"
# 唤醒所有代理
node bin/cli.mjs gateway wake --text "new deployment ready" --mode now
```
**执行审批** 模块（`src/openclaw-exec.mjs`）为代理命令执行提供了一个治理层。它管理一个审批队列（待处理、允许、拒绝），并从 `~/.openclaw/exec-approvals.json` 读取 OpenClaw 的原生每个代理、基于通配符的执行审批允许列表。
**钩子** 模块（`src/openclaw-hooks.mjs`）为代理注册和管理事件钩子。支持的事件包括 `message:received`、`message:sent`、`command:new`、`command:reset`、`command:stop`、`agent:bootstrap` 和:startup`。钩子可以放置workspace/hooks/` 下的每个代理或共享在 `~/.openclaw/hooks/` 下。
**Cron** 模块（`src/openclaw-cron.mjs`）处理调度任务管理，允许您为任何代理列出和删除 cron 任务。
```# 列出 cron 作业
node bin/cli.mjs cron list
定时轮询
node bin/cli.m add --name "hourly-comments" --task "poll GitHub comments" --schedule "0 * * * *"
```
**示例：完整的 OpenClaw 代理工具包工作流程**
GroupMind 房间消息到达 →自动化匹配规则
2. 规则触发 `gateway trigger --agent ether --deploy staging"`
3. Ether 代理运行部署，写入回执
4执追加到 JSONL 日志，带有跟踪 ID
5. 评论器检测到对部署 PR 的新 GitHub 评论
6. IDE tmux 提示审查评论
# OpenClaw 配置（在团队中继配置文件中）
{
"openclaw": {
"home": "/path/to/openclaw",
"bin": "/opt/homebrew/bin/openclaw "ssh": "family@localhost"
}
}
```
### 房间自动化（`src/room-automation.mjs`）
基于 GroupMind 房间消息的规则自动化。定义匹配条件（关键词、发件人、房间、正则表达式、提及）和有界动作（发布到房间、执行命令、提示 tmux）。每个动作都会产生回执。包括冷却和仅首匹配模式，以防止级联。
```bash
# 启动自动化引擎
node bin/cli.mjs automate thinkoff-development --api-key $KEY --handle @mybot
# 配置文件中的规则（ide-agent-kit.json）：
{
"automation": {
"rules": [
{ "name": "greet", "match": { "sender": "petrus", "keywords": ["hello"] }, "action": { "type": "post", "room": "${room}", "body": "Hello!" } },
{ "name": "deploy", "match": { "mention": "@mybot", "regex": "deploy|ship" }, "action": { "type": "nudge", "text": "check rooms" } }
]
}
}
```
#### 多智能体路由（以房间为工具总线）
相同的 `automation.rules` 模式在每个智能体运行自己的 IAK 实例并拥有自己的规则集时，作为每个智能体的权限表。常见的多智能体配置：
```json
{
"automation": {
"rules": [
{ "name": "自我唤醒", "match": { "mention": "@claudemb" }, "action": { "type": "nudge", "text": "检查房间" } },
{ "name": "总结总线", "match": { "mention": "@claudemb", "regex": "summari[sz]e|recap" }, "action": { "type": "exec", "command": "node bin/cli.mjs summarize ${room}" } },
{ "name": "部署门控", "match": { "sender": "petrus", "mention": "@claudemb", "regex": "deploy|ship|release" }, "action": { "type": "nudge", "text": "部署当前分支" } },
{ "name": "忽略确认", "match": { "mention": "@claudemb", "regex": "^(ok|thanks|got it)\\.?$" }, "action": { "type": "post", "body": "" } }
]
}
}
```
每条规则限定哪些消息到达哪个动作：`match` 过滤发送者、房间、提及、关键词、正则表达式；`action.type` 约束副作用（`post` / `exec` / `nudge`）。如果消息不匹配任何规则，则被忽略。要限制智能体为只读行为，请从其配置中删除所有 `exec` 和 `nudge` 规则，只保留 `post` 规则。
对于临时多智能体调度（一个房间，多个智能体响应不同的提及），为每个智能体的 IAK 实例提供以其自己的 `@handle` 为键的规则。 正文中的提及模式是路由键；每个智能体读取相同的房间，但执行其自己的切片。
### 评论轮询（`src/comment-poller.mjs`）
轮询 Moltbook 帖子和 GitHub 问题/讨论中的新评论。 将新评论写入事件队列并可选地提示 IDE tmux 会话。
```bash
# 一次性轮询
node bin/cli.mjs comments poll --config ide-agent-kit.json
# 长运行的监视器
node bin/cli.mjs comments watch --config ide-agent-kit.json
# 配置：
{
"comments": {
"moltbook": { "posts": ["uuid1", "uuid2"] },
"github": { "repos": [{ "owner": "org", "repo": "name", "type": "issues" }] },
"interval_sec": 120
}
}
```
### Moltbook（`src/moltbook.mjs`）
通过挑战-验证流程发布到 [Moltbook](https://www.moltbook.com)，读取订阅源，并轮询评论。 支持 submolt 目标和可配置的基础 URL。
```bash
# 发布到 Moltbook
node bin/cli.mjs moltbook post --content "来自我的智能体的问候" --api-key $KEY
# 读取订阅源
node bin/cli.mjs moltbook feed --limit 10
```
### GroupMind 聊天室（`scripts/room-poll*.`）
参见上面的 [房间轮询器](#房间轮询器)。 通过 [groupmind.one](https://groupmind.one) 上的共享聊天室提供实时多智能体通信。
### Discord 频道（`src/discord-poller.mjs`）
通过 OpenClaw CLI（`openclaw message read --channel discord`）轮询 Discord 频道中的新消息。 将事件写入 JSONL 队列，源为 `"discord"`，类型为 `"discord.message.created"`。 Webhook 服务器还接受 Discord 事件，路径为 `POST /discord`。
需要 OpenClaw 2026.2.25+，并启用 Discord 插件。
```bash
# 一次性轮询
node bin/cli.mjs discord poll --config ide-agent-kit.json
# 长运行的监视器
node bin/cli.mjs discord watch --config ide-agent-kit.json
```
配置：
```json
{
"discord": {
"channels": [
{ "id": "1474426061218386094", "name": "general" }
],
"interval_sec": 30,
"self_id": "1474422169470636134",
"skip_bots": false
}
}
```
### ACP — 智能体客户端协议（`src/acp-sessions.mjs`）
用于多智能体团队的结构化任务编排。 ACP 在基于房间的聊天基础上添加了会话生命周期：分配任务、跟踪进度、关闭并确认。 默认情况下安全（禁用、令牌保护、允许列表、仅限本地主机）。
```bash
# 1. 向智能体分配任务
node bin/cli.mjs acp spawn --agent @claudemm --task "审查 PR #42"
# => 会话已创建：a1b2c3d4
# 2. 在任务中添加上下文
node bin/cli.mjs acp send --session a1b2c3d4 --body "关注身份验证更改" --from @ether
# 3. 检查进度
node bin/cli.mjs acp list --status active
# 4. 完成后关闭
node bin/cli.mjs acp close --session a1b2c3d4 --reason "已合并"
```
也可通过 webhook 服务器上的 `POST /acp` 使用（通过 `X-ACP-Token` 头进行令牌身份验证）。 每个操作都有确认，包括拒绝的请求。
```json
{
"acp": {
"enabled": false,
"token": "your-secret-token",
"allowed_agents": ["@claudemm", "@ether"],
"session_timeout_sec": 3600,
"max_concurrent_sessions": 5,
"sessions_file": "./data/acp-sessions.json"
}
}
```
#### ACP + IDE 智能体套件在标准 ACP 之上添加的内容
标准 ACP 设计用于 1 个 IDE 控制 1 个智能体通过 CLI。 IDE 智能体套件将其扩展到生产环境中的多智能体团队：
1. **多智能体，多 IDE** -- 跨不同机器上的 N 个 IDE（Claude Code、Codex、Gemini）协调通过共享房间 + ACP 会话的 N 个智能体。
2. **跨服务消息投影** -- ACP 会话绑定到跨 GroupMind、xfor 和 AgentPuzzles 的统一消息。 所有平台上都可以看到任务确认。
3. **房间感知上下文** -- ACP 会话引用房间线程。 智能体从 ACP 接收任务，在房间中讨论，关闭带有确认的会话，链接回对话。
4. **操作策略层** -- 令牌保护的允许列表、每个会话的消息上限、超时强制执行和对拒绝请求的确认轨迹超越 ACP 的内置权限模式。
5. **OpenClaw 机队桥** -- ACP 会话可以通过现有的 CLI 触发 OpenClaw 网关智能体。 ACP 处理任务路由，OpenClaw 智能体处理执行。
ACP 为我们提供了协议。 IDE 智能体套件为我们提供了多智能体、多表面、确认执行的层。
### 其他模块
**确认** (`src/receipt.mjs`) 提供一个带有跟踪 ID 和幂等键的只追加 JSONL 确认日志，用于审计每个操作。 **发出** (`src/emit.mjs`) 将确认或任意有效载荷发送到外部 webhook URL。 **内存** (`src/memory.mjs`) 为智能体提供跨会话的持久键值存储。 **会话保持活跃** (`src/session-keepalive.mjs`) 管理 macOS `caffeinate` 以防止在长时间运行的远程会话期间显示和空闲睡眠。 **tmux 运行器** (`src/tmux-runner.mjs`) 在 tmux 会话中执行允许列表命令并捕获输出。 **监视** (`src/watch.mjs`) 监视 JSONL 队列文件是否有更改。
## 命名约定（固定）
- JSON 字段（事件、确认、配置）：**下划线命名**
- CLI 标志：**连字符命名**（内部映射到下划线命名）
## CLI
```
ide-agent-kit serve [--config <path>]
ide-agent-kit automate --rooms <rooms> --api-key <key> --handle <@handle> [--interval <sec>]
ide-agent-kit comments <poll|watch> [--config <path>]
ide-agent-kit discord <poll|watch> [--interval <sec>] [--config <path>]
ide-agent-kit poll --rooms <rooms> --api-key <key> --handle <@handle> [--interval <sec>]
ide-agent-kit moltbook <post|feed> [--content <text>] [--api-key <key>]
ide-agent-kit tmux run --cmd <command> [--session <name>] [--cwd <path>] [--timeout-sec <sec>]
ide-agent-kit emit --to <url> --json <file>
ide-agent-kit receipt tail [--n <count>]
ide-agent-kit gateway <health|agents|trigger|wake> [options]
ide-agent-kit memory <list|get|set|append|delete|search> [options]
ide-agent-kit init [--ide <claude-code|codex|cursor|vscode|gemini>] [--profile <balanced|low-friction>]
ide-agent-kit acp <spawn|list|status|send|close> [options]
ide-agent-kit keepalive <start|stop|status> [--pid-file <path>] [--heartbeat-sec <sec>]
```
## 配置
参见 `config/team-relay.example.json` 获取完整的配置结构。 关键部分：
- `listen` - webhook 服务器的主机/端口
- `queue.path` - 规范化事件追加的位置（JSONL）
- `receipts.path` - 追加操作确认的位置（JSONL）
- `tmux.allow` - 命令允许列表（前缀匹配）
- `tmux.default_session` - tmux 会话名称
- `tmux.nudge_text` - 唤醒脚本输入到 IDE 的内容（默认为 `check rooms`）
- `tmux.ide_session` - 您的 Claude Code（或其他 IDE）实例的 tmux 会话名称 - `wake_ide` MCP 工具以此为目标
- `github.webhook_secret` - 签名验证的 HMAC 机密
- `github.event_kinds` - 接受的 GitHub 事件
- `poller.api_key` - 房间轮询器 + 聊天回复轮询器在 `iak-mcp-daemon` 中使用的 GroupMind API 密钥
- `mcp.sessions` - `wake_all` MCP 工具针对的 tmux 会话列表
- `mcp.confirmations` - 确认注册设置（由 `iak-mcp-daemon` 使用）：
- `port` - HTTP 监听端口（默认为 `8788`）；还为浏览器提供批准/拒绝 UI，路径为 `/`
- `host` - 绑定地址（默认为 `127.0.0.1`；使用 `0.0.0.0` 以使 LAN 可访问的手机/手表/其他 Mac 可以访问 `/intent`、`/wake`、`/intents`）
- `room` - GroupMind 房间 slug，发布确认请求到（也是聊天回复轮询器监视 `/approve <id>` 和 `/deny <id>` 的地方）
- `callback_base` - 此守护进程的公共 URL（例如 `http://192.168.50.240:8788`）- 用于聊天帖和浏览器 UI 的链接
- `auth_token` - 可选的承载令牌保护 `POST /intent/:id/decision` 和 `POST /intent`
- `wake_script` - 唤醒脚本的路径；默认为存储库中的 `scripts/claudemb-wake.sh`。 由 `POST /wake` 和 `wake_remote` MCP 工具使用
- `peers` - `@handle` → 守护进程 URL 的映射，在对等机器上；房间轮询器的 `wake-on-mention.sh` 在看到新房间消息中的 `@handle` 时，将 `/wake` 发布到匹配的对等节点。 示例：
```json
"peers": {
"@claudemm": "http://192.168.50.241:8788",
"@CodexMB": "http://192.168.50.241:8788"
}
```
- `codewatch_gate_url` / `codewatch_gate_token` - 旧版 CodeWatch 中继路径（与 Wear OS 桥接器分开，Wear OS 桥接器随 CodeWatch Android 应用一起提供）
### 低摩擦配置文件
当您希望对例行非破坏性命令的 manual accept 提示更少时，请使用 `low-friction` 配置文件。
```bash
node bin/cli.mjs init --ide codex --profile low-friction
```
此配置文件扩展了 `tmux.allow` 以包括常见的读取/构建/测试命令（`rg`、`ls`、`cat`、`git log/show`、`npm run lint/typecheck/test` 等），同时默认仍排除破坏性命令。
## 模式
- `schemas/event.normalized.json` - 规范化的传入事件
- `schemas/receipt.json` - 操作确认
## 测试
```bash
node --test test/*.test.mjs
```
## 示例流程
参见 `examples/flow-pr-opened.md` 获取完整的 PR → 测试 → 确认演练。
## 许可证
GNU Affero 通用公共许可证 v3.0（AGPL-3.0）。 有关详细信息，请参见 [LICENSE](LICENSE)。
所有源文件都包含 `SPDX-License-Identifier: AGPL-3.0-only`。
## GroupMind 助手
- `examples/flow-pr-opened.md` — 示例 PR-opened 事件流程。
使用 `gemini -p` 带有硬超时以防止卡住的轮询循环。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器