Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .agents/plugins/marketplace.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "codex-with-zcode",
"interface": {
"displayName": "Multi-Agent Mailbox · 多智能体信箱"
"displayName": "文枢 · Post-Core"
},
"plugins": [
{
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ permissions:
jobs:
test:
runs-on: windows-latest
timeout-minutes: 15
timeout-minutes: 20
steps:
- uses: actions/checkout@v6
with:
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -22,3 +22,4 @@ modules/agent-core/docs/
*.vsix
host-config.json
binding.json
.codex/
6 changes: 0 additions & 6 deletions .zcode/acp/sandbox.json

This file was deleted.

2 changes: 1 addition & 1 deletion DEPENDENCY_AUDIT.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Audited on 2026-09-05 from `https://registry.npmjs.org`, without executing packa
The downloaded tarballs reproduced those SHA-512 values. Neither direct package declares an install lifecycle script; the lockfile records transitive packages.

- MCACP bundles registry search/install/uninstall/upgrade and merges user/system agent configuration. The gateway hides those tools, fixes lifecycle calls to `agentId: "zcode"`, and uses an empty registry list.
- `zcode-acp-server` reads ZCode's configured credentials from `(HOME || USERPROFILE)/.zcode/v2/config.json` and starts local `zcode app-server --stdio`. This plugin neither copies nor logs those values. On this host, child-only `HOME` and `ZCODE_DATA_BASE_DIR` point to `E:\Programming\IDE`; Windows `USERPROFILE` remains unchanged so the existing shared CLI session database stays in its original location.
- `zcode-acp-server` reads ZCode's configured credentials from `(HOME || USERPROFILE)/.zcode/v2/config.json` and starts local `zcode app-server --stdio`. This plugin neither copies nor logs those values. Keep ACP credentials and native CLI session storage separate when configuring child-only environment overrides.
- Correction from the 2026-09-07 profile investigation: the dependency's `tasks-index.js` directly opens the adjacent `tasks-index.sqlite` to register newly created sessions and update titles. Its initial `completed` index value is not a runtime completion signal. The gateway does not write this database itself, but the end-to-end creation path is not SQLite-write-free.
- Its remote and quota features are not used: the configuration uses only `server`, clears remote variables, sets `ZCODE_ACP_REMOTE=0`, and supplies no remote token.
- MCACP's Windows transport uses `shell: true` and emits Node's `DEP0190` warning. The configured agent command is the fixed token `node` with fixed package arguments; workspace paths travel only as JSON-RPC data, never as shell arguments.
Expand Down
13 changes: 10 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
[English](README.md) | [简体中文](README.zh-CN.md)

# Multi-Agent Mailbox · 多智能体信箱
# 文枢 · Post-Core

The local multi-agent mailbox is named **文枢** (Post-Core). Its product adapters are **小洞** (Post-Qoder-Dong), **小折** (Post-Zcode-Zhe), and **小元** (Post-Chat-Yuan). Claude Code and Kimi Code connect directly through the same Core MCP implementation, without dedicated plugins. Existing package IDs, tool names, queue owners and data paths remain compatible.

[![CI](https://github.com/WQMYH/multi-agent-mailbox/actions/workflows/ci.yml/badge.svg)](https://github.com/WQMYH/multi-agent-mailbox/actions/workflows/ci.yml)
[![Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
Expand All @@ -22,11 +24,13 @@ This is not another agent client or global scheduler. An agent does **not** need

## Tested agents and compatibility

Native evidence is current through **2026-10-01**, on Windows. Product versions describe observations, not a version allowlist: inspect capabilities and investigate version changes when a route fails.
Native evidence includes scoped tests through **2026-10-12**, on Windows; see [per-case scope](docs/compatibility.md). Product versions describe observations, not a version allowlist: inspect capabilities and investigate version changes when a route fails.

| Agent | Generic mailbox tested | Dedicated integration tested |
| --- | --- | --- |
| Codex | Send, receive, correlated reply and exact confirmation | Three-tool MCP and matching CLI |
| Claude Code | Direct Core MCP receive, correlated reply and both confirmations; existing DeepSeek Flash route | No dedicated plugin required |
| Kimi Code | Persistent native Core MCP receive, correlated reply and both confirmations; existing DeepSeek Flash route | No dedicated plugin required |
| pi | Native mail tools; pi → Qoder → the same pi session | No dedicated plugin required |
| Qoder CN standalone | Real receive/reply in the pi ↔ Qoder mail loop | Session creation/send, FIFO, multi-session/multi-turn returns and explicit crash recovery |
| ZCode CLI | **Codex ↔ the same native ZCode CLI session**, receive/reply/confirmation, no Sharing Link | Uses its existing command tool; no mail-specific ZCode plugin |
Expand All @@ -35,7 +39,7 @@ Native evidence is current through **2026-10-01**, on Windows. Product versions

**Other agents are generally interface-compatible** if they can execute the Node CLI or use MCP. They are not individually certified by this table. A small specialized adapter can add native wakeup, session targeting or Hooks; reuse Core and the existing queue rather than another message state machine.

Mail is **pull-based**, not automatic product wakeup. ZCode's no-link test covers a new native CLI session with explicit resume. Control of an **existing ZCode desktop conversation** through `agent-zcode` still uses its Sharing Link. These are separate channels.
Mail keeps durable pull routes. Explicit native receiver connections can also notify the selected existing session; Kimi ↔ Codex fresh notifications, actual fetches, correlated replies and exact confirmations were accepted in a scoped native test on 2026-10-11. Receiver support and native approval remain product-specific. ZCode's no-link test covers a new native CLI session with explicit resume. Control of an **existing ZCode desktop conversation** through `agent-zcode` still uses its Sharing Link. These are separate channels.

## Quick start: mailbox only

Expand Down Expand Up @@ -72,11 +76,14 @@ Keep the returned `ownerId`, `target`, `consumers` for that logical session. Use
| `agent-core` | Shared CLI/MCP and module lifecycle | [Core](modules/agent-core/README.md) |
| `agent-mail` | Generic pull mailboxes | [Mail](modules/agent-mail/README.md) |
| `agent-qoder` | Standalone session control and its product queue | [Qoder](modules/agent-qoder/README.md) |
| `agent-qoder-wake` | Native QoderWake CN CLI/daemon control (experimental; distinct from standalone and IDE) | [Wake](modules/agent-qoder-wake/README.md) |
| `qoder-codex-bridge` | Optional Qoder Hooks, result attribution and Codex return | [Return plugin](qoder-codex-bridge/README.md) |
| `agent-qoder-ide` + `qoder-ide-bridge` | Authenticated IDE command/page bridge | [IDE](qoder-ide-bridge/README.md) |
| `agent-zcode` | ZCode desktop control via native remote mechanism | [ZCode](modules/agent-zcode/README.md) |
| `zcode-codex-bridge` | Fixed-target Codex status/notification from ZCode | [Companion](zcode-codex-bridge/README.md) |

The shared [post-core-mail skill](modules/agent-core/skills/post-core-mail/SKILL.md) guides agents to keep one Core instance, fetch actual bodies, correlate replies, confirm exact batches and preserve unknown requests. Installation is separate from actual session adoption. Wake keeps its own native state rather than using the Qoder CN SDK/CDP; native Session events do not confirm Core Mail consumption.

Codex's native plugin entry:

```powershell
Expand Down
13 changes: 10 additions & 3 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
[English](README.md) | [简体中文](README.zh-CN.md)

# 多智能体信箱 · Multi-Agent Mailbox
# 文枢 · Post-Core

文枢是本机多智能体信箱的公共基底,英文名为 Post-Core。专用入口命名为:Qoder「小洞」(Post-Qoder-Dong)、ZCode「小折」(Post-Zcode-Zhe)、ChatGPT「小元」(Post-Chat-Yuan)。Claude Code 和 Kimi Code 直接接入同一文枢 MCP 实现,不建立专属插件。现有安装标识、工具名、队列 owner 与数据路径保持兼容。

[![CI](https://github.com/WQMYH/multi-agent-mailbox/actions/workflows/ci.yml/badge.svg)](https://github.com/WQMYH/multi-agent-mailbox/actions/workflows/ci.yml)
[![Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
Expand All @@ -22,11 +24,13 @@

## 已测智能体与兼容性

以下实机范围截至 **2026-10-01**,操作系统为 Windows。产品版本仅记录环境,**不是强制白名单**;先检查能力,在调用失效时再核对更新影响。
以下记录包含截至 **2026-10-12** 的限定实机验证,逐项范围见[兼容说明](docs/compatibility.md),操作系统为 Windows。产品版本仅记录环境,**不是强制白名单**;先检查能力,在调用失效时再核对更新影响。

| 智能体 | 通用信箱实测 | 专用适配实测 |
| --- | --- | --- |
| Codex | Core 发信、收信、关联回复、精确确认 | 三工具 MCP 与同实现 CLI |
| Claude Code | 直接 Core MCP 真实收信、关联回信、双方确认;沿用已有 DeepSeek Flash 配置 | 不需要专用插件 |
| Kimi Code | 持久登记原生 Core MCP,真实收信、关联回信、双方确认;沿用已有 DeepSeek Flash 配置 | 不需要专用插件 |
| pi | 原生 mail 工具;pi → Qoder → 同一 pi 会话闭环 | 不需要专用插件 |
| Qoder CN 独立版 | pi ↔ Qoder 闭环真实收信、回信 | 创建/发送、FIFO、多会话/多轮回传、崩溃后显式恢复 |
| ZCode CLI | **Codex ↔ 同一原生 CLI 会话**收信、回信、确认,无 Sharing Link | 使用原生命令工具,无需专用 mail 插件 |
Expand All @@ -35,7 +39,7 @@

**其他智能体基本具备接口兼容条件**:能运行 Node CLI 或作为 MCP 客户端接入即可。未逐款实测,不将接口兼容当作全部产品认证。需要原生唤醒、会话定位或 Hooks 时可配备最小专门化插件;复用 Core/现有队列,不叠加第二套发送状态机。

通用 mail 是**拉取型信箱,不自动唤醒产品**。ZCode 无 link 测试是新原生 CLI 会话和显式接续;`agent-zcode` 对**桌面已有会话**的控制仍需 Sharing Link。两条通道分别标注。
通用 mail 保留持久拉取路线。明确接线的原生 receiver 也可通知指定既有会话;2026-10-11 的限定原生验收已通过 Kimi ↔ Codex fresh 通知、实际取信、关联回信与精确确认。receiver 支持和原生审批须按产品分别核实。ZCode 无 link 测试是新原生 CLI 会话和显式接续;`agent-zcode` 对**桌面已有会话**的控制仍需 Sharing Link。两条通道分别标注。

## 最小安装:只用信箱

Expand Down Expand Up @@ -72,11 +76,14 @@ node /absolute/path/to/multi-agent-mailbox/modules/agent-core/src/mcp-server.mjs
| `agent-core` | 公共 CLI/MCP、生命周期 | [Core](modules/agent-core/README.md) |
| `agent-mail` | 通用信箱 | [Mail](modules/agent-mail/README.md) |
| `agent-qoder` | 独立版控制与产品队列 | [Qoder](modules/agent-qoder/README.md) |
| `agent-qoder-wake` | QoderWake CN 原生 CLI/daemon 控制(实验模块;与独立版、IDE 分开) | [Wake](modules/agent-qoder-wake/README.md) |
| `qoder-codex-bridge` | Qoder Hook、结果归属、回传 Codex | [回传](qoder-codex-bridge/README.md) |
| `agent-qoder-ide` + `qoder-ide-bridge` | 认证窗口、命令和当前页交互 | [IDE](qoder-ide-bridge/README.md) |
| `agent-zcode` | ZCode 桌面端原生远程控制 | [ZCode](modules/agent-zcode/README.md) |
| `zcode-codex-bridge` | ZCode → 固定 Codex 目标状态/通知 | [回传](zcode-codex-bridge/README.zh-CN.md) |

智能体收发指导见 [post-core-mail skill](modules/agent-core/skills/post-core-mail/SKILL.md):保持同一 Core 实例、读取实际正文、按原信关联回信并精确确认,不重放未知请求。skill 安装与运行会话实际采用分开验证。Wake 使用自己的原生产品状态,不复用 Qoder CN 的 SDK/CDP;原生 Session 事件不是公共信箱的消费确认。

Codex 原生插件入口:

```powershell
Expand Down
92 changes: 92 additions & 0 deletions docs/chat-tunnel-startup.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
# Chat Tunnel 启动

Windows 上使用仓库启动器,不再在启动命令里写死代理端口:

```powershell
node scripts/start-chat-tunnel.mjs <tunnel-client.exe路径> <原有profile名或YAML文件路径> <已授权read-config路径>
```

启动器依次验证进程/用户环境中的 HTTP(S) 代理、Windows 当前启用的手动代理,以及直连。使用无密钥的 OpenAI HTTPS 请求验证连接;不会调用模型。系统代理端口变化时下次启动重新读取,不扫描任意本机端口,也不修改系统或用户环境变量。

只将有效路由传给这次 Tunnel 进程。全部连接失败时不启动;启动时连通不等于 Tunnel 鉴权、云端会话或本地主机工具已经可用,还须检查真实调用。密钥复用进程环境或用户变量中的 `OPENAI_API_KEY`,不写入启动参数或诊断。

保留原 profile、Tunnel ID、读取范围和消息记录。profile 内不要另写固定代理,避免与自动探测冲突。此入口不替代原生 `tunnel-client`;以后应通过它启动,直接运行原生客户端不会执行探测。运行中切换端口不热迁移连接,需重新启动该 Tunnel;不重启 Codex 或其他应用。仅 PAC/WPAD、SOCKS 或带用户名密码的代理不由此启动器自动解析;无有效 HTTP(S) 代理时尝试直连,直连也失败则明确停止。

## 按需启动与故障恢复

在现有 registry 同目录放置本机 `chat-tunnel.json`,或显式设置
`AGENT_CORE_CHAT_TUNNEL_CONFIG`。此文件仅包含路径,不包含密钥:

```json
{
"schemaVersion": 1,
"client": "C:/existing/tunnel-client.exe",
"profile": "C:/existing/profile.yaml",
"launcher": "C:/mailbox/scripts/start-chat-tunnel.mjs",
"readPolicy": "C:/existing/read-scope.json",
"stateDir": "C:/existing/tunnel-runtime",
"healthUrlFile": "C:/existing/health.url"
}
```

Core CLI 的 `discover/read/act`、Core MCP 的初始化及工具调用会按需确保一个后台
运行实例,不依赖临时 PTY,不创建登录自启或定时任务。缺少本机配置时保持原行为;
Tunnel 失败不阻止其他 Core 模块。相同配置的并发请求通过独占文件锁归并为一个实例。
停止只请求该启动代次退出,不按历史 PID 强杀进程。

```powershell
node modules/agent-core/src/cli.mjs chat ensure C:/existing/chat-tunnel.json
node modules/agent-core/src/cli.mjs chat status C:/existing/chat-tunnel.json
node modules/agent-core/src/cli.mjs chat stop C:/existing/chat-tunnel.json
```

守护进程对 Tunnel 异常退出进行最多四次启动尝试,间隔 1/2/4 秒;每次重新探测
当前代理。失败后停止自动尝试,下一次明确的本机需求可以重新启动。状态 JSON
区分启动、就绪、恢复、失败和停止,提供退出码、阶段、本机日志路径及健康检查命令;
不打印密钥、文件内容或消息正文。原生 `/readyz` 只证明 Tunnel 就绪,不证明 Codex
宿主或远端任务启动成功。恢复进程不重放任何消息。

缺运行密钥、读取本机设置失败、网络路由不可达分别保留明确错误原因;进程权限等
系统错误保留错误码。未知异常正文不外发,避免凭据泄露。若守护恰在旧锁回收的
短窗口内崩溃,保守保留 `recovery.lock`,状态命令明确提供排障提示;operator
确认锁 owner 已结束后才能移除该孤立锁,不自动删除未知锁或强杀进程。

远端 Chat 经仍在运行的 Tunnel 可继续调用;**本地执行通道和 Tunnel 全部停止时,
同一个 Tunnel 无法接收用于启动自己的请求**。这时需先由在线的本机执行通道调用
Core,或运行上述 `ensure`。没有额外云端唤醒服务。守护进程本身被结束后也依靠
下一次本机需求恢复,而不是承诺无人自动重生。

## 读取授权默认临时

桌面重启后的绑定由正式启动环境 `CODEX_APP_TOOLS_PIPE_PATH` 提供,Core 的 MCP
声明通过 `env_vars` 保留该字段。按需入口可在本机配置增加可选项:
`"hostBinding": {"module":"已接受的host-notifier.mjs绝对路径","dataDir":"原回传数据目录"}`。
Core 使用同一个共享连接器验证原 operator 身份及可信本机管道,只更新 pipePath;
不猜测其它管道、不读取进程内存,不修改 operator、读取授权或消息记录。
普通 CLI 没有桌面环境变量时,仍先验证已配置的宿主,不把缺少覆盖值误当离线。
旧管道失效而又没有可信新绑定时明确返回 `hostBinding.state=failed` 及具体错误码;
不猜管道、不以 Tunnel ready 冒充宿主恢复成功,也不阻塞其他 Core 模块。

在新的运行区间,私人委托连接可依据会话中本次明确授权调用
`select_codex_task(grantReadAccess:true)`。该操作只启用所选会话的临时读取,
不恢复旧会话名单或文件目录;同区间的明确授权可合并,永久模式不会由此启用。

默认 `grant` 将明确目录/任务范围绑定到本次守护运行区间。Tunnel 子进程异常恢复
不结束区间;守护停止或重新开始后旧授权立即失效,必须重新确认。没有日历过期票据,
旧 schema 1 配置也不会被默认为长期授权。

```powershell
'{"threadIds":["明确授权任务UUID"],"workspaceRoots":["C:/approved/workspace"]}' | node modules/agent-core/src/cli.mjs chat grant C:/existing/chat-tunnel.json
node modules/agent-core/src/cli.mjs chat revoke C:/existing/chat-tunnel.json
```

只有用户明确要求长期授权时,operator 才可使用同样范围输入执行
`chat grant-persistent`。长期模式保留到明确撤销/修改;该命令不提供给远端模型工具。
启动服务本身不续授旧范围,也不把“允许这次读取”改成长时访问。

Chat 会话目录通过本机已装 Codex 的原生 `thread/list` 补齐,显式使用
`modelProviders: []`,避免切换提供方后只看见新提供方会话。启动入口设置本机
`CODEX_CHAT_INVENTORY_EXECUTABLE` 与 `CODEX_CHAT_INVENTORY_HOME`,再合并桌面
列表及侧栏引用并去重;不读原始 transcript、不恢复或发送会话,不改变提供方
配置或历史记录。存储目录没有全局运行状态,相关条目返回 `status: null`;
桌面接口可提供状态的条目保留其原生状态。列表扩大不代表文字或文件读取范围扩大。
Loading