|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
00ba69d899
|
docs: 说明新克隆可直接编译（static/ 留了占位页）
|
2026-09-02 10:33:03 +08:00 |
|
|
|
c73dd10f9c
|
build: 保留 go:embed 占位页，新克隆无需 node 即可编译
go:embed 要求目标目录存在才能编译，而构建产物不进版本库 ——
上一版把整个 gateway/internal/static/static/ 忽略掉，导致新克隆连
go build ./cmd/server 都跑不起来（pattern static: no matching files found），
只改后端的人被迫先装 node。
改为忽略目录内容但保留一个占位 index.html：说明前端未构建、给出构建命令，
并明确后端 API 仍然可用。真实产物由 install.sh 覆盖后嵌入。
|
2026-09-02 10:32:41 +08:00 |
|
|
|
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 |
|
