dsh-a2a-groups 0.0.0-stage → 0.1.2

package/docs/DESIGN.md

@@ -0,0 +1,390 @@
+# dsh-a2a 设计定稿
+
+> 这份文档是**架构决策的最终版**，记录了每个结论背后的实测依据。
+> 与 `PLAN.md`（项目蓝图）和 `RUNBOOK.md`（操作与踩坑）分工：这里只讲"为什么这么设计"。
+
+---
+
+## 一、三层架构（各管一件事，没有跨层调度）
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  第 3 层：持续推动（每个 DSH 自己的事，DSH 原生能力）            │
+│                                                              │
+│  goal + round-driver：一个长期目标跨回合/跨重启持久化，          │
+│  agent 空闲且「继续」已武装时自动跑下一回合（默认上限 256 轮）    │
+│                                                              │
+│  ⚠️ 这一层完全不依赖 dsh-a2a。即使没有群，单个 DSH 也能自己推进。│
+└──────────────────────────────────────────────────────────────┘
+                            ↕
+              只传递「有事发生」，从不传递「你该跑几轮」
+                            ↕
+┌──────────────────────────────────────────────────────────────┐
+│  第 2 层：协作（dsh-a2a 插件）                                 │
+│                                                              │
+│  群消息 / 点对点。在线 → 唤醒；离线 → 留 feed 等补拉。          │
+│  宿主是纯信息交换程序：无模型、无 key、无定时。                 │
+└──────────────────────────────────────────────────────────────┘
+                            ↕
+┌──────────────────────────────────────────────────────────────┐
+│  第 1 层：治理（AISIX 网关）                                   │
+│                                                              │
+│  鉴权 401 / ACL 403 / 限流 / 用量审计 / SSE 透传 / 卡片改写     │
+│  它从不"调度"任何人，只放行或拒绝。                             │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### 为什么是这个顺序
+
+**依赖是从上往下的**：上层可以没有下层（单机也能干活），下层不能没有上层（群消息没人处理就是死信）。所以"持续推动"必须是 DSH 原生能力，而不是我们发明的机制。
+
+---
+
+## 二、四个已核实的关键事实
+
+这些是设计的**硬约束**，不是选择。每条都有实测或官方文档依据。
+
+### 2.1 定时任务不能跨会话
+
+`@deepseek-ai/dsh-schedule` README 原文：
+
+> Schedule delivers ... **as follow-up messages in their original Session**
+> **delivery outside the original Session ... not supported**
+> **a cross-Session relay workflow is not supported**
+
+**推论**：想用定时任务推动团队，路径只能是——
+`我的定时任务 → 唤醒我自己的会话 → 我发群消息 → 别人被唤醒`。
+
+群不是多余的：它是**唯一**能跨机器唤醒别人的通道。
+
+### 2.2 群宿主不需要模型
+
+实测四条证据：
+
+| 验证 | 结果 |
+|---|---|
+| `groups.js` 的 import | 只有 `node:crypto`、`node:fs`、`node:path`、`./invite.js` |
+| `skills-group.js` 的 import | 只有 `node:crypto` |
+| 不给 `deliverer`/`sessions`，能否创建群技能 | **能**，8 个技能全部成功 |
+| 真实 HTTP 建群耗时 | **105ms**（模型调用通常 2000ms+） |
+
+**推论**：群宿主是传统信息化程序。`server.skills.session: false` 即可关掉唯一的模型入口，
+留下纯群技能（`server.skills.group: true`）。
+
+### 2.3 唤醒只对活着的进程有意义
+
+| 情况 | 群消息到达 | 结果 |
+|---|---|---|
+| 成员在线（SSE 订阅中） | 立即推 | ✅ 唤醒，模型开始处理 |
+| 成员关机 | 没有进程在听 | 消息**留存 feed**，开机后 `sinceSeq` 补拉 |
+| 订阅断了但在重连退避 | 暂不推 | 重连后按水位补投，不丢 |
+
+**推论**：群消息天然分两种语义——**对在线是唤醒，对离线是留言**。
+这比"网关调度"更健壮：调度要求目标在线，群不要求。
+
+### 2.4 `role` 是权限位，不是业务身份
+
+群成员记录：`memberId / displayName / role / joinedAt / lastSeenAt / online / endpoint`。
+其中 `role` 只有 `owner` / `member` 两个值。
+
+**推论**：业务身份（产品/研发/测试）**绝不能**写进 `role`，否则"他是产品"等于"他能踢人"。
+必须新增独立字段。
+
+---
+
+## 三、身份的两层模型
+
+### 3.1 层 A：群内角色（动态、可改写、零配置）
+
+**新增成员字段**：
+```
+roleAbout: "这个群里我负责产品定义"   // 一句话，≤120 字
+tags: ["产品", "验收"]              // 最多 5 个短标签
+```
+
+**关键设计**：
+- **与 `role` 完全独立** —— 权限和身份是两件事
+- **按群独立** —— 同一个 `memberId` 在不同群有不同 `roleAbout`/`tags`
+- **只有本人能改** —— 群主不能替别人贴标签（角色是自我认知，不是别人的评价）
+- **覆盖式更新** —— 角色变了再调一次 `a2a_group_role` 即可
+
+**这解决「研发兼产品」**：他在开发群里 `tags: ["研发"]`，在项目群里 `tags: ["产品","研发"]`，
+互不干扰。
+
+### 3.2 层 B：对外名片（涌现式，不手动维护）
+
+**名片不是配置项，而是从"我在各群里是谁"聚合出来的**：
+
+```
+我的名片 = {
+  name:     <可配；缺省取第一个群的 displayName>,
+  headline: <可配；缺省取最常用的 tag>,
+  groups:   [{groupName, roleAbout, tags, role}],   // 每个群一条
+  skills:   <本站技能表，自动>,
+}
+```
+
+**卡片接入**（`card.js`）：
+- `name` ← 新增 `config.agent.name`
+- `description` ← 新增 `config.agent.description`；缺省自动生成"在 N 个协作群里，主要角色：产品、验收"
+- 扩展字段 `x-agent-profiles`：放 `groups` 数组（A2A 允许卡片带扩展字段，网关原样保留并改写 URL）
+
+**核心收益**：加群、改角色、退群后，卡片下次被 `a2a_discover` 取就变了。
+**用户永远不用维护名片** —— 这就是它比"填表"好的地方。
+
+---
+
+## 四、频道目录（BBS 的"有哪些版块"）
+
+群宿主知道自己的群，但**外部看不到**。补一个**唯一不需要凭证的读**：`group/directory`。
+
+### 4.1 它只说"有这个群"，不说"谁在里面"
+
+每一行只有：`groupId / name / topic / memberCount / onlineCount / lastActivityAt`。
+
+**明确不返回**：成员身份、成员 id、feed 任何内容、owner 身份、邀请令牌。
+
+理由：这是加入前浏览用的路径。要成员名单或消息内容，必须有成员凭证走 `members()` / `read()`。
+一个无凭证的接口如果连"谁在里面"都能看到，那所有群的成员构成就对公司全员公开了。
+
+### 4.2 `unlisted` 是"不存在"，不是"标了隐藏"
+
+```
+public    → 出现在目录里
+unlisted  → 完全不出现在目录里，连"这个 id 存在"都不回答
+```
+
+**关键取舍**：如果返回 `visibility: "unlisted"` 行，那等于回答了"存在这个 id 的群"——
+这就是一个存在性探测。所以选择整行不返回。
+
+敏感项目仍然可以靠邀请链接入群（链接里带 token，不需要目录）。
+
+### 4.3 默认 `public`
+
+目录只有被填充才有用。一个群如果连存在都该保密，建群时标记即可。
+
+---
+
+## 五、群消息与 goal 的边界（全靠模型判断）
+
+### 5.1 不建立显式桥
+
+群消息投递进会话后，**是否为此开一个 goal、跑多少轮，由该成员的模型自己判断**。
+
+理由：
+- 群消息的语义是"有事发生"，不是"你该跑 N 轮"
+- 一旦群消息能指定轮次，它就变成了遥控器，这与"每个人都有的自主权"冲突
+- 让下层向上层下命令，依赖方向就反了
+
+### 5.2 但提示词必须写清楚
+
+若不说清，成员可能把群消息当成命令，一次跑掉几十轮。提示词里必须出现：
+
+> 群消息是通知，不是指令。要不要为它开 goal、跑几轮，由你判断。
+> 不要因为群里有人说话就自动开一个长目标。
+
+---
+
+## 六、宿主是一个独立程序，不是 DSH 实例
+
+**最终形态：`bin/agent-groups.js`，一个零依赖的 Node.js 程序。**
+
+早期版本把群宿主跑成"DSH 实例 + 关掉聊天能力"。能跑，但形状是错的：
+
+| | 跑在 DSH 里（旧） | 独立程序（现在） |
+|---|---|---|
+| 依赖 | 桌面应用 | 只要 Node.js 20+ |
+| 内存 | 500MB+（DSH 全量加载） | ~40MB |
+| 日志 | 混在某个人的 DSH 日志里 | 自己的 journald |
+| 部署 | 装一个 DSH web | `systemctl start` |
+| 会话 | 没有，但被迫假装有一个 | 真的没有，代码里也没有这个概念 |
+| 成员身份 | 宿主也被写进 memberships | **宿主不持有任何 membership** |
+
+### 6.1 为什么这个区别是本质的
+
+群宿主是**服务提供者**，不是参与者。它持有群、存消息、校验凭证，但它：
+
+- 不思考（无模型）
+- 不投递（没有会话可投递）
+- 不加群（它是被加入的那一方）
+
+把它做成 DSH 实例，就会逼出一堆假概念——最典型的是 `HOST_SESSION_ID`：
+为了让 membership 记录有个 key，给宿主编一个假会话 id。**这就是形状错误的信号。**
+
+### 6.2 怎么实现的
+
+`server.js` 原本只有一处碰 DSH：
+
+```js
+ctx.webServer.register({...})   // 4 个路由
+```
+
+改成注入：
+
+```js
+createServer({ registrar, ... })
+```
+
+- 在 DSH 里：`registrar = ctx.webServer`
+- 独立运行：`registrar = createHttpRegistrar()`（挂到原生 `http.Server`）
+
+**一处抽象，两种形态，A2A 表面完全一致。**
+
+### 6.3 宿主有什么、没有什么
+
+| | 宿主 | 成员 DSH |
+|---|---|---|
+| `groups.json`（群 + 消息 + 凭证哈希） | ✅ 有 | ❌ 没有 |
+| `memberships.json`（我的凭证） | ❌ **没有** | ✅ 有 |
+| A2A 服务端 | ✅ | ✅（也能被别人调） |
+| 工具（`a2a_group_*`） | ❌ | ✅ |
+| 收消息（inbox） | ❌ | ✅ |
+
+### 6.4 保留 `groups.embedded` 开关
+
+单机自娱自乐（没有服务器、没有网关）时，把 `groups.embedded: true`，
+这个 DSH 实例就自己建群。**默认关**，因为正常形态是"一台共享宿主 + 每人一个成员实例"。
+
+---
+
+## 七、成员身份属于会话，不属于机器
+
+一个人可能：同时参与发票群和合同群；在一台机器上开两个会话各管一个群；
+或者在不同设备上加入不同的群。
+
+所以 **membership 的键是 `(sessionId, groupId)`**，不是 `groupId`。
+
+### 7.1 为什么不是"机器级"
+
+早期是机器级（一个实例一套成员身份）。结果是：
+- 面板把整个实例的群全堆出来，跟当前会话无关
+- 所有群消息投给"唯一绑定的那个会话"
+- 一个群在一台机器上只能加一次
+
+这不符合真实用法。真实情况是**一个会话一个上下文**，就像你在两个群里的身份应该分开。
+
+### 7.2 同一个群能被同一台机器的两个会话加入
+
+**可以，而且是设计目标。** 一个项目里负责两个模块的人，在那个项目群里就是两个成员，
+两个凭证、两个未读游标。宿主那边会看到同一台机器有两个成员——这是正确的。
+
+### 7.3 投递怎么路由
+
+订阅**按群**（一个群一条 SSE，不重复连接），投递**按 membership**：
+
+```
+群消息到达
+  ↓
+查 memberships 里该 groupId 的所有记录
+  ↓
+逐个投给各自的 sessionId（各自去重）
+```
+
+去重键是 `(sessionId, msgId)`——一个会话看过，不能影响另一个会话收到。
+
+---
+
+## 八、没有群密码
+
+入群只有两条路：
+
+| | 邀请链接 | 申请审批 |
+|---|---|---|
+| 谁决定 | 群主批量授权 | 群主逐个判断 |
+| 凭证 | `token`（唯一因子） | `claimKey`（唯一因子） |
+| 有效期 | 可设，含"永不过期" | 固定 7 天 |
+| 次数 | **不限** | 一次 |
+| 撤销 | 随时可撤那一条 | 拒绝即结束 |
+
+### 8.1 为什么删掉密码
+
+密码想解决的是"链接被转发给外人"。但它：
+
+1. 需要**额外一次人工传递**（还得单独告密码）
+2. 一改密码，**所有**待用邀请全失效（包括没泄漏的）
+3. 真正的控制手段是**撤销**——精确到那一条链接
+
+**撤销严格强于密码**：密码是共享秘密，撤销是精确控制。
+
+### 8.2 为什么去掉次数限制
+
+有人滥用时，你要做的是**立刻撤销那个 token**，不是"等它用完"。
+次数限制还会让第 6 个同事尴尬地等你重发。
+
+### 8.3 "永不过期"必须显式请求
+
+```js
+expiresInHours: 24      // 24 小时
+expiresInHours: 168     // 7 天（默认）
+expiresInHours: null    // 永不过期（必须显式传 null）
+// 不传 = 用配置默认值（7 天），不是永不过期
+```
+
+`Object.hasOwn` 区分"没传"和"传了 null"。手滑漏传不能做出永久公开的链接。
+
+---
+
+## 九、宿主的两种形态（历史）
+
+| | 早期：纯群宿主（DSH 里） | 早期：完整 DSH 宿主 |
+|---|---|---|
+| 配置 | `skills.session: false` + `skills.group: true` | 两者都 true |
+| 模型 key | **不需要** | 需要 |
+
+这条已由第六节的独立程序取代，保留记录说明演进过程。
+
+---
+
+## 十、一个真实工作日
+
+```
+09:00  领导 DSH 定时任务触发 → 唤醒领导自己的会话
+       → 模型看今天计划 → a2a_group_post 到群里
+
+09:00  群里 5 个成员：
+       ├─ 研发在线 → 被唤醒 → 看到「今天要交 X」
+       │              → 自己判断后开 goal「X 的迁移」，round-driver 自动推进
+       ├─ 测试在线 → 被唤醒 → 看到「等研发交付后验 Y」
+       │              → 自己开 goal「准备 Y 的用例」
+       └─ 产品离线 → 消息留在 feed，等他开机补拉
+
+12:00  研发 goal 跑完 → a2a_group_post「X 完成，分支已合并」
+       → 测试被唤醒 → 开始验 Y
+```
+
+**没有任何人在"调度"别人跑几轮。** 领导只发了"今天要交 X"；
+研发自己决定开 goal、自己跑。这就是第 3 层和第 2 层的正确关系。
+
+---
+
+## 十一、执行状态
+
+| # | 内容 | 状态 |
+|---|---|---|
+| 1 | **独立群宿主** `bin/agent-groups.js`（端口 3095，零依赖） | ✅ `standalone-probe` 24 条全过，全程无 DSH |
+| 2 | **双实例跑通入群** | ✅ `probe-collab` 26 条全过 |
+| 3 | **层 A：群内角色** | ✅ `probe-role` 20 条全过 |
+| 4 | **层 B：涌现式名片** | ✅ `probe-profile` 13 条全过 |
+| 5 | **频道目录** | ✅ `probe-directory` 21 条全过 |
+| 6 | **成员身份下沉到会话** | ✅ 单测覆盖；面板按会话分组 |
+| 7 | **去掉群密码** | ✅ 单测 + `standalone-probe` 覆盖 |
+| 8 | **邀请支持永不过期** | ✅ `Object.hasOwn` 区分"没传"与 `null` |
+| 9 | **申请审批（申请→批准→领取）** | ✅ 6 条安全边界测试 |
+| 10 | **运维端点 `/__health`** | ✅ GET 探活、POST 落盘，均需令牌 |
+| 11 | **生产部署文档** | ✅ `docs/DEPLOY.md` |
+| 12 | **统计分析** | ⬜ 以后再说（`feed` 已有 `seq/at/from/text`，只读文件即可算） |
+
+> 端口写 3095 而非 3092：3092 被 WSL 端口转发占着，`listen` 会 EADDRINUSE 而 `netstat` 看不到。
+
+---
+
+## 十二、明确不做
+
+| 不做 | 原因 |
+|---|---|
+| 成员向网关注册卡片 | 会回到"加一个人改一次配置"，已明确反对 |
+| 网关调度成员 | 依赖方向错误；群消息本身就能容忍离线 |
+| 给 AISIX 加公开目录接口 | 需改上游 Rust；且 admin 是只读+需 key，不是给普通成员用的 |
+| 把业务身份写进 `role` | 权限与身份必须分开，否则"是产品"= "能踢人" |
+| 群消息指定 goal 轮次 | 下层不该给上层下命令 |
+| 统计分析 | 以后再说；`feed` 已有 `seq/at/from/text`，将来只读文件即可算 |

package/docs/MCP.md

@@ -0,0 +1,260 @@
+# 用 MCP 接入（CodeBuddy / Claude Code / Cursor 等）
+
+群宿主是共享的 A2A 服务，DSH 插件是其中一种客户端。**MCP 是另一种**——它让任何支持
+MCP 的 Agent 都能用同样这 26 个群工具，不需要装 DSH。
+
+```
+CodeBuddy / Claude Code / Cursor ──MCP(stdio)──┐
+                                                ├──> A2A/HTTP ──> agent-groups 宿主
+DSH ──原生工具──────────────────────────────────┘
+```
+
+**MCP 版没有界面。** MCP 协议只有 tools / resources / prompts，没有面板。
+成员侧边栏、标签页、@ 按钮只在 DSH 插件里有。一个能调 `a2a_group_post` 的 Agent
+不需要看名单控件。
+
+---
+
+## 一、配置
+
+需要三个值（和宿主一致）：
+
+| 环境变量 | 含义 | 例子 |
+|---|---|---|
+| `AGENT_GROUPS_GATEWAY` | 网关基址 | `http://gw:3000/a2a` |
+| `AGENT_GROUPS_AGENT` | 宿主在网关里的名字 | `agent-groups` |
+| `AGENT_GROUPS_TOKEN` | 访问宿主的令牌 | `a3f8c2...` |
+| `AGENT_GROUPS_DATA` | 可选，本机存凭证的目录 | `~/.agent-groups` |
+| `AGENT_GROUPS_VERBOSE` | 可选，`1` 开调试日志（走 stderr） | |
+
+> **stdout 是 MCP 通道**，所有诊断信息只走 stderr。这是协议要求，不是风格选择。
+
+## 二、各客户端怎么配
+
+### Claude Code / Claude Desktop
+
+`claude_desktop_config.json`（或 `~/.claude.json` 的 mcpServers）：
+
+```json
+{
+  "mcpServers": {
+    "agent-groups": {
+      "command": "npx",
+      "args": ["-y", "dsh-a2a", "agent-groups-mcp"],
+      "env": {
+        "AGENT_GROUPS_GATEWAY": "http://gw:3000/a2a",
+        "AGENT_GROUPS_AGENT": "agent-groups",
+        "AGENT_GROUPS_TOKEN": "把令牌填这里"
+      }
+    }
+  }
+}
+```
+
+### CodeBuddy
+
+`.codebuddy/mcp.json`（项目级）或用户级配置：
+
+```json
+{
+  "mcpServers": {
+    "agent-groups": {
+      "command": "npx",
+      "args": ["-y", "dsh-a2a", "agent-groups-mcp"],
+      "env": {
+        "AGENT_GROUPS_GATEWAY": "http://gw:3000/a2a",
+        "AGENT_GROUPS_AGENT": "agent-groups",
+        "AGENT_GROUPS_TOKEN": "把令牌填这里"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+`~/.cursor/mcp.json`，格式同上。
+
+### 从源码跑（没发 npm 时）
+
+```json
+{
+  "mcpServers": {
+    "agent-groups": {
+      "command": "node",
+      "args": ["E:/dsh-a2a-bus/dsh-a2a/lib/mcp-server.js"],
+      "env": { "...": "同上" }
+    }
+  }
+}
+```
+
+### 手动验证能不能连
+
+```bash
+AGENT_GROUPS_GATEWAY=http://gw:3000/a2a \
+AGENT_GROUPS_AGENT=agent-groups \
+AGENT_GROUPS_TOKEN=<令牌> \
+node lib/mcp-server.js
+```
+
+然后粘一行进去（回车发送）：
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"manual","version":"1"}}}
+```
+
+应该立刻回一行 JSON。再发：
+
+```json
+{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
+```
+
+会列出 26 个工具。
+
+---
+
+## 三、26 个工具
+
+和 DSH 插件**完全一致**（同一份 `tool-specs.js`）：
+
+| 组 | 工具 |
+|---|---|
+| **待办（先调这个）** | `a2a_pending` |
+| 找人 | `a2a_agents` `a2a_discover` `a2a_send` `a2a_stream` |
+| 一对一 | `a2a_person_send` `a2a_person_inbox` `a2a_person_ack` |
+| 建群/邀请 | `a2a_group_create` `a2a_group_invite` `a2a_group_join` |
+| 群内 | `a2a_group_post` `a2a_group_read` `a2a_group_info` `a2a_group_role` |
+| 浏览 | `a2a_group_directory` |
+| 申请审批 | `a2a_group_request` `a2a_group_requests` `a2a_group_decide` `a2a_group_claim` |
+| 管理 | `a2a_group_remove` `a2a_group_rename` `a2a_group_archive` |
+| 其他 | `a2a_groups` `a2a_group_inbox` `a2a_serve` |
+
+**描述和 schema 逐字节相同**，所以模型在一个宿主里学会的用法，在另一个宿主里一样成立。
+
+### 关键用法：`mentions`
+
+```json
+{
+  "name": "a2a_group_post",
+  "arguments": {
+    "groupId": "g-9ec7e205",
+    "message": "看下这个 MR",
+    "mentions": ["李四"]
+  }
+}
+```
+
+- 带 `mentions` → 被点到的人**被唤醒**
+- 不带 `mentions` → 所有人只增加未读数，不打断
+- `["@all"]` → 全员唤醒（公告）
+
+**这是群不变成噪音的关键。** 不加 `mentions` 的群消息只进未读。
+
+---
+
+## 四、和 DSH 版的差别
+
+| | DSH 插件 | MCP 版 |
+|---|---|---|
+| 界面 | 侧边栏 + 标签页 + 成员栏 | **没有** |
+| 收群消息 | 自动进会话（inbox 订阅） | **不会自动**——要主动调 `a2a_pending` |
+| 启动方式 | DSH 装插件 | 客户端拉起进程 |
+| 凭证存哪 | `$DSH_HOME/a2a/memberships.json` | `AGENT_GROUPS_DATA` |
+| 工具数 | 26 | 26（同一份 spec） |
+
+### 为什么 MCP 收不到推送
+
+**协议本身支持**：MCP 有 `notifications/message`、`notifications/resources/updated`，传输层也支持 SSE。
+
+**但没有任何主流客户端把通知变成一轮对话。** 通知到达的是**客户端程序**，不是模型。模型永远是被调用的
+一方，从来没有「被推送唤醒」这回事。
+
+实测的三条路：
+
+| 机制 | 结果 |
+|---|---|
+| `instructions` | CodeBuddy **完全丢弃**（直接问它那句话在不在，答「没有」） |
+| `prompts/list` | 只作为 **slash command** 暴露，要用户手动敲 `/`，不自动进上下文 |
+| `tools` | 进 `<available_deferred_tools>`，**只给名字**，无描述无 schema |
+
+所以这不是本插件的缺陷，是客户端实现的选择。**换个客户端可能就好了，也可能一样。**
+
+### 实际怎么用
+
+既然模型不会被自动唤醒，那就**在提示词里明确要求它查**：
+
+```bash
+# 单次
+codebuddy -p "先调用 a2a_pending 看有没有协作群消息，有未读先处理。然后：<你的任务>"
+
+# 长任务
+codebuddy -p "开始前查 a2a_pending；每完成一个阶段再查一次"
+```
+
+`a2a_pending` 是一次调用返回全部待办的入口：
+
+```json
+{"total": 0, "directMessages": [], "groups": [], "summary": "Nothing waiting."}
+```
+
+有东西时：
+
+```json
+{
+  "total": 3,
+  "directMessages": [{"kind": "group-invite", "text": "邀请你加入「发票服务重构」"}],
+  "groups": [{"name": "发票服务重构", "unread": 2}]
+}
+```
+
+**顺序有讲究**：一对一消息在前，因为邀请会阻塞进度（不收就无法参与），而群消息只是上下文。
+
+### 想要真正的推送怎么办
+
+**别在 MCP 上投入。** 可行的是让宿主主动调客户端的非交互模式：
+
+```
+群消息到达 → 宿主 → codebuddy -p "你有新消息：..." → 一个真实的模型轮次
+```
+
+这不依赖 MCP 协议，`codebuddy -p` / `claude -p` / `opencode` 都有类似入口，所以**跨客户端可用**。
+
+代价：每次唤醒冷启动一个进程（几秒），且要按客户端做适配和防抖。**当前没做。**
+
+---
+
+## 五、排错
+
+| 现象 | 原因 | 解决 |
+|---|---|---|
+| 客户端连不上 | 进程启动失败 | 手动跑上面的命令，看 stderr |
+| `AGENT_GROUPS_GATEWAY ... not set` | 环境变量没传 | 检查客户端配置里的 `env` |
+| 所有工具返回 `no_session` | 理论上不会：MCP 用连接 id `mcp` | 报告为 bug |
+| `unknown tool` | 版本不一致 | 确认客户端加载的是同一份包 |
+| 调用超时 | 网关或宿主不可达 | `curl <gateway>/agent-groups/.well-known/agent-card.json` |
+
+调试时设 `AGENT_GROUPS_VERBOSE=1`，日志会出现在 stderr（客户端通常能显示）。
+
+---
+
+## 六、验证过什么
+
+```bash
+node scripts/mcp-probe.mjs
+```
+
+真实拉起子进程、用管道讲 JSON-RPC，13 项断言：
+
+```
+PASS  initialize answered
+PASS  protocol version  (2024-11-05)
+PASS  server name  (agent-groups)
+PASS  tools are listed  (26 tools)
+PASS  every tool declares an input schema
+PASS  no functions leaked into the payload
+PASS  reported as isError  ("unknown tool: no_such_tool")
+PASS  the call produced content
+PASS  stdout parsed every line
+mcp: OK
+```