|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
4fd18a2e83
|
docs(plan): 遗留项收敛——D4 与端到端已完成，提权无需决策
|
2026-09-27 13:18:28 +08:00 |
|
|
|
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 |
|
|
|
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 |
|
|
|
532500e3c9
|
docs(plan): 内核主线与插件线全部完成，记录两个设计决策与三处遗留
|
2026-09-27 13:06:10 +08:00 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
9746538a00
|
docs(design): 补 0.2 阶段行
|
2026-09-27 11:56:19 +08:00 |
|
|
|
ae3cdaa1a0
|
docs: 同步两份文档的实现进度（内核主线 0~2.5 全部完成）
|
2026-09-27 11:56:01 +08:00 |
|
|
|
0327419c88
|
feat(prompt): 提示词声明「同轮默认并行」及其例外（阶段 2.5）
⚠️ 本阶段有硬性顺序约束：必须在并行执行（阶段 2d）落地**之后**。
反序（先说"并发"、内核仍串行）会让提示词**对模型说谎** —— 模型据
"并发执行"推断安全性，写出真正依赖顺序的调用。宁可晚改，不可错改。
改动（tooldefs.go，buildSystemPrompt）：
· 新增【工具执行顺序】段，讲清四件事：
1. 同一条回复里的多个工具调用**默认并行**（同时跑），不是依次执行
2. **不要依赖执行顺序** —— 参数依赖前一个结果就分两轮
3. **例外一：同通道 output_send__ 保序**（用户可见消息顺序敏感）
4. **例外二：不并发安全的工具整批退回串行**（写类工具 / 未声明者）
· 顺带说明并发安全由**工具自己声明**（ParallelSafe），不由模型判断
· 改掉 spawn_child 的落空表述：原文「应并行 spawn，不要自己串行逐个执行」
在并行化之前是**落空**的（模型照做，内核仍串行）。改为机制性表述，
并补一句「一次 spawn 只是启动动作，要拿结果仍需另一次 child_result」。
⚠️ 措辞刻意与 batchRunnable 的**真实**判据一致（全批 ParallelSafe 才并发
+ 同通道保序），而不是理想化表述 —— 提示词与实现不符，比不说更坏。
判据（prompt_parallel_test.go，5 条）：
· 四要点齐全（并行 / 顺序 / 保序 / 并发安全声明）
· ★ 必须同时讲**例外** —— 只讲并行就是"说谎"的那一种
· 同通道保序须显式说明（保序是内核兜底，模型不知情就会浪费它）
· spawn_child 不再含旧的落空措辞
· 回归防护：既有要点（输出规则 / output_list_channels / 工具能力 / 记忆清理）不丢
★ 判据里的一次自伤：先写了 spawnChildDescription(a) 这个**不存在**的
helper（"工具名反查描述"），编译失败后改为 toolDefDescription —— 内部
遍历 buildToolDefs 的**真实产物**。判据必须对着代码真实输出，不能另建一套
注册表。
变异验证：把两条例外改写成"以上适用于所有工具"⇒ 3 条判据 FAIL
（缺"保序"、缺"例外"、同通道未说明）。即"提示词说谎"这一失败模式
现已被判据覆盖。
回归：internal/agent/... internal/sdk/... internal/plugins/... 全绿（15 包）。
|
2026-09-27 11:55:33 +08:00 |
|
|
|
446645d0a0
|
docs(plan): 阶段 2 标记完成，记录并发规则与 2c 判据闭合
|
2026-09-27 11:27:53 +08:00 |
|
|
|
34c0df2705
|
feat(toolcall): 批次并发调度与同通道保序（阶段 2d，闭合 2c 判据缺口）
规则（三条全满足才并发）：
1. 批内 >1 个工具
2. **全部**工具声明 ParallelSafe —— 一个不声明就整批降级，不做部分并发
3. 不含需保序的同通道输出发送
SDK：
· ToolDef 加 ParallelSafe bool。⚠️ 零值 false 是刻意的：存量插件不改一行
就得到**保守**行为（整批串行），不会因升级被意外并发。声明它是责任
而非特权。纯新增字段，无签名变更。
· io.ToolDef 同步加该字段（设备/通道工具走 io 路径，只查 StageHost 会漏）。
core：
· 新增 StepToolBatch —— runTaskSteps 是单线程驱动状态机的，
「每步一个工具」的游标模型无法表达「一批同时跑」，故需独立 step。
· stepToolBatch：fan-out（每工具一 goroutine，各写自己的 toolCtxs[i]）
→ join → **按索引顺序**串行收尾（after_toolcall / 落消息 / 事件）。
收尾必须串行且按索引：f.Msgs 是共享切片，且按索引落才能让模型读到的
上下文顺序与它自己发出的顺序一致。
· runOneTool 抽出「before_toolcall + 执行」的单工具逻辑，串行/并发两条路共用。
· toolParallelSafe / batchRunnable 判据函数。
★ 修掉一个我自己引入的竞争：resolveTurnScenes 会把结果记进**共享**的
f.sceneDone / f.turnScene（memorypass.go:289）。最初在每个 goroutine 里
各调一次 —— 既是数据竞争，又会各自触发一次 EnterSceneWithHint，
重复计入场景强度（正是 sceneDone 注释警告过的问题）。改为在 fan-out
**之前**解析一次，goroutine 内只读。
判据（parallelsched_test.go，4 条）：
· 全批 ParallelSafe ⇒ 并发峰值 >= 2（用阻塞设备观察真实并发）
· 一个非 ParallelSafe ⇒ 整批串行，但**仍全部执行**
· 同 output_send__<通道> 连发 3 条 ⇒ 严格按声明顺序到达
· ★ 并发下每个工具的 ctx 只带自己的 ToolCalls、after 读到自己结果
★ 并关闭了 2c 的判据缺口：此前两条 2c 判据在**串行**下无法区分
per-tool 与单槽（变体验证后仍全绿）。新增的并发版判据在退回单槽时
触发 **6 处 DATA RACE 报告 + 串味断言失败**（dup:k_a 与 k_a 撞名）。
至此 2c 可记为已验证。
过程中三次自伤：
· resolveTurnScenes 竞争（上述）；
· 我的 harness 用 StageHost 注册 handler 遮蔽了设备工具，
slowDevice 根本没被调用（"实际 0"）——改为在 io.ToolDef 上声明；
· 批内并发峰值判据最初用 StageHost 声明 ParallelSafe，掩盖了
「设备工具也需要该字段」这一真实缺口。
回归：internal/agent/... internal/sdk/... internal/plugin/...
internal/plugins/... 全绿（17 包）；core 包 -race 全绿。
|
2026-09-27 11:27:24 +08:00 |
|
|
|
3d12e82f65
|
refactor(toolcall): StageContext 拆 per-tool，为并发执行消除共享槽（阶段 2c）
问题：f.StageCtx 是**单槽**，批内每个工具都覆写它（ToolCalls=[单元素]、
ToolResults 覆写、Results[0] 回读）。串行下看不出问题，但并发下
N 个 goroutine 同写一个 ctx = 数据竞争，且 after_toolcall 插件可能读到
**别的工具**的结果。
改动（task.go）：
· TaskFrame 增 toolCtxs []sdk.StageContext（每工具一份）
· buildToolContexts 在 stepLLM 设 PendingTools 时建池；
Extra **逐份浅拷贝**——共享同一 map 即竞争（stage handler 会写它）
· toolCtxFor(i) 取第 i 份，越界/未建时回落 f.StageCtx（测试替身安全）
· stepToolBegin（before_toolcall + 参数回填）、stepToolExec（写结果）、
stepToolAfter（读结果）三处全部切到 per-tool ctx
判据（toolbatch_test.go 追加两条）：
· 每个工具的 before_toolcall ctx 只带自己的 ToolCalls[0].Name，
且 Extra[output_channel] 逐份带过去（stage.go:18 依赖它）
· after_toolcall 读到的 Result 必须属于当前工具，不能是批内另一个的
★ 诚实记录：这两条判据在**串行**下**测不出与单槽的差别**——串行时
每工具跑完才进下一个，不存在交错。变体验证（toolCtxFor 退回单槽）后
判据仍全绿。故 2c 记为「实现已就位、判据未闭合」，真正判据必须与 2d
（并发执行）一起写，并以 -race 确认无竞争。已在执行计划中标注。
过程中两次自伤：
· 我的 harness 没设 Extra[output_channel]（那是 prepareInputTask 才写的，
task.go:380），判据一度报「产品缺陷」——核实后是我造的场景，已对齐生产；
· 阶段 1 的 TestStageCtxSuccessIsHonestEndToEnd 读 f.StageCtx.ToolResults，
拆分后失效——判据跟随新结构改为按批索引取 toolCtxs[i]，
断言的仍是内核产出的 Success 值本身。
顺带记录（非本次引入）：TestResidualKeep/Drop 偶发失败，根因是
offload_test.go 的 SpawnResident 起了子调度器 goroutine，而测试
enqueue 后无同步就读同一队列。干净基线 3/3 全绿属运气。已在计划中
记为待修，避免后续误判为并行化引入的回归。
|
2026-09-27 11:17:06 +08:00 |
|
|
|
28b42bcf0f
|
refactor(toolcall): 批内消息改为「一个 assistant 带全部 tool_calls」（阶段 2a）
问题：现状每个工具各自 append 一对（assistant[tool_calls=[tc]] + tool），
既不表达「这是一批」，也无法支撑并行：
· 产生 N 条 assistant 消息，同一段 assistant 文本语义上只该出现一次
· 并行下完成顺序不确定，若等结果回来再落消息，assistant 就必须等所有
结果齐了才能写——而 OpenAI 协议要求 assistant(tool_calls) 在结果**之前**
改动（task.go）：
· TaskFrame 增 assistantMsgIdx
· 新增 ensureBatchAssistant：惰性写入，全批只写**一条** assistant，
携带 f.PendingTools 全部 tool_calls；后续工具只补 tool 消息
· stepToolBegin 的 denied / unhealthy 分支与 stepToolAfter 统一改用它
· stepLLM 设 PendingTools 时清零 assistantMsgIdx
· msgContent 的 ContentOnce 归位移入 ensureBatchAssistant（仍是只挂第一条）
⚠️ 依赖：before_toolcall 阶段**不得**改写工具参数——已核实全仓无此用法
（grep ToolCalls[0].Arguments 赋值无结果）。若将来某插件要改写 args，
需改为「回填后重写该条 assistant」。该前提已写入代码注释。
判据（toolbatch_test.go 追加 TestBatchLayoutSingleAssistantCarriesAllToolCalls）：
· 带 tool_calls 的 assistant **恰好一条**且携带 2 个 tool_calls
· 其后紧跟 2 条 tool 消息且按声明顺序（c1、c2）
变异验证：让 ensureBatchAssistant 退化为「每工具一条」⇒ 判据 FAIL
「批内 assistant 应带 2 个 tool_calls，实际 1」。
stage 0.5 补的三条判据（配对完整性 / ContentOnce / denied 后继续）
在本改动后**仍然全绿**——它们正是为这种改动准备的保护网。
回归：internal/agent/... internal/sdk/... internal/plugins/... 全绿（18 包）。
|
2026-09-27 11:09:02 +08:00 |
|
|
|
25f5c53086
|
feat(io): 多模态块改 per-call 归档，为并行执行铺路（阶段 2b）
问题：ConsumeToolBlocks 此前是 **IOManager 级单队列**（取走即清空），
没有 call_id 维度。并行化后同批多个工具各自注入媒体时，后执行的
Consume 会**抢走**前一个的块 ⇒ 媒体挂到错误的 tool 消息上。而
task.go 里「媒体必须走 user message 且紧跟自己的 toolMsg」那条结论
是三轮实测才定下来的，并行会直接破坏它。多模态插件在 3 处调
SetToolBlocks（multimodal/plugin.go:136,246,320），是真实使用面。
改动：
· 字段 toolPendingBlocks: []interface{} → map[string][]interface{}
· 新增 SetToolBlocksFor / ConsumeToolBlocksFor / ClearToolBlocks（按 call_id）
· 保留 SetToolBlocks / ConsumeToolBlocks 作兼容入口（走 callID=""），
存量调用方与串行单工具场景不受影响；其注释写明并行下该路径不可靠
判据（toolblocks_test.go，4 条）：
· 两个 call 各自注入、**交叉顺序**并发取回，各归其主
· 取走即消费（二次取回为空）
· 未知 callID 返回空且**不影响他人**的块
· 32 路并发零串味
变异说明：本阶段是从「单槽」直接改为 per-call，旧实现在这四条判据下
（per-call API 不存在）无法编译通过，等价于判据先失败；per-call 版
再经 `go test -race` 验证无数据竞争。回归：internal/agent/io 全绿。
|
2026-09-27 11:06:41 +08:00 |
|
|
|
bce40b5099
|
feat(toolcall): 按 schema 预校验参数，在分派前拦下（阶段 1c）
问题：`required` 在仓内被声明 69 处，却**无任何消费方**（内核从不读）。
校验散落在每个工具内部手写成中文字符串（"path is required"），
要等工具真被调用才暴露——而模型看到这类与真因无关的报错只会原样重试
（实测 cmd_run 失败率 34%~48% 的成因）。
改动：
· core/argvalidate.go: validateToolArgs（纯函数）+ validateArgsAgainstSchema。
★ 校验器刻意**宽松**：只拦真正无法解析的形态，对模型实际会写的等价形态
一律放行。依据是工具内部 getter 的既有约定（utils.go 注释：
"实际调用里 bool/string/float 三种都出现过"；unitNumberRe 修的正是
`"20s"` 少引号那类）。**校验比工具更严就是在制造新失败**。
· required 判据是**键存在性** + 非空字符串；显式 null 视为已提供
（模型可能有意传 null，工具按零值处理，判成缺失即误伤）
· boolean 全放行（getBool 的 true/"1"/"0"/"yes"/0/1 全都合法）
· integer 接受 int/float64/"20"/"20s"；string 接受含 JSON 的长文本
· 无 schema / 无 required / 查不到 schema ⇒ 一律放行
· core/toolcall.go: 在 __arg_error 短路**之后**、分派**之前**接入。
· io/channel.go: 新增 IOManager.ToolDefOf——没有它就只校验到插件工具，
而 cmd_run / files_write 这类**设备/通道工具会完全绕过校验**。
判据（argvalidate_test.go，7 组）：
· 缺 required 被拦下并指名字段
· ★ 误伤防线：bool 传 "true"/"0"、integer 传 float64/"20"、
显式 null、字段顺序不同 —— 全部必须放行
· 类型确实不符报 type 错误
· 无约束场景一律放行（含 args 为 nil + schema 带 required ⇒ 应拦，
这条我最初**误放进放行组**，写完立刻发现改正）
· 错误文案含字段名/必填/改法（否则模型只会原样重试）
· 端到端：缺参时**设备真的没被调用** + 文案指名字段
· 端到端反向：参数齐备照常执行（校验不得阻塞正常路径）
变异验证（两轮）：
· 关闭分派前校验 ⇒ 端到端判据 FAIL「仍进入了工具」
· 把 boolean 校验改严格 ⇒ 宽松防线 FAIL 两个子用例（误伤 "true"/"0"）
过程中三次自伤：臆造 sdkToolError 别名；number 分支写了没有绑定的 x(v)；
把"显式 null"先当成缺失、过度修正后又漏掉"键不存在"的判定——
最终改为「键存在性 + 非空串」双条件，null 与缺失各归其位。
回归：internal/agent/... internal/sdk/... internal/plugin/...
internal/plugins/... 全绿（18 包）。
|
2026-09-27 10:56:02 +08:00 |
|
|
|
396d13e9af
|
feat(toolcall): 结果契约诚实化 —— Success 不再恒真 + 结构化失败可回填（阶段 1b/1d）
问题（实测，三条互相印证）：
· ToolResult.Success 硬编码 true（task.go 唯一赋值点）⇒ 该字段在结构上
不可能为 false，是**谎报字段**；
· 工具失败以 nil error + 错误**值**返回（files 的 errorResult、
pluginmgr 的 {"error":…}），上游无从判别；
· stepToolAfter 用 `Result.(string)` 断言，而插件返回的多是 map ⇒
断言几乎恒失败，after_toolcall 阶段对结构化结果的改写**静默失效**。
改动：
· third_party/homeagent-sdk: 新增 ToolError{Field,Reason,Detail,Hint}
与 Error()。纯新增、无签名变更，存量插件不必改动（零值语义：
内核的失败识别同时兼容既有三种约定，新类型是可选项而非迁移要求）。
· internal/sdk: 补 ToolError 别名。
· core/toolerror.go: isToolError / toolErrorText / renderToolResult。
⚠️ 判据必须同时兼容仓内**三种**既有失败约定，且**不得**把成功误判：
① {"error": msg} ② {"isError":true,content:…} ③ *ToolError
明确不判失败的：exit_code != 0（业务结果，带真实 stdout/stderr）、
stderr 非空（cmd 成功常带 warn）、字符串/数字/bool/数组/nil
（自由文本按成功处理：宁可少报失败，也不把正常结果报成失败）。
· core/toolcall.go: executeToolCallOutcome 返回 toolOutcome{Text,Raw}，
**Raw 必须在成功分支也带上**——否则结构化失败在 fmt.Sprintf("%v")
那一步被抹平，Success 又退回恒真。panic 与 60s 超时统一以 ToolError
表达（可执行 Hint，避免模型原样重试工具故障）。
· core/task.go: Success=!isToolError(Raw)；修恒失败的类型断言；
TaskFrame 增 CurRaw（未降级的原值）。
判据：
· toolerror_test.go 单元级：三种失败约定识别 / 成功形态不误判 /
非零退出不算工具失败 / ToolError 识别。
· TestStageCtxSuccessIsHonestEndToEnd 端到端读 f.StageCtx.ToolResults，
验证**内核产出的值本身**，而非辅助函数。
变异验证（两轮）：
· Success 退回硬编码 true ⇒ 端到端判据 3 个子用例 FAIL；
· 把字符串判据改成 strings.Contains(x,"error") ⇒ 「成功文本含 error 字样」
用例 FAIL。**第二轮暴露了判据缺口**（最初没有该用例），已补。
过程中三次自伤（均由判据/编译暴露）：用正则批量包装 return 时把
多行 fmt.Sprintf 截断；包装范围溢出到返回 string 的辅助函数；
测试里重复注册同名工具导致 IOManager 取到错误的 device。
遗留：全量 go test ./internal/... 在本机无法完整跑完——/tmp 是 9.8G
tmpfs 且已 98% 占用，link 阶段报 "no space left on device"；
/var/tmp 另有约 29G 陈旧 release worktree。与本次改动无关（未触碰
memory/* 等失败包），已在干净基线（7a566d5）对比确认。
|
2026-09-27 09:17:16 +08:00 |
|
|
|
4ba72977d2
|
test(toolcall): 补批内路径的三条缺失判据（阶段 0.5）
同一批多个 tool_call 的循环（StepToolBegin→Exec→After）此前只被
scheduler_critical_test.go:125 一条用例覆盖「按序执行」，缺的三条正是
阶段 2（并行执行层）要改的地方：
· tool_call_id 配对完整性 —— 阶段 2 改消息落法（一个 assistant 带全部
tool_calls + N 条 tool）时，配对断裂上游会直接报错
· ContentOnce 批内语义 —— 同一段 assistant 文本在批内重复 N 次，撑爆上下文
· denied 后继续批内 —— 改成 abort 会丢掉本可执行的后续调用
判据 toolbatch_test.go（4 条），全部确定性断言：阶段 0 已消除 map
迭代随机性，同批工具的落序与配对可稳定断言。
变异验证：令 stepToolBegin 跳过批内最后一个工具后，4 条判据同时 FAIL
（既有那条也 FAIL），报错直指 ToolsUsed=[tool_alpha]、
tool_call_id "c2" 被声明 0 次。
更正一处此前的不准确表述：我曾说「无任何测试直接驱动批内路径」——
不准确。scheduler_critical_test.go:125 已驱动「同批两工具按序执行」；
漏查是因为只 grep 了 PendingTools/ToolIdx 字段名，没查断言内容。
真正缺的是上表三条。
过程中三次自伤（均由「判据先写」暴露）：臆造不存在的 helper；
stageHost 置 nil 后又使用；给 newTaskFrame 传 nil 导致 stepPrepare 于
task.go:519 nil 解引用 panic（改用仓内既有 a.stageCtxFromInput）。
顺带记录：生产两处 newTaskFrame 调用都传真实 ctx，但 stepPrepare 对
f.StageCtx 无 nil 兜底——本次不修（无生产触发路径），记为潜在缺口。
回归：internal/agent/... 与 internal/plugins/... 全绿。
|
2026-09-27 08:59:30 +08:00 |
|
|
|
7a566d50b7
|
fix(toolcall): 工具「不存在」类型化 + 修父 io 兜底吞错误 + 修并行 tool_call 落序随机
主线：工具调用并行化改造（阶段 0 与 0.2）。
① flush 顺序随机（process.go）
flushToolCall 由 `for idx := range accs` 驱动，Go map 迭代顺序随机化
⇒ 同一批并行 tool_call 进入 resp.ToolCalls 的顺序每次运行都可能不同。
对 output_send__ 这类用户可见通道，分段消息到达顺序不可复现。
改为收集 index 后 sort.Ints 再 flush（两个调用点统一走 flushAll）。
判据 stream_flush_order_test.go（8 工具 × 200 轮），已变异验证可检测。
② 工具「不存在」类型化（io/channel.go、core/stages.go、core/toolcall.go）
工具是动态注册的，「不存在」是运行期常态而非异常。原先内核用
strings.Contains(err, "not found in any plugin") 判别——约定而非契约，
插件文案含该子串即被误判。改用哨兵 ErrToolNotFound + errors.Is
（沿用仓内 ErrInputChannelUnknown 的先例）。
⚠️ 顺带修一个静默 bug：IOManager 向父兜底时吞掉父的执行失败，
误报为「工具不存在」。后果是设备离线这类本该 retry 的失败被判为
「工具没了」⇒ 整组被跳过，与「插件真没加载」无法区分。改为只传递
「确实不存在」，其余如实上抛。
「不存在」的文案改为可执行指引（get_plugin_tools / output_list_channels），
而非含糊的「执行失败」——后者会让模型反复重试同一个不存在的名字。
判据：toolcall_error_test.go（类型化 vs 诱饵子串、%w 穿透、执行期文案）、
channel_error_test.go（父失败不吞、真的不存在仍可判别）。
两者均经变异验证。回归：internal/agent/... 与 internal/plugins/... 全绿（14 包）。
设计文档：docs/zh/toolcall-contract-and-sequence-design.md
执行计划：docs/zh/toolcall-parallel-execution-plan.md
|
2026-09-27 08:55:25 +08:00 |
|
|
|
85e3d66e92
|
Merge branch 'feature/scene-writeback' — 场景式记忆修复 + WebUI 性能与星图改进
## 记忆：场景式记忆的 5 处根因（生产实测驱动）
现网 65 个场景里有 6 组是同一场面的双胞胎键，最严重的
auto:chan:qq+part:morning 累积到 strength=271 / 6 features / 0 refs，
日志里被「命中」179 次；孪生的 auto:chan:qq_part:morning 持有 210 refs
却有 0 features（聚类只读 scene_features，所以它永不被看见）。两套特征
体系各活各的，谁也发现不了谁。
- 1fa9ef6 键归一化 + 排除最弱维度：建键路径（createSceneLocked）漏过
NormalizeSceneKey，而 EnsureScene / effectiveScenes / RecallByScene
三处都过了 ⇒ '+' 与 '_' 成为两个合法主键，key UNIQUE 拦不住。
同时把权重仅 0.2 的 part（时段）排除出场景身份 —— 实测「morning 场景
吞掉 evening 指纹」（共享 chan:qq，相似度 1.0/1.4=0.714 > 阈值 0.5）。
冲突后缀 '#N' 改 '.N'（'#' 也会被归一化，是第四处双胞胎来源）。
- 758ec11 图整备覆盖 scenes：新增 DedupeScenes 并接入 mergeLoop。
原先 detectEntityMerge 的遍历入口 Recall(nil,nil,1,"") 只查
entities/relations，scenes 完全没有整备路径 —— 这是「双胞胎从 9-15 起
无人发现」的原因。生产库副本实测：65 → 57，合并 8 组，refs/rel/ent
一条没丢。
- 758ec11 证据桶按桶清：createSceneLocked 原先是
DELETE FROM situation_evidence（全表清）。多通道共用计数表，qq 的场景
一长出来就把 mc/webui 尚未攒够 minSceneEvidence=2 的证据抹掉 ⇒ 判据
实测「6 个通道各来 3 次只长出 2 个场景」。
- 2567a22 场景键两路合并去重：现网日志实测 scenes=[chan:qq chan:qq]。
声明路与通道派生路之间缺共同的 seen。
## SDK：补 ScenePolicy 声明项（经用户授权的公开接口扩展）
ChannelDef 已有 NoMemory/ContextPolicy/RecallPolicy 三件套，唯独没有
「这条输入算不算一场戏的一部分」，现状是无条件参与 ⇒ chan:system /
chan:kernel / chan:timer 这类纯内部信噪通道也在撑场面。
新增 ScenePolicyAuto/None + ValidScenePolicy，形状与既有两项完全一致；
ChannelDef.ScenePolicy 与 InjectOptions.ScenePolicy 均带 omitempty，
零值行为逐字节不变。默认取 auto（参与）而非 none：场景只附加检索路、
不改记忆本体，默认关会让存量通道突然失去召回。**现网不标任何一个通道**
（用户裁定「多写无影响、少写会缺场景」；实测 0-refs 通道召回返回空，
且 declared 场景不进相似度空间）。
⚠️ 本次合并会使 git_release_check 的「公开 SDK 接口冻结」项报 FAIL，
属预期：有意的新增接口，非破坏性变更。
## WebUI
- ae87f4b 服务端 gzip（首屏 wire 字节 -70%）：状态机写成单一枚举而非
多个 bool；SSE 不压、必须透传 http.Flusher、Content-Length 需防陈旧值。
- d3315c6 前端按页签懒加载：空闲请求 37 → 17（-54%）；顺带治掉三个
轮询器，并把 loadChatStarmapData 的空图分支硬取
getElementById("sm-container-chat") 改为可移植（该 bug 曾导致首页
首帧必抛、永不重试、星图永远空白）。
- 9346fed 星图跟随 agent 活动 + 搬到主页 + 修分类配色从未生效
（服务端发 "Concept"、JS 键是 "concept" ⇒ 永不匹配 ⇒ 1150 节点
全回退兜底灰）。
- 9c93f23 配色改中性灰蓝：上一提交修好后，1148/1149 个 Concept 节点
第一次真拿到亮青绿 ⇒ 整张图变绿。绿色不是渲染 bug，是「配色终于生效」
后暴露出的真实数据形状；之前的灰恰好是「全都没匹配上」的症状。
- 4a231a8 两处表达式合并为单行（纯格式化）。
## 文档
- f441574/6e94209/13a070f 场景记忆修复 plan（5 根因 → 7 步骤）
- bf5d891 介绍站补「场面涌现」板块
- SDK 站新增 docs/guide/scene-memory.md（概念 + 声明项用法）
## 验证
记忆 8 包 + agent/core 全绿；全仓 59 包 0 FAIL。生产部署后置清单全绿
（版本自报、插件子进程 25、Fatal 0、端到端）。场景清理后复验：涌现出的
新键不含 +/#、有 features 且有 refs。
|
2026-09-27 08:25:30 +08:00 |
|
|
|
9c93f232e3
|
fix(webui): 星图配色改中性灰蓝 + 图例按实际类型动态生成
### 为什么会出现「一片绿」
上一提交修好了「分类配色从未生效」那个 bug（服务端发 "Concept"、JS 键是
"concept" ⇒ 永不匹配 ⇒ 1150 个节点全回退兜底灰 0xcccccc）。修好之后
颜色值**一个字没改**（concept 键仍是 0x44ff88），于是 1148 个 Concept
节点第一次真的拿到了那个亮青绿 —— 1149 个节点里 1148 个是 Concept，
所以整张图变成绿的。
⇒ 结论：绿色不是渲染 bug，是「配色终于生效」后暴露出的真实数据形状。
之前的灰色恰好是「全都没匹配上」的症状。
### 换中性色（用户裁定）
默认色改为 SM_COLOR_DIM = 0x7d8a9e（中性灰蓝）。亮青绿配 1149 个
自发光球确实扎眼。
### 顺带把「图例说谎」也修了
原图例写死「人物/概念/对象/地点/来源」五项，而实测图谱里只有
Concept（1148）与 Source（1）—— 列出四个永不出现的类型，等于告诉
用户存在实际不存在的分类。
现在：
- 图例按**实际出现**的类型动态生成，标注占比
- 占比 <1% 的不单列（实测 1/1149 = 0.087%，单列会显示成「来源 0%」，
既难看又误导读者以为图里没有来源节点），归入「其他 N 个」
- 只有**一种有存在感**的类型时，附一句实话说明「节点同色不是分类图」
### 颜色规则也跟图例对齐
smColorFor：只有存在 >=1% 的第二类型时才按类型上色，否则全图中性色。
理由：99.9% 概念 + 0.1% 其他时按类型上色，得到的仍是一整片同色，
而那一两个异色点在视觉上就是噪点（实测 colors 只剩 ["7d8a9e"]）。
不动服务端类型识别（用户裁定）：nlp/extractor.go 至今不判类型、
graph.go:451 写死 Concept，根治要改记忆链路，本轮不碰。
### 途中修掉一个自己引入的 bug
图例空。首屏星图在**总览页**初始化，那时 #sm-legend 还不存在
（骨架由 renderStarmapTab 建），smLegend 内部 getElementById 返回 null
直接返回；而 renderStarmapTab 建完骨架后只调了 smUpdateStat()。
⇒ 浏览器实测图例 html 长度 0。在 renderStarmapTab 里补一次 smLegend()。
### 验证（真实 1149 节点数据集 + WebGL）
- 颜色：["7d8a9e"]（单一中性色）—— 改前 ["44ff88"] 一片绿
- 图例文本：「概念 100% 其他 1 个（图谱实体几乎都是同一类型，节点同色；
出现新类型后会自动分类）」
- 统计：1149 节点 / 865 关系；控制台零异常
- go vet 干净；全量测试通过
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
2026-09-27 07:14:34 +08:00 |
|
|
|
4a231a8d4c
|
style(webui): dashboard.js 两处表达式合并为单行
纯格式化，无语义变化：
- state.startedAt 的三元表达式（563 行附近）
- renderAll 里 Promise.all 的实参（624 行附近）
两处的表达式与参数列表逐字符相同，只是原先的换行被收拢。
已随二进制部署并验证上线：现网 `/` 返回的 HTML 里单行写法命中 1 处、
旧多行写法 0 残留。
|
2026-09-27 06:44:49 +08:00 |
|
|
|
d3315c68ca
|
perf(webui): 前端按页签懒加载 —— 首屏不再拉隐藏页签的数据，空闲请求砍到 1/3
生产实测的问题：renderAll 无论当前在哪个页签，都无条件拉 9 个接口并
渲染全部 7 个页签。首屏 792,933 B 里**约 230KB 花在用户看不见的隐藏
DOM 上** —— /api/v1/kernel（152KB，只有内核页要）与 /api/v1/settings
（72KB，只有设置页要），而 renderKernel() / renderOneSettings() 是在
**隐藏的 tab 容器**里构建 DOM 的。更糟的是每 15s 重来一遍。
### 依赖关系是实测出来的，不是猜的
逐个 render 函数 grep 它读的 state.*：
renderOverview → 无（只读 status/runtime/dom）★ 总览最便宜
renderKernel → state.kernel
renderOneSettings → state.settings / state.meta
renderPlugins → state.kernel / installedPlugins / disabledPlugins
renderAdapters → 无（自拉 /api/v1/adapters）
renderChat → 自建布局；星图/终端/命令是其子面板
于是「切到哪页才拉哪页的数据」写成一张 TABS 表（唯一真相表），
正确性由结构保证，而不是靠一串 if 串联。
### 顺带治掉三个轮询器（浏览器 40s 空载实测）
改前停在总览页 40s 内 37 个请求：
/runtime 17 次、/terminals 8 次、/cmd/history 8 次、/status 3 次
1. **terminals/cmd/history 的 5s 轮询是无条件的** —— 但这两个面板只
存在于**聊天页**（buildChatLayout 里的 chat-panel-terminal/-cmd），
在总览/设置/内核页渲染它们既没人看也只改看不见的 DOM。
改为「仅聊天页可见时才轮询」。
2. **/runtime 有两个消费者各拉一遍**：startRuntimeTicker（3s）与
starmapPullActivity（3s）。星图现在只读 state.runtime，不再自己发请求。
3. 轮询改走共享数据块 starmapFetchBlock（带 3s 节流 + 单一数据源）。
改后 40s 内 17 个请求（-54%），且不再有任何接口用于渲染不可见的面板。
### 首屏
overview 首屏只拉 status/runtime/chat/history/persona/memory-graph，
**不再拉 kernel 与 settings**。
### 刷新语义
区分「活数据」与「近乎不变的数据」：status/runtime 每 3s 允许重拉；
kernel/settings/plugins 首次拉过后**不再每 15s 重拉**（这正是 53MB/h
的主因）。切回页签也不重拉（数据没理由变）。四个变更操作
（源/MCP 的增删）改调 renderAll(true) 强制刷新；启停插件/保存设置那几处
本来就自己 refetch 再局部重渲染，不依赖 renderAll。
### ★ 途中修掉一个被上一提交引入的真 bug
loadChatStarmapData 的空图分支硬写 getElementById("sm-container-chat")。
星图搬到总览后，总览页与独立页签都没有这个 id ⇒ 首页首帧必抛
「Cannot set properties of null」，被 catch 吞掉但 starmapInit 没置上，
于是**永不重试、星图永远空白**。改为取 starmapActiveContainer() 并加
空值保护。浏览器实测：修前 ERRORS 非空，修后 STARTUP + 7 个页签全 clean。
（教训：把 UI 元素挪到新位置后，必须把所有按 id 直取该元素的地方找全 ——
grep 该 id 一次。）
同时删掉被 starmapActiveContainer 取代的死函数 starmapContainer()。
### 验证（浏览器实测，非估算）
- go vet 干净；全量测试通过
- 首屏（overview）：只拉 status/runtime/chat-history/persona/memory-graph，
kernel 与 settings 确认**未出现**
- 逐页切换记录请求：每页只拉自己那几项
- 空载 40s：37 → 17 个请求
- 运行态面板仍正常渲染（rt-panel 存在、rt-sec-pipe / rt-sec-topo 均在）
- 启动 + 7 个页签全部无控制台异常
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
2026-09-27 00:23:04 +08:00 |
|
|
|
ae87f4b8b2
|
perf(webui): 服务端 gzip —— 首屏 wire 字节 -70%
生产实测：首屏 API 合计 792,933 B，而服务端此前**完全没有** Content-Encoding
（直连 127.0.0.1:8080 与经 nginx 的公网入口两条路径都验过：响应头里没有
该字段，wire 尺寸 == 原始尺寸）。同一份数据 gzip 后：
/api/v1/kernel 152,667 → 37,697 (-75%)
/api/v1/chat/history?limit=40 554,764 → 174,594 (-69%)
这些是高度重复的 JSON（同批 key 名反复出现、中文实体名、时间戳），
压缩比自然地高。真实实例上实测首屏 wire 字节 77,943 → 23,339（-70%）。
位置：链改为 proxyDispatch → gzip → logged → mux。夹在 proxyDispatch
与 logged 之间，是因为 proxyDispatch 命中时直接 return、响应来自上游
（其 Content-Encoding 由 httputil 处理），我们不插手；门户自身的全部
响应（requireAPI 的 401/503、requireWeb 的 302、HTML/CSS/JS、全部
JSON API）都压。
### 三个必须显式处理的坑
1. **SSE 不能压。** text/event-stream 进 gzip 缓冲后 flush 语义就废了
（前端收不到流式，要等缓冲攒够）。对 SSE 请求直接透传。
2. **必须透传 http.Flusher。** handleChatEvents / streamOpenAI 里是
`w.(http.Flusher)` 类型断言；包装 ResponseWriter 会让断言失败 ⇒
flusher 为 nil ⇒ 走降级分支 ⇒ SSE **静默**坏掉（不报错，只是收不到
流式）。这不是「顺手加一下」能过的改动，有专门的判据守着。
3. **204/304/HEAD 没有 body**，压它们只浪费 CPU 并加坏头。
另外 webp/png/zip/gzip 等已压缩类型也跳过（mascot.webp 133KB 就在内）。
### 小于 1KB 的响应不压
gzip 头 23 字节，几百字节的 JSON 压完反而更大。与 nginx 的
gzip_min_length 1000 对齐。实测 /api/v1/status（197B）不带
Content-Encoding。
### 状态机写成枚举而非多个 bool
第一版用 passthrough/decided/buffering/allowBuf 四个 bool 交叉表示，
结果出两个 bug：小响应内容被写成空、已压缩类型仍被压。根因是
「该不该压」在 Write / WriteHeader / 收尾三处各判一次且判据不一致。
改成单一 mode 枚举（undecided/passThrough/buffering/streaming）、
判据只在 WriteHeader 与 Write 各求值一次后，两个 bug 同时消失。
### ★ 一条判据我自己写错了，值得记下来
TestGzipDropsContentLength 初版断言「压缩响应不应带 Content-Length」，
实测失败。追查后证明**判据错了、代码是对的**：
Go 在 Del("Content-Length") 之后，若响应体小到能被一次性缓冲（<2048B），
net/http 会**自动重算**并补上压缩后的真实长度（实测 14000B → 119B →
响应头 Content-Length: 119，正确）。真正要防的是**陈旧长度**：留着
14000 而实发 119 时，客户端按 Content-Length 读满会先拿到 119 字节再吃
unexpected EOF（已用对照探针实测复现）。判据改成两条：①声明长度 ==
实际读到字节数 ②该值 == 压缩后长度而非压缩前长度。另加一条对照判据
TestGzipStaleContentLengthWouldBreak，把危害钉成可执行断言。
### 验证（不是「应该能跑」）
- go vet 干净；全量测试通过；新增 12 条 gzip 判据；覆盖率 66.5% → 67.0%
- 真实实例（独立数据目录 + 18081 端口）实测：
· SSE：无 Content-Encoding，2 次独立 TCP 读（逐帧下发，未被缓冲）
· /api/v1/status（197B）：不带 Content-Encoding
· /api/v1/kernel -69%、/api/v1/settings -73%、/api/v1/plugins -63%
· 首屏 wire 字节 77,943 → 23,339（-70%）
· 内容完整性：gzip 解压后与明文逐字段相等（plugins/tools/build/
channels 名称集合与顺序均一致）
- ★ 途中被一个「MISMATCH」误导过一轮：/api/v1/kernel 两次请求字节不同。
追查发现是 IOManager.ListChannels 遍历 **map**（Go 每次迭代随机化），
**在本次改动之前就已不确定**，与 gzip 无关。差点被我误报成压缩 bug。
附：dashboard.js 被自动格式化器整体重排（6783 增 / 6293 删，纯空白与
引号风格）。已用 prettier 归一化后逐字节比对确认**零语义差异**。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
2026-09-27 00:02:28 +08:00 |
|
|
|
9346fed0d9
|
feat(webui): 星图跟随 agent 活动 + 搬到主页 + 修分类配色从未生效
星图此前只是静态展示：starmapAnimate() 只转星空，节点完全静止，
与 agent 的动作零关联。本轮三件事。
★ 修一个从未被发现的 bug：分类配色一直是坏的
服务端 type 是首字母大写（"Concept"，见 internal/memory/graph.go），
而 smTypeColors 的键全是小写 ⇒ 永远匹配不上 ⇒ 1151 个节点全渲染成
同一个灰色 0xcccccc。浏览器实测确认：改前 colors=["cccccc"]，
改后 ["44ff88"]（概念绿）。
一、跟随 agent 动（三路信号，全部在渲染循环里推进，不另起定时器）
1. tool_call / stage / agent_output 的 SSE 事件 → 命中节点发光冲高
+ 尺寸微扩。工具名按**词**匹配实体（knowledge_list → knowledge_*）。
2. /runtime 调度器（3s）→ 排队/中断/挂起时全图绷紧；中断或抢占计数
上升时来一记强脉冲。
3. /memory/graph/pulse（10s，新端点）→ 新记忆「生长」：从 0 弹到
正常大小并留余晖。
另：距上次活动越近，全图越亮（抽样呼吸）—— agent 一忙图就活。
二、搬到主页 + 独立页签
总览页内嵌 360px 星图；顶部导航加「星图」独立页签（全高 + 图例）。
同一套 renderer 用 appendChild 在容器间搬运 canvas（three.js 的
canvas 只能有一个父节点，同时渲染会一边黑屏）。
三、性能：保留全部 1151 节点，但全部降规格
改前每节点 = 独立 SphereGeometry(16,12) + 独立光晕球 + 一张 256x64
CanvasTexture ⇒ 2302 个独立 geometry、约 88 万三角形、1151 个
<canvas>，仅文字贴图就吃约 72MB 显存。全景远看根本读不清那些标签。
改后：共享 SphereGeometry(8,6)（约 84 三角形/节点）；标签改为 hover
时在容器角上显示 HTML 文本（零显存，且比 3D 贴图更清晰）；
866 条边按关系类型合并成 4 个 LineSegments（draw call 866 → 4）。
hover 复位随之改为 baseScale —— 旧的 set(1,1,1) 会把按 mention_count
缩放过的大节点缩成最小尺寸。
四、/memory/graph 瘦身：不再下发稠密向量
星图是本接口唯一消费者，却从不读 vector。生产实测该字段占
79,314 / 402,811 字节 = 19%，而 8 块记忆就这么多，200 块就是 ~2MB
白查白发白堆。真实数据集实测响应 402,811 → 326,997 字节（-18%）。
新增 /memory/graph/pulse：只回 since 窗口内变动过的实体（id/name/type/
mention_count/updated_at）。星图每 10s 拉它来判断「哪个节点新长出来」，
而不必重拉 400KB 全量。
验证（不是「应该能跑」）：
- go vet 干净；go test 全绿；新增 5 个测试（向量裁剪 / pulse 窗口 /
since 放大 / pulse 不带向量 / 类型断言失败时透传不丢数据）
- 覆盖率 65.5% → 66.5%
- 真实 1151 节点数据集上跑 headless chromium + SwiftShader 实测：
nodeMeshes=1151、edgeSegs=4、geoShared=true、控制台零报错、
图例与统计（1151 节点 / 866 关系）正常、canvas 在两个容器间正确搬运
- 脉冲匹配在浏览器里逐个 hint 验证：
knowledge_list → 2 个（只命中 knowledge_base / knowledge_list）
qq_get_message 等无匹配 → 8 个（走「整体活动」兜底）
★ 途中修掉自己的两个错：① 最早的子串匹配让 hint="knowledge" 命中
全部单字实体（一次 pulse 选中 250 个、队列顶到 260 上限）；
② 改成词匹配后，旧的「补齐到 20 个」逻辑又把 1 个真实命中补成 20 个
无关节点 —— 现象与①一样，只是成因不同。补齐现在只在**完全无匹配**
时启用。
未做（本轮范围外）：服务端 gzip（首屏 793KB 无压缩，实测可压到 ~240KB）、
renderAll 按页签懒加载（首屏仍在拉隐藏页签的 kernel+settings 共 230KB）、
setInterval 15s 全量重拉（空闲 53MB/h）。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
2026-09-26 23:31:58 +08:00 |
|
|
|
bf5d8915dd
|
docs(site): 介绍站补「场面涌现」板块
三层记忆那张图只讲了字面相关性召回，缺了按场合召回的那一半。
新增一段说明：场面指纹（通道/对象/工具/话题/时段）如何自己长成场面、
为什么只发生一次的不算场面、以及 ScenePolicy 声明项（默认参与）。
沿用现有 card/grid-3/reveal class，视觉与既有三张卡一致；
div 与 p 配平关系与改动前完全一致（142/142、差值 40 未变）。
|
2026-09-26 23:14:17 +08:00 |
|
