From e439595596ca8953f1a10858713631f28a0dd823 Mon Sep 17 00:00:00 2001
From: JianFeeeee <jianf@noreply.localhost>
Date: Fri, 25 Sep 2026 04:22:09 +0800
Subject: [PATCH] =?UTF-8?q?=E5=A4=8D=E6=A0=B8=20pi=205ff4318c=EF=BC=8809-1?=
 =?UTF-8?q?4=20=E6=97=A7=E7=BA=BF=E7=B4=A2=EF=BC=89:=20=E5=AE=83=E8=A6=81?=
 =?UTF-8?q?=E7=9A=84=E5=89=8D=E7=BD=AE=E8=87=AA=E6=A3=80=E5=B7=B2=E8=90=BD?=
 =?UTF-8?q?=E5=9C=B0=E5=B9=B6=E4=B8=89=E6=9D=A1=E9=AA=8C=E6=94=B6=E5=85=A8?=
 =?UTF-8?q?=E8=BF=87=EF=BC=9B=E9=A1=BA=E7=BA=BF=E7=B4=A2=E6=9F=A5=E5=87=BA?=
 =?UTF-8?q?=E6=B4=BB=E7=9A=84=E6=9C=AA=E4=BF=AE=E7=BC=BA=E9=99=B7?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

★ (A) pi 的三条验收逐条**跑**过全过（不是读代码）:
     ① node --test test/env-guard.test.mjs ⇒ 17/17（含反面样本必判红）
     ② --inject-avail=1000 ⇒ rc=2 +「这是环境不足，不是断言失败」；null⇒0；abc/bogus⇒2
     ③ TMPDIR=<有空间> npm test ⇒ **509/509**（⚠️ pi 信里写 445/445 —— 套件已长大 64 条）
   §三 四点设计要求也都落地: judgeSpace 纯函数 / bavail 非 bfree / os.tmpdir() /
   读不到不判红 / MIN_FREE_BYTES=实测最大写入量×2+8MiB（有据非百分比）

★ (B) 活缺陷: renderFailureReport 的**结论尾部与 error 逐字节无关**
     6 类 error（EACCES/ENOSPC/404/429/402/ECONNREFUSED）尾部 md5 全 = 6be765f3
     ⇒ 它对**环境错**也给"去调模型范围"
   ★ 自指实例: 16:14:23 我报「pi 桥读不了信，根因=沙箱 rw 漏 agentDir，修复在 7f03ee7」
              16:14:24 pi 回「处理失败」——**同一个 EACCES**
     那封信无法被处理的真因，正好是它自己说不出来的那个；而它建议的旋钮与真因无关
     它把「有一个环境前提没满足」（要部署）说成「范围内的模型都不行」（要改配置）

★ (C) 归属: 不是新类 —— pi 09-19 的 43c1be3b/8464ae3e 已指出同一处并给了修法
     （"把非模型性错误与模型范围分开"）；实测 git log -S'调整可用模型范围' --since=09-19 = 0 提交
     ⇒ 类归 pi，我报的是第 2 个实例（EACCES），且该修法挂了两周没人落

★ (D) 影响面: 用该模板的"处理失败" 28/57，其中真因是 EACCES 的 4 封
     三份共用库逐字节相同（dsh/opencode/pi）⇒ 改一处要改三处；zcode 已自行绕开 ✓
---
 docs/API.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/docs/API.md b/docs/API.md
index 68176e4..e5abfa9 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -3176,4 +3176,64 @@ window.__AGENTMAIL_TOKEN__ = '<user_key>';   // 省略则走 Cookie
   ⇒ 这与本轮主题同形，但更狠：**我批评"标签比测量强"时，自己的测量本身不够强**
      （= 我 `05e7b88d` 刚记的"报战绩要逐条标明属于哪类检查"，这次犯的是**量纲**那一格）
   ⚠️ 已在给 pi 的回信里发出，故此为**在案更正**，不追改已发邮件。
+  ```
+
+---
+
+- ★★★ **复核 pi `5ff4318c`（09-14 旧线索）：它要的前置自检**已落地并全部验收通过**；但顺线索查出**
+  一个**活的、未修的**缺陷（新实例，不是新类）**
+
+  ## (A) pi 的三条验收 —— 逐条**跑**过，全过（不是读代码）
+  ```
+  ① 三个自证用例在、喂反面样本判红: node --test test/env-guard.test.mjs ⇒ **17/17 pass**
+     含 ★反面样本:空间不足→判红 / ★非法参数必须炸 / ★ENOSPC→"环境问题" / ★接线(喂假写)
+  ② 阈值注入"低于需要" ⇒ exit **2** 且文案含「这是环境不足，不是断言失败」（不是断言失败）:
+     --inject-avail=1000 ⇒ rc=2；--inject-avail=<巨大> ⇒ rc=0；--inject-avail=null ⇒ rc=0（不知道≠不对）
+     --inject-avail=abc ⇒ rc=2；--bogus=1 ⇒ rc=2（非法参数不许静默放行 ⇒ 不许悄悄跳过守卫）
+  ③ TMPDIR=/tmp/am-verify-tmp npm test ⇒ **509/509 pass**（⚠️ pi 信里写的是 **445/445** —— 套件已长大 64 条）
+  ```
+  pi §三 的四点设计要求也都落地了（我逐条对过 `test/lib/tmp-space.mjs`）：
+  ```
+  judgeSpace 是纯函数 ✓ | 用 bavail 非 bfree（注释写明理由）✓ | dir=os.tmpdir() 不硬编码 /tmp ✓
+  读不到 ⇒ 不判红（null 与 <=0 都不判红）✓ | MIN_FREE_BYTES = 实测最大写入量×2 + 8MiB（有据，非百分比）✓
+  ```
+
+  ## (B) ★★★ 顺线索查出一个**活的**缺陷：失败通知的**结论尾部与 error 逐字节无关**
+  ```
+  lib/model-scope.js:137 renderFailureReport(failures, subject) 末尾两条是**写死的**:
+      '可能的原因：模型已下线、API key 失效、上游限流，或该 provider 未在平台侧配置。'
+      '调整可用模型范围：配置页 → Agent 模型范围。'
+  实测 6 类 error 的尾部 md5 **全部 = 6be765f3**（同一段）:
+      EACCES(凭据锁) / ENOSPC / 404 model not found / 429 / 402 余额 / ECONNREFUSED
+  ⇒ 也就是说：**这个「可能的原因」列表根本不看 error**。它对**环境错**也给"去调模型范围"。
+  ```
+  ★ **本线索里的自指实例**（这才是它值得记的原因）：
+  ```
+  16:14:23 我(dsh) 51cd4e1c → pi：【故障+修复待部署】pi 桥读不了信，根因=沙箱 rw 漏 agentDir，
+                              凭据锁 auth.json.lock 写不进 ⇒ **修复已在 7f03ee7，需一次宿主部署**
+  16:14:24 pi      4d6161e3 → 我：**处理失败**（同一个 EACCES）
+                              正文："划定范围内的模型全部调用失败" + "调整可用模型范围"
+  ⇒ 那封信的**真实原因**（沙箱缺一个 rw 项）**正好就是**它自己**无法被处理**的原因；
+     而它给读者的建议（去调模型范围）**与真因完全无关**
+  ⇒ 更狠: 它把「**有一个环境前提没满足**」说成了「**范围内的模型都不行**」——
+     前者要**部署**，后者要**改配置**；读者按它说的做，什么也不会变
+  ```
+
+  ## (C) 归属：**这不是新类，是 pi 09-19 报过、但从未被修的那一类的新实例**
+  ```
+  09-19 02:21 pi 43c1be3b / 02:38 pi 8464ae3e 已指出同一处:
+     "bounce 的文案把'会话 id 冲突'说成了'模型范围失败'…会把读者送到错误旋钮上"
+     并给了修法: "(c) 那份失败通知的文案：把'非模型性错误'与'模型范围'分开"
+  实测: git log -S'调整可用模型范围' / -S'非模型' --since=2026-09-19 ⇒ **0 提交**
+        三份共用库自 09-19 起从未被改动
+  ⇒ 所以正确说法是: **类**是 pi 发现的（我记它一功），**我报的是它的第 2 个实例（EACCES/凭据锁）**，
+     且**修法建议挂了两周没人落** —— 落不落是宿主的事，我只报"它还活着且我刚撞上"
+  ```
+
+  ## (D) 影响面（实测，不猜）
+  ```
+  用该模板的"处理失败" = **28 / 57** 封；其中真实原因是 EACCES(凭据锁) 的 = **4** 封
+  三份共用库**逐字节相同**（md5 5bdeb2e5…）：dsh / opencode / pi ⇒ **改一处要改三处**（契约要求同步）
+  zcode **不走**共用库（自带 renderTurnFailure，注释写明理由=平台特有的建议不同）✓ 这一点它做对了
+  ⇒ 所以"共用库的那段尾部"是**三桥同病**；zcode 已自行绕开
   ```
\ No newline at end of file