diff --git a/docs/DEBTS.json b/docs/DEBTS.json index 6d07db6..03bd84b 100644 --- a/docs/DEBTS.json +++ b/docs/DEBTS.json @@ -198,10 +198,10 @@ { "id": "platform-mirror-replace-domain-too-wide", "count": 1, - "where": "`server/internal/repo/platform_sessions.go`：`ReplacePlatformSessions` 的 `DELETE ... WHERE agent_name = $1`（:63）与 `INSERT`（:79）—— 替换域=**agent**，而每个上报者只知道**一个 directory**（`plugins/opencode-mail-bridge/index.js:1147` `client.session.list({ query: directory ? {directory} : undefined })`）。复现读数：`sqlite3 --readonly /opt/agentmail/data/agentmail.db \"select workspace,count(*) from agent_platform_sessions where agent_name='opencode' group by workspace;\"` —— 连续采样会看到它按 project 轮换（实测 10 个状态）。同族另一处：`server/internal/handler/agents.go:185` 的 `req.PlatformSessions != nil` 对 `[]` 为真 ⇒ 空清单也走整表替换。 ★ 同批必改的第三处（**与 PK 改动无关、今天就可达**）: `server/internal/repo/platform_sessions.go:393-397` 的 `LEFT JOIN agent_platform_sessions aps ON aps.platform_id = s.platform_id` ＋ `QueryRowContext(...).Scan(...)` —— JOIN **不带 agent_name/workspace**，而镜像表的 PK 是 `(agent_name, platform_id)` ⇒ **同一个 platform_id 挂在两个 agent 下就有两行**。消费者 `server/internal/notify/mail.go:94` 的 owner 决定 `platform_session_id` 发给谁（发错 = 收方去自己磁盘找别人的会话文件 ⇒ 抛「平台侧会话已删」⇒ 邮件静默消失）。", + "where": "`server/internal/repo/platform_sessions.go`：`ReplacePlatformSessions` 的 `DELETE ... WHERE agent_name = $1`（:63）与 `INSERT`（:79）—— 替换域=**agent**，而每个上报者只知道**一个 directory**（`plugins/opencode-mail-bridge/index.js:1147` `client.session.list({ query: directory ? {directory} : undefined })`）。复现读数：`sqlite3 --readonly /opt/agentmail/data/agentmail.db \"select workspace,count(*) from agent_platform_sessions where agent_name='opencode' group by workspace;\"` —— 连续采样会看到它按 project 轮换（实测 10 个状态）。同族另一处：`server/internal/handler/agents.go:185` 的 `req.PlatformSessions != nil` 对 `[]` 为真 ⇒ 空清单也走整表替换。 ★ 同批必改的第三处（**与 PK 改动无关、今天就可达**）: `server/internal/repo/platform_sessions.go:393-397` 的 `LEFT JOIN agent_platform_sessions aps ON aps.platform_id = s.platform_id` ＋ `QueryRowContext(...).Scan(...)` —— JOIN **不带 agent_name/workspace**，而镜像表的 PK 是 `(agent_name, platform_id)` ⇒ **同一个 platform_id 挂在两个 agent 下就有两行**。消费者 `server/internal/notify/mail.go:94` 的 owner 决定 `platform_session_id` 发给谁（发错 = 收方去自己磁盘找别人的会话文件 ⇒ 抛「平台侧会话已删」⇒ 邮件静默消失）。 ★★ 消歧键必须写**两把**（agent + workspace），只写 agent 在未来态仍歧义 —— pi（`43d2c9dd`）造的场景C「**同 agent + 同 platform_id + 两个 workspace**」（PK 加 workspace 后合法）下，只按 agent 消歧 ⇒ **仍 2 行**；agent+workspace ⇒ 1 行（我实测复核成立）。★ 第四处（**最容易漏且最致命**）: `server/internal/db/migrations/init_sqlite.sql:407` 与 `init.sql:371` 都是 `CREATE TABLE IF NOT EXISTS` ⇒ **改主键这一行在已部署库上静默不生效**；`server/internal/db/migrate.go:33-40` 每次启动逐条重跑 init DDL（`cmd/server/main.go:39/48` 调），而 `addMissingColumns`（:365）只补**列**、不碰约束 ⇒ 必须**显式重建表**（SQLite 不能 ALTER PK：建新表→COPY→DROP→RENAME；全仓现无任何 RENAME TO/_new/DROP TABLE 代码）。", "due": "**决定「一个 agent 一个镜像桶」还是「一个 (agent, workspace) 一个桶」之时**（即修这个缺陷的那一次）。★ 前置条件（实测而非推断）：**必须先动主键** —— `PRIMARY KEY (agent_name, platform_id)`（`server/internal/db/migrations/init_sqlite.sql:421`）若不加 workspace，则「同一 platform_id 出现在两个 workspace」会 `UNIQUE constraint failed (1555)`，而 INSERT 无 `ON CONFLICT`（grep=0）+ `defer tx.Rollback()` ⇒ **整个 DELETE 回滚**、`agents.go:186` 降级为 -1、桥侧不读该字段（grep=0）⇒ 三重静默，表现为「心跳一直成功而镜像永久停滞」（比现在的间歇擦除**更难查**）。顺序：先 PK 加 workspace，再 DELETE 加 workspace。", "kind": "scope", - "note": "2026-09-26 我（dsh）与 pi 在 `21c398ee` 会话上共同定位；**尚未实现修法**，故记欠账。\n\n## 现象（可复现）\n```\n同一文件/同一 inode 的 agent_platform_sessions 在若干状态间轮换，差的恒为一个 project 的会话数:\n 实测 10 个状态: /tmp=49 /root=38 am-mcp-probe=23 agentmail=37 TrueAgent=100\n llmsproxy=18 facemodule=7 LiquidUnifiedDebugEngine=7 NextAgent=2 (空)\n每次替换是**整表**（同状态内 37 行的 reported_at span = 0.0ms）\n```\n\n## 危害（口径已修正）\n```\n候选列表有两个来源: 来源1 = 本侧 sessions（实测 6 条）、来源2 = 该镜像表（实测 37 条）\n⇒ 镜像被别人擦掉时，该 workspace 的候选从 ~43 掉到 ~6（掉 37 条）—— **不是归零**\n （我先前写成 37→0，是漏了来源1；数字口径缺口径，已更正）\n```\n\n## 三个曾被提出、但已被推翻的根因（留作反面材料）\n```\n① 「读域 vs 擦除域不等，且 [] 是 truthy」——只解释 5 个 0 会话 project（实测 45 次里 9 次空），\n 非主因（非空替换占 36/45 = 80%）\n② 「PK 允许并集 ⇒ 擦除在语义上不必要」——**错**。整表替换是**有意设计**且有测试钉着:\n `server/internal/repo/platform_sessions_test.go:219` `TestReplacePlatformSessionsIsFullReplace`\n ＋ 函数文档 :44-46 明写要防「平台删了会话却留在镜像 ⇒ 选了 404」\n ⇒ 擦除**必要**，错的是**范围**（应 per-source replace，即「擦的域 == 读的域」）\n③ 「今天不撞 PK 是因为 session.id 全局唯一」——**因给错了**。实测: 同一 platform_id 换 workspace\n **也不撞**（err=nil）⇒ 真正的原因是两处**代码结构**:\n · 跨调用: `DELETE WHERE agent_name=$1` 先清该 agent 全部行（:63）\n · 同调用内: `seen` map 去重（:70）\n 与 id 是否唯一无关 ⇒ 「数据性质 vs 约束」那个框架本身对，载体是这两处代码。\n```\n\n## 为什么这条值得进登记（而不是只留在信里）\n```\n它是一个**已定性的、带顺序约束的**修法前提: 不是「顺手改一下」，而是\n「先改 PK、再改 DELETE，否则新的写法会从间歇擦除变成**永不自愈的静默停滞**」——\n而后者没有报错、没有日志、桥也不读响应（三重静默），下一个人只会看到「补全里少了会话」。\n★ 该断言的形状（而非点名三笔）已在 debt_registry_test.go 里确立，故新增条目不触碰既有断言。\n```\n\n\n## ★★ 补记（2026-09-26 我实测，三条）\n```\n① `:395` 的歧义**今天就可达，且与 PK 改动无关**: 造两个 agent（opencode/homeagent）上报**同一**\n platform_id（workspace 可以不同、也可以相同）⇒ 该 JOIN 出 **2 行**，\n PlatformSessionFor 返回 owner=**homeagent**，而那条会话是 **opencode** 接管的 ⇒ **取错归属**。\n ⇒ 所以它不是\"改 PK 的副作用\"，是**既存缺陷**（只是今天生产数据里跨 agent 的 platform_id 交集=0，\n 所以没显形 —— 又一个\"当前干净是数据性质、非约束\"）。\n② pi 建议的修法「JOIN 加 workspace」**不完整**:\n 场景A 跨 agent + **不同** workspace ⇒ 1 行 ✓ 修好\n 场景B 跨 agent + **相同** workspace ⇒ **2 行** ✗ 仍歧义（我实测）\n③ 正确的消歧键是 **agent 身份**，不是 workspace: `JOIN ... AND aps.agent_name = s.from_agent`\n ⇒ 1 行 ✓。而 `sessions.from_agent` 由 `AdoptPlatformSession → CreateSession(ctx, nil, agentName, …)`\n 写入（repo.go:260 的第 2 个形参）⇒ **接管路径上结构性地非空**（生产库实测: 接管会话里\n from_agent<>'' = 9 条、=0 条 ⇒ 无空值）。\n⇒ ★ 结论: 这条欠账的伴随项**不止** PK + DELETE + JOIN-加-workspace，\n 而是「**PK 加 workspace（保 (agent,ws,pid) 唯一）+ DELETE 加 workspace + :395 的 JOIN 按 agent 消歧**」\n 三处**必须同批**改；漏掉第三处 ⇒ 出现\"取错归属 ⇒ 邮件静默消失\"（比候选少一条更重）。\n```\n" + "note": "2026-09-26 我（dsh）与 pi 在 `21c398ee` 会话上共同定位；**尚未实现修法**，故记欠账。\n\n## 现象（可复现）\n```\n同一文件/同一 inode 的 agent_platform_sessions 在若干状态间轮换，差的恒为一个 project 的会话数:\n 实测 10 个状态: /tmp=49 /root=38 am-mcp-probe=23 agentmail=37 TrueAgent=100\n llmsproxy=18 facemodule=7 LiquidUnifiedDebugEngine=7 NextAgent=2 (空)\n每次替换是**整表**（同状态内 37 行的 reported_at span = 0.0ms）\n```\n\n## 危害（口径已修正）\n```\n候选列表有两个来源: 来源1 = 本侧 sessions（实测 6 条）、来源2 = 该镜像表（实测 37 条）\n⇒ 镜像被别人擦掉时，该 workspace 的候选从 ~43 掉到 ~6（掉 37 条）—— **不是归零**\n （我先前写成 37→0，是漏了来源1；数字口径缺口径，已更正）\n```\n\n## 三个曾被提出、但已被推翻的根因（留作反面材料）\n```\n① 「读域 vs 擦除域不等，且 [] 是 truthy」——只解释 5 个 0 会话 project（实测 45 次里 9 次空），\n 非主因（非空替换占 36/45 = 80%）\n② 「PK 允许并集 ⇒ 擦除在语义上不必要」——**错**。整表替换是**有意设计**且有测试钉着:\n `server/internal/repo/platform_sessions_test.go:219` `TestReplacePlatformSessionsIsFullReplace`\n ＋ 函数文档 :44-46 明写要防「平台删了会话却留在镜像 ⇒ 选了 404」\n ⇒ 擦除**必要**，错的是**范围**（应 per-source replace，即「擦的域 == 读的域」）\n③ 「今天不撞 PK 是因为 session.id 全局唯一」——**因给错了**。实测: 同一 platform_id 换 workspace\n **也不撞**（err=nil）⇒ 真正的原因是两处**代码结构**:\n · 跨调用: `DELETE WHERE agent_name=$1` 先清该 agent 全部行（:63）\n · 同调用内: `seen` map 去重（:70）\n 与 id 是否唯一无关 ⇒ 「数据性质 vs 约束」那个框架本身对，载体是这两处代码。\n```\n\n## 为什么这条值得进登记（而不是只留在信里）\n```\n它是一个**已定性的、带顺序约束的**修法前提: 不是「顺手改一下」，而是\n「先改 PK、再改 DELETE，否则新的写法会从间歇擦除变成**永不自愈的静默停滞**」——\n而后者没有报错、没有日志、桥也不读响应（三重静默），下一个人只会看到「补全里少了会话」。\n★ 该断言的形状（而非点名三笔）已在 debt_registry_test.go 里确立，故新增条目不触碰既有断言。\n```\n\n\n## ★★ 补记（2026-09-26 我实测，三条）\n```\n① `:395` 的歧义**今天就可达，且与 PK 改动无关**: 造两个 agent（opencode/homeagent）上报**同一**\n platform_id（workspace 可以不同、也可以相同）⇒ 该 JOIN 出 **2 行**，\n PlatformSessionFor 返回 owner=**homeagent**，而那条会话是 **opencode** 接管的 ⇒ **取错归属**。\n ⇒ 所以它不是\"改 PK 的副作用\"，是**既存缺陷**（只是今天生产数据里跨 agent 的 platform_id 交集=0，\n 所以没显形 —— 又一个\"当前干净是数据性质、非约束\"）。\n② pi 建议的修法「JOIN 加 workspace」**不完整**:\n 场景A 跨 agent + **不同** workspace ⇒ 1 行 ✓ 修好\n 场景B 跨 agent + **相同** workspace ⇒ **2 行** ✗ 仍歧义（我实测）\n③ 正确的消歧键是 **agent 身份**，不是 workspace: `JOIN ... AND aps.agent_name = s.from_agent`\n ⇒ 1 行 ✓。而 `sessions.from_agent` 由 `AdoptPlatformSession → CreateSession(ctx, nil, agentName, …)`\n 写入（repo.go:260 的第 2 个形参）⇒ **接管路径上结构性地非空**（生产库实测: 接管会话里\n from_agent<>'' = 9 条、=0 条 ⇒ 无空值）。\n⇒ ★ 结论: 这条欠账的伴随项**不止** PK + DELETE + JOIN-加-workspace，\n 而是「**PK 加 workspace（保 (agent,ws,pid) 唯一）+ DELETE 加 workspace + :395 的 JOIN 按 agent 消歧**」\n 三处**必须同批**改；漏掉第三处 ⇒ 出现\"取错归属 ⇒ 邮件静默消失\"（比候选少一条更重）。\n```\n\n\n## ★★ 补记之二（2026-09-26 我实测：③ 的键写全 + ④ 迁移静默失效）\n```\n③ 的键必须写**两把**: 我原写「按 agent 消歧」（`aps.agent_name = s.from_agent`）——\n ★ pi 造出场景C 反驳，我实测**成立**:\n 场景A 跨 agent + 不同 ws ⇒ 三键皆 1 行 ✓\n 场景B 跨 agent + 同 ws ⇒ 按 ws 2 行 ✗ / 按 agent 1 行 ✓ / 两把 1 行 ✓\n 场景C 同 agent + 同 id + 两 ws（**未来态**，PK 加 ws 后合法）⇒ 按 agent **2 行** ✗ / 两把 1 行 ✓\n （我造这张两行的表: 今天插第二行报 `UNIQUE ... (agent_name, platform_id)` 1555 ⇒ 场景C 今天不可达）\n ⇒ 结论订正: 正确键 = `aps.agent_name = s.from_agent AND aps.workspace = s.workspace`，\n 且 `sessions.workspace` **列已存在**（sqliteAddColumns 补的），生产实测: 有 platform_id 的会话 9 条\n ⇒ workspace 非空 **9/9**、与 aps 一致 **6/6**（另 3 条镜像无此 id）⇒ 第三把键**不需要新加数据**。\n ★ 另: 我一度提出用 `ORDER BY (aps.agent_name = s.from_agent) DESC LIMIT 1` 替代\"谓词入 ON\"，\n 实测**更差**: 场景E（本侧由 e2 接管、镜像同名 id 只剩 e1 那行）下 ORDER BY 取到 **e1**（错），\n 而谓词入 ON 得 NULL ⇒ 退回 `from_agent`=e2（对，与文档 :388-390「镜像没有则退回 from_agent」一致）。\n ⇒ 所以 pi 的「谓词入 ON」形态是**对的**，我的排序键想法**撤回**。\n\n④ ★★ 改 PK 这一步在**已部署库上静默不生效**（本回合最重的发现，实测四环）:\n ① `CREATE TABLE IF NOT EXISTS`（init_sqlite.sql:407 / init.sql:371）对**已存在**的表**整条跳过**\n ② `migrate.go:33-40` 每次启动逐条重跑 init DDL（`cmd/server/main.go:39/48`）；\n `addMissingColumns`(:365) 只补列、不碰约束 ⇒ 补不了 PK\n ③ 实测复现: 按旧 PK 建库 → 重跑含新 PK 的 DDL ⇒ **rc=0、无报错**，\n `sqlite_master` 里 PK **仍是旧的** → 再插「同 id 不同 ws」第二行 ⇒ **仍报 1555**\n ④ 而测试库走 `t.TempDir()` + `Migrate` ⇒ **每次全新建表** ⇒ 新 PK 生效 ⇒ **测试全绿**；\n 且全仓**无任何** schema/PK 断言（`sqlite_master`/`table_info` 查询 grep=0）\n ⇒ ★★ 于是「改完 DDL、测试全绿、生产没变」是**完全静默**的:\n 生产上 ②DELETE 加 workspace 会删对、③JOIN 双键会写对，但 ①PK 没变 ⇒\n 同 id 跨 ws 的 INSERT 仍撞 1555 + 无 ON CONFLICT + `defer tx.Rollback()` ⇒\n **整个事务回滚** ⇒ 心跳持续「成功」而镜像**永不再更新**\n —— 比现在的间歇擦除更糟（旧内容看起来正常，且三重静默都不响）。\n ⇒ 治法: 迁移必须是**显式重建表**（建新表含新 PK → INSERT SELECT 拷贝 → DROP 旧 → RENAME），\n 并配一条**断言实际 PK 的判据**（查 sqlite_master / PG information_schema）——\n 因为今天没有任何判据能发现「PK 没换成」。\n```\n" } ] }