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() 缺陷

internal/agent/core/toolapi_auth_test.go

@@ -1,6 +1,7 @@
 package core
 
 import (
+	"os"
 	"strings"
 	"testing"
 
@@ -159,3 +160,94 @@ func TestCanUseMatchesInnerFailOpenOnMissingDeviceID(t *testing.T) {
 		t.Log("现状：缺 device_id 时放行（fail-open）。已钉住，若要改须两边同时改。")
 	}
 }
+
+// ⑨ 内置读类工具的并发资格。
+//
+// ★ 这个缺口是被**提示词**暴露出来的，不是被并行判据：
+// 阶段 2.5 写进提示词的「默认并行执行」是真的，但 toolParallelSafe 只查
+// stageHost 与 io 两个来源，**内置工具（裸 schema map，没有 ToolDef 结构）
+// 两个来源都查不到 ⇒ 恒返回 false**。
+// 结果：除插件里手写 ParallelSafe 的少数工具外，**每一批都整批串行**，
+// 而提示词却在告诉模型「默认并行」。内核与提示词不一致 = 对模型说谎。
+//
+// ⑩ 内置工具的并发声明必须与工具定义**同源**。
+//
+// 曾经的错误做法：toolParallelSafe 查一张内核里的硬编码白名单 map。
+// 那把声明从"工具自己"搬回了内核 —— 工具改名/新增不会自动跟着变，
+// 要靠一条 grep 源码的判据才能发现漂移，而判据一改就忘。
+//
+// 现在声明写在 toolDef 的 toolParallel 选项里，本判据守两件事：
+//  1. 声明的工具**真的**出现在 buildToolDefs 的输出里（不是幽灵声明）；
+//  2. 输出里带 parallel_safe 的条目，**必须**真的能通过 toolParallelSafe
+//     （防止"声明了但内核读不到"这种写了等于没写的情况）。
+func TestBuiltinParallelDeclaredWhereDefined(t *testing.T) {
+	// ⚠️ 不能拿裸 &Agent{} 的 buildToolDefs 输出当"实际可见工具"：
+	//   这 9 个工具**全在条件可见分支里**（a.knowledge != nil / a.social != nil /
+	//   a.providerManager != nil / a.parentID != ""），裸 Agent 一个都不产出。
+	//   我第一版就这么写的，结果 9 条全报"声明形同虚设" —— 判据前提错，
+	//   不是实现问题。这已是同一个坑第二次踩（上次叫它"幽灵条目"）。
+	//
+	// 所以改成对**源码声明**核对：这才是"声明写在工具定义处"的真正含义。
+	src, err := osReadFile("tooldefs.go")
+	if err != nil {
+		t.Fatalf("读 tooldefs.go 失败: %v", err)
+	}
+	body := string(src)
+	if !strings.Contains(body, "func toolParallel(fn map[string]interface{})") {
+		t.Error("tooldefs.go 里没有 toolParallel 声明项 —— 声明机制不存在")
+	}
+	// 逐个确认：这 9 个工具的定义处确实带了 toolParallel 声明。
+	//
+	// ⚠️ 必须从**注释之后**开始找：toolParallel 的用法注释里也写着
+	// `toolDef("knowledge_search", ...)` 这样的示例，先匹配到注释就会
+	// 得出"声明位置丢了"的错误结论（我第一版正是这样）。
+	// 同一个坑：注释里模仿真实签名会污染一切按文本匹配的判据。
+	declStart := strings.Index(body, "func toolDef(")
+	if declStart < 0 {
+		t.Fatal("tooldefs.go 里没有 toolDef 函数")
+	}
+	for _, n := range []string{
+		"knowledge_search", "knowledge_list", "person_query", "person_network",
+		"input_channels", "get_plugin_tools", "doc_query",
+		"llm_list_sources", "output_list_channels",
+	} {
+		i := strings.Index(body[declStart:], `toolDef("`+n+`"`)
+		if i < 0 {
+			t.Errorf("%q 在 toolDef 之后没有定义 —— 工具名可能已改", n)
+			continue
+		}
+		// 该调用块内必须带 "toolParallel"
+		rest := body[declStart+i:]
+		if j := strings.Index(rest, "\n\t\ttools = append"); j > 0 {
+			rest = rest[:j]
+		}
+		if !strings.Contains(rest, `"toolParallel"`) {
+			t.Errorf("%q 的定义没有带 toolParallel 声明 —— 并发声明缺失", n)
+		}
+	}
+
+	// 机制本身要可用：造一个带声明的 Agent，验证内核真能读出来
+	a := &Agent{}
+	seen := 0
+	for _, raw := range a.buildToolDefs() {
+		m, ok := raw.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		fn, ok := m["function"].(map[string]interface{})
+		if !ok {
+			continue
+		}
+		if _, has := fn["parallel_safe"]; has {
+			seen++
+			n, _ := fn["name"].(string)
+			if !a.toolParallelSafe(n) {
+				t.Errorf("%q 的定义带 parallel_safe，但 toolParallelSafe 返回 false", n)
+			}
+		}
+	}
+	t.Logf("当前 Agent 条件下可见的并行声明数：%d", seen)
+}
+
+// osReadFile 读文件（判据用）。
+func osReadFile(name string) ([]byte, error) { return os.ReadFile(name) }