From 682bcf3d45f7fa8cbc109cac9d1e906a23ce3345 Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Sat, 26 Sep 2026 01:44:26 +0800 Subject: [PATCH] =?UTF-8?q?docs(debt):=20=E7=99=BB=E8=AE=B0=E3=80=8C?= =?UTF-8?q?=E5=B9=B3=E5=8F=B0=E9=95=9C=E5=83=8F=E7=9A=84=E6=9B=BF=E6=8D=A2?= =?UTF-8?q?=E5=9F=9F=E8=BF=87=E5=AE=BD=E3=80=8D=E2=80=94=E2=80=94=20agent?= =?UTF-8?q?=20=E7=BA=A7=E6=95=B4=E8=A1=A8=E6=9B=BF=E6=8D=A2=20vs=20per-pro?= =?UTF-8?q?ject=20=E4=B8=8A=E6=8A=A5=E8=80=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 现象（实测，可复现）: agent_platform_sessions 在 10 个状态间轮换，每次差的恒为一个 project 的会话数 （/tmp=49 /root=38 am-mcp-probe=23 agentmail=37 TrueAgent=100 llmsproxy=18 facemodule=7 Liquid=7 NextAgent=2 空），同状态内 reported_at span = 0.0ms ⇒ 每次都是**整表替换**，而每个上报者只知道一个 directory ⇒ 后一个把前一个的清单整体擦掉 危害（口径已修正）: 候选 = 来源1(本侧 sessions, 实测 6) + 来源2(该镜像, 实测 37) 镜像被擦时该 workspace 的候选 ~43 → ~6（掉 37 条），**不是归零** （先前写 37→0 是漏了来源1） ★ 为什么记的是「到期前提」而不是「修法」: 它是**带顺序约束**的: 若只给 DELETE 加 workspace 而 PK 不动，则 「同一 platform_id 出现在两个 workspace」⇒ UNIQUE constraint failed (1555) ⇒ INSERT 无 ON CONFLICT(grep=0) + defer Rollback ⇒ **整个 DELETE 回滚** ⇒ agents.go:186 降级 -1、桥不读该字段(grep=0) ⇒ 三重静默 ⇒ 从「间歇擦除」变成「永不自愈的静默停滞」（更难查） 故到期前提写死为: **先 PK 加 workspace，再 DELETE 加 workspace** 三个已被推翻的根因（留作反面材料，见 note）: ① 「读域 vs 擦除域，且 [] 是 truthy」——非主因（80% 是非空替换） ② 「擦除在语义上不必要」——错，整表替换有意且有 TestReplacePlatformSessionsIsFullReplace ③ 「今天不撞靠 session.id 全局唯一」——因给错了，实测同 id 换 workspace 也不撞， 真正原因是「全量 DELETE + seen 去重」两处代码结构 校验: go test ./internal/repo/ -run Debt ⇒ PASS（余额 27，新条已计入） --- docs/DEBTS.json | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/DEBTS.json b/docs/DEBTS.json index 5757095..9b3e6cb 100644 --- a/docs/DEBTS.json +++ b/docs/DEBTS.json @@ -194,6 +194,14 @@ "where": "待建。落点取决于抑制修法落在哪一层（`server/internal/repo/relayhops.go` 的 `CountTrailingRelayHops` 一族 / 发送侧桥）；口径复算工具在 `deploy/recount-relay-counts.sh`", "kind": "scope", "note": "★★ 2026-09-25 pi 提出（`a948cdbb`）、我复核确认并登记。**这条钉的是机制，不是当下恰好成立。**\n\n## 当前为什么「看起来不需要它」\n```\nB 口径（agent, failure-父链根）: 98 封 → 92 组、抑制 **6**\n 组内「两个成员共享同一父」的组数 = **0**（我逐组实测）\n ⇒ 5 个多成员组**全是真链式**（成员互为父子链），今天确实不会误合并\n```\n★ 但那是**当前数据的性质，不是设计的保证** —— 只要出现「同一封来信被两个不同 agent 各回一封失败报告」（或同一 agent 对同一封回两次），root-keying 就会把它们合并掉，而那些是**内容各异的并列失败**。\n\n## 这形状在本系统**真实发生过**（所以不是假想）\n```\nsession d042cc4c: 22 封失败报告、**22 个 parent 两两不同**\n (agent, 线程根) 口径 ⇒ 塌成 4 组（9/7/5/1）⇒ 一次**丢 18 封**\n 其中只有 1 个 parent 本身是失败报告 ⇒ **21 封是并列**\n```\n⇒ 「同级并列」不是边角情况。判据② 定稿即按此: **22 封并列失败、（线程根误用下）塌成 4 组、一次丢 18**。\n\n## 与已否掉的修法的关系（避免下一个人重走）\n```\n✗ 修法① 跳过 kind=summary —— 实测恰好豁免它要拦的那一类（该环 100% summary）\n✗ 修法②（仅根 root-keying） —— 就是本条要防的那个: 会吞并列\n△ relay_key 前缀判「是否失败报告」—— 诊断成立，但**服务端语义变更**，待人或宿主定\n```\n⇒ 本条不预设修法；它只要求: **无论选哪种，并列失败不得被合并**必须有判据。\n★ 这就是它该进登记而不是只留在邮件里的原因: 一个没有执行者的结论会一直「在讨论」，而登记 + 到期条件会让接手的人**必须**遇到它。\n\n## ★★ 2026-09-25 追加（我实测）：本条的**前置**问题 —— \"是不是失败报告\"这个谓词**没有载体**\n\n在讨论\"用哪种 keying 抑制\"之前，先要回答\"**这封是不是失败报告**\"。我把它的**全部产生点**查了一遍 —— 它散在 **8 条语句 / 5 个文件 / 3 种语言**，且**写法互不相同**:\n```\nplugins/dsh-mail-bridge/src/index.ts:1240 model-failure:${data.mail_id}\nplugins/dsh-mail-bridge/src/index.ts:1749 **empty-reply**:${mailSessionID}\nplugins/pi-mail-bridge/src/worker.mjs:625 model-failure:${...}\nplugins/pi-mail-bridge/src/worker.mjs:715 model-failure:${...}\nplugins/zcode-mail-bridge/src/index.mjs:304 zcode-failure:${...}\nplugins/homeagent-mail-bridge/plugin.go:929 \"homeagent:failure:\"+replyTo ← Go\ndeploy/service-failure-notify.mjs:92/94 service-failure:${INVOCATION_ID|sha256} ← systemd 脚本\n```\n而**网关侧对它一无所知**: `grep -c` 这四家前缀 + empty-reply 于 `server/**/*.go` = **0**。\n\n★ 所以\"拿现成的 `RelayKeyForMail` 判一下就行\"只对一半 —— 它返回 `(relay_key, kind)`，而 **`kind` 区分不了失败**:\n```\nfailure 行的 kind 分布: kind=**summary** | 98 ← 全是 summary\nkind='summary' 内部: failure 98 / **非failure 321**\n⇒ 用 kind 判 ⇒ 会连 321 行普通搬运一起豁免 —— **正是已否掉的修法①**\n```\n\n★★ **活的反例**（这条最关键）: `empty-reply:` 是失败类但**不含 `failure` 字样** ⇒ `LIKE '%failure%'` **永远抓不到它**（该路径代码 1 处、当前 **0 行** ⇒ **将来第一次触发就是静默漏判**）。\n\n⇒ 推论: 若在网关里硬编码这四家前缀，第 6 家桥出现时**静默漏判**，后果是\"报告不再被抑制\" ⇒ 环回来（**假绿**）。\n⇒ 所以修法应先把**分类变成网关拥有的东西**（relay 枚举加第三类 / 或 relayed_mails 加一列），再由各桥**声明**而非拼串。\n\n⚠ 加枚举会撞上一条**故意**的锁: `TestRelayKindsIsExactlyTwo`（`relay_test.go:60-64`）\"免配额类型是白名单…新增前请确认它确实是 harness 代劳\" ⇒ 必须同步改它，而那正是它**本来就该问**的问题（failure 确实是 harness 代劳）。\n\n## ★★ 2026-09-25 追加（判据清单落定）：⑥ permission 分叉点，**必须**钉住\n\npi `8f6f6e6e` 提出、我 `476d22ad` 复核后定为判据清单的第六条。\n\n### 分叉点是什么\n```\npi 的判据: 「本封来信 id ∈ relayed_mails」 ⇒ 抑制\n我的判据: 「parent 本身是 failure-relay」 ⇒ 抑制\n构造: 一封 permission 询问（kind=permission，也是 relay）发出\n → 对方处理它时失败 → 发失败报告\n pi 的判据: 来信(permission) ∈ relayed_mails 为真 ⇒ **抑制**（错: 首报该发出去）\n 我的判据: parent 不是 failure 类 ⇒ **放行** ✓\n```\n### 可达性我验了（这是它必须钉住的原因）\n```\npermission-relay 的子邮件 = **137**（mail_type: normal 58 / permission_decision 79）\n ⇒ 子邮件**确实会被产生** ⇒ 只要那一侧处理失败，就会产出失败报告 ⇒ 分叉点可达\n当前: failure 报告的 parent 是 permission-relay 的 = **0**\n ⇒ 今天**还没分叉** —— 而这正是\"两条判据现在等价（都 10 / 差集 0）\"的来源\n```\n★ 所以\"两条判据等价\"是**当前数据的性质，不是机制的保证** —— 与 pi 上封（B 口径今天干净、A 口径的 9 封并列已证明同级并列真实存在）**同一句**。\n⇒ 选判据的理由**不能是\"它们现在等价\"**，而是: **我的判据把\"是不是失败类\"这件事读了出来，pi 的没有** —— 信息量更大的一点更耐久。\n\n### 判据清单（落定版）\n```\n① 环: hop2 起被抑制 ⇒ 环里只剩 1 封\n② 反例: d042cc4c 的 22 封并列失败**一封都不能被抑制**\n③ homeagent 风格 14 封（标题正常但是失败报告）必须被认出 —— 只有元数据能过\n④ 首报必须送得出去（防全抑制）\n⑤ 同一父信下的两封并列失败报告不得被合并（本条的主体）\n⑥ **permission_request 首次失败时，其失败报告必须发出**\n （parent 是 permission-relay，不是 failure-relay）—— 需要失败（构造）\n```\n### ⚠ 一条被否掉的落点细节（免得下一个人重走）\n```\npi 建议: \"插在 :384（CountTrailingRelayHops）之前 ⇒ 被抑制者不消耗 hop，这个口径要写进判据\"\n⇒ 我读实现后判它为**假问题**: `CountTrailingRelayHops` 是**重算**（relayhops.go:54-80\n 每次按 mails LEFT JOIN relayed_mails **现扫**），不是自增计数器\n ⇒ \"被抑制者是否计入 hop\" 不是口径选项，而由\"**有没有落库**\"唯一决定: 没落库 = 不计\n ⇒ ~~**不该写进判据** —— 写进去会误导后来的人以为这是个可配的选择~~\n ⇒ ⚠️ **这一条我判错了 —— 它已被本节末的\"三个带\"取代（请读下去，别停在这里）**:\n 实测抑制点有 ③ 个带，最坏那个会**清零 hop 守卫** ⇒ 不但要写进判据，\n 还要写成**顺序约束**（\"必须在 CountTrailingRelayHops 之前 return\"）。\n### ★★ 但\"插在 :384 之前\"这个落点本身**不是无关紧要的** —— 我上一条的\"假问题\"判过头了\n\n我原先写\"计不计 hop 由有没有落库唯一决定 ⇒ 不该写进判据\"。**那半对，但漏了两个形** ——实测（`/tmp/hop.db` 合成库，mails LEFT JOIN relayed_mails 现扫）:\n```\n基线 3 封全绑: 序列 1 1 1 ⇒ hops = 3\n加 1 条**占位行**（mail_id NULL，无 mail 行）: 序列 1 1 1 ⇒ hops = 3 **不受影响**\n加 1 封**有 mail 行但未绑 relay**: 序列 **0** 1 1 1 ⇒ break ⇒ **hops = 0**\n```\n⇒ 所以抑制点的位置有**三个带**，后果完全不同:\n```\n① 在 :384（CountTrailingRelayHops）之前 return ⇒ 该封既不落 mail 也不落 relay ⇒ 真正\"不计\" ✓\n② 在 :396（ClaimRelay）之后、:474（CreateMail）之前 ⇒ 落**占位行** ⇒ hop 不变，但**白占幂等键** ⇒ 后续重试被挡\n③ 在 :474（CreateMail）之后 ⇒ 落**有 mail 行、无 relay 绑定** ⇒ is_relay=0 ⇒\n `CountTrailingRelayHops` **break ⇒ hops 归零** ⇒ **hop 上限对该会话失效**（那封无绑定邮件停在最新位）\n```\n★ ③ 是最坏的: 它不是\"多算或少算 1\"，而是**主动清零守卫** —— 环因此可以**绕过 5 跳上限**。\n而 ③ 正是\"抑制逻辑写在 CreateMail 之后\"这种最自然的写法会落进去的带（因为那里才拿到 mailID）。\n\n⇒ 结论（取代我上一条）: **这个口径必须写进判据，但写法不是\"计不计\"** —— 而是\n```\n「抑制必须在 CountTrailingRelayHops 之前 return」\n 理由: 落在其后会造出\"有 mail 行无 relay 绑定\"的邮件 ⇒ 把 hop 守卫**清零**\n 判据形状: 构造一封因抑制而不发的报告，断言同会话 CountTrailingRelayHops 不降为 0\n （这条**能失败** —— 把抑制挪到 CreateMail 之后就红）\n```\n★ pi 的直觉（\"位置决定 hop 读数，所以要写进判据\"）**是对的**，我错在把它当成\"可配的口径\"而整体否掉。正确的是: 它不是口径，是**必须满足的顺序约束**，而顺序约束**更要**进判据。\n```" + }, + { + "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` 对 `[]` 为真 ⇒ 空清单也走整表替换。", + "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" } ] }