jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-09-28 05:13:27 +00:00
Code Issues Packages Projects Releases Wiki Activity
718 Commits 5 Branches 27 Tags
79c15f0452f4bd08b6ccc1b8b2216f97f418e8f2
Commit Graph

718 Commits

This Branch
This Branch
All Branches
Author SHA1 Message Date
JianFeeeee
79c15f0452 test(webui): 压测补齐另外 3 个插件的路由 —— 我第一版漏了两个 
第一版只压了 webui 的 `/api/v1/*`。核实后发现 **8080 上注册 HTTP 路由的
插件有 4 个，监听端口还不止 8080**（`ss -ltnp` 实测）：

| 端口 | 插件 | 路由 | 认证 |
| --- | --- | --- | --- |
| 127.0.0.1:8080 | webui | /api/v1/* | config_webui.api_key |
| | remotedevice | /api/v1/device/* | config_remotedevice.ws_token |
| | kbtree 子路径 | /api/v1/knowledge/tree/{categories,counts} | config_webui.api_key |
| 127.0.0.1:9876 | **pluginmgr** | /plugins（**无** /api/v1） | **无需认证** |
| 127.0.0.1:9892 | **kbtree** | /categories /counts（**无**前缀） | config_kbtree.token |
| 127.0.0.1:9890 | remotedevice | 设备 WS 网关（非 REST） | 不压 |

⇒ 「打 /api/v1/*」这个假设只对 8080 上的 webui 成立：`:8080/plugins`
实测 **404**。三套认证各不相同，脚本现在按分组取对应 token。

## 端点 18 → 24

新增：`/api/v1/device/online`（remotedevice）、`/plugins`（pluginmgr）、
`/categories` `/counts`（kbtree 根路由）、以及 webui 前缀内的
`/api/v1/knowledge/tree/{categories,counts}`。

收 `/api/v1/device/online` 之前逐行读过实现：仅 `GET` +
`registry.OnlineList()`，纯读。**不收** `/device/push`（向真实设备下发）、
`/device/ws`（长连接）、`/device/{id}`（语义未核实）。

## 实测（24 端点 × 3 档，2880 请求零失败）

| scale | 请求 | 吞吐 | p50 | p95 | p99 | max | 成功 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | 480 | 953 req/s | 4.0ms | 23.0ms | 34.7ms | 40.6ms | 480/480 |
| 2 | 960 | 1310 req/s | 7.9ms | 32.4ms | 48.4ms | 72.3ms | 960/960 |
| 3 | 1440 | 1422 req/s | 12.0ms | 42.7ms | 60.5ms | 88.7ms | 1440/1440 |

压测期间服务端 `active`、0 个 5xx。

**p99 随并发单调上升**（34.7 → 48.4 → 60.5ms），符合排队预期。
上一轮曾出现 scale=2 的 p99 反常地高于 scale=3，当时机器上另一个 agent 的
chromium 占 766% CPU ⇒ 环境噪声，已明确不作为性能特征。

## 又踩了一次前缀的坑（两种方向都踩了）

1. 「表里存路径后半段 + 代码按 group 补前缀」⇒ remotedevice 拼成
   `/api/v1/api/v1/device/online` ⇒ 落到 webui 兜底路由、
   返回 **200 + 登录页 HTML**（靠 `looks_like_login_page()` 抓到）。
2. 反过来「表里已含前缀 + 代码仍补」⇒ webui 组全 404。

⇒ 最终统一成**表里写完整路径、代码不补**。两次都是靠 `--probe` 抓到的，
这正是它存在的理由。

## 顺带修掉我写错的一处

`contextlib.suppress(sqlite3.connect)` —— `connect` 是函数不是异常类，
`suppress` 会抛 `TypeError`。改回显式 `try/except sqlite3.Error`，
并把 `config.db` 的打开方式保持 `mode=ro`（压测不碰生产库写路径）。

## 文档里我自己写错又改正的一处

§7 表格里 scale=1 一行先写成 1680/2013/5.4ms，核对 JSON 后实为
**480/953/4.0ms**（24 端点 × 20 轮）。已订正，并加了提交前的
JSON 逐项比对，三档现已全部一致。
 2026-09-28 09:33:22 +08:00
JianFeeeee
aed8f1f808 test(webui): WebAPI 只读端点压测 + 实测 2160 请求零失败 
打的是**生产实例** 127.0.0.1:8080。

## 为什么只压只读端点

压测绝不能改状态。18 个端点**逐个探测确认**是 GET + 只读：
小（/status…/proxy/services，104B–1.8KB）、中（/plugins…/knowledge，
4.4KB–53KB）、大（/kernel 157KB、/memory/graph 338KB、/knowledge/tree 425KB）。

**排除**：/chat（真调 LLM）、/chat/interrupt（中断在跑的任务）、
/settings/* 与 /plugins/*（改配置）、/login /logout（改会话）、
knowledge/memory 写接口、/device/*（控制真实设备）。

## ★ 两条判据（都不是"看有没有报错"）

### 1. 必须先 `--probe`：webui 无认证时返回 200 + 登录页 HTML

含 `THEME_PLACEHOLDER`，**状态码是 200**。只看 `http_code` 会把登录页
当成健康响应 ⇒「全部 200」是假的。脚本因此额外校验响应体。

### 2. 端点表漏了 `/api/v1` 前缀 ⇒ 18 个端点全 404

第一版把端点存成路径后半段（`"/status"`），拼出
`http://127.0.0.1:8080/status`，而真实路径是 `/api/v1/status` ⇒
**全部 404**，同一时刻 curl `/api/v1/status` 却是 200。

⇒ **压测脚本必须先 probe 再压。** 不 probe 的话那一跑的结论会是
「webui 全挂」，完全错误。这条已写进手册。

## 实测（2026-09-28）

| scale | 请求 | 吞吐 | p50 | p95 | p99 | max | 成功 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | 360 | 779 req/s | 6.7ms | 26.8ms | 45.5ms | 51.6ms | 360/360 |
| 2 | 720 | 788 req/s | 12.2ms | 52.6ms | 163.0ms | 213.5ms | 720/720 |
| 3 | 1080 | 1038 req/s | 16.4ms | 60.4ms | 79.7ms | 123.0ms | 1080/1080 |

**2160 请求零失败**；压测期间服务端 `active`、0 个 5xx、0 个 webui 错误，
QQ/agent 链路未受影响，homed CPU 仅 1.2%。

### 重响应不是瓶颈（并发 1 → 16）

| 端点 | 大小 | 并发 1 | 并发 16 | 吞吐 |
| --- | --- | --- | --- | --- |
| /status | 0.2KB | 104 req/s | **1781 req/s** | 320KB/s |
| /kernel | 153KB | 126 req/s | 375 req/s | 19 → **57 MB/s** |
| /memory/graph | 330KB | 70 req/s | 410 req/s | 23 → **135 MB/s** |
| /knowledge/tree | 415KB | 79 req/s | 717 req/s | 33 → **297 MB/s** |

大 JSON 端点的 p50 **不随并发上升**（/knowledge/tree 12.3ms → 8.9ms，
排队更充分、效率更高）⇒ 瓶颈不在 JSON 序列化。

## ⚠ 一处未下结论的观察

scale=2 的 p99（163ms）反而**高于** scale=3（79.7ms）。看着反常，但当时
机器上另一个 agent 的 chromium 占 **766% CPU**（另有 cjpm/cjc 在编译）
⇒ 是**环境噪声**。

**未在可比条件下重测就不下结论** —— 不拿这一组当性能特征。要判定需先
固定负载条件再跑。这条也写进手册。

## 顺带

ruff 报的三条 blocker 都修了：`pct()` 空样本不再抛错（调用方直接拿去做
f-string 格式化）、写 JSON 失败明确报错而非静默丢报告、错误体读取用
`contextlib.suppress` 免得二次异常盖掉真正的状态码。
 2026-09-28 09:22:16 +08:00
JianFeeeee
ee5cb75e00 fix(gui): 401 重试无限递归 —— 我上一个优化放大的 bug 
## 真机实测发现的

Xvfb + Electron + CDP 真跑，发现 `api()` 的 401 分支**无限自我递归**：

    第1次: lock=false → 重登 → lock=false → return api()   ← 递归
    第2次: lock=false → 重登 → lock=false → return api()   ← 又递归
    …

那把锁的语义本该是「已经重登过一次，别再登」，但它在递归**之前**就被
清掉了 ⇒ 每层递归看到的都是 `false`。真机实测 **fetch 被调 13 次、
重登 12 次**才被我的探针上限截断。

## 为什么这与我的上一个提交直接相关

`1ef1998` 把 401 分支的固定等待从 800ms 降到 30ms（修「认证过期时每个
请求白等 0.8s」）。但重试**没有次数上限** ⇒

- 改前：每 800ms 慢速空转
- 改后：每 30ms 快速烧 CPU + 反复打服务端

**我的优化把这个 bug 放大了。** 真机上探针调用 `api()` 直接挂死，
我起初还以为是我的测试写法问题。

## 修法

两处递归点（真 401 / 门户返回 200 但内容是登录页）都改成：

    try {
      return await api(p, o);
    } finally {
      window._haReloginLock = false;
    }

`finally` 保证递归抛错时也释放锁 —— 否则会把后续所有请求都锁死成直接 401。

## 判据 retry-guard.test.mjs

在 `node:vm` 沙箱里跑**真实抽出的 `api()`**，用恒回 401 的 `fetch` 驱动，
统计真实调用次数。

### 写这条判据时踩的四个坑（都记在文件里）

1. **先给了假绿灯**：把 401 分支当独立函数体执行，但那块以
   `return api(p,o)` 结尾、外面没有调用它的上下文 ⇒ 我从未真正进入那个
   `if` ⇒ `api 递归=0` ⇒ 什么都没测到。改成跑**真实 api()** 才对。
2. **递归时忘了保持 `r.status===401`**：真实场景是「重登后凭据仍是错的」。
   漏了它 ⇒ 递归那层不进 401 分支 ⇒ 又一次假绿灯。
3. **沙箱 `setTimeout` 只记录不执行**：`api()` 用它做超时控制
   （`setTimeout(() => ctl.abort(), to)`）⇒ AbortController 永不被 abort
   ⇒ 表现为「fetch 只调 1 次、8000ms 被当成 401 等待」。
4. **沙箱缺 `clearTimeout`** ⇒ 抛 `clearTimeout is not defined` ⇒
   整段在 fetch 之后就断了 ⇒ 永远走不到 401 分支。

★ 共同点：**沙箱不完整 ⇒ 静默地什么都没测 ⇒ 假绿灯**。
判据自己给假绿灯比没有判据更危险。

### 变异测试（精确锚点，验证判据真能抓）

把第一处 try/finally 退回「递归前清锁」⇒ 判据立刻红
（`fetch 被调 13 次`）；恢复后全绿。

★ 第一次做这个变异时我误判「判据漏抓」—— 实际是我的变异脚本用了模糊
锚点、**压根没改到文件**（`grep` 显示 return await 从 2 变 1，但 `sed`
命中的是另一处）。两个信号矛盾时先坐实文件状态，别急着改判据。

## 顺带把 `make test` 的门禁修好（9c3d285 / f59a3cf 之外）

新判据已接入 `npm test`，实测 14 项通过、`make test-gui` 全绿。
 2026-09-28 09:11:58 +08:00
JianFeeeee
56023e31c4 docs(runbook): 记「判断线上跑哪次构建」的正确判据（我今天差点白部署） 
## 线上其实已经是修好的版本

去部署 `d084137`（webui 总览 5 个 KPI 空）前核实，发现：

    /api/v1/status → {"commit":"d084137", "startedAt":"2026-09-27T23:23:39"}

23:23 那次部署**不是我做的**（我只在 21:50 部署过），已经包含
`d084137`。`/api/v1/kernel` 里 5 个 KPI 依赖的字段也全部有值
（`plugins` 39 个、`llm`/`memory`/`documents`/`runtime`/`onnx` 非空）。

⇒ **不需要部署。**

## ★ 为什么 `strings` 不能用来判断

webui 等插件的静态资源是 `//go:embed` **编译进二进制**的
（`internal/plugins/webui/handler.go:27`），内容取决于**构建时**磁盘上的
文件。⇒ 已提交但未部署的改动，线上二进制的 `strings` 里**也可能**
出现新代码片段。

我据此差点白重启一次生产。同一天还撞上**字节数完全相同**的巧合
（86811464），更掩盖了这点 —— 大小相同更让人以为"没变化，不用管"。

## 正确的判据顺序

1. `/api/v1/status` 的 `commit` —— 线上在跑什么
2. `git log <commit>..HEAD` —— 差哪些提交
3. 那些提交里**有无运行时改动**（`internal/`、`cmd/`）—— 只有它需要部署
4. 文档 / 判据 / 部署脚本类提交**不需要**部署

## ⚠ 那条命令必须带认证头

无认证时 `/api/v1/status` 返回**登录页 HTML**（200 + `THEME_PLACEHOLDER`），
`grep '"commit"'` 匹配不到 —— 看起来像"命令没输出"，实际是认证缺失。
与 GUI 客户端 `api()` 专门检测 `THEME_PLACEHOLDER` 是同一件事。

## 顺带：内置插件 vs 独立二进制

`internal/plugins/<name>/` 编译进 homed；`plugins/<name>/plugin.bin`
是独立插件，要单独构建部署。**目录存在不等于有独立二进制** ——
`plugins/webui/` 目录存在但 **0 个文件**，走内置。

实测（2026-09-28）：`webui`/`cmd`/`seq` 内置，`qq` 独立。
改内置插件只需重编 homed。
 2026-09-28 08:52:12 +08:00
JianFeeeee
4bd2355991 feat(watch): 站点漂移巡检（只读，有差异才提醒） 
`site-drift-watch.sh` 巡检 192.168.2.106 上的两个站，**只读不动**：
不构建、不上传、不碰线上任何文件。档位是「有差异就提醒」而不是
「自动推」—— 文档站发错了是公开可见的，宁可等人点一下。

判三类信号：
1. 线上漂移：.106 上的站 ≠ 本机产物/site 源（逐字节 md5 清单比对）
2. 源码漂移：git HEAD 比产物新 ⇒ 提交了但没重新构建部署
3. 探活失败：.106 或 NapCat 挂了（比文档漂移紧急）

不复用 `deploy-sdk-site.sh --check`：那脚本输出是给人看的彩色文本，
拿来当机器判断依据太脆（改个文案就失效）。md5 清单逻辑很短，
这里复刻一份并在注释里指向 deploy-sdk-site.sh 保持同步。

## `.drift-watch/` 加入 .gitignore

里面的 `state` 是运行时状态（含时间戳与指纹，每次跑都变），不该入库。

## 提交前核实（两处我的检查写错了，脚本本身没问题）

- 我查"凭据"命中 1 处 ⇒ 实为注释里的「烧 token」，指 LLM token 非密钥。
  真实密钥形态（`sk-*` / `password=`）**0 处**。
- 我查"部署调用"命中 6 处 ⇒ 全是**注释与提示文本**（提醒人去跑
  `deploy-sdk-site.sh`）。实际执行 `rsync`/`scp`/调用部署脚本**均 0 处**，
  `rm -rf` 0 处 —— 与它「只读」的声明一致。
- `set -uo pipefail` 少了 `-e`：**有意为之**。巡检要在某项检查失败时
  继续跑完其余项，`-e` 会中途打断。实测跑一次四项全绿、无差异。
 2026-09-28 08:45:03 +08:00
JianFeeeee
f59a3cf376 fix(make): test-gui 不再被前序失败短路（门禁曾形同虚设） 
## 问题

`make test` 原本是 make 的**依赖链**：

    test:
    	$(GO) test ./...
    	@$(MAKE) test-gui
    	@$(MAKE) csrc-test
    	...

`go test ./...` 一旦 FAIL，make **立即中止** ⇒ 挂在它后面的目标一行都不跑。

实测坐实：`internal/plugin/proc` 偶发 FAIL 时，`make test` 的日志里
**找不到 test-gui 的任何输出** —— 刚接进去的 GUI 判据根本没被执行。
门禁挂上去等于没挂。

## 为什么不能简单用 `-@$(MAKE) test-gui`

`-` 前缀会**吞掉 GUI 判据自己的失败码** —— 判据红了 make 照样绿，
等于给假绿灯。那比短路更糟：它让人以为门禁在生效。

## 做法

全部跑完，最后统一判退出码：

    test:
    	@rc=0; $(GO) test ./... || rc=$$?; \
    	 $(MAKE) test-gui || rc=$$?; \
    	 $(MAKE) csrc-test || rc=$$?; \
    	 $(MAKE) check-csrc || rc=$$?; \
    	 $(MAKE) check-codec-cgo-only || rc=$$?; \
    	 exit $$rc

既保证每一步都跑，也保留每一步自己的失败。

## 验证（注入失败实测，不是推断）

往 `TestKillReturnsEvenWhenGrandchildSurvives` 里塞 `t.Fatal` 制造必然失败：

| 验证项 | 结果 |
| --- | --- |
| `make test` 退出码 | **2**（非 0，失败被上报） |
| proc 包 FAIL | 抓到 |
| **GUI 判据输出** | **仍执行** ← 这是要证明的那件事 |
| csrc-test | 也执行了 |
| 汇总 | ok=43 FAIL=1 |

随后已恢复该测试文件（`git checkout` + 确认 0 处残留 `t.Fatal`），
并复跑该包确认 ok 10.6s。

全绿路径也验过：`make test` 退出码 0、ok=44 FAIL=0、GUI 判据执行。
 2026-09-28 08:43:04 +08:00
JianFeeeee
f5981a2807 docs(make): 记下 proc grandchild 测试本身不稳定（现象，未下根因） 
`make test` 的后置验证里发现 `internal/plugin/proc` 会 FAIL，实测形态：

- 单独跑**同一命令**：`ok 11.5s` / `FAIL` 交替出现（至少各一次）
- 全量并发跑：曾 600s 超时（`panic: test timed out after 10m0s`），
  也曾 90s 就 FAIL
- 失败测试固定是 `TestKillReturnsEvenWhenGrandchildSurvives`，
  伴随日志 `[proc] audit 退出: signal: killed`

与本次改动（1ef1998 SSE 退避、9c3d285 判据）无关联：改的是
`cmd/gui/renderer/app.js` 与判据脚本，没碰 `internal/plugin/proc`。

症状**像** fork/kill 的进程组语义在容器/并发下不稳（孙进程 setsid
脱组后杀不掉 ⇒ Wait 挂死），但**尚未定位到根因**，因此 Makefile 里
只记现象、不下结论。

★ 记这一条是因为我自己先踩了坑：一开始连跑 3 次全绿，我就准备写
「单跑稳定、仅并发偶发」；紧接着同一命令又 FAIL 了。**单跑通过不能
当结论** —— 这类 fork/kill 测试必须重试才能给出可信判断。
 2026-09-28 08:30:44 +08:00
JianFeeeee
9c3d2856a6 test(gui): 行为判据 + 接进 make test（此前无人能跑） 
## 为什么加行为判据

`sse-backoff.test.mjs` 检查源码**形状**（有没有清零、上限自不自洽）。
但形状对 ≠ 行为对：把清零写到 `reader` 取流**之后**，形状检查照样通过，
而实际仍在用旧计数重连。

新判据 `sse-backoff-behavior.test.mjs` 从**真实源码**抽出退避表达式并
在 `node:vm` 沙箱里求值，用假状态记录实际等待。实测量化：

    历史累计 8 次后建连成功再断流 → 等 1000ms（改前会是 32000ms）
    连续 6 次「建连成功→断流」  → 1000,1000,1000,1000,1000,1000ms

## 变异测试（都抓到）

| 变异 | 形状判据 | 行为判据 |
| --- | --- | --- |
| 清零挪进 setTimeout 内 | 通过 | **红** ← 只有行为抓得到 |
| 删掉「建连后」清零 | **红** | 通过 ← 暴露了行为判据的盲区 |
| pump 上限改回 60000 | **红** | — |
| 30ms 改回 800ms | **红** | — |

第二行促成了「行为 0」：建连后清零原本不在被验证的路径上
（抽取锚点只抓 pump 那一处），补了独立检查。

## ★ 判据本身踩的坑（都写进文件注释）

1. **别包假 setTimeout**：`exprSrc` 本身就是延迟数值
   （`setTimeout(fn, <延迟>)` 的第二个参数），包一层让结果恒为 null，
   三项全红。
2. **别用 `new Function`**：等价于 eval，是安全反模式。改用 `node:vm`
   的 `runInNewContext`（官方受限环境，拿不到宿主作用域，带 1000ms 超时）。
3. **一个正则兼容两种幂运算形态会取错捕获组**：`Math.pow(2,x)` 比 `2 ** x`
   多一层括号 ⇒ 组数差 1 ⇒ `r[length-1]` 取到 NaN。
   最终形态是**定位与取值分离**：正则只定位（不捕获数字），数字单独取。
4. **`String.raw` 拼接正则不可用**：`\\.` 保持字面双反斜杠（去找字面的
   "\."），且拼接后捕获组编号不可控。

## ★ 这些判据此前没有任何入口会跑

`cmd/gui` 是**纯 Electron 目录**（0 个 `.go`、无 `go.mod`），Go 通配会
跳过它 ⇒ 判据挂着也没人执行。现已接入：

- `cmd/gui/package.json` 加 `"test"`
- `Makefile` 加 `test-gui` 目标，并挂进 `test`
- 无 node 时显式 SKIP 而不是静默通过

```bash
make test-gui     # 或 cd cmd/gui && npm test
```

## 顺带说明

`go test ./cmd/gui` 报 `no Go files [setup failed]` **不是回归**：
该目录 0 个 `.go` 文件，只有**显式点名**才报。仓库门禁用的三种形态
（`go test ./...`、`go test ./cmd/...`、Makefile 的 `test`）全部通过。
 2026-09-28 08:16:51 +08:00
JianFeeeee
1ef1998e72 fix(gui): SSE 退避计数从不重置 —— 消息流不稳的一个共因 
## 现象

用户报 GUI「消息流不稳、动画不连贯、看着卡」，四类症状都有：滞后、
卡顿、闪断、资源高。定位到**同一个**共因，不是四个独立问题。

## 根因 1：退避计数只增不减

`state._sseRetryAttempts` 的自增只发生在 `connectFetchSSE` 的 catch 分支
（连接**建立**失败），而 `pump()` 中途断流后的重连**只读它算延迟，
从不清零**：

    Math.min(1000 * Math.pow(2, Math.min((state._sseRetryAttempts || 0), 5)), 60000)

后果：只要历史上累计过 5 次，**之后每次断连都固定等 32s** —— 哪怕这次刚
成功连上、说明服务端和网络都好好的。而"成功连上"恰恰是最该重置的信号。

修：建连成功后清零（reader 取流之前），断流重连前再清一次。

## 根因 2：外层 60000 上限是死代码

`2^5 = 32s < 60s` ⇒ `Math.min(..., 60000)` 永远达不到，**真实封顶是 32s**。
改为 32000，让声明值与实际一致（判据会验这一条）。

catch 分支那处保留 60000：它语义不同（连接根本没建起来，attempts 已 +1，
退避本就该更长），上限放宽无害 —— 判据按各自语义分别判定，不一刀切。

## 根因 3：401 重试固定空等 800ms

`api()` 里每个 401 都走 `syncConnAuth()` + 固定 `setTimeout(800)` 才重试。
认证过期时**每个**请求白等 0.8s，并发几个就叠加成明显的「卡」。
`syncConnAuth` 本身就是 await 的，返回即代表凭据就绪 ⇒ 降到 30ms
（留一点让 setAuth 的 cookie 落盘）。

真 401 与「门户返回 200 但内容是登录页」两个分支都有这处等待，两处都改。

## 判据：cmd/gui/sse-backoff.test.mjs

`cmd/gui` 无测试框架（package.json 只有 start/dev），app.js 是 203KB 单文件。
判据从**真实源码**提取退避表达式并求值，而不是抄一份逻辑重写 ——
抄写的那份会和真实代码漂移，而漂移本身就是这个判据要防的东西。

3 项 + 变异测试（删清零 / 改回 60000 / 改回 800ms，三次全部被抓到）。

### 判据本身踩的三个坑（都记在文件注释里）

1. **正则两种形态括号数不同**：`Math.pow(2, x)` 比 `2 ** x` 多一层括号。
   早先只按 pow 写，biome 规范化成 `**` 后**静默失配**。
2. **不能用 String.raw 拼接正则**：`\\.` 保持双反斜杠字面量（去找字面的
   "\."），且拼接后**捕获组编号不可控** —— 实测 cap 解出 NaN。
3. **一个正则兼容两种形态会取错捕获组**（组数差 1）⇒ 改为
   **定位与取值分离**：正则只负责定位（不捕获数字），数字单独取。

### 只认 pump 那处上限自洽

catch 那处 `60000` 不可达但无害（语义是"最多等一分钟"）。
判据对两处**分别**判：pump 要自洽，catch 只要有有限上限。

## 排查时坐实的两件事

- **`go test ./cmd/gui` 报 `[setup failed]` 不是仓库问题**：`cmd/gui` 有
  **0 个 `.go` 文件**（纯 Electron），Go 通配会跳过它，只有显式点名才报。
  `go test ./...` 实测退出码 0、43 包 ok、0 处提及 cmd/gui。
- **biome 会顺手把 `function () {}` 改成箭头函数**（本次混入 12 行）。
  与本次修复无关，已从 HEAD 干净重放，最终 diff 只有 3 处实质改动
  （24 增 3 删，零无关格式化）。
 2026-09-28 07:59:15 +08:00
JianFeeeee
d084137def fix(webui): 修总览 KPI 长期空值（我上轮懒加载改出来的）＋星图改银色 
### ★ 严重问题：总览页 8 个 KPI 里有 5 个是空的
线上实测（https://homeagent.jianfgit.xyz）：
  ["运行中状态","1h 22m 18s运行","0插件","v1.4.0…版本","—LLM",
   "—记忆","—文档","—运行时"]
对照 state：{"status":true,"kernel":false,"settings":0,"runtime":true}

根因是**我上一个提交（d3315c6 按页签懒加载）引入的**：
总览的插件数/版本/LLM/记忆/文档/运行时全部读 `state.kernel`
（`updateOverview` 里写作 `(k && k.plugins)` 这类安全取值），
而我把 kernel 从 overview 的数据块里删掉了。
⇒ 缺数据时不报错、**只显示「插件 0、记忆 —、文档 —」**，
看起来像「服务坏了」而不是像 bug —— 这类静默降级最难自查。

★ 教训（已写进代码注释）：依赖分析必须覆盖**整个调用链**。
我当初只 grep 了 `renderOverview` **直接**读的 state.*，漏了它间接
调用的 `updateOverview`。逐页重核后确认只有 overview 漏配，其余页签
（plugins/settings/kernel 各自要的）本来就是对的。

修复：overview 的 fetch 补回 kernel。kernel 拉过一次后不再重拉
（starmapFetchBlock 的节流），152KB 只在首屏付一次。
实测：["运行中状态","1m 15s运行","17插件","v1.4.0HomeAgent版本",
      "deepseekLLM","1200/893记忆","0文档","39 · 11M运行时"]

### 星图配色改银色（用户裁定）
SM_COLOR_DIM: 0x7d8a9e（灰蓝）→ 0xc8ced8（银色）。
实测 colors: ["7d8a9e"] → ["c8ced8"]

### 关于「页面还是绿色」这个现象
线上内联的颜色实测已是 0x7d8a9e，缓存头也正确
（cache-control: no-cache, no-store, must-revalidate），
浏览器复现同样是灰蓝色 ⇒ 那是**已打开标签页里的旧 JS**：
页面 HTML 变了，但没重新加载的标签页不会自己换。
本提交部署后需**刷新页面**（Ctrl+Shift+R 强刷）才会看到新配色。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
 2026-09-27 23:20:01 +08:00
JianFeeeee
5cc0f53df8 docs(runbook): 补 §6 部署单元清单，并纠正一次误判的记录 
## 补齐漏掉的单元

`cmd/` 下共 7 个可构建入口，服务端只部署 3 个：

| 单元 | 入口 | 服务端部署 |
| --- | --- | --- |
| homed（内核） | `cmd/homed` | ✅ 本机 `/usr/local/bin/homed` |
| waiter / waitercli | `cmd/waiter` | ✅ 106、30 的 `/opt/waiter/waiter` |
| 站点 | `site/`、`site_build/` | ✅ 106 的 `sites/` |
| **GUI** | `cmd/gui` | ❌ **Electron 桌面应用，随客户端分发** |

**GUI 不在服务端部署**（已确认生产无 `*.service`、无进程）。它与 waiter
是两端：GUI 用 `devicebridge_dll.js` 走设备桥协议连服务端 waiter，
`a781f8e` 修的正是 GUI 侧 bind 判 ok 与登记状态暴露。
⇒ 排查 GUI 问题要看**用户机器上的客户端**，不是 `homeagent.service` 日志。

另记：核查"有没有进程"时 `ps -ef | grep -c "[e]lectron"` 会把**自己的
grep 命令行**算进去返回非 0（实测返回 2，实际 0）—— 要看列出的内容，别只看计数。

## 本机 waiter 与 106/30 不同步

本机也留了一份 `/usr/local/bin/waiter`，`v1.3.2-153-gff69127`（2026-09-25
构建），**早于** main 在 09-26 合入的那批修复（设备反复掉线、bind 判 ok、
服务端发现自动链接），因而缺它们。106/30 已是 `1.4.0`。
本机这份无进程无服务，不影响生产设备桥；更新方式已记入文档。

## 记一次误判：判定"是否已合入"要按内容查

我曾用 `git merge-base --is-ancestor ff69127 origin/main` 判定"这批提交
没进 main"，并推断"存在一条未合入、只靠 reflog 撑着的 5 提交线"。**该结论是错的。**

真实情况：这批改动在 2026-09-26 以**新 hash** 重做并进入 main，五对逐字节一致
（diff 均为 0 行）：`1acbd39`→`1e58af7`、`3d30482`→`5d278cf`、
`078517e`→`7f5bf16`、`aaafaac`→`94c74b2`、`ff69127`→`a781f8e`。

⇒ 只查**旧 hash 的祖先关系**会误判；同一改动被重做为新 hash 时
   `merge-base` 必然说不包含，而 `git merge-tree` 报的 13 个"冲突"
   正是同源改动做两遍的必然结果，**不能当冲突去解**。

顺带修正一处归因：106 此前长期无 `online` 日志的成因是
`94c74b2`（设备反复掉线/静默失联：ping 路径断连 + bind 结果无人处理），
2026-09-26 已进 main，今天部署的 `1.4.0` 包含它。
 2026-09-27 23:10:49 +08:00
JianFeeeee
e773f156fb feat(deploy): 站点部署流水线（SDK 文档站 + introduce） 
`deploy-sdk-site.sh` 覆盖两个静态站，与 homed / waiter 是独立部署单元：

- SDK 文档站：本地 `third_party/homeagent-sdk/site_build/` → 106 的
  `/vol1/docker/navi-data/sites/sdk`
- introduce：本地 `site/`（零构建，源即产物）→ `sites/introduce`

用法：`--check`（只核对差异）/ 默认（构建+部署+验证）/ `--rollback <备份名>`。
`--check` 逐字节比对，2026-09-27 核实两站线上与本地产物**完全一致**。

## 更新了一处会误导的注释

脚本原注释写「设备网关白名单只放行 ls/stat/find/cat，打不了包」。
那是 waiter 白名单**硬编码 18 条**时的状况；2026-09-27 部署 7193446 后
106 已扩到 **22 条**（含 find/grep/sed/sort/tr/wc/head/tail/stat/file）。

**结论（打不了包）不变，但理由已变** —— 22 条里**没有 `tar`**，
有 `sed` 也不能打包。照旧文字理解会以为白名单只有 4 条。

## docs/zh/deploy-runbook.md 补 §5 站点章节

- 链路：`.60` nginx stream 按 ssl_preread SNI → 106:3080 → navi 容器内 nginx
  （**不是** portal-nginx，那个已 Exited 两周）
- 坑①：构建**必须**走 `tools/apidoc/build.sh`。裸跑 `mkdocs build` 会丢掉
  整个 `api/*.md` 和 `llms.txt` —— 而 `llms.txt` 正是给 agent 直读的入口。
  正确产物 106 个文件，裸跑只有 78 个
- 坑②：打包不能走设备网关（无 `tar`），必须 SSH 直连
- ★ **新增文档后必须更新 `mkdocs.yml` 的 nav** —— 没登记会被 mkdocs 明确
  警告 `not included in the nav configuration`，等于写完了但站点里不可达
- 验证要打**线上**而不是只看本地产物
- 回滚点与失败版本保留策略

写文档时我一度把 introduce 的域名写成「另见 §5.2」，但 §5.2 只讲了 SDK 的
SNI 链路 —— 已改为只写"同台同目录"，并补上脚本里有依据的"故意不带 README.md"。
 2026-09-27 23:00:04 +08:00
JianFeeeee
175fa9dd62 docs: 新增生产部署手册（homed / waiter） 
`site-infra-runbook.md` 是**静态站 / nginx / 证书**的手册，不含 homed 与
waiter —— 两次生产部署（19:45 首次、21:50 修复）因此只存在于提交信息里，
查不到。

## 内容

**§1 homed**
- 硬前置：必须 `-tags=onnxruntime`（普通 build 只有 ~28MB，缺 ONNX Runtime）
- ★ **构建参数必须与线上一致**：不要顺手加 `-s -w`。加了产物从 86.8MB 掉到
  78MB，8.8MB 的差会让人误判成"构建坏了"，而它只是被 strip 了
- `check` / `deploy` / `rollback` 三条命令与备份位置
- 部署后必核：`multimodal space active: provider=chineseclip` 才是 ONNX
  真加载起来的标志，缺它说明已降级但**不报错**
- ★ 适配器升级的保护语义（`.bundled` 三种情形的判定表），并记 21:50 那次
  实测：手工补过 `stream_index` 的 `openai.lua` 被正确判定为用户修改并保留
- 两次部署的真实数据对照表

**§2 waiter**
- 逐台更新、不可并行（两台连同一网关，同时重启会同时断链）
- 部署后确认 `device waiter-* online`
- 记 2026-09-27 顺手解决的悬案：106 此前无 `online` 而 30 正常，两台配置与
  token 完全相同 ⇒ 差异只可能在旧二进制，8月27日那版落在"未 bind 时收到
  ping 会关连接"的缺陷窗口
- `device_cmd_allowlist` 的替换语义、生效验证、幂等追加方法
- ★ 明确写**白名单只匹配命令名、不看参数**，`find -delete`/`sed -i` 仍能逃
  ⇒ **不要称它为"只读白名单"**

**§3 故障排查**：按"消息没反应 / 命令被拒 / 适配器异常 / 告警是否缺陷"
四条线各给命令；特别标注"群聊 not @bot"与"私聊没回"是两件事

**§4 已知未修**：三项目前是已知限制而非疏漏

文中数字均与现场核对：脚本子命令确实存在（`check`/`deploy`/`rollback`）、
生产白名单确为 22 条、两次二进制大小取自实际部署。
 2026-09-27 22:25:58 +08:00
JianFeeeee
bcd75d25fd fix(provider): has empty arguments 误报 —— 零参数工具被当成参数丢失 
## 现象

部署后生产日志出现 14 次：

    provider.go:414  [provider:llmsproxy] tool_call seq_list (...) has empty arguments

## 根因

原始响应里参数**完好**（从日志扒出来）：

    "tool_calls":[{"function":{"arguments":"{}","name":"clawhubadapter_list"},...}]

诊断条件是 `len(tc.Arguments)==0 && tc.RawArguments==""`，而
`parseToolArguments("{}")` 走 string 分支 → `json.Unmarshal("{}", &m)`
成功且 `m != nil`（**非 nil 的空 map**）⇒ 返回空 map ⇒ 命中告警。

被点名的全是**零参数工具**（`seq_list` / `*_list` / `seq_help`，
它们的 `properties` 本来就是 `{}`）。

## 为什么必须修

不是"日志吵"。这条诊断的本职是抓「上游/适配器**真的**把参数丢了」，
真发生时会被这 14 次噪音淹没 —— **诊断日志失去信噪比就等于没有**。

## 修法

新增 `argsLookDropped(rawArgs)`，判 `RawArguments` **原文**而非解析后的 map：

- 空串 / 纯空白 ⇒ 上游没给 arguments 键 ⇒ 真丢
- 能解析成 JSON（哪怕是 `{}`）⇒ 上游确实回了参数 ⇒ 不报
- 解析失败（如半截 JSON）⇒ 参数本身是坏的 ⇒ 等同丢失

## 判据（3 条）

- `TestEmptyArgumentsDiagnosticIgnoresExplicitEmptyObject`  4 个子用例：
  `{}` / ` { } ` / 完全缺失 / 只有空白
- `TestArgsLookDroppedIgnoresNonEmpty`  非空参数一律不报
- `TestArgsLookDroppedEndToEnd`  用**日志里出现过的真实 body** 走
  `normalizeOpenAIToolCalls` 到判定的完整接缝 —— 单测过了但接缝不对
  只有端到端抓得到

写判据时我先用错了类型：拿 `apiToolCall`（**非流式**路径的结构）喂
`normalizeOpenAIToolCalls`，vet 直接报错才纠正为 `openAIToolCall`。
两套结构并存，很容易接错缝。

## 顺带记录：另一个告警不是内核缺陷

`重复申请 stage 锁`（5 次）经排查是**插件侧**问题，内核自愈机制工作正常：

- `proc_main.go.tmpl:1569` SDK 模板在每个 stage handler 入口**自动**调
  `stage.lock`；`lock.go:51` 锁**不可重入** ⇒ 同一次 `before_toolcall`
  被触发两次且首次未释放就命中
- 已排除 qq 业务代码：`beforeToolcall`（plugin.go:1303-1350）只有
  `ctx.Lock()`（SDK **数据**锁，与 proc stage 锁是两把锁）与纯本地调用，
  无任何再次触发 stage 的路径
- 成因在插件进程侧运行时（编译进 9月14日的 `plugin.bin`，**不随 homed 部署**）
- 内核 `stage.go:102-106` 的强制释放是**有意设计**（"锁仲裁回内核"自愈，
  实验 9），避免后续插件死锁；`stages.go:258` 把错误收进 `ctx.Errors`
  不中断流程 ⇒ 那轮 212 秒正常跑完

两条结论都写进文档，避免以后有人当内核缺陷去修。

门禁：`-race` 通过，`go test ./internal/... ./cmd/...` 全绿。
 2026-09-27 21:18:32 +08:00
JianFeeeee
20d357328b docs: 两份 toolcall 文档对齐实现与部署实况 
## 契约文档：状态头从「尚未实现」改为「已实现并部署」

生产已注册 7 个 `seq_*` 工具，但文档仍写着"设计定稿，尚未实现" ——
实现者（和读者）会以为 seq 还不存在。

新增 §9.3「实现落点」：设计稿 §8 写的是**六个** `seq_*` 工具，实现时
多了一个 `seq_when_call`（跨序列条件调用独立成工具，否则模型要手写
"先 seq_list 再挑目标再 seq_call"，多一次往返且容易挑错），并记下三项
设计之外的修正（`seq_create` O(n²)、`Store.List()` 误认任意 `.json`、
存储用 AST 而非原始文本）。

同时点明：设计条款**仍是契约**，实现与本文冲突时以本文为准并修实现。

## 修一处预先存在的失效引用

§7 末尾 `见 §4.5` —— §4 只到 4.4，该小节不存在。改为按标题名引用
（`§4「结果契约」的 ErrToolNotFound 哨兵`）：将来增删小节时不会再次失效。

自查脚本第一版把 8 个**存在**的章节误报成失效引用 —— 标题格式是
`## 1. 背景`（编号后跟 `.`），而我的正则要求编号后是空格。判据自己错了，
改成 `(\d+(?:\.\d+)*)\.?\s` 后才得到真实结果。

## 并行计划文档：部署小节 + 白名单专节

- 原「⚠ 部署前置条件（未完成）」改为「✅ 部署（已完成）」，补实际验证数据
- 记下"实例自述没有编排工具"不是说谎：生产二进制构建于 06:36、seq 引入
  于 `71c894c`（更晚）⇒ `strings | grep -c internal/plugins/seq` 为 0。
  这类"实例自述与代码状态不一致"应先查二进制构建时间，别急着怀疑提示词
- 新增「设备命令白名单改为可配置」：起因、替换语义、daemon 路径的疏漏
- 明确写下**已知局限**：白名单只匹配命令名、不看参数，
  `find -delete` / `sed -i` / `sort -o` 仍放行 ⇒ **不要把它叫"只读白名单"**，
  那会让人以为写操作被挡住了
- 记 106 此前无 `online` 日志的成因（旧 waiter 落在未 bind 时收 ping 会断连的
  缺陷窗口），以及 `ssh` 吃掉 `read` 输入导致"喂了 yes 却说已取消"

删掉了初稿里一段"反引号内 `+=` 写进 heredoc 导致赋值落到子 shell"的说法 ——
脚本与 git 历史里都没有这种写法，属凭记忆误记，不能留。

文中数字均与现场核对：seq 工具 7、二进制 86784400 / 12691402、白名单 22 条。
 2026-09-27 20:00:33 +08:00
JianFeeeee
c022ac98cd fix(deploy): deploy-waiter 的 ssh 加 -n，否则「喂了 yes 却说已取消」 
`do_check` 里的 ssh 会从 stdin 读，把后续 `read -p "确认更新"` 的输入吃掉 ——
于是 `bash deploy-waiter.sh deploy <ip> <<< "yes"` 里的 yes 被 ssh 消耗，
read 拿到空串，脚本静默走「已取消」分支。

症状极难定位：脚本本身完全正常、备份逻辑没问题，只是"明明喂了 yes"却
什么也没发生。5 处 ssh 统一加 -n。
 2026-09-27 19:52:53 +08:00
JianFeeeee
20e5d917c3 chore(stress): 加 waiter 远程更新脚本；修 cmp.py 的 docstring 格式 
## deploy-waiter.sh：106 / 30 的 waiter 更新

现状（更新前）：两台都是 8月27日构建的 /opt/waiter/waiter（11,388,177 字节），
以 root 跑 waiter-remote.service，配置指向 ws://192.168.2.60:9890/…

安全设计：
- 先备份旧二进制（`$BIN.bak-<时间戳>`），失败即回滚（脚本内自动）
- **只换二进制，不动 waiter.yaml**（配置由 deploy 后单独追加）
- **逐台更新并验证，不并行** —— 两台都连同一网关，同时重启会同时断链
- 106 走 admin+sudo、30 走 root
- 验证项：服务 active + 进程时长 + **配置 md5 未变**

用法：`check`（只读）/ `deploy <ip>`（需输 yes）/ `rollback <ip>`

## cmp.py：两处格式

docstring 的 `"""` 紧贴内容、以及函数段之间缺两个空行（PEP8）。纯格式，
无逻辑改动。
 2026-09-27 19:42:06 +08:00
JianFeeeee
71934464cf feat(waiter): 设备命令白名单改为 waiter.yaml 可配置 
## 起因

白名单是源码里硬编码的正则（`homeagentAllowCmd`，18 个命令），
而 `waiter.yaml` 里**没有任何键能改它** ⇒ `find` / `grep` / `sed` / `sort` / `tr`
这些排查问题最常用的**只读**命令一律被拒。生产实测：

    device_ctl_cmdrun  device_id:waiter-fnnas  error: command not in whitelist

命令执行完全在 waiter 侧（`device.go` 的 `exec.CommandContext`），插件侧无二次
限制；触发者是 **agent**（经 device_ctl_cmdrun），所以这道闸是机器闸、不是人工确认。

## 改动

waiter.yaml 新增 `device_cmd_allowlist`（字符串数组）：

    device_cmd_allowlist:
      - ls
      - find
      - grep
      - sed

- **替换**默认集而非追加：避免"以为加了 find、结果还留着 python3 -c 任意执行"
- 留空 ⇒ 用内置默认集（★ **绝不能变成"全放行"**，那等于静默拆掉闸门）
- 匹配只取命令名**第一段**再整词匹配：`grep -rn x .` 能过，
  而 `grepXxx` / `mygrep` 不会因 contains 蒙混过关；也跳过 `FOO=bar cmd` 的赋值前缀
- `deviceCmdAllowed` 是包级函数变量，由配置赋值 —— 与同文件既有的
  `sendBridgeResult` 同一模式

## ★ 一次真实的疏漏（判据记着）

waiter 有**两条**设备桥启动路径：
- `main.go` 的 `startDeviceBridge` —— 交互/一次性模式
- `daemon.go` 的 `startDaemonDeviceBridge` —— `waiter --daemon`（**生产两台都这么跑**）

我最初只在 `main.go` 里赋值。daemon 路径不经过那里 ⇒ 配置**完全不生效**，
而症状是"配置写了、启动也打了招呼、命令照样被拒"，极难定位。
两处都接上了，并加 `TestDaemonPathAppliesAllowlist` 守住。

## 判据（5 条）

- `TestDefaultAllowlistStillBlocksDestructive`  默认集必须挡住
  `rm -rf /`、`dd`、`chmod -R 777`、`mkfs`、fork 炸弹 ——
  **这道闸存在的唯一理由**，谁把它改成"什么都不拦"这条就要失败
- `TestConfigAllowlistExtends`  配置里声明的 `find/grep/sed/sort/tr` 能过；
  配置未含的 `rm -rf /` 仍被拒（证明是"替换"不是"叠加"）
- `TestEmptyConfigFallsBackToDefault`  配置为空时回退默认集，**且不放行** `rm -rf /`
- `TestCmdAllowlistFromYAML`  走**真实** `readFile` 解析 yaml（不另写一份解析，
  两处会漂移，而漂移本身就是漏洞）
- `TestDaemonPathAppliesAllowlist`  守住 daemon 路径也应用配置

## 生效方式

106/30 的 `/opt/waiter/waiter.yaml` 追加 `device_cmd_allowlist`，
并更新二进制。启动日志会打印 `device cmd allowlist: N 条（来自 waiter.yaml）`
或 `默认 N 条`，便于确认配置是否真的被读到。
 2026-09-27 19:41:43 +08:00
JianFeeeee
55906b8b7e chore(deploy): 补强部署后验证 
原来只说「等 20s 看 /kernel 状态」，等于没验。进程活着 ≠ agent 起来了。
现在逐项核对，每项对应一个真实故障模式：

- 60s 内未见 'kernel ready' ⇒ 判失败并给出回滚命令 + journalctl 尾部
- 注册工具条目数（生产应 18 个左右）⇒ 少了说明插件加载异常
- 'LLM API unreachable' 次数 > 3 ⇒ 内核在 rollback 循环
  （生产设了 max_retries=100000，不可达会一直重试）
- ONNX provider 相关日志 ⇒ 缺失时应是明确错误+降级，不静默假装启用
 2026-09-27 19:12:12 +08:00
JianFeeeee
9b6d946344 chore(deploy): 加生产部署方案脚本（check/backup/deploy/rollback 四段） 
## 为什么需要

生产二进制是 **`-tags=onnxruntime`** 构建（86.5MB，.rodata 62.5MB），
而普通 `go build` 只有 37MB —— 差的是 ONNX Runtime 绑定。
`deploy/packaging/package-linux.sh:139` 会显式拒绝非 onnxruntime 构建：

    if ! go version -m "$homed_bin" | grep -Eq 'build[[:space:]]+-tags=.*onnxruntime'; then
        echo "ERROR: homed 不是 onnxruntime 构建，拒绝打 server/full 包" >&2

也就是说：**用错构建方式部署，依存句法分析与多模态向量化会静默失效**。
这个坑我自己踩过一次（拿普通构建去比体积，才发现的），所以脚本第一步
就卡这个判据。

## 四个动作

- `check`    只读检查：服务状态、onnxruntime 标签、libonnxruntime.so、
              模型资产、适配器清单。**不改任何东西**，可随时跑
- `backup`   备份二进制 + 适配器 + unit 文件，并**生成 ROLLBACK.sh**
- `deploy`   check → 人工确认（输入 yes）→ 备份 → install -m 0755 原子替换
              → 重启 → 8 秒后验活；失败时打印回滚命令与 journalctl
- `rollback` 用最近一次备份回滚

## 刻意不做自动回滚

回滚要不要做、什么时候做，是人的判断。脚本只负责把状态保全好，
让回滚成为一条**可执行**的命令，而不是一个自动决策。

## 部署不会碰的东西（已在 check 里显式打印）

- **适配器文件**：`d3eaff4` 的新逻辑在「无历史清单」时不动任何已存在的文件，
  所以生产的 10 个 .lua 保持原样（含那个已含 stream_index 的 openai.lua）
- **数据目录**：51G 的 models/ 与配置都不动，部署只换二进制
 2026-09-27 19:11:41 +08:00
JianFeeeee
07feecba11 docs(plan): 补记全面压测结果与部署前置条件 
两版隔离实例实测（规模 3 = 288 条输入），核心差异是**处理数**而非耗时：
旧版 openai.lua 缺 stream_index 透传 ⇒ 多个分片并到槽 0、参数混拼 ⇒
工具一个都没真跑，却因为「少干活」而耗时更短。

    !slowbatch8   旧 0.220s / 0 个  →  新 0.409s / 8 个
    并发 vs 强制串行（新版内部）      N=8 加速 3.88×
    调度器轰炸 288 输入             两版均 100% 通过
    连续稳定性 20 轮                两版均无错误、内核无 panic

规模 1（32 条）与规模 3（288 条）结果完全一致 ⇒ 可复现。

同时记录部署前置条件：生产是 -tags=onnxruntime 构建（strip 后 75MB vs
普通构建 28MB），package-linux.sh:139 会显式拒绝非 onnxruntime 构建。
本次改动未触及任何 ONNX 路径，故压测结论对生产成立，但必须走
deploy/packaging/build.sh 才能部署。
 2026-09-27 19:00:53 +08:00
JianFeeeee
56fe10d3a4 docs(plan): 记录更新前后全面压测结果与部署前置条件 
两版隔离实例实测（规模 3 = 288 条输入），核心差异是**处理数**而非耗时：
旧版 openai.lua 缺 stream_index 透传 ⇒ 多个分片并到槽 0、参数混拼 ⇒
工具一个都没真跑，却因为「少干活」而耗时更短。

    !slowbatch8   旧 0.220s / 0 个  →  新 0.409s / 8 个
    并发 vs 强制串行（新版内部）      N=8 加速 3.88×
    调度器轰炸 288 输入             两版均 100% 通过
    连续稳定性 20 轮                两版均无错误、内核无 panic

规模 1（32 条）与规模 3（288 条）结果完全一致 ⇒ 可复现。

同时记录部署前置条件：生产是 -tags=onnxruntime 构建（strip 后 75MB vs
普通构建 28MB），package-linux.sh:139 会显式拒绝非 onnxruntime 构建。
本次改动未触及任何 ONNX 路径，故压测结论对生产成立，但必须走
deploy/packaging/build.sh 才能部署。
 2026-09-27 19:00:19 +08:00
JianFeeeee
190e46908d test(stress): 补更新前后全面对比脚本（cmp.py），修 blast 的计数错误 
## cmp.py：更新前后对比的四个维度

★ 每轮都记录**处理数**（响应里有多少个工具结果标记）与**是否出现 error 帧**，
任一不符即记失败。理由：工具调用这一路的失败模式几乎都是**静默**的 ——
工具没跑、参数混拼、只处理了第一个 tool_call，都不报错只是结果不对。
"跑完没崩"完全不能说明它 work。

1. **批内工具调用**：!slowbatchN 在两版上各跑几轮，比中位耗时与处理数
2. **并发 vs 强制串行**（新版内部对照）：!slowbatchN vs !serialbatchN
3. **调度器并发轰炸**：多连接并发排队，算通过率
4. **连续稳定性**：20 轮无错误率

## 修掉 mock 的 !serialbatch 缺失

之前只在 /tmp 的临时副本里加过，没进仓库，导致 cmp.py 测「强制串行」时
那个 marker 根本不存在 —— 测出来的"串行"其实是并发，**加速比是假的**
（0.34x / 0.31x，看起来并发比串行慢）。已加回并说明它的用途：跨版本做不了
并发/串行对照（旧版适配器缺 stream_index，工具一个都没真跑），只能在
同一套内核上做。

## 修掉 blast 的计数错误

第一版按 `conns * inputs` 起线程、每个线程又跑 `inputs` 轮 ⇒ 总输入数是
conns×inputs²，分子分母量纲不一致，算出过 **"128/32 = 400%"** 这种荒谬数字。

现在：恰好 conns 个 worker、每个跑 inputs 轮；且分母用**实际发出的**输入数
（含连接失败的），否则连接失败时通过率会虚高。

## 踩过的两个坑（都写进注释）

- 内核 `task.go:353` 有输入去重（`isDuplicateInput`，为 webui 断线重连重放
  而设），相同文本被丢弃并回空响应 ⇒ 每轮输入必须带唯一后缀
- cli 的 auth 帧本身就是 `{"type":"response"}` ⇒ 必须先吃掉它再开始收集，
  否则第一轮的"终止帧"是 auth，测出来耗时恒为 0
 2026-09-27 18:56:25 +08:00
JianFeeeee
d3eaff46f1 fix(lua): 内置适配器按内容自动更新，替代「文件已存在就跳过」 
## 原机制是这次全部误判的根源

    if _, err := os.Stat(dstPath); err == nil { continue }

**升级二进制永远不更新已部署的适配器文件。** 于是"改了仓库 ≠ 生产生效"，
而这个机制让同类问题可以长期潜伏：

    2026-08-26 15:46  生产 openai.lua 手工补上 stream_index 透传
    2026-08-26 16:10  ddef195 提交，说明里写了但代码没改这个文件

修复当天先在生产落地、32 分钟后才提交入库（漏了这个文件），此后一个月里
两端都没人发现 —— 生产不报问题（它有），仓库的判据也测不到（直接构造 Go
结构体，绕过适配器）。而"升级不覆盖"意味着即使仓库补上修复，已部署的
老实例也不会拿到。

## 新判据（按内容，不按存在）

    文件不存在                     ⇒ 写
    有历史清单且盘上 == 上次内嵌   ⇒ 覆盖（只是没跟上新版本）
    有历史清单但盘上 != 上次内嵌   ⇒ 不动 + 日志（用户改过）
    无历史清单（首跑/从旧版本升级） ⇒ 不动，只补缺失文件（与旧行为一致）

"上次内嵌的版本"记在 `DataDir/adapters/.bundled`（`<name>\t<sha256>`）。

⚠️ 为什么不能无条件覆盖：adapter_path 是可配置项，用户可以把 adapter_path
指向自己维护的适配器。静默覆盖等于丢弃他们的修改，而且**没有报错**。

## 判据（两个方向都要测）

- TestWriteBundledAdaptersSkipsUserModified  用户改过的**必须保留**，
  且改完仍能正常加载（fixture 必须功能完整，否则会因为缺钩子函数而失败 ——
  那是 fixture 问题，不是保护逻辑问题）
- TestWriteBundledAdaptersUpdatesStale       落后于新内嵌的**必须被更新**，
  且**幂等**（三跑不再改写任何文件）

★ 第二条是必要的：只测保护的话，**一个"永远不覆盖任何文件"的实现也能全绿**
  —— 而那正是要修的病。

## 代价（必须知道）

**升级到本版本的这一次，已部署实例的适配器不会更新**（没有历史清单可比）。
从第二次升级起自动生效。要立刻生效就删掉 DataDir/adapters 让内核重新解包。

对本次修的 8 个适配器而言：生产此刻用不到（三个源 llmsproxy/visionllm/
justworker 全是 openai.lua），所以不影响运行；将来启用 deepseek 等源时，
自然就是修复版。

## 顺带

`bundledAdapterNames` 从 writeBundledAdapters 里提出来成包级变量 ——
writeBundledAdapters 与体检判据共用，避免两处各写一份而漏掉某个
（漏掉的后果是该适配器永远不会被更新）。
 2026-09-27 18:46:51 +08:00
JianFeeeee
cff8e10ad5 fix(lua): 补齐 6 个适配器的流式 tool_calls 支持 
体检判据（TestAllBundledAdaptersStreamToolCallStatus）报出的三类问题，
本提交解决其中两类；第三类（gemini）未动，原因见下。

## ① OpenAI 兼容族：github / groq / mistral（3 个）

它们的 transform_stream_chunk 与修复前的 deepseek **逐字相同** ——
只透 content/done，tool_calls 处理只存在于 transform_response（非流式）。

后果与 deepseek 相同：流式模式下工具调用全部丢失，模型调不动任何工具，
且**没有任何报错**。生产当前未启用这三个源，但按预设配置的用户会踩到。

照 deepseek 的修法补上（含 reasoning_content 透传）。

## ② 嵌套形态 + 键名错：server / kimicode / anthropic / ollama（4 个）

这四个**有** tool_calls 处理，但发的是：

    { index = N, id = ..., ["function"] = { name = ..., arguments = ... } }

而 homed 的 `agentAPI.ToolCall` 是**扁平**结构，json tag 为：

    id / type / name / arguments / raw_arguments / stream_index

两处都是**静默**失效（Go 侧按 json tag 反序列化，取不到就是零值，无报错）：
- **嵌套** `["function"]` ⇒ `name` / `raw_arguments` 取零值
  ⇒ flush 时判「无 name」丢弃，或参数为空
- **键名 `index`** ⇒ `StreamIndex` 取零值
  ⇒ 多个分片并到同一个桶，argsRaw 混拼 ⇒ 每个工具报「参数不是合法 JSON」
  而**一个都没真跑**

已逐项对齐为扁平 + `stream_index`。协议差异都保留：
- anthropic：`content_block_start` / `input_json_delta`，续传片 name 留空
  （内核按 stream_index 累积，补齐 name 后才 flush）
- ollama：tool_calls **整条一次发完**（不分片），故 stream_index 取数组下标

## ③ gemini 未动

它的流式函数处理 `candidates[].content.parts`，**全文件没有任何
tool_calls / functionCall 处理** —— 连非流式路径也没有。补它不是"对齐"
而是新实现，且 gemini 的 functionCall 形态（`functionCall: {name, args}`，
args 是对象而非 JSON 字符串）与 OpenAI 族不同，需要单独判据。

生产三个源（llmsproxy / visionllm / justworker）全部用 `openai.lua`，
不阻塞。留作独立项。

## 判据

- TestOpenAICompatibleFamilyHandlesStreamToolCalls  5 个 OpenAI 族适配器，
  逐个验证 tool_calls 未丢 + stream_index 正确
- TestAnthropicAdapterEmitsFlatToolCallsWithStreamIndex  用 **Anthropic 协议**
  的 fixture（不用 OpenAI 的，否则会因"不适用该 chunk"跳过 —— 看着绿，
  实则没测）
- TestOllamaAdapterEmitsFlatToolCallsWithStreamIndex  用 Ollama 协议形态
- TestDeepSeekAdapterHandlesStreamToolCalls  单列，因它有源预设指向

★ 三个判据按**协议**分文件而非逐适配器：这几个文件的流式函数逐字相同，
共用一个 fixture 会因协议不适用而静默跳过 —— 那等于没测。

## 体检分类

    修前: ✓ [openai]        ⚠ [kimicode server]  ✗ [anthropic deepseek gemini github groq mistral ollama]
    修后: ✓ [openai deepseek github groq mistral]  ⚠ []  ✗ [gemini]
 2026-09-27 18:34:33 +08:00
JianFeeeee
0fdb13749a fix(lua): deepseek 适配器的流式路径处理 tool_calls（此前全部丢失） 
## 缺陷

deepseek.lua 的 tool_calls 处理只存在于 `transform_response`（**非流式**路径），
而 `transform_stream_chunk` 只透 content/done：

    return json.encode({ content = delta.content or "", done = (fr ~= nil) })

于是 deepseek 源在**流式**模式下工具调用全部丢失 —— 模型调不动任何工具，
且**没有任何报错**，只是"工具好像不听话"。

## 为什么难发现

- 非流式路径是好的 ⇒ 端到端手工测试也过
- 内核的 tool call 循环默认走**流式**（provider.go 的 stream 分支）⇒ 实际不可用
- 功能判据（core 包的批内测试）直接构造 `agentAPI.StreamChunk{}`，
  **绕过适配器** ⇒ 测不到这一层

配置里 `deepseek` 源预设指向 `adapters/deepseek.lua`，所以任何按预设配置
的用户都会踩到（生产当前未启用该源，配置里 deepseek 相关键为 0）。

## 修法

照 openai.lua 的做法在流式路径补上：OpenAI 兼容格式
`{function:{name,arguments}, id, type, index}` → homed 扁平结构
`{id, type, name, raw_arguments, stream_index}`，含 reasoning_content 透传。

两个容易踩的点也写进注释：
- **不能按 name 过滤**：流式续传片 name 为空但携带 arguments，
  内核按 stream_index 分桶累积
- **必须透传 stream_index**：否则多个分片并到槽 0、argsRaw 混拼

## 判据

新增 TestDeepSeekAdapterHandlesStreamToolCalls：喂两个含 tool_call 的分片，
断言 tool_calls 未被丢弃且 stream_index 正确。修前两条分片全被丢弃。

## 体检分类随之变化

    修前: ✓ [openai]                                       ✗ [deepseek ...]
    修后: ✓ [deepseek openai]                              ✗ [anthropic gemini github groq mistral ollama]
 2026-09-27 18:31:42 +08:00
JianFeeeee
17bc9a5553 docs(stress): abtest 补「跨版本对比的陷阱」—— 老版本可能只是没干活 
脚本原本只写「加速比 = 基线延迟 / 新版延迟」。实测发现跨版本对比时这个
数字**没有意义**：

    N    老版本 中位/处理数      新版本 中位/处理数      算出的"加速"
    2    0.273s / 0 个        0.480s / 2 个          0.57x
    4    0.273s / 0 个        0.492s / 4 个          0.55x
    8    0.273s / 0 个        0.512s / 8 个          0.53x

"老版本更快"是假的 —— 它只是没干活：适配器缺 stream_index 透传 ⇒ 多个
分片并到槽 0 ⇒ argsRaw 混拼 ⇒ 每个工具报"参数不是合法 JSON"而一个都没
真跑。

★ 跨版本能比的硬指标是**处理数**；耗时对比只在新版内部做（混一个非并发安全
工具触发整批降级）才有意义 —— 那种对照下 N=12 时加速 5.72×。

顺带记下：老版本的内核分桶逻辑其实完整（`idx := tc.StreamIndex` + `accs[idx]`，
来自 2026-08-26 的 ddef195），缺的只是适配器那一个字段；而生产在当天 15:46
就手工补上了，比该提交（16:10）早 32 分钟。
 2026-09-27 18:30:09 +08:00
JianFeeeee
8fafd5eafe test(stress): 补批内并发压测与 A/B 对比脚本，并给 mock 加多 tool_call 能力 
## 缺口

现有 kernel-stress 只压**调度器**（多连接排队 + L4 中断 + 驻留子），mock 每轮
只发**一个** tool_call。而内核的并发判据是：

    if f == nil || len(f.PendingTools) <= 1 { return false }

⇒ **一个 tool_call 永远不并发**。所以现有压测压的全是串行路径，批内并发
一条都没走过。

## mockllm.py：让 mock 能发多个 tool_call

- `!batchN`   N 个全部 ParallelSafe 的只读工具 ⇒ 强制走 stepToolBatch
- `!mixedN`   夹一个 knowledge_create（未声明并发安全）⇒ 验证整批降级
- `!slowbatchN` N 个 sleep 型 cmd_run（单工具约 200ms，时长递增）
  ⇒ 工具慢才能让并发的收益从噪声里显出来；时长递增使**完成序与声明序相反**，
  可据此判定"是否按声明序落消息"
- `!serialbatchN` 在 !slowbatch 基础上插入一个非并发安全工具 ⇒ 强制整批串行，
  作为并发对照的另一半
- `!img` / `!ocr` 触发多模态工具路径（不加载模型，只验内核 IPC 接线与错误处理）
- `!err` / `!hang` 故障注入

### 三个协议细节（踩过才知道，都写在注释里）

1. **必须带 `index`** —— 内核按 `StreamIndex`（上游 JSON 的 index）分槽累积
   arguments。缺 index 时所有分片落到槽 0，几个 tool_call 的参数被**混拼**，
   症状是每个工具都报"参数不是合法 JSON"而工具一次没真跑过。
   单 tool_call 时不设 index 也正常，所以老 mock 一直没暴露。
2. **必须按协议分片** —— 一个 chunk 一个 tool_call，各自带 index；
   后续 chunk 只续 arguments。整数组塞进一个 chunk 会被内核按"续传"语义累积。
3. **每个工具都要发"带 name 的首片"** —— 我第一版只给第 0 个发首片、其余直接
   发续传片，看起来省事，但内核 flush 时按"无 name 即丢弃"处理，
   于是 idx=1/2/3 全被丢，只跑 1 个工具。

## batchstress.py：批内并发压测（带校验）

只看峰值是不够的 —— 校验：工具是否真跑（响应里应有结果标记）、
消息顺序是否稳定（并发执行但按索引落消息）、mixed 批是否整批降级。

## abtest.py：串行 vs 并发的定量对比

同一套内核上用 !slowbatch / !serialbatch 两组对照，交替执行抵消机器负载漂移，
取中位数（长尾会污染均值）。

★ 判据里加了"工具是否真执行"这一项：**只看耗时是不够的** —— 出现过
"内核 274ms 就回复、工具一个没跑"的情况，那种情况下并发与串行都是 0.2s，
加速比毫无意义。

## 实测（隔离 netns 实例，mock + 内核同网段，5 轮中位）

    N    并发        串行         加速     上限
    2    0.481s    0.685s      1.42x    2
    4    0.491s    1.114s      2.27x    4
    8    0.513s    2.037s      3.97x    8
    12   0.531s    3.039s      5.72x    12

并发批耗时几乎不随 N 增长，串行批严格线性。

★ 另一个踩过的坑（abtest 脚本自己的）：内核有输入去重
（task.go:353 `isDuplicateInput`，为 webui 断线重连重放而设），相同文本会被
丢弃并回空响应。第一版每轮发同一个 marker ⇒ 只有第 1 轮有效，后面全是
0 秒 0 工具。修法是每轮加 `time.time_ns()` 唯一后缀。
 2026-09-27 18:29:39 +08:00
JianFeeeee
61a2d56bbb test(lua): 记录仓库/生产适配器漂移的具体内容与时间线 
生产 adapters/openai.lua（4853 字节）含 stream_index，仓库 ddef195 时的版本
（4709 字节）不含。生产文件时间 2026-08-26 15:46，比 ddef195 提交（16:10）
早 32 分钟 —— 该提交说明里写着「openai.lua 输出 stream_index 字段」，
但 --stat 显示它没改这个文件：修复先在生产生效，入库时漏了。

于是「生产能跑多工具、仓库跑不了」持续一个月而两端都没人发现：生产不报
问题（它有），仓库的判据也测不到（直接构造 Go 结构体，绕过适配器）。

判据本身不变（仍是诊断式 t.Log），只把这条漂移的具体内容写进注释 ——
它是理解本次全部误判的关键背景。
 2026-09-27 18:29:32 +08:00
JianFeeeee
969206eb85 test(lua): 加适配器漂移报告 + 键名契约判据 
上一提交（66200ff）纠正了一处误判：仓库的 openai.lua 缺 stream_index 透传，
而生产实例早就有 —— 仓库版本落后于生产。这个漂移当时没有任何判据能发现。

## 两条判据，定位不同

### TestBundledAdaptersMatchDeployedOnes —— 诊断式，刻意**不**作为失败判据

实测结果：生产部署的 7/10 个适配器比仓库旧（anthropic 2537 vs 5144 字节），
而 openai 那份反而领先。这**是正常的** —— 生产是长期运行的部署，适配器在它首次
创建时就解包落地，之后仓库一直在演进。

若把"必须一致"写成失败判据，它会在任何老部署上恒红，而恒红的判据会被无视 ——
那等于没有判据，甚至更糟（它会掩盖真正的漂移）。所以这里只把差异摆出来。

但它顺带把**部署陷阱**摆到了明面上：

    vm.go writeBundledAdapters: if 文件已存在 { continue }

升级二进制**不会更新已部署的适配器文件**。于是"仓库改了适配器但老实例上不生效"
与"仓库根本没改"在现象上完全一样 —— 这大概就是仓库长期缺 stream_index 却
没人发现的原因之一。

### TestAdapterEmitsOnlyKnownFields —— 这条才是能自动抓 bug 的

契约 = agentAPI.ToolCall / StreamChunk 的 json tag：
`id, type, name, arguments, raw_arguments, stream_index`（+ 上游原样透传的
`index` / `function`）。

★ 为什么必须有：Go 侧按 json tag 反序列化，**键名拼错会静默取零值**。
`streamindex`（少个下划线）与"没写这行"的表现完全一样 —— 无报错、字段为零、
分桶全部并到槽 0。这正是本次 stream_index 缺失的形态。

判据只看"适配器吐出来的键名对不对"，与环境无关，所以能在 CI 里恒定生效。

## 顺带确认的一件事（事后查明：是我的操作失误）

压测实例解包出的 openai.lua 是 4709 字节（无 stream_index），而二进制 embed
里是 5672 字节（有）。`rm -rf` 后重新解包**仍是旧的**。

我逐行读过 `writeBundledAdapters`，只找到 embed 一条来源，一度判为"未解释的
矛盾"。**真因是操作失误**：`rm -rf` 之后启动的那一轮，用的还是修复前编译的
/tmp/homed-stress —— 删除与重编之间隔了几轮，中间又用旧二进制起了好几次
实例，每次解包出来的自然都是旧版。

用当前 main 重新构建 + 全新数据目录验证：全新解包 5672 字节、含
stream_index×3、md5 与源文件一致；删掉再解一次仍一致；启动日志有
`[lua] installed bundled adapter: openai.lua`。⇒ **writeBundledAdapters 无缺陷**。

★ 教训：验证"二进制内嵌内容是否更新"时，必须确认跑的就是**刚编译出来的那个
二进制**。否则会得出"代码有 bug"的错误结论 —— 我确实这么怀疑了好几天。

（下面那条"部署陷阱"观察本身仍然成立：升级二进制确实不会更新已部署的适配器
文件。但它与这次的现象无关。）
 2026-09-27 18:29:15 +08:00
JianFeeeee
66200ff226 test(lua): 补适配器 stream_index 透传判据 + 全适配器体检 
## 先纠正一件事：这个修复在生产上早就存在

最初我判断"`openai.lua` 缺 stream_index 透传、批内并发在生产走不通"，并据此
写了实现。**核对生产实例后，这个判断是错的**：

    生产 /home/newqqagent/adapters/openai.lua   130 行  含 stream_index
    仓库 950b21b^                                128 行  无 stream_index

生产那份的注释是「透传上游分片 index：并行多工具调用时内核按它区分归属桶」——
简洁，与本提交新增的长注释不同。**也就是说仓库版本落后于生产，生产一直没这个
问题。** 我修的是"仓库与生产的差距"，不是"生产正在发生的故障"。

## 真正缺的是判据

`internal/agent/core/stream_index_test.go` 的
TestAccumulateStreamParallelToolCallsByIndex 直接构造 Go 结构体
`agentAPI.StreamChunk{...}`，**不经过 Lua 适配器** —— 所以"适配器有没有把
index 透传出来"它永远测不到。生产有、仓库没有，判据也发现不了。

而提交 ddef195（2026-08-26，"流式并行 tool_call 按 JSON index 分桶"）的说明里
写着「openai.lua 输出 stream_index 字段」，Go 侧也加了
`StreamIndex int json:"stream_index,omitempty"` 并注明"lua 适配器以
stream_index 键透传" —— 但那次提交**根本没改 openai.lua**（6 个文件里没有它）。
说明与实现不符，而没有任何判据能发现。

## 本提交做的事

① 让 openai.lua 与生产一致（补 stream_index 透传），并说明为何缺它会静默失效：
   多个分片全部并到槽 0 → argsRaw 混拼 → 每个工具报"参数不是合法 JSON"，
   而**工具一次都没真跑过**。单工具时上游 index 恒为 0，缺省也是 0，
   所以问题只在"一轮多个 tool_call"时显形。

② 新增 internal/lua/adapter_streamindex_test.go，**真正加载并执行内嵌的
   openai.lua**（复用 VM 的真实路径），三条判据：
   - TestOpenAIAdapterPassesThroughStreamIndex  3 个 tool_call 的
     stream_index 必须是 0/1/2
   - TestOpenAIAdapterKeepsContinuationFragment 续传分片（只有 arguments、
     没有 name）的 stream_index 必须正确 —— 它是分桶的**唯一**依据
   - TestAllBundledAdaptersStreamToolCallStatus  全 10 个适配器体检

★ 第三条刻意**不**用 t.Skip 掩盖不支持的适配器 —— 早期版本一律 Skip，结果
"完全不支持流式工具调用"也会让整体显示为绿，而绿会被误读成"都支持"。
现在分类记录：openai ✓ / kimicode+server 透传嵌套形态需另修 /
其余 7 个未产出 tool_calls。

③ 体检顺带暴露的、与本提交无关但已记录的问题：
   - **仓库 vs 生产漂移无判据**：仓库适配器落后于生产时，只有靠人工对比才发现
   - **部署陷阱**：vm.go writeBundledAdapters 是
     `if 文件已存在 { continue }`，升级二进制**不会更新已有适配器文件**。
     这可能正是"仓库缺透传却没人发现"的原因之一
 2026-09-27 17:48:16 +08:00
JianFeeeee
f8add88dbc perf(stagehost): 工具声明查询免去结构体拷贝（热路径 1000 并发下省 1000 次） 
## 问题

StageHost.ToolDef 返回 &def —— 一次**结构体拷贝**：3 个 string + 2 个 map 头
+ 2 个 bool + Cleaner 函数指针。

而 toolParallelSafe 在**每批**并发判据里对每个工具各调一次：
batchRunnable 遍历 PendingTools → toolParallelSafe(tc.Name)。
1000 并发批次 = 1000 次结构体拷贝，全在判定阶段（执行之前）。

不是"逃逸漏洞"（Go 1.22+ 循环变量每轮独立，go.mod 是 1.25），纯粹是白拷贝。

## 修法

ToolDef 保留 —— 它要给需要完整声明的调用方（Cleaner、Parameters 校验），
返回副本也是**有意**的（ToolDef 里有 map 与函数指针，交出内部元素会把
可变引用漏出去）。

新增免拷贝查询，热路径专用：

    ConcurrencySafeOf(name) (safe, found bool)   // 只读 ParallelSafe && !Serial
    NoMemoryOf(name)       (v, found bool)
    HasTool(name)          bool

全部在持 RLock 下走同一个 findLocked。

`toolParallelSafe` 切到 ConcurrencySafeOf。语义完全等价 —— 两者都算
`ParallelSafe && !Serial`，只差一次拷贝。

## 判据（两个都防"优化悄悄改了语义"）

- TestNoCopyQueriesMatchToolDef  7 种声明组合（plain / parallel / serial /
  both / nomem / all / serial_nomem）下，免拷贝查询与 ToolDef(...).字段
  **逐字段等价**；不存在的工具三态一致（false/false/true）。

  ★ 这类优化最危险的失败模式就是语义漂移：并发判据若读错字段，
    能并发的批次会**悄悄退化成串行** —— 没有任何报错，只表现为"变慢了"。
    所以判据必须逐个组合比对，而不是只测一个典型值。

- TestNoCopyQueriesConcurrent  32 goroutine × 50 工具并发查询，
  -race 无竞态且结果与串行一致。

回归：go build ./... 通过；go test ./internal/... 全绿；
go test -race ./internal/agent/core 通过。
 2026-09-27 16:29:24 +08:00
JianFeeeee
8a98969fac refactor(parallel): 内置工具的并发声明改为 SDK 同构的结构体字段 
上一提交（2232d54）把并发安全改成了声明式，但内置工具那一路仍是将就：
声明靠往 required 变参里塞字符串 "toolParallel" 传递。

## 为什么那不算声明式

对照 SDK 的 NoMemory 逐条看：

| | SDK NoMemory | 当时的内置工具 |
|---|---|---|
| 载体 | `ToolDef.NoMemory` 字段 | required 里的字符串 |
| 拼错后果 | 编译器报错 | **静默失效** |
| 内核读取 | 查结构体字段 | 遍历工具表 + 解析字符串 |

"少一个工具能并发"恰恰是最难察觉的一类问题 —— 没有任何报错，
只是并行的批悄悄退化成串行。

## 改法

### 1. sdk.BuiltinToolDef 补声明项（与 NoMemory 同构）

```go
type BuiltinToolDef struct {
    Name, Description string
    Parameters        map[string]interface{}
    ParallelSafe      bool   // 零值 false = 默认串行（保守）
    Serial            bool   // 优先于 ParallelSafe
}
func (d BuiltinToolDef) ConcurrencySafe() bool { return d.ParallelSafe && !d.Serial }
func (d BuiltinToolDef) ToSchema() map[string]interface{}
```

### 2. 工具定义处声明

```go
toolDef("memory_merge", ...)                                  // 默认串行
toolDefWith("knowledge_search", ..., []string{"query"}, parallelOpts())  // 已核实只读
```

### 3. 内核一次聚合并缓存（照 StageHost.NoMemoryToolNames）

```go
graphOf()      // 快照
declareParallelTool(name)   // init 里登记
concurrencySafeOf(name)     // 查表
```

不再每次 toolParallelSafe 都重跑 buildToolDefs()（O(工具数) 重复劳动，
而声明是静态的）。

## ★ 一个更隐蔽的问题：声明表曾经是空的

`declareParallelTool` 最初挂在 `toolDefWith` 的**运行时调用**上。而那 9 个
工具全在 `if a.knowledge != nil` / `if a.social != nil` / `if a.parentID != ""`
之类的条件分支里 —— 测试环境根本不走进这些分支 ⇒ 聚合表始终为空。

而判据查的是同一张表，于是**自证通过**：全绿，并发能力为零。

这就是判据设计的教训 —— 判据和数据源同源时，它证明的只是"我和我一致"。
现在判据双向核对：名单里的必须真声明了，声明了不在名单里的也会报出来；
并额外验证内核**真的读得到**（concurrencySafeOf 而非读同一份 map）。

## 顺带修掉的迁移事故

用正则批量改造 30+ 个 toolDef 调用点时，把 `person_set_trait("name", "content")`
这类**变参**调用误改成 toolDefWith(... "name", "content") —— 那是**写工具**，
差点被标成可并发。已全部回退并逐一核对：9 个声明并发，0 误伤。
 2026-09-27 15:59:11 +08:00
JianFeeeee
374c19246b fix(seq): 修掉 seq_create 的 O(n²)，并加极端压测 
## 起因：1000×1000 压测直接跑爆

用户要求「1000 条序列 × 每条 1000 个组内 toolcall」。第一版跑满 8 分钟超时。
分阶段计时定位到瓶颈：

| 阶段 | 200 条 × 1000 工具 |
|---|---|
| 创建 | **27.0s**（135ms/条，**随序列数线性增长**） |
| 执行（组内 1000 并发） | 0.55s（20 万次调用，2.7µs/次） |
| 删除 | 4.7ms |

瓶颈在创建，不在执行。

## 根因

```go
// handlers.go:70 —— 每次 seq_create 之后
graphErr := p.store.CheckGraph()

// store.go:166 —— List() 全量 + 逐条 Load() 全部序列
```

1000 条各 250KB ⇒ 每次创建都重读 250MB 并反序列化。第 N 条的创建代价
随 N 线性增长，总计 O(n²)。

## ★ 走过的弯路：我一度建议「把校验挪到运行期」—— 那是错的

store.go:163 明确写着：

    两条检查（都必须在**建序列/保存**时做，而不是等运行）：
      1. 每个 seq_call 的目标必须存在（不存在会在运行期才发现，浪费一整轮）

**校验时机是语义，不是性能旋钮。** 目标不存在若等到运行才发现，模型已经
白白花掉一整轮工具调用。性能问题不能靠挪语义来解。

## 修法：缓存调用边，Save 做 O(1) 增量

```go
// Store 新增
graph map[string][]string   // 序列名 → 它调用的目标（裸名）

// Save:  只更新这一条的边
s.graph[seq.Name] = edgesOf(seq)
// Delete: 移除这一条的边
delete(s.graph, name)
```

`callTargets` 只依赖 AST，不必每次从盘重建。**校验语义完全不变** —— 目标
存在性与三色 DFS 环检测都照旧在建序列时执行。

## 判据

- TestStoreGraphCacheKeepsSemantics  逐条钉住三个保证：目标存在性 ✓、
  环检测 ✓、删除后不再误报成环 ✓
  （这类优化最危险的失败模式是"校验还在跑但少查了某种情况"）
- TestStoreSaveScalesLinearly       分段对比后半程/前半程每条耗时。
  ★ 判据自己改过一次：初版用「总耗时 ÷ 单条耗时」，而单条只有 48µs 时
    噪声占比过高，同一份代码两次跑出 84× 和 203× —— 判据不稳定时报的
    失败就是噪声，比没判据更糟。改成分段对比（平方时后半程会慢约 n/2
    倍，线性时基本持平），阈值 3 倍留足磁盘与 GC 抖动余量。
  实测 300 条：84~203× 单条（线性期望 300×），平方会是 90000×。

## 压测本身也修了两个自己的 bug

- 源文件目录与 store 目录分离时只改了写入侧，清理侧还指着 store 目录 ⇒
  报 "no such file"。看起来像文件被提前删了，真因是路径拼错。
- newE2EPlugin 的 runner 参数写死 *e2eRunner，压测换替身就编译不过 ⇒
  改为接受 seqRunner 接口。

## 压测规模

TestStressExtreme_ThousandSeqs 现为 1000 条 × 1000 toolcall（O(n²) 修复后
可跑）。判据全是**不变量**：每工具恰好调一次、1000 槽在交错延迟下仍按
声明序合并（并发下若按完成序合并必然错位）、删除后无残留。
 2026-09-27 15:58:54 +08:00
JianFeeeee
2232d5483c feat(parallel): 并发安全改为声明式，并审计标注 37 个工具 
把"能不能并发"从内核硬编码名单改成**工具自己的声明项**，形态照 SDK 的
NoMemory 走。

## ★ 起因：提示词在跟内核不一致

阶段 2.5 写进提示词的「内核默认并行执行」当时是**假的**：toolParallelSafe
只查 stageHost 与 io 两个来源，而全仓 ParallelSafe:true 的生产代码数量
是 **0**。于是除碰巧只发一个工具外，每一批都整批串行回退，而提示词正教
模型把多个查询放同一轮。**内核行为与提示词不一致 = 对模型说谎。**

并发面：0 → 37 个工具（18 插件 ParallelSafe + 19 插件 Serial + 9 内置只读）。

## 声明形态（照 SDK，不自创）

### 插件：结构体字段
    s.RegisterTool("config_get", sdk.ToolDef{
        Name: ..., Description: ...,
        Parameters: map[string]interface{}{...},
        // 已核实只读：…
        ParallelSafe: true,      ← 插在 Parameters 之后、handler 之前
    }, p.handleGet(s))

位置与 SDK 的 NoMemory/ContextPolicy/RecallPolicy 一致：Name 在首位，
声明项在末尾，不打散 gofmt 对齐。

### 新增 SDK 声明项：ToolDef.Serial
ParallelSafe 的**反向**标记，判据优先级高于 ParallelSafe。
为什么需要：ParallelSafe 零值 false 已表达"安全"，插件无法区分"我没想过"
与"我确认过必须串行"。没有这个区分，工具作者只能靠命名约定传递意图。

内核已消费它（io.ToolDef 同步加字段对齐），并有判据守"Serial 胜出"。

### 内置工具：toolDef 的 toolParallel 选项
内置工具以裸 schema map 下发，没有 ToolDef 结构，所以用变参选项：
    toolDef(名字, 描述, 属性)                  // 默认串行
    toolDef(名字, 描述, 属性, "toolParallel")  // 已核实只读，可并发
读工具表的老调用点一行不用动，声明就写在工具定义那一行。

## ★ 走过的弯路（都留了判据）

1. **硬编码白名单**：先在 toolParallelSafe 里查一张
   builtinParallelSafeTools map。那把声明从"工具自己"搬回了内核 ——
   工具改名/新增不会自动跟着变，得靠一条 grep 源码的判据才能发现漂移，
   而判据一改就忘。已删，改为从定义读。

2. **判据前提错（同一个坑踩了两次）**：拿裸 &Agent{} 的 buildToolDefs 输出
   当"实际可见工具"，但这 9 个内置工具全在条件分支里（a.knowledge != nil /
   a.social != nil / a.parentID != ""…），裸 Agent 一个都不产出 ⇒ 全部误报
   "声明形同虚设"。第一次叫它"幽灵条目"，没认出是同一个坑。

3. **注释模仿真实签名污染判据**：toolParallel 的用法注释写着
   `toolDef("knowledge_search", ...)`，判据按文本匹配先撞上注释。

4. **buildToolDefs 的 nil 不一致**：开头判了 a.io != nil，末尾却无条件
   a.io.ListChannels()。任何无 IO 的 Agent 调它都 panic —— 而 panic 报在
   io 包里，根因在 tooldefs.go。已补。

5. **插入脚本用正则找"最后一个顶层字段"**：被嵌套 map 里的同形文本骗到，
   823 处错误重排把文件改坏。改用括号深度 + 记录进入深度 3 的行号
   （空 properties 会让深度在同一行进出平衡，只判 depth==2 不够）。
   工具在 SDK 仓 tools/annotate_parallel/，复用时用绝对路径。

## 提示词措辞同步修正
「默认并行执行」→「尽量并发执行，但这是**逐工具判断**的」，并教模型
**把查询类放同一轮、写操作单独发一轮**（写和查混在一批，整批都串行）。

## 判据
- TestSerialOverridesParallelSafe          Serial 优先于 ParallelSafe
- TestToolParallelDeclarationsAudit        并发面不许再归零
- TestNoToolDeclaresBothParallelAndSerial  两者同标即谎话
- TestBuiltinParallelDeclaredWhereDefined  声明写在定义处、且内核真读到
- TestStoreListIgnoresForeignJSON          压测抓到的 List() 缺陷
 2026-09-27 15:15:57 +08:00
JianFeeeee
b1b96b788d test(seq): 三个压力测试 —— 超长序列 / 100 工具并行 / 串行降级 
与单元判据的分工：单元判据钉住**语义**（一条路径对不对）；压力测试钉住
**规模下的不变量**。沿用仓内既有范式（media/soak_test.go）：
testing.Short() 跳过 + 独立 -run 跑。

① 超长序列
   · 解析 10 / 100 / 1000 组（250KB 文本）：6.8ms，无硬上限误报
   · 执行 200 组 × 5 工具 = 1000 次调用：2.0ms
     断言：每工具恰好被调 nGroups 次（无遗漏/重复）、结果含**最后一组**
     —— 组间串行在规模下仍成立

② 100 工具组内并行
   · 100 工具全声明并发安全 ⇒ 11ms，完成顺序**确实被打乱**（判据会校验
     这一点，否则它测不到并发）
   · 断言每个槽拿到**自己**的结果（并发下若按完成顺序合并就会错位）

③ 串行降级
   · 50 个工具里**一个**未声明并发安全 ⇒ 整批退回串行，
     完成顺序严格等于声明序（106ms vs 并发的 11ms，降级确实生效）

★ 压力测试第一次跑就抓到一个**真实分层缺陷**：
「含非并发安全工具则整批串行」这条规则**只在上层 runGroup 实现**，
而引擎层 execGroup 只信 g.Parallel 字段 ⇒ 任何人直接调 execGroup
都会拿到不受约束的并发。
已修：降级判据下沉到引擎层，新增 batchCanRun(g, runner)，
toolRunner 增加 parallelSafe 方法（生产路径行为不变，只是把判据
放到了它本该在的层）。

过程中压测自身也暴露了两个测试缺陷（都修了）：
· fixture 让 100 个工具写同一个标量槽 o，被静态校验正确拦下
  （"组内并行下同名写入是数据竞争"）—— 压测不该去撞这条规则；
· ★ e2eRunner.called 是无锁 append，100 工具并发时 -race 报出**真竞态**
  （不是误报）—— 加锁 + 提供 calledSnapshot 供断言。

另：建序列与跑序列原本用了**不同 plugin 实例**（序列存在实例的 store 里，
换实例就读不到自己刚建的），已改为同一实例。

回归：go test -race ./internal/plugins/seq 全绿；go test ./internal/... 全绿。
 2026-09-27 14:16:09 +08:00
JianFeeeee
8ca28eb071 feat(toolcall): 工具结果只统计不裁剪（方案 B），并治掉 seq 侧的静默截断 
问题（核实过）：工具结果进 f.Msgs 时**没有任何长度上限**（task.go 直接
`Content: result`），内核也**不预检**是否超长 —— 超限由上游 API 报错。
时间线那侧有预算（ContextTokens = 0.8×窗口，进消息前就裁过），但那只管
a.context 的历史事件，**不管单条工具结果** ⇒ 一条巨大结果可能直接冲破
预算而内核不会提前发现。

为什么**不裁剪**（与方案 A 的取舍）：
· 截断会让模型拿到**残缺**信息，而截断位置由内核武断决定；
· 模型无法得知"这里被截断了"，会基于残缺数据下结论 —— 与本仓反复
  吃亏的「静默降级」同族（`20s` 少引号 → 静默降级 → cmd_run 失败率 34%）；
· 处置权应交给调度器/上层（告警、拒绝、或让模型自己换更窄的查询），
  而不是内核单方面替模型决定。

改动：
· core/toolresult_budget.go: checkToolResultSize 只**计数+报告**；
  阈值默认 = ContextTokens/8（一条吃掉全部预算会把其它上下文全挤掉）；
  报告经 toolResultReporter（可替换），默认 logReporter —— **不给模型发
  消息**：那是在已花掉的 token 之上再加一条 system，且对当前这轮决策无帮助。
· 接入点在 stepToolAfter 的 toolMsg 落定**之后**（那里才是模型最终看到的
  内容；stepToolExec 拿到的尚未经 after_toolcall 改写）。
· TaskFrame 记 oversizeTools / oversizeToolNames，供调度器与状态面查询
  "是否有工具在稳定产出超大结果"。

★ 顺带治掉 seq 侧一处**我自己留下的静默截断**：
handlers.go 里我当初随手写了 truncate(…, 160)，把变量槽静默截到 160 字
且**无任何标注** —— 正是我批评过的静默降级。
改为 renderSlot：≤160 给全；超过则显式标注「已截断：共 N 字，此处显示前
160 字」并给出改法。**槽里存的始终是完整值**，截断只影响回填文本长度。
端到端判据 TestSeqRunDoesNotSilentlyTruncateSlot 抓到了这个缺陷
（"变量槽被截到 160/5000 字却没有任何标注"）。

判据（toolresult_budget_test.go，4 条）：
· 400KB 结果触发超限报告（含工具名与 token 数）
· ★ **默认不裁剪**：200KB 结果原样进 tool 消息（方案 B 的核心不变式）
· 小结果不误报（噪音会淹没有效信号）
· 报告文案可执行：带工具名、token 数、改法建议

变异验证：去掉统计调用 ⇒ 两条判据 FAIL（"统计没生效" + "被裁剪了"）。

另：检查项报 stepToolBatch 的 goroutine 竞态，-race 实测**误报**——
循环变量显式传参（非闭包捕获）、且按索引写各自槽位（非共享 map），
`-race` 下 20 轮并发判据全绿。
 2026-09-27 14:05:38 +08:00
JianFeeeee
116dc413f0 feat(seq): 新增 seq_help —— 格式说明 + 可照抄示例 
动机来自真机实跑：模型写序列时踩了三个坑，各试 1~3 次才改对
  ① tools 漏末尾的 ';'       → 「末尾缺少 ';'」
  ② group 的 in 传成字符串     → 重试 3 次
  ③ as 指向未声明的 out 槽      → 静态校验拦下
这三处都是**格式细节**，塞不进工具描述（有长度限制），却恰是模型最易错处。
散落在七个描述里等于没有集中入口。

实现（help.go + tools.go + plugin.go）：
· seq_help 无参数、纯文本返回（与仓内 output_send__*_help 同范式）
· 「格式要点」逐条写明：in/out 必须是**对象**、tools 必须是**字符串**、
  每个 tool 后（含最后一个）都要 ';'、as 必须在 out 声明、
  groups 与 file 二选一、组内并行组间串行
· 「条件 when」列出支持的表达式形态
· 「可照抄的完整示例」给一行**单行紧凑**的合法序列

★ 判据（plugin_test.go，3 条）：
· seq_help 已注册、有 description、不声明并发安全
· 内容覆盖真机踩过的**每一个**坑（判据从"坑"出发而非从"打算写什么"）
· ★ 示例**自己能被本包解析器接受**：validateHelpExample 从帮助文本里
  抽出示例喂给 Parse —— 模型是照抄的，示例自己解析不过就是给模型挖坑。
  而"从文本里有没有某个词"是看不出这类 bug 的。

过程中判据自己错了两次（都被这条示例判据照出来）：
1. 抽取用 strings.Index(help, `{"name"`) ⇒ 先命中「格式要点」里**有意写的**
   示意片段，截到非示例的内容，报出莫名其妙的 invalid character '…'。
2. 修完又混用两套偏移基准（base 的下标拿去切 help）⇒ invalid character '\xaf'。
   ⇒ 重写为全程在同一 base 上定位。
★ 两次都说明：**判据的抽取逻辑本身就是需要验证的代码**，
它出错时报出的信息极具误导性（看起来像实现有 bug）。

示例形态也改过一次：原为多行缩进 JSON，改为**单行紧凑** —— 模型照抄时
免去缩进/换行带来的额外风险。

变异验证：去掉示例里的末尾 ';' ⇒ 示例判据 FAIL。

另一处：加 seq_help 后「恰好注册 6 个工具」判据 FAIL（实际 7）——
这正是那条判据的用意（防止悄悄多加工具稀释工具面），已更新并注明原因。

回归：go build ./... 通过；internal/plugins/... core sdk 全绿。
 2026-09-27 13:48:15 +08:00
JianFeeeee
0b96d6d78c fix(seq): 类型不匹配的错误改成模型可执行的话（真机实跑发现） 
真机实跑（独立实例）发现：模型把 group 的 `in` 传成字符串 "{}"，
拿到的是 encoding/json 的原始报错：

  json: cannot unmarshal string into Go struct field rawSeq.groups.0.in
        of type map[string]string

这句说的是**事实**（string 解不成 map）而不是**该怎么做**
（in 应该写成对象 {"键":"类型"}）；残留的 `rawSeq` / `Go struct field`
更是 Go 内部实现细节，对模型无意义且会误导它去猜一个叫 rawSeq 的东西。
模型为此**重试了 3 次**才改对。

这与本仓反复吃亏的那类问题同源：`20s` 少引号 → 静默降级 →
cmd_run 失败率 34%。**报事实不报改法，模型只能猜。**

改动（parse.go）：新增 friendlyJSONError，把原始报错翻译成可执行文案
· in / out 类型不符 ⇒ 说明"应写成对象 {键:类型}；无入参请写 {}"
· tools 类型不符 ⇒ 说明"应写成字符串（内容是 ; 分隔的 JSON 对象）"
· groups / name / when / missing / timeout / on_error ⇒ 逐个说明期望
· 未知字段 ⇒ 列出 group 允许的全部字段名（拼写错误最常见）
· shortFieldName 剥掉 `rawSeq` 这类包内类型名前缀
· jsonKind / goTypeName 把 Go 类型翻译成模型看得懂的说法

判据（parse_test.go，2 条）：
· in 传字符串 ⇒ 错误须指名字段、须说明该传对象、**且不得残留 Go 内部类型名**
· tools 传数组 ⇒ 错误须指明 tools 且说明它是字符串

★ 变异验证时踩了一次坑：第一次变异让 friendlyJSONError 不被调用，
结果**编译失败**（函数变成未使用），判据压根没跑，我却看到 "ok"。
改用可编译的变异（函数保留、开头直接 return err）后判据正确 FAIL。
★ 教训：**"变异后判据通过"要先确认变异真的生效**——编译失败 ≠ 判据通过。

真机复验：模型读一次即懂，并明确说"提示里的意思很明确"；
修复前它为此重试 3 次。

回归：internal/plugins/... internal/agent/core internal/sdk 全绿。
 2026-09-27 13:43:39 +08:00
JianFeeeee
7e1169bcda feat(kernel): 内置工具注册进 ToolAPI 面（方案 B，补真机实跑发现的架构缺口） 
真机实跑实证（独立实例 /tmp/seqtest，未触碰生产）：
  seq_run 报「工具 knowledge_list 不存在或未注册」，
  而**同一轮模型直接调 knowledge_list 是成功的**。

根因：`memory_*` / `knowledge_*` / `doc_*` / `person_*` 这 20+ 个是
**内核内置**工具，在 core.executeToolCallInner 里按**前缀分派**，
由 buildToolDefs 直接生成 schema，**从不进 StageHost / IOManager**
⇒ ToolAPI（只有插件工具 + IO 设备工具）既查不到也调不了。
后果：序列只能编排插件/设备工具，无法编排记忆/知识/文档/人物
——恰恰是最常用的能力。

方案 B 的实现：
· internal/sdk: 新增 BuiltinProvider（Defs/Exec）与 SetBuiltinProvider。
  用**晚绑定注入**而非让 toolImpl 依赖 core，理由：ToolAPI 是**全局单例**
  却需要 per-agent 数据（驻留子是轻量内核，memory 为 nil；内置工具可见性
  由 `if a.memory != nil` 等门控）。sdk 不能依赖 core（方向反了）。
· internal/sdk/tool_impl.go: ToolDefByName / ExecuteTool 补查内置工具。
  ⚠️ ExecuteTool 只在「io 确实没有该工具」时才转内置；io 的**执行失败**
  必须如实上抛 —— 否则会把「设备离线」误报成「工具不存在」，让调用方
  按 missing 策略跳过（与 P3 修过的父 io 吞错误同一族陷阱）。
  内置工具**默认不声明 ParallelSafe**（含 SQLite 写与召回）。
· internal/agent/core/builtin_toolapi.go: Agent 侧 provider。
  ★ Defs **复用 buildToolDefs 的同一批生成逻辑**（筛出不在
  StageHost/IOManager 中的那些），保证"模型看得到什么"与"插件看得到什么"
  门控完全一致 —— 避免两套语义。
  Exec 复用 executeToolCall 完整路径（授权闸 + 异常处理）。
· cmd/homed/bootstrap.go: agent 构造后注入。

★ 不会让模型看到重复工具（已核实）：模型侧走 buildToolDefs
（a.io / a.stageHost **直调**），ToolAPI 只经 PluginSDK.Tool() 暴露给插件
—— 两条不重叠的路径。

判据（builtin_toolapi_test.go，6 条）：
· 内置工具能从 ToolAPI 查到
· ★ 查到 ≠ 调得通：必须真的能执行
· 门控语义保持：未接 memory/knowledge 时不得声称有那些工具
· ★ 接了 knowledge 时必须可见（这正是要补的缺口）
· ToolAPI 上"不存在"必须是类型化 not-found（供 seq 的 missing 策略用）
· 内置工具默认不声明并发安全

真机复验（同一隔离实例，新二进制）：
  序列 "smoke2" 执行完毕（1/1 组）— 工具 1 个
  变量槽: summary = cangjie/central-repo/agreement/...
⇒ knowledge_list 成功执行并回填具名槽。上一次的「不存在或未注册」已消除。

已知局限（记入待定）：ToolAPI 单例而内置工具面是 per-agent，
多 agent 下看到的是"最近一个注入者"的面。本次不解决。
 2026-09-27 13:40:22 +08:00
JianFeeeee
4fd18a2e83 docs(plan): 遗留项收敛——D4 与端到端已完成，提权无需决策 2026-09-27 13:18:28 +08:00
JianFeeeee
3d31037f63 test(seq): 端到端接线判据，抓出「传参方式完全不可用」的真 bug 
P1–P4 的判据都在**包内**（假 runner / 直接调函数），覆盖的是**语义**；
本轮补的是**接线**层——参数名对不对、返回值模型读不读得懂、跨层调用断不断。
接线层的 bug 语义判据抓不到：例如工具注册了但参数名拼错，单元判据全绿
而模型永远传不进来。

★ 抓到一个真 bug：**seq_create 走 groups 传参时完全不可用**。
根因：marshalGroups 只把 groups 包进 JSON 文档、不带 name，而 Parse 要求
name 非空 ⇒ 报「序列缺少 name」。而 seqCreate 里那句
`if seq.Name == "" { seq.Name = name }` 回落分支是**死代码**（Parse 早就失败了）。
后果：**只有 file 方式能用，传参方式一律失败**。
已修（name 一并包装）。包内判据抓不到这个——它们直接构造 *Sequence，
不经过这条路径；只有真正 dispatch 一遍才暴露。

判据（e2e_test.go，7 条）：真实 dispatch 串通
seq_create → seq_list（须展示签名，模型据此按名调用）→ seq_run
（执行序按 tools 声明序、槽回填、结果里**不得**出现 Go 的 `map[` 语法）
· seq_call 按名调用 group 并返回其出参
· seq_when_call 条件为假 ⇒ 跳过且**零工具被执行**
· seq_when_call 条件畸形 ⇒ **报错**且零执行（不得静默跳过）
· seq_create 走**文件**（长序列的主力用法）
· groups 与 file 同时传 ⇒ 报错「二选一」
· seq_delete 不存在 ⇒ 报错（模型会以为删掉了）

过程中又一次臆造 helper（`writeFile`），改用 os.WriteFile；
并把三处 `_, _ = p.dispatch(...)` 补上 err 检查（正是
go-ignored-call-result 报的那类）。

回归：seq -race 全绿；go build ./... 通过；go test ./internal/... 全绿。
 2026-09-27 13:18:19 +08:00
JianFeeeee
994f198bc5 fix(security): 设备授权闸下沉到 ToolAPI 路径（D4，堵住绕过） 
问题：设备类工具的授权闸只存在于 core.executeToolCallInner
（toolcall.go:151-152），即**「agent 收到模型 tool_call」那条路径**。
而 ToolAPI.ExecuteTool 是**另一条**独立执行入口，不经那道闸
⇒ 凡是走 ToolAPI 的调用都能绕过 AllowedOutputs。

实测范围**不止序列**：cli 插件的 /terminal 直接经 ToolAPI 调 agentcli 的
终端工具（cli/plugin.go:1038 的注释自陈"SDK 的 ToolAPI 已允许跨插件调用
工具"）。任何插件拿 ToolAPI 都能指挥未授权的设备。

改动：
· internal/sdk/tool.go: ToolAPI 新增 CanUse(toolName, args) bool。
  **纯新增方法**，零值实现返回 true ⇒ 未实现者（存量插件、测试替身）
  行为不变。
· internal/sdk/tool_impl.go: 实现 CanUse。判据只有一条——设备类工具按
  `device/<id>` 查授权；非设备工具不受影响（闸的作用域必须窄，否则会把
  所有工具锁死）。
  授权查询走**可注入**的晚绑定闭包：toolImpl 在 internal/sdk，而
  IsOutputAllowed 是 core.*Agent 的方法，sdk 不能依赖 core。
· internal/plugin/registry.go: 新增 SetDeviceAuthQuery。
· cmd/homed/bootstrap.go: 在 newMainAgent 末尾注入。⚠️ 必须在 agent
  构造**之后**——判据要用 agent 自己的 allowedOutputs，而 registry 早于
  agent 构造，故 registry 存的是晚绑定闭包。

判据（toolapi_auth_test.go，7 条），核心是**两条路径必须一致**：
· 收窄授权时 ToolAPI 路径同样被拦
· 已授权设备放行（防闸过严杀掉正常能力）
· 非设备工具不受影响
· 枚举类工具不受影响（与内核 TestDeviceToolAuth_EnumerationNotGated 同语义）
· 未配置白名单 = 完整授权
· ★ TestCanUseAgreesWithInnerPath：4 组用例逐例比对内核路径与 ToolAPI
  路径的结论 —— 判定不同本身就是漏洞
· ★ TestCanUseMatchesInnerFailOpenOnMissingDeviceID：把现状
  （缺 device_id 时**放行**）钉住。⚠️ 这是 fail-open，是既有的可疑设计
  （core 的 TestDeviceToolAuth_* 依赖它），本次不擅自改语义；判据写明
  "若要改成 fail-closed，必须两处同时改"。

过程中三次自伤：
1. 一度在 core 写了个 toolAPIRef —— **只实现部分方法的替身**是过度设计，
   且两份实现必然漂移。改为判据直接用 sdk.NewTool(stageHost, iom)，
   与插件侧走**同一个**实现。
2. 判据里又写了 `var _ = agentIO.DeviceOutput` 这种压 unused import 的
   占位 hack（第二次犯这个），并重造了 strings.Contains。都已去掉。
3. 注入点一开始找错了位置（以为 newStageAndRegistry 能拿到 agent，
   实际 pluginReg 是 main() 的局部变量）。核实 newMainAgent 的签名后
   确认它同时持有 agent 与 pluginReg，注入点落在那里。

变异验证：让 CanUse 恒返回 true（还原成原缺口）⇒ 两条判据 FAIL，
其中一条直指「内核路径=false 而 ToolAPI 路径=true —— 两条路径判定不一致」。

回归：go build ./... 通过；go test ./internal/... 全绿。
 2026-09-27 13:15:22 +08:00
JianFeeeee
532500e3c9 docs(plan): 内核主线与插件线全部完成，记录两个设计决策与三处遗留 2026-09-27 13:06:10 +08:00
JianFeeeee
71c894c182 feat(seq): 六个 seq_* 工具、插件装配，并补内核两处缺口（插件线 P4） 
内核缺口（都是 P3 落地时暴露的真实缺陷）：
· **GetAllTools 丢 ParallelSafe**：它只带出 Name/Description/Parameters，
  插件看到的设备工具一律"不可并发" ⇒ 设备工具的并发声明**对插件不可见**。
· **ToolAPI 缺按名查**：新增 ToolDefByName。插件需要在**运行前**判断目标
  是否存在/是否并发安全（工具动态注册，"不存在"是常态），
  而 GetAllTools 只能拿到全量列表。查不到返回 nil，不 panic。

seq 插件：
· plugin.go：插件骨架 + kernelRunner（把 sdk.ToolAPI 收窄成三个方法，
  判据因此能用假实现驱动，不必构造整个内核）
· tools.go：六个工具定义（独立真相源，注册/判据/文档都从它取）
· handlers.go：seq_create/list/delete/run/call/when_call 的实现
· register.go + all.go：按 skillmgr 同一范式 init 注册

★ 过程中解决一个**我自己的设计矛盾**：
判据原先要求 `seq_call` / `seq_when_call` 进黑名单，但"按名调用
group/序列"恰恰是本包的核心能力——禁掉它，序列就退化成单层脚本。
分层澄清后：黑名单只管**对外发消息 / 起子 agent / 改插件表 / 再跑整条
序列**；seq_call 系列留给序列内部组合，其递归由 maxCallDepth + 环检测
负责（设计文档 §8.3 本来就是这么定的，我把两层混了）。
`seq_run` 留在黑名单：序列内再跑整条序列语义上是递归。

**六个工具一律不声明 ParallelSafe**：seq_run/seq_call 会执行一串工具，
其中可能含写操作；标成并发安全会让内核把两条 seq_run 并发跑，
两个序列的执行顺序交错、变量表互相污染。

安全性：序列名与文件路径都做穿越防护（`..` 段、分隔符、空名）。

过程中四次自伤：
1. 臆造 `jsonMarshalIndent`（不存在）→ 改 encoding/json.MarshalIndent；
   并把 execGroup 的 runner 传错成 p（应 p.runner）。
2. seq 判据里写了 `black(name)`，而 blacklisted 是**谓词**不是函数。
3. 一次 python 替换删漏，把「跨序列目标存在性检查」那段从 CheckNew
   里整段摘掉又贴回原处——靠编译错误发现。
4. ★ 注册失败我写了 panic：内置插件在 main() 装配期加载，panic 会
   **直接拖垮内核启动**，而"某个工具没注册上"只该让该工具不可用。
   已改为 log.Printf + 继续（与 clawhubadapter / mcp 一致）。

变异验证：把 seq_run 移出黑名单 ⇒ 黑名单判据 FAIL。

判据（plugin_test.go，6 条）：六个工具全部注册且 description/参数 schema
非空；seq_create 声明 required 并说明 groups/file 二选一；
seq_run 说明"按数组顺序"；六个工具均未声明 ParallelSafe；
黑名单含递归风险项且**不误伤** seq_call 与普通工具。

回归：seq -race 全绿；internal/sdk/... internal/plugins/... 12 包全绿。
 2026-09-27 13:05:28 +08:00
JianFeeeee
3d753126a3 feat(seq): 序列存储、跨序列调用图与 missing 策略（插件线 P3） 
store.go：
· **存 AST 不存文本**。执行期不重新解析原始文本 ⇒ 一次格式改动不会
  悄悄改变已保存序列的行为。
· 先写 .tmp 再 rename，避免写一半被读。
· **路径穿越防护**：序列名来自模型且被直接拼进文件路径，不校验的话
  `seq_load("../secret")` 能读任意文件、`seq_delete` 能删任意文件。
· CheckGraph：跨序列调用的**目标存在性** + **环检测**（三色 DFS），
  报错时给出**环路径**（#A → #B → #A），便于定位。
· maxCallDepth = 4 是**结构常量**不是配置项 —— 沿用内核
  MaxInterruptFrames 的做法（core/scheduler.go:271「结构上界，不是配置项」）：
  上界一旦可配，总有人会把它调到栈溢出。

exec.go 补 missing 策略（动态注册下「工具不存在」是**常态**）：
· fail（默认）/ skip / degrade，与「执行失败」严格分开
· ⚠️ missing 分支**必须先于**通用 on_error 检查：否则「插件挂了」会被
  on_error=abort 连坐整组中断，skip/degrade 形同虚设
· skip 时**不赋值槽**（与「条件为假」同一情形，下游要能应对槽缺失）
· 本包自带 errToolNotFound 哨兵而**不复用** io 包的同名错误：seq 是插件，
  拿得到 sdk.ToolAPI，拿不到 io 包类型（见设计文档 §7 边界声明）

★ 过程中解决一个**设计死锁**（值得单列）：
我最初让 Save 校验「跨序列目标必须已存在」。但互调的两条序列
谁也存不下来——A 要 B 先在、B 要 A 先在，**依赖在设计上无解**。
⇒ Save 只校验**同序列内**的 group 引用（那部分信息自足）；
  跨序列目标的存在性与环由 CheckGraph 在保存后统一兜底。
  判据与实现都写明了这个分工的理由。

判据（store_test.go，7 条）：
· 存取往返保住 AST（含 out 声明——它是签名的一部分）
· 列表 / 删除；删不存在的**报错**（不静默成功，模型会以为删掉了）
· ★ 跨序列成环被拒且错误含环路径；无环通过
· maxCallDepth 是正的结构常量
· ★ missing 三种取值各有明确行为
· ★ 路径穿越：7 种恶意名既读不到也删不掉，且**在 store 目录外**放真实
  文件断言它仍在（不是"读代码看着对"，是跑出来的）

过程中三次自伤：
1. 序列名我写成 "#A"/"#B"——`#` 只是 target 里的前缀标记，
   落盘名不带它，于是 CheckGraph 找不到、误报「不存在」。
2. missing 策略与 on_error 检查的**顺序**反了，导致 skip/degrade 被
   abort 连坐（判据直接暴露）。
3. 为压掉 unused import 写了 `var _ = os.Remove` 这种占位 hack ——
   正是检查项 go-ignored-call-result 指出的那类东西，已删；
   另把 rename 失败分支的 `os.Remove(tmp)` 加上注释说明
   「清理失败有意忽略，否则会盖掉真正的失败原因」。

变异验证：去掉环检测（三色 DFS 全放行）⇒ 成环判据 FAIL
（"A→B→A 成环却通过检查"）。

回归：-race 下 seq 全绿；internal/plugins/... 全绿。
core 包偶发 TestResidualKeep 失败是**已记录的既有竞态**
（offload_test.go 的 SpawnResident 起了子调度器而测试无同步就读队列），
与本阶段无关，已在执行计划中记为待修。
 2026-09-27 12:47:18 +08:00
JianFeeeee
7532af7e9b feat(seq): 执行引擎 —— 组内并行 + 具名槽 + 条件求值（插件线 P2） 
三个不变量（各有判据钉住）：

1. **组内并行、组间串行**。parallel=true 时各工具并发执行。

2. ★ **合并按声明顺序**，不按完成顺序。
   并行下完成顺序不确定；若按完成顺序合并，同样的输入产出不同的结果，
   整条序列**不可复现**。做法：各工具把结果写进 `results[i]`（按索引），
   组屏障处按 tools 数组顺序一次性合并。
   顺序合并顺带解决了并发写 map —— **执行期完全不写共享 map**。

3. ★ **条件求值失败必须报错**，不得降级成"条件为假"。
   把求值失败当作跳过 = 序列安静地少做一步，而模型以为跑完了
   —— 与「静默吞工具」同族（那正是 P1 判据里刚堵上的同类问题）。

条件求值（设计文档 §5 的 L1+L2，不引表达式引擎）：
· true/false、$args.key 裸引用（真值）
· == / != / > / < / >= / <= 、contains
· 字面量支持 "str" / 'str' / true / false / 数字 / 裸文本
· 布尔与字符串宽松比较（true == "true"），对齐 utils.getBool 的既有约定

变量插值两种形态（缺一不可）：
· **整值引用** "$args.count" ⇒ 替换为**原始值并保留类型**
  （数字仍是数字；否则模型收到字符串 "3"）
· **文本内插值** "ssh $args.host" ⇒ 在字符串内替换
· 标量渲染：对象/数组用**紧凑 JSON**，绝不用 fmt.Sprintf("%v")
  （那会产出 `map[k:v]` 这种模型读不懂的 Go 语法）

on_error：abort（默认）/ continue。失败时也留槽（记错误文本）——
否则后续组读到的是"缺失"，而"缺失"与"值为空"在下游难以区分。

判据（exec_test.go，8 条）：
· 具名槽写入正确
· ★ 结果按声明顺序合并（用 delay 让完成顺序**确实**打乱）
· array 槽同名 as 按声明顺序确定性追加
· 条件为假 ⇒ 整组跳过、槽**不赋值**、零工具被执行
· ★ 条件畸形（空键 / 引用未声明入参 / 语法不完整）⇒ 报错且**不执行任何工具**
· 条件为真 ⇒ 正常执行
· on_error 的 abort / continue 两种语义
· 插值：文本内替换 + 整值引用保留类型

过程中三次自伤：
1. ★ **toolRunner 接口第一版写成 call(name)**，不收 args ⇒ 插值判据成了
   摆设（永远"通过"）。改为 call(name, args) 后插值才真正可观察。
2. toolRunner / compactJSON 定义在了 _test.go 里，exec.go 引用不到 ⇒
   build 失败。toolRunner 是**引擎的依赖契约**，必须在非测试文件。
3. fixture 里给 "slow" 配了不存在的返回值，误以为它该返回 "B" ——
   是我没配就断言，不是实现错。

变异验证：把合并改为"按完成顺序 append"⇒ array 槽顺序判据 FAIL，
报错直指 `[C A ran:slow]` vs 期望 `[A ran:slow C]`。
（第一版变异用了一个 no-op 的 sort.SliceStable，等于什么都没测，
 已改成真正模拟完成序的实现。）
`-race` 全绿；回归 internal/agent/... internal/plugins/... 全绿。

顺带修正设计文档：两处 tools 示例原写成 `{tool:cmd_run,...}`，
**不是合法 JSON**（P1 判据实测会解析失败）。已改为合法 JSON 并加注
「键要带引号，这是实现时判据跑出来的真实缺陷，不是假想」。
 2026-09-27 12:29:56 +08:00
JianFeeeee
76030ae30e feat(seq): 序列文本 → AST 解析与静态校验（插件线 P1） 
插件，不是内核：并行执行是内核提供的**唯一**基础设施（core 的
batchRunnable）；分组 / 具名槽 / 条件 / 调用图全部在本包内自建，
**不要求内核开任何新接口**。

实现（parse.go）：
· Sequence / Group / ToolCall 三个 AST 类型
· Parse：JSON → AST + **全部**静态校验一次做完
  （而非留到执行期——group 有独立签名，具名槽的价值就在于构建期就能
  查出错写的槽）
· splitToolList：`;` 仅在 brace 深度 0 且**不在字符串内**时才是分隔符
· 枚举/未知字段一律硬报错：DisallowUnknownFields + 显式校验
  （missing / on_error 报错时列出合法取值，不当默认值蒙过去）

静态校验规则：
· `as:X` 未在 out 声明 ⇒ 报错（具名槽的核心价值）
· `$args.X` 未在 in 声明 ⇒ 报错
· group 名重复 ⇒ 报错（签名名必须唯一才能按名调用）
· 非 array 槽被同名 as 写多次 ⇒ 报错（组内并行下同名写入是数据竞争）；
  array 槽则允许（组屏障按序追加）
· tools 分隔符畸形（漏中间 / 漏末尾 / 连续 / 未闭合）⇒ **硬报错**，
  绝不静默吞掉一个工具

判据（parse_test.go，9 条），★ 两条最关键：
· 含分号的真实 command（取自 core 里那份线上日志 fixture）保持为 1 个工具
· ★ TestBracesInsideStringDoNotAffectDepth：字符串里的**不成对**花括号
  不得影响 depth

★ 本阶段的三次自伤（都靠变异测试暴露，不是靠判据变红）：
1. **格式本身是错的**：我在设计文档里写的 `{tool:cmd_run,...}` 根本不是
   合法 JSON（键没引号），encoding/json 直接解析失败。判据一跑就暴露
   ——"写了格式却从没验证它能解析"。已改为要求合法 JSON（键带引号），
   这也是 DisallowUnknownFields 能生效的前提。
2. **判据验证的不是它声称验证的规则**：原本那条"分号在字符串内"的用例，
   分号其实落在 args 对象的**花括号内部**，depth>0 就足以保护 ⇒ 删掉
   分词器的字符串跟踪后**仍然全绿**。反复两次才找到真正的判别点：
   必须用**不成对**花括号在 depth 恰为 0 处，才只有字符串态能救它。
3. 手写多层转义把引号写成 \"，使分词器永远进不了字符串态。改用
   json.Marshal **分层构造** fixture——手写转义没有不出错的机会。

变异验证（两轮，均能检出）：
· 删掉"回到顶层必须紧跟 ;"检查 ⇒ 漏中间分隔符用例 FAIL
· 删掉字符串跟踪 ⇒ TestBracesInsideStringDoNotAffectDepth FAIL
  （"结构未闭合（括号深度 1）"）

回归：internal/agent/... internal/plugins/... 全绿。
 2026-09-27 12:05:27 +08:00
JianFeeeee
9746538a00 docs(design): 补 0.2 阶段行 2026-09-27 11:56:19 +08:00
JianFeeeee
ae3cdaa1a0 docs: 同步两份文档的实现进度（内核主线 0~2.5 全部完成） 2026-09-27 11:56:01 +08:00