jianf/MailUI4Agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
17 Commits 1 Branch 0 Tags
fc330879826f3f0f37c16d6e60002e12e8dfb028
Commit Graph

5 Commits

Author SHA1 Message Date
JianFeeeee
e6fd2fafdc feat: agent 邮件寻址能力全面补齐 + .new 别名替换 
## 别名替换（让 .new 邮件可寻址）

repo/autoalias.go: AutoAliasFor + EnsureSessionAlias
- .new 建完会话立刻给别名（形如 dsh-重构导入路径）
- 名字与主题都要：只用主题跨 Agent 撞名，只用名字看不出聊什么
- sanitizeAliasPart 只留 unicode.IsLetter/IsDigit，其余折 -
- 撞名追加 -2/-3，全占用退 session-<uuid前8位>
- 不复用 SyncSessionAlias：那个假定已存在且跳过 manual
- 条件写入 WHERE alias IS NULL OR ''，并发安全
- resolveTarget 的 .new 与默认会话两条路径都调

notifyRecipients 加三个字段（每个收件方拿到自己那个地址的版本）：
- session_alias / reply_address / self_address
- 别名为空时退回省略 session 位，绝不写 new

FormatAddress(name,path,session) 空 path 也必须留 @ 与 .

## Agent 侧寻址发现（五个只读端点）

handler/agent_discovery.go:
- /agent/contacts + /agent/contacts/suggest（三段式补全）
- /agent/mail/{id} + /agent/mail/{id}/thread
- /agent/sessions/{id}/participants
- 不复用人类路由：scope 不同、审计需求不同
- 一律只读：归档/改名/权限决策仍只有人能做

repo/participants.go: SessionParticipants 逐封扫 from/to/cc
- Roles 用集合、MailCount 只数发信（0=还没开口的人）
- 发件人 path 不取 from_workspace（那列存的是 Agent 名）

repo.SuggestPaths 重写：mails.to_workspace（按 MAX(created_at) 倒序）
+ agents.workspaces 并集。原只读 workspaces，官方插件传 [] 永远空

## 共用模块（三插件逐字节相同）

lib/addressing.js: formatAddress/roleOf/replyAddressFor/selfAddressFor/participantsOfMail
lib/discovery.js: renderNameSuggestions/renderPathSuggestions/renderSessionSuggestions/
                  renderParticipants/renderContacts/renderThread

lib/inbox-format.js: renderMail 新增收件人/身份/可投递地址三段
  - selfName 参数（兼容旧调用不传的情况）

check-shared-libs.sh 纳入 addressing + discovery

## 插件侧

opencode: suggest_address + list_contacts + session_participants + read_thread + read_mail
dsh: 同上 + forward_mail（此前只有 opencode 有）+ upload_attachment 改真 multipart
pi: 同上（createMailTools 加 agentName 参数）

dsh: ctx.agents.create id collision 改为 readSession 探测后 resume
dsh: 关键路径日志改 console.error（ctx.logger 不进 journalctl）

## 测试

repo: autoalias_test.go 11 + participants_test.go 7 = 18 例
plugins: addressing.test 17 + discovery.test 23 + inbox-format.test 31 = 71 例
go test ./... + npm test（opencode 155 + dsh 173 + pi 199）全绿
端到端验证：admin 发 dsh@....new 抄送 opencode@....new
  → dsh 用 session_participants 取到地址 → send_mail 给 opencode
  → 地址取自工具返回值（.crisp-planet），未手工拼写
 2026-09-03 12:09:12 +08:00
JianFeeeee
289f37f7fb docs: PLUGIN-GUIDE 重写为 PLUGIN-CONTRACT（可核对的插件规格） 
原 PLUGIN-GUIDE 是叙事式的「怎么做 + 踩过的坑」，读者要自己从散文里推断
「我到底必须做什么」。接第三个平台时这不够用 —— 尤其当照着实现的是一个代理。

改为规格式，编号可引用、强度明确标注、每条尽量给出可机械核对的判据。
旧文档的内容全部保留（迁进第八、九节），另补上原先没有的四类：

## 一、能力矩阵（新增）

回答「这个平台能不能接」。七项必需能力（C-1..C-7）加七项可选（C-8..C-14），
每项给出判据。附一个七问自检 —— 任何一问答不出来就先别写代码。

其中 C-4「轮次结束信号必须能区分成功与出错」在两次适配里都被漏掉过，
两次都造成「无效模型被判成成功」，所以单独标了出来。

## 二、行为约定（重写）

原先散在各节的要求收拢成一个状态机，按事件逐条规定：B-1 启动 / B-2 心跳 /
B-3 new_mail / B-4 permission_decision / B-5 轮次结束 / B-6 无法处理时回信 /
B-7 启动补拉 / B-8 权限询问 / B-9 关停。

## 四、降级语义（新增）

平台缺某项能力时的确切退化路径（D-1..D-7）。原文档只说了「可选」，
没说缺了之后该怎么办 —— 于是「不支持权限钩子」很容易被实现成
「提供 request_permission 工具补偿」，而那正是 I-1 反对的模式。

## 六、不变量与禁止事项（新增）

12 条 MUST NOT，每条附「违反会怎样」。这些是测试全绿、跑起来也不报错，
但行为就是错的那类问题 —— 例如拉取失败时传 [] 而非省略字段会清空服务端目录。

## 七、验收清单（新增）

八组可勾选项，每条给出具体命令：grep 自查禁止事项、sqlite3 查在线状态与
配额未被消耗、停插件发信再启动看补投日志。

## 核对过的事实

写完逐项核对了代码，不是凭记忆：
- 12 个端点全部在 main.go 里存在且方法一致
- 发信 9 个字段名与 sendMailRequest 的 json tag 一致
- 心跳响应 12 个字段名与 handler 一致
- 九个数字（30s 心跳 / 25MB 附件 / 20 次每小时 / 补投 5 封 / 快照 200 条 /
  模型上限 10 / 目录上限 300 / 降级超时 60s / inbox 默认 5）都能在代码里找到出处
- 验收清单里的六条 sqlite 查询都在生产库上跑通
- 38 个编号无重复，18 处交叉引用全部有定义

引用同步：PLAN.md、PHASE7-REMAINING.md、API.md、README.md、
install.sh、check-shared-libs.sh。
 2026-09-03 08:09:54 +08:00
JianFeeeee
9e5c557cdf feat: 跨主机 Agent 验证 + 离线邮件补投 + 400 指向具体字段 
7.8「跨主机 Agent 发现」原计划（Gateway + Registry 拆分、etcd/Consul 注册）
取消，改为验证现有协议已经够用。验证过程暴露两个真实缺陷，一并修掉。

## 为什么不做注册中心

它要解决「Gateway 怎么找到 Agent」，而这个问题在本架构里不存在：
连接方向是单向的 —— Agent 主动连 Gateway，Gateway 从不外呼。
远端 Agent 只需要一个公网 URL 加一把密钥，被叫方自己会打进来。
注册中心要解决的「被叫方在哪」根本没出现过。

同一个理由此前已经决定了平台会话同步走插件上报而不是 Gateway 拉取。

## 验证方式：一个纯标准库脚本

`deploy/remote-agent-demo.py` 在另一台主机（192.168.2.106）上跑，
不装 AgentMail 的任何代码。注册 / 心跳（带模型目录）/ SSE 长连 /
收件箱 / 标记已读 / 发信全通，Gateway 侧 status=online 且 last_seen 随心跳推进。
完整一轮往返跑通：admin 发给 remotebot@/tmp/remotebot-ws，脚本回信入库。

「协议层面已支持」的含义就是这个：跨主机不需要新组件，只需要三个环境变量。

## 缺陷一：SSE 只推连上之后的事件，没人补拉积压

写那个脚本时第一版只挂了 SSE，启动前发的邮件永远不会被处理。
查了才发现**两个正式插件也有这个洞** —— 原以为它们做了补拉，实际没有。
后果比明确的失败更难排查：邮件躺在收件箱里，而发件人以为 Agent 收到了。

新增共用模块 `lib/catchup.js`，两插件在首个成功心跳后补投一次。五条约束
都对应一种具体的坏行为：

- 只在**首个**心跳后补 —— 每轮都补会把「模型正在处理中、尚未标已读」的
  邮件重复投递
- 串行、一次最多 5 封 —— 每封都要起一轮模型，并发放出去等于对上游打 N 个
  并发请求，且最后几封要等前面全部跑完
- 与 SSE 共用 deliveredMails 去重 —— 心跳与 SSE 建连之间有个窗口，
  那期间到的邮件两条路都会到
- 按时间**正序**投（收件箱倒序返回）—— 倒着塞进去同一会话的上下文是乱的
- permission 类不补投 —— 原来的工具调用早随进程没了，没有可恢复的上下文

端到端两平台各验一次：停插件 → 发信 → 启插件 → 日志「补投 1 封离线期间的
邮件」→ 回信入库；随后在线再发一封确认只回一次。

## 缺陷二：400 只说 "Invalid JSON"，不说是哪个字段

脚本把 `workspaces` 传成字符串数组（它要 `[{name, path}]`），
得到的只是一句固定文案，只能靠翻服务端结构体才能发现。
两个官方插件都传 `workspaces: []`，所以这个洞一直没暴露；
第三方客户端没有「翻服务端源码」这个条件。

新增 `handler.DecodeBody`，22 处 `Decode` + 固定文案的调用点全部换过去：

    {"error": "字段 \"workspaces\" 类型不对：期望 object，收到 string"}
    {"error": "JSON 语法错误（第 8 字节处）"}
    {"error": "请求体为空"}

刻意不回显 encoding/json 的原文 —— 它带 Go 类型名（models.Workspace），
那是本侧的实现细节，不该出现在公开 API 的响应里。期望类型用 JSON 的说法。
截断的 JSON 走 io.ErrUnexpectedEOF 而不是 json.SyntaxError，单独一条分支，
否则会落到笼统的兜底文案里（写测试时才发现）。

## 验证

- Go：13 个新测试（decode_test.go 含「不得泄漏 Go 类型名」断言）
- 插件：两侧各 10 个补投测试，共 200 个
- 共用模块同源校验通过（catchup 已纳入 check-shared-libs.sh）
- 生产已部署
 2026-09-02 22:47:31 +08:00
JianFeeeee
89356d4a9b feat: 每平台可用模型范围 + 降级尝试 + 失败回报 
配置页为每个 Agent 平台划定「邮件场景下可用的模型」，插件按顺序逐个尝试，
全部失败把原因封装成邮件回复。目录由插件上报、管理员只做勾选 —— 手打模型名
会打错，而打错的后果要到真发邮件时才暴露成一次失败。

## 目录上报走心跳，不另设端点

模型清单会在运行中变（换 provider 配置、上游上下线、换 API key）。
只在注册时报一次的话目录会静静变陈，管理员在配置页选中一个平台其实调不到的
模型。心跳本来就是 30 秒一次的现成通道；另设一个 POST 等于给「目录是谁写的」
留两个答案，排查时要同时看两处。

心跳响应回传 `allowed_models`，因此管理员改了范围后最多一个周期生效，
不必重启插件。

与 platform_sessions 同一约定：拉不到目录时**省略字段**（保留现有目录），
传空数组会把配置页清成空白。

## 目录与选择分两张表

模型会从平台目录里消失（上游临时下线、换了 provider 配置）。合成一张带
allowed 标记的表时，整行被删就连带把管理员的选择也删了，模型回来还得重配一遍。
分开存之后「选了什么」是持久的，目录只决定「这一项现在是否可用」；
已选但不在目录里的标为 stale 显示出来 —— 不显示会让人以为自己没选过它。

## 最难的一点：模型失败不是同步抛出的

两个平台都踩了。`promptAsync()` 立即返回、`ctx.agents.create()` 不校验模型，
只包 try/catch 的话第二个模型永远不会被试到 —— 第一个无效模型会被判成成功。

必须等异步结论：
- opencode → `session.error` 事件（event 钩子在 deliverMail 之外，
  因此用 turnWatchers 表把两者接起来）
- DSH → `turn/end` 的 `reason.kind === 'error'`

DSH 还有个陷阱：**`assistant/chunk` 不能当成功信号**，它的 `finish` 子类型
也带错误 —— `{chunk:{type:'finish',reason:{kind:'error',failure:{code:'NO_ADAPTER'}}}}`。
实测「无效 provider 却判成功」正是因为把任意 chunk 当成了走通。判据要落在
chunk 的类型上：finish 看 reason，其余才意味着模型真的在产出。

超时按成功处理（60 秒窗口）：模型可能只是很慢，把慢当成失败会在换模型的同时
把已经在跑的那一轮丢掉。

DSH 换模型要换会话 id（`<原 id>-r1`）并 dispose 失败那个 agent：复用同一个 id
会让重试接在一条已经出错的会话后面，不 dispose 则 agent/status 还会为那个
死会话触发一次自动转发。

## 其他决策

- **范围优先于环境变量**：范围是运行时可改的策略，`AGENTMAIL_REPLY_*` 是部署时
  的兜底。反过来的话管理员在配置页改了却不生效，得去改 service 文件重启
- **范围为空返回 `[undefined]` 而非 `[]`**：空数组会让调用方一次都不试，
  而「管理员没配」的正确含义是不限定，不是「一个都不许用」
- **上限 10 个**：降级是串行的，选 50 个意味着最坏情况下一封邮件要等 50 次超时
- 前端 key 按**第一个** `/` 切分 provider/model：model id 可能含 `/`
  （如 `org/model-name`），按最后一个切会把 provider 切错
- 保存后用服务端返回的结果刷新界面而非回显入参：repo 层会跳过重复与空字段

## 验证

- Go 10 个新测试（含「模型从目录消失后选择必须留存」的直接回归）
- 两插件各 18 个模型范围测试，共 180 个
- 端到端四轮：正常路由 → 全部无效（收到失败回报邮件，used_rounds 保持 0
  确认走了免配额通道）→ DSH 降级（fake-a 失败 → llmsproxy/AUTO 成功）→
  opencode 降级（nonexistent/bad 失败 → AUTO 成功，日志确认「前 1 个失败」）
- 生产已部署，前端「模型范围」页可用
 2026-09-02 21:34:55 +08:00
JianFeeeee
7c9be9fd58 docs: 插件适配指南 + 共用模块提取（为接入更多平台做准备） 
两次适配（opencode、DeepSeek Harness）里的方法与坑此前散落在提交信息和
代码注释里，接第三个平台时要重新翻。这次固化成文档，并把与平台 SDK 无关的
逻辑提到共用模块。

## docs/PLUGIN-GUIDE.md

八节：职责边界、必须实现的六件事、会话命名回写、平台会话快照上报、
平台差异对照表、踩过的坑（按排查成本降序）、新平台适配清单、共用模块清单。

三条设计原则贯穿全文，后面每一节都是它们的推论：

1. **平台原生信号才是真相来源**，不要求模型「记得」调工具 —— 因此不提供
   request_permission（改挂权限钩子）、不要求模型主动回信（改在「一轮结束」
   的平台信号上自动转发）
2. **插件代劳的转发不消耗配额** —— 因此这两类转发带 relay + relay_key
3. **平台命名优先** —— 因此创建会话时不传占位标题（那会掐掉平台自己的命名机制）

「踩过的坑」一节按排查成本排序，头一条是花了一下午的 followup() 参数形状。

## 共用模块提取

`lib/inbox-format.js`（新）：收件箱渲染与已读策略。三条规则各对应一次错误行为，
而它们与平台 SDK 无关：

- 附件必须带 attachment_id（只说「有附件」模型无从下载）
- 抄送人要显示（不显示模型以为是私信，回信时漏掉其他参与方）
- 只标本次列出的、status=all 时不标（limit 之外的还没看过；把历史邮件标成已读
  会让下一轮的新邮件混在里面认不出来）

顺带修好两处不一致：DSH 的 read_inbox 此前**完全没有标记已读**（每轮重复捞同一批），
且默认 status=all（同上）；附件大小两边一个显示字节数一个显示 KB/MB。

`lib/workspace.js`：提到两侧共用。签名从 (workspace, fallbackKey) 改为
(workspace, fallback) —— 各平台的兜底不同：opencode 有插件启动时的 directory，
DSH 只能落到 ~/.dsh/mail-sessions/<会话>（mailSessionFallback）。
opencode 侧此前是内联的三行判断，没有「目录不存在时不创建」与「拒绝相对路径」
这两条保护。

## deploy/check-shared-libs.sh

`lib/` 与 `test/` 下的共用文件必须逐字节相同，纳入 install.sh 门禁。

一侧改了另一侧没改，两个平台的行为就会悄悄分叉：同一封邮件在 opencode 那边
标了已读、在 DSH 那边没标，而两处代码看起来都「对」。这类分叉没有测试能发现，
只能靠 diff。

## 文档同步

- PLAN.md §7.7 从「待做」改为已完成，补 7.7.1（工作目录归属）与
  7.7.2（平台会话快照）两节，记录根因而非只记改法
- API.md 加「心跳与平台会话快照」章节；SSE 章节补 new_mail 与
  permission_decision 的 payload 说明（to_workspace 的语义、relay_key 的用途）
- PHASE7-REMAINING.md 移除已完成的 7.7，新增「每平台可用模型范围」的进展
  （repo 层已就绪，handler/插件/前端待做）
- README 文档索引与项目结构

验证：两插件共 136 个测试通过，同源校验通过，Go/前端全绿；
端到端发信 → DSH 用新的 read_inbox 渲染读取 → 自动回信 213 字节。
 2026-09-02 20:28:19 +08:00