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

13 Commits

Author SHA1 Message Date
JianFeeeee
e94313f66a 跨端: 接手 pi 的两个 WebUI 开项——默认值统一到服务端契约 12/4；缓存键按账号（含一次性迁移） 
pi 问"这两个开项谁执行"，我接了（他那边无 shell，我这边改过 WebUI）。两件都是他读源码读出来的实缺陷。

## 1 默认值：不是审美，是**服务端契约**（pi 更正了自己上一封）

`server/internal/models/models.go` 的 `DefaultAppearance()` 明写 `BgDim: 12, BgBlur: 4`，
且注释宣称"与客户端 backgroundStore / themeStore 的默认值一致"——而 WebUI 的
`backgroundStore.ts` 是 `dim: 24, blur: 8`，**那句注释是假的**；`lib/appearance.ts`
的 `clamp(..., 12, 4)` 又是另一套。**同一份代码里两个"默认值"**，走哪条路就落哪个数。

后果不是"两处代码不一样"这么轻：服务端"没有记录"时客户端以本地为准推上去，
于是**新账号的初始外观由第一个同步它的客户端决定**（先 WebUI 登录存 24/8，
先鸿蒙登录存 12/4）——同一个账号，压暗强度取决于谁先到。

改法：新增 `src/lib/appearanceDefaults.ts` 作为**唯一来源**（DEFAULT_DIM/DEFAULT_BLUR/
上限），`backgroundStore` 与 `lib/appearance` 都引用它，字面量全部消失。

## 2 缓存键按账号（含旧全局键的一次性迁移）

`STORAGE_KEY = 'agentmail.background'` → `storageKey(accountId)` = 前缀 + 账号；
写盘只走 `storageKey()`；旧全局键**只作为迁移源**：当前账号首次读到它时接管并存进自己的键，
然后**立刻删除**（否则下一个账号继续从它"继承"，等于把刚修的缺陷留在原地）；
未登录时不迁移（旧值不能送给一个还不知道是谁的账号）。

配套顺序：`appearanceSync` 在账号切换时**先 `reloadForAccount()` 再 `pull()`** ——
服务端"没有记录"时 `pull()` 会"以本地为准推上去"，那时"本地"必须已经是本账号的值。

## 3 判据（新增第 13 个判据文件 appearance-defaults）

`test/appearance-defaults.test.mjs`：**去 Go 源码里读** `DefaultAppearance()` 的四个字段，
再比对三处（WebUI 常量、store 的 DEFAULT_BACKGROUND 不许有字面量、鸿蒙 Appearance 的字段默认值）；
另两条钉"键按账号、不许退回全局键、旧键必须被删除"与"重读在 pull 之前"。
这样服务端那句注释是**可核对**的，不是承诺。

顺带更正：`Wallpaper.ts` 里"WebUI 默认 24"的注释已过时 → 改 12 并写明缘由；
`harmony-appearance` 里"WebUI 是全局键"的前提失效 → 改为断言两端都按账号分键。

## 验证

`npm test` 退出码 0（13 个判据文件全绿 + vitest 263 passed，原 258 + 新增 5 条行为测试：
键隔离、迁移一次并删除、未登录不迁移、默认值=12/4）。
 2026-09-14 15:17:01 +08:00
JianFeeeee
4d6e944220 feat(webui): 打开即已读 + 回复即已读 
用户：「现在邮件需要完全手动标记是否已读而不支持点进去自动已读或者回复自动已读」。

## 改法

- **打开即已读**：MailView 里加一个 effect —— 当前邮件是 unread 且**真正可见**时
  调 `markRead`。两个刻意的细节：
  1. 窄屏下 MailView 可能已经渲染但被列表覆盖层盖住（NarrowStack）⇒ 必须等到
     `narrowPane === 'detail'` 才标，否则"滑过去但没看"的邮件也会被标已读；
  2. 只对 `unread` 发请求（已读的再标一次是白跑，还会让接口日志一直响）。
- **回复即已读**：ReplyBar 发送**成功之后**才标（发送失败不该把"我处理过了"记下来）。
- 手动标记按钮保留（显式动作仍然有用）。

## 端到端验证（真浏览器 + 真库）

造一封未读 → 浏览器里展开会话分组、点开那封邮件 →

    POST /read → 200
    mail_reads 里出现 (reader=gui-lab)
    冗余列 mails.status: unread → read

即"打开即已读"确实生效，而且是记在**读者维度**上（不会像旧的邮件级已读那样
被别人一标就没了）。

## 一个过程记录

前两次验证都"没有发出 /read 请求"，我一度以为代码没生效。其实是**点错了对象**：
会话分组默认折叠，`button:has-text(主题)` 匹配到的是**分组那颗**，点它只展开、
不选中邮件（所以不触发已读 —— 这恰恰是正确行为）。展开后再点具体邮件行才触发。
判据必须点"用户真正会点的那一层"，这句话这次又应验了。

套件：vitest 15 文件 / 258 用例全绿。
 2026-09-14 13:12:36 +08:00
JianFeeeee
5ce25f6fdb fix(webui): 修侧栏点击无法翻页 + 回信 UI 统一成一个组件 
用户两句：「侧边导航栏完全不可用，点击无法翻页，而且窄屏显示不全」、
「按顺序做吧」（= 做回信 UI 统一）。

## ① 侧栏点击无法翻页（严重，我的错）

导航合并时我把点击目标写成：

    onClick={() => setViewMode(target || commTab || modes[0])}

只有「通信」有意回上次的子页签，而**日历/联系人没有 target** ⇒ 点它们会跳到
`commTab`（收件箱）⇒ 表现为"点了没反应/不翻页"。

修成 `setViewMode(target ?? (isComm ? commTab : modes[0]))`。

**为什么没被拦住**：我的验证全在看**结构与样式**（导航项数、徽标、圆角、玻璃、
对比度），**一次都没点过**。所以补了 `test/components/Sidebar.test.tsx`：点每一项，
断言落到它自己那一项，并带一条反向对照。真浏览器点击也复验：日历→日历页、
联系→联系人、通信→回通信页。

## ② 回信 UI 统一（用户点名的欠账）

新增 `src/components/Composer.tsx`：**形状**（输入区 / 动作行 / 提示）只有一处定义，
**差异**用 `header`（选项胶囊）、`footerExtra`、`submit.tone`、`density`
（compact=批注、roomy=回信正文）条件渲染 —— 差异是数据，不是又一套 UI。

三处各写一套的地方现在都走它：提问型授权表单、审批型（同意/拒绝）、ReplyBar 回信。
输入框的边框/圆角/聚焦环/禁用态从"抄了三遍"变成一处。

**重构时我引入过一个危险的错**：给审批型加了个"提交备注"按钮，兜底用 `options[0]`
（= 同意）⇒ 点一下就**默认批准**。被既有判据当场抓住（`PermissionPanel` 两条红），
已改成"点选项即提交"（`submit` 现在是可选的），并用 `variant="action"`
把同意/拒绝的颜色语义恢复成原来的实心绿 / 浅红。

## ③ 我自己的流程问题（写下来）

- 结构类改动必须配一条"**点它**"的判据 —— 这次就是缺了它。
- 单测里改 store 后必须 `rerender` 再点：否则闭包里是旧值（我第一版因此误判代码有问题）。
- 窄屏"显示不全"**没能复现**：390×844 与 320×568 都量了 —— 无横向溢出、
  内容面板完整落在悬浮导航之上、最后一行完整可见。需要用户指出具体页面。

判据：vitest **15 文件 / 258 用例全绿**（含新增 Sidebar 点击 4 条）。
 2026-09-14 12:26:06 +08:00
JianFeeeee
77699e216b fix(webui): 新到的授权请求藏在折叠分组里 —— 徽标动了，内容看不见 
用户报告："我点到授权界面，才更新显示授权请求"。

先排除了推送本身：实测徽标是**实时**更新的（gui-lab 授权 7→8、jianf 1→2，
都没导航）。问题在内容：`PermissionList` 的展开状态
`const openSet = expanded ?? new Set(autoOpen)` —— 一旦手动点过一次，
`expanded` 就冻结成"点的那一刻"的快照，此后新到的待决请求落在一个折叠的分组里：
徽标数字变了，正文却看不见，直到离开再回到授权页（组件重挂载、`expanded`
回到 null、默认展开重算）才出现。

这违反代码自己的设计意图（注释写着「有待决策请求的会话默认展开：那些是在等人
动手的，藏起来等于没解决问题」）。

修法：加一条**状态迁移**判据 —— 新出现的待决邮件（`sessionId:mailId`）让它所在
的会话自动展开。用 mail_id 而不是"会话有没有待决"作判据，是因为实测撞到的正是
"会话早就有待决、用户把它折叠了，之后又来了一条"；而用户在那之后再手动折叠同一
条不会被弹开（没有新 mail_id）。

验证：
  · 真浏览器复现：授权 2 → 3 而新请求正文不可见，重进页面才可见（复现成功）
  · 新增 `test/components/PermissionList-autopen.test.tsx`（3 条，含反向对照）
  · 扰动验证：撤掉修复 → 2 条目标判据红、对照判据仍绿；恢复 → 3/3
  · 部署后同一探针复验：折叠状态下新请求**立刻可见**，不再需要重进页面
  · 前端 239 测试全绿；桌面重打包与 WebUI 同源（index-jaRgHqX2.js）

顺带修掉一个**更严重的缺陷**（在做「用 zcode 写个网页」时被 agent 自己报出来的）：

  fix(plugins): zcode 的 read_mail 永远返回空正文

agent 回信原话：「read_mail 返回的正文是空的，收件箱预览在「点击计数…」处被截断」
—— 它因此只看到前两条要求，写出来的页面漏了第 3 条（生成时间）。

根因在 `lib/inbox-format.js` 的渲染端：

    const body = m?.body_preview || m?.body || '';
    lines.push(`内容: ${String(body).slice(0, bodyLimit)}`);

zcode 的 read_mail 用 `bodyLimit = 0` 表示"要全文"（HTTP 侧 `?body_limit=0`
也确实是这个语义，服务端返回了完整正文），但这里 `slice(0, 0)` 把正文渲染成
**空字符串** ⇒ 模型永远读不到全文，只能看收件箱里那段预览。

修法：`bodyLimit <= 0` 视为不截断；不截断时优先取 `body`（单封接口可能同时带
`body_preview`，那是短的那个）。四份副本逐字节同源（`check-shared-libs.sh`
通过），每个桥各加 2 条判据：0 = 不截断、不截断时优先全文。
扰动验证：退回旧写法 → 2 条红。

端到端验证：让 zcode 读全文并原样回报最后一行（一个随机标记）。
修复后它精确回出 `最后一行标记：ZTOKEN-2c7561fd` ✓ —— 修复前这不可能。

四家桥都已重新部署到新快照（pi/opencode/dsh/zcode），部署漂移检查：
「四个宿主都在跑当前代码」。测试基线：pi 417 / opencode 323 / dsh 372 / zcode 382。
 2026-09-13 10:39:26 +08:00
JianFeeeee
5804ba4f63 fix(webui): 自定义背景完全不可用 —— 「图片」档进不去 
现象：点「图片」后背景反而被关掉，上传控件永远不出现 ⇒ 自定义图片在 UI 上
完全不可达（用户看到的正是"自定义背景不正常"）。

根因：`normalizeBackground` 把「kind=image 但还没有图片数据」折叠成 `none`
（这条判据本身是对的 —— 读盘时那确实是脏数据），但 store 的 `commit()` 每次
patch 都要过一遍它，于是 `setKind('image')` 这一瞬间就被折叠回去；而上传控件
只在 `kind === 'image'` 下渲染 ⇒ 鸡生蛋问题，用户永远走不到选文件那一步。

修法：给归一化加 `keepEmptyImage`。
  - 读盘（`readStored`）保持严格：空图片状态是脏数据，退回 none。
  - 交互（`commit`）保留瞬态：允许"已选图片档、还没挑文件"这个中间状态存在。
静止态的不变量没有放松，放松的只是正在选图的那一瞬间；`applyBackground` 对
空图片本来就不铺开（不会出现 `url("")`）。

判据（都验过"修复前会红"）：
  · 新增 `test/components/BackgroundPicker.test.tsx` —— 点「图片」后选文件控件
    必须出现、选完图背景必须亮、失败必须说原因、选「无」必须能关掉。
    **扰动验证**：把修复撤掉 → 组件 3 红 + store 1 红；恢复 → 22 全绿。
  · `test/stores/background.test.ts` 补 2 条：交互进入图片档要留住 /
    瞬态落盘后重读必须退回 none。

线上验证（真浏览器，部署后）：线上 bundle 换成 index-CSFGa8wa.js 后 ——
点「图片」→ `kind=image` 保持 → 上传 16KB 小图与 9MB 大图都成功
（大图压缩到 1790KB）→ 刷新后仍在 → 全程无页面错误。

顺带：应用内**从未出现**过品牌图标。`BrandMarkIcon` 只用在登录页与首启页
（都是登录前界面），登录后的日常界面里一处都没有。侧栏顶端加上品牌标记
（点它回收件箱）。favicon 那条链本来就是好的（3 个 link 都 200、类型正确、
图标内容正确），已在验证中确认。
 2026-09-13 08:55:55 +08:00
JianFeeeee
addde97600 feat(electron): 多账号第一纵切 —— 账号存储/选择器/聚合收件箱 
按 docs/MULTI-ACCOUNT-PLAN.md 实现客户端多账号的前半段（SSE 多连接与
写信账号切换留作下一轮）。

- `src/lib/accounts.ts`：纯逻辑（地址规范化、身份判重、默认账号、聚合合并），
  16 条测试钉住每条判据（含反向对照）。
- 持久化在主进程：`userData/accounts.json`，**原子写**（临时文件 + rename）+
  0600。不落 localStorage：那份存储渲染层任何脚本都可读，且 file:// 与
  http:// 是两套。无 IPC 时（浏览器）退到 localStorage 并在界面**如实写明**。
- 取信：单账号走原路径（逐字节不变）；聚合时**每账号各一次请求、各带自己的
  令牌**（`fetchWithAuth`，不碰认证单例，避免并发串号）。
- ★ 只合并**同一网关**的账号：跨网关的邮件混进列表后点开会去问当前账号的
  服务器（404，或 mail_id 撞上就打开了别人的信）。如实排除 + 列表上方说明。
- ★ 部分失败可见：某账号取不到时给出账号名与原因 —— 静默丢掉它会让聚合列表
  少一整份邮件而界面看起来完全正常。
- `API_BASE` 改为 `let`（切换账号要换网关），api 层不得缓存它
  （`client.ts` 的 `const BASE` 快照已改成每次读）。
- UI：列表头下拉（≥2 个可用账号才出现「全部邮箱」）+ 账号徽标 + 账号页
  「多账号」一段（添加前调 /auth/me 验证，401 当场拒绝，不写进列表）。
- 测试：vitest 230 通过（原 222 + 新 8）、`test/lib/accounts.test.mjs` 16 通过、
  typecheck 通过。新增 `test/manual/multi-account-verify.mjs`（真起打包产物 +
  两个真实账号，判据落在网络层：聚合必须每账号各一次请求且各带自己的令牌）。
 2026-09-13 06:16:59 +08:00
JianFeeeee
8b2206ed53 fix(electron): Phase 3 验收抓到的两个静默缺陷 —— 白屏与登录 
Phase 3（写信 + 附件 + 权限面板）的验收脚本第一次跑就把这两件事翻出来了，
两个都**表现正常**：进程活着、窗口标题对、接口能通，只有结果不对。

## 1. 打包后的应用是白屏（vite 的 base 缺省值）

`vite.config.ts` 没设 `base`，Vite 按默认的 `/` 生成 `src="/assets/index-xxx.js"`。
同一份 dist 有两个宿主：网关在 `/` 下伺服它（Web 正常），Electron 用 `loadFile()`
从 **file:///…/dist/index.html** 加载它 —— 绝对路径在那儿解析成
`file:///assets/index-xxx.js`（不存在），**JS 根本没加载**。

现场：`#root` 里一个子节点都没有。没有报错对话框，控制台里只有一条不起眼的
资源加载失败。而当时所有既有检查都是绿的：`npm run build` 成功、deb 元数据检查、
asar 内容清点（**它们只看文件在不在，不看文件引用什么**）。

修法：`base: './'` —— 两边都对（Web 在 /index.html 里 `./assets/x.js` → `/assets/x.js`；
Electron 在 dist/index.html 里 → `dist/assets/x.js`）。

## 2. 桌面壳用账号密码登录是断的，而且静默失败

账号密码登录靠 `SameSite=Lax` 的会话 Cookie，而桌面壳的页面是 `file://`
（**不透明源**）—— Chromium 按第三方上下文处理它，Cookie **不予存储**。

实测现场：`POST /auth/login` 返 **200**、响应体能读出用户名，但 `document.cookie`
是空的，紧接着的 `/auth/me` 返 **401**；界面停在登录页，看起来像「密码错了」，
而同样的账号密码用 curl 登录是成功的。所以这不是凭据问题。

修法：桌面壳里**不再给账号密码表**（一个必然失败的按钮比没有更糟），改成粘贴
**用户密钥**（`Authorization: Bearer`，桌面端本来就该这么用）：
- preload 显式声明 `__AGENTMAIL_SHELL__ = 'desktop'`（宿主契约，而不是让渲染层
  sniff 协议；顺带让 jsdom 里可测 —— 那里的 `location.protocol` 不可重写）
- 新增 `authStore.loginWithKey`：成功后才留下令牌，失败**还原**（否则之后每个请求
  都会带上这个坏 key 并 401，而人看到的是「重输一次也不行」）
- 顺手修了 label 与 input 没有关联（`htmlFor`/`id`）—— 无障碍缺陷，也让测试能按标签查

## 验收

- 结构性守卫进 `npm test`（`test/packaging.test.mjs`，不需要浏览器）：base 必须是
  相对路径、产物里不能有绝对资源引用、**安装包里的 dist 与当前构建一致**
  （前端改了没重打包时，装上去的人看到的是旧界面，两边不一致却谁都不报错）。
  判据自检过：把 base 改回 `/` 或把产物改回绝对路径，各自都能让对应那条变红。
- 组件测试 6 条（两种壳的形态、密钥成功/失败、空密钥不可提交）。
- `test/manual/desktop-phase3-verify.mjs`：真起打包好的应用（xvfb + CDP），
  一条贯穿的链 —— 用桌面 UI 写信带附件 → 外部核验信与附件真到了网关 →
  这封信触发 zcode 的真实授权请求 → 在桌面**授权面板**里点同意 →
  外部核验 **Agent 真的执行了**（标记文件出现）。第二次跑 14/14 全绿。
- 客户端全量 222/222；网关换新产物后 Web 依旧正常（相对路径在 `/` 下同样成立，
  实测渲染出收件箱、无控制台错误），并真发一封邮件确认回信到达。

## 判据自己的错（记一笔）

第一次跑时「附件真的挂在信上」报红，而库里那 41 字节的附件**明明挂在信上** ——
我把端点写成了 `/me/mail/{id}`（不存在，404），正确是 `/mail/{id}`。
判据用错端点时以「附件是空的」现形，看起来像功能 bug。

另：`pkill -f 'agentmail-web'` 会把**自己这条命令**也杀掉（命令行里含同样的字符串），
表现是「脚本没有任何输出、退出码 143」。改用端口定位（`ss -tlnp | grep :9223`）。
 2026-09-12 20:25:00 +08:00
JianFeeeee
bbddee26b9 feat(permission): 待办带上失效时刻；越窗的决策不再假装成功 
# 起因：一次端到端验证暴露的静默缺口

建了示例工程让 pi 通过邮件干活（plan 档拦截、workspace 档审批、多 agent 指派）。
plan 档与多 agent 都通过，workspace 档却卡住：**人在界面上批准了一条待办，
接口回 200，但那件事什么都没发生。**

追下去是三件事叠在一起：

1. **桥**等不到决策时（pi 的回合超时 TURN_TIMEOUT_MS，默认 10 分钟）会拆掉 worker
   与它的决策路由表；此后再来的决策只会作为**通知**投给 Agent，不恢复当时那次
   工具调用 —— 该轮已经结束了。
2. **服务端**只有 `permission_requests.result IS NULL`，没有「失效」概念。
   迟到决策照样回 `{"status":"decided"}`。
3. **前端**只看 `permission_result` 判待决/已决，没有任何时间或失效提示。

于是那条待办永远挂在授权页上显示「等待你决策」，人点了也白点。这是 I-5
（失败必须当场可见）要消灭的那类静默成功，而且**跨所有客户端**成立 ——
WebUI 不显示，Electron / Harmony 同样无从显示。

# 设计：邮件上给「时刻」，不给「是否失效」的布尔值

服务端不知道插件此刻是否还在等（那是它进程内的状态），所以只标出「这封待办已经
放了很久」，不替插件宣布裁决。

关键取舍：对外只发**截止时刻**（`permission_expires_at`），不发 `stale` 布尔值。
布尔值是「发出那一刻」的快照 —— 经 SSE 推送并被客户端缓存后会永久停在旧值，
界面就会一直显示「等待你决策」。时刻是持久事实，任何客户端在任何时候都能自己
比出现在过没过期。这也是为什么推导而非落库：它是 created_at 的函数，存下来会失真。

`DecidePermission` 的响应里则用布尔值（`expired`）—— 响应本身就是「此刻」的
一次性快照，不会像邮件那样被缓存反复展示。

# 改动

- `models.PermissionWaitWindow`（10 分钟，与 pi 桥的回合超时同量级）+
  `PermissionDeadline(createdAt)`；两端共用这一处算式，避免「界面说已过期、
  决策说没过期」。
- `Mail.PermissionExpiresAt` / `PermissionRequest.ExpiresAt`：由读路径推导填充。
  5 个读路径各插一行（`AttachPermissionDeadline*`）—— 与审计修复① 加
  permission_kind 时同一套路数，漏掉任一路径只会静默变成 nil。
  只给**仍未决策**的待办填，已决策的不再是待办。
- `decideResponse`（抽出纯函数以便测试）：越窗时加 `expired` + `warning`，
  讲清「决策已记录、但不会恢复原调用」。**不改 HTTP 状态码**：决策仍是人的真实
  意愿、仍然有效（桥会当通知投递，Agent 重起一轮），所以不能拒掉，但必须说清。
- 前端：列表里失效项不再与「还能立刻生效」的长得一样（灰底 + 「可能已失效」）；
  批准面板在决策**前**（人正要按下去）与决策**后**（人以为事情办了）都显示提示。

# 验证

- Go：models/repo/handler 三处新增测试全绿；全量 `go test ./...` 通过；vet 通过
- 前端：typecheck 通过；200 项测试全绿（含新增 4 条失效态）
- 真机（用现成的过期待办，未造合成数据）：
  - `/permission/pending` 返回 `expires_at` = 创建 + 10 分钟，服务端判定已过窗
  - 邮件载荷带上 `permission_expires_at`（前端列表的数据源）
  - 对过期待办提交批准 → `{"expired":true, "expires_at":…, "warning":"该请求已超过
    等待窗口（10 分钟）…不会恢复当时那次工具调用…"}`
- 已用 redeploy-gateway.sh 部署，服务 active、四 agent 心跳正常、日志无 panic
 2026-09-11 22:02:25 +08:00
JianFeeeee
4050827e5c feat(permission): 新增第三种强制力 partial —— DSH 如实自报，不再冒充 native 
# 问题

审计发现 DSH 自报 mode_enforcement=native，而实测它的 Landlock 沙箱受内核 ABI
版本限制、拦截覆盖不完整（PLAN.md L5 自己写的就是 dsh = Landlock partial）。

只有 native / advisory 两个取值时，这个平台无论标哪个都是在说假话：
  - 标 native → 人会以为 plan 档是硬保证，把它当安全边界依赖；
  - 标 advisory → 又低估了它（确实在拦），而「平台无法强制」会让模型
    在本可依赖的边界上过度保守。
多一个取值比多说一句假话便宜。

# 改动

- Go models：EnforcementPartial = "partial"，ValidEnforcement 接受它；
  NormalizeEnforcement 对显式自报值一律原样保留（partial 降级到任一极端都是假话），
  未知值仍然 fail-closed 到 advisory。
- 三桥共用 lib/permission-mode.js（逐字节同源）：ENFORCE_PARTIAL +
  modeBriefing 三态措辞。partial 版必须同时做到两件事：
  说清「覆盖不完整」，并收回 native 那句「都会被平台拦下」的承诺
  —— 否则模型会以为越界一定被拦，于是不必自己小心。
- 前端 PermissionChip：三个点形区分（实心 / 靶心 / 空心）+ 三套 tooltip 文案；
  认不出的强制力按 advisory（与后端同方向）。
- DSH 插件心跳改报 partial。
- 顺带修正活跃 DSH 会话的历史快照：那批 native 是插件当时的**误报**，
  不是能力变化，因此把 status<>'archived' 的 dsh 会话改为 partial；
  归档会话按设计保留（不重写已结束的历史）。改前已 sqlite3 .backup 备份。

# 验证

- agents.mode_enforcement：dsh 由 native 变为 partial（心跳生效）
- Go 全量、三桥插件 320/362/409、前端 196 全绿（新增 PermissionChip 11 例）
- 三桥共用模块同源校验通过
- 关键判据：partial 的措辞与 native/advisory 两两不同，且不含「无法强制」
 2026-09-11 12:04:06 +08:00
JianFeeeee
429149e118 chore(format): 撤销误入提交的整体重排，并关闭本仓库的格式化器 
# 发生了什么

pi-lens 内置「安全格式化」：它会自动安装 biome 并对**编辑过的文件**跑
`biome format --write`。本机原先没有任何 biome 配置，于是 biome 用它自己的
默认值 —— tab 缩进 + 双引号 —— 把文件整体重写。

我在 19a3161 那次提交里用了 `git add -A`，把这批与功能无关的重排一起扫了进去：
约 7000 行改动散落在 20 个文件上，使那次提交无法审查，还掩盖了
server/internal/handler/permission.go 的一处删行（实为文件末尾空行，无代码丢失）。

# 为什么是「关掉」而不是「配置成我们的风格」

试过把缩进/引号/lineWidth 全部对齐本仓库习惯（biome.json + space/2/single/
lineWidth 120）：`biome format --write` 仍然改动 17 个文件。原因是本仓库从未按
biome 的规则排版过 —— 注释按语义换行、数组与调用按可读性手工折行，
这些无法由格式化器还原。也就是说只要格式化器开着，每次编辑都会产生与内容无关的
大面积 diff，把真正的改动埋掉。

因此 biome.jsonc 里 formatter 与 linter 都关闭：本仓库的静态检查由
tsc / go vet / tree-sitter / ast-grep 与各自测试套件承担，不引入会改动无关行的
自动修复。

（pi-lens 这一版把 format 服务的 enabled 硬编码为 true，没有配置开关，
所以只能在仓库侧用 biome 配置让它不动文件；已验证 `biome format --write`
对这些文件零改动。）

# 本提交内容

把 19a3161 里除「有意改动」外的 20 个文件还原到重排前的样子。
19a3161 中真正有意的改动是 deploy/install.sh 的扩展注册与
plugins/pi-mail-bridge/extension/index.ts 新文件，两者原样保留。

验证：Go 全量、三桥插件（320/362/409）、前端 196 全绿；
`biome format --write` 对还原后的文件零改动。
 2026-09-11 12:03:51 +08:00
JianFeeeee
19a3161ee4 feat(pi): 交互式 pi 会话接入邮件工具（send_mail/read_inbox 等 10 个） 
问题（⑧）：守护进程用 noExtensions:true 起会话，它的邮件工具只给模型在邮件
会话里用；人在 TUI 里敲的 pi 拿不到。结果是平台的建设者自己收不到邮件 ——
一个「邮件驱动」的平台，维护者只能绕到 curl + 密钥直连 Gateway 才能看收件箱。

新增 plugins/pi-mail-bridge/extension/index.ts：把同一套工具（createMailTools）
注册到交互式会话。两者是同一条 AgentMail 身份（agent pi）的两个入口，与 DSH 的
「TUI + 邮箱是同一个 Agent」一致。

密钥解析顺序（交互式 pi 的环境里没有 AGENTMAIL_*）：
  1. 进程环境
  2. AGENTMAIL_ENV_FILE（默认 /etc/agentmail/pi.env）—— 与守护进程同一把密钥，
     因此身份一致
  3. AGENTMAIL_CONFIG_DIR/agent.key 或 ~/.agentmail/agent.key
     （兼容 key 与 key_token 两种字段名；实测本机文件用的是 key_token，
      只认 key 会静默读不到）
拿不到密钥时不注册任何工具并明确告知 —— 挂一组永远 401 的工具比没有更糟。

不注册 connect_to_server：它会重写 Gateway 坐标并重新登记密钥，而交互式会话与
守护进程共用同一身份，一次 TUI 对话不该改到守护进程的配置。

为什么不会重复注册（读 SDK 实现确认，并用探针实测）：
  resource-loader.js 里 noExtensions 为真时只用 cliEnabledExtensions，
  settings.json 的 extensions 数组被排除 —— 即 noExtensions:true 只加载
  命令行 -e 传入的扩展。
  探针：noExtensions=true → 扩展数=0；false → 16 个且含 pi-mail-bridge。

deploy/install.sh 增加幂等的扩展注册步骤（写入 settings.json 的 extensions）。

验证：headless pi 实际调用 read_inbox 返回真实邮件主题；工具清单含
send_mail/read_inbox/read_mail/forward_mail/upload_attachment/download_attachment/
suggest_address/list_contacts/session_participants/read_thread（10 个），
connect_to_server 按设计排除。
 2026-09-11 11:32:47 +08:00
JianFeeeee
f91efd2d8d feat(question): DSH ask_user_question 桥接 + 前端问答面板 + 待办字段全路径透出 
问题（P0）：DSH 有两个独立的人机交互 seam —— approval/request（危险工具审批）
与 ask_user_question → ctx.userQuestions（模型主动提问）。原来只桥接了前者。
邮件驱动的会话没有本地 UI，而 ask() 的 provider 是 DSH host 注册的本地 UI 实现，
于是在那里等人点选永久等不到，那一轮工具调用**静默挂死**。

修法（不抢注全局 provider —— registerProvider 只允许一个活动实例，抢注会让
平台自己的界面失效）：在 tools/execute around-dispatch 里只对**邮件驱动**的
会话接管 ask_user_question，其余原样 next()。失败一律当场报错而不是 next()：
下一个 answerer 是本地 UI，邮件会话没有兜底 UI，放过去就是挂死。

- lib/user-question.js（三桥逐字节同源，14 例测试）：DSH questions[] ↔ AgentMail
  单问题询问邮件的双向映射。多问题时把选项并集摊平、按 label 归属分配回各问题
  （label 认不出来就不猜测放行）；无选项题走自由文本 custom。
- Gateway：kind=question 且无选项时**不再**回落「同意/拒绝」（那会让自由文本
  问题变成两个毫无意义的按钮）；主题按类型区分「权限请求 / 需要回答」；
  推送 payload 带上 permission_kind / multi_select / options。
- mails.permission_kind / permission_multi_select 此前只存在于结构体与写入路径，
  五个读路径的 SELECT/Scan 都没带 —— 前端永远拿到空串，把提问渲染成批准/拒绝。
  container 修正五处并加 repo 测试（含反向验证：删掉任一处字段，测试即失败）。
- 前端 PermissionPanel：question 走「勾选 + 自由文本」，多选/单选、空回答禁止提交；
  approval 路径不变（回归测试覆盖）。

测试：opencode 316 / dsh 349 / pi 405 / 前端 185 / Go 全量 全绿。
 2026-09-11 10:44:18 +08:00
JianFeeeee
f9d757b5e5 chore: directory migration - gateway→server, web→client/electron 2026-09-08 19:16:35 +08:00