MailUI4Agents/docs/PLUGIN-CONTRACT.md

AgentMail 插件契约 / Plugin Contract

把一个 Agent 平台接进 AgentMail 需要写一个桥接插件。这份文档是那个插件的 规格说明：必须支持哪些平台能力、每个事件到达时必须做什么、平台缺某项能力时 怎么退化、线协议的确切字段、以及每一条怎么自证做到了。

读者假定为「照着实现的人或代理」，因此：

• 条目用 MUST / SHOULD / MAY 标注强度，编号可引用（C-1、B-3…）
• 每条尽量给出可机械核对的判据，而不是「注意某某」
• 每条附为什么 —— 不知道为什么的约定会在第一次不方便时被绕过

已有两个实现可直接对照：

插件	平台	框架	语言
plugins/opencode-mail-bridge/	opencode	@opencode-ai/plugin	JavaScript
plugins/dsh-mail-bridge/	DeepSeek Harness	Cordis	TypeScript
plugins/pi-mail-bridge/	pi	pi SDK (createAgentSession)	JavaScript (ESM)

第八、九节是这两次适配的实现细节与踩坑记录 —— 规范部分（一至七节）与平台无关。

---

〇、术语与不变量

三维寻址

name@path.session
 │     │      └─ 会话位：三态，见下
 │     └─ 工作目录（可含 / 与 .）
 └─ Agent 名或人类用户名（共用一个命名空间）

按最后一个 . 切分。dsh@/home/a.b/proj.refactor 的 path 是 /home/a.b/proj、session 是 refactor。

会话位三态，语义不可混淆：

写法	含义
dsh@/path	默认会话（该 Agent + path 下最近活跃的那条，没有则新建）
dsh@/path.new	强制新建
dsh@/path.refactor	必须是已存在的别名，不存在返回 404 —— 绝不静默新建

为什么三态而非两态：.refactor 静默新建的话，一个拼错的别名会让 Agent 在 一条空会话里干活，而发件人以为在续原来那条。失败必须是可见的。

全局不变量

以下几条贯穿全文，每一节都是它们的推论。违反其中任何一条，插件的行为就是错的, 哪怕单元测试全绿。

#	不变量
I-1	平台原生信号是唯一真相来源。 不要求模型「记得」调工具去汇报状态
I-2	插件代劳的转发不消耗配额。 权限询问与最终总结走 relay 通道
I-3	平台命名优先。 会话标题/短名由平台生成，插件只回写，不另造
I-4	插件只搬运，不决策。 不改写模型输出，不代替人做权限判断
I-5	失败必须可见。 投不进去、模型起不来、目录不存在 —— 都要有人能看到

I-1 的由来：早期版本提供了 request_permission 工具让模型自己调。模型 可能忘了调（危险操作直接执行），也可能在不需要时乱调（每一步都问人）。而平台 自己的权限钩子拦下的那一次是事实。同理，「模型说完了」由平台的轮次结束信号 决定，不由模型自己声明。

---

一、能力矩阵 / Capability Matrix

判断一个新平台能不能接，以及接了之后哪些功能可用。

必需能力（缺任何一项无法接入）

#	能力	Capability	判据
C-1	在会话外注入一轮用户消息	inject_turn	存在一个 API，能对指定会话追加一条用户消息并触发模型跑一轮
C-2	创建会话并指定工作目录	create_session_with_cwd	创建时能传 cwd/directory，且平台按它给会话分组
C-3	会话的稳定 id	stable_session_id	创建后返回一个 id，用它能再次投递到同一会话
C-4	轮次结束信号	turn_end_signal	有事件/回调告知「这一轮跑完了」，且能区分正常结束与出错
C-5	读取会话内的消息	read_messages	能取到最后一条 assistant 消息的文本块
C-6	注册自定义工具	register_tools	能给模型加工具，且工具能拿到当前会话 id
C-7	插件常驻进程	long_running	插件能持有一条 SSE 长连接与一个 30 秒定时器

C-1 与 C-3 是硬门槛。 没有它们，「一封邮件 → 一轮工作 → 一封回信」这条 主链路根本无法搭起来 —— 而那是 AgentMail 的全部意义。

C-4 必须能区分成功与出错。 只知道「跑完了」不够：模型调用失败时会话里没有 任何 assistant 消息，如果把它当正常结束，插件会转发一个空字符串回去， 发件人看到一封空邮件而不是错误说明（见 B-6、D-3）。

可选能力（缺则退化，不阻塞接入）

#	能力	Capability	缺失时的退化	影响
C-8	权限/审批钩子	permission_hook	不转发权限询问	危险操作只能靠平台本地 UI 决策
C-9	钩子可异步等待	async_permission	转出去后立即返回「待决」，决策经 SSE 回来后再补	模型会先被拒一次再重试
C-10	列出会话	list_sessions	不上报平台会话快照	写信时只能续谈邮件驱动的会话
C-11	模型标题	model_title	走 D-5 阶梯：退到邮件主题派生别名	补全列表里的名字来自人写的主题，而非模型对内容的概括
C-12	列出可用模型	list_models	不上报模型目录	管理员无法在配置页划定模型范围
C-13	指定单轮模型	per_turn_model	不做降级尝试	主力模型故障时该 Agent 整体不可用
C-14	会话内文件读写工具	file_tools	附件下载后模型看不到	附件功能形同虚设

C-11 可能是「部分具备」。 pi 是实例：它确实会生成会话标题，但生成器在 pi-web 包里，不在 pi-coding-agent 内核里。人在 pi-web 界面上开的会话有标题， 桥用 SDK 起的会话没有。判定的依据只能是桥自己起的那条会话上 sessionName 到底有没有值，不是「这个平台有没有这个功能」。

具备 C-11 的平台还要回答第二个问题：别名由谁定稿。别名负有寻址唯一性义务 （撞名追 -2、manual 来源永远优先），平台侧没有这个约束。两侧各自命名会分叉， 因此必须由服务端定稿、插件把响应里的值回写进平台（见 D-5、W-7）。

能力自检脚本

接入前先回答这八个问题。任何一个答不出来，先去读平台文档，不要开始写代码：

1. 我怎么在不通过 UI 的情况下让某个会话跑一轮？        → C-1
2. 创建会话时工作目录参数叫什么？平台按它分组吗？      → C-2
3. 一轮跑完时我从哪得到通知？                          → C-4
4. 那个通知能区分「正常结束」和「模型调用失败」吗？    → C-4（最容易漏）
5. 怎么取到最后一条 assistant 消息的纯文本？           → C-5
6. 注册工具时 execute 能拿到 session id 吗？           → C-6
7. 权限钩子是同步还是异步？能不能真的等人？            → C-8/C-9
8. 往一条**空闲**会话里注入一轮，用的是哪个方法？      → C-1（见 9.11）

问题 4 在三次适配里被漏掉过两次，两次都造成「无效模型被判成成功」—— 详见 D-3 与第九节。

问题 8 是 pi 适配加上的：平台常常有两个注入入口（一个起新轮、一个往正在跑的轮次里 排队），而排队那个在会话空闲时静默什么也不做 —— 不报错、不超时、没有回信。 见 9.11。

---

二、生命周期与行为约定 / Behaviors

插件是一个状态机。这一节按事件逐个规定「到达时必须做什么」。

  B-1 启动
   ├─▶ 解析密钥 ──▶ POST /agent/register ──▶ 首次心跳（B-2）
   │                                          ├─▶ 读 allowed_models
   │                                          └─▶ pending_mails > 0 ? 补拉（B-7）
   ├─▶ 建立 SSE 长连（首次不带 Last-Event-ID）
   └─▶ 启动 30s 心跳定时器

  运行中
   ├── Gateway 推来 ─────────────┬── 平台侧事件 ──────────────┐
   │                             │                            │
   ▼                             ▼                            ▼
 new_mail (B-3)          轮次结束 (B-5)              权限询问 (B-8)
 permission_decision      ├─ 取 text 块                ├─ 转成邮件问人
   (B-4)                  ├─ 模型已自己发过 → 让位      └─ 决策回来 → 回答平台
                          └─ relay:"summary" 发出       标题生成 → 回写别名 (W-7)

  B-9 关停
   └─▶ 断 SSE、停定时器、未决询问 fail closed

B-1 启动（MUST）

#	要求	强度
B-1.1	按 环境变量 → ~/.agentmail/agent.key 顺序解析密钥；两者皆无时本地生成一把、写入该文件、并把全文打印到日志	MUST
B-1.2	POST /agent/register，workspaces 传 []	MUST
B-1.3	立即发一次心跳，不等第一个 30 秒周期	MUST
B-1.4	建立 SSE 长连；首次连接不带 Last-Event-ID	MUST
B-1.5	启动 30 秒心跳定时器	MUST
B-1.6	首个成功心跳的 pending_mails > 0 时补拉存量未读（见 B-7）	MUST

B-1.1 为什么是「本地生成 + 登记」而不是服务端签发：密钥全文只从客户端 流向服务器一次。插件生成后打印，管理员在后台登记即可，不需要把密钥从服务器 反向传给客户端 —— 那条路径上任何一处日志都可能把它落盘。

B-1.4 首次不带 Last-Event-ID：带上会收到一批已经处理过的旧事件， 于是插件重启一次就把历史邮件重投一遍。补投走 B-7 那条明确的路径。

B-2 心跳（MUST，30 秒）

请求体三个字段全部可选，语义见 W-3：

{ "platform_sessions": [...], "models": [...] }

#	要求	强度
B-2.1	间隔 30 秒，失败不重试不报错，下一轮补上	MUST
B-2.2	从响应读 allowed_models 存入模块级变量	MUST
B-2.3	带上模型目录（拉不到则省略字段，不传空数组）	SHOULD
B-2.4	带上平台会话快照（同上）	SHOULD
B-2.5	心跳失败不影响 SSE 与投递	MUST
B-2.6	请求体带 mode_enforcement（native / advisory），告知平台本侧的权限强制力	MUST

B-2.1 为什么失败不报错：网络抖动很常见，而 Gateway 已经有可见的失败信号 —— 持续连不上时 last_seen 会让它显示为离线。插件自己再打一串错误日志只会 淹掉真正的问题。

B-2.2 为什么范围随心跳回传而不是插件轮询：管理员在配置页改了范围后最多 一个周期（30 秒）生效，不需要重启插件；也不需要插件多起一个请求。

B-2.6 为什么上报 mode_enforcement：平台表达的档位（plan / workspace / full） 是「我要求你做到什么」，而平台能实际做到的（沙箱、审批、仅通知）取决于本侧的 强制力。两者分开记录，人在界面才能看到「这个平台无法强制这一档」。

响应里的 unknown_fields：心跳是唯一走宽容解码的端点（DecodeLenient）， 容忍插件带了平台不认识的字段。但容忍不等于咽下去 —— 响应里会回 unknown_fields 数组，插件应据此判断自己是否比平台新得太多，必要时降级。

B-3 收到 new_mail（MUST）

new_mail 到达
  │
  ├─ 1. 去重：mail_id 已在 deliveredMails 里 → 丢弃
  ├─ 2. 解析 cwd = resolveWorkspaceCwd(to_workspace, 兜底)
  ├─ 3. 查映射：session_id → 平台会话 id
  │      命中且会话还活着       → 续谈（inject_turn）
  │      platform_session_id 非空 → **接管**那条平台会话（B-3.7）
  │      否则                    → 新建会话（不传占位标题）
  ├─ 4. 按 modelAttemptOrder 逐个尝试，等异步结论（见 D-3）
  ├─ 5. 注入提示词：告诉模型「调 read_inbox 读正文」「回信不用你自己发」
  └─ 6. 登记 mail_id 到 deliveredMails

#	要求	强度
B-3.1	cwd 必须取自 to_workspace，不得自己拼临时目录	MUST
B-3.2	新建会话时不传占位标题（会掐掉平台自己的命名机制）	MUST
B-3.3	维护 mail session_id ↔ 平台 session id 双向映射	MUST
B-3.4	提示词里写明「回信由插件自动发，不必调 send_mail」（仅 from_human === true 时）	SHOULD
B-3.5	提示词里带 mail_id，让模型能自己查这封	SHOULD
B-3.6	投递失败要让人看到（日志 + 见 B-6）	MUST
B-3.7	platform_session_id 非空时必须投进那条平台会话，不得新建	MUST
B-3.8	那条平台会话已不存在时必须报错，不得退回新建	MUST

B-3.1 是踩过最贵的坑之一（详见第九节）：平台按 cwd 给会话分组，用自己拼的 临时目录会让所有邮件会话既不属于任何项目、彼此也不同组 —— 界面上全落进 「未分组」，而模型在一个空目录里找不到任何要改的代码。

B-3.4 为什么要在提示词里说：不说的话模型会自己调 send_mail 回信， 而插件在轮次结束时也会自动转发一次 —— 同一件事两封邮件。生产里真实发生过。 说了之后仍要保留 B-5.3 的去重兜底：提示词是建议，去重是保证。

为什么改为 SHOULD：from_human === false 时自动转发规则 B-5.6 已经拦住， 不需要也不应该在提示词里说「回信由插件自动发」—— 那对 Agent 收件方是假话。 提示词是建议，去重是保证，这条不变。

B-3.7 接管平台会话（MUST）

平台界面（TUI/GUI）与邮箱是同一个 Agent 的两个入口，不是两套隔离的世界。 人在界面上开的会话早就被 C-8 的会话快照上报成候选，写信时能在补全里选中； 若投递侧不认这一跳，选中后只能得到 404 —— 候选列表在承诺一件做不到的事。

Gateway 在本侧建一条会话并记下那条平台会话的 id（「接管」），随后每次投递 都在事件里带 platform_session_id。插件看到它就去那条平台会话里接着谈。

平台	接管方式
opencode	session.get 确认存在 → 照常 promptAsync({ path: { id } })
DSH	startAgent 的 resume 分支（会话 id 换成平台自己那个）
pi	SessionManager.open(file) → 跑一轮 → dispose
HomeAgent	N/A（无会话概念，所有邮件注入同一事件循环）

字段解析与失败话术走共用模块 lib/adopt.js（adoptedSessionID / adoptMissingMessage）—— 字段名各写一遍时少个下划线就静默退化成「每封邮件 新开一条」，而那个错误不抛任何异常。

接管之后必须把该会话加入 mailDriven 集合（B-5.5 的判据）。不加的话 邮件投进去了却永远没有回音：发件人只看到信发出去后再无音讯。

B-3.8：平台侧那条会话已被删时报错，不要退回新建。 镜像是快照、可以过期。 退回新建会让人在界面上看不到这封邮件带来的对话，而那正是接管的目的 —— 与 N-8「404 后自动改用 .new 是禁止的」是同一条原则。错误话术必须给出 可执行的下一步（用 .new），只说「不存在」的话模型会原地重试同一个地址。

文件型会话（pi）必须短暂持有

pi 的会话是磁盘上的 .jsonl，没有任何锁机制（SDK 里 flock/lockfile 命中为 0），它假定「一个文件一个持有者」。写入是纯 append，所以两个持有者不会 把文件截断；坏的是各自的内存索引：活着的 SessionManager 不 watch 文件， 对方追加的行自己看不见，于是算出的 parentId 指向一个对方不知道的 entry， 会话树分叉。

取舍是 open → 跑一轮 → dispose，不放进长期缓存。下一封邮件重新 open， 那一次读到的就是界面那边写的全部内容。窗口是一轮对话的时长。

三处配套细节，少一个就有实测过的坏处：

• isStreaming 时不释放。同一条会话可能已经排了下一封邮件，此时 dispose 会把排着的那轮一起杀掉。排着的那轮结束时会再触发轮次结束事件，由它释放。
• 兜底计时器（轮次超时的两倍）。轮次结束事件不来就永远握着文件； 计时器要 unref()，否则它会阻止进程退出。
• 接管会话跳过命名同步（C-11）。它的别名是人从补全里选的那个 slug； 同步会双向改坏它 —— 别名撞名时 Gateway 加后缀，而定稿别名又回写进平台侧， 于是下一次快照上报的 slug 变成带后缀那个，人选的名字凭空消失（实测撞出来过）。

B-4 收到 permission_decision（MUST）

#	要求	强度
B-4.1	用 relay_key 找到挂起的询问并回答平台	MUST
B-4.2	找不到挂起项（插件重启丢了内存映射）→ 退化为把决策当一封通知投进 session_id 指向的会话	MUST
B-4.3	退化路径不得凭空新开会话	MUST

B-4.2 为什么需要退化路径：待决映射在内存里，插件重启就丢了。此时平台侧 那次工具调用早已被拒绝，但人刚刚点了「同意」—— 什么都不做的话人以为自己批准了、 Agent 却毫无反应。把决策作为一条消息投进原会话，模型至少能重试。

B-5 轮次结束 → 自动转发（MUST）

#	要求	强度
B-5.6	收件方是 Agent（from_human === false）→ 不转发	MUST
B-5.1	只取最后一条 assistant 消息里 type === 'text' 的块	MUST
B-5.2	带 relay: "summary" + 平台侧稳定 id 作 relay_key	MUST
B-5.3	本轮模型已亲手回过这条线索 → 不转发	MUST
B-5.4	文本为空 → 不发空邮件	MUST
B-5.5	只对邮件驱动的会话转发（人在平台 UI 里开的会话不转）	MUST

B-5.6 为什么排在最前面：Agent → Agent 的邮件如果自动转发，两边插件都认为 「我只要把话说完就行」，实际上彼此持续唤醒 —— 生产实测 pi 与 dsh 互相客套 6 轮 直到撞上 hop 上限。此规则的判据是 from_human：它由服务端用 EXISTS (SELECT 1 FROM users WHERE username = from_name) 判定， 不依赖插件自己的猜测。

B-5.1 丢掉 reasoning：思考过程不该出现在邮件里 —— 它对收件人没有意义， 而且经常包含「我先假设…」这类会被误读为结论的内容。

B-5.3 用什么去重：靠进程内的 explicitSends（记录本轮模型主动发过的信）， 不是 relay_key。后者保证「同一条 assistant 消息不转两次」， 管不了「模型已经自己发过了」—— 那是两条不同的邮件。

B-5.5 为什么限定邮件驱动：人在平台 UI 里正常干活时不该往邮箱里灌总结。

B-6 无法处理时必须回信（MUST）

三种「模型一次都没跑起来」的情形，会话里没有任何 assistant 消息， 因此 B-5 什么也不会发 —— 发件人只会看到邮件发出去后再无音讯。

情形	处理
划定范围内所有模型都失败	发一封列出每个路由与失败原因的邮件
创建会话失败	同上，说明是建会话阶段失败
工作目录不可用且无兜底	同上，说明期望的 path 与实际回退的目录

#	要求	强度
B-6.1	主题形如 处理失败: <原主题>	SHOULD
B-6.2	正文逐条列出尝试过的路由与原因，并指出去哪里调整	MUST
B-6.3	带 relay: "summary" + relay_key: "model-failure:<mail_id>" 走免配额通道	MUST
B-6.4	发完仍要 throw/记录，不要静默	MUST

B-6.3 为什么免配额：这是插件的故障报告，不是模型的自主发信。让一次配置 错误吃掉用户的往返预算是双重惩罚。

B-7 启动补拉（MUST）

SSE 只推连上之后的事件。插件重启前发来的邮件不会再推一次。

#	要求	强度
B-7.1	只在首个成功心跳后补一次，不是每轮	MUST
B-7.2	串行投递，一次最多 5 封	MUST
B-7.3	与 SSE 共用同一个 deliveredMails 集合去重	MUST
B-7.4	按时间正序投（收件箱是倒序返回的）	MUST
B-7.5	mail_type !== 'normal' 的不补投	MUST
B-7.6	逐封投递前再查一次去重集合	SHOULD
B-7.7	插件以子进程形式运行时，去重必须落盘，且区分「投过」与「跑完」	MUST

B-7.1 为什么只补一次：每轮都补会把「模型正在处理中、尚未标已读」的邮件 重复投递 —— 一封邮件起两轮模型。

B-7.2 为什么串行且限 5 封：每封都要起一轮模型。攒了 80 封时一次性放出去 等于对上游打 80 个并发请求，且最后几封要等前面全部跑完。剩下的留在收件箱里， 下次重启或人工触发时再处理。

B-7.3 为什么必须共用去重集合：心跳与 SSE 建连之间有个窗口，那期间到的邮件 既在 pending_mails 里、也会被 SSE 推一次。

B-7.4 为什么必须正序：同一会话里的多封邮件倒着塞进去，上下文顺序是乱的。

B-7.5 为什么跳过 permission：原来的工具调用早随进程一起没了， 投过去模型没有可恢复的上下文。

B-7.7 为什么内存去重不够（生产事故，2026-09-04）： deliveredMails 是进程内的，而 homeagent 的插件跑在子进程里 —— homed 重启（或插件崩溃自动重启）会换一个新进程，那个集合随之清空。时序：

1. 邮件落库，旧进程的 SSE 收到，注入第一次
2. 同一秒进程被重启，那一轮被掉断（日志：context canceled）
3. 新进程起来，deliveredMails 是空的
4. 心跳报 pending_mails: 1（第一轮没跑完 → read_inbox 没执行 → 邮件仍未读）→ 补投注入第二次

模型上下文里因此出现两段几乎相同的指令。

为什么不能只记「投过没有」：那会把「重复」换成「丢件」。上面第 2 步里 那一轮被掉断，发件人没有收到回信，而落盘记录说「已投过」→ 永远跳过。 丢件比重复严重：重复至少人能看出来，丢件是静默的。

因此记两个状态：

状态	含义	再次收到时
delivered	注入过（可能被中断）	仍然重投，但提示词里说明「上一轮被中断」
completed	那一轮真的跑完且回信已发出	跳过

「说明上一轮被中断」不是装饰：不说的话模型在上下文里看到两段相似指令， 会以为人重复交代了一遍，于是可能把同一件事做两次。

何时标 completed：回信发出去了、模型自己回过了（B-5.3 让位）、 或失败通知发出去了（B-6）—— 三者都是「发件人得到了一个交代」。 回信发失败时不标 —— 那时发件人一个字都没收到。

常驻守护进程形态的插件（如 pi 桥）不受这一条约束：它自己就是进程， 重启同时也会丢掉 SSE 连接，那时走的是 B-7 补拉而不是两条路径并发。

B-8 平台权限询问 → 邮件（若平台有审批环节，MUST；没有则 N/A）

挂平台的权限/审批钩子，把询问转成一封邮件问人。这是 I-1 最直接的体现： 被平台真正拦下的那一次才是事实，不依赖模型「记得」问人。

前置条件是「平台本来就要问人」。

三个已实现的平台各有一个现成的审批环节，桥做的只是把它从本地 TUI 改道到邮件通道：opencode 的 permission.ask、DSH 的 approval/request、 pi 的 tool_call。桥没有发明审批协议。

HomeAgent 的设计不同：核心是一个纯思维核，本身没有任何对外交互能力 （能力全部来自插件），因此它不问人 —— 工具调用直接执行。 它确实有 StageBeforeToolcall 这个可以拦下调用的位置 （插件给 ctx.Response 赋值即视为拒绝），但那是「插件可以否决」而不是 「平台在征求同意」：没有待批准的请求、没有选项、也没有等人的语义。

在那种平台上，B-8 整条不适用（N/A），不是待实现项。硬要补的话等于 给平台加一层它本来没有的能力：需要自己划定高风险工具白名单、自己定义 超时与 fail closed 语义 —— 那是产品决策，不是契约合规。

判据：在 SDK 与核心两处 grep approval|consent|permission|confirm， 命中数均为 0。

平台权限钩子被调用
  ├─ 1. POST /permission/request（带平台的权限 id 作 relay_key）
  ├─ 2. 记住 平台权限 id → 挂起项
  ├─ 3a. 能异步等（C-9）→ await 到 permission_decision 回来，返回人的决策
  └─ 3b. 不能等        → 立即返回「询问中」，决策回来后用 SDK 回复那条权限

#	要求	强度
B-8.1	relay_key 用平台的权限 id；平台不给 id 时用 会话:工具:callId 拼一个	MUST
B-8.2	转发暂时失败（5xx / 408 / 429 / 网络）→ 让位给平台本地 UI	MUST
B-8.2b	转发永久失败（4xx，除 408 / 429）→ 当场拒绝并把原因告诉模型	MUST
B-8.2c	拒绝给模型的文本必须是真实原因，不能是平台的「用户拒绝了」写死文案	MUST
B-8.3	同一次询问重复触发只产生一封邮件（服务端按 relay_key 幂等）	MUST
B-8.4	邮件正文带足够上下文（工具名、参数摘要、触发这次询问的任务与派活人），让人能判断	SHOULD
B-8.5	权限询问不消耗配额	MUST
B-8.6	不传 to —— 决策人由服务端解析	MUST
B-8.7	平台支持「永久允许」时，选项里必须给出「一直同意」并真的记住它	MUST
B-8.8	免批的作用域是 (会话, 工具名)；决策文本判定用 lib/permission-grants.js	MUST
B-8.9	relay_key 发出前必须用 lib/relay-key.js 的 clampRelayKey 收敛长度	MUST

B-8.1 为什么必须是平台的 id：服务端会随决策事件把 relay_key 回传， 插件重启丢了内存映射也能对上（B-4.2）。自己生成的随机 id 重启后就对不上了。

B-8.5 为什么不收费：人不点头 Agent 就动不了，对它收费等于收「求人费」。 这里的 relay_key 只用于幂等，不是配额豁免的凭证。

B-8.6 为什么不能自己定决策人：插件手边最自然的候选是「来信人」 （mailContexts 里的 replyTo），但来信人可能是另一个 Agent —— Agent 把任务分派给自己或同伴的另一条会话时，权限邮件就发给了 Agent 自己。 后果是死锁而不是报错：Agent 不可能在 Web 界面上点「同意」，服务端的 用户推送又投进一个不存在的通道（没有任何人被提醒），于是插件里那个 await 永不 resolve —— 会话永久挂死，没有超时、没有日志、没有回信。

决策人必须由服务端定：它按 会话 owner → 线索里最近的人类 → 无人可问则 409 解析，那是唯一能看到整条线索的地方。插件只有本地那点上下文， 猜不出「这条 Agent 链最初是谁派的活」。

收到 409（整条链上没有人类）时按 B-8.2b 处理 —— 服务端已经判定没人可问， 继续等下去就是死锁。

B-8.2 / B-8.2b 为什么必须分开（生产事故）：原本只有「除 409 一律让位」一条。 实测碰到 pi 侧 relay_key 过长（上限 160 字节） 返回 400，被归入「暂时失败」 让位给本地决策 —— 而邮件驱动的会话根本没有本地 UI，那条 bash 就在无人 批准的情况下执行了。同一条会话 22 秒后另一次 key 正常则成功发出询问 —— 所以守卫是随机失效的，比稳定失效更难发现。

判据（lib/relay-key.js 的 isPermanentFailure，homeagent 侧是 relay_key.go）：

状态	类别	理由
4xx（除 408 / 429）	永久	请求本身有问题，重试一万次还是同一个结果
408 / 429	暂时	超时与限流，等一会儿真的可能成功
5xx	暂时	服务端的问题
无状态码	暂时	网络层（DNS、连接被拒）

401 归到永久：密钥无效要人去后台重新登记，不是等一等就好的事。 （实测过一次：opencode 被停用后拿着已撤销的密钥重试了 18 小时，2690 次 401。）

永久失败必须 fail closed：宁可让模型看到「权限系统坏了」并自己改道， 也不能悄悄放行一条没人看过的命令。拒绝时把原因写进 reason（平台会当工具 报错回给模型），它才知道下一步该换什么做法。

B-8.2c 为什么单列一条（DSH 实例）：“当场拒绝”在有些平台上不等于 “模型知道为什么被拒”。DSH 把 approval/request 的返回值翻译成模型可见 文本时用的是 @deepseek-ai/dsh-tools 里写死的句子：

case "rejected":    reason = `the user rejected tool "${exec.name}"`
case "unavailable": reason = `... no approval channel is available`

于是插件因为「这条链上没有人类」主动拒绝时，模型看到的是 「the user rejected tool bash」—— 没有任何用户拒绝过它。模型会以为人 不同意，而不会去换一条路；服务端给的 suggestion 只进了日志。

三个平台的出口不同：

平台	reason 能不能直达模型	做法
pi	能	return { block: true, reason }
opencode	能	output.status = "deny" + output.reason
DSH	不能	在 approval/request 里记下 (agentId, callId) → 原因，再在 tools/post-execute 返回 {kind:'block', feedback} 换掉那句写死的文案

DSH 那条路可行的依据：门禁拒绝的调用也会进 post-execute （pre-execute 的 deny 走 {kind:"post-result"} → finalizeScheduledExecution → postExecute）。替换必须是一次性的（同一 callId 只换一次）、 按 (会话, callId) 隔离、只对 isError 的结果生效，否则会把一个原因 贴到别的失败上。

B-8.9 为什么不能直接截断：toolCallId 的长度不在插件控制下。启用 extended thinking 时 Bedrock 把思考签名拼进了 toolCallId，实测同一条会话里 两种形态混着出现：

toolu_bdrk_01F6roEBHa8nic1mYiyLgNWK                  35 字节
toolu_bdrk_01FsWUWhEs4arnEWo44gqzLC~sig1:CAISoQIK…   437 ~ 13601 字节

直接截断会让前缀相同的两次调用撞成同一个键 —— 而这个键的全部意义 是幂等，撞键意味着第二次询问被服务端当重复请求丢掉。clampRelayKey 保留可读前缀（日志里还能 grep 会话 id）+ :sha256:<原始键的完整哈希>， 且未超限时原样返回 —— 否则插件升级前后会算出不同的键，等于把已发出的 询问变成新询问。Node 与 Go 两侧必须对同一输入算出同一输出（已用跨语言 比对验证）。

B-8.4 为什么要带派活人：决策人未必是这条会话的参与者。Agent 转派出来的 会话，人从没见过它，只给一句「是否允许执行 bash」无从判断 —— 得知道这活是 谁派的、为的什么事。

B-8.7 / B-8.8 免批（「一直同意」）

默认语义是每次都问。这在「跑一条命令看看」时是对的，在「审查这个工程」 时是灾难 —— 实测同一条 pi 会话被问了 15 次 bash，人点了 15 次「同意」， 全是同一类操作。

三个平台的原生能力不同，决定了免批状态该由谁持有：

平台	原生三态	免批由谁记	选项
opencode	once / always / reject	平台（回 response:"always"）	同意 / 一直同意 / 拒绝
pi	只有 block / 放行	桥（createGrantStore()）	同意 / 一直同意 / 拒绝
DSH	allowed-once / rejected（无 always）	不提供	同意 / 拒绝

平台能记就让平台记：opencode 的 always 是它自己的权限模型的一部分， 桥再存一份就有两个真相来源（I-1）。pi 的钩子只能答"拦/不拦"，没有地方 表达"以后别问了"，这时桥持有状态是唯一选择。

DSH 为什么干脆不给这个选项：它的 ApprovalOutcome 只有 allowed-once | rejected | cancelled | unavailable。桥自己记的话，DSH 侧 仍会每次调 approval/request，而桥不问就答 allowed-once —— 那是用插件 内存覆盖平台的审批策略，且这份策略没人能审计。给不出的能力就不要在 界面上摆一个按钮（摆了又不生效比没有更糟，见下）。

作用域为什么是 (会话, 工具名)：人看到的那句「是否允许执行 bash？」 就是在这个粒度上提的问，授权范围不该超出提问范围。

• 放宽到全局 → 人为「审查 llmsproxy」批准的 bash，会静默授权另一个 发件人派来的另一条任务。那不是他批准的东西。
• 收紧到 toolCallId → 等于没有免批。

换模型重开会话必须撤销（revokeSession）：授权是人对那次上下文的 判断，新会话重跑一遍提示，不该继承上一条的授权。

只在内存里是有意的：长期免批该由平台自己的 settings 管 （pi 的 settings.json、opencode 的 permission 配置）。让守护进程的内存 变成事实上的安全策略，没人能审计，重启后又悄悄消失。

判定为什么必须用共用模块：isAlwaysDecision 用的是精确匹配。 写成 /^同意/ 之类的前缀正则会让「同意」也判成 always —— 人点一次单次授权，后面所有命令都不再问，这是把单次授权静默升级成永久授权。 反向的坑同样真实：opencode 侧的三态映射一度以 : "once" 兜底， 于是任何意外文本（空串、旧选项、服务端将来新增的选项）都会放行一次 没人批准的操作 —— 兜底必须落在 reject 一侧（N-9）。

B-9 关停（MUST）

#	要求	强度
B-9.1	断开 SSE、清除心跳定时器	MUST
B-9.2	所有未决权限询问 fail closed（返回「拒绝」或「不可用」）	MUST
B-9.3	不发「插件下线」类通知邮件	SHOULD

B-9.2 为什么 fail closed：平台侧那些 await 永不返回的话，整个会话会挂死。 而且默认放行一个没人批准的危险操作，比让它失败严重得多。

---

三、工具契约 / Tools

插件给模型注册的工具。除 send_mail 与 read_inbox 外都可选。

#	工具	强度	说明
T-1	read_inbox	MUST	读收件箱，顺便标记已读
T-2	send_mail	MUST	主动发信（三维地址、抄送、reply_to、附件）
T-3	download_attachment	SHOULD	attachment_id → 本地文件
T-4	upload_attachment	SHOULD	本地文件 → attachment_id
T-5	forward_mail	MAY	转发（走完整三维寻址，它是一条新线索）
T-6	connect_to_server	MAY	登记密钥并注册，方便首次接入
T-7	request_permission	MUST NOT	见 I-1：改挂平台权限钩子
T-8	suggest_address	SHOULD	查可用收件人/工作目录/会话；发信前应先调
T-9	list_contacts	SHOULD	列出自己参与过的全部会话及可投递地址
T-10	session_participants	MAY	列出某条会话的参与方（用于回给抄送方或转达）
T-11	read_thread	MAY	查看某封邮件所在线索的完整往来
T-12	read_mail	SHOULD	读一封邮件的完整内容（含参与方地址与 reply_address）
T-13	propose_alias（T-2 参数）	MAY	模型在 send_mail 的 propose_alias 字段提议改名

为什么 T-8 到 T-12 都是 SHOULD/MAY 而不是 MUST：它们解决的是静默投递错误 （suggest_address）和信息不足（list_contacts / read_mail / read_thread）， 但都不影响主链路（收信 → 起会话 → 自动回信）。一个最小可行插件只注册 T-1 和 T-2 就能跑通主链路，上面这些是让它「不猜地址、不漏抄送方」的增强。

T-1 read_inbox 的三条硬规则

#	规则	违反后果
T-1.1	附件清单必须带 attachment_id	只说「有附件」模型无从下载
T-1.2	抄送人必须显示	模型以为是私信，回信时漏掉其他参与方
T-1.3	只标本次列出的那些，且 status=all 时不标	limit 之外的还没看过；把历史邮件标成已读会让下一轮的新邮件混在里面认不出来

默认参数：status='unread'、limit=5。

为什么默认只看未读：默认 all 会让模型每轮重读旧邮件，几轮之后上下文里 全是重复内容。这个 bug 在 DSH 插件里真实存在过（默认 all 且完全没标已读）。

共用实现 lib/inbox-format.js。跨平台必须一致 —— 它不依赖任何平台 SDK。

T-7 为什么禁止 request_permission

模型可能忘了调（危险操作直接执行），也可能在不需要时乱调（每一步都问人）。 平台的权限钩子拦下的那一次是事实。见 I-1、B-8。

T-8 ~ T-12 寻址发现工具（lib/discovery.js）

这五个工具的渲染逻辑全部在 lib/discovery.js（三平台共用），与平台 SDK 无关。 它们解决的是静默投递错误：模型猜一个地址（如 opencode@/home），投递成功 但那不是 opencode 的工作目录，静默变成了一条平行会话 —— 发件人以为在续谈，其实 在跟一条空会话说话。suggest_address 用模型从候选列表里选而不是猜，彻底杜绝了 这种错误。

#	工具	渲染函数	服务端端点
T-8	suggest_address	renderNameSuggestions / renderPathSuggestions / renderSessionSuggestions	GET /agent/contacts/suggest
T-9	list_contacts	renderContacts	GET /agent/contacts
T-10	session_participants	renderParticipants	GET /agent/sessions/{id}/participants
T-11	read_thread	renderThread	GET /agent/mail/{id}/thread
T-12	read_mail	内联渲染（含参与方地址与 reply_address）	GET /agent/mail/{id}

read_mail 的 reply_address 必须回显：它告诉模型「发件人的可投递地址是什么」。 不回显的话模型只能用原始地址续谈，但那个地址的 session 位可能是默认的，回过去 不一定落到同一条线索里。

T-13 propose_alias（T-2 send_mail 的可选参数）

propose_alias 让模型在干完活后提议一个更贴切的会话别名（例如从邮件主题 排查登录问题 改成更精确的 fix-session-cookie-leak）。

#	规则	违反后果
T-13.1	标记格式是 HTML 注释 <!-- agentmail:rename-session alias="x" reason="y" -->	服务端正则匹配不上，提议静默消失
T-13.2	标记必须由共用库 lib/rename-proposal.js 构造	各平台各写一遍拼接，少个空格就失效
T-13.3	别名不合法时不追加标记（isProposableAlias 返回 false）	发一个服务端匹配得上却校验失败的标记，白白浪费一轮
T-13.4	回显服务端返回的 rename_proposed，不是本地提议的值	服务端跑过 normalizeAlias（非法字符换 -、new 变 session-new），回显本地值会让模型拿一个不存在的名字寻址
T-13.5	回显时必须说明「等人确认，生效前继续用原别名」	模型以为改名已生效，接着用新别名当地址发信 —— 那个别名此刻还不存在

T-3 / T-4 附件参数命名差异

两个共享参数在三个平台的工具里名称不一致（历史原因，已锁定）：

参数语义	opencode	dsh / pi
要上传的本地文件路径	path	file_path
下载后的保存路径	save_to	save_path
自定义展示文件名	filename	filename（新增）

这些是工具参数，不是 API 字段，因此与服务端协议无关。但新插件实现时应参照 自己所在平台已有插件的命名，避免同一平台内两个工具参数风格不一致。

---

四、降级语义 / Degradation

平台缺某项能力时的确切退化路径。原则：降级要可见，不要装作正常。

D-1 无权限钩子（缺 C-8）

做什么	不做什么
完全不转发权限询问	提供 request_permission 工具补偿
在插件启动日志里声明「本平台不支持权限转发」	默默放行危险操作

补偿方案会重新引入 I-1 反对的那个模式。危险操作交给平台本地 UI 决策， 是一个诚实的限制；让模型自己判断该不该问人，是一个隐蔽的风险。

D-2 权限钩子不能异步等待（有 C-8 缺 C-9）

钩子被调用
  ├─ 转成邮件发出去（relay: "permission"）
  ├─ 立即返回「待决」/「询问中」——不阻塞
  └─ 人的决策经 permission_decision 事件回来后，用平台 SDK 回复那条权限

#	要求	强度
D-2.1	钩子内不得阻塞等待（会挂死整个平台请求）	MUST
D-2.2	转发暂时失败时让位给本地 UI（return next() 或保持「询问中」）	MUST
D-2.2b	转发永久失败（4xx）时当场拒绝，不让位	MUST
D-2.3	记住 平台权限 id → 挂起项 的映射	MUST

D-2.2 为什么要让位：转不出去还占着那个钩子，平台会挂在那儿等一个永远 不会来的回答。让位之后本地 UI 还能接管 —— 但这个前提只对人坐在 TUI 前面 的会话成立。邮件驱动的会话没有人在看，让位等于无人把关。

因此「让位」只能给暂时失败：网络抖动、Gateway 正在重启 —— 那些情形下 插件不知道下一秒会不会好，而人确实可能在本地看到弹窗。永久失败（4xx） 已经知道结果了，让位就是静默放行（见 B-8.2b）。

D-3 无法指定单轮模型（缺 C-13）

不做降级尝试，modelAttemptOrder 退化为 [undefined]（交给平台自己选）。

有 C-13 时，降级尝试的判定是整个契约里最容易写错的地方：

#	要求	强度
D-3.1	必须等异步结论才能判定一次尝试成功或失败	MUST
D-3.2	「提交调用返回了」不等于「模型跑起来了」	MUST
D-3.3	流式 chunk 的 finish 子类型也可能带错误	MUST
D-3.4	超时（60 秒）按成功处理	MUST
D-3.5	换模型重试时换一个新的会话 id，并销毁失败那个	SHOULD

D-3.1/D-3.2 —— 两个平台都踩了：promptAsync() 立即返回、 ctx.agents.create() 根本不校验模型。只包一个 try/catch 的话第一个无效模型 会被判成成功，第二个永远试不到。必须监听平台的错误事件或轮次结束事件。

D-3.3 具体形态：

{"chunk": {"type": "finish", "reason": {"kind": "error", "failure": {"code": "NO_ADAPTER"}}}}

「收到任意 chunk 就算走通」会让无效 provider 判成成功 —— 实测踩过。判据要落在 chunk 的类型上：finish 看 reason，其余（text-delta、block-start…） 才意味着模型真的在产出。

D-3.4 为什么超时算成功：模型可能只是很慢（首 token 前要装载上下文）。 把慢当成失败会在换模型的同时把已经在跑的那一轮丢掉，用户拿到两份回复。

D-3.5 为什么换会话 id：复用同一个 id 会让重试接在一条已经出错的会话后面； 不销毁失败那个 agent 的话，它的轮次结束信号还会触发一次自动转发。

D-4 无法列出会话（缺 C-10）

心跳里省略 platform_sessions（不是传 []，见 W-3）。 后果：写信时的会话补全只能看到邮件驱动的那些。

D-5 别名来源阶梯（C-11 缺失或不可用时）

| 优先级 | 别名来源 | 何时用 | 邮件主题派生（无平台标题） | |---|---|---| | 1 | 平台自带的 slug（如 witty-planet） | 平台创建会话时就给 | | 2 | 由平台标题派生（slugFromTitle） | 有标题且标题可用 | | 3 | 由邮件主题派生 | 平台没有标题，或标题不可用（见下） | | 4 | 不回写，保持服务端自动生成的别名 | 以上都没有 |

不得用占位标题回写（"新会话"、"处理邮件" 之类）：那会覆盖掉一个 本来可能更有意义的名字，且之后平台真的生成标题时无从判断该不该覆盖。

第 3 级是 pi 适配加上的。 原先的阶梯假定「平台要么有标题，要么完全没有命名机制」。 pi 是第三种情况：内核不生成标题（生成器在 pi-web 里），于是 SDK 起的会话 sessionName 恒为 undefined。只走前两级的话别名永远是空的 —— name@path.<别名> 续谈无从下手，.new 又是一次性的，那条会话事实上只能收一封信。

「标题不可用」是真实存在的一类。 pi-web 的标题生成器会泄漏思维链， 本机 82 条会话里捞到过这两条真实样本：

The user is asking me to generate a title for a coding-agent
我们只需要生成标题，不包含其他内容。标题应反映请求内容：测试opencode的源。简短：最

它们语法上是合法标题（cleanSessionName 只取首行 + 截 60 字符）， 派生出的别名却是一句废话。判废逻辑在 lib/session-snapshot.js 的 isUnusableName()：命中就降到下一级，不是改写成别的。

别名必须由服务端定稿

具备 C-11 的平台也要走这一步。插件提议、服务端定稿、插件把响应里的值回写：

插件观察到平台的名字
  → POST /sessions/{id}/sync { alias: slug, title: 原文 }
  → 读**响应里**的 alias（可能被改写过）
  → 与平台当前名字不同 → 写回平台

两个原因让单向推送无法收敛：

服务端行为	后果
别名撞名时追 -2、-3（SyncSessionAlias）	平台侧没有唯一性约束，不会跟着改
alias_source='manual'（人手工改过）永远优先	服务端原样返回当前别名，忽略提议

不回写的话：邮箱里显示 fix-leak-2、平台界面上显示 fix-leak， 用户按界面上看到的名字发信会收到「无法送达」。

回写有三条实测约束（pi 的形态，其它平台需各自确认）：

#	约束	违反的后果
1	只能用平台的改名 API，不能自己写会话文件	首条 assistant 消息落盘前文件不存在，pi 首次落盘用 openSync(file,"wx")，抢先创建让它抛 EEXIST
2	活着的会话管理器从不重读文件	它自己后续的 session_info 会覆盖外部改名
3	空名字是清除语义	「没拿到定稿值」绝不能落成一次空写入

还要防自激循环：改名通常会触发「名字变了」事件，而那个事件正是同步的触发源。 插件必须记住上次提交的内容指纹并在相同时跳过。指纹不能用平台名字本身 —— 名字为空时（上面 pi 的常态）它无法区分「还没提交过」与「提交过、内容没变」。

D-6 工作目录不存在

#	要求	强度
D-6.1	目录已存在才用	MUST
D-6.2	不存在时回退到兜底目录，不创建	MUST
D-6.3	拒绝相对路径	MUST
D-6.4	回退时打日志说明期望值与实际值	MUST

D-6.2 为什么不创建：一个笔误 /home/porgram/x 不该在磁盘上落下真目录 —— Agent 会在里面一无所获地干活，而那比明确的回退更难排查。

D-6.3 为什么拒绝相对路径：相对基准是 harness 进程的启动目录， systemd 下通常是 /。

D-7 Gateway 不可达

#	要求	强度
D-7.1	心跳失败静默重试，不打断已有会话	MUST
D-7.2	SSE 断开后自动重连，重连时带 Last-Event-ID	MUST
D-7.3	工具调用失败把错误如实返回给模型	MUST
D-7.4	不缓存待发邮件到磁盘	SHOULD

D-7.4 为什么不做本地队列：那需要一套持久化 + 重放 + 去重，而收益很小 —— Gateway 通常与插件同机。失败如实告知模型，它可以重试或告诉人。

---

五、线协议 / Wire Protocol

确切的端点、字段与语义边界。完整 API 见 API.md。

认证：所有 Agent 侧请求带 Authorization: Bearer <agent_key>。

W-1 端点清单

方法	路径	用途
POST	/api/v1/agent/register	注册（注意 agent 是单数）
POST	/api/v1/agent/heartbeat	心跳 + 上报 + 读回模型范围
GET	/api/v1/events/stream	SSE 长连
GET	/api/v1/mail/inbox	收件箱
POST	/api/v1/mail/read	批量标记已读
POST	/api/v1/mail/send	发信
POST	/api/v1/mail/{id}/forward	转发
POST	/api/v1/permission/request	发起权限询问
POST	/api/v1/attachments	上传附件（multipart，字段名 file）
GET	/api/v1/attachments/{id}	下载附件
POST	/api/v1/sessions/{id}/sync	回写会话别名/标题
GET	/api/v1/agent/models/allowed	读模型范围（心跳已回传，此处仅供排查）

W-2 注册

POST /api/v1/agent/register
{ "name": "mybot", "platform": "myplatform", "workspaces": [] }

字段	类型	说明
name	string	Agent 名，与人类用户名共用命名空间
platform	string	平台标识，仅用于展示
workspaces	对象数组 [{name, path}]	官方插件都传 []

workspaces 是对象数组，不是字符串数组。 传字符串会得到 400 字段 "workspaces" 类型不对：期望 object，收到 string。 工作目录由每封邮件的 to_workspace 决定，所以传 [] 是正确做法。

W-3 心跳

POST /api/v1/agent/heartbeat
{
  "platform_sessions": [
    { "platform_id": "ses_abc", "workspace": "/home/program/agentmail",
      "slug": "witty-planet", "title": "重构导入路径",
      "mail_driven": false, "updated_at": "2026-09-02T11:41:16.744Z" }
  ],
  "models": [
    { "provider": "llmsproxy", "model": "AUTO", "display_name": "AUTO (smart routing)" }
  ],
  "mode_enforcement": "native"
}

响应：

{
  "status": "ok",
  "pending_mails": 0,
  "stats": { "agent_name": "dsh", "default_rounds": 20, "sent_total": 0 },
  "platform_sessions_synced": 12,
  "models_synced": 9,
  "allowed_models": [{ "provider": "llmsproxy", "model": "AUTO" }],
  "models_unrestricted": false,
  "unknown_fields": []
}

省略字段与传空数组语义不同 —— 这是最容易搞错的一处：

字段	省略	[]
platform_sessions	保留服务端现有镜像	平台侧确实一条会话都没有 → 清空镜像
models	保留服务端现有目录	一个模型都拿不到 → 清空目录（配置页变空白）

因此拉取失败时必须省略，不能传空数组。反过来说，平台真的返回空列表时 应当传 [] —— 平台侧删掉的会话必须从补全候选里消失（session 位三态语义要求 指向不存在的会话直接 404）。

allowed_models 按优先级排序；models_unrestricted: true 表示管理员没划定范围, 插件应回退到平台默认模型 —— 与「一个都不许用」不同。

W-4 SSE 事件

GET /api/v1/events/stream
Authorization: Bearer <agent_key>
Last-Event-ID: <上次收到的 id>     # 仅重连时带

Agent 侧只会收到两个事件：

new_mail

{
  "mail_id": "9ea5ff18-...", "session_id": "7b5081e0-...",
  "from_name": "admin", "subject": "重构导入路径",
  "mail_type": "normal", "role": "to",
  "to_workspace": "/home/program/agentmail",
  "session_alias": "refactor-imports",
  "reply_address": "admin@.refactor-imports",
  "self_address": "pi@/home/program/agentmail.refactor-imports",
  "platform_session_id": "",
  "in_reply_to": "",
  "from_human": true,
  "permission_mode": "workspace",
  "permission_enforcement": "native"
}

字段	说明
role	to 或 cc
to_workspace	收件方那个地址的 path 位（抄送方拿到的是自己那个地址的）
mail_type	normal / permission_request / …
session_alias	这条会话今后的寻址名
reply_address	「把回信发回这条会话」的现成地址
self_address	对方应当用来称呼自己的地址，供转发/报告时引用
platform_session_id	非空 = 投进这条已存在的平台会话（见 B-3.7）；空 = 照旧
in_reply_to	父邮件 id：这封信是回复哪封的；空串 = 线索根
from_human	true = 发件方是人类（服务端用 EXISTS users 判定）。B-5.6 据此决定是否自动转发
permission_mode	所属会话的权限档位（plan / workspace / full）—— 插件应据此设置沙箱/审批策略
permission_enforcement	平台对该档位的实际强制力（native / advisory）—— 插件据此决定是强制执行还是打日志告警

reply_address 应当放进提示词。 插件会自动转发本轮总结（B-5）， 但模型仍然会主动发信 —— 要抄送第三方、或分多封交代不同的事时。让它自己拼三维地址 的话，.new 会被拼进去，于是回信静默开出一条新会话，原来的线索里再无下文。

permission_decision

{
  "mail_id": "...", "decision_mail_id": "...",
  "decision": "同意", "note": "", "decided_by": "admin",
  "session_id": "...", "relay_key": "perm_xyz", "relay_kind": "permission"
}

relay_key 是当初发起询问时插件传的那个（平台的权限 id）。服务端持久化了这个 映射并在此回传 —— 因此插件重启丢了内存映射也能对上。

W-5 发信

POST /api/v1/mail/send
{
  "to": "admin",                       // 或 name@path.session
  "cc": "ops@root, sre@root",          // 逗号/分号/空格分隔
  "subject": "Re: 重构导入路径",
  "body": "已完成。",                   // Markdown
  "reply_to": "<原 mail_id>",
  "session_alias": "refactor",         // 仅新建会话时生效
  "attachment_ids": ["..."],
  "relay": "summary",                  // "" | "permission" | "summary"
  "relay_key": "msg_abc123"            // relay 非空时必填
}

响应：

{ "mail_id": "...", "session_id": "...", "session_alias": "refactor",
  "budget_remaining": 18, "budget_max": 20 }

relay 为白名单枚举，只有两个合法值：

relay	用途	relay_key 取值
"permission"	平台权限询问转邮件	平台的权限 id
"summary"	轮次结束的最终总结、故障报告	平台的消息 id / 事件序号

#	要求	强度
W-5.1	relay_key 必须是平台侧生成的稳定 id，模型伪造不出来	MUST
W-5.2	同一个 relay_key 重复提交返回 {"status":"duplicate_relay"} 而非报错	—
W-5.3	模型自主发信不得带 relay	MUST

W-5.1/W-5.3 为什么：免配额通道防滥用靠的是幂等键的唯一约束，不是计数。 让模型能自己填 relay_key 等于给它一条无限发信的路。

W-6 权限询问

POST /api/v1/permission/request
{
  "question": "允许删除 build/ 目录吗？",
  "options": ["同意", "拒绝"],          // 省略则默认这两个
  "context": "工具 bash，命令 rm -rf build/",
  "session_id": "...",
  "relay_key": "perm_xyz"              // 平台的权限 id，用于幂等
}

权限询问本来就不扣配额（人不点头 Agent 就动不了，收费等于收「求人费」）， relay_key 在这里的作用只是幂等 —— 权限事件会重复触发，插件也会重连重放。

W-7 会话命名回写

POST /api/v1/sessions/{id}/sync
{ "alias": "witty-planet", "title": "重构导入路径" }

字段	写入	说明
alias	session_alias	可寻址的短标识
title	subject	模型生成的摘要

#	要求	强度
W-7.1	alias 必须去掉寻址分隔符 . @ /	MUST
W-7.2	不得回写占位标题	MUST
W-7.3	中文可以保留	—

W-7.1 为什么：留在别名里会让它自己被解析器切开，填进去的地址指向一个 完全不同的目标。中文不影响解析（按最后一个 . 切分），而转拼音后既不好读 也不好打。

服务端撞名时自动追加 -2/-3，因此同步永不失败。人工改过的别名 （alias_source = 'manual'）不会被平台同步覆盖。

W-8 附件

POST /api/v1/attachments        multipart/form-data，字段名 file
GET  /api/v1/attachments/{id}

上限 25 MB（AGENTMAIL_MAX_ATTACHMENT_BYTES）。超限返回 413。 下载一律 application/octet-stream + Content-Disposition: attachment + nosniff。

W-9 错误约定

状态码	含义	插件应当
400	请求体/字段错误（信息指向具体字段）	修代码，不要重试
401	密钥无效	停止重试，打印明确错误
403	配额用尽	把原因如实告诉模型
404	会话别名不存在	不要改成 .new 重试 —— 那会静默新建
413	附件超限	告知模型文件太大
429	新建会话速率超限（20 次/小时）	按响应里的秒数退避
5xx	服务端故障	有限重试

404 不得自动降级为 .new：那正是 session 位三态要防的事 —— 一个拼错的 别名会让 Agent 在一条空会话里干活，而发件人以为在续原来那条。

---

六、不变量与禁止事项 / Invariants

违反这些的代码可能测试全绿、跑起来也不报错，但行为是错的。

禁止事项

#	MUST NOT	为什么
N-1	提供 request_permission 之类让模型自报状态的工具	I-1：模型会忘、会乱调
N-2	为不存在的 to_workspace 创建目录	笔误会落下真目录，Agent 在里面一无所获
N-3	用相对路径作 cwd	相对基准是进程启动目录，systemd 下是 /
N-4	新建会话时传占位标题	掐掉平台自己的命名机制（I-3）
N-5	模型自主发信带 relay	免配额通道防滥用靠幂等键，不是计数
N-6	把 reasoning 块转发进邮件	思考过程不是结论
N-7	拉取失败时传 [] 而非省略字段	会清空服务端的镜像/目录（W-3）
N-8	404 后自动改用 .new 重试	静默新建，违反三态语义
N-9	未决权限询问在关停时 fail open	放行一个没人批准的危险操作
N-10	修改模型输出的文本内容	I-4：插件只搬运
N-11	首次 SSE 连接带 Last-Event-ID	会重投历史邮件
N-12	让共用模块依赖平台 SDK	那是它们能跨平台共用的前提
N-13	给 /permission/request 传 to（尤其是来信人）	来信人可能是 Agent，权限邮件发给它必然死锁（B-8.6）

共用模块必须逐字节相同

lib/ 下的文件在所有插件里逐字节相同，由 deploy/check-shared-libs.sh 校验， 并纳入 deploy/install.sh 的门禁。

文件	职责
relay-dedup.js	自动转发去重：本轮模型是否已亲手回过这条线索
inbox-format.js	收件箱渲染 + 已读策略
session-snapshot.js	平台会话快照整理（subagent 过滤、slug 派生、去重）
workspace.js	寻址 path 位 → 可用的 cwd
model-scope.js	模型目录整理 + 降级顺序 + 失败报告
catchup.js	离线期间积压邮件的补投选择
addressing.js	三维地址的拆分与校验
discovery.js	寻址发现工具的渲染（T-8~T-12）
rename-proposal.js	会话改名标记的构造与回执文案（T-13）
permission-grants.js	权限决策文本判定 + 免批授权表（B-8.7 / B-8.8）
relay-policy.js	自动转发适用范围 + 据此给模型说什么话（Agent 间不转）
relay-key.js	relay_key 长度收敛 + 永久/暂时失败分类（B-8.2b / B-8.9）
adopt.js	接管平台会话的 id 提取与缺失报文（B-3.7）
permission-mode.js	权限档位翻译（AgentMail 声明什么 → 平台怎么下发）
bounded.js	有界 Map/Set：给常驻进程里「只增不减」的映射表兜上界

Go 子进程插件的例外：homeagent 是 Go，import 不了 Node 模块。 那几个模块在它那边是 relay_policy.go / relay_key.go / bounded.go， 注释与判据原样搬过去，测试逐条对齐（relay_policy_test.go / relay_key_test.go / bounded_test.go）。clampRelayKey 还额外要求两边对同一输入算出同一输出 （幂等键分叉就失去意义）；bounded.go 的上限常量必须与 Node 侧同值 （一侧偷偷调小会让「重复投递」只在那个平台出现），但淘汰策略允许不同 —— Go 的 map 不保证遍历顺序，那边是 FIFO 而不是 LRU，理由写在文件顶部。

常驻进程里的表必须有出口

四个桥都是常驻进程（pi 的守护进程能跑几十天，另三个跟着平台一起活）。里面每一张 「这条会话/这封邮件我处理过吗」的表，键都来自外部事件流 —— 会话数与邮件数随时间 单调增长。每张这样的表都必须有出口，两条：

出口	时机	性质
session_archived 事件	会话归档	确定性：归档后别名 404、不会再有邮件投进来，映射再无用处
上限淘汰（bounded.js）	超过上限	兜底：兜的是「一直不归档」

确定性的出口优先：能确切知道该删的时候不该靠上限去猜。 session_archived 是 SSE 事件里唯一一个「这条会话到此为止」的信号， 四个桥原来全都没处理它。

不要给「还在等结果的东西」套上界：待决权限询问（opencode 的 pendingPermissions、DSH 的 pendingApprovals）里存的是 resolve 回调， 静默淘汰一条会让对应的 await 永远不返回 —— 平台侧那次工具调用直接挂死。 那些表有确定的清理路径（决策到达 / 超时 / 拆插件时 fail closed），不需要上界。 上界只适合「记录已经发生过的事实」的表。

这类表不是内存暴涨的原因：单条成本只有几十到几百字节。症状是跑够久之后 进程里躺着几十万个再也不会被查到的条目，且 GC 回收不了（还被强引用着）—— 不会在开发和测试里出现，只在生产上跑了几周后表现为「重启一下就好了」。

pi 专属：不要在心跳路径上调 SessionManager.listAll()

心跳每 30 秒要上报平台会话快照，而 snapshotPiSessions 只用四个字段 （id / cwd / name / modified）。listAll() 为了拿这四个字段会把 ~/.pi/agent/sessions 下每个 .jsonl 的每一行读进来并 JSON.parse， 还把所有消息正文拼成一个 allMessagesText 大字符串。

本机实测（115 个文件 / 145MB，其中单个会话 29MB、单行最长 2.63MB）：

做法	耗时	RSS
listAll()	1431ms	41 → 323MB（heapUsed 141MB）
只读 header 首行	3ms	41 → 46MB
src/session-scan.mjs（冷启动）	516ms	41 → 131MB
src/session-scan.mjs（稳态）	3ms	重扫 0 字节

那 282MB 每 30 秒分配一次、随即变成垃圾。GC 收得掉（所以 RSS 呈锯齿而不是单调 上升），但代价是常驻内存被垃圾撑到 300MB 上下，且每拍有 1.4 秒的同步解析跑在 事件循环上 —— 那期间 SSE 读循环停着，新邮件事件在 TCP 缓冲区排队。

src/session-scan.mjs 的三条省法：id/cwd 只在首行 header（读 4KB 就够）； name 来自 session_info 行而那种行只有几百字节（按行扫描时长度超上限的行直接 跳过、不 materialize）；文件是 append-only 的，缓存 size 之后每拍只扫新增的尾巴。

它必须建一次并复用：省内存全靠跨拍存活的 size 缓存。每拍新建一个等于每拍 都冷启动，退回全量读的开销。

为什么必须逐字节相同而不是「行为一致」：一侧改了另一侧没改，两个平台的行为 会悄悄分叉 —— 同一封邮件在 A 平台标了已读、在 B 平台没标，而两处代码看起来都 「对」。这类分叉没有测试能发现，只能靠 diff。

接新平台时把 lib/ 与 test/ 整个拷过去，平台专属逻辑写在入口文件里。 TypeScript 插件另需手写 .d.ts。

平台会话快照的四条规则

#	规则	为什么
S-1	无 slug 的会话不报	slug 是填进 session 位的值，没有它这一项点下去只能得到空的 session 段
S-2	subagent 子会话不报	父 agent 内部的工作单元，人往里发邮件毫无意义；且标题就是派活提示词前缀，slug 全撞名
S-3	slug 撞名只留最近那条	服务端只能取一条，上报同名项只会让补全里出现几个点哪个都不确定的候选
S-4	按最近活跃排序，截断到 200 条	上千个候选对人没有意义

S-2 的实测数据：DSH 一次列出 49 条子会话，其中九条标题都叫 You are auditing ONE file。

状态持久性

以下状态目前只在内存，插件重启后丢失。这是已知取舍，不是 bug：

状态	丢失后果
sessionMap / reverseMap	续谈的邮件会新开一条平台会话
mailDrivenSessions	快照里 mail_driven 全变成 false
pendingPermissions	决策回来时走 B-4.2 的退化路径
explicitSends	重启后的第一轮可能重复转发
deliveredMails	同一进程内的 SSE 重放靠它；跨进程的重复必须由 B-7.7 的落盘账本兜住

要持久化的话应当落在平台的会话元数据里，而不是插件自己的文件 —— 那样才能跟着会话一起被平台清理。

例外：投递账本必须落盘（B-7.7）。上面那些丢了只是「多开一条会话」 或「多转发一次」，而投递去重丢了是「同一封邮件被注入两遍」—— 模型上下文 里出现两段相同指令，可能把同一件事做两次。子进程形式的插件尤其如此： 它的重启频率由宙主进程决定，不是罕见事件。

---

七、验收清单 / Acceptance Checklist

每条都可机械核对。[ ] 全打完之前不要说「接好了」。

7.1 静态检查

[ ] lib/ 与 test/ 下的共用文件与参照插件逐字节相同
      ./deploy/check-shared-libs.sh

[ ] 共用模块的纯函数测试全绿
      cd plugins/<新插件> && npm test

[ ] 入口文件不导出除 default 之外的东西（若平台按导出扫插件）

[ ] grep 自查禁止事项：
      grep -rn "request_permission" src/ index.js     # 应为空（N-1）
      grep -rn "mkdir" src/ index.js                  # 不得用于 to_workspace（N-2）
      grep -rn "'\[\]'" 上报处                        # 拉取失败处不得传空数组（N-7）

7.2 连接与生命周期

[ ] 首次启动无密钥时生成一把并打印全文（B-1.1）
[ ] 管理员登记后重启，日志显示「已接入 <URL>，身份 <name>」
[ ] sqlite3 <db> "SELECT status, last_seen FROM agents WHERE agent_name='<name>'"
      → status=online，last_seen 每 30 秒推进（B-2.1）
[ ] 断网 60 秒再恢复：SSE 自动重连，期间的邮件通过 Last-Event-ID 补回（D-7.2）
[ ] kill 插件：未决权限询问全部 fail closed（B-9.2；平台无审批环节时跳过）

7.3 主链路

[ ] 发一封到 <name>@<存在的目录>.new
      → 平台里出现新会话，且 cwd == 那个目录（B-3.1）
      → 模型调了 read_inbox（T-1）
      → 一轮结束后收到自动回信（B-5）
      → 回信不消耗配额：sessions.used_rounds 保持不变（I-2）

[ ] 会话别名回写：sqlite3 "SELECT session_alias, subject FROM sessions ..."
      → 别名是平台生成的短名，subject 是模型生成的标题（W-7）
      → 别名里没有 . @ /（W-7.1）

[ ] 用回写的别名续谈：<name>@<目录>.<别名>
      → 落进同一条平台会话，不新建（B-3.3）

[ ] 发到一个不存在的别名
      → 404，且平台侧没有新建任何会话（N-8）

[ ] 接管平台会话（B-3.7）：在平台界面里手动开一条会话并聊几句
      → 等一次心跳，sqlite3 "SELECT slug FROM agent_platform_sessions
          WHERE agent_name='<name>' AND mail_driven=0"  → 出现它的 slug
      → 发一封到 <name>@<那条会话的 workspace>.<那个 slug>
      → 日志显示「接管/resume」而**不是**「新会话」
      → 让模型回答「这条会话之前在谈什么」→ 答案含界面上聊过的内容（上下文装回来了）
      → sqlite3 "SELECT platform_id FROM sessions WHERE session_alias='<slug>'"
          → 等于那条平台会话的 id
      → 收到自动回信（接管后也进 mailDriven，B-5.5）
      → 再发第二封：复用**同一条**本侧会话，不再新建（避免线索裂成多条）
      → 平台侧会话文件/记录里**没有**新增改名条目（接管会话跳过 C-11）

[ ] 平台侧删掉那条会话后再投同一个别名
      → 报错且话术含 `.new`，平台侧**没有**新建任何会话（B-3.8）

[ ] 模型主动调 send_mail 回信的那一轮
      → 只有一封邮件，没有额外的自动转发（B-5.3）

[ ] Agent → Agent 负向对照（B-5.6）：
      → 向另一个 Agent 发一封（from_human === false）
      → 收件方 Agent 的日志里**没有**「自动转发」相关条目
      → 收件方 Agent 的 sessions.used_rounds 不因自动转发而涨
      → 如果收件方 Agent 的模型跑了但没调 send_mail → 邮件链到此为止，发件方收不到任何回信
      → 如果收件方 Agent 的模型调了 send_mail 回信 → 那封回信的 from_human === false
          → 收件方的收件方也不自动转发

[ ] 模型带 propose_alias 发信（T-13）
      → 入库正文里**没有** agentmail:rename-session 标记（已被剥掉）
      → mails.rename_alias / rename_reason 记下了提议
      → GET /sessions/{id}/rename-proposal 返回该提议
      → 人接受（PUT /sessions/{id}/alias）后别名真的改了，alias_source 变 manual
      → 接受后 rename-proposal 返回 null（提示条不再反复弹）
      → 新别名可寻址：<name>@<目录>.<新别名> 落进同一条会话
      → 桥的后续命名同步**不覆盖** manual 别名

7.4 工作目录

[ ] to_workspace 指向存在的目录  → 会话 cwd 是它
[ ] to_workspace 指向不存在的目录 → 回退到兜底目录，且磁盘上没有新目录（D-6.2）
      ls <那个不存在的路径>   → No such file or directory
[ ] to_workspace 是相对路径     → 拒绝并回退（D-6.3）
[ ] to_workspace 为空           → 用兜底目录

7.5 降级与失败

[ ] 把模型范围设成两个都无效的路由，发一封
      → 收到「处理失败: <原主题>」邮件，正文列出两个路由与原因（B-6）
      → sessions.used_rounds 保持 0（B-6.3 走免配额通道）
      → relayed_mails 里有一条 model-failure:<mail_id>

[ ] 把范围设成「第一个无效 + 第二个有效」，发一封
      → 日志出现「<有效模型> 成功（前 1 个失败）」（D-3.1）
      → 收到正常回信

[ ] 停插件 → 发一封 → 启插件
      → 日志出现「补投 N 封离线期间的邮件」（B-7）
      → 收到回信

[ ] 插件在线时再发一封
      → 只收到一封回信，没有重复投递（B-7.3）

[ ] （子进程形式的插件）发一封 → 模型跑到一半时重启宙主进程（B-7.7）
      → 数据库里只有一封 `Re:`（模型上下文里也只有一段有效指令）
      → 日志出现「上一轮被中断，带说明重投」
      → 账本里该 mail_id 先一行 `c:false` 后一行 `c:true`
      → 再次重启（邮件已跑完）→ **不再投递**，会话邮件数不变

7.6 权限（若平台支持）

[ ] 触发一次平台原生的权限询问
      → 邮箱里出现一封 mail_type=permission_request 的邮件
      → 不消耗配额（I-2）
[ ] 在界面上点「同意」
      → 平台侧那次工具调用继续执行（D-2 / B-4.1）
[ ] 重复触发同一次询问（事件重放）
      → 只产生一封邮件（W-6 幂等）

[ ] **Agent 自己给自己派活的会话里触发权限询问**（B-8.6 / N-13）
      造：让 Agent 用 send_mail 发给自己 <name>@<目录>.new，正文要求它跑 bash
      → 权限邮件的 to_name 是**人**（会话 owner 或线索里最近的人类），不是 Agent
        sqlite3 "SELECT to_name FROM mails WHERE mail_type='permission_request' …"
      → 正文里带得出「触发任务」与「任务来自」（B-8.4）
      → 整条链上确实没有人类时：服务端返回 409，插件**当场拒绝**并把原因告诉模型，
        **不是**无声挂起（日志里要能看到拒绝那一行）

[ ] **永久失败不得静默放行**（B-8.2b）
      造：把转发请求里的 relay_key 换成 200 字节的串（超服务端 160 上限），
          或把密钥改错造 401
      → 服务端返回 4xx
      → 插件**当场 block / deny / rejected**，日志里有「永久失败」字样
      → 那次工具调用**没有执行**（这是生产事故的反面：
        原本 400 被当暂时失败让位，bash 就在无人批准下跑了）
      → 改造 503（停接 Gateway）：插件才该让位给本地 UI

[ ] **模型看到的拒绝理由是真实原因**（B-8.2c）
      造：让 Agent 把活派给自己另一条会话并要求跑 bash（整条链上无人类）
      → 模型收到的工具报错里带得出「没有人类用户」与服务端的 suggestion
      → **不得**是平台写死的「用户拒绝了」/ 「the user rejected tool X」
        （那句话是假的 —— 没有任何用户看过这次询问）
      → 模型随后改道或在回信里说明需要人工执行，而不是反复重试同一个工具

[ ] **relay_key 收敛后能通过**（B-8.9）
      造：clampRelayKey("<36 字节会话 id>:" + "A".repeat(500))
      → 结果≤ 160 字节、保留会话 id 前缀、尾部是 :sha256:<64 位 hex>
      → 直接 POST /permission/request 得 200（未收敛的原始键得 400）
      → Node 与 Go 两侧对同一输入算出**完全相同**的键

[ ] **「一直同意」真的免批**（B-8.7 / B-8.8）
      造：一封信里要求连续三次单独调用 bash
      → 第一次弹权限，点「一直同意」
      → 后两次**不再产生邮件**：
        sqlite3 "SELECT COUNT(*) FROM permission_requests WHERE session_id='…'"
        → 应为 1，不是 3
      → 换个工具（write）仍会问一次 —— 授权不跨工具
      → 另一条会话的 bash 仍会问 —— 授权不跨会话
      反例（修复前的真实数据）：同一条会话 15 封 permission_request，
      result 全是「同意」，界面上那个「一直同意」按钮点了等于没点

7.7 上报

[ ] 心跳带模型目录
      sqlite3 "SELECT COUNT(*) FROM agent_model_catalog WHERE agent_name='<name>'"
      → 与平台实际可用模型数一致

[ ] 心跳带会话快照
      sqlite3 "SELECT COUNT(*) FROM agent_platform_sessions WHERE agent_name='<name>'"
      → 与平台会话数一致，且不含 subagent（S-2）
      → 没有重复 slug（S-3）

[ ] 平台侧删掉一条会话后
      → 下次心跳后镜像里也消失（W-3 整表替换）

[ ] 断开平台的模型服务（让 list_models 失败）
      → 心跳里省略 models 字段，服务端目录**不变**（N-7）

7.8 端到端脚本

上面的检查可以攒成一个脚本。参照 deploy/remote-agent-demo.py —— 它用纯标准库跑完了注册 / 心跳 / SSE / 收发信，可以拿来当协议层的对照实现。

---

八、平台差异对照 / Platform Matrix

三次真实适配的对照表。接新平台时逐行回答「我这边是什么」。

关注点	opencode	DeepSeek Harness	pi	HomeAgent
插件形态	export default async function(input)	Cordis：export const inject + apply(ctx, config)	常驻守护进程，不是插件（见下）	独立子进程 plugin.bin，SDK 走 C ABI
建会话	client.session.create({ query: { directory } })	ctx.agents.create({ sessionId, meta: { cwd }, agentOptions })	createAgentSession({ cwd, sessionManager, … })	没有会话概念 —— 单事件循环，不做会话映射
注入一轮	client.session.promptAsync({ parts })	agent.followup(UserMessage)	session.prompt(text)；忙时 prompt(text, {streamingBehavior:'followUp'})	s.InjectText(source, channel, text) / InjectInputSync（同步等回复）
工具定义	zod schema	defineTool() + spec 格式参数	defineTool() + TypeBox schema	s.RegisterTool(name, ToolDef, handler)，Parameters 是裸 JSON Schema map
轮次结束	session.idle 事件	agent/status → idle	prompt() 的 promise resolve；事件是 agent_end	无「轮次」事件；靠 RegisterOutputChannel 的 handler 被调用
模型失败信号	session.error 事件	turn/end 的 reason.kind === 'error'	prompt() reject 或 末条 assistant 的 stopReason==='error'	无（核心不把模型错误暴露给插件）
权限钩子	permission.ask（同步，不能等）	approval/request（异步 waterfall，能等）	tool_call 扩展事件（能 await，实测）	无审批环节（核心不问人）。有 StageBeforeToolcall 可否决，但语义不同 —— 见 B-8
拒绝理由能不能递给模型	能：output.reason	不能 —— 'rejected' 被翻译成写死的 the user rejected tool "X"；需在 tools/post-execute 返回 {kind:'block', feedback} 换掉（B-8.2c）	能：{block:true, reason}	N/A
会话列表	client.session.list()	ctx.sessionQuery.listSessions()	SessionManager.listAll()（不传参，传字符串会被当自定义目录）	N/A
模型目录	client.config.providers()（models 是对象）	ctx.llm.listProviders() + listModels()	modelRuntime.getAvailable()（不是 getModels()：1221 条里只有 1 条能用）	N/A（模型由核心配置，插件不选）
别名来源	session.slug（创建时就有）	模型标题派生	邮件主题派生（SDK 会话没有平台标题，见下）	邮件主题派生（无平台标题）
日志可见性	console.error	console.error（ctx.logger 不进 journalctl）	console.error	log.Printf 进 homed 的 journalctl（带 [plugin] 前缀）
工作区分组	session.create({directory}) 自带	ctx.get('workspaceRegistry') → create(cwd) + attachSession()	按 cwd 自动分目录（~/.pi/agent/sessions/--tmp-x--/），无需注册	N/A（无会话，无 cwd 概念）
工具参数命名	path / save_to	file_path / save_path	file_path / save_path	自定（本桥用 file_path / save_path 对齐其他平台）
权限三态	原生 once/always/reject	只有 allowed-once/rejected	只有 block/放行	N/A
「一直同意」	给，平台自己记	不给（表达不了，桥代劳会覆盖平台策略）	给，桥用 createGrantStore() 记	N/A

HomeAgent 为什么整列都是 N/A：它的核心是一个纯思维核 —— 本身没有任何对外交互能力，全部能力来自插件，也没有「会话」这一层 （单事件循环）。因此桥在这个平台上不做会话映射：所有邮件注入同一个循环， 靠 output_send__agentmail 输出通道把回复送出去。 它是四个平台里唯一不需要为每封邮件开一条平台侧会话的。

pi 为什么是守护进程而不是扩展：pi 扩展被加载进一条已经存在的会话， 那条会话的 cwd 由启动 pi 的人决定。而 B-3.1 要求每封邮件的 to_workspace 成为会话 cwd —— 扩展做不到「按邮件新开一条 cwd 不同的会话」。 桥因此用 SDK 起会话，一个进程里并存多条不同 cwd 的会话（实测可行）。 代价是它需要自己的 systemd 单元（deploy/pi-mail-bridge.service）。

pi 的 C-11 是有条件的：pi 会生成会话标题，但生成器在 pi-web 包里 （sessionNameGenerator.js），不在 pi-coding-agent 内核里。桥用 SDK 起的会话 走不到那条路径，session.sessionName 一直是 undefined。因此 pi 侧的别名走 D-5 阶梯的第二级（邮件主题派生），并把 Gateway 的定稿值回写进 session.setSessionName() —— 这一步让 pi-web 界面上显示的名字与邮箱里一致。

回写只能用 setSessionName()，三条实测约束：首条 assistant 消息落盘前 会话文件还不存在，pi 首次落盘用 openSync(file,"wx")，外部抢先创建会让它抛 EEXIST；活着的 SessionManager 从不重读文件，它自己后续的 session_info 会覆盖外部改名；空名字是清除语义，不是「不改」。

---

九、踩过的坑 / Pitfalls

按排查成本降序。新接平台前先扫一遍这一节 —— 每一条都是几小时到一天的代价。

9.1 followup() 的参数形状（花了一下午）

DSH 的 agent.followup(message) 要完整的 UserMessage：

agent.followup({ content: [{ type: 'text', text }], source: { kind: 'user' } })

照抄 opencode 的 parts 数组 [{ type: 'text', text }] 不会当场报错 —— agent-loop 会一路走到 preStep 里读 message.source.kind，然后抛 Cannot read properties of undefined (reading 'kind')。错误落在框架内部， 既不指向调用点也不说是哪个字段，turn 一 start 就 end、模型请求根本不发出去。

教训：「错了不当场报错、只在深处炸一个无关错误」的约定必须用测试钉住。 lib/message.js + test/message.test.mjs 就是为此存在的。

9.2 模型失败不是同步抛出的（两个平台都踩）

见 D-3。两次都表现为「第一个无效模型被判成成功，降级从不发生」。 opencode 侧还有个额外复杂度：event 钩子在 deliverMail 之外，需要一张 turnWatchers 表把两者接起来。

9.3 工作目录用了自己拼的临时路径

DSH 插件最初用 ~/.dsh/mail-sessions/mail-<uuid> 作 cwd，结果所有邮件会话在 平台界面上全落进「未分组」（平台按 cwd 分组）。而且 Gateway 当时根本没把地址的 path 位发给插件 —— 补了 SSE payload 的 to_workspace 才修好。

修好前后的会话目录名：--root-.dsh-mail-sessions-mail-<uuid>-- → --home-program-agentmail--。

9.4 opencode 插件入口只能有 default 一个导出

opencode 用 Object.values(mod) 把每个导出都当插件工厂检查（反编译确认）。 入口多导出一个 Map 就报 Plugin export is not a function，插件静默失效、 邮件全投不进去。

因此所有可测试的逻辑必须放 lib/ 子模块，入口只 export default。

9.5 Cordis 插件必须导出 inject

没有它 ctx.tools / ctx.agents 根本不存在（报 cannot get property "tools" without inject）。

但不要把可选服务写进 inject —— 那是硬依赖，服务没挂载时整个插件不启动。 DSH 的 sessionQuery 用 ctx.get('sessionQuery') 取：会话上报只是补全体验， 不该能把邮件投递整体拘死。

9.6 DSH 的 setup 应当留空

给 ctx.agents.create({ setup }) 挂 preset + installModelSelection 会让整个 turn 崩溃。base bundle 已经注册了 agent-loop / llm / tools， agentOptions: { provider, model } 就够了。

9.7 DSH 工具必须经 defineTool

直接给 ctx.tools.register 原始对象会报 parameters must be lossless JSON before schema projection。 defineTool 负责把 spec 格式的 parameters 转成 JSON Schema 并在 execute 前 校验，还必须声明 output: { schema, render }。

9.8 部署环境的坑

现象	原因	处理
读不到 ~/.agentmail/agent.key	systemd 不注入 HOME	service 里显式 Environment=HOME=/root
插件像没加载	opencode 插件懒加载	ExecStartPost 发一个空请求预热
ctx.logger.info 看不到	DSH 的 logger 不进 journalctl	用 console.error
dsh --patch 不生效	--patch 只对 dsh --profile <name> 有效	配置写进 profile 的 cordis.patch.yml
第二个实例起不来	task-board 的 ledger 文件锁	注入现有实例，不另起
平台活着但外网访问不了	转发层（socat / nginx）没跟着平台重启	见下

转发层的依赖要写两个方向。 平台监听 loopback、靠一个 socat 单元暴露到 LAN 或公网时，只写 Requires= 是不够的：

指令	管什么	少了会怎样
Requires=平台	平台停止时转发也停	——
PartOf=平台	平台重启时转发也重启	restart 后转发永久消失
平台侧 Wants=转发	平台启动时拉起转发	手工 start 后转发不起来

Requires 不含重启语义，PartOf 不含启动语义，单元自己的 WantedBy=multi-user.target 只在开机时生效 —— 三者缺一， systemctl restart <平台> 或 stop + start 之后就会出现 「平台进程活着、loopback 通、外网全不通」 这个很难联想到转发层的现象。

2026-09-02 真实发生过一次，隐形 9 小时：为验证插件的离线补投重启了 dsh， socat 被 Requires 带停后再没起来。加 PartOf 后又发现 start 起不来， 才补上平台侧的 Wants。

另外给转发单元加 SuccessExitStatus=143：被 SIGTERM 停掉是正常路径， 不加会在 systemctl status 里留一条红色 failed，掩盖真正的故障。

用 Wants 而不是 Requires 引用转发层：转发起不来不该阻止平台本身启动， loopback 访问仍然可用（插件走的正是 loopback）。

9.9 登记密钥的字段名是 key_token

POST /api/v1/admin/agent-keys 登记自带密钥时字段名是 key_token，不是 key。 传错服务端会静默生成一个随机 token 且全文只回一次。

9.10 node --test test/ 在 node 24 上报 MODULE_NOT_FOUND

它把目录名当模块解析。必须写 glob：node --test 'test/*.test.mjs'。

9.11 pi 的 followUp() 在会话空闲时什么也不做（静默丢邮件）

session.followUp(text) 只往 followUpQueue 里塞消息，而那个队列只在运行中的 轮次末尾被 drain（pi-agent-core/agent.js 的 run 循环，以及 continue()）。 会话空闲时（上一轮早已结束）塞进去的消息永远没人取。

表现极具欺骗性：日志打了「续谈成功」，prompt() 没报错，收件箱里却只有来信、 没有回复。既没有异常也没有超时。

正确做法：按 session.isStreaming 分流 —— 空闲用 prompt(text) 直接起一轮， 正在跑用 prompt(text, { streamingBehavior: 'followUp' }) 排到当轮之后 （缺 streamingBehavior 时 pi 会抛 Agent is already processing.）。 不要用 steer：那会打断当前轮，而当前轮正在处理上一封邮件。

9.12 pi 的全局扩展会 listen 固定端口

~/.pi/agent/extensions/ 下的 pi-a2a / pi-acp 在加载时就 bind 127.0.0.1:12010 / 12011。同机已有 pi 在跑时，任何新起的 pi 进程（包括 pi --help）都会 EADDRINUSE 并把整条会话拖死。

桥用 noExtensions: true + 内联 extensionFactories 起会话：既避开端口冲突， 也不继承那套给人类交互用的扩展（TUI 命令、快捷键、状态栏对邮件没有意义）。 邮件工具走 customTools，权限钩子走内联工厂。

9.13 SessionManager.listAll(dir) 的参数不是 agentDir

它的字符串参数是自定义会话目录，会直接在里面找 .jsonl。传 getAgentDir()（~/.pi/agent）得到的是空列表 —— 会话在它的 sessions/ 子目录下按 cwd 分目录存放。不传参数才会走默认的逐 cwd 扫描。

同理不要用 list(cwd)：桥的进程 cwd 与会话 cwd 无关，按前者过滤会漏掉 所有真正在干活的会话。

9.14 改名提议的标记拼错是静默失败

<!-- agentmail:rename-session alias="x" reason="y" --> 由服务端正则解析 （server/internal/handler/rename_proposal.go）。少个空格、把双引号写成单引号、 或把 reason="" 写成空属性 —— 邮件照常发出，提议凭空消失，而模型以为自己提过了， 在后续对话里当作已完成的事引用。

这就是为什么拼接必须收在共用库 lib/rename-proposal.js（T-13.2）： 三平台各写一遍的话，任一处的偏差都不会有人发现。 test/rename-proposal.test.mjs 里内置了一份服务端正则的等价实现来验证生成结果。

9.15 换 Gateway 地址后必须清 lastEventID 并重连 SSE

守护进程形态的插件（pi）提供 connect_to_server 时有个额外义务：改完 baseURL 要重建 SSE 长连，因为旧长连仍连着旧地址。

更微妙的是断点：lastEventID 是旧 Gateway 环形缓冲里的序号，拿它去问新 Gateway 会命中一段完全无关的历史（或被拒），收到的事件属于别人的会话。 GatewayClient.reconfigure() 在地址变化时清空它，于是重连以「首次连接」姿态 （不带 Last-Event-ID，见 N-11）进行。

插件形态（opencode/dsh）没有这个问题：它们的 SSE 由宿主生命周期管， connect_to_server 只改配置，下次宿主重连时自然用新值。

9.16 把来信人当权限决策人 → 会话永久挂死

插件手边最自然的决策人候选是「来信人」（mailContexts 里的 replyTo）， pi 侧一度就是这么传的。它在人给 Agent 派活时看起来完全正确，直到 Agent 给 Agent 派活：

jianf → pi（会话 A）          pi 把子任务分给自己（会话 B）
                              会话 B 触发 bash 权限询问
                              replyTo = "pi" → 权限邮件发给 pi 自己

后果不是报错而是死锁，而且是三重静默：

1. Agent 不可能在 Web 界面上点「同意」
2. 服务端 SendToUser("pi") 投进一个不存在的用户通道 —— 没有任何人被提醒
3. 插件里 await new Promise(...) 永不 resolve —— 没有超时、没有日志、没有回信

会话就那么停在那里，从外面看像「模型在思考」。实测发生过：两条会话排了任务， 只有一条在干活，另一条的最后动静是一封 to_name=pi 的 permission_request。

修法见 B-8.6 / N-13：不传 to，决策人由服务端沿会话上溯解析。 服务端是唯一能看到整条线索的地方；插件只有本地那点上下文，猜不出 「这条 Agent 链最初是谁派的活」。

排查这类问题的第一个动作： SELECT to_name FROM mails WHERE mail_type='permission_request' —— 出现 Agent 名就是它。

9.17 摆一个「一直同意」按钮却不实现它

比不给这个选项更糟的是给了但不生效。pi 侧一度在 options 里放了 ['同意','一直同意','拒绝']，放行正则也认 一直同意 —— 但没有任何地方记住它，所以点完下一条命令照样来一封邮件。

生产数据（修复前）：

同一条 pi 会话被问了 15 次 bash
permission_requests.result 全是「同意」—— 一次「一直同意」都没有

人不是不想点，是点了发现没用，于是退回去一条一条点「同意」。

判断一个平台该不该提供这个选项，看它的钩子能不能表达"以后别问了"：

• opencode 能（response:"always"）→ 给，且让平台记
• pi 不能（钩子只回 block/放行）→ 给，桥自己记（B-8.8）
• DSH 不能且不该由桥代劳（会覆盖平台审批策略）→ 不给

自查：在 options 里加任何选项之前，先在代码里搜一遍这个选项的文本， 看它除了"被展示"之外还出现在哪里。只出现在 options 和一条放行正则里， 就是这个坑。

---

9.18 摆一套权限规则，却从不调用，且形状根本没人能消费

比 9.17（给了按钮不实现）更深一层的错：代码看起来像强制力的实现。

lib/permission-mode.js 里曾有 opencodePermissions(mode)，实现完整、注释详实 （含 6 条实测结论）、还有 9 条测试把它的行为钉住。opencode 的 index.js 第 45 行确实 import 了它 —— 然后全文件再也没有第二次出现。

静态审计要花力气才能发现它是死的，而读代码的人会理所当然地以为 「opencode 的 plan 档由这套规则拦着」。实际不是：opencode 是 advisory。

它不只是没接上，而是接不上

查 1.18.29 的 SDK 类型定义，三条都排除：

// ① 会话级参数里没有 permission，也没有 agent（只有这两个字段）
export type SessionCreateData = {
    body?:  { parentID?: string; title?: string };
    query?: { directory?: string };
};

// ② permission 只存在于 Config / AgentConfig，而且是 map 形状
export type Config = { permission?: {
    edit?: "ask"|"allow"|"deny";  bash?: …;
    webfetch?: …;  doom_loop?: …;  external_directory?: …;
}; };

// ③ 权限事件也没有 action 字段
export type Permission = {
    id, type, pattern?, sessionID, messageID, callID?, title, metadata, time
};

而那个函数返回的是 {permission, action, pattern}[] —— 与三者都不匹配， 并且 deny 了 task（本版本 permission 的合法键里没有 task）。

所以这不是「加一行调用就能生效」，而是输出没有任何消费者。

为什么 per-session 强制在 opencode 上做不到

Config / AgentConfig 是配置文件级（全局或项目级）。邮件桥若靠改配置来 给某条会话加 plan 限制，会连带锁住这个人其他所有会话的同一工具 —— 一条 plan 档的邮件把人身兼的其他工作一起禁掉，不可接受。

opencode 目前的拦截路径只能是「它自己先问 → 桥转发 → 服务端按档位 409 → 桥当场 block」，前提是它的配置恰好是 ask；若配置直接 allow， 桥连 permission.updated 事件都看不到。这就是它只能是 advisory 的原因。

处理：删掉函数，知识搬进本节

死代码留着就是陷阱。函数与 9 条测试已删除，6 条实测结论保留在这里：

1. findLast 胜出 —— 规则数组里 deny 必须排在 allow 之前， 反了的话最后匹配到 deny，连允许的路径也被拒。
2. pattern 匹配 worktree 相对路径 —— 写 /tmp/** 这种绝对 pattern 永远匹配不上 （/tmp/x 相对 /home/program/agentmail 是 ../../../tmp/x）。
3. write / edit / patch 共用 edit 一个权限名（if(A==="write"||A==="edit"||A==="patch"){G.edit=I}）。
4. 全 deny 会让工具从模型清单里消失（模型自述「I don't have a bash tool available in this session」），部分 deny 则工具保留、越界调用才报错。
5. task（子代理）能绕过父会话权限 —— 实测中模型发现自己没 write， 主动 task 委派给一个带 write 的子代理去写成了。
6. bash 能绕过 edit 的路径限制 —— 模型用 shell 重定向写成了本该被 deny 的文件。

另注：opencode 原生有 plan_enter / plan_exit 权限项，与我们的 plan 档 撞名但语义不同（那是它自己的计划模式开关），不要碰它们。

自查：一个 export function 写完之后，除了它的测试，还有谁调用它？ 只有 import 行、没有调用点时，先查它的输出形状在目标平台里到底有没有消费者 —— 「形状没人认」比「忘了接线」更常见，且更隐蔽。

---

附：文档关系

文档	内容
本文	插件的规格：能力矩阵、行为约定、降级语义、线协议、不变量、验收清单
API.md	完整 HTTP API（含人类侧接口）
PLAN.md	分阶段实施记录与决策依据
PHASE7-REMAINING.md	未完成项与已知取舍

参照实现：plugins/opencode-mail-bridge/、plugins/dsh-mail-bridge/、 plugins/pi-mail-bridge/、deploy/remote-agent-demo.py（纯标准库的协议层对照）。