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

28 Commits

Author SHA1 Message Date
JianFeeeee
de6b91516a feat(默认会话): 非邮件轮次用 /tmp 默认会话作合法 session_id —— 配套 15e4fe9 的收严 
`15e4fe9` 让未声明 session_id 的读信一律 403，而 homeagent 的工具**全局可调** ⇒
对话里自主调 read_mail/read_thread 时 `currentSessionID` 为空 ⇒ 403。
不能因此让「非邮件轮次读信」这个能力消失（它是 10-01 那个 read_inbox 修复的
用户可见部分），所以给它一个合法声明。

## 关键约束：workspace 能回落 cwd，session_id 不能

`session_id` 是 AgentMail 会话的 UUID，进程 cwd 给不出它 ⇒ 只能问服务端。
落点选 `/tmp`：非邮件轮次没有真实工作目录，而 /tmp 是中性落点（不属于任何真实
项目，不会把项目邮件混进来），且满足 `UnreadWorkspaces` 的 `workspace LIKE '/%'`
（能被寻址补投）。

## 服务端：`GET /api/v1/agent/session/default`

**复用**已有的默认会话语义（`FindOrCreateDefaultSession`，8 个测试覆盖），
只把它开放成可查询形状 —— 不新造概念。

★ 第一版调 `FindOrCreateDefaultSessionCreated`，判据当场报**每次都新建**
（连问两次得到两个不同 UUID）。根因：那个函数的复用条件含
`EXISTS (SELECT 1 FROM mails …)`，空会话不满足 ⇒ 永远「没找到可复用」。
改「先查后建」仍不够。想深一层：**根本不该建** —— 非邮件轮次若 `name@/tmp`
一封都没通过，收件箱本来就该是空的，不需要一条 id 才能表达「空」。
⇒ 改成**纯只读**：没通信过就返回 `session_id: null`。
GET 有副作用是坏味道，它会被桥每轮调一次。

同时把匹配 SQL 抽成 `defaultSessionMatchSQL` 共享常量：`FindExisting` 与
`FindOrCreate` 必须给出**同一个**答案，否则「查到的默认会话」与「发信落进去的
会话」会静默分叉（各写一份 SQL 的话，改一边不会红）。

## 桥（homeagent）：effectiveSessionID = 信封 → 默认会话

⚠ 取值函数**不发请求**。我第一版把 HTTP 塞进 `effectiveSessionID`，
`&Plugin{}` 构造的测试当场 nil panic，且 scopeQuery 变成「拼 URL 时顺带发请求」。
IO 移到装配期 `register()` 里的 `ensureDefaultSession()`。

⚠ `client == nil` 时**不标记已问** —— 那不是「答案是空」而是「还没资格问」，
标了会永久缓存空值。而 register() 里就会调它，真的会在插件加载阶段崩。

## 判据

服务端 6 格（含★「不是万能钥匙」：拿默认会话 id 去读别人的会话仍须 403 ——
少了这格，这个端点就是「声明一个合法会话然后读遍全场」的后门）。
homeagent 6 格。
三个变异各红 1 格：退回旧的整体放弃 / 未就绪也标记 / 默认落点与服务端不一致。

## 未改：pi / dsh / opencode

实测它们的裸奔已停止（pi 自 Sep 26、opencode 自 Sep 28，`[agent-scope]` 日志归零），
`getMailSessionId` 由 worker 闭包注入且只有一处装配点。dsh 待单独核。
 2026-10-02 01:09:19 +08:00
JianFeeeee
f86f08c7dc fix(桥): read_inbox 在非邮件驱动会话上也得带 workspace —— homeagent 与 opencode 两处 
同一个形状的缺陷在两个桥上，**根因都是架构差异，不是"忘了写"**：
pi/opencode/dsh 的工具**只在邮件驱动回合里装配** ⇒ workspace 永远有值；
homeagent 的 15 个工具是 `registerTool` **全局注册**（webui/a2a/对话都能调），
opencode 是 `export default` 全局插件 ⇒ 非邮件驱动会话上查不到工作区
⇒ 拼不出 `&workspace=` ⇒ 服务端 400。

实测：homeagent 2026-10-01 14:32:26 一次真实失败，近 24h **3 失败 / 0 成功**。
opencode 那次是**静默**失败（工具返回错误文本，模型照走）⇒ 线上 0 次报错
不代表没问题，是靠两桥的架构差异推出来的，不是靠日志。

修法不同（各自的可用信号不同）：
- homeagent: `effectiveWorkspace()` = 信封 → **回落到进程 cwd**。
  cwd 是对的默认值：homed 按调用上下文以子进程拉起插件，实测对话中那个桥
  cwd=/home/program/agentmail，而从插件目录拉起的那个是 plugins/...。
  ⚠ 只是默认不是保证（库里 17 个工作区），收窄语义不变。
- opencode: handler 拿得到 `context.sessionID`，而 opencode `Session`
  **带 directory**（types.gen.d.ts 的 `export type Session` 可见），
  且 `client.session.get` 本桥已在用 ⇒ 现场问权威值，不猜也不另存一份。
  readInboxTool 是模块级常量，故新增 hostClient 在 init 时捕获。

部署：homeagent 首次走正规 hmap 路径（解包 + cp manifest + install -m 0755，
skill §5 四步全绿）。判据：homeagent 新增 4 格 + 修正 3 条失效的既有断言
（补 cwd 回落使其旧前提失效：整串相等 vs 分片包含、"q[1:] 不能有 &" vs 合法分隔符、
"没工作区就不带"vs"带的是不是真值"——判据失败时先判断是判据错了还是行为错了）。
opencode 新增 5 格。全量：server 全绿 + race 干净；opencode 桥 359/359。

端到端：homeagent webui 一轮 `tool read_inbox result: {"content":[{"text":"收件箱为空。"
（修复前是 400）；opencode 两条非邮件驱动会话均 status: completed，
"空"是正确的收窄结果（74 封全是 read/archived，unread=0），近 10 分钟 0 次 400。
 2026-10-01 19:41:16 +08:00
dsh
60012ede3d fix(homeagent桥): ★ read_thread 不传 offset 时 URL 拼成 /thread&session_id ⇒ 100% 404 
症状：模型默认不传 offset ⇒ offset="" ⇒ scopeQuery("&") 拼出
  /agent/mail/{id}/thread&session_id=…
`&` 被当成路径的一部分，网关路由 /agent/mail/{id}/thread 匹配不上 ⇒ 404。

根因：2a5e3d7（09-14「四家桥的读端点也带上会话收窄」）只给 read_thread 拼错了
分隔符；其余四家桥走 `path.includes('?') ? '&' : '?'`，没踩到。

★ 网关日志里的单字符对照实验（09-30 10:14:47，同一 mail_id、同一 session_id 值、
相隔 0 秒的两条请求，只差分隔符）：
  /thread?session_id=x  -> 401  86B  ← 已路由进 handler，只是鉴权没过
  /thread&session_id=x  -> 404  19B  ← 从未匹配到路由
同一 session_id、同样缺 workspace，唯一变量是 ? / &。09-29 的三次 404
（20:21:12 / 20:58:14 / 21:44:42）URL 形态一致，且**不伴随** [agent-scope]
「没声明 session_id」告警 ⇒ session_id 确实带上了，问题在分隔符。

为什么「同一二进制 09-29 全 404、09-30 全成功」不是矛盾：该缺陷只在
currentSessionID != ""（即正在处理某轮邮件）时触发。09-30 那三次读发生在回合外，
scopeQuery 返回空串、不追加分隔符 ⇒ 路径正确 ⇒ 200（网关日志有 [agent-scope]
「旧语义放行」告警为证）。所以它恰好只在**邮件回合内**发作 —— 即需要读线索
才能回信的那条路径。

修法：sep := "?" ; if offset != "" { sep = "&" }。
不能只把 "&" 改成 "?" —— offset 自带 "?offset=%d"，一刀切会把分页那条从对的改错。
两条路径都在 plugin_read_thread_path_test.go 里逐字断言路径 == 网关路由。

自证边界（改完仍无法自证的部分）：单测证明的是**拼出的 URL 落在网关路由上**，
不等于已在 homeagent 部署的那份 plugin.bin 上端到端复现过。原守卫测试
（plugin_read_scope_test.go）断言的是「URL 里有没有 session_id=」，缺陷 URL 里
恰恰有 ⇒ 绿着放行；新测试把判据落在 u.Path 上。
 2026-09-30 10:40:44 +08:00
JianFeeeee
83a5787ac9 fix(homeagent桥): SDK 钉子指向 v1.3.0，而构建机指针已是 v1.4.0 
## 现象

`go test ./...`（在该包内）红：

    --- FAIL: TestSDKPinMatchesBuildMachinePointer
        go.mod 的 SDK 钉子偏离了构建机指针：
          钉子: /root/.homeagent/hmapdev/sdk/v1.3.0
          指针: /root/.homeagent/hmapdev/sdk/v1.4.0
        后果不是「编译不过」，是**照原样重编会再造一个旧版本插件**：
        内核升级后装上去启动即崩、崩溃循环、要人介入（2026-09-14 的形状）。

## 为什么这个包的红一直没被发现

`plugins/homeagent-mail-bridge/` 有**独立 go.mod** ⇒ 不在主 module 内
⇒ 仓库根的 `cd server && go test ./...` **覆盖不到它**。

（主 module 覆盖率实测：`go list ./... | grep -c homeagent` → **0**。）

## 改法

`go.mod` 的 replace 改成指针指向的目录（判据给出的改法，一行），
然后按 `build.sh` 重编并部署。

## 验证（判据自己写明的口径：不是版本号相等，是建链成功）

- 判据：✅ 过
- 重编：`hmapdev build` 成功，`SDK=v1.4.0 hash=ba5cece0ca8a52ad version=1.4.0`
- 部署：`install -m 0755` 原子替换 + 留档 `plugin.bin.bak-20260928-093600`
- **建链**：内核日志 `homeagent-mail-bridge` 经 proc 通道加载、
  `protocol=2 sdk=1.4.0`、工具全部注册（`loaded: homeagent-mail-bridge`）
- **端到端**：真发一封 `.new` → 20s 内回信「SDK v1.4.0 重建后正常」

★ 顺带记一条：build.sh 自己注明 `go build ./...` 会报
  `function main is undeclared` —— 那是正常的（入口由 hmapdev 包装），
  真正的编译在 hmapdev 那一步。拿 `go build` 当"能不能编"的判据会误报。
 2026-09-28 09:40:34 +08:00
JianFeeeee
4175c0ba45 fix(bridge): ★ 投递即标已读 —— 修「桥重启 → 重投 → 回声」 
用户 2026-09-26 原话：
  「我都不记得我下达这个任务，是你的桥自动重投存在 bug」
  「就是你的错误的重投机制造成了回声」

# 我上一轮把因果搞反了

我先认定是「两个 Agent 自发辩论」，还为此写了第三道防线（数 Agent↔Agent
连续往返）。**方向错了** —— 是**桥把同一封信反复投递**，每次投递起一个
worker 回信，回信又触发下一轮。模型在做什么？它在回答一封被重复投进来的
旧信。用户根本不知道有这回事。

# 根因：deliveredMails 只在内存，库里的 status 从没被写

投递路径（SSE `new_mail` / 心跳补投 / 决策回执）只做两件事：起 worker、
把 id 记进 `deliveredMails`。**没有任何一处调 `/mail/read`** —— 桥里唯一
那处标已读在 `read_inbox` 工具里，要等模型自己去读收件箱。

于是每封被投递的信**永远是 unread**；而 `catchUp` 按 `status=unread` 拉
⇒ 桥一重启（**每次部署都会**），积压的"未读"被当成离线漏投**再投一遍**。

# 实证（不是推断）

· 5 个 mail_id 各出现在**两条不同 pi 会话**里：
    f06129f4 → 04:54:45 投进 01a0a2bd
             → 08:01:20 投进 01a0daf0
  （而那封信库里已有 1 封回信 —— 它早就被处理过）
· 同一封信被投两次 ⇒ 两个 worker 各回一封 ⇒ 对方收到两封 ⇒ 各回两封…
· pi 收件箱 287 封 unread 中 **187 封已经回过信了**
  （`EXISTS(SELECT 1 FROM mails r WHERE r.parent_mail_id=m.mail_id)`）
· 两条会话各烧到 463 / 268 封
· 桥侧：同一邮件会话 id 前缀 `01a0a2bd` 出现在 **4 个** pi 会话文件里
  （投了两次 + 别的历史残留）

# 修法：内存与库必须同时写

`deliveredMails` 是**内存**集合，重启即丢；数据库的 status 才是跨重启的
"我接管过了"记录。两者只写其一 ⇒ 口径不一致 ⇒ 重投。

新增 `markDelivered(id)`：**凡是标记"我接管了这封"的地方都走它**
（SSE / 补投 / 决策回执三个投递点），同时写内存与库。漏一处就是一条重投
路径 —— 这正是缺陷的形状（四处各自 add，没有一处标已读）。

标已读只改 status，不改内容、不删行；`read_inbox` 传 `status=all` 照常可见。
而"已交给一个 worker 处理"正是那封信此刻的真实状态 —— 库里本来就该记这件事，
而不是"模型有没有顺手调过 read_inbox"。

# 四个桥：三个有缺陷，第四个早已修过

| 桥 | 投递标已读 | 说明 |
| --- | --- | --- |
| pi | ✗ → ✓ | 三处 add 都不标 |
| opencode | ✗ → ✓ | 同上 |
| dsh | ✗ → ✓ | 同上 |
| **homeagent** | **✓ 早有** | `ledger` 落盘，跨进程 |

homeagent 不用这个修法：它的 `ledger` 记 `delivered`/`completed` 两个状态，
只有 `completed` 才跳过（投过但被中断的**仍然重投**并带说明）—— 那份设计的
注释里就写着 18:59:38 那次实测，比我今天这个修法更早也更完整。
所以对它只做了「补投按工作区收窄」那一半（见下条）。

# 附带修：homeagent 的 workspace 收窄（我今天打破了它）

我先部署服务端（缺 workspace 直接 400）并修了三个桥，**漏了 homeagent**
⇒ 线上 07:42 起持续报 `read_inbox 工具执行失败: HTTP 400 缺少 workspace`。
这是我造成的，靠自己的日志发现的（pid 还是重启前的旧进程 2291455）。

修法与另三个同源：`currentWorkspace`（信封的 `to_workspace`）在回合期间暂存
（与 `currentSessionID` 同一形状、同一生命周期），`inboxURL`/`scopeQuery` 带上它，
补投从"读一次全局收件箱"改为逐工作区（清单来自心跳的 `pending_workspaces`）。

# 清理重投燃料

151 封归档（80 封回声：会话全程无人类 + 71 封 `permission_decision` 不可投）。
★ 用 `archived` 而不是 `read` —— `read` 还能被 `status=all` 拉出来重投。
判据用服务端自己的口径（`unreadFor` = `m.status<>'archived'` 且
`mail_reads` 无该读者），不手写 SQL 猜语义。

后置：pi / dsh / opencode / homeagent 在**所有工作区**的 unread 全部为 0。

# 判据

· `delivery-marks-read.test.mjs` × 3（pi / opencode / dsh）各 4 条：
  核心那条钉的是「`deliveredMails.add` **只允许**出现在 markDelivered 内部」——
  任何别处直接 add 就是绕过标已读的重投路径。另加自检反例。
  变异验证：绕过投递点 / markDelivered 不写库 / 补投绕过，三处全判红。
· `inbox_workspace_test.go`（homeagent）5 条：URL 带 workspace、带不到时不带
  （让服务端 400：错误可见好过静默越界）、补投逐工作区、两处投递路径都设工作区
  且都清空。变异 3 处全判红。
· 改了两条既有判据（pi / dsh 的 permission-note）：原来钉
  `deliveredMails.add(decisionMailID)` —— 那个形状**就是**缺陷载体。
  语义没变（仍"不再当新任务"），载体变了。

全量：pi 517 / opencode 344 / dsh 407 / homeagent 除一条既有的
`TestSDKPinMatchesBuildMachinePointer`（依赖构建机路径，改动前后同样红）全绿。
 2026-09-26 09:18:39 +08:00
JianFeeeee
2a5e3d7d15 fix(auth): 四家桥的读端点也带上会话收窄 + 转发同一条命（工作区隔离第 2 步） 
第 1 步（1b8cd43）把工作区判据放在服务端、pi 桥接上了线。这一步补齐另外四家，
并把**转发**纳入：转发是"把原文引出去"，能转发就等于能读到那条线索的全部内容，
与 read_mail 同一条命（服务端 ForwardMail 也加了同一道校验）。

四家各自的会话来源，与各自的 read_inbox 同一处（不引入第二个来源）：
- dsh：`mailSessionOf(exec)`（工具第二个参数）—— 五个读工具原本没接 exec，这次补上
- opencode：`reverseMap.get(context.sessionID)`
- zcode：`process.env.AGENTMAIL_SESSION_ID`（一轮一个进程）
- homeagent：`p.currentSessionID`（新增 `scopeQuery(sep)`，与 inboxURL 同构）

判据（每条两侧都钉：包住了 / 没包住的不存在）：
- dsh：静态对照，且额外钉 **dist** —— 那是真被 dsh 加载的那份（main: dist/index.js），
  src 改了忘了 build 就是"源码对、线上旧代码"
- opencode / zcode：同上（opencode 还钉"会话来自 context 而不是模块级变量"）
- homeagent：起 httptest 当网关，**五个读工具 + 转发真调一遍**，断言请求 URL 带
  session_id；对照侧：不在回合里（currentSessionID 为空）时不许带
- pi：把 post 的 URL 也纳入记录，forward 进用例表

★ zcode 那条判据我第一版**对照组写错**了：对照组只写裸 URL，而它本来就是
`withScope(\`裸URL\`)` 的子串 ⇒ `!includes(bare)` 恒假。夹具形状不对时判据会以
"恒红/恒绿"的方式骗人（这次是恒红，一眼可见；恒绿就麻烦了）。

变异：homeagent 去掉 read_mail 的收窄 ⇒ 恰好那条断言红。

（工作区共享，只 add 了上面这 12 个文件；dsh 的 dist 是 gitignore 的，由
redeploy-plugin.sh 在 staging 里构建。）
 2026-09-14 23:18:12 +08:00
JianFeeeee
33488760ce fix(相位/安全): 部署门禁只判产物自证；静默 break 改成出声；内核读数带时间坐标 
pi 2026-09-14 的裁定与两条更正，逐条落地。

1. **相位裁定（选 c）**：`packaging`/`build-stamp` 属于**构建相位**，不属于安装相位。
   `run-all.mjs` 现在有相位：`AGENTMAIL_CRITERIA_PHASE=install`（部署门禁用）。
   每条判据登记它读的哪一侧（`ARTIFACT`/`SOURCE`），install 相位里出现 SOURCE 侧判据 → 红；
   被跳过的判据**点名打印**，不静默丢。汇总打 `RESULT phase=build|install`。
   规则入册 `test/CRITERIA.md` §11（含三个真实实例：check-shared-libs 恒红、
   packaging 一改前端就卡死、HOME 在门禁跑完之后才炸）。

   安装相位**真正能判的那一半**：`deploy/install.sh` 读**产物自证**（不重算 dist）——
   `releaseCandidate !== true` → 拒绝；产物 `gitRev` ≠ HEAD → "这个包比源码旧" → 拒绝；
   放行要显式 `--allow-dirty` / `--allow-stale`；`--check` 干跑只报结论不拦。
   实测干跑输出：`产物：gitRev=6702cc2 树=dirty releaseCandidate=false ｜ 当前 HEAD=6702cc2`
   → 报"不是发布候选 + 正式安装会被拒绝 + 要放行请显式说清"。

2. **别解析运行器文本**（pi §5）：`broken`/`red` 的判定改成按 TAP 的**名字**——
   文件级失败的测试名就是路径，断言失败的名字是判据名。变异双向验证：
   未定义标识符 → 「跑不起来的判据」；把某条判据条件改成假 → 「红的判据」。
   不再往关键字表里加补丁（那是往文本解析里加补丁，方向是错的）。

3. **静默 break 是安全相关**（pi §3）：`session_update` 找不到活动会话时不再静默 break，
   改成出声日志（走 journalctl 那条通道），写清两种成因（此刻没在跑 / **接管会话**重启后无法定位）、
   方向（收紧被延迟）、以及兜底的**前提**（"下次投递"要求这条会话还会收到新邮件）。
   `lib/mail-session-id.js` 模块头同步改成安全相关措辞（"人以为自己收紧了权限、实际没有"），
   四桥逐字节同源，`check-shared-libs.sh` 退出码 0。

4. 内核读数补时间坐标（pi 13ea2fdf）：`BUILD_INFO.txt` 里除原始 `dep`/`=>` 行外，
   现在还有 `kernelBinMtime` 与**正在运行的进程启动时间** —— 二进制会在两次读数之间被换掉，
   没有时间坐标的读数不成立。
 2026-09-14 16:54:30 +08:00
JianFeeeee
dae508b25b docs(判据): 补「已知限制」与「缺省语义登记」两节；build.sh 把原始 dep/=> 行写进 BUILD_INFO 
pi 2026-09-14 两件：

1. **登记册真的没有**。我上封信说"已写进 test/CRITERIA.md 的已知限制一节"——**不成立**，
   只有 `appearance-defaults.test.mjs` 里有那段注释。已在 CRITERIA.md 补 §9「已知限制」
   （标识符只解析一层；静态判据的到期前提是"本工作区能装能点"）。
   过度声明自己做过什么是这轮反复出现的那一类错，这次是同一个形状的又一例。

2. **新建 §10「缺省语义登记处」**（pi 的更正：不是无条件 fail-closed，而是"缺了的后果必须
   有人登记 + 写明谁批准了这个方向"）。三条入库，各带依据：
   · 邮件 `permission_mode` 缺 → **不写、不改档**（窄），依据是本轮那个 `|| 'workspace'` 兜窄档的坑；
   · HomeAgent `plugin.json.sdk` 缺 → 内核**不读**（不是语义，是文档），依据内核 manifest.go 结构体 + registry.go；
   · HomeAgent `capabilities` 缺 → **不受限**（宽），依据内核注释明写的理由：17 个存量清单都没有它。

3. `build/BUILD_INFO.txt` 现在**原文贴入** `go version -m <内核>` 的输出，并附"这两行怎么读"
   （`dep … vX.Y.Z` 后面跟 `=> … (devel)` 时那串版本号只是 require 行残留；`=>` 必须按模块名联接）。
   理由：这场争论的全部内容就是这两行该怎么读，原始证据必须和结论放在一起。
 2026-09-14 16:50:33 +08:00
JianFeeeee
4f0a6e6097 fix(homeagent): 构建不许弄脏源码树 —— hmapdev 会重写 plugin.json，构建后还原并出声 
实测：`hmapdev build` 会重写受版本管理的 `plugin.json`（只吃掉了文件末尾换行）。
"构建把树弄脏"这件事在 electron 那边刚定过规矩（脏树产物不得自称发布候选），
所以这里同样处理：构建前留快照，构建后若被改写就还原 + 打印一行说明
（不静默还原 —— 下一个人要知道这条工具会动源码）。

验证：`bash build.sh`（HOMEAGENT_SDK_DIR=…/sdk/v1.3.0）产出 build/plugin.bin（9018271 字节），
构建后 `git status plugins/homeagent-mail-bridge/` 只剩我自己改的 build.sh。
 2026-09-14 16:41:54 +08:00
JianFeeeee
7e696f9a8c fix(homeagent): 撤回"另一条 SDK 血脉"的错误结论；build.sh 不再猜路径；清单判据改成一致性口径 
pi 用只读文件系统逐条反驳了 357662e 的根因，三条我都验证并接受：

1. **"内核链 0.9.x 血脉"不成立 —— 那是我的搜索顺序造出来的事实。**
   本机有 6+ 份 `third_party/homeagent-sdk` checkout：
     /root/ha-test/…（0.9.0，C-ABI 时代，无 plugin.bin 支持）
     /var/tmp/rel-1.3.12/…、/var/tmp/rel-1.3.11/…（1.3.0）
     /var/tmp/release-main/…、/var/tmp/clean-check/…、/var/tmp/homed-p3/…（1.2.0）
   而 build.sh 第一版按候选根目录**第一个命中就算**，命中的正是 ha-test 那份老 checkout。
   内核自己用的是 1.3.0 那份，与钉子 `sdk/v1.3.0`、与 `<SDK_ROOT>/current` **一致**。
   两条教训写进注释了：别用"第一个存在的路径"当权威来源；别把模块版本字符串当身份
   （`replace => local (devel)` 时它只是 require 行的残留）。

2. **"API 不兼容"也是同一个错造成的。** 换成正确的 SDK 之后：
     HOMEAGENT_SDK_DIR=/root/.homeagent/hmapdev/sdk/v1.3.0 bash build.sh
     → hmapdev build 成功，产出 build/plugin.bin（9018271 字节）
   也就是说**这个插件在本机编得出来**，先前的 `SettingsAPI.DataDir` 报错是拿老 checkout 编的产物。

3. **判据把能工作的配置判红**（pi §2）：第 4 步原先硬校验"产物 SDK 模块版本 == 内核模块版本"，
   而生产上能跑的组合恰恰是"内核 + v1.3.0 编的插件"。已删掉这个相等性判据：
   SDK 源码**只认显式指定**（HOMEAGENT_SDK_DIR），不猜、不试探；
   内核那条 dep/=> 只作为**提示**打印（并且按模块名精确联接、只接受紧跟 SDK dep 行的 `=>`，
   不再取"输出里第一个 =>"）；身份改记 **realpath + 内容哈希**；
   `meta.Version` 读取先剥注释（注释里的 `Version = "9.9.9"` 不再能赢）。
   真正的不变量是 **wire 协议 protocol=2 + 一次真实握手**，写在脚本末尾（部署后回看日志）。

4. **清单判据改成一致性口径**（pi §5）：不再"禁止 sdk 字段"——那会把正在工作的那份清单
   （/home/newqqagent/plugins/homeagent-mail-bridge/plugin.json 声明 sdk=1.3.0，正是 08:30
   那次恢复的处置动作）判红，而我没有"内核不读该字段"的证据。现在：可以不声明；
   声明了就必须与构建机指针一致。
 2026-09-14 16:38:28 +08:00
JianFeeeee
357662ed08 fix(homeagent): 不再把 SDK 版本钉在源码里；构建期按内核的依赖表校验对齐 
崩溃循环的根因不是"忘了重编"，是**把 SDK 版本钉死**：

- `plugin.json`/`plg.json` 写死 `"sdk": "1.3.0"`（本机已装 21 个插件里只有 3 个声明该字段）；
- `go.mod` 的 replace 指向 `/root/.homeagent/hmapdev/sdk/v1.3.0`（绝对路径 + 具体版本目录）。

于是"照原样重编"只会再造一个装上去就崩的包。实测本机内核链的是**另一条 SDK 血脉**：

    $ go version -m /usr/local/bin/homed
    dep gitcode.com/JianFeeeee/homeagent-sdk v0.9.2
    =>  ./third_party/homeagent-sdk (devel)

所以判据改成**两个二进制的依赖表一致**，而不是"版本号看起来像"：

- `build.sh`：读内核的 SDK 依赖（`go version -m`）→ 据此解析 SDK 源码目录 →
  用 `-modfile` 临时替换（不改动受版本管理的 go.mod）→ 构建 → **回头验产物**：
  产物与内核链的 SDK 版本不一致就报错退出，绝不产出"装上去就崩"的包。
- `manifest_sdk_test.go`：① 清单不许写死 `sdk`；② go.mod 的钉子不得偏离构建机指针
  （取不到基准就红，不许默默放过）；③ `build.sh` 必须在（它是与内核对齐的硬校验点）。
  三条都做过变异验证（写死 sdk / 钉子漂到 v1.2.0 / 删掉 build.sh → 各自红）。

顺带查出一个比"重编"更根本的事实：本机 `build.sh` 跑到编译就失败 ——

    ./plugin.go:217:18: sett.DataDir undefined (type sdk.SettingsAPI has no field or method DataDir)

即本插件源码用的是 **1.3.0 SDK 的 API**，而本机内核链的是 0.9.x 血脉：**重编解决不了**，
要么内核改成链 1.3.x 的 SDK，要么把插件移植到内核那份 SDK（这是 HomeAgent 侧的决定）。
 2026-09-14 16:27:02 +08:00
JianFeeeee
be0693821b fix(agents): 四家桥的 read_inbox 一律按会话收窄（dsh/opencode/zcode/homeagent） 
用户：「你还是没修好不同 session agent 收件箱隔离的问题」。上一轮我只修了 **pi**，
另外四家还漏着 —— 它们是**每一家各自实现** read_inbox，不修就还是漏。

## 缺陷

列表按 Agent 列（整个收件箱），而 read_inbox 按契约把**列出来的都标成已读**
⇒ A 会话的回合会把 B 会话的未读标掉 ⇒ B 之后按 `?status=unread` 补投时
再也看不到那封信（静默丢信，不是"少看一封"）。用户是在别的 Agent 上看到它的。

## 四家的修法（各自平台能力不同，但都要"并发安全"）

| 桥 | 会话来源 | 为什么这样做 |
|---|---|---|
| dsh | 工具第二参数 `exec.agent.id` → `reverseMap` | 平台就在上下文里给了会话；**不能用模块级"当前会话"变量**（同进程可能同时跑多条会话的回合，会互相覆盖） |
| opencode | 工具第二参数 `context.sessionID` → `reverseMap` | 同上 |
| zcode | `AGENTMAIL_SESSION_ID`（在**调用时**读） | 一轮一个进程，驱动本来就注入它给授权钩子用；调用时读，避免将来复用进程拿到旧值 |
| homeagent | `p.currentSessionID`（回合开始设、结束清） | Go 插件，本来就有这个状态 |

取不到会话一律**退回整体收件箱**（历史行为），不猜 —— 猜错就是静默丢信。

## 判据

- 服务端语义：`server/internal/repo/session_scope_test.go`（读 A 不动 B、列表收窄、
  计数与列表口径一致）。
- 桥侧接线：dsh 4 条、opencode 3 条、zcode 3 条、homeagent Go 1 条
  （`TestInboxURLScopedBySession`，直接断言拼出来的 URL）。
  每家都带**判据自检**：拿旧写法喂进来必须判红；dsh/opencode 还专门断言
  "不得用模块级当前会话变量"。
- **部署件**（不是仓库）：四家的部署快照里都能 grep 到 `session_id=`。
- **线上实测**：用 opencode 自己的 Agent 身份请求收窄列表 —— 会话 A 3 封、
  会话 B 0 封、两者无交集、且都是全量的子集。

套件：opencode **331**、dsh **381**、zcode **385**、homeagent ok，全绿。
四家桥已重新部署（dsh/opencode/zcode 快照切换 + homeagent 新 plugin.bin 并重启），
四个服务均 active。
 2026-09-14 12:07:45 +08:00
JianFeeeee
5b6fef764f feat(appearance): 主题与壁纸搬到服务端（账号级）—— 回答"为什么背景存在本地" 
用户质问：「为什么背景是保存在本地而不是服务器！」当时的实情是主题与壁纸只写
localStorage：换设备/换浏览器就没了，而且**多账号共用一份**（键是全局常量
`agentmail.background`）—— 同一台机器换账号背景不跟着走。而 localStorage 的 ~5MB
配额也解释了客户端那套"压到 2.4MB 以内"的限制本来就是为本地存储设计的。

现在：**服务端是权威（账号级），本地只是缓存**（首屏秒开、离线可用）。

## 服务端

- 新表 `user_appearance`（两种方言），用**列**而不是 JSON：blob GC 要一眼看出
  "这张图还有没有人用"。
- `/api/v1/me/appearance`：GET / PUT（主题+背景档）/ POST image（multipart）/
  GET image / DELETE image。鉴权同其余 /me/*（cookie 或 Bearer）。
- 图片走**内容寻址的 blob 存储**（与附件同一套），库里只存 sha256；上限 4MB 兜底
  （客户端会先压到 ~2.4MB），只收图片类型（非图片 415 —— 浏览器会把非图片渲染成
  空白，用户只会看到"设置了却没变化"），超限 413 不静默截断。
- ★ **blob GC 的引用源加了这张表**：我在实现前先读了 `SweepUnreferencedBlobs`，
  它只认 attachments / calendar_attachments。漏了这一处，壁纸会在下次 GC 时被当
  孤儿删掉，而库里那行还在 —— 表现为"图 404、设置却显示已设置"。判据同时验了
  壁纸存活**与**孤儿确实被清（否则"还在"可能只是因为 GC 没跑）。

## 客户端

- `lib/appearance.ts`（纯函数：两侧形状换算、data URL→Blob）+ `stores/appearanceSync.ts`
  （pull / push / 去抖订阅 / 账号切换重新拉取）。
- 三条不变量都有判据：拉取以服务端为准；★ **拉取不会再推回去**（否则是自触发回环，
  一次拉取顺带一次 PUT，服务端 updated_at 被无意义刷新）；本地改动会推上去。
- 壁纸**只在换图时上传一次**（几 MB 不该每次 PUT 都跟着走）。
- 降级**必须可见**：未登录/不可达 → `local-only`，推失败 → `pending`，背景设置里
  有徽标与说明（"已同步 / 待同步 / 仅本机"）。静默降级会让人以为已经同步，
  然后在另一台机器上发现没有 —— 正是这次的缺陷。
- 图片用**带认证的 fetch** 取回再转 data URL：`<img src>` 发不出 Bearer，而
  `?token=` 会把密钥写进历史记录与服务端日志（明确不做）。

## 判据

- Go 10 条：往返、★多账号隔离、非法值归一、上传/取回字节一致、非图片 415、
  超限 413、删除、未登录 401（五个端点）、★GC 存活 + 孤儿对照。
- 客户端 10 条：形状换算、image 无图退回 none、越界夹取、拉取生效、
  ★拉取不推送、推送 payload、未登录/500 → local-only、推失败 → pending、
  ★壁纸只上传一次。
- 全量：server 10 包全绿、客户端 249 通过（含打包一致性判据 —— 它先红后绿，
  因为前端改了必须重打安装包，这条护栏是先前特意留下的）。

## 线上验证与交付

- jianf 设置 → 回包 saved=true；**gui-lab 读到自己那份默认值**（隔离生效）；
  gui-lab 上传 67B PNG → 取回 sha256 一致、`has_image=true`；DELETE 后 404。
- 网关已重打（WebUI 内嵌）并部署；Electron 安装包已重打（AppImage + deb）。

遗留：鸿蒙端还没有外观功能（数据已在服务端，将来可直接读）；本地缓存仍在（离线可用）。
 2026-09-14 08:32:22 +08:00
JianFeeeee
1ec88866ac fix(permission): 另外四家桥的"人类说明"缺口 —— 三家修、一家本来就有 
承接 453f451（pi 桥）。用户批准后把同款缺口在其余四家逐一核对：
**zcode 本来就有**（`说明：${decision.note}`），homeagent / dsh / opencode 三家缺。

## homeagent（Go，能完整修）

SSE 事件结构里**根本没有 Note 字段**（json 里只有 decision/decided_by）⇒ 备注在
解码那一步就没了。补上字段，并把提示词抽成纯函数 `permissionDecisionPrompt(evt)`，
加了判据（说明必须出现 + 反向对照：无说明/空白说明不得凭空造出说明段）。
构建（`go build -buildmode=plugin`）后 install 到
`/home/newqqagent/plugins/homeagent-mail-bridge/plugin.bin` 并重启，已核验部署件
含新符号（`grep -a`，中文用 strings 查是查不到的）。

## dsh / opencode（平台回执放不下理由 → 分两步）

两家的审批回执都是**三态字符串**：DSH `ApprovalOutcome` 只有
allowed-once / rejected / cancelled / unavailable，openCode 只有 once / always / reject
—— **没有地方放人类的说明**。所以：

1. 提示词（"你之前发起的权限请求已有结论：…"）统一走 `permissionPrompt(data)`，
   带上 `用户的说明：…`。dsh 原有**三处**内联文案（续谈/新会话/通知投递），
   措辞分叉正是这类信息漏掉的地方 —— 判据直接钉"只有一处拼这句话"。
2. 带说明的决策**另投一趟通知**，让模型在会话里看到理由。代价是多一轮；比悄悄
   丢掉人的指令轻（原缺陷就是丢了指令，模型把同一条命令换写法又问一遍，连问 9 次）。
3. 决策回执不再被当成"新任务"（内容已随 permission_decision 交付），并记下
   `decision_mail_id` 防重复 —— 与 pi 桥同源。

判据：dsh / opencode 各 5 条（含"拿缺陷时的源码形态喂进来必须判红"的自检）。

## 部署与代价

- dsh → 快照 20260914-081456、opencode → 20260914-081516、homeagent → 新 plugin.bin，
  三家的服务 active 且心跳/连接已核。
- 重启 dsh 时它正在"续谈"一封邮件（08:10:45 日志）——事后核对：那一轮**已回完**
  （faad0037 的 parent = 4919aa88），没有丢活。
- 套件：dsh 372、opencode 323、homeagent go test ok、zcode 382 全绿。
 2026-09-14 08:17:23 +08:00
JianFeeeee
10ff50e899 feat(homeagent): 输出通道改造 —— 通道名 email + 注入通道对齐 + 附件走路径 
修的是内核的交付判定与我们对不上的问题。

## 根因

内核判断「这一轮到底有没有交付」**只认工具名前缀** `output_send__*`
（internal/agent/core/process.go 的 isOutputDeliveryTool）。而 `send_mail`
是个普通工具，长得和 read_inbox 没有区别 —— 模型用它发完信，内核不知道
回复已经交付，照常补一句「请根据以上工具结果继续。」。模型把这句话读成
「还要再做一步」，而它手里唯一能做的「一步」往往又是再发一封信。
这个自我强化循环在 QQ 上有过真实事故（单轮 34 次 output_send__qq、514 秒）。

三处改动，缺一不可：

1. **通道名 `homeagent` → `email`**（按投递介质命名，与内核自带的
   qq/webui/cli/acp/a2a 一致），内核据此拼出 `output_send__email`。
   能力位声明必须与实现一致：原先声明了 CapFile 而 handler 不读 `type`，
   于是任何 type=file 都会静默变成一封「把路径当正文」的邮件 ——
   声明一个做不到的能力比不声明更糟（调用方无从发现）。现在 caps=7
   且真的实现 text/file/image。

2. **注入来信时用通道名，不再用插件名**。内核的约定是「用回复该走的通道名
   注入」：webui 传 "webui"，clawhubadapter 传它自己的通道名。我们原先两个
   参数都传 `homeagent-mail-bridge` —— 那个名字**不是一个已注册的通道**，
   于是注入来源、模型被告知要用的通道名、实际注册的通道名三者对不上。

3. **提示词补上平台特有的投递指引**（channel.go 的 deliveryHint）。
   共用的 replyInstruction 对人来信说的是「回信不用你自己发，插件会替你转发」
   —— 那句在 dsh/opencode/pi 上完全正确，在 HomeAgent 上却与内核的 persona
   （「必须显式调用 output_send__{通道名}」）相反。实测：模型听我们的、
   返回纯文本、插件兜底转发，邮件确实到了，但内核不知道已交付。
   现在两条口径对齐：优先走通道，兜底 relay 仍然生效且**不会重复发**
   （通道 handler 先 noteExplicitChannelSend，自动 relay 据此让位）。

同时按新纪律在 plg.json 声明 `sdk: "1.2.0"`；工具链据此同步了 go.mod 的
require/replace（它自己写的，含 store 里的绝对路径 —— 换机器跑一次
hmapdev build 会重新同步）。

## 验证（真模型、真网关、真邮件）

进程构建：`hmapdev build` 报「SDK 1.2.0（项目声明 sdk=1.2.0）」、
子进程模式（协议 2）；go vet 干净、go test 通过。

部署：经内核自己的 pluginmgr（POST 127.0.0.1:9876/plugins，overwrite=true）
0.1.0 → 0.2.1 → 0.2.2，每次 config_kept=true；重启后 loaded/alive/心跳齐全，
插件日志「注册完成（15 个工具 + 1 个输出通道）」。

行为端到端（两封真邮件）：
- 让模型列出通道 → 回信里列出 `email | text / file / image`，与注册的
  caps=7 及描述逐字一致
- 让模型「原样重复标记」→ 内核日志 `executing tool: output_send__email`，
  回流**恰好 1 封**，插件日志「模型已自行回复，跳过自动 relay」
- 让模型建文件并以 type=file 发送 → `cmd_run` → `output_send__email_help`
  → `output_send__email`，附件 chan-file-*.txt（15 字节）原样到达，relay 让位

这两条正是改造的两个动因：内核认得交付（循环被切断），以及附件走
「一个本地路径字符串」而不是 `attachment_ids=[...]` 数组
（opencode 上模型把数组写成 JSON 字符串、连试 6 次放弃整个任务的那个失败模式，
在结构上就不存在了）。
 2026-09-12 17:38:32 +08:00
JianFeeeee
ed3703295c homeagent: advisory 档位提示词 + 心跳报 advisory + permission_mode.go 
- 新建 permission_mode.go：NormalizeMode / ModeBriefing（advisory 版本）
  homeagent 无工具拦截点，档位只能在提示词里告知模型，措辞如实说
  「这个平台无法强制这一档」—— 假装强制会让模型以为越界会被拦
- mailEvent 加 PermissionMode 字段（从 SSE new_mail payload 读入）
- handleNewMail 提示词追加 ModeBriefing（plan/workspace/full 三档说明）
- 心跳上报 mode_enforcement: 'advisory'
- go vet + 68 测试全过
 2026-09-06 19:23:42 +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
13fcb00acc feat: relay-key 共用模块（三桥 + homeagent） 
Sha256 clamp relay_key 过 160 字节上限，避免服务端 400
被 worker 当暂时失败让位，导致邮件驱动会话无本地 UI 静默挂死。

新增 relay_key.go / relay-key.js + 15 个纯函数测试。
 2026-09-06 15:16:34 +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
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
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
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
5b76ac5c57 feat(homeagent): 四个日程工具 + 工具计数不再硬编码 
create_schedule / list_schedules / update_schedule / delete_schedule，
插件从 11 个工具变 15 个。

时间格式是这组工具最容易出错的地方，parseEventTime 接受三种形态：
完整 RFC3339（推荐）、无时区（按本机时区解释）、只有日期（当天 9 点，
比零点有用 —— 零点的提醒没人看）。

**刻意不接受自然语言**（「明天九点」）：解析它需要知道模型以为今天是哪天，
而它上下文里那个日期常常是错的 —— 一个静默偏移一天的提醒比报错糟得多。
解析失败的报文里带上当前本机时间，让它能自己算。

其他细节：
- recipients 用逗号分隔的 string 而非数组：几个平台对数组参数的 schema
  支持不一致，而逗号分隔在所有平台上都是普通 string。中英文逗号都收 ——
  中文输入法下打出「，」是常态。
- argInt 同时收 float64 与字符串："30" 带引号会让「提前 30 分钟」静默失效。
- update 的工具描述里写明「只传要改的字段」：模型的默认倾向是回传它记得的
  全部字段，记错一个就覆盖掉原有的提醒正文或收件方。
- list 在接近上限（>=75%）时主动提示清理，而不是等撞墙 —— 撞墙那一刻
  模型往往正在做别的事，没有余裕去清理。
- scheduleEvent.effectiveRecipients() 与服务端同一条兜底链：只读
  recipients 会让旧数据显示成「发给：」后面空白。

**工具计数从 RegisterTool 的调用数派生，不硬编码。**
之前写死 13 而实际注册 11 —— 排查「工具没生效」时日志说 13、平台说 11，
两个数字都不可信，白花了一轮时间。加工具时忘改常量是必然的，
所以让它没有机会写错。

plugin.go 另补 put/delete 两个 HTTP 辅助（原来只有 get/post）。

已部署验证：homed 日志「注册完成（15 个工具 + 1 个输出通道）」，
模型实际调用 list_schedules 成功。
 2026-09-04 06:28:55 +08:00
JianFeeeee
473c46659a fix(homeagent): 删除 plugin.go 里与 tools.go 重复的 6 个方法 
plugin.go 与 tools.go 各自声明了同名工具处理器。逐个 diff 后保留
tools.go 的版本 —— 它严格更丰富：read_thread 多 ParentHid → parent_hidden
并区分「父邮件无权查看」与「父邮件尚未加载」，suggest_address 多解析
candidates，connect_to_server 多一条注释。

plugin.go 删除 handleConnectToServer / handleForwardMail /
handleSuggestAddress / handleListContacts / handleSessionParticipants /
handleReadThread + minInt。

tools.go 删除本地 min()：go.mod 是 go 1.25.0，内置 min 可用，
本地定义只是遮蔽。

部署验证：11 项工具注册（日志里硬编码的「13 个工具」是错的数字）。
 2026-09-03 21:11:15 +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
fc33087982 feat: homeagent-mail-bridge —— TrueAgent 接入 AgentMail（MVP） 
## 架构

TrueAgent 是单一常驻 agent 事件循环，没有 per-conversation session。
插件像 QQ 插件一样：所有邮件注入同一个事件循环，靠中断消息文本传递 context。
不做 platform_sessions 上报（无 sessions 可映射）。

## 工具

- read_inbox: 收件箱查询（渲染发件人/主题/正文/抄送/附件）
- send_mail: 三维地址发信（支持 reply_to）
- output_send__homeagent 输出通道（agent 可主动发信）

## 自动回信

InjectInputSync（阻塞）等待 agent 处理完毕 → 自动把 FinalText
发回给发件人（reply_to 指向原邮件）。agent 不需要记得调 send_mail。

试过 StageAfterOutput hook，但 before_output 看不到 ToolCalls
（read_inbox 调用在 turn 中间就被清掉了），导致自动回信不触发。
InjectInputSync 更可靠：TrueAgent 保证不重入。

## 基础设施

- 心跳 25 秒
- SSE 长连 + 自动重连（3 秒退避）
- 注册时自动注册密钥（AGENTMAIL_AGENT_KEY 环境变量）
- systemd drop-in 注入 AgentMail 环境变量

## 构建

plugindev build → dist/homeagent_linux_amd64.hmap
安装到 /home/newqqagent/plugins/homeagent-mail-bridge/
homeagent.service drop-in: /etc/systemd/system/homeagent.service.d/agentmail.conf

## 端到端验证

admin → homeagent@/tmp/homeagent.new（自动回信验证）
→ homeagent 读取邮件 + 自动回信「收到确认」→ 25 秒往返完成
 2026-09-03 12:57:43 +08:00