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

23 Commits

Author SHA1 Message Date
JianFeeeee
c440df6537 修复：收件箱 ListInbox 漏算 to_human 导致人类地址被拼上 workspace/session 
根因：用户从收件箱点开邮件看到 。
收件箱路径 GET /me/mail/inbox 走 repo.ListInbox，它的 SQL 只算了
from_human，漏了 to_human（EXISTS users 子查询）—— 于是返回的
mail.to_human 恒为 false，前端 participantAddress 把人类 jianf 当成
Agent 拼成三段地址。

修复：ListInbox SQL 补 to_human 子查询 + Scan 补 &m.ToHuman。
这是 C 部分「人/Agent 区分」遗漏的最后一条路径（其余 mails 读路径
GetMailByID/GetSessionMails/GetSessionMailByID/ListSentBy 均已填）。

验证：GET /me/mail/inbox 返回 to_human: True，前端正确渲染 jianf。
 2026-09-07 06:17:25 +08:00
JianFeeeee
1dc6223631 L2: permission mode propagation across forward/calendar/adopt + PUT endpoint + tests 
P1 - forward inherits mode:
- doForward: when creating a new target session, use InheritedMode from
  the source session (plan parent → plan child, cannot escalate)
- enforcement snapshot set from receiving agent

P1 - calendar_events gets permission_mode column:
- Added to 3 migration sites (sqlite init, pg init, incremental alter)
- CalendarEvent model gains PermissionMode field
- CreateCalendarEvent / UpdateCalendarEvent normalize + persist the field
- resolveCalendarSession: on new session → write event's mode;
  on reuse → ModeAtMost(cur, eventMode), prevents escalation
  (plan Agent's reminder fires into a workspace session = bypass)
- SendCalendarMail now takes permMode and threads it through
- fireEvent passes event.PermissionMode to all delivery paths

P1 - AdoptPlatformSession explicitly writes default mode:
- Writes DefaultPermissionMode + enforcement on adopt, instead of
  relying on DB column default (avoids silent drift on schema changes)

P2 - PUT /sessions/{id}/permission endpoint:
- New handler UpdateSessionPermission (auth required, access check)
- Registers PUT route alongside existing budget/alias endpoints
- Broadcasts session_update on change
- Does NOT refresh enforcement (design: snapshot at creation)

P3 - Tests (24 new cases):
- permission_mode_test.go: InheritedMode (6 cases), SetSessionPermissionMode
  roundtrip, dirty value fail-closed, NormalizePermissionMode, calendar event
  roundtrip/dirty/update, adopt writes default mode, plan escalation guard,
  3-level inheritance chain
- defaultsession_test.go: budget regression, permission mode regression
  (pins created=false → no reset on reuse)

Deploys with: bash deploy/redeploy-gateway.sh --skip-tests
Schema migration: auto via addMissingColumns (new column default 'workspace')
 2026-09-06 17:32:47 +08:00
JianFeeeee
79c4171c9d feat: L0 线协议冻结 + 附件链路修复 + 人/Agent 区分 
L0 核心：
- 严格解码 Decode(DisallowUnknownFields) 全覆盖 29 个 DecodeBody 调用点
- DecodeLenient 心跳专用：容忍新字段但回报 unknown_fields
- 400 消息列出本端点接受的全部字段（jsonFieldNames 反射 tag）
- 日历 status 校验（create 补字段 + update 拦非法值）
- 新增 strictdecode_test.go 10 例 + blob/list_test.go 6 例

A-4 附件挂载回滚：checkAttachable 在 CreateMail 前校验，失败按
解挂→释放 relay→删邮件→退预算回滚，幽灵邮件这条路堵住了

A-5 反向 GC：blob.Store.List() 枚举磁盘（跳 .upload-*），
SweepUnreferencedBlobs 按 attachments + calendar_attachments 反查，
48h 年龄下限兜上传窗口。已接进每小时 sweep 循环

C 人/Agent 区分：四个读路径 + threadCols 补 from_human / to_human
（EXISTS users 判定），models.Mail 加 ToHuman。前端判据从
workspace 启发式改成显式布尔，mailCounterpart/sessionCounterpart
从 session_workspace 取 path（修 dsh@dsh 拼接 bug）

契约文档：SSE new_mail 补 4 字段（in_reply_to/from_human/
permission_mode/permission_enforcement），B-5 加 B-5.6
（Agent→Agent 不转发），B-3.4 MUST 改条件式，心跳补 mode_enforcement
+ unknown_fields，demo 死链修复 + from_human 检查
验收清单加 Agent→Agent 负向对照项
 2026-09-06 15:18:06 +08:00
JianFeeeee
a44fd6949b feat: 权限档位体系（三档 plan/workspace/full + 四桥 from_session_id） 
L2 核心改动：sessions 表补 permission_mode / permission_enforcement 两列
（sqlite + pg 同步），三桥 lib/permission-mode.js 翻译档位到平台原生配置，
homeagent advisory 模式提示词告知模型实际强制力。四桥全部携带 from_session_id
供 relay 去重与会话回溯。

FromHuman / ToHuman 判据已加入心跳 payload 与 notify/mail.go。
 2026-09-06 15:16:49 +08:00
JianFeeeee
344f970353 修死信黑洞：发信前校验收件人可达性 
## 事故

发给已彻底删除的 Agent 返回 200：邮件入库、分配 20 个来回预算、
建好会话，而那一端永远不会有人读。发件人看到 200 和一个 session_id，
以为送出去了。

实测（修复前）：
  POST /me/mail/send to=remotebot@/tmp  → 200
  mail_id 53e4c9ea… session dc8a41c3… budget_max 20

remotebot 的 agents 行在本会话早前已被 DELETE /admin/agents 删掉。

根因：三个发信入口的检查链只有「地址语法 / 调用权限 / 会话别名」，
从不问「这个名字存在吗」。`AgentDisabled` 那个函数只在注册路径被调用，
发信路径压根不查——它的注释甚至写着「Agent 不存在时返回 false」。

静默丢件比报错严重：报错能立刻改，静默丢件要等对方追问才发现。
这与之前修过的「relay_key 400 被当暂时失败导致静默挂死」同类。

## 修法

`repo.RecipientDeliverable(ctx, name)` 作为唯一判据：
- 人类用户 → 放行（人的收件箱一直在，不受 Agent 停用影响）
- Agent 在册且未停用 → 放行
- Agent 不存在 → ErrRecipientUnknown → 404
- Agent 已停用 → ErrRecipientDisabled → 409

`handler.checkDeliverable` 把它接到三个入口，**收件人与抄送位一起查**：
不查 cc 的话抄送位就成了绕过口，而且因为不是主收件人更不容易被发现。

- me.go   MeSendMail   （人类发信）
- mail.go SendMail     （Agent 发信）
- forward.go ForwardMail（人与 Agent 两条转发路径共用）

停用选择「当场拒收」而非「入库等恢复后补投」：停用的语义就是这个
Agent 现在不干活，让发件人以为信已送达更坏——它会照常等回信。

## 测试

`internal/repo/deliverable_test.go` 8 例：人类 / 在线 Agent / 不存在 /
删除后不可达 / 停用 409 / 恢复后重新可达 / 空名放行 /
同名人类优先于已停用 Agent。

负向对照：让 RecipientDeliverable 无条件 return nil（还原事故前行为），
UnknownName、AfterDelete、Disabled 三例如期失败。

## 线上验证

  发给已删除 remotebot        → 404「收件人不存在」
  发给在线 pi                → 200，pi 回信「可达性 OK」
  cc 位放已删除 remotebot     → 404（绕过口已封）
  停用 pi 后发信             → 409「已被管理员停用」
  恢复 pi 后发信             → 200

## 顺带

- 部署改用 sqlite3 .backup + install -m 0755（原子 rename，不写坏
  运行中进程镜像），来自 git-release-discipline skill 的运维纪律
- 清理本会话测试残留：误登记的 opencode 密钥、remotebot 两把残留密钥、
  死信测试邮件与会话
 2026-09-05 09:58:36 +08:00
JianFeeeee
9ebb8dfb41 Agent 删除：后端 DELETE /admin/agents/{name} + 名字退役保护 
## 新增端点

DELETE /api/v1/admin/agents/{name} → 清 Agent 全部运行态，保留邮件历史。

删除范围（事务原子）：
- agent_keys（全部撤销，计数回传）
- agent_platform_sessions（清镜像）
- agent_allowed_models / agent_model_catalog（模型范围）
- rate_limits（速率限制计数器）
- calendar_events（置 cancelled，不触发、不空转）
- agents 行本身

保留范围（审计凭据，不删）：
- mails（历史邮件）
- sessions（线索与邮件一起组成线索）

内置管理员 jianf 不可删（二次保险）。

## 名字退役保护

`IsRetiredAgentName`：agents 表里没有 + mails 表里有引用 = 已退役。

注册路径（RegisterAgent）+ 密钥登记路径（CreateAgentKey）两处都拦。
后者原来会级联建 agents 行，绕过注册检查——现在名字退役时
CreateAgentKey 也返回 409。

## 错误信息

`writeKeyErr` 加 `strings.Contains(err, "已退役")` 分支，返回 409
而不是通用的「密钥操作失败」。

## 前端

QuotaPanel：每个 Agent 行右侧加「删除」按钮，二次确认里
明确说明「邮件保留，此名不可再用」。恢复与删除共用一套
confirming 状态，通过 confirmAction 区分。

## 测试

gateway build + vet + go test 全绿（预存农历 bug 不是本轮引入）。
生产验证：remotebot 删除后数据库四张表清空、-mails 保留；
同名建密钥被 409 拦截；jianf 删除被 403 拒绝。
 2026-09-05 00:28:05 +08:00
JianFeeeee
784192d8c4 Agent→Agent 不自动转发 + 提示词区分新活/回复/补投 
## 设计规则：Agent 之间不自动转发

自动转发存在的理由是「人不该等模型记得调 send_mail」—— 收件方是人时这是
纯收益。**收件方是另一个 Agent 时这个理由不成立，而且有害**：双方的插件都
会自动回一封，于是两个模型都以为「我只要把话说完就行」，实际在持续互相唤醒。
生产实测 pi 与 dsh 客套 6 轮直到撞上连续 relay 跳数上限。

规则现在写死在共用模块 `lib/relay-policy.js`（三平台逐字节相同）：
- `autoRelayDecision` — 插件该不该替模型开口
- `replyInstruction` — 提示词怎么跟模型说（人类 vs Agent 各一套措辞）
- `inboundHeadline` — 进来的是新活、回复、还是补投

`from_human` 缺失时保守按 Agent 处理：宁可让模型多调一次 send_mail，
也不能承诺一个不会发生的自动回信让发件方白等。

## Gateway 侧：`in_reply_to` + `from_human`

- `notify.Mail` 新增 `ParentMailID`（非空 = 这是对收件方某封信的回复）
- `notify.Mail` 新增 `FromHuman`（走 `repo.IsHumanUser`）
- SSE payload 里叫 `in_reply_to` / `from_human`
- 四个调用点全部传入：handler/mail（转发后产出的邮件，parentMailID 从
  resolveTarget 取）、handler/me（同理）、handler/forward（传空串，
  因为对收件方而言那封原邮件不在它的线索里）、scheduler/calendar（传空串）
- `ListInbox` 的 SELECT 加 `EXISTS (SELECT 1 FROM users u WHERE u.username = m.from_name)`
  → `models.Mail.FromHuman`，让补拉路径也有这个信号

## 提示词分流

三种处境各一套标题：
- 新活（人类）：「你收到一封新邮件」+ 「回信不用你自己发：…」
- 新活（Agent）：「你收到一封新邮件（对方是一个 Agent）」+ 「插件不会替你
  回信。需要回复时你必须自己调 send_mail…请先判断是否真的需要回复」
- 回复到了：「你上一封信的回复到了。**这不是新任务**。」
- 补投：在标题里说明「离线期间积压」

## homeagent 特殊处理

Go 插件不能直接 `import('../lib/relay-policy.js')`，因此新增 `relay_policy.go`
（Go 对应物）+ `relay_policy_test.go`（11 例，逐条对齐 Node 侧判据）。
`sseLoop` / `catchUp` 两条路径都接上。

## `mailEvent` 命名类型

homeagent 的 SSE 事件解析 / handleNewMail / handlePermissionDecision 三处
原来各写一遍匿名 struct（字段列表几乎相同），加 `from_human` / `in_reply_to`
时漏改一处 → 编译报错但错误信息是两串几乎相同的字段列表，极难定位。
提成 `mailEvent` 命名类型：一处改、三处跟着走。

## 测试

- `lib/relay-policy.test.mjs`（Node）16 例：含「replyInstruction 与
  autoRelayDecision 不得互相矛盾」「Agent 来信的标题要点名且回复要明确反对」
- `relay_policy_test.go`（Go）11 例：逐条对齐 Node 侧
- `turn.test.mjs` +3 例：from_human 缺失时按 Agent 处理 / Agent 来信时改口 /
  回复到了说「不是新任务」；删掉两条旧的「必定自动转发」断言
- 共用脚本 `check-shared-libs.sh` +1 个文件（relay-policy）
- pi 288 / dsh 241 / opencode 217 / homeagent 14 / gateway 8 包全绿
 2026-09-04 23:52:52 +08:00
JianFeeeee
c297468819 修 platform_session_id 无差别下发导致抄送方邮件静默消失 + homeagent 补投漏去重 
## platform_session_id 只发给归属方（Gateway）

`notify.Recipients` 原来对所有参与方推同一个 `platform_session_id`，
而那是**会话级**的一个值。生产实测：会话 16845133 接管了 pi 的平台会话
`01a05a5e-…`，那封邮件抄送了 dsh@/home/program/agentmail.new。DSH 收到
同一个 id，在 ~/.dsh/sessions/ 里查不到（那是 /root/.pi/agent/sessions/
下的文件），于是走进「平台侧会话已删」那道防线抛错。

那道防线本身是对的（N-8：不能退回新建，否则人在界面上看不到这封邮件带来
的对话），它拦下的却是「别人的会话」。异常被 ctx.logger.error 吞掉，而
DSH 的 logger 不进 journalctl —— 邮件静默消失，日志里一个字都没有。

- 新增 `repo.PlatformSessionFor` 一并返回归属 Agent：以镜像
  `agent_platform_sessions.agent_name` 为准，镜像整表替换后退回
  `sessions.from_agent`（AdoptPlatformSession 写在那里）
- `PlatformIDOf` 变薄封装，保留原签名
- `notify.Recipients` 加 `platformFor(forName)`：归属方以外一律空串；
  归属抽不到时（owner 空）也不下发 —— 宁可退回当普通会话处理，
  也不让一个抽不到归属的 id 把邮件弄丢
- 归属与收件角色无关：归属方在抄送位上同样拿到

## homeagent catchUp 漏 deliveredMails 去重

`go p.catchUp(…)` 与 `go p.sseLoop()` 是两个并发 goroutine，重启时窗口
重叠：SSE 推一次 + 补投拉一次 = 同一封邮件注入两遍。homeagent 的回信正文
印证了这一点（「之前的对话时序中已经收到并确认过多次了」）。另三个插件的
catchUp 都有这层双查，只有这里漏了。

去重放在循环内逐封查而不是拉完一批再筛：InjectInputSync 一封要跑几十秒，
那期间 SSE 完全可能已经投过后面那几封。

## DSH 接管失败改用 console.error

DSH 的 ctx.logger 不进 journalctl，投递失败是「发件人等不到回信」的唯一
线索。接管失败点与 SSE 分发的 catch 都改走 console.error，并带上 mail_id
与发件人。

## 前端 ccAddress 移除（收尾上一轮未提交的改动）

cc_list 里的 `.new` 是**原始意图**，不该被替换成主收件人的别名：每个抄送
方的 `.new` 是独立的 —— pi@/x.new 给 pi 开一条、dsh@/x.new 给 dsh 开另一
条，各有自己的别名。数据库存的就是原文。删掉 ccAddress，MailView /
ThreadView 直接显示 c.raw。

## 测试

- `internal/notify/notify_test.go` +3 例：挂真实 SSE 客户端读帧，验
  归属方拿到 / 抄送方为空 / 归属方在抄送位也拿到 / 普通会话全空。
  负向对照跑过：platformFor 无条件返回时两条用例失败
- `internal/repo/platform_owner_test.go` +3 例：镜像取归属、普通会话、
  镜像被清后退回 from_agent
- 修好 web/test/components/replyTarget.test.tsx（上一轮遗留的语法损坏），
  三条 .new 用例改成断言原样保留
- gateway 7 包全绿；web 176 例 + 主题 26；dsh 219 / pi 250 / opencode 201

## 生产验证

- 抄送验证：jianf → pi（接管会话）cc dsh。DSH 正常建会话并回信「收到」，
  pi 走接管续谈 —— 两封回信都落在同一条线索上（此前 DSH 那封不存在）
- homeagent 去重：连发两轮，其中一轮在邮件未处理完时重启 homeagent 造出
  SSE/catchUp 并发窗口，两轮都只产生一封 Re:
- homeagent SSE：换新 plugin.bin 后连续 89 分钟零断连（此前 2 小时 102 次
  deadline exceeded 自激振荡）
 2026-09-04 19:06:36 +08:00
JianFeeeee
30b78ef2cd fix: SuggestPaths 从镜像取路径 — 清库后路径补全不再为空 
SuggestPaths 原来只查 mails.to_workspace（清库后为空）和
agents.workspaces（标准插件永远为空） → 清库后路径补全对所有
Agent 都空，界面提示「没有可用路径」。

加第三个来源：agent_platform_sessions.workspace（镜像，心跳上报）。
清库后镜像仍在（心跳重新上报），补全立即恢复。

按使用频率降序排列，常用路径（/root, /home/program/llmsproxy）
排在前，测试路径（/tmp/pi-bridge-e2e/ws）排在后。

顺带修了 SQL：SELECT DISTINCT + ORDER BY MAX() 不加 GROUP BY
在 SQLite 上语法错误（静默返回空集而非报错）。
 2026-09-04 15:50:27 +08:00
JianFeeeee
e8583ecd41 fix: 事故全链路修复 — 调度器合流 + 接管保护 + 补全去重 + 权限显示 + homeagent SSE 振荡 
## 事故现场

用户选中补全里的「项目定位」→ 邮件投进另一条会话，界面显示的名字也不是
自己选的那个。授权页只显示 Agent 名，看不出哪个目录哪条线索。

## 四处因果链

**① 调度器自己的 new_mail payload（起点）。** `notifyRecipients`（handler）
与 `SendCalendarMail`（scheduler）是两份代码。加 `platform_session_id` 时只改了
handler 那份 → 日历提醒投进接管会话时插件不知道是接管 → 另开一条新会话 →
命名同步冲掉接管会话的别名。

修法：抽出 `internal/notify` 包，唯一入口 `notify.Recipients`。
handler / scheduler / permission.go 都走它。新增字段时不存在「另一处忘了改」。

**② SyncSessionAlias 覆盖接管别名。** 别名是人从补全里选中的平台 slug，
任何平台命名同步都不该动它。加守卫 `platform_id <> ''` → 有绑定就返回当前值。

**③ SuggestSessionCandidates 按别名字符串去重。** 别名一被冲掉，同一条会话
出现两次（一次被冲的名字、一次镜像 slug），而另一条真实会话被吃掉。
改按 `platform_id` 去重。 mail 侧查 `s.platform_id`，镜像侧查 `platform_id`。

**④ FindOrCreateDefaultSession 不排除接管会话。** 日历提醒省略 session 位 →
FindOrCreateDefaultSession 挑中人显式指定的接管会话。加 `platform_id = ''` 条件。

## 权限页

**CreatePermissionMail 不写 from_workspace。** `from_workspace` 存空串 →
前端 `g.path && ...` 不渲染 → 人只看到光秃的 Agent 名，不知道哪个目录
哪条线索在请求权限。修法：INSERT 时从 sessions.workspace 取。

**SSE payload 缺 session_alias。** permission.go 的 SSE 不走 notify 包（决策人
不是地址解析出的参与方），但 payload 也要带 `session_alias` → 前端拼出
`pi@/home/program/agentmail.别名`，而不是光秃的 `pi`。

**mailGroups.ts：path ← session_workspace。** `from_workspace` 对 Agent 存的是
Agent 名（历史遗留），不能当路径用。PermissionList 显示完整三段地址
`agent@path.alias`。

## NarrowStack z-index

窄屏日历的星期表头（`sticky top-0 z-10`）穿透到二级页面之上。覆盖层
auto z-index 输给 z-10 → 底层组件的层叠穿透到覆盖层。

修法：底层容器加 `isolate`（isolation: isolate），自成层叠上下文；
覆盖层加 `z-10`。只给覆盖层加 z-index 只能治当前一处，底层再写更大的
z-index 又会复现。

## homeagent SSE 自激振荡

根因：五处缺陷叠加，SSE 每 60 秒断一次 → Gateway 全量重放 → 再断 → 再重放。

1. `p.client`（60s Timeout）跑 SSE 长连接 → 新增 `sseClient`（无超时）
2. `InjectInputSync` 在读循环里同步调用 → 改为 `go p.handleNewMail(evt)`
3. `lastEventID` 无条件赋值，Gateway 重放时发旧 ID → 单调递增 `sseMaxID`
4. 无邮件级去重 → 补 `deliveredMails map[string]bool`
5. 手动 `[]byte` 管理：每次 `buf[lineStart:]` 缩小 cap → 最终 len==cap
   → Read 零长切片 → 满速空转。改 `bufio.Reader`。

## 清库

保留 jianf + 4 个 Agent 密钥 + 模型范围配置。清掉 mails/sessions/
calendar_events/attachments/agent_platform_sessions/relayed_mails/
permission_requests/rate_limits。测试数据已全部清零。

## 测试

- gateway 7 包全过；repo + 7 例（adopt_alias_test.go）
- web 182 例（mailGroups 新增 session_workspace 断言）
- 前端构建通过
 2026-09-04 15:35:48 +08:00
JianFeeeee
55b3f9bc4e fix(web): 地址显示按「人 / Agent」分维度 —— 别名跟 Agent 走，人只显示名字 
## 症状

单封邮件的元信息三行都不对（生产实测那封 12:12:12）：

    发件  jianf.邮件驱动·多智能体协作平台-完整设计文档-一、项目概述-11-项目定位
    收件  pi@/home/program/agentmail
    抄送  pi@/home/program/agentmail.new

人指定的是「投进 pi 的那条会话」，而界面把会话别名拼给了**发件人**。

## 三处错

**1. 别名拼错了一方。** `name@path.session` 三段才唯一确定「哪个 Agent、
在哪个目录、哪条线索」—— 别名必须跟 Agent 走。拼给发件人之后收件人变成
`pi@/home/program/agentmail`，那指向**默认会话**而不是人指定的那条。

**2. 人不该有目录和会话位。** 人没有工作目录，发给人就是进收件箱。
`jianf.某会话` 是把 Agent 的三维语义硬套在人身上，而且因为 from_workspace
为空，拼出来的形态连 ParseAddress 都还原不了 —— 没有 `@` 时整串被当成
**名字**（实测 name="jianf.某会话别名"），投递必然 404。

**3. 抄送残留 `.new`。** 它是一次性动作，建完会话就失效；留着会让人以为
再发一次还能投进同一条会话，实际会开出第三条。

## 修法

`identityAddress` → `participantAddress(name, workspace, alias)`，
判据是有没有 workspace：

    Agent → pi@/home/program/agentmail.日程提醒：…    三段齐全
    人    → jianf                                     裸名字

`ccAddress` 按同一判据分流；`.new` 换成当前会话别名。
六处手工拼接（MailView / MailList ×2 / ThreadView）统一走这两个函数。

## 顺带修掉 `dsh@dsh`

改的时候实测发现：**`mails.from_workspace` 对 Agent 存的是 Agent 名而不是
路径**（历史遗留，见 db/migrate.go 里 sessions.workspace 的注释）。
拿它当路径拼，Agent 发来的信显示成 `dsh@dsh`。

会话的 workspace 才是权威来源 → `models.Mail` 新增 `SessionWorkspace`，
六处查询补 `s.workspace`：GetMailByID / ListInbox / GetSessionMails /
GetSessionMailByID / ListSentBy / threadCols。

## formatAddress 与后端对齐

第一版我改成「path 为空时舍弃 session 返回裸名字」，对着后端 ParseAddress
跑了一遍才发现搞反了 —— **正确形态是保留 `@`**：

    jianf@.任务  → name=jianf path="" session=任务   ✓
    jianf.任务   → name="jianf.任务"                  ✗

现在两端六个 case 逐例一致（这个分支只在内部逻辑上用得到；
展示一律走 participantAddress，人根本不带会话位）。

## 取舍

列表行与对话树节点**不带会话位**：列表的分组头已单独显示别名，
树的每个节点都在同一条线索上 —— 重复无信息量，而 92 字节的别名会把那行挤没。

## homeagent 日程工具的两个修复（同批）

**查询串手拼吃掉了时区。** RFC3339 的 `+08:00` 里那个 `+` 在查询串里正是
空格的转义形式，服务端 ParseQuery 还原成空格 → time.Parse 失败 →
AgentListCalendarEvents **静默退回默认区间**（不报错）。表现为「明明有日程
却说一条都没有」。改走 url.Values.Encode()。

**默认窗口 3 个月太窄。** yearly / lunar_yearly 的下一次触发随时落在窗口外，
模型问「我建过什么」得到空结果，然后照着空结果再建一条重复的。改成 14 个月。
空结果的话术也从「你还没有建过日程」改成说出实际查询区间 —— 前者在窗口外
有事件时是假话。

## 验收

- web 182 例（replyTarget 24 → 46）；tsc 无错；Gateway 7 包全过
- 新增 test/manual/addr-verify.mjs：真渲染两个方向都验过
    人 → Agent：jianf / pi@/home/program/agentmail.日程提醒：…
    Agent → 人：dsh@/home/program/agentmail.查看工程与插件适配指南 / jianf
  判据含「Agent 的 path 必须是真路径而不是 Agent 名」（锁 dsh@dsh 那个 bug）
 2026-09-04 13:49:16 +08:00
JianFeeeee
255c799a40 feat(adopt): 邮件可投进平台上已存在的会话（TUI 与邮箱同一入口） 
人在平台界面（pi TUI / opencode / DSH GUI）里开的会话，此前无法被邮件投进去。
补全早就把它们列为候选（agent_platform_sessions 镜像，插件心跳上报），
但投递侧的 FindNamedSessionFor 只查 sessions 表 —— 选中后只能得到 404。
候选列表在承诺一件做不到的事。

TUI 与邮箱是同一个 Agent 的两个入口，不是两套隔离的世界。

## Gateway

sessions 表加 platform_id 列 + 部分索引。resolveTarget 的 SessionNamed 分支
本侧查不到时再查镜像，命中则「接管」：本侧建一条会话并绑定 platform_id，
之后每次投递都在 SSE 事件里带 platform_session_id。

- FindPlatformSession(agent, slug, workspace) 查镜像
- FindSessionByPlatformID 防重复接管（一条平台会话只能被接管一次，
  否则同一条对话在邮箱里裂成多条互不相干的线索）
- AdoptPlatformSession 建会话 + 绑定 + 别名复用平台 slug（撞名自动加后缀）
- PlatformIDOf 供 notifyRecipients 读

三处语义决定：
- workspace 以平台会话为准（它的 cwd 创建时就定了）。地址 path 位不同则不命中，
  否则邮件会投进另一个项目的会话
- 主题优先用平台侧标题（它代表整条对话在谈什么，也是补全里显示的）
- 接管计入 AllowNewSession 速率限制 —— 镜像里可能有几百条 slug，
  不计的话它是绕过限流的后门

## 插件

字段解析与失败话术抽成共用模块 lib/adopt.js（三方逐字节相同 + 进同源校验）：
字段名各写一遍时少个下划线就静默退化成「每封邮件新开一条」，而那个错误不抛异常。

- opencode：session.get 确认存在 → 照常 promptAsync（服务端持有会话，单一写者）
- DSH：复用 startAgent 的 resume 分支，会话 id 换成平台自己那个；
  界面上正开着时直接 followup（两个 handle 会各自写日志，replay 过不去）
- pi：SessionManager.open(file) → 跑一轮 → dispose，不放进长期缓存

pi 必须短暂持有：SDK 无任何锁机制（flock/lockfile 命中 0），活着的
SessionManager 不 watch 文件 —— 外部追加的行看不见，算出的 parentId 指向
对方不知道的 entry，会话树分叉。写入是纯 append 所以文件不会坏。
配套三处：isStreaming 时不释放（否则杀掉排队中的下一封）、兜底计时器
（轮次超时 ×2，unref）、接管会话跳过命名同步。

最后一条是实测撞出来的：别名撞名时 Gateway 加后缀，而定稿别名又回写进 pi
会话文件 → 下次心跳上报的 slug 变成带后缀那个，人从补全里选的名字凭空消失。
opencode/DSH 无此环（它们的 slug 只读不写）。

接管后必须加入 mailDriven 集合，否则邮件投进去了却永远没有回音。

## 迁移顺序

idx_sessions_platform 不能写在 init_sqlite.sql 里：那个脚本在
addMissingColumns 之前执行，而已部署的库里 sessions 表已存在
（CREATE TABLE IF NOT EXISTS 不补列）→ 索引建在不存在的列上，
整个迁移中断、服务起不来（生产实测）。依赖补出来的列的索引一律放
migrate.go 的 sqliteAddIndexes。PG 侧用 ALTER TABLE ADD COLUMN IF NOT EXISTS。

## 生产验证

- pi × 2（agent-only-chain / mail-probe-alias）、opencode（glowing-moon）、
  dsh（查看工程与插件适配指南）四条链路接管成功
- dsh 那次回信准确说出了界面上聊过的内容 → 上下文确实装回来了
- 第二封复用同一条本侧会话，平台侧无新增改名条目
- 回归：opencode 普通 .new + 别名续谈 + used_rounds=0（免配额通道未受影响）

## 其他

pi-mail-bridge 补 systemd 单元（此前是 setsid 裸进程，重启机器不会拉起）：
陈锁清理 ExecStartPre、MemoryMax=4G、TimeoutStopSec=10。
配置目录必须与 opencode 分开（共用会让后起的读到对方密钥或撞单实例锁）。

PLUGIN-CONTRACT.md 加 B-3.7 / B-3.8 + new_mail 字段表 + 检查清单验收项。

测试：repo +10 例（adopt_test.go）；三插件各 +7 例（adopt.test.mjs）
 2026-09-04 11:14:44 +08:00
JianFeeeee
2ae4df0e98 feat(agent-calendar): Agent 侧日历端点（可写，只能动自己建的） 
在这之前 /calendar/* 全挂在 UserAuth 后面，Agent 密钥一律 401。
于是「明天九点提醒我看 CI」只能靠插件进程里的 setTimeout —— 进程一重启
定时器就消失，那条提醒静默不见且无处留痕。放进 Gateway 后由数据库与
调度器保证：插件重启、Agent 换机器、甚至换平台都不影响。

更重要的是它让**跨 Agent 的任务交接**成立：模型可以给 dsh 设一条
「明天交周报」的提醒。这件事模型自己做不到 —— 它没法让另一个进程在未来
某刻醒来。

三处收紧：

**1. 只看/只改自己建的。**
别人的日程里可能有它无权知道的会议与地址。不存在与不属于我都回 **404**
而非 403 —— 后者会泄漏「这个 id 存在」，让 Agent 能枚举出别人有多少条日程。

**2. 不能设给人类。**
理由是投递通道不对等。Agent 之间的提醒是任务信号：收到就干活、干完回信。
发给人的提醒是打扰 —— 进收件箱、触发未读徽标，而人**无法回信让它停下**
（提醒是日历实体不是对话），只能去 WebUI 里找出那条事件删掉。
一个 Agent 建条「每 10 分钟提醒 jianf 检查进度」的代价远大于收益
（它其实可以直接 send_mail）。

**3. 速率 + 总量双闸。**
速率（20 次/小时，独立桶）压住「短时间暴建」，压不住「每小时建 19 条、
连建一周」—— 而日历事件是**长效**的，一条每日重复提醒会一直发下去。
攒下 300 条之后即使停止建新的，每天仍有 300 封提醒涌出来。
所以加 maxActiveEventsPerAgent=50，并在列表响应里回传 active_limit：
模型看到 42/50 就知道该清理，只在撞墙时才报错等于让它一直蒙在鼓里。

其他设计点：
- **PUT 是部分更新**（人类端点是整体替换）。调用方是模型 —— 要求它每次
  回传全部字段，漏一个就把提醒正文或收件人清空，而那种破坏没有任何报错。
  全部字段用 *T，nil = 没传 = 保持原值。
- 一次性事件设在过去拦掉（会立刻触发，几乎总是时区或年份写错）；
  重复事件不拦 —— 「每天 9 点」从昨天开始是合理写法。
- 收件人省略时默认给自己：最常见的用法，每次要求写出自己的名字只会让
  模型忘记然后拿到 400。

顺带：两个 handler 文件各写了一份手写 itoa（models_scope 那份还漏了负数），
统一成 strconv.Itoa。

测试 repo 9 例：创建者过滤、收件人≠创建者不返回、总量计数、
速率桶与会话桶独立、按 Agent 隔离、失败归还名额。
生产实测 11 项全过（含 403/400/404/429 各条边界）。
 2026-09-04 06:28:33 +08:00
JianFeeeee
069bf03ae2 feat(calendar): 日历后端 —— 事件/提醒/重复规则 + iCal + 多收件人 
三层分离：事件是日历实体，提醒是触发器，邮件是投递通道。
`from_name = "calendar"` 刻意既非人类名也非 Agent 名 —— 用创建者的名字
会让 Agent 以为人在实时找它，而人此刻可能在睡觉，模型据此判断
「要不要马上追问」，来源写错会让它问一个不在线的人。

日历提醒不扣会话预算：预算的语义是「这件事值得模型自主发多少封信」，
而提醒是人预先设定的定时任务，不是模型的自主行为。

**多收件人两种投递模式，都要**：
- separate（默认）= 各发一封、落各自会话、互相看不到
- together        = 首个为主收件人、其余进 cc_list、共享一条线索

「让三个 Agent 各自独立汇报」与「让 pi 主办、dsh 知情」是完全不同的任务
形态。默认 separate 因为失败模式更轻：together 用错会让本该独立判断的
Agent 互相看到回复而趋同，那种上下文污染事后无法分离。

抄送方也推 SSE。漏了这步的后果很隐蔽：cc_list 里有他们、查收件箱看得见，
但没有任何事件推给他们 —— 插件不会唤起会话，Agent 到下次补拉才发现。

recipients 存**原始地址串**而非结构化：session 位的 new/别名三态该在
触发那一刻解析，存结构化会让「.new」这种一次性语义在建事件时就被固化，
而重复事件每次触发都该重新决定落到哪条会话。

---

修掉的七个真问题：

**1. 默认提醒模板把时间烤成字面值。**
原来 Sprintf 出含字面时间的正文存进 reminder_text。对重复事件是错的：
AdvanceRecurrence 只推进 event_time，模板不动 —— 「每天 9 点」的提醒
从第二天起永远写着第一天的日期，且不报任何错。改为存变量形式。

**2. `{time}` 渲染成 UTC。**
DSN 带 _timezone=UTC，读回的 EventTime 是 UTC。直接 Format 会把人在
+0800 输入的 14:30 写成 06:30，而前端预览用本地时间 —— 两边差 8 小时
且都不报错。

**3. 同一提醒每 tick 重发一次（生产实测 4 封）。**
DueEvents 有 60 秒 lookahead（周期 30 秒，不提前看会迟到）。去重判据
原本是 `last_fired_at < event_time` —— 触发时刻本来就早于落在窗口内的
event_time，条件恒真。实测一条 12:53:17 的事件在 12:52:30 / 12:53:00 /
12:53:06 / 12:53:36 各发一封。新增 fired_for 列记录**已触发的
occurrence**，判据改为 `fired_for <> event_time`。

**4. 过期重复事件刷屏。**
AdvanceRecurrence 只推一步：一条 100 天前设的每日事件每轮都判定过期 →
发一封 → 只前进一天 → 下轮又过期。实测 30 轮触发 30 次，而周期是
30 秒。改成 advanceToFuture 一路推到越过当前时刻；跳过的 occurrence
不补发（三个月前那次站会提醒现在发出去毫无意义，只会淹掉该看的那封）。
带 maxAdvanceSteps=4000 上限：农历路径依赖外部库，没有上限就是个死循环
goroutine，而它跑在调度器里 —— 整个提醒系统会一起卡住。

**5. 越过 recurrence_end 不置 cancelled。**
留在 active 会变僵尸事件：DueEvents 每轮都捞到它（event_time 在过去），
但 fired_for 已等于 event_time 所以又不触发。

**6. 附件从未落盘。**
`data := make([]byte, header.Size); file.Read(data)` 两处错：单次 Read
不保证填满缓冲（大文件必然短读，sha256 算的是半截内容），而且文件内容
压根没写进 blob 存储。结果是附件「上传成功」、清单里看得见、
发提醒时取不到任何字节。改走 Blobs.Put。

**7. iCal TRIGGER 往返是断的。**
导出写 `-P15M`、导入找 `-PT%dM`，自己导出的文件自己都读不回来。更糟的是
`-P15M` 在任何合规客户端里都是「提前 **15 个月**」—— iCal duration 的 M
在 T 之前是月、之后才是分钟。而且用 maxInt(RemindBefore,15) 兜底，把用户
明确设的「到点提醒」(0) 悄悄改成提前 15 分钟。

---

其他修正：
- **PG schema 整块缺失日历两张表** —— DATABASE_URL 非空时所有 /calendar/*
  在 relation does not exist 上 500，而 SQLite 下一切正常，问题只在切外部库
  时才暴露
- DeleteCalendarAttachment 曾返回 501，让人「删整个事件来清附件」
- 导出忽略 from/to；导入只接受 multipart（命令行调用者收到含糊的
  「Missing file field」）
- 上传附件不校验事件存在 —— 会攒孤儿记录，而 ON DELETE CASCADE 清不掉
  它们（SQLite 的 foreign_keys 默认关）
- 农历规则 RRULE 表达不了，走 X-AGENTMAIL-RECURRENCE 扩展属性 + 公历近似
  兜底。**RRULE 分支不能覆盖已读到的农历值** —— X- 出现在 RRULE 之前时
  无条件赋值会把 lunar_monthly 打回 monthly，往返一圈农历规则悄悄退化
- 抽出 calendarCols 常量：原先四处手抄同一串列名，加一列漏改任何一处
  不会编译报错，只会运行时列错位（ListSessionsFor 上真的发生过）

测试：repo 20+ 例（到期判定/幂等/lookahead 不重发/过期不刷屏/农历推进/
多收件人/兜底链）、handler 20 例 iCal、scheduler 7 例模板渲染。
生产端到端验证并清理了数据。
 2026-09-04 06:28:03 +08:00
JianFeeeee
edb4bd94fd fix(permission): 权限决策者必须是人类，顺会话树查找 
死锁现场：pi 的权限邮件 to_name = "pi"（决策者被解析成 Agent 自己），
SendToUser 找不到收件人 —— 请求发出去后无人可答，会话无声挂死。

新增 repo.NearestHumanInThread 三级查找：会话 owner → 最近人类发件人 →
最近人类收件/抄送方。发件人优先于收件人：主动说话的人更可能在关注这条线索。

不用递归 CTE 沿 parent_mail_id 上溯而按会话扫：权限请求常常不挂父邮件，
上溯会在第一跳就断。

没有人类可路由时**自动拒绝并给 Agent 可执行的替代建议**，而不是转给管理员
—— 管理员对这条 Agent 链的上下文一无所知，收到也无法判断。
409 返回结构化的 error/detail/suggestion/decider_was。

nearesthuman_test.go 4 子测试。
 2026-09-03 21:08:39 +08:00
JianFeeeee
1767953331 fix(db): SQLite 时间绑定改用 sqlite 格式 + UTC 时区 
modernc.org/sqlite 在 writeTimeFormat 为空时回落到 t.String()，写出
`2026-09-03 16:45:38.5 +0800 HKT m=+0.009` —— 带单调时钟后缀，
datetime() 返回 NULL，与 NOW() 的字符串比较必然错。

后果是安全 bug：user_sessions.expires_at 无法被 datetime() 解析，
过期令牌照样通过校验 —— 会话永不过期。

修法是一行 DSN（`_time_format=sqlite&_timezone=UTC`）而不是改 40 处
db.Ts() 绑定点：DSN 是全局的、不可能漏，辅助函数要求每个新绑定点都记得调用。

排除 `_time_format=datetime`：它把亚秒截断，会重新引入「同秒插入多封邮件
排序不确定」——「会话里最早那封」（决定联系人身份）与「最后那封」
（决定最新进展）都会取错行。

新增 usersession_time_test.go 5 例。反向验证：摘掉 DSN 修复后 4 个失败，
报文即「过期令牌竟然解析成功 —— 会话永不过期」。
 2026-09-03 21:08:23 +08:00
JianFeeeee
f321380fa3 fix: relay 死循环防护 + DSH 工作区注册修复 + homeagent 工具集补齐 + 三插件 connect_to_server 
## relay 死循环防护（两道防线）

### 主防线：免配额只给发往人类的 relay（handler/mail.go）

原设计：relay 走免配额通道（harness 搬运不该算模型自主发信）。
问题：收件方是另一个同样会自动转发的 Agent 时，整个回路里没有任何
一处在计数——生产上跑出过 41 封（会话 f3d824ce），间隔从 15 分钟
缩到 5 秒，且用了 37 封才烧掉 4/20 预算。

改为：repo.IsHumanUser(to.Name) 判定。Agent→Agent 的 relay 照样扣预算。

顺带修次序问题：原来是「先占幂等键再扣预算」，预算耗尽时幂等键
已被占用，加了额度也无法重发。现在预算失败会 ReleaseRelay 还回去。

### 兜底：hop_limit 列接通（repo/relayhops.go）

schema 里早有 hop_limit INT DEFAULT 5，从未有代码读它。
CountTrailingRelayHops 从最新邮件往前扫，遇到第一封非 relay
邮件即停（中间有一封自主发信或人类插话就归零）。

5 测试：空会话 / 只数 relay / 自主发信打断归零 / 达到上限 / 按会话独立

## DSH 工作区注册修复

问题：上一轮加的 workspaceRegistry.create(cwd) 用了兜底值 cwd（来自
resolveWorkspaceCwd，可能是 ~/.dsh/mail-sessions/mail-<uuid>），
而不是会话 header 里的真实 cwd。两者不一致时 attachSession 拒绝，
且 create 已先执行，每封邮件都往注册表里塞一条空的垃圾 workspace。

修复：读 handle.agent.session.header.cwd —— create 路径下是 meta.cwd，
resume 路径下是持久化 header 里那个。

## homeagent 插件：11 工具齐平 opencode

tools.go 新增：read_mail / forward_mail / suggest_address /
list_contacts / session_participants / read_thread / connect_to_server
+ handleConnectToServer（注册到 Gateway 前先用候选坐标试注册，
成功才写回 p.gwURL/p.key，失败不破坏原配置）

关键修：Plugin.name（插件名，homed 注册用）与 Plugin.agentName
（AgentMail 身份，Gateway 密钥绑定用）是两个命名空间。
它们混淆会导致 403：「该密钥已绑定到 Agent 'homeagent'，不能用于
注册 'homeagent-mail-bridge'」。现已分开，并在 systemd drop-in
里显式设 AGENTMAIL_AGENT_NAME=homeagent。

## 三插件补齐 connect_to_server

之前只有 opencode 有。后果：Gateway 换地址或密钥需要重新登记时，
opencode 里的模型能自己修好，其他平台只能干等环境变量被人改。

DSH 版：从 GatewayClient 内部调 register()，成功后写回 client.baseURL
与 client.agentKey 当场生效。

pi 版：新导出 KEY_FILE / saveLocalKey（从 gateway.mjs），connect
工具直接用。

# 测试

relayhops_test.go 5 例
opencode 172 / dsh 188 / pi 214 全绿
check-shared-libs.sh 三方同源（rename-proposal 已纳入校验）
 2026-09-03 15:01:52 +08:00
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
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
ca64d12057 feat: 工作区归属修复 + 平台会话同步 + 对话树整树展开 + DSH 插件 
四个各自独立的生产缺陷，共同的根源都是「本该属于会话的属性没有存在会话上」。

## 1. dsh 指定工作目录完全失效（所有会话落进「未分组」）

插件建会话时用的 cwd 是自己拼的 `~/.dsh/mail-sessions/mail-<uuid>` ——
每封邮件一个全新的空目录。DSH 与 opencode 都按 cwd 给会话分组，于是所有
邮件会话既不属于任何项目、彼此也不同组。

而 Gateway 从来没把地址里的 path 位发给插件：`notifyRecipients` 的 payload
只有 mail_id/session_id/from_name/subject，`to_workspace` 虽然入库了却不在
SSE 事件里，插件即使想用也拿不到。

- SSE `new_mail` 事件加 `to_workspace`。**每个收件方拿到自己那个地址的 path**，
  不是主收件人的 —— 抄送给 opencode@/a 与主发给 dsh@/b 是两个工作区
- 两个插件的 cwd 都改为取寻址的 path 位；不存在的目录**不创建**而是回退到
  兜底目录（一个笔误不该在磁盘上落下真目录，Agent 会在里面一无所获地干活）
- 拒绝相对路径：cwd 的相对基准是 harness 进程的启动目录，systemd 下通常是 `/`

## 2. 会话别名列不出工作区下的历史会话（无法选择）

workspace 只存在于 `mails.to_workspace` 上，「这个工作区下有哪些会话」必须
JOIN mails 再从收发双方的 workspace 里猜。而 Agent 回信时 from_workspace
填的是 **Agent 名**而不是路径，旧条件 `to_workspace = $p OR from_workspace = $p`
在只剩 Agent 回信可匹配时两边都对不上。

- `sessions.workspace` 新列，`CreateSession` 从地址的 path 位带入
- `SuggestSessionCandidates` 取代 `SuggestSessionsFor`：以会话自己的 workspace
  为权威，历史会话（该列为空）回退到 mails 反推 —— 升级后老会话不该消失
- `FindOrCreateDefaultSession` 同步改用会话的 workspace

## 3. 平台侧会话在补全里根本不存在

人直接在 opencode/DSH 界面上开的会话，Gateway 一无所知。

新增 `agent_platform_sessions` 镜像表，插件在心跳里上报快照。
**上报而非 Gateway 反向拉取**：当前架构是单向的（Agent 持密钥主动连 Gateway，
Gateway 从不外呼），反向拉取需要它保存各平台的地址与凭证，那是另一套信任模型。

- 与 sessions 表分开存：镜像里是别人家的会话，id 属于平台的 id 空间，没有
  本侧的 owner/预算/邮件。混进 sessions 会让每一处「按会话鉴权」都要先判断
  这条到底是不是真的本侧会话
- **整表替换而非增量合并**：平台侧删掉的会话必须从候选里消失 —— session 位是
  三态语义，指向不存在的会话直接 404
- **nil 与空数组语义不同**：插件拉不到列表时省略该字段（保留镜像），
  而不是传空数组把镜像抹掉
- **subagent 子会话不上报**：实测 DSH 的 list 里混着 49 条子会话，标题就是
  派活的提示词前缀（九条都叫 "You are auditing ONE file"），slug 全撞名；
  它们是父 agent 内部的工作单元，人往里发邮件毫无意义
- **slug 撞名只留最近那条**：服务端只能取其中一条，上报同名项只会让补全里
  出现几个点哪个都不确定的候选
- DSH 插件此前**完全没有心跳** —— Gateway 靠 last_seen 判在线，一直靠注册撑着

补全候选带标题与来源：`suggestions` 保留纯字符串数组（不打破已部署的前端与
第三方客户端），新增同序的 `candidates`。过滤时标题也参与匹配 —— 人记得的是
「缓存选型」而不是 brisk-harbor 这种随机短名。

## 4. 对话树看不见抄送与转发产生的分支

旧实现从锚点分「祖先链 + 子树」两路展开，而**兄弟节点既不是锚点的祖先也不是
它的子孙**：一封抄送给两个 Agent 的邮件收到两个回复，从其中一个看树永远看不到
另一个；挂在原件上的转发分支同理。

改为先 `ThreadRootOf` 上溯到线索根，再从根整树 BFS。只剩一个加载方向，
因此不再需要滚动位置补偿。前端补上抄送人列表与转发标记 —— 树上两个兄弟节点
为什么并列，唯一的解释就是父邮件抄送给了两个人。

## 5. DSH 插件（Phase 7.7）

卡了一下午的 `Cannot read properties of undefined (reading 'kind')` 根因是
`followup()` 的参数形状：DSH 要完整的 UserMessage（content + source），
而我照抄了 opencode 的 parts 数组。错误抛在 agent-loop 内部，不指向调用点。

- `agent/status` → idle 时自动转发最后一条 assistant 消息（对应 opencode 的
  session.idle），复用 relay-dedup 让位于模型的主动回信，走免配额通道
- `approval/request` 权限询问转邮件问人。与 opencode 的差异：那边的
  permission.ask 是同步钩子只能立即返回 ask，DSH 这边是异步 waterfall，
  可以真的等人 —— 拆插件时未决询问一律 fail closed，否则 await 永不返回
- 会话别名由模型标题派生（保留中文，去掉 `.` `@` `/` 等寻址分隔符 ——
  留在别名里会让它自己被解析器切开）
- 逻辑放 lib/ 下的纯函数并加测试：三类约定都是「错了不当场报错、只在深处
  炸一个无关错误」

## 其他

- `deploy/reset-demo.sh`：清空演示邮件数据，保留账号与密钥。备份用 `.backup`
  而非 cp（WAL 下 cp 拿到的是缺尾巴的库）；手工按依赖顺序删（SQLite 的
  foreign_keys 默认关，声明了 REFERENCES 也不级联）；只在目标是默认库时才碰
  systemd（演练时误停过一次生产服务）
- 插件 dist/ 不进版本库，install.sh 负责构建
- `permission_decision` 事件补 session_id：插件重启丢了待决映射时要靠它定位会话
 2026-09-02 20:05:51 +08:00
JianFeeeee
9d4718a412 feat: SSE Last-Event-ID 补投 + 连接状态指示 + 限速器 DB 化 
## SSE Last-Event-ID 补投

EventSource 断线重连时自带 Last-Event-ID 头，但服务端直接忽略了——
所有断线期间的邮件通知都丢失。用户刷新页面也会错过已推的事件。

改为 per-user 事件环形缓冲区（500 条，~100KB/用户，20 在线 ≈ 2MB）：
每次 Broadcast/SendToUser/SendToAgent 同时写入对应用户的缓冲区；
AddClient 时取 Last-Event-ID 头，找到该 ID 的位置后从下一条回放。
找不到 ID 说明事件已被覆盖（缓冲区溢出），从头回放全部。

事件 ID 用全局递增序列号（非 UUID），EventSource 的 Last-Event-ID
就是靠这个 ID 记住断点的。

新增测试：缓冲区回放、溢出行为、并发安全（10 goroutine × 200 次 push）、
端到端重连验证（SendToUser → 带 Last-Event-ID 的 AddClient → 补投）。

## 连接状态指示器

Sidebar 用户头像右下角的小圆点：绿=已连接，黄=连接中，橙=重连中，红=断开。
NarrowNav 底栏也有（移动端）。

SSE 模块新增 onSSEStatus/getSSEStatus 接口，onerror/onopen 驱动状态变化。
状态点用 absolute 定位在头像边缘，不遮挡文字。

## 限速器 DB 化（解决多实例部署时的计数漂移）

原实现：LoginLimiter 与 sessionRateLimiter 都是进程内内存计数器。
多实例部署时各自独立计数，等效上限变成 N 倍。

改为 rate_limits 表（bucket + ts），两个限速器共享同一套基础设施：
- LoginLimiter：bucket="login:<username>"，COUNT(*) >= 5 → 锁定 5 分钟
- sessionRateLimiter：bucket="session:<agent_name>"，COUNT(*) >= 20/h → 拒绝

判断与写入在同一个 BEGIN IMMEDIATE 事务里——SQLite 的 IMMEDIATE
在事务开始时获取 RESERVED 锁，防并发写事务同时进入 COMMIT 阶段。
实测 80 并发下恰好放行 20 次（旧内存版同样通过，但 DB 版才能多实例共享）。

DB 不可用时放行（宁可放开限速也不能让用户完全无法使用）。
新建 rate_limits 表迁移（SQLite + PG 两版）。
 2026-09-02 14:33:41 +08:00
JianFeeeee
07e6b789b2 feat: 配额下沉到会话 + 窄屏覆盖式布局 + 工作列表卡片视图 
## 配额重构：废除 Agent 终身额度

原实现在 agents 上放一个 max_rounds/used_rounds 计数器，used_rounds 单调递增、
永不重置 —— 跑满就要管理员手工重置才能再干活。那是把一次性资源模型套在长期
在线的服务上，且并行任务互相抢额度。

改为：
- 唯一被强制的预算是【会话】的往返预算（sessions.max_rounds/used_rounds），
  写信时给、对话页里随时改 —— 配额的语义是「这件事值得多少个来回」，
  那是任务的属性而不是 Agent 的属性
- agents.default_rounds 只作为「派给这个 Agent 的新任务」的默认值（默认 20）
- agents.used_rounds 降级为纯统计
- 新建会话速率限制（1h/20 条）堵住用 .new 开一串新会话绕过预算；
  人类不受限（agentLimiterKey 返回空串即不计量）

## 窄屏适配（用户反馈「窄屏基本不可用」）

原先只有三栏并排：60(导航)+320(列表)+详情，375px 屏上详情被挤到 0。

第一版做成「一次只显示一栏」，用户纠正应当是新页面覆盖老页面并带动画，
于是重做为覆盖式：
- NarrowStack：底层列表始终挂载，详情绝对定位盖在上面。两个好处 ——
  列表滚动位置与选中态天然保留；退出动画有东西可播（直接卸载再渲染另一个
  组件的话，没有任何一帧能让旧页面往右滑出去）
- 因此必须区分「逻辑上是否打开」与「是否还在 DOM 里」：关闭时先播 200ms
  滑出，动画结束才卸载
- 入场用双层 requestAnimationFrame：必须让浏览器至少绘制一帧「在右侧之外」
  的状态，否则挂载与 translate-x-0 在同一帧内完成，transition 不触发
- 窄屏专属控件用 useIsNarrow() 条件渲染而非 md:hidden —— 后者只是视觉隐藏，
  宽屏用户按 Tab 会聚焦到看不见的返回按钮
- 底部导航 + 抽屉侧栏 + env(safe-area-inset-bottom)

## 工作列表卡片视图（Phase 7.1 最后一项）

中间栏可切列表/卡片。列表答「跟谁在聊」，卡片答「在聊什么、进展如何」：
主题 + 最新一封的发件人与摘要 + 往返预算徽标。

- 两种视图共用同一份数据与同一套动作；归档确认框也共用 —— 归档是破坏性操作，
  换个视图就换套确认 UI 只会让人对「自己点了什么」更没底
- 预算徽标在「不限」时不显示（对每张卡片都成立的「0/0」是纯噪声）
- 数据一次取回，不让卡片为每条会话再打一次库

## 修掉的缺陷

- GET /me/sessions 一直 500：ListSessionsFor 的 SELECT 加了预算两列却没加进
  Scan，列数不匹配。联系人栏一条数据都拉不到，而错误只是「Failed to list sessions」
- GET /sessions/{id} 忘了填充附件：前端会话视图走的是这个端点，于是 Agent
  回信里的附件在 UI 上完全不存在（另一个端点填了但没人调用）
- 插件曾完全没在加载：为了可测在 index.js 里 export 了辅助函数与一个 Map，
  而 opencode 把入口模块的每一个导出都当成插件工厂逐个检查，多导出一个 Map
  就 "Plugin export is not a function"，插件静默失效、邮件全投不进去。
  逻辑挪到 lib/relay-dedup.js，并加断言钉住「入口只有 default 导出」
- 同一件事发两封邮件：模型带附件主动回信后，session.idle 又把它最后那段话
  自动转了一遍（生产实测 311 与 342 字节各一封）。explicitSends 记录本轮
  主动发信，自动转发据此让位；relay_key 幂等管不了这个 —— 那个键保证的是
  「同一条消息不转两次」
- SQLite 时间戳只有秒精度：同秒插入的多封邮件排序不确定（实测同秒插 5 封，
  顺序由随机 UUID 决定）。「会话里最早那封」（决定联系人身份）与「最后那封」
  （决定最新进展）都会取错。NOW() 升到微秒 + mails 的 INSERT 显式传它
  （改 schema 默认值只对新库生效，SQLite 没有 ALTER COLUMN）+ 所有
  ORDER BY created_at 补 mail_id 兜底
- fillAttachments 从逐封查询改成一次 IN(...)：原来是 N+1，200 封的会话打开
  要打 200 次库
- repo 层 5 处 rows.Next() 循环补 rows.Err()：没有它，读到一半连接断掉会
  静默返回部分结果，UI 上表现为「邮件凭空少了几封」
- go:embed 占位页改名 placeholder.html：叫 index.html 会被 Vite 产物覆盖并
  提交进去，而它引用的 assets/ 是被忽略的 —— 新克隆打开是白屏

## 回复/转发栏

- 两处都加抄送（可折叠）；原邮件带抄送时多一个「回复全部」，回填用
  cc_list[].raw 而非重拼 name@path（后者会丢掉会话段）
- 会话视图每张卡片加转发入口：转发之前只存在于单封邮件视图，而人多数时间
  待在会话视图里，等于功能在 UI 上找不到
- ReplyBar 的错误从 console.error 改为显示出来：预算耗尽、地址不存在、
  速率限制都走这条路，之前点发送毫无反应

## 测试

- repo: 列顺序（三个 SQL 分支）、卡片字段、previewRunes 边界、时间戳亚秒精度、
  批量附件查询、速率限制（80 goroutine 断言恰好 20 条通过）
- web: 窄屏布局 16 条结构性断言（覆盖而非分栏、延迟卸载、双层 rAF、
  条件渲染而非 md:hidden）
- 插件: 自动转发去重 17 条（含「入口只有 default 导出」不变量）
- install.sh 把插件测试也纳入部署前门禁
 2026-09-02 14:16:46 +08:00
JianFeeeee
0e754617a4 feat: AgentMail —— 以邮件为统一范式的多智能体协作平台 
Go 单二进制网关 + React 前端 + opencode 桥接插件。部署产物是
「一个二进制加一个 .db 文件」：前端经 go:embed 打进二进制，
数据库默认内置 SQLite，systemd 托管。

核心设计
- 三维寻址 name@path.session，按最后一个 . 切分；session 位三态：
  省略=默认会话 / new=强制新建 / 具体别名=必须已存在（否则 404 无法送达）
- 会话别名默认复用 Agent 平台自己的命名机制（opencode 的 slug 与模型生成的
  标题），不在本侧另造一套；人显式定过的别名不被平台同步覆盖
- 对话树不建 tree_nodes 表：parent_mail_id 已完整编码树结构，
  再维护一张表就是第二份真相。用递归 CTE 查，按方向分块加载
- 附件内容存磁盘、按 sha256 内容寻址，数据库只存元数据；天然去重，
  且路径与用户 filename 无关，杜绝 ../ 穿越
- 配额约束的是模型的自主发信，不是 harness 的转发：插件代劳的权限询问与
  最终总结走免配额通道，靠上游消息 id 做幂等键而非计数
- 往返预算下沉到会话（写信时给、对话页里改）+ Agent 全局配额，两层都要过

后端 gateway/
- models/repo/handler/middleware/sse/blob 分层；两方言（SQLite/PostgreSQL）
  共用一份 repo 层 SQL，差异集中在 internal/db
- 多用户认证（bcrypt cost12、登录限速、会话隔离、权限边界）
- 密钥体系：Agent 密钥与用户密钥分表，三种生命周期；登记式密钥让全文
  只从客户端流向服务器一次
- 所有「判断 + 自增」都在同一条 UPDATE 里（配额、预算、one_time 密钥、
  附件挂载），并发下不会刷穿

前端 web/
- 三栏布局、三段式地址补全、权限卡片、密钥面板、配额面板、对话树、附件
- 全站纯 SVG 图标，不使用 emoji
- api/ 即可复用的客户端 SDK：基地址与凭证集中在 api/config.ts

插件 plugins/opencode-mail-bridge/
- 六个工具 + 两类自动转发（permission.ask 钩子接管平台原生权限询问、
  session.idle 时转发本轮总结）
 2026-09-02 10:29:26 +08:00