feat(shm): 文档/知识正文入共享内存 + 协议版本 bump 到 2(§13.13)

## 数据面补齐

- doc.insert / doc.insertWithMedia:新增 doc_ref / attachments_ref,
  模板序列化后 putValueInArena
- knowledge.add:新增 content_ref(内容是 JSON 字符串,读出后再解一层)
- 抽出通用 resolveJSONRef(resolveBlocks 也改用它),三处共用一套
  “共享优先、内联回退”逻辑

## 协议版本 bump:让错配显式失败,而不是静默坏

这是本轮更重要的部分。§13.6/§13.13 改了内核→插件 payload 的承载方式,
两种错配都不会报错、只会静默失效:

- v1 插件只读内联 args(tool/cleaner/output)→ 遇到 v2 内核拿到空参数
- v2 插件发 blocks_ref → v1 内核反序列化时静默忽略(旧内核
  io.setToolBlocks 还是桩实现)

现场表现为“输出变空 / 图注入没反应”,极难定位。所以把 ProtocolVersion
与模板 procProtocolVersion 一起 bump 到 2:双方都是等值校验,v1 插件遇上
v2 内核会在建链时明确报“协议版本不匹配…请用配套 plugindev 重编”。

测试里把“错误必须带出重编指令”也断言上了——生产上碰到它的现场就是
“只更新了内核没重编插件”,光报“不匹配”定位不到行动。

testdata 8 个插件的 protocol 同步更新(badprotoplugin 仍用 999 验证拒绝)。
工具链已重建并安装(协议 2,内嵌 blocks_ref/doc_ref/content_ref),
回滚副本 plugindev.bak-20260910-232544。

验证:-race 全绿。新增 KnowledgeAddViaArena(12000B 正文)、
KnowledgeAddInline、DocInsertViaArena、SetToolBlocks 三例 +
真实模板 e2e + 协议不匹配断言强化。

§13.13 第 5 条(反向大结果)范围更大——需把内核→插件的应答路径整体改成
“大结果写段 + 返回 ref”,涉及 callCore 的返回处理与 doc.query/llm.chat 等
所有读大结果的 method。已在 plan.md 标注未做,不冒充完成。
This commit is contained in:
JianFeeeee
2026-09-10 23:26:16 +08:00
parent 15d912ef34
commit 50ba4a64cb
13 changed files with 252 additions and 37 deletions

View File

@ -316,6 +316,10 @@ func TestProcess_ConcurrentCallsRouteCorrectly(t *testing.T) {
}
// 协议版本不匹配必须显式拒绝,不能半兼容运行。
//
// v2 引入的必要性就靠这条v1 插件(只读内联 args遇上 v2 内核,跟 v2 插件
// 发 blocks_ref 给 v1 内核,都会静默失效、不报任何错。只有在这里显式拦下,
// 那双错配才会变成一条带修复指令的启动失败。
func TestProcess_ProtocolMismatchRejected(t *testing.T) {
bin := buildTestPlugin(t, "badprotoplugin.go")
_, err := Spawn("badproto", bin, Options{Handler: noopHandler})
@ -325,6 +329,11 @@ func TestProcess_ProtocolMismatchRejected(t *testing.T) {
if !strings.Contains(err.Error(), "协议版本不匹配") {
t.Errorf("错误应说明版本不匹配,实际: %v", err)
}
// 运维可读性:光报“不匹配”不能定位到行动。生产上碰到它的现场是
// “只更新了内核没重编插件”,所以错误里必须带出这条修复指令。
if !strings.Contains(err.Error(), "plugindev") || !strings.Contains(err.Error(), "重编") {
t.Errorf("错误应给出重编插件的修复指令,实际: %v", err)
}
}
func TestProcess_SpawnRequiresHandler(t *testing.T) {