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

60 Commits

Author SHA1 Message Date
JianFeeeee
71a3c35610 按 pi 复核改五处：判据的"值/行为"原则、真正的构建门、typecheck 进门、Go 判据零匹配、迁移归属 
pi 用反例与变异逐条点了五处，全部**先跑变异再改**（结论都写在原地）。

## 1 判据③：形状正则已删（它永远差一个反例）

实测 pi 的反例 —— `const k = PREFIX + accountId; return PREFIX;`（拼了但没返回）——
对第三版判据**仍然全绿**：第三版锚的是"**函数体里存在**这样的表达式"，不是"**返回的**表达式"。
三版的骗法各一个（签名里的参数 / 提了一下没用 / 拼了没返回），都在判"源码里有没有那个形状"，
而缺陷是"算出来的值对不对" ⇒ **权威交给行为判据**（`test/stores/background.test.ts` 直接断言
`storageKey('a') !== storageKey('b')`、`=== 'agentmail.background.acct-a'`、不退回全局键），
正则那条删掉并把反例写在原地（否则下一个人会好心加回来）。
保留"键必须来自 storageKey()"那条：那是**来源**约束，不是值对不对，正则在这里合适。
鸿蒙侧只能静态判（`.ets` 本机没有运行时），已把这条限制写进判据说明。
推广进规范：CRITERIA.md §6.7 + run-all 自检关键词（10 → 11）。

## 2 真正的门：`scripts/release-linux.sh`

- 实测 pi 提的变异：**`touch dist/index.html` 时 stamp 判据是绿的** —— 它抓不到"构建失败但碰过 dist"。
  stamp 是**探测器**（抓"src 改了产物没跟上"），门是**喂退出码**，两者不互替（§6.7.1）。
- `build:linux` 里**没有管道**（`&&` 链，退出码本来就传），但那次的哑巴失败是我在命令行手打
  `npm run build 2>&1 | tail -4 && …` 造成的；同时发现它跑的是**裸 `vite build`，跳过 `gen:bg`**。
- 于是把配方收成 `scripts/release-linux.sh`：`set -euo pipefail` + 走 `npm run build` + 再打包。
- 判据是**行为**的：注入失败的构建（`AGENTMAIL_BUILD_CMD='exit 7'`）→ 断言退出码非 0
  **且打包那步没跑**（标记文件不存在）。变异：脚本改成 `|| true` → 红 ✓。

## 3 typecheck 进 `npm test` 链

`npm run typecheck` 原本就有，但没人跑。先修掉它唯一的报错（我自己留下的未使用 import），现在干净；
`test` = run-all + vitest + typecheck。它恰好检查**没被任何测试 import 的文件**（vitest 只解析被测到的图）——
也就是那次 `is not exported by` 的形状。

## 4 Go 源码判据：零匹配 / 读不懂 都要红

改成三分：切不出函数体 → 红；字段在但值不是字面量 → 报「**判据读不懂**」（变异：`BgDim: defaultDim` → 红 ✓）；
字段不在 → 红。静默放行是这类判据最危险的失败方式。
**措辞更正**：这条核对的是"与**这份服务端源码**的契约"，不是"在跑的服务端二进制是 12/4"
（与"dist 是产物"同构）；文档同步改。

## 5 迁移归属：定向做不到，就把"不可恢复"降级成"可恢复"

查实：`accountStore` 的 `activeId` 是**派生视图状态、不落盘**（`persist(accounts)` 只存数组），
所以**本机没有"上次活跃账号"标记可定向** —— 旧值的作者事后无法还原，定向迁移在原理上做不到。
升级前用 B、升级后先登录 A ⇒ A 接管 B 的外观，**一次性错档**，触发条件就这一条。
两件能做的都做了：**写了回读校验**（写不进去就不删旧键，避免净损失；变异：改成先删后写 → 2 条红 ✓）、
**删前另存** `agentmail.background.legacy.bak`（只写不读 ⇒ 不引入新的继承源，判据钉"只写不读"）。
§7.12 把本地这半与显形方式写进同一行。

## 验证

`npm test` 退出码 0：14 个判据文件全绿 + vitest **265** 通过（+2 迁移行为测试）+ typecheck 干净；
`hvigorw assembleHap` BUILD SUCCESSFUL；安装包经新脚本重打（dist 与包同批）。
 2026-09-14 15:41:52 +08:00
JianFeeeee
ccd0a39e76 docs(P5): 悬浮玻璃导航落地记录 + 视觉验收的**实测**阻塞（不是"还没做"） 
- §5.4 的 P5 行由「⬜ 未做」改为「✅ 主体完成」，并写明**未验项与原因**。
- 新增 §7.21：改了什么（NavItems.ts 放尺寸常量让判据判**数值**；内容按 index 挂载；
  内容底部让位 76vp —— 不让位则最后一行压在条底下，看得见点不到）、判据 6 条、
  4 种变异、以及**判据自己修的两处**（非贪婪正则撞对象字面量的 `}`；色值检查读了含注释的原文）。
- §7.21 末节把"观感验不了"逐层测清楚：①模拟器要写工作区外的
  /root/.Huawei/…/Log/qemu.log，本会话 workspace-write 判 Permission denied；
  ②放宽权限需审批而**这条链上没有人类**，工具明确拒绝；③不需要权限的替代路
  （HOME 挪进工作区，复制实例 + 符号链接镜像，2.7GB）过了写入这关却卡在**许可协议**，
  重放 y 等于替用户同意法律协议 —— 不做，已停止模拟器并删除暂存副本。
  → 要解除需人二选一：放行工作区外写入，或由人在本机起模拟器后把画面交回。

验证：hvigorw assembleHap BUILD SUCCESSFUL；npm test 14 个判据文件里 13 绿
（唯一红的 narrow-layout 由并发写作者的未提交 MailView.tsx 改动引起 —— 用 git stash 验过：
剥掉那个改动即 52 通过，与 P5 无关，未动他人的文件）。
 2026-09-14 15:35:48 +08:00
JianFeeeee
dbdb2f5039 跨端: 修打包坑（构建失败被管道吞掉）+ dist 新鲜度判据；判据从"窗口式"改成同表达式 
接手 pi 的 WebUI 开项途中踩到三个坑，都已修好并配判据（承接 e94313f）。

## 坑 1：`npm run build 2>&1 | tail -4 && electron-builder …` 吞掉构建失败

pipeline 的退出码是 `tail` 的 → 构建失败、`&&` 照样往下走、electron-builder
**拿旧的 dist 打了新包**。而所有判据都是绿的：
- vitest 绿（见坑 2）；packaging 绿（它比 dist vs 安装包，两边都是旧的，自然一致）。

新增判据：**dist 必须比 src 新**（build-stamp）。变异：`touch` 一个 src 文件 → 红；
重新 `npm run build` → 绿。错误信息写明"注意别把它的退出码丢在管道里"。
已重构建 + 重打包（deb 与 app.asar 同批，15:19）。

## 坑 2：测试通过 ≠ 能打包

真正的失败：`AGGREGATE_ID` / `isUsableAccount` 被我当成 `accountStore` 的导出
（它们住在 `lib/accounts.ts`）。vitest 263 条全绿，生产构建直接报
`"AGGREGATE_ID" is not exported by "src/stores/accountStore.ts"` ——
测试运行时对缺的具名导出是宽容的（拿到 undefined）。**生产构建是一道独立的门。**

## 坑 3：判据写成"窗口式"，被自己的变异测试抓住两次

`appearance-defaults` 的"取键函数必须把账号拼进去"：
1. 第一版从 `export function` 切到 `}` → **参数表里的 accountId 满足了正则**，
   把实现退回全局键仍然全绿（假判据！）；
2. 第二版只取函数体 → `return accountId ? PREFIX : PREFIX;`（提了一下没用）又骗过去；
3. 第三版要求**同一个表达式里既有常量又有账号的插值/拼接**：
   两种退化都红，合法的 `PREFIX + accountId` 写法仍然绿。

三种变异都验过（红/红/绿），还原后基线绿。

## 文档

§7.12 两行改为「已修」并写明依据（默认值＝服务端契约；缓存键差异已消除，旧全局键
只作一次性迁移源）；新增 §7.20 记这三个坑与推论（产物是 gitignore 的，
"源码修好"≠"用户手上那个包修好"）。

## 验证

`npm test` 退出码 0（13 个判据文件全绿 + vitest 263 passed）；
`hvigorw assembleHap` BUILD SUCCESSFUL；`npm run build` + electron-builder 均 exit 0。
 2026-09-14 15:20:30 +08:00
JianFeeeee
d1e0ba32f9 跨端: 壁纸遮盖色改用页面底色系（mask 两套主题都深，浅色下方向与 WebUI 相反）；模态遮罩保持 mask 
pi 提了一个**方向性**疑问，让我先把值读出来再定 —— 读完确认**他是对的**，而且这是"机制上确定不同"。

## 实测（两张 SDK 表交叉验证，不靠记忆）

`ets/build-tools/ets-loader/sysResource.js` 给名字→id，`previewer/.../resources.txt` 给 id→值：

| 令牌 | 浅色主题 | 深色主题 |
|---|---|---|
| `ohos_id_color_mask_regular`（原 `Theme.overlay`） | `#99182431` **深蓝灰** | `#b2000000` 黑 |
| `ohos_id_color_background` | `#ffffffff` **白** | `#ff18181a` 近黑 |

⇒ mask 的 light/regular/thick 是**浓度档**（同一深色的三个 alpha），不是深浅两套值：
它在**两套主题下都是深色**（模态遮罩语义）。而 WebUI 的 `--bg-scrim` 浅色是**白**
（原话「浅色下用白把花哨的图案洗淡」）—— 壁纸遮盖用 mask 就是**反方向**：
浅色主题下把预设压暗，而 WebUI 是把它洗淡。

## 改法

- 新增 `Theme.wallpaperScrim = $r('sys.color.ohos_id_color_background')`（页面底色系：
  浅色白、深色近黑，**自动换向**，与"朝底色淡化"同一意图）；预设档与图片档的遮盖层都用它。
- `Theme.overlay`（mask）**只留给模态弹层**（那里语义确实是压暗背后）。
- 不复用 `pageBg` 的原因写进注释：页面底在背景开启时会被换成**透明**
  （`bgActive ? Color.Transparent : Theme.pageBg`），而遮盖层**永远要一个真实颜色** ——
  两个用途生命周期不同，共用一个名字迟早坏一头（这个仓库撞过四次的模式）。

## 判据（从 SDK 读真值再判，不写死结论）

断言「mask 两套主题都深」「页面底色系浅白深黑」「WebUI 的 `--bg-scrim` 浅色是白」，
再落到代码：两处遮盖层必须用 `wallpaperScrim`、弹层仍用 `overlay`、两个令牌不许混用。
**这样"令牌选错方向"以后不能靠记性避免。**

变异：遮盖退回 mask → 红 1 条；只改一层 → 红 2 条。

## 文档

§7.17b-2 记这次读数（表格 + 两张表怎么读 + 为什么不复用 pageBg + 变异结果）；
§7.12 有意差异表加一行（遮盖色令牌：两个语义两个令牌，"不允许混用"）。

## 验证

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0
（12 个判据文件全绿 + vitest 258/258；harmony-appearance 23 → 24 条）。
 2026-09-14 15:10:15 +08:00
JianFeeeee
71585dc42b 跨端: 预设档补遮罩（WebUI 的 --bg-dim 不分档位）+ 主题变化时重算"我们自己算的值"；缓存键差异记入表 
pi 读 WebUI 源码后发现两处两边不一致，都处理了。这一提交同时改 harmony 与 electron，故自报家门。

## 1 预设档遮罩：**补上**（选"与 WebUI 一致"，因为那服务的是可读性）

pi 的证据：WebUI 的 `applyBackground()` **无条件**写 `--bg-dim`（默认 24），
`.app-backdrop::after` 是 `rgb(var(--bg-scrim) / var(--bg-dim))` —— **遮罩不区分档位**；
它的注释写着目的「背景越花，正文越需要一层遮罩才读得动」。
而鸿蒙当时只在 image 档压（`resolveBackground` 里那行注释还写着"preset 档不用"），
且我们已经让出了页面底 → 正文直接压在原色渐变上，**比 WebUI 更艳更亮、更不好读**。

现在两档用**同一个浓度**（同一个服务端字段），页面在预设分支的渐变之上加一层
系统遮罩色 × 浓度（浅色由系统洗白、深色压黑，不自己写 alpha）。

判据：旧断言"preset 档不压暗"**反过来**（留着理由），另加一条钉"两档同一浓度"+
"两处遮盖层都在"+"WebUI 确实无条件写 --bg-dim"（这条差异有据可查）。
变异：预设档不压 → 红 2 条；页面预设分支的遮盖层被删 → 红。

## 2 多账号缓存键：**鸿蒙是对的，不许退回**（pi 点名）

WebUI 的键是全局常量 `agentmail.background`，后果是切到服务端没有记录的账号时
`saved=false` 分支会把**上一个账号的外观** push 上去（新账号"继承"了外观，还写进了服务端）。
这条差异进 §7.12「有意差异」表，**明确写"鸿蒙是对的"**，
判据防的就是"将来有人为了两边一致把它改回去"：取键函数的**正文**里必须拼账号 id
（按块取，不是看调用点出现过 `accountId` 就当数 —— "判结构要配对/解析"那条对我自己也适用），
且不许出现 WebUI 那个全局键。变异：`prefKey` 去掉账号 → 红 2 条。

## 3 "未做" → 按 pi 的三档口径改成**已知不一致**，并把系统侧的接法做掉

pi 指出这不是"没做"：色板确实按主题算了，只是没接环境变化事件 ——
现象是运行期切系统深浅色时"系统语义色/材质立刻跟随、我们自己算的色板不重算"的**撕裂**。
他给的规则我记成了通用规则（会咬到 P5/P6）：**系统自动跟随的东西不会顺带把
"我们自己计算/缓存的值"一起更新** —— 凡随主题变化的自算值都要挂在**同一个主题变化事件**上。

照做：`applicationContext.on('environment')` → `onConfigurationUpdated` 里
**只在 `colorMode` 真换向时**重算（`applyAppearance()`），页面销毁 `off` 退订。
状态 = **未验**（只有真机/模拟器能验：切一次系统深浅色看预设是否跟着换）。

SDK 锚点与两个编译错都记进 §7.17b：`EnvironmentCallback.onConfigurationUpdated(config: Configuration)`
（`Configuration` 从 `@kit.AbilityKit` 取，**不在** `common` 命名空间下）、
`Configuration.colorMode` 是**枚举 | undefined**（字段写成 `number` 直接编译失败）、
`on('environment')` 返回 **number 型 callbackId**。变异：不订阅 → 红。

## 4 文档

- §7.12 加两行：缓存键（含 WebUI 侧开项）、遮罩浓度默认值那两套（`24/8` vs `12/4`，
  按 `clamp` 的 12/4 对齐，因为服务端缺字段时落地的是它）。
- §四 验收纪律改成**四档口径**：没做 / 未验 / 已知不一致（要写触发条件与现象）/
  机制上确定不同（必须判），并把 pi 那条"自算值必须挂主题事件"的可复用规则写进去。

## 验证

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0
（12 个判据文件全绿 + vitest 258/258；harmony-appearance 20 → 23 条）。
 2026-09-14 15:04:07 +08:00
JianFeeeee
4babc96f8b test(criteria): runner 不再手写 --test（由内容推导）+ 自检 4「这条判据能不能红」；规范补两档 
pi 提的三条，第一条落地前先按他的要求**贴真实样本实测**，结论与他的猜测不同（记在代码里）。

## 1 runner 内部那个"配错 flag = 绿" —— 实测后换了个形状

pi 的猜测：给自定义 `check()` 的判据传 `--test`，runner 会报"0 个测试"并以 0 退出。
实测（node v22.22.2，两条真实样本）：

- `node --test <自定义 check() 判据>`：**退出码照样传出来**（文件 exit 1 → 命令行 exit 1），
  没有被吞；
- 但 `node --test <什么都不做的文件>` 报 `# tests 1 / # pass 1` ——
  **pass 计数不是"检查跑过"的证据**。

所以"解析 pass 计数、0 就判红"这条路两头不讨好：抓不到空判据（它报 1），
还会在 `narrow-layout` 上误报（它的汇总行是"窄屏布局：全部通过"，里面没有数字）——
正是 pi 提醒的"别照抄我的正则，先贴样本"。

换成两条**结构证据**：

- **`--test` 不再手写**：由文件内容推导（源码里 `from 'node:test'` 就走 node:test），
  清单里出现手写 `--test` 直接红 —— 配对错误不再靠记性维护；
- **自检 4**：每条判据文件里必须存在"能红"的路径（`test(` / `check(` / `process.exit(1)`），
  外加"跑完必须有输出"。一个都没有 = 它永远不会红，与"全通过"长得一模一样
  （这是"判据自己不会跑"家族的第 6 个宿主，家族表和六种宿主都写进规范了）。

变异：清单手写 `--test` → 红；加一条"什么都不做、退出 0"的判据 → 红；
静默成功（有能红路径但一行不输出）→ 红。

## 2 规范 §3 补一档：变异红了还要看**红在哪**（pi）

"只报红了不算，要能指名红的是哪几条"；**红在解析/加载失败上不算红**（先让变异
"语法正确、语义错"）；变异作用于被剥掉的注释也不算。

## 3 `CRITERIA.md` 的可见性（pi 提的位置问题）

它管两个客户端的判据，却躺在 electron 的测试目录里。已在
`docs/HARMONY-ALIGN-PLAN.md` §四（验收纪律）加指针，并顺手把 pi 点名过的两条口径写死在那儿：
**"未验"只能用于"步骤做过、结果没看"，功能不存在必须写"没做"**；
**"机制上确定不同"要判、不许记成"未验"**（深色档预设那次）。

## 验证

`npm test` 退出码 0（12 个判据文件全绿 + vitest 258/258）。
 2026-09-14 15:00:26 +08:00
JianFeeeee
22c9be7181 跨端: 预设色板两套（pi：这不是"观感未验"而是机制上确定不同）+ 手写色清册跨文件 + TMPDIR 按会话分家 + 提交归属可判 
pi 读完 `model/Wallpaper.ts` 后指出四处，全部处理。这一提交同时改了
`client/harmony/` 与 `client/electron/`（跨端改动），所以 subject 按新约定自报家门。

## 1 预设色板不随主题 —— **类别判错了：不是"未验"，是机制上确定不同**

我上一版把"深色档预设"记成"观感未验"。pi 指出：WebUI 的 `.bg-preset-*` 写的是
`rgb(var(--c-blue-100))`，而 `--c-*` 在 `.dark` 里整体换了一套（blue-100 → `30 43 67`），
所以 **WebUI 的预设自动随主题变**；这边只有浅色那套 = 深色主题下"浅色渐变垫在深色系统表面之下"，
正是这一整轮在治的病。**它不需要真机就能判**（机制写在代码里）—— 我把可判的东西
记成了"未验"，这跟上一轮把"没做"写成"没验"是同一类错。

选 pi 倾向的那条（跟随主题，与 WebUI 一致）：

- 色板两套：`LIGHT_*` 取 CSS `:root`、`DARK_*` 取 CSS `.dark`；`paletteFor(dark)` 选一套，
  `layersFor(id, dark)` 按主题出层；
- `isDarkMode(theme, systemColorMode)` 放在纯逻辑里：选了 dark/light 就照办，
  `system` 看系统当时的 `colorMode`（锚到 SDK：`COLOR_MODE_DARK = 0` / `COLOR_MODE_LIGHT = 1`；
  读不到按浅色，与 WebUI 的 `:root` 默认一致）；
- 系统深浅从 `resourceManager.getConfigurationSync().colorMode` 读
  （`Context` 基类没有 `config`；`UIAbilityContext.config` 要转型；两个枚举取值一致，都核过 SDK）；
- 判据：两套值与 `:root`/`.dark` **逐个相等**；每个预设的深浅两套**必须真的不同**
  （否则"两套"是抄了两遍）；网格线色也要换；`isDarkMode` 五种输入。
- **未做**：运行期间改系统深浅色不会自动重算（要重进页面）——系统侧正确做法是订阅
  `applicationContext.on('environment', …)`，记在 §7.17b。

变异：`DARK_BLUE_100` 偏一位 → 红；`paletteFor` 永远返回浅色（= 我原来那个状态）→ 红；
`isDarkMode` 把系统深浅记反 → 红；页面把深浅写死成 false → 红。

## 2 手写色清册**跨文件按类扫**（原 A2 只保护 `Theme.ets`）

`Wallpaper.ts` 也有手写色。若对照是"按名字枚举"的，第 15 个色就会逃掉 ——
与 A2 要防的是同一件事，只是换了文件。现在一份清册按类扫：全 `ets/` 树里每个
`X: string = '#RRGGBB'` 都必须登记（Theme 的品牌/业务语义色，或预设色板 ——
后者常量名必须带 `LIGHT_`/`DARK_` 前缀，值由 CSS 两段比对负责）。反向也判清册过期。

变异：`Theme.ets` 加未登记色 → 红；`Wallpaper.ts` 加未登记色 → 红；
加一个"看着合规"的 `DARK_EXTRA` → 红。

## 3 `TMPDIR` 互踩（pi 提出）

这个 worktree 可能同时有多个 agent 跑构建，而 fpm 会把 291MB 的 `linux-unpacked`
**整份复制**进 `TMPDIR` —— 撞车就是随机的产物损坏。`whoami` 区分不开（大家都是 root），
所以按**会话**分家：`TMPDIR=$PWD/.tmp/${DSH_SESSION_ID:-$(id -un)-$$}`
（进了 `npm run build:linux` 与 BUILD.md 的手敲命令；普通终端退化成"用户+PID"）。

## 4 提交归属变成**跑判据就看得出来**（pi 给的形状）

新的 `test/commit-hygiene.test.mjs`：扫最近 40 条提交，**同时改两侧目录**的提交
必须在 subject 里自报家门（`跨端:`）。两条防腐：基线 = 该判据文件自己的引入提交
（**历史不改**，规则管从今往后）；分类逻辑拿合成输入自检
（未标注的混合提交必须判红、标注过的不许红）——否则"解析没跑起来"时它会全绿。
变异：`COMMIT_HYGIENE_BASELINE` 指到老提交 → 历史里那两个被卷进去的提交立刻判红。

## 验证

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0
（12 个判据文件全绿 + vitest 258/258；`commit-hygiene` 在本提交落地后基线生效）。
 2026-09-14 14:57:18 +08:00
JianFeeeee
0ce8b29546 test(criteria): 判据规范 CRITERIA.md（邻接不是结构·第三次露头）+ 废弃 API allow-list 结构化 + 扫描范围自检 
pi 的两条增量，都不需要他再确认。

## 1（pi 建议）：生成清单 + 空 allow-list 的结构性风险

他的推演：SDK 升版会往清单里加新条目 → 某天早上套件**突然红**，且红在与本次改动无关的
代码上；这时人的第一反应是把名字塞进 allow-list —— 而 allow-list 一旦这么用，
就不再是"研究过的例外"，只是"红的止痛药"。所以条目结构化：

```js
const ALLOW = [ /* { name, replacement, why } */ ];
```

`replacement` 非空是硬断言（"暂时不想改"不是放行理由，"替代品要求的 API level 高于基线"才是）。
**刻意不断言"名单必须为空"** —— 那会挡住合理放行；断言的是"有名字、没替代品 → 红"，
于是侵蚀发生时红的是**放行这件事本身**，而不是某天的新 SDK。
变异：塞一条 `{ name:'px2vp', replacement:'', why:'暂时不想改' }` → 红。

## 2（pi 建议）：扫目录的判据要防"空判据"

他问废弃 API 判据扫哪些目录（怕只扫 `pages/`，`common/` 里的旧写法逃掉）。
答案：扫的是**整个 ets 目录递归**（实测 25 个文件，含 `pages/ common/ model/ api/ entryability/`）。
顺手加了防退化的自检：文件数 ≥ 20，且 `pages/ common/ model/ api/` 四个目录都必须扫到
—— 目录改名/只扫一个子目录会让这条变成空判据而依然全绿。
变异：把扫描范围改成只扫 `pages/` → 红。

## 3（pi 建议）：把"邻接不是结构"写进判据规范

同一个坑在本仓露头三次：① 窗口式正则被一行注释挤爆（原注释自嘲过）；
② 括号配对取代窗口；③ 链式修饰符让"看前一个字符是不是 `}`"静默失效。
共同形式值得升格成规则，于是新建 `client/electron/test/CRITERIA.md`（七条），
并在 `run-all.mjs` 加**自检 3**：规范文件必须在、且必须点到关键条目。
WebUI 侧 `background.test.mjs` 的窗口式存量按 pi 的说明**记着不动**（那是他的地盘）。

规范里另外两条是本仓自己踩出来的：剥注释读代码 vs 读原文读理由（混用必红）；
以及**验证要按真实入口跑** —— 我用 `node --test test/run-all.mjs` 验自检 3 时它"依然绿"，
其实是 runner 把内部的 `process.exit(1)` 吞了；换成 `npm test` 走的那一行就红对了。
变异：删掉规范里的一条关键规则 → `npm test` 那条路 exit 1。

## 验证

`npm test` 退出码 0（11 个判据文件全绿 + vitest 258/258）；`hvigorw assembleHap` 未受影响。
 2026-09-14 14:51:30 +08:00
JianFeeeee
c4ee5f3ebe docs(harmony): 记下 §7.17 那批代码的提交归属（并发写入者的 git add -A 把它们并进了 WebUI 提交） 
P4b 的实际代码（`model/Wallpaper.ts`、`MainPage` 的壁纸层与页面底让出、判据、本节文档）
落在 `c9717da` 与 `1717863` 里 —— 那两个提交的信息写的是 **WebUI** 的事：
并发写入者与我共用同一个 git 身份，它 `git add -A` 时把我尚未提交的工作区一起提交了。
代码是好的，归属是错的；`962df62` 里有完整的"改了什么/为什么/怎么验"，但 diff 只有判据文件。

所以补一条 7.17a：说清哪几个提交、为什么信息对不上、以及按路径 add 更稳。
不留这条的话，`git log -1 -- .../Wallpaper.ts` 会指向一个 WebUI 提交，
后来人只能靠猜。

`npm test` 退出码 0（11 个判据文件全绿 + vitest 258/258）。
 2026-09-14 14:49:40 +08:00
JianFeeeee
1717863c87 fix(webui): 手势与横向滚动分家 + 纵向滚动边缘淡出 
用户给了两条具体信息（这比我自己猜五轮都管用）：
「横向滚动条会与切换视图的手势冲突，我觉得周视图需要卡严条件，
  同时我说的其他硬截断是对应内容项上下滑动会直接被切断」。

## ① 手势卡严（周视图）

冲突是真的：周视图窄屏下必须横向滚（`overflow-auto` + `min-w-[36rem]`），
而我又给整页加了左右滑动翻页 ⇒ 同一次横滑既想滚又想翻，两边都不好用。

规则定死：**手势从可横向滚动的区域里起手，就归滚动条，完全不参与翻页判断**
（触点沿祖先链查找 `overflow-x: auto/scroll` 且真的能滚的容器）。
想翻页就从别处滑（例如上方标题栏）。

## ② 纵向滚动边缘淡出

滚动条本身是"一刀切"：卡片滚到边缘被硬生生截断 —— 这就是用户说的"直接被切断"。
给纵向滚动容器（`.overflow-y-auto`）加 12px 上下渐隐遮罩，切得有交代。

只作用在**纵向**容器：横向滚动有自己的滚动条，加纵向遮罩会跟它打架。

## 过程记录（值得记）

这两条改动**第一次没有生效**，因为部署失败了：`/tmp` 是 tmpfs 且已 100% 满，
而部署脚本把构建产物写到硬编码的 `/tmp/agentmail-gateway-build-*` ⇒
`no space left on device`。我差点把"旧构建上的测量结果"当成"改动无效"。
清理后（清掉我自己的探针脚本/截图/旧构建，约 950MB）部署成功。
⚠️ `/tmp` 现在仍占 91%（`gocache` 4.5G 等不全是我的），**下次部署可能还会撞上**；
脚本改成尊重 `TMPDIR` 才是根治（未做）。
 2026-09-14 14:35:43 +08:00
JianFeeeee
a6b5e52f45 test(harmony): 判据按 pi 复核意见补强 —— 手写色登记表、玻璃叠用形状、按标题取小节、遮罩必须被用、废弃 API 清单从 SDK 生成 
pi 逐行读了 `cross-client-theme.test.mjs` 与 `Theme.ets` 后指出五处（第一处是真缺口），
外加一条建议。全部处理，并且**每一处都用变异验证过**。

## 一（真缺口）：枚举 11 个"必须是系统资源"的名字，挡不住第 12 个新写死的手写色

`static readonly brandSecondary: string = '#123456'` 这种新增**三条判据都碰不到**：
A（不在名单里）、B（六位、不是半透明）、裸色值那条（只管 `pages/`）。
原理与当初 14 处 Google 色逃出去是同一条 —— **枚举挡实例，类才挡漂移**，
只是这次枚举的单位是**名字**。补 `A2` 条：

- 枚举 `Theme.ets` 里所有 `static readonly X: string = '#……'`，未登记的 → 红；
- 名单里已不存在的名字 → 红（名单不能烂成化石）；
- `Theme.ets` 里的「手写色登记表」段必须逐个列出这些名字（理由不能只存在于记忆里）；
- 自检：把一个**新的**手写色塞进源码字符串，确认这条抓得到。
  `Theme.ets` 因此新增登记表（17 项，每项一行理由，按品牌 / 业务语义 / 档位胶囊分组）。

变异：Theme.ets 加 `brandSecondary` → 红。

## 二：C 的"玻璃只有一处"**说错了自己断言的东西**

`assert.equal(glassCalls.length, 1)` 断言的是"全仓共一处"，**不是**"没有嵌套"：
同页两个**并列**玻璃面（没问题）会让它红，真嵌套它没在判。P5 正是悬浮玻璃导航，
到时若把 1 改成 2 就等于不判。改成形状判据：

- 收集每个调用点所作用的**组件块**（按括号配对回溯；注意 ArkUI 修饰符是链式的，
  `X.blur(A).blur(B)` 前面是 `)` 不是 `}` —— 第一版只看一个字符，对这种写法**静默失效**，
  是判据自检抓出来的）；
- 判两种叠法：同一组件上叠多次（同一块）、以及套在另一层玻璃的子树里；
- 每一处玻璃都要在 `GLASS_REGISTRY` 里登记（附一句为什么），名单里的位置若已不存在 → 红。

变异：链式叠两层 → 红；通信页多开一处未登记玻璃 → 红；导航条块内嵌玻璃 → 红。

## 三：文档小节用 `indexOf('有意差异')` 会**拿错段落**

别的段落正文里出现这四个字，切片就从那里开始，后面所有断言都在**别的段落**上判。
改成**按标题**定位（正则匹配 `^#{2,4}…有意差异…$`），并加了表头列名断言
（WebUI / 鸿蒙 / 为什么）—— 拿错段落时表头不会是这个形状，于是它自己会红。

顺带修掉一个**我自己的**同类毛病：品牌色那行原来用"关键词 + 80 字符窗口"判，
窗口宽度在赌表格单元格字符数（该行两格之和 > 80）。改成**按行取**那一行再断言。
另外把偏移算术的切片换成**按行**切片（偏移差一个字符就会把最后一行拦腰截断，
现象是"品牌色那行只剩 57 字符"这种看着像文案、其实像切片的怪事）。

变异：文件前面插入含「有意差异」的段落 → 仍绿（按标题定位生效）；
再改坏真表里的品牌色行 → 红（确实读的是那一张表）。

## 四：`Theme.overlay` 只判了"存在"，没判"被用"

没使用点的令牌是自证。补断言：它必须在 `Theme.ets` **之外**有真实使用点
（实测 `SettingsPage.ets` / `MailDetailPage.ets` 两处自绘弹层在用），
并把 `overlayColor`/`overlayAlpha` 消失的理由写进 §7.12 —— 否则下一个人会当成漏改补回来。

## 五：材质档次是这次替换里唯一"判据绿但可能观感错"的地方

`COMPONENT_THICK` 的依据（对 THIN / BACKGROUND_* / ULTRA_THICK 的取舍）写进 §7.12，
并把"材质档次在导航条上的实际观感"列为**模拟器起来后第一个要看的项**（间距是数字，材质是判断）。

## 六（建议）：废弃 API 判据**类化** —— 清单从 SDK 生成

原来是手写"不得再用全局 `promptAction.showToast`"（只挡已踩过的那个）。
现在从 SDK 生成：顶层（花括号深度 0）被标 `@deprecated` 的 `declare function`
—— 实测 68 个名字（含 `animateTo` / `getContext` / `px2vp`），配一份**空**的 allow-list。
深度判定是必要的：`declare namespace fileIo { declare function open() }` 里的 `open`
是命名空间成员，算进来会造一堆假红。只算全局调用（排除 `x.name(`）。

变异：调 `px2vp(10)` → 红；`this.px2vp(10)`（成员调用）→ 绿（假阳性自检）。

## 验证

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0
（11 个判据文件全绿 + vitest 258/258）。cross-client-theme 13 → 14 条，harmony-system-api 4 → 5 条。
 2026-09-14 14:26:45 +08:00
JianFeeeee
43aca575c7 docs(harmony): 阶段表标状态（P2/P4 ✅、P3 主体完成、P5/P6 未做），并写明状态口径 2026-09-14 14:19:43 +08:00
JianFeeeee
2a6ad93ec0 feat(harmony): P4 —— 外观（主题 + 壁纸）跟着账号走 
服务端 2026-09-13 起就是外观的权威（账号级 `/api/v1/me/appearance`），WebUI 接好了，
**鸿蒙这边此前完全没接**。这一期补上，并把"谁覆盖谁"的规则做成可判据的纯逻辑。

## 改了什么

- `api/AppearanceApi.ets`：`GET/PUT /me/appearance`、`POST /me/appearance/image`、
  `GET /me/appearance/image`（图片带认证取回本体：不用 `?token=`，也不让 Image 直连 http）。
- `api/ApiClient.ets`：新增 `getBytes()`（按 ARRAY_BUFFER 收）—— 复用 `request<T>` 会当场炸，
  因为它假定响应是 JSON（`JSON.parse`）。
- `model/Appearance.ts`（纯逻辑，判据直接执行）：归一化 / PUT 报文 / **合并决策** /
  模糊值→系统材质档次 / 主题→系统色彩模式 / 遮罩浓度 / 状态文案。
- `common/AppearanceStore.ets`：落地副作用 —— 主题交给**系统**（`setColorMode`，不自己维护
  深色色值）、壁纸取回 `PixelMap`、缓存**按账号**分键（`appearance.<accountId>`）。
- 入口两处：`MainPage`（进主界面就应用 —— 只在设置页生效的话"一进主界面就变回去"，
  WebUI 侧踩过）与 `SettingsPage` 新增「外观」段（三档主题 + 同步状态「已同步 / 仅本机」）。

## 为什么这么写（两条最贵的规则）

1. **服务端"没有记录"时以本地为准**（`saved === false`）：服务端这时回的是一份*默认值*，
   拿它覆盖本地 = 把用户已有的主题/壁纸抹掉（WebUI 原话：每个老用户升级后第一次登录
   都会发现被重置）。正确动作是把本地那份推上去。
2. **降级必须可见**（`local-only` → 显示「仅本机」）：否则用户以为换设备也能带走。

## 判据（新增 11 条，已接进 run-all；套件 10 → 11 个判据文件）

归一化（脏值/越界/小数/NaN 退回默认）；`image` 档无图 → 退回 `none`；PUT 报文蛇形字段名；
★服务端无记录 → 以本地为准且**一个字段都不能被默认值顶掉**；服务端有记录 → 以服务端为准但
**不擦掉**本地那张服务端还没有的图；离线状态可见且三种状态文案互不相同；
★模糊值→系统材质档次（与 SDK 的 `BlurStyle` 成员**逐一比对**）；
主题→色彩模式（数值与 SDK 的 `ConfigurationConstant.ColorMode` **逐一比对**）；
★路径必须**相对基地址**（WebUI 那条"整套同步从来没生效过而单测全绿"的坑）；
缓存键**带账号**；两处入口都真的应用。

变异验证（6 种，均判红）：默认值覆盖本地 / 不管"image 档但服务端无图" / 材质档次自造名字 /
路径多写 `/api/v1` / 缓存键不带账号 / 深浅色彩模式数值写反。

## 判据抓到的两个真 bug

- `snapshotFromResponse` 在字段缺失时给 `bgDim = 0`，而 WebUI 语义是退回 12 ——
  ArkTS 反序列化把缺失字段留成**类里写的默认值**，"字段不在"与"字段是 0"分不开。
  已把默认值对齐 WebUI 的 `clamp(..., dflt)` 语义（并让 `saved` 默认 false = 安全的那一侧）。
- 主题落地按"0=浅色、1=深色"写的 `setColorMode` —— **正好反了**
  （SDK：`COLOR_MODE_DARK = 0`、`COLOR_MODE_LIGHT = 1`），选深色会切成浅色。
  靠判据去 SDK 枚举文件读数比对发现；映射已搬进纯逻辑 `colorModeValue`，
  从"某处有个 setColorMode 调用"变成"可判据的行为"。

## 验证 / 未验

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0（11 个判据文件全绿 + vitest 258/258）。
套件自检又抓到一次"判据写好没接进套件"（新文件第一版漏了 run-all），已修。

**未做**：壁纸**上传**入口（选图 → `POST /me/appearance/image`）—— 需要 picker，API 与命名已就位。
**未验**：壁纸在真机上的渲染 —— 需真机或模拟器。
 2026-09-14 14:19:26 +08:00
JianFeeeee
73f886aea5 feat(harmony): P2b+P3 —— 「收件箱」改成「通信」（内部三栏 + 徽标 + 悬浮加号），发件箱与授权栏落地 
用户：「收件发件授权改为一个导航项，通过内部导航区分，然后新建作为他们内部的一个悬浮的圆形加号」。
所以这一期不是"再加两个页面"，而是对齐信息架构。

## 鸿蒙侧

- 底部第一项 **收件箱 → 通信**（`CommPage`），内部三栏 收件箱 / 发件箱 / 授权；
  页签下划线式（不是浮动白胶囊 —— WebUI 侧用户原话「通信页面的二级页面与其他位置极其割裂」）。
- **徽标**：收件箱红（未读）、授权橙（**待决策**）、发件箱无；0 不显示，>99 写 `99+`。
  合并成一个导航项后，底部看不到"授权有 3 个在等我"，这个信息不能丢 —— 它比未读更急。
- **悬浮圆形加号**挂到通信页这一层（三个栏都要能新建）；`⚙` 也搬上来（否则切栏就够不到设置）。
- **收件箱不再混权限邮件**（`splitByPermission`），未读按筛后算 ——
  WebUI 实测过"一个会话 17 封权限邮件挤掉另外两个会话"。
- **发件箱**：`GET /me/mail/sent`，与收件箱同构（同一套折叠/行），行上主角是**收件人**；
  空态有说明（主句与 WebUI 逐字一致「暂无邮件」+ 一句"这里放什么"）。
- **授权栏**（P3 主体）：`GET /permission/pending`（不从收件箱筛）+ `POST /permission/decide`。
  拒绝**可填备注且备注真的送出**；请求**过期**时当场说清「审批不会让那次调用继续」。
- 顺手删掉死代码：收件箱里「写邮件」的 `bindSheet`（`composeVisible` 从未置 true，谁也打不开）。

## 判据（harmony-logic 19 → 28 条）

页签键/顺序从 WebUI 源码抽取比对（`uiStore.ts` 的 `CommTab` + `CommTabs.tsx` 的 `TABS`）；
页签状态机（键↔下标往返、脏键/越界/非整数 → 回收件箱）；徽标规则（数字来源、0 不显示、
99+ 上限、红/橙与 WebUI 类名对应）；分家语义（决策过的不再算待决策、空串与 null 同义）；
三栏空态互不相同且主句与 WebUI 一致；接线（三个 pane 真的渲染、加号是圆形且在通信页、
"先分家再折叠"、接口路径与决策体三字段、拒绝传备注、过期分支）。

判据抓到一个**真 bug**：`commTabFromIndex` 只判范围，`1.5` → `COMM_TABS[1.5]` = `undefined`
（表现"点哪都不亮"）。已加 `Number.isInteger`。

变异验证（六种）：授权徽标看未读 / 权限邮件不分出去 / 类型名拼错 / 决策过仍算待决策 /
收件箱不分家 / 发件箱空态去掉说明 —— 全部判红。

## 排序说明

**日历暂时没有入口**：P6 的内容（网格 + 事件读写 + 滑动翻页）还没做，
先放一个点进去空着的入口比暂时没有更糟 —— 有意排序，记在 §7.15 以免被当成漏做。

## 验证 / 未验

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0（10 个判据文件全绿 + vitest 258/258）。
**未验**：页签/徽标/悬浮加号在真机上的观感与点击 —— 需设备或模拟器（模拟器要人在命令行启动）。
 2026-09-14 14:13:45 +08:00
JianFeeeee
c6aaf8c468 refactor(harmony): 23 处废弃 API 换成 UIContext 写法（全局 promptAction.showToast 自 API 18 废弃） 
SDK 里写得很清楚：`@ohos.promptAction.d.ts` 的全局 `showToast` 标着 `@deprecated since 18`，
替代品是 `UIContext.getPromptAction()`。仓库里有 23 处这种调用（6 个页面，历史遗留）——
这一轮既然在按"用系统方案"整理鸿蒙侧，就一次扫干净，并加判据挡住回潮。

- `promptAction.showToast(...)` → `this.getUIContext().getPromptAction().showToast(...)`（23 处）
- 清掉不再需要的 `promptAction` import（多个 → 只留 `router` 等）
- 新增判据：不得再用全局写法。防的不是这次，而是**新增页面照抄旧代码**这条回退路径 ——
  它编译照样通过、只在真机上行为不同。自检同时验"认得出旧写法"与"不误伤新写法"。
- 顺带把权限徽标那条"点它弹说明"的判据改成钉**非废弃**写法（原来是 `promptAction.showToast(`）。

变异验证：把 `SettingsPage` 的一处改回全局写法 → 判红并点出文件。

验证：`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0（harmony-logic 20 条）。
 2026-09-14 14:05:35 +08:00
JianFeeeee
36f3183bba feat(harmony): 系统方案第一批 —— 表面/文字/圆角交给系统、删手写玻璃、每项一张卡；跨端判据改"意图相同" 
jianf：「鸿蒙也同步，但是鸿蒙要求用系统方案」。按 pi 对齐的形状（A/B/C + 品牌色防线）落地。

## 鸿蒙侧改了什么

- `Theme.ets` 的表面/文字/分隔/遮罩/圆角**来源换成系统**：
  `pageBg→sys.color.ohos_id_color_background`、`surface→…_list_card_bg`、
  `surfaceMuted→…_sub_background`、`border→…_list_separator`、三级文字 `→…_text_primary/secondary/tertiary`、
  `overlay→…_mask_regular`、`radiusCard/Control→sys.float.ohos_id_corner_radius_card/button`。
  于是这些维度自动跟随深色模式与无障碍设置 —— 这正是"手抄 WebUI 色值"做不到的事。
- **删掉手写玻璃** `#B8FFFFFF`/`#B80F172A`：那两个值等于"我们替系统猜了深色该怎么做"。
  换成一个**档次**声明 `navMaterial: BlurStyle = BlurStyle.COMPONENT_THICK` + 导航条上的
  `.backgroundBlurStyle(...)`；深浅两套颜色与模糊半径由系统按主题给。
  遮罩的两段式（色 + 透明度）同样删掉：拆两段本就是为了"随主题换向"，而这件事系统已经做了。
- **每项一张卡/气泡**：收件箱行、会话组头、联系人列表行改成卡片（圆角 + 卡片底色 + 行间距），
  联系人列表那条贯通分隔线删除。
- 仍然自己写的只有两类：**品牌色**（`accent = #2563EB`，跨客户端身份）与**业务语义色**
  （权限三档、预算三档 —— 系统只有 warning/alert 两个情绪色，凑不出三档，硬套会丢语义）。

## 判据：从"取值相同"改"意图相同"（两侧一起改）

- 品牌蓝**唯一保留取值钉**，并新增防线：不得退化成 `$r('sys.color.*')`
  （系统强调色随主题/厂商皮肤变，"两个客户端是同一个产品"就靠不住了）。
- 圆角/材质/遮罩：改成"WebUI 自声明令牌 + 鸿蒙来自系统 + 差异被记录"（§7.12 有意差异表）。
- 新增 A（系统拥有的维度唯一来源是 `$r('sys.*')`，且不得退回 string/number）、
  B（旧机制不得回来：`navBg*`、8 位半透明色、`rgb(`/`rgba(`、写死的 14/8）、
  C（玻璃位置必须调 `backgroundBlurStyle` 且**只许一层**）。
- pi 指出的洞已补：裸色值判据原来只扫 `#RRGGBB(AA)`，抓不到 `rgba(`/`0xRRGGBBAA` ——
  而这几种恰是"改用系统材质"时最容易混进来的形态。现在四种一起扫，且**先剥注释**
  （注释里正当地引用旧写法不该被judged红）。
- pi 的 §5 建议也已落地：新增"版本库不得跟踪缓存/构建产物"判据（`.tmp/` 那次 554 个文件的事故判据化），
  并放行 `server/internal/static/static/placeholder.html`（go:embed 落点的有意占位，删了 Go 侧编不过）。

## 变异验证（能红，且红在对的地方）

| 变异 | 结果 |
|---|---|
| 品牌蓝 → 系统强调色 | 红 3 条 |
| 手写玻璃 `navBgLight` 回来 | 红 2 条 |
| 导航改用写死半透明色、不调 `backgroundBlurStyle` | 红 2 条 |
| 卡片上再开一层模糊 | 红 1 条（"玻璃应只出现在一处，实际 2 处"） |

## 验证 / 未验

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0
（10 个判据文件全绿：跨端 13 条、系统资源名 4 条、harmony-logic 19 条… + vitest 258/258）。
**未验**：观感（卡片间距、系统材质在导航条上的实际效果、深色模式）—— 需真机/模拟器；
模拟器要人在命令行跑一次 `harmony-emu start`。`sys.*` 名字全部对着 SDK 名表核过，且判据持续盯着。
 2026-09-14 14:04:04 +08:00
JianFeeeee
4d226be056 test(harmony): 「用系统方案」的地基 —— 系统资源名与 BlurStyle 取值离线可校验（判据先于替换） 
jianf 追加要求「鸿蒙要求用系统方案」（§二·五）。难点是**没有设备**：
`$r('sys.color.写错了')` 编译期不报、只有真机运行到那一行才炸 —— 这块会变成谁都验不了的区域。

SDK 里其实带着答案：`sdk/default/openharmony/toolchains/id_defined.json` 列了全部系统资源名
及其类型（本机 API 26：7826 条，color 1059 条）；BlurStyle 取值在 `component/common.d.ts` 的
`declare enum BlurStyle` 里。两边都能离线查，所以"名字写对没有"可以变成构建期判据。

新增 `test/harmony-system-api.test.mjs`（4 条，已接进 run-all）：

1. SDK 名表/组件声明找不到时**判红并给出替代做法**（会静默跳过的判据等于没有这条判据 ——
   本仓库已栽过四次同类问题）；
2. 源码里每个 `$r('sys.<type>.<name>')` 必须存在且**类型相符**；
3. 每个 `BlurStyle.<MEMBER>` 必须在 SDK enum 里；
4. 替换计划要用的那批系统色**先核过再写代码**，并且钉住一条边界：名表里没有
   `brand`/`confirm`/`success` —— 权限三档、预算三档这些**业务语义色没有系统对应物**，
   继续用自定义令牌，不许"为了系统化"把 plan 档画成 warning 色（那是丢语义换形式）。

变异验证：拼错色名 `ohos_id_color_list_cad_bg` → 报「查无此名」并指出文件；
写错 `BlurStyle.COMPONENT_不存在` → 报出可用取值。顺带修掉解析精度问题：
早先的宽松正则把文档里的 `T`、`R` 也当成了枚举成员，现在精确到 `,`/`=` 分隔符。

验证：`npm test` 退出码 0（10 个判据文件全绿 + vitest 258/258）。
 2026-09-14 13:56:43 +08:00
JianFeeeee
5ce711fbcd test(suite): 自检 3（判据不得埋在 process.exit 之后）+ TMPDIR 固化 + API 同名不同义表 
## 自检 3（pi 提议）

自检 1/2 管"文件没接线"，管不到"检查写在 `process.exit()` 之后"—— 而那正是实际发生的
第 4 例（4 条玻璃判据被并发写入落到文件末尾）。成因是**结构性**的（并发写入总是往文件末尾
追加），所以它一定会再发生，而它下一次仍然不报错。静态扫一遍即可：`process.exit(` 之后
若再出现 `check(`，直接判红并指出文件。变异验证：往 `theme.test.mjs` 尾部追加一条 check → 判红。

## TMPDIR 固化（pi 建议，采纳）

"记得加 TMPDIR"这种约定活不过两次踩坑（hvigor、fpm 各一次）。所以不再靠口径：
- `npm run build:linux` 自带 `mkdir -p .tmp && TMPDIR=${TMPDIR:-$PWD/.tmp}`；
- `BUILD.md` 的 deb 一节写明这条前置与原因（`/tmp` 是 tmpfs、占内存、常年近满）。

## `docs/API.md`：`total` 不是总封数 + 同名不同义表

`GET /me/mail/inbox` 的 `total` 是**未读总数**（`repo.CountUnread`），不是本页/全部邮件数 ——
鸿蒙端曾因此写出「共 7 封」和「未读 7」两行自相矛盾的字。在人类接口开头加了醒目提示，
并新增一张表：`total`（未读数）/ `status`（邮件=unread|read，会话=active|archived）/
`status` 与 `is_read` 同义不同名。

## 验证

`npm test` 退出码 0：9 个判据文件全绿 + vitest 258/258（安装包已按判据要求重打，
AppImage 与 deb 均为最新）。
 2026-09-14 13:53:34 +08:00
JianFeeeee
b3f404838b feat(harmony): P2a 收尾 —— 撤掉平级「会话」tab + 权限"强制力"上界面，判据 14→19 
## 撤 tab（按 pi 的顺序：先补视图与折叠，再撤入口）

底部只剩 **收件箱 / 联系人**。「会话」不是第三个地方，而是同一批数据的两种看法：
收件箱那栏按会话折叠（组头就是会话），联系人那栏的卡片视图是会话的进度视角。
依据是"信息没丢"，并且把它做成了判据：**卡片字段集与 WebUI `WorkCard` 完全相等**
（多一个少一个都红）—— 其中 `status`(active/archived) 与 `from_agent` 参考实现也不显示；
哪天 WebUI 补上，这条会红，提醒跟着补，而不是悄悄少一块。

## 权限"强制力"上界面（WebUI 有、鸿蒙原先没有）

只显示档位会让人以为 plan 档真的管住了对方。WebUI 把说明放在 `title`（悬停提示），
**手指没有悬停** —— 所以鸿蒙拆两步：标记形状当场可辨（● 平台强制 / ◉ 覆盖不完整 /
○ 仅提示），点徽标用 toast 说完整那句话。三条纪律落进判据：

1. 档位/强制力标签与 WebUI 的 `MODE_LABEL` / `ENFORCEMENT_LABEL` **逐字一致**；
2. **说明文案从 WebUI 源码抽出字符串逐字比对**（3 档 × 3 强制力全覆盖）——
   两个客户端对同一个任务不能给两种保证；
3. 认不出的强制力归一到 `advisory`（保守方向），空/未知必须说"仅提示"。

收件箱每封邮件里没有 `permission_enforcement`（会话级字段），故那里只写中文档位 ——
凭空画一个强制力标记等于编一个"平台做到了什么"。

## 判据自己不可信的两个坑（变异测试逼出来的，各修一次）

- **断言一律读剥掉注释的源码**：把 `showToast` 注释掉，正则照样匹配 ——
  注释里有某个调用证明不了它存在。
- **"在回调里"不能靠正则窗口**：`onClick` 体掏空、或把 toast 挪到相邻的 `onHover`，
  窗口式正则都会放过。改成**括号配对**取那个 `onClick` 的 `{...}` 体，只在里面找。
  两次变异现在都判红。

`harmony-logic.test.mjs` 19 条（原 14）；变异验证：改文案 / 改档位标签 / 页签改回「会话」/
注释掉 toast / toast 挪出 onClick / toast 写死文案 → 各判红。

## 文档

§7.9 记本轮；§7.10 记 jianf 追加的「鸿蒙要求用系统方案」：同意该理解，并补上**可离线校验**的
做法 —— SDK 自带系统资源名表 `sdk/default/openharmony/toolchains/id_defined.json`（7826 条），
其中正好有 `ohos_id_color_list_card_bg`（每项一张卡的底色）、`_list_separator`、
`_text_primary/secondary/tertiary`、`_emphasize`、`_warning`、`_alert`、`_mask_*`、
`ohos_id_blur_style_component_*_color`。**没有设备**，`$r('sys.*')` 写错在运行前发现不了，
所以先立一条判据：源码里的每个 `sys.*` 名字都必须在该表里查得到，再逐处替换。
`cross-client-theme` 的三个取值钉改"意图相同"**先与 pi 对齐、两侧一起改**（他已明确要求）。

## 验证

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 9 个判据文件（background 42 /
cross-client 8 / harmony-logic 19 / nav-merge 8 / build-stamp 4 / packaging 3 …）+ vitest 258。
视觉与点击仍未验（无设备，模拟器需人在命令行启动）。
 2026-09-14 13:51:35 +08:00
JianFeeeee
dfaeab0e4d docs(harmony): 记入"必须用系统方案"的要求与 WebUI→鸿蒙的做法对应表 
用户：「鸿蒙也同步，但是鸿蒙要求用系统方案」。

已转给 dsh（线索 harmony-ui-alignment），并写进计划文档：

- **含义**：能交给系统的就交给系统 —— 用 ArkUI 的组件/材质/语义资源，
  而不是把 WebUI 那套"手写 rgba + 自定义模糊 + 自制卡片"照搬。
  系统材质会跟随深色模式、动效曲线与无障碍设置，手写的不会。
- **对应表**：`backgroundBlurStyle(BlurStyle.*)` 取代手写模糊；系统 `Tabs`/`TabBar`
  取代自制导航条；`List`/`ListItem` 取代 `Scroll`+`Column`；组件自身的
  `borderRadius`/`shadow` 取代 `.glass-card`；`$r('sys.color.*')` 语义色取代自切变量
  （**顺带解决 WebUI 那个"半深不浅"的病根**）；`animateTo`/`transition` 取代自定义动画。
- **对既有判据的影响（重要）**：`cross-client-theme.test.mjs` 钉的是三个**取值**。
  改用系统资源后它应当变红 —— 那是预期的，届时要把它从"取值相同"改成"意图相同"
  （品牌蓝仍须一致，材质与圆角允许各自跟随系统）。**必须两侧一起改**，
  避免一边改了一半。

同时提醒 dsh 两条已同步的语义：列表项与顶部都是"每项一张卡/气泡"（不是通栏）；
玻璃只出现在一层。
 2026-09-14 13:45:34 +08:00
JianFeeeee
6be5a543af test(suite): 判据总入口 run-all —— 全部跑完再算退出码，并接上两条从未跑过的判据 
## 为什么

`npm test` 是 `&&` 链：**前面红一条，后面全部不跑**。于是"只红一条"看起来像
"只有一个问题"，实际后面那些判据连跑都没跑（`packaging` 那条能发现"界面改了没重打包"的
判据，长期因此隐身）。而且这套规矩下"全绿"可信、"红"不可信。

改成 `test/run-all.mjs`（pi 建议）：每条都跑，红的收集起来最后一起报、一起退出。

- **自检 1**：清单里的文件必须存在（名字写错 = 一条判据静默消失）；
- **自检 2**：`test/` 下每个 `*.test.mjs` 都必须接进清单 —— **新增判据忘了接线直接红**。
  这条自检当场抓出 `nav-merge.test.mjs`、`build-stamp.test.mjs` 两个"写好了没接线"的文件
  （8 + 4 条判据此前从未跑过，与 `cross-client-theme` 是同一族问题）。
- 变异验证：强制 `theme.test.mjs` 判红 → 后面 5 条判据照跑，汇总如实报"红 1/9"、退出码 1。

`package.json`：`"test": "node test/run-all.mjs && vitest run"`。

## 接线后暴露的两条陈旧判据（代码没错、判据钉的是旧写法），按"钉行为不钉字面"修

1. `setViewMode(target || commTab` —— 代码后来等价改写成
   `target ?? (isComm ? commTab : modes[0])`。改成钉行为"isComm 时落到 commTab"，
   并额外要求桌面分支带 `target`（否则日历/联系人点不动）。
2. `MailView.tsx` 里 grep `glass-control` —— 授权多选胶囊已抽成共用组件 `ComposerChip`，
   样式其实是对的（neutral 未选中态就是 `glass-control`）。改成钉
   "MailView 用 ComposerChip" + "ComposerChip 用控件档"（文件会搬、组件不会）。
   两条都做了变异验证（去掉玻璃档 / 去掉 commTab 回退 → 各判红 1 条）。

## 生成产物再补一条判据（pi 提议）

用 postcss 真解析 `background-takeover.generated.css`：断言每条规则的选择器形状恰好是
`html[data-bg='on'] .bg-xxx`，且规则条数与源码扫到的清单条数一致。
只验"能解析"不够 —— 实测 postcss 对当年那份坏产物照样解析出 1 条规则（选择器前粘了
注释尾巴），所以卡形状与条数。变异：把坏头注释塞回生成产物 → 该条判红。

## BUILD.md：deb 结论撤回（不是 fpm）

`TMPDIR=/var/tmp/ebtmp` 在本沙箱建不出来；把 TMPDIR 指到工作区大盘后 deb 正常产出
（`release/agentmail-web_0.1.0_amd64.deb`，约 100MB）。日志关键行是 **`Errno::ENOSPC`**：
fpm 要把 291MB 的 `linux-unpacked` 整份复制进 TMPDIR，而本机 `/tmp` 是 9.8G tmpfs、
被 `/tmp/gocache`（4.5G）等占到 99%。所以「本机打不出 deb」是环境症状、不是工具链缺陷，
deb 不必从 `build.linux.target` 摘掉。排查命令写进 BUILD.md。

## 验证

`npm test` 退出码 0：9 个判据文件全绿（markdown-xss、narrow-layout、nav-merge 8、
theme、background 42、cross-client 8、harmony-logic 14、build-stamp 4、packaging 3）
+ vitest 258/258。鸿蒙侧 `hvigorw assembleHap` 仍 BUILD SUCCESSFUL。
 2026-09-14 13:44:00 +08:00
JianFeeeee
e0c68d8bb2 test(cross-client): 预算条三个档位的令牌也和 WebUI 对齐 + 记录模拟器权限门 
## 判据

P2a 新加的 6 个预算条令牌（`chipNeutral*` / `chipSpent*` / `chipWarn*`）此前只有鸿蒙侧
自己在用，没有任何判据钉住它们与 WebUI `BudgetChip` 的 gray-100/gray-500、
red-100/red-700、orange-100/orange-700 是**同一批值** —— 于是"鸿蒙那边自己挑了个接近的红"
没人会发现。补进 `cross-client-theme.test.mjs`（8 → 8 条，第 7 条扩了 6 个断言），
并加了反向对照（差一个色阶必须判红，实测判红）。

注意 `--c-gray-100` 等在 `.dark` 段有第二处定义，`cssVar()` 取第一处（`:root` 浅色一套），
与 `Theme.ets` 的浅色令牌对应。

## 文档

`docs/HARMONY-ALIGN-PLAN.md` §7.6：把"鸿蒙视觉/点击未验"查到根上 —— DevEco CLI 说明本机
**有**可启动的模拟器（起来后 `devecocli ui layout/click/screenshot` 能做点击级验证），
但 `harmony-emu start` 要写 `/run`、`/root/.Huawei`（工作区之外），按规矩升级重试一次后
被拒：**「权限询问无法送达：该任务链上没有人类用户」**。
即：鸿蒙的点击级验证不是"还没做"，是"当前做不到"——需要人在命令行跑一次
`harmony-emu start`。此前所有阶段只能按"逻辑有可执行判据 + 接线有判据 + 观感未验"验收。
 2026-09-14 13:38:35 +08:00
JianFeeeee
3729afd96f feat(harmony): P2a —— 收件箱按会话折叠 + 联系人页卡片视图（判据直接跑同一份逻辑） 
按 pi 的结论落地 P2a 的前一半：**先补视图与折叠，再删平级「会话」tab**（tab 本轮保留）。

## 判据怎么"点用户真正会点的那一层"

鸿蒙侧没有设备（`hdc list targets` 为空、模拟器在本机沙箱下起不来），"点一下"暂时
无法自动验。应对不是编个能过的新判据，而是把会点的那一层的内核抽成纯逻辑：
`entry/src/main/ets/model/MailGrouping.ts`（无 UI 依赖），判据用 node 的
`--experimental-strip-types` **执行同一份代码**（`test/harmony-logic.test.mjs`，14 条），
断言的是行为而不是"源码里出现过某个字符串"：

- 折叠后组头是不是**最新一封**、组内是否时间倒序、组间排序、同一时刻用 `mail_id` 倒序兜底；
- 时间解析失败**不能让顺序依赖入参**（WebUI 侧踩过的 NaN 比较坑）；
- 多账号合并下同名 `session_id` 不能被错并成一组；`session_id` 缺失时各自成组；
- 预算档位与 WebUI `BudgetChip` 完全一致（剩 0 用尽 / ≤1 将尽 / 上限 0 不显示）；
- 视图切换与卡片上"最新一封是人还是 Agent"的判据。

页面那一层另用源码判据钉"确实调了这些函数"，两层合起来覆盖「逻辑对」+「页面接上了」。
**变异验证 4 处全部判红**：去掉组内排序（2 条红）、预算阈值 `<=1` 改 `<1`、
分组键去掉账号前缀、页面不再区分单封组。

## 收件箱折叠

- 组头取组内最新一封的别名与主题，带未读数徽标与「N 封」，点它展开/收起；
- **单封不成组、平铺**（与 WebUI `isFlatGroup` 同结论：给孤立一封信套组头只是多一次点击）；
- 多账号是鸿蒙特有：分组键带账号前缀；`session_id` 缺失按 `mail:<id>` 各自成组。

## 顺带修掉一个"看起来是总数、其实是未读数"的显示

`/me/mail/inbox` 的 `total` 是 **`CountUnread`（未读总数）**，不是总封数
（`server/internal/handler/me.go`）。鸿蒙底部原写「共 N 封」⇒ 同一屏出现
「共 7 封」和「未读 7」两行自相矛盾的字。改成：未读数用服务端 `total`（权威，
原来数这一页会少报）；「共 N 封」→「已加载 N 封」；**这一页取满时如实提示
「已加载 50 封（本页上限 50，可能还有更多）」** —— 客户端没有可信总封数，
就不能把 50 封说成全部（pi 提醒的"别让只取 50 封伪装成只有这么多会话"）。
WebUI 侧不读这个字段，故只影响鸿蒙。

## 联系人页补卡片视图（撤 tab 的前置）

- 右上角切列表/卡片，标题「联系人」/「工作列表」（与 WebUI 同词），切换规则在
  `nextContactView()`；
- 卡片对应 WebUI 的 `WorkCard`：Agent 名 + 工作目录 + 未读徽标、会话别名、
  **主题当主角**、最新摘要 + 人/Agent 标记、`N 封 · 时间`、权限档位徽标、
  **往返预算条**（同一档位判据）。
- 平级「会话」tab 暂留：撤 tab 按 pi 的顺序排在后面单独一步（撤早了预算/status/from_agent 没处看）。

## 验证

- `hvigorw assembleHap` **BUILD SUCCESSFUL**（`.ts` 纯逻辑模块被 `.ets` 引用，实测可行）。
- `npm test` **退出码 0**：窄屏布局全通过、主题 30、背景 34、cross-client 8、
  harmony-logic 14、packaging 3、vitest 258/258；新判据已接进 `npm test`。
- **视觉与点击仍未验**（无设备）：展开手感、卡片间距、组头命中区没有任何自动判据
  能代替人眼 —— 交付按"结构/逻辑已验证、观感未验"写，未写成已完成。
 2026-09-14 13:36:05 +08:00
JianFeeeee
e07e3bf1a1 docs(harmony): 记入交接核对结果与 pi 回复的落地（P2a/P2b 顺序、判据、真 bug） 
第五节：收到 pi 移交信后的核对 —— 移交信里属实的两条（构建成功、cross-client 6/6 绿）、
三处纠正（P3 接口名写错、判据只挡枚举、导航差距其实是信息架构差距），
以及一条与鸿蒙无关但该让 pi 知道的（WebUI `npm test` 在 HEAD 上恒红）。

第六节：pi 回复的落地 ——
- 「会话」入口的结论：不是删功能，是联系人页的**卡片视图** + 收件箱按会话折叠，
  两件到位后再删 tab（在那之前删 = 丢信息：轮次预算 / status / from_agent 无处可看）。
  ⇒ 分期顺序改为 P2a 联系人双视图 + 收件箱折叠 → P2b 通信页签 → P3 授权 → P4 主题壁纸
  → P5 悬浮玻璃导航 → P6 日历 → 最后删 tab。
- 遮罩拆两段式；WebUI 侧不立同名令牌（立了没人用、判据只能验"它存在"，是自证）。
- 两条红判据的 patch 已落地且验证过能判红；background 判据 32 → 34 通过。
- 顺手修掉的真 bug：生成 CSS 头注释提前闭合导致 `.bg-amber-100` 那条规则被整条丢掉。
- 一条判据从来没被跑过：cross-client 判据不在 `npm test` 链里，已加进去。
- `npm test` 现在全绿（退出码 0）；deb 目标在本机打不出来（fpm），要确认是否影响交付平台。
- 仍未验的：鸿蒙侧的视觉与点击（模拟器起不来），到 P2a 必须有人眼或设备。
 2026-09-14 13:30:03 +08:00
JianFeeeee
fac30eb09c docs(harmony): 鸿蒙对齐移交 dsh（jianf 指定），计划文档记入负责人与纪律 
用户：「鸿蒙 ui 应当交给对这一块更熟悉的 dsh 负责」。

- 给 dsh 发了移交信（新线索 `harmony-ui-alignment`），交代：
  当前状态（P1 完成）、分期（P2–P6）、**判据纪律**（结构类改动必须配"点它"的判据
  —— WebUI 侧就是因此漏掉了"点日历不翻页"）、**避坑清单**（不许新写死颜色；
  这个应用没有真正的深色主题，别让单个面自己变深；玻璃只该出现一次；
  列表项每项一张卡；ArkTS 的 `arkts-no-any-unknown`/`arkts-no-standalone-this`；
  视觉不可验要如实标注）、以及两条服务端语义（已读按读者记录；
  授权被拒的备注必须送达模型）。
- `HARMONY-ALIGN-PLAN.md` 记入负责人与移交线索，并标明 P1 已完成、P2–P6 归 dsh。

分工：鸿蒙归 dsh，WebUI/Electron 与网关仍归 pi；需要两边同时改令牌之类的配合，
由 dsh 回信给我。
 2026-09-14 13:13:44 +08:00
JianFeeeee
5434bc9e4e feat(harmony): 对齐第一阶段 + 对齐计划文档（差距/分期/验收纪律） 
用户：「安排对齐」。

## 先量差距（不靠感觉）

鸿蒙侧的调色板与 WebUI **根本不同**：`#1A73E8`（Google 蓝）vs 品牌 `#2563EB`、
`#333333` vs slate-900 `#0F172A`、`#F5F7FA` vs `#F8FAFC`、`#FF4444` vs red-600…
共 217 处硬编码色值散在 7 个页面里。

功能面：鸿蒙是 收件箱/会话/联系人 三个 tab，**缺 发件箱 / 授权 / 日历 / 管理**，
也没有玻璃悬浮底栏、主题壁纸同步、Composer 共用组件。

## 第一阶段（已完成并可验收）

- `common/Theme.ets` 补齐文字/浅底/语义令牌，页面里的旧调色板**全量替换为令牌**
  （共 203 处），`hvigorw assembleHap` **BUILD SUCCESSFUL**。
- 判据：`cross-client-theme.test.mjs` 新增"鸿蒙页面里不得再出现旧调色板色值"
  （6 条全绿，含扰动自检）。这条防的是**新页面又随手写个"差不多"的颜色** ——
  漂移就是这么开始的，而此前没有任何判据会红。

## 计划文档：docs/HARMONY-ALIGN-PLAN.md

写清两件事，免得每轮重新猜"还差什么"：

- **差距表**（逐项，标出"缺页面/交互不同/观感不同"的性质）；
- **分期**：P2 发件箱（与收件箱同构，风险最低）→ P3 授权页（备注必须随决策送达模型
  —— WebUI 侧踩过这个坑）→ P4 主题/壁纸同步（服务端"无记录"时以本地为准）
  → P5 玻璃悬浮导航 → P6 日历（最大，单独排）。

## 如实说明

鸿蒙**视觉未验证**：本机 `hdc list targets` 为空、HAP 未签名 ⇒ 只能保证编译通过 +
令牌一致，观感需要设备或签名后由人眼确认。文档里也把这条写进"验收纪律"。
 2026-09-14 12:49:40 +08:00
JianFeeeee
69b1887eae chore(deploy): 清理部署残留（1.0GB）+ 把清理写成可复跑脚本 
用户说「清理一下」。实测 /opt/agentmail 累计 1.3GB：
- 网关旧二进制 33 份 × 24MB ≈ 790MB（每次 redeploy 留一份，从 09-05 起没清过）
- 插件快照：opencode 6 份 339MB、dsh 7 份 195MB、zcode 16 份、pi 9 份
- /tmp 里的部署前数据库备份 10 份（tmpfs，占内存）

新增 `deploy/prune-deploy-artifacts.sh`（可复跑，不手敲 rm），两条硬规矩：
① **保留回滚窗口**：网关留最新 3 份、每个插件留最新 3 份快照，`current` 永远保留
（发布纪律要求有回滚目标，所以不是全清）；
② ★ **绝不删正在使用的快照**：扫 /proc 的 cmdline 与 cwd，命中就跳过。

执行结果：**/opt/agentmail 1305MB → 302MB（释放 1003MB）**，7 个服务全部 active，
`current` 指向未变，`check-deploy-drift` 仍报「四个宿主都在跑当前代码」。

## 过程中的一处自纠

"在用"闸门第一版有**自我匹配**缺陷：我的测试命令把路径写在命令行里，于是扫 /proc 时
扫到了自己 ⇒ 对不存在的路径也判"在用"（与 `pkill -f` 杀掉自己那条命令同一类）。
已改为排除本进程及其祖先链，并**换正确方式重测**（路径从文件读、不进 cmdline）：
在用快照判"在用" ✓、不存在的路径不误判 ✓ —— 判据两侧都验过才敢执行删除。

文档：docs/DEV-TOOLING.md 记了用法与那两条规矩。
 2026-09-14 08:43:54 +08:00
JianFeeeee
1619399470 fix(gateway): 已读改为**按读者**记录 —— 修掉"别人读掉，我就看不到" 
用户报的那句 dsh 自述（"收件箱列表未展示它，直接按 mail_id 读取成功"）不是插件问题，
是网关的已读模型：`mails.status` 是**邮件级**的一个列，任何收件人读掉，对所有收件人
（含抄送）都变成已读 —— 全库没有任何按人记录已读的表，我查过 schema 与迁移文件。

实测复现（两个人类用户、一封共享邮件，排除 Agent 干扰）：
  gui-lab 读掉 → gui-lab 未读清空（应当）→ **jianf 的未读也没了**（错误）
  而 jianf 的 `status=all` 里仍在 ⇒ 是已读语义问题，不是送达问题。
线上那封信正是这个形状：`jianf → dsh` 抄送 pi/opencode/zcode/homeagent，**pi 最先
回复（= 它读过了）** ⇒ 这封对 dsh 也变成 read ⇒ dsh 的 `read_inbox`（默认 unread）
返回空 ⇒ 它只能按提示词里的 mail_id 兜。

三个受害面：① Agent 的 `read_inbox` 拿不到信（换一个不兜的模型就变成"正文是空的"）；
② 人类的未读被抄送的 Agent 读掉；③ ★ 桥的补投判据 `pending_mails = CountUnread` 归零
⇒ SSE 漏过或进程重启时那封信**不再补投**（静默丢信）。

改动：
- 新表 `mail_reads(mail_id, reader_name, read_at)`，未读 = 这张表里没有该读者的行。
- 判据收敛到一处（repo 的 `unreadFor` / `readStateFor`），六处读写点全部改用它：
  单封已读、批量标已读、权限决策（只记**决策人**）、`ListInbox`（过滤 + 返回的
  status 都按读者算）、`CountUnread`、`CountUnreadInSession`、会话列表未读计数。
- 一次性回填补历史：`mails.status='read'` 记到**主收件人**名下（唯一可用的推断），
  用 `app_meta` 里的标记守住 —— 不能每次启动都跑，那会把"某抄送方读过"按主收件人
  写成已读，正是这次要修的错。实测：`done rows=207`。
- `mails.status` 保留为"有人读过 / 已归档"的冗余列，**不再是判据**。

★ 顺带挖出并修掉一个真 bug：`CountUnreadInSession` 用的是 PG 专有语法
（`cc_list @> $3::jsonb`），而线上是 SQLite ⇒ 那条 SQL **语法错误**
（`unrecognized token: "@"`），调用点又是 `unread, _ :=`（吞错）⇒
**会话列表的未读数一直是 0**。现已改用仓库既有的方言助手 `db.CCHas`。
实测：happy-pixel 会话现在 `unread_count=5`（修复前恒 0）。

判据：新增 `internal/repo/readstate_test.go`（5 条：按读者未读、会话内计数、
批量标已读、归档对所有人可见性、权限决策只记决策人）。
**扰动验证**：把 `unreadFor` 退回旧语义 → 4 条判据全红；恢复 → 绿。
全量 server 10 包全绿。文档同步：API.md 的「标记已读」段 + PLUGIN-CONTRACT 的 T-1.4。

线上复验：同一受控实验 —— gui-lab 读掉后，**jianf 的未读仍在且 status=unread** ✅
 2026-09-13 14:25:44 +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
33e44074e7 fix(tooling): pi-lens 的项目防护其实一直没生效（JSON 里带注释 → 整份被忽略） 
## 现场

跑 `pi --help` 时有一行不起眼的警告：

    [pi-lens] ignoring invalid project config …/.pi-lens.json:
    Expected double-quoted property name in JSON at position 60

`.pi-lens.json` 是 `d50c55d` 专门加的项目级防护（关掉 pi-lens 的格式化与
autofix），但它的说明写成了 `//` 注释 —— 读 pi-lens 的源码确认：

    PROJECT_CONFIG_BASENAMES = ['.pi-lens.json', 'pi-lens.json'];  // 没有 .jsonc
    raw = JSON.parse(text);                                        // 不去注释
    // 解析失败 → 打一行警告，然后**整份忽略**

所以「已经关掉了」这个结论是**错的**，防护从落地那天起就没生效过。
而它要防的是两次已发生的真实损失：一次是 `19a3161` 把约 7000 行 biome 重排
扫进功能提交（无法审查、还掩盖了一处删行），一次是 prettier 改坏
`client/electron/index.html` 并打破 `test/theme.test.mjs` 的两条断言。

失败方式是静默的：进程照常跑，只有启动时一行警告 —— 而我正是在
`pi --help` 的输出里才看见它。

## 修

- `.pi-lens.json` 改为**严格 JSON**（只有 `$schema` / `format` / `autofix`；
  `$comment` 也不行 —— pi-lens 校验未知键，会为它刷一条
  「unknown key … ignored」的警告，而噪声会训练人忽略告警）。
- 理由移到 `docs/DEV-TOOLING.md`（含 pi-lens 的源码依据、两次事故、
  以及「为什么不是把格式化器配成本仓库风格」——试过，仍改 17 个文件）。
- `biome.jsonc`（允许注释）里加指针：它只是两道闸中的一道，真正的总开关是
  `.pi-lens.json`，而那份**必须是严格 JSON**。
- 验证：`pi --help` 现在 **0 行** pi-lens 输出；反向对照（故意塞回一行注释）
  会重新出现 `ignoring invalid project config`。

## 顺带：仓库里有一个活的凭据

`scripts/verify-l2.sh` 把**管理员 user key 硬编码**在文件里（`1759666` 起就在
git 历史里）。实测它**仍然有效**（`/auth/me` → 200），属于用户 `jianf`。

- 已改为从 `VERIFY_L2_TOKEN` 或 `/root/gotmp/verify-l2-token.txt`（600）读取，
  两者都没有时**报错退出**（反向对照验过：EXIT=2，不静默跑）；
- 跑通一次确认可用（6 通过 0 失败）。

**但删掉当前这行不能把它从历史里拿掉** —— 要真正作废必须轮换那把 key。
这需要你定（它是你账号的密钥，可能还有别的工具在用），见提交后的说明。
 2026-09-12 23:49:55 +08:00
JianFeeeee
a60ab66a40 refactor(plugins): 删掉「摆了一套权限规则却没人调用、且形状没人能消费」的死代码 
# 问题

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

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

比 9.17（给了按钮不实现）更深一层：那只是没实现，这个是**看起来像实现**。

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

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

  SessionCreateData.body 只有 { parentID, title }；query 只有 { directory }
      → 会话级根本没有 permission，也没有 agent
  permission 只存在于 Config / AgentConfig，且是 map 形状
      → { edit, bash, webfetch, doom_loop, external_directory } → ask|allow|deny
  Permission 事件（permission.updated 的 properties）没有 action 字段
      → { id, type, pattern?, sessionID, messageID, callID?, title, metadata, time }

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

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

# 为什么 opencode 的 per-session 强制做不到（如实说明）

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

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

# 改动

- 删除 `opencodePermissions` 及其 doc 注释、`OpencodePermissionRule` 接口声明
  （三份共用库同时改，改后 md5 仍逐字节相同）
- 删除 opencode/index.js 里那行未使用的 import
- 删除 9 条针对该函数的断言（三桥各 9 条）
- **6 条实测结论没有丢** —— 搬进 `docs/PLUGIN-CONTRACT.md` 新增的 §9.18，
  连同上面那三条类型证据与「为什么 per-session 做不到」

删掉而非保留，是因为留下的就是陷阱：函数存在、注释写着「实测过」、
测试还全绿，唯一缺的是调用点 —— 下一个人会以为档位在这里被强制。

# 验证

- `deploy/check-shared-libs.sh` → 共用模块三方同源
- 三桥 `npm test` 全绿：pi 400 / dsh 360 / opencode 311，0 失败
  （删除前 pi 409 / opencode 320，各 −9 即被删断言；dsh 另有并发提交新增测试，
  净 −9 后为 360）
- `node --check` 四个改动文件全过；ESM 动态 import 该 lib 成功，
  导出里已无 `opencodePermissions`，index.js 只引用仍存在的符号
- 本改动不影响运行时行为（删的是一个从未执行的函数与一个未使用的 import）
 2026-09-11 23:59:24 +08:00
JianFeeeee
f9d757b5e5 chore: directory migration - gateway→server, web→client/electron 2026-09-08 19:16:35 +08:00
JianFeeeee
83d3c2a51a docs: HMS-PUSH-PLAN.md 华为统一推送服务端集成方案 2026-09-07 17:00:06 +08:00
JianFeeeee
7278fcdf9a docs: MULTI-ACCOUNT-PLAN.md 多账号架构方案 v0.1（单一事实源） 
dsh+pi 共同遵守的多账号设计文档：
- 账号数据结构（displayName/gateway/token/username）
- 聚合/单独视图交互（账号选择器）
- 发信账号选择
- SSE 每账号一连接架构
- 配置页 UI
- Gateway API 映射
- 安全要点（已审计）
 2026-09-07 16:57:55 +08:00
JianFeeeee
bf32369ebd docs/API.md: 补权限档位端点与字段（dsh 反馈的文档缺口） 
dsh 在鸿蒙计划反馈中指出 API.md 未收录权限档位相关：
- PUT /sessions/{id}/permission 端点
- GET /sessions/{id} 返回的 permission_mode/permission_enforcement
- 发信请求体的 permission_mode 字段
- new_mail SSE 事件的档位字段

补：
- 会话端点清单加 PUT /sessions/{id}/permission
- 会话对象字段表（permission_mode 三档 + permission_enforcement native/advisory）
- 新增「权限档位」节：三档语义、新建/续谈均可设定、Agent 继承约束
- 发信请求体 JSON 示例加 permission_mode + 说明（两种情形都生效）
- new_mail SSE payload 示例补档位字段（含 from_human/to_human/in_reply_to）

注：后端只有 PUT 没有 GET /sessions/{id}/permission，文档已注明读取走会话详情。
 2026-09-07 07:32:00 +08:00
dsh
314c3224ce docs: 鸿蒙计划补权限档位(plan/workspace/full)与SSE档位字段（据 pi API 梳理） 2026-09-07 07:28:39 +08:00
dsh
9cdf4b9e3f docs: 鸿蒙客户端(ArkUI)构筑计划 GUI-PLAN-HARMONY.md 2026-09-07 07:26:04 +08:00
JianFeeeee
da67aae2dd PLAN.md: P5 前端档位选择器完成 2026-09-06 21:25:12 +08:00
JianFeeeee
36f1099c02 PLAN.md: L5 补充实测（dsh 写文件真拦，pi workspace 一律问人，homeagent advisory 不遵守） 2026-09-06 20:44:46 +08:00
JianFeeeee
b67c33c352 PLAN.md: L5 实测结果修正（opencode = advisory 自愿遵守，dsh = Landlock partial） 2026-09-06 20:40:44 +08:00
JianFeeeee
fc958f8809 opencode: 修正权限档位接线——session.create 不支持 permission，改用提示词 advisory 
根因：opencode 1.18.29 的 session.create API 只接受 {parentID, title} + query.directory，
permission 字段被静默丢弃（SDK types.gen.d.ts 证实 SessionCreateData 无此字段）。
之前传入的规则不报错也不生效，plan 档下 bash 仍执行。

修复：
- 移除 session.create({permission: ...}) 调用（已被 API 忽略）
- 在 deliverMail 的 prompt 构造里注入 permBriefing（modeBriefing advisory 路径）
- permBriefing 与 homeagent 同理：如实说「这个平台无法强制这一档」
- 修正 catch (e: any) 语法错误（.js 文件不支持 TS 类型注解）
- 补充 import modeBriefing

L5 实测：opencode plan 档回信「由于当前权限档位为 plan（只读），我无法直接执行 bash 命令」
模型自愿遵守 advisory 约束（行为正确，但非平台强制）
 2026-09-06 20:38:33 +08:00
JianFeeeee
b76d0d6c96 PLAN.md: P4 四桥档位接线全部完成（dsh/opencode/pi/homeagent） 2026-09-06 19:26:17 +08:00
JianFeeeee
16df8f44c9 PLAN.md: L2 (P1/P2/P3) 权限档位传播链路 + PUT 端点 + 24 例测试全部完成 2026-09-06 17:36:59 +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
8e501f041e pi 桥改为工作进程池 + homeagent 落盘投递账本 
## pi 桥：模型工作下到子进程（并发模型重构）

主进程原来自己跑模型，而 pi 的会话装载是同步的：`SessionManager.open()` 走
`openSync` + `readSync` 循环把整个 `.jsonl` 读进内存并逐行 JSON.parse。实测本机
最大那条会话 23MB，`open` 一次**阻塞事件循环 118ms**；模型跑起来后 SDK 内部还有
更多同步工作。SSE 读循环在那期间完全停住 → 后续邮件卡在 TCP 缓冲区 → 久到
Gateway 认为连接死了 → 重连 → 重放。

上一轮我在几个调用点前加 `setImmediate` 是无效的仪式（让出一次之后同步工作照样
占满线程），已回退。这一轮把模型工作整体搬进子进程：实测同样的活在 fork 出的
子进程里跑，主进程事件循环阻塞 **0ms**。

- 新增 `src/worker.mjs`：一封邮件一个进程，跑完就退。权限询问期间的挂起只影响
  那一个 worker（原来 `await new Promise(...)` 等人决策，整座桥不再收信）。
- 新增 `src/pool.mjs`：**不同会话并发**（上限 3，每个 worker 约 140MB RSS）、
  **同一会话严格串行**（pi 假定「一文件一持有者」，两个进程同时装载同一条会话
  文件会让各自的内存索引看不见对方追加的行 → 会话树分叉）、满载排队不丢邮件、
  硬超时 SIGKILL 回收卡死进程。
- `src/index.mjs` 只剩 I/O 与调度：SSE、心跳、去重、分派。
- 选进程而不是 `worker_threads`：模型会跑 bash/write/edit，一次 OOM 不该带走
  整座桥。两者实测都能建起 AgentSession，但线程与主线程共享堆和生命周期。
- 「接管会话短暂持有」那套机制（adopted / adoptTimers / releaseAdopted + 兜底
  计时器）整个删掉 —— worker 退出**就是**释放，且普通会话与接管会话一视同仁。
- 轮次超时 60s → 10 分钟：60s 那个数字是「主进程要腾出手收下一封」的产物，
  worker 没有这个理由，等真结论更准（带工具调用的一轮跑几分钟很正常）。
- IPC 只传路径与标量（sessionFile / cwd / grants / 命名指纹）—— AgentSession
  跨不了进程边界，worker 每次从 sessionFile 重新装载。

`test/pool.test.mjs` +19 例，真 fork 子进程、用桩 worker（不装 SDK）跑毫秒级：
并发上限、同会话串行、不同会话真并发（判据是两个进程的心跳交错，不是 running
map 里有两个条目）、sessionFile/grants/命名指纹跨 worker 传递、config() 每次重取、
硬超时回收、权限决策路由、决策原文透传、worker 退出后清路由、mailDrivenIDs、
kind 透传、stop 先发 shutdown 再杀。跑过三组负向对照确认用例真能抓回归：
拆掉串行守卫 / 不传 sessionFile+grants / 硬超时不杀，对应用例分别失败。

## homeagent：投递去重必须落盘

用户报的重复投递不是上一轮那个 bug。两段提示词的措辞差异指出了来源：
SSE 那段写「你把本轮工作做完」，补投那段写「你把结论说出来就行」。

`deliveredMails` 是进程内的 map，而 homeagent 的插件跑在**子进程**里：

  1. 18:59:38 邮件落库，旧插件进程的 SSE 收到，注入第一次
  2. 同一秒 homed 被重启，那一轮被掐断（`context canceled`）
  3. 18:59:45 新进程起来，`deliveredMails` 是空的
  4. 心跳报 `pending_mails: 1`（第一轮没跑完 → read_inbox 没执行 → 仍未读）
     → catchUp 注入第二次

**不能只记「投过没有」**：那会把「重复」换成「丢件」—— 第 2 步里发件人没收到
回信，而记录说「已投过」→ 永远跳过。丢件比重复严重，重复至少人能看出来。

新增 `ledger.go`：JSONL 账本记两个状态。`completed` 才跳过；`delivered` 但未
`completed` 的仍然重投，但提示词前面插一段说明「上一轮被中断，别把同一件事做
两次」。落在 SDK 的 `Settings().DataDir()`；拿不到时退回 key 文件目录；目录不可
写时退化为纯内存（不比修复前差，也不该让插件起不来）。

- 判定与记录在同一把锁里：SSE 与 catchUp 两个 goroutine 的竞态
- 每行写完 fsync：这个文件的全部意义就是「进程死了之后还算数」
- 坏行跳过而不是报错退出（崩溃时最后一行可能写残）→ 那封退化为重投，安全
- 14 天保留期；过期过半时「临时文件 + rename」压实
- `shortID()` 替代 `id[:8]`：日志不该有能力 panic 掉投递协程

`ledger_test.go` +14 例，含两组负向对照（只记「投过」→ 丢件用例失败；不读账本
→ 跨进程用例失败）。

## 契约文档

`B-7.7`（MUST）：子进程形式的插件去重必须落盘且区分「投过」与「跑完」，含事故
时序、两状态表、何时标 completed。已知取舍那节标注投递账本是唯一必须落盘的状态。
验收清单加「模型跑到一半重启宿主」一项。

## 生产验证

- pi 三封 → 三条会话：三个 worker PID 并存，回信「收到 1/2/3」各落自己线索
- pi 同一会话两封：严格串行（收到A 19:26:39 → 收到B 19:26:48，全程单 worker）
- pi 主进程事件循环阻塞 1ms（旧版单进程 open 23MB 一次就 118ms）
- homeagent 正常一封：账本 `c:false` → `c:true`，一封回信
- homeagent 处理中重启：日志「上一轮被中断，带说明重投」，**只有一封 Re:**
- homeagent 再次重启：账本 2 条 completed，不再投递，会话邮件数不变
- gateway 7 包 / web 176+26 / pi 269 / dsh 219 / opencode 201 / homeagent 14
 2026-09-04 20:33:44 +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
e4052f8e84 docs: B-8 在 HomeAgent 上是 N/A（平台无审批环节），补齐平台矩阵第四列 
B-8 的 homeagent 那格一直标着「❌ 要先摸清 homed approval API」。
查清了：**那个 API 不存在，而且不该存在。**

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

前置条件是「平台本来就要问人」。另三个平台各有一个现成的审批环节
（opencode `permission.ask` / DSH `approval/request` / pi `tool_call`），
桥做的只是把它从本地 TUI 改道到邮件通道 —— 没有发明审批协议。

HomeAgent 的核心是纯思维核：本身无对外交互能力（全部能力来自插件），
也没有会话这一层（单事件循环）。它不问人，工具调用直接执行。

它确实有 `StageBeforeToolcall` 可以拦下调用（`process.go:273`，插件给
`ctx.Response` 赋值即拒绝，核心把「工具 X 已被插件拒绝」喂回模型）。
但那是「插件可以否决」而非「平台在征求同意」：没有待批准的请求、
没有选项、也没有等人的语义。

所以 B-8 是 N/A 而不是待办。硬补等于给平台加它本来没有的能力 ——
要自己划高风险工具白名单、自己定义超时与 fail closed、自己决定人不在时
怎么办，那些是产品决策不是契约合规。

顺带记下一个需要知道的事实：homeagent 的工具全部无条件执行（含 cmd_run），
接入邮件之后任何能给它发信的人或 Agent 都能间接触发，中间没有人类确认。
另三条链至少有 409 兜底，这条没有 —— 因为它根本不发起询问。
这不是缺陷而是那个平台的信任模型（homed 跑在用户自己机器上，默认完整权限），
记下来是为了让「谁能给 homeagent 发信」被当作访问控制来对待。

平台差异对照表补齐 HomeAgent 一列（14 行）。它是四平台里唯一**不需要**
为每封邮件开平台侧会话的：没有会话概念，所有邮件注入同一事件循环，
靠 output_send__agentmail 输出通道送回复。
 2026-09-04 09:11:43 +08:00
JianFeeeee
bca50b80c6 docs: 日历子系统 + 寻址发现工具组 + 权限死锁的排查记录 
PHASE7-REMAINING 新增日历一节：三层分离的理由、修掉的六个真问题
（含每一个的现场取证与判据）、前端三个易错点、验证清单、未做的缺口。

写成「可核对的规格 + 踩坑理由」而不是叙事：这些 bug 的共同点是
**不报错**（模板烤死时间、{time} 渲染成 UTC、每 tick 重发、附件从未落盘、
TRIGGER 往返断开、PG schema 缺表），下一个人只有知道判据才能避开。

README 把插件工具表从「六个」更新到十一个（现在 homeagent 是十五个），
并说明寻址发现那一组解决的是**猜地址** —— 生产上真的发生过一个 Agent
猜了 opencode@/home，投递成功但那不是它的工作目录，那封邮件静默变成了
一条平行会话的开端。

PLUGIN-CONTRACT 补 B-8（权限询问转邮件）的判据表与三平台差异。
 2026-09-04 06:30:56 +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