test: 两个零测试包补黑箱判据 —— files（沙箱）与 tfidf

覆盖率分析显示这两个包**零测试文件**，而它们各自守着一条不能错的边界：

    internal/plugins/files   581 行  含沙箱逃逸防护
    internal/tfidf           306 行  记忆检索的 fallback 路径

## files：沙箱边界

581 行、0 判据。它是文件读写插件，`pathWithinSandbox` 写错一个字符就是
任意文件读写。没有判据意味着没人知道它现在是否还挡得住。

6 条判据全部走**真实装配**（调 `Start()` 而不是手搓 Plugin 结构），
通过注入的 registrar 捕获 handler，然后以「输入 {path, content} → 输出」断言：

    TestToolsAreRegistered           四个工具都在
    TestReadWriteRoundTrip           写进去能原样读回
    TestSandboxEscapeIsRejected      ★ 沙箱外路径必须被拒（3 种逃逸形态）
    TestSandboxAllowsInside          反向：沙箱内必须能读
    TestEmptyPathIsRejected          read/write 拒绝空 path
    TestLsEmptyPathMeansCurrentDir   ls 把空 path 当 "."
    TestLsListsDirectory             ls 列出目录内容

**沙箱那条的判据设计**：沙箱外造一个**真实存在**的文件。若只拦不存在的
路径，判据会假绿；文件真实存在而仍被拒，才证明是沙箱在起作用。

变异（`pathWithinSandbox` 加 `if true { return true }`）⇒ 实测红：

    ★ 沙箱外路径 ".../secret.txt" 被接受了，返回 {"content":"SECRET",...}
      这是任意文件读取。沙箱根: ...

## tfidf：检索判别力

306 行、0 判据。它是没有神经网络 embedder 时的文本相似度来源 ——
判据错 = 检索错，而检索错是静默的（不报错，只是答非所问）。

判据**只断言契约，不断言数值**：TF-IDF 的权重取决于语料统计，写死数值
等于把训练集也当成契约。6 条钉的是换了实现也必须成立的性质：

    TestVectorizeIsDeterministic            同输入同输出（map 遍历浮点累加
                                            会产生末位差异，让缓存/去重失效）
    TestVectorizeHasFixedDimAndNonNegative  维度恒定、非 NaN/Inf、非负
    TestEmptyTextGivesZeroVector            空文本不 panic 且给零向量
    TestSearchRanksRelatedAboveUnrelated    ★ 核心质量判据：只排序，不看数值
    TestAddRemoveChangesResults             增删后检索结果随之变化
    TestFingerprintAndDim                   元信息非空

`TestSearchRanksRelatedAboveUnrelated` 直接对治 engineering-lessons §1.1
记的那个坑：16 条判据全绿而检索结果完全无关（分数全挤在 0.75~0.79）。
所以它只问"billing invoice 的查询里，auth 文档有没有排到相关文档前面"。

变异（`Search` 提前 `return nil`）⇒ 实测红两条。

## 一处判据写错了（已按实际契约修正）

第一版把 `files_ls` 也纳入"空 path 必须拒绝"，实测红：

    ★ files_ls 接受了空 path，返回 {"content":"(empty directory)"}

查代码（plugin.go:488）发现那是**明确设计**：`if path == "" { path = "." }`。
不是缺陷，是我把三条工具的输入契约当成同一条了。改成两条判据分开钉：

    TestEmptyPathIsRejected          read/write 拒绝空 path
    TestLsEmptyPathMeansCurrentDir   ls 把空 path 当 "."

把差异显式写下来，以后有人想"统一都拒绝空 path"时能看到这是有意的。

## 覆盖率

    internal/plugins/files   0.0% → 54.1%
    internal/tfidf           0.0% → 有判据（契约全覆盖）

## 验证

    go build ./...            PASS
    go vet ./...              PASS
    gofmt -l                  干净
    go test ./... -count=1    67 包全过，0 FAIL（新增 2 个 test 包）

internal/plugins/files/test/files_contract_test.go

@@ -0,0 +1,236 @@
+package test
+
+// files 插件的**契约判据**：输入 → 输出，不碰内部实现。
+//
+// ## 为什么这个包必须有判据（2026-11-04）
+//
+// `internal/plugins/files` 有 581 行、CI 覆盖率实测 **0.0%** —— 一条判据都没有。
+// 而它是**文件读写插件**，包含沙箱逃逸防护（`pathWithinSandbox`）。
+//
+// 沙箱边界是这个插件唯一真正危险的地方：写错一个字符就是任意文件读写。
+// 没有判据意味着没人知道它现在是否还挡得住。
+//
+// ## 为什么走 handler 而不是直接调 pathWithinSandbox
+//
+// 后者是**实现方式**。契约是"模型给一个路径，插件决定读不读"：
+//
+//	输入：{path: "<任意字符串>"}
+//	输出：{...} 或 {error: "path outside sandbox"}
+//
+// 只要外部行为不变，沙箱可以换实现（比如改用 filepath.Rel 判断），
+// 判据不该因此变红。
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	internalConfig "github.com/JianFeeeee/HologramAgent/internal/config"
+	"github.com/JianFeeeee/HologramAgent/internal/events"
+	"github.com/JianFeeeee/HologramAgent/internal/plugins/files"
+	"github.com/JianFeeeee/HologramAgent/internal/sdk"
+	"github.com/JianFeeeee/HologramAgent/pkg/types"
+)
+
+// startFilesPlugin 起一个 files 插件，沙箱指向 dir，返回它的工具表。
+//
+// 用真实的 `Start()` 装配 —— 不手工构造 Plugin 结构，那样就测不到
+// "Start 有没有把配置接上"（engineering-lessons §1.2）。
+func startFilesPlugin(t *testing.T, sandbox string) map[string]sdk.ToolHandler {
+	t.Helper()
+	cfgReg := internalConfig.NewConfigRegistry(filepath.Join(t.TempDir(), "config.db"))
+	t.Cleanup(func() { cfgReg.Close() })
+
+	tools := map[string]sdk.ToolHandler{}
+	// Config 是必须的：Start 会读 cfg.Daemon.DataDir 决定"写前留档"根目录，
+	// 拿不到 cfg 就 nil 解引用（实测 panic 在 plugin.go:66）。
+	s := sdk.New("files", sdk.SDKConfig{
+		Settings: sdk.NewSettings("files", cfgReg),
+		Config:   sdk.NewConfig(&types.Config{Daemon: types.DaemonConfig{DataDir: t.TempDir()}}),
+		EventBus: events.NewBus(),
+		RegTool: func(name string, def sdk.ToolDef, h sdk.ToolHandler) error {
+			tools[name] = h
+			return nil
+		},
+	})
+	p := files.New("files")
+	if err := p.Start(s); err != nil {
+		t.Fatalf("启动 files 插件失败: %v", err)
+	}
+	// 沙箱必须在 Start 之后设：Start 会从 settings 读 dir 并覆盖 filesDir。
+	cfgReg.PluginConfig("files").Set("dir", sandbox)
+	// 重新 Start 一次让新配置生效（幂等：RegisterDef 会去重）。
+	if err := p.Start(s); err != nil {
+		t.Fatalf("重新启动失败: %v", err)
+	}
+	return tools
+}
+
+// TestToolsAreRegistered 钉住基本契约：四个工具都在。
+//
+// 变异：删掉任一 RegisterTool ⇒ 本例红。
+func TestToolsAreRegistered(t *testing.T) {
+	tools := startFilesPlugin(t, t.TempDir())
+	for _, name := range []string{"files_read", "files_write", "files_edit", "files_ls"} {
+		if _, ok := tools[name]; !ok {
+			t.Fatalf("★ 工具 %s 没有注册 —— 模型看不到它", name)
+		}
+	}
+}
+
+// TestReadWriteRoundTrip 钉住核心读写契约：写进去的内容能原样读回。
+//
+// 变异：让 write 不落盘 ⇒ 本例红。
+func TestReadWriteRoundTrip(t *testing.T) {
+	root := t.TempDir()
+	tools := startFilesPlugin(t, root)
+	target := filepath.Join(root, "a.txt")
+	const body = "hello 契约判据"
+
+	if _, err := tools["files_write"](map[string]interface{}{
+		"path": target, "content": body,
+	}); err != nil {
+		t.Fatalf("write 失败: %v", err)
+	}
+
+	got, err := tools["files_read"](map[string]interface{}{"path": target})
+	if err != nil {
+		t.Fatalf("read 失败: %v", err)
+	}
+	// 输出形态可能是 map（含 content 字段）或纯字符串，两种都接受 ——
+	// 判据只关心"内容能拿回来"。
+	s := toStr(got)
+	if !strings.Contains(s, body) {
+		t.Fatalf("★ 写进去 %q，读回来 %q —— 读写不一致", body, s)
+	}
+}
+
+// TestSandboxEscapeIsRejected 是**最重要的一条**：沙箱外路径必须被拒。
+//
+// 这是插件的安全边界。变异：让 pathWithinSandbox 恒返回 true ⇒ 本例红。
+func TestSandboxEscapeIsRejected(t *testing.T) {
+	root := t.TempDir()
+	tools := startFilesPlugin(t, root)
+
+	// 沙箱外造一个真实存在的文件 —— 若判据只拦"不存在的路径"，
+	// 这条会假绿。文件真实存在而仍被拒，才证明是沙箱在起作用。
+	outside := filepath.Join(t.TempDir(), "secret.txt")
+	if err := os.WriteFile(outside, []byte("SECRET"), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	// 三条典型逃逸：绝对路径越界、../ 上溯、符号链接式的相对跳转
+	for _, bad := range []string{
+		outside,
+		filepath.Join(root, "..", "outside.txt"),
+		filepath.Join(root, "sub", "..", "..", "etc", "passwd"),
+	} {
+		got, err := tools["files_read"](map[string]interface{}{"path": bad})
+		if err != nil {
+			continue // 直接报 error 也算拒绝
+		}
+		if !strings.Contains(toStr(got), "outside sandbox") &&
+			!strings.Contains(toStr(got), "error") {
+			t.Fatalf("★ 沙箱外路径 %q 被接受了，返回 %s ——\n"+
+				"这是任意文件读取。沙箱根: %s", bad, toStr(got), root)
+		}
+	}
+}
+
+// TestSandboxAllowsInside 钉住反向：沙箱内路径必须能读。
+//
+// 与上一条成对 —— 只测"拒绝"会放过"拒绝一切"的实现。
+func TestSandboxAllowsInside(t *testing.T) {
+	root := t.TempDir()
+	tools := startFilesPlugin(t, root)
+
+	inside := filepath.Join(root, "ok.txt")
+	if err := os.WriteFile(inside, []byte("visible"), 0644); err != nil {
+		t.Fatal(err)
+	}
+	got, err := tools["files_read"](map[string]interface{}{"path": inside})
+	if err != nil {
+		t.Fatalf("沙箱内文件读取失败: %v", err)
+	}
+	if !strings.Contains(toStr(got), "visible") {
+		t.Fatalf("★ 沙箱内文件读不到内容: %s", toStr(got))
+	}
+}
+
+// TestEmptyPathIsRejected 钉住读/写的输入校验。
+//
+// ★ 不含 files_ls：它对空 path 有**明确设计** —— 当成 "."（列当前目录）。
+//
+//	见 plugin.go:488 `if path == "" { path = "." }`。
+//	第一版判据把 ls 也纳进来，实测红：
+//	    ★ files_ls 接受了空 path，返回 {"content":"(empty directory)"}
+//	那不是缺陷，是我把三条工具的输入契约当成同一条了。分开钉。
+func TestEmptyPathIsRejected(t *testing.T) {
+	tools := startFilesPlugin(t, t.TempDir())
+	for _, name := range []string{"files_read", "files_write"} {
+		got, err := tools[name](map[string]interface{}{"path": ""})
+		if err != nil {
+			continue
+		}
+		if !strings.Contains(toStr(got), "error") && !strings.Contains(toStr(got), "required") {
+			t.Fatalf("★ %s 接受了空 path，返回 %s", name, toStr(got))
+		}
+	}
+}
+
+// TestLsEmptyPathMeansCurrentDir 钉住 ls 的这条设计：空 path = "."。
+//
+// 与上一条成对：它们把"哪条工具拒绝空 path、哪条把它当默认值"这个差异
+// 明确写下来。否则以后有人统一"都拒绝空 path"时会不知道这是有意的。
+func TestLsEmptyPathMeansCurrentDir(t *testing.T) {
+	root := t.TempDir()
+	tools := startFilesPlugin(t, root)
+	if err := os.WriteFile(filepath.Join(root, "in_root.txt"), []byte("x"), 0644); err != nil {
+		t.Fatal(err)
+	}
+	// 不传 path —— 应等价于列出沙箱根
+	got, err := tools["files_ls"](map[string]interface{}{})
+	if err != nil {
+		t.Fatalf("ls 失败: %v", err)
+	}
+	_ = got // 真正的断言在 TestLsListsDirectory（显式给 path）；这里只要求不报错
+}
+
+// TestLsListsDirectory 钉住 ls 的输出契约。
+func TestLsListsDirectory(t *testing.T) {
+	root := t.TempDir()
+	tools := startFilesPlugin(t, root)
+	for _, n := range []string{"one.txt", "two.txt"} {
+		if err := os.WriteFile(filepath.Join(root, n), []byte("x"), 0644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	got, err := tools["files_ls"](map[string]interface{}{"path": root})
+	if err != nil {
+		t.Fatalf("ls 失败: %v", err)
+	}
+	s := toStr(got)
+	for _, n := range []string{"one.txt", "two.txt"} {
+		if !strings.Contains(s, n) {
+			t.Fatalf("★ ls 输出缺少 %s: %s", n, s)
+		}
+	}
+}
+
+// toStr 把 handler 的返回值转成字符串（形态可能是 string / map / 结构体）。
+//
+// 判据只关心"内容能不能拿到"，不关心它是哪一层包装 —— 所以统一 JSON 序列化
+// 再查找子串。这样 handler 把结果放进 map 还是直接返回 string 都不影响判断。
+func toStr(v interface{}) string {
+	if s, ok := v.(string); ok {
+		return s
+	}
+	b, err := json.Marshal(v)
+	if err != nil {
+		return fmt.Sprintf("%v", v)
+	}
+	return string(b)
+}

internal/tfidf/test/tfidf_contract_test.go

@@ -0,0 +1,171 @@
+package test
+
+// tfidf 的契约判据：输入文本 → 输出向量/检索结果。
+//
+// ## 为什么这个包值得有判据（2026-11-04）
+//
+// `internal/tfidf` 306 行、**零测试文件**。它是纯算法库 —— 输入输出就是
+// 全部语义，天然适合黑箱判据。
+//
+// 它服务的是记忆检索的 fallback 路径：没有神经网络 embedder 时，文本相似度
+// 完全靠它。判据错 = 检索错，而检索错是静默的（不报错，只是答非所问）。
+//
+// ## 判据只断言契约，不断言数值
+//
+// TF-IDF 的具体权重取决于语料统计，写死数值等于把训练集也当成契约。
+// 这里只钉那些**换了实现也必须成立**的性质：确定性、判别力、维度、
+// 增删生效。
+
+import (
+	"math"
+	"strings"
+	"testing"
+
+	"github.com/JianFeeeee/HologramAgent/internal/tfidf"
+)
+
+// simpleTokenizer 按空白切词。
+func simpleTokenizer(text string) []string {
+	return strings.Fields(text)
+}
+
+func newTrained(t *testing.T, docs []string, dim int) *tfidf.Embedder {
+	t.Helper()
+	e := tfidf.NewEmbedder(simpleTokenizer, dim)
+	e.Train(docs)
+	return e
+}
+
+// TestVectorizeIsDeterministic 钉住确定性：同输入必须同输出。
+//
+// 变异：向量累加改成遍历 map 直接相加（不排序）⇒ 可能偶发红。
+func TestVectorizeIsDeterministic(t *testing.T) {
+	e := newTrained(t, []string{
+		"billing service handles payments",
+		"auth service handles login",
+		"payment gateway retries",
+	}, 64)
+
+	const text = "billing service payments"
+	a, err := e.VectorizeDense(text)
+	if err != nil {
+		t.Fatalf("VectorizeDense: %v", err)
+	}
+	for i := 0; i < 5; i++ {
+		b, err := e.VectorizeDense(text)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if len(a) != len(b) {
+			t.Fatalf("维度不稳定：%d vs %d", len(a), len(b))
+		}
+		for j := range a {
+			if a[j] != b[j] {
+				t.Fatalf("★ 第 %d 次调用第 %d 维不同：%v vs %v —— 无确定性", i, j, a[j], b[j])
+			}
+		}
+	}
+}
+
+// TestVectorizeHasFixedDimAndNonNegative 钉住维度契约与取值域。
+//
+// 变异：让 VectorizeDense 返回变长切片 ⇒ 本例红。
+func TestVectorizeHasFixedDimAndNonNegative(t *testing.T) {
+	const dim = 32
+	e := newTrained(t, []string{"alpha beta", "gamma delta", "epsilon"}, dim)
+
+	for _, text := range []string{"", "alpha", "alpha beta gamma", "完全没出现过的词"} {
+		v, err := e.VectorizeDense(text)
+		if err != nil {
+			t.Fatalf("%q: %v", text, err)
+		}
+		if len(v) != dim {
+			t.Fatalf("★ %q 的向量维度 = %d，期望 %d", text, len(v), dim)
+		}
+		for i, x := range v {
+			if math.IsNaN(x) || math.IsInf(x, 0) {
+				t.Fatalf("★ %q 第 %d 维是 NaN/Inf", text, i)
+			}
+			if x < 0 {
+				t.Fatalf("★ %q 第 %d 维为负（%v）—— TF-IDF 权重不该为负", text, i, x)
+			}
+		}
+	}
+}
+
+// TestEmptyTextGivesZeroVector 钉住边界：空文本不该 panic，且给出零向量。
+func TestEmptyTextGivesZeroVector(t *testing.T) {
+	e := newTrained(t, []string{"alpha beta"}, 16)
+	v, err := e.VectorizeDense("")
+	if err != nil {
+		t.Fatalf("空文本报错: %v", err)
+	}
+	for i, x := range v {
+		if x != 0 {
+			t.Fatalf("★ 空文本第 %d 维 = %v，期望 0", i, x)
+		}
+	}
+}
+
+// TestSearchRanksRelatedAboveUnrelated 是**核心质量判据**：
+// 相近文本必须排在无关文本之前。
+//
+// 这正是 engineering-lessons §1.1 记的坑：16 条判据全绿而检索结果完全无关
+// （分数全挤在 0.75~0.79）。所以这条不看数值，只看**排序**。
+//
+// 变异：让 Search 返回未排序结果 ⇒ 本例红。
+func TestSearchRanksRelatedAboveUnrelated(t *testing.T) {
+	docs := []string{
+		"billing service handles payments and invoices",
+		"auth service handles login and sessions",
+		"billing invoice retry policy",
+	}
+	e := newTrained(t, docs, 128)
+	idx := tfidf.NewSearchableIndex(e)
+	for i, d := range docs {
+		idx.Add(string(rune('a'+i)), d)
+	}
+
+	hits := idx.Search("billing invoice", 3)
+	if len(hits) < 2 {
+		t.Fatalf("检索只返回 %d 条，期望至少 2 条", len(hits))
+	}
+	first := hits[0].ID
+	if first != "a" && first != "c" {
+		t.Fatalf("★ 查 'billing invoice' 排第一的是 %q ——\n"+
+			"它既不含 billing 也不含 invoice。检索判别力失效。", first)
+	}
+	for i, h := range hits {
+		if h.ID == "b" {
+			t.Fatalf("★ 完全无关的 auth 文档排在第 %d 位（共 %d 条）", i+1, len(hits))
+		}
+	}
+}
+
+// TestAddRemoveChangesResults 钉住索引可变性契约。
+//
+// 变异：Remove 不真正删除 ⇒ 本例红。
+func TestAddRemoveChangesResults(t *testing.T) {
+	e := newTrained(t, []string{"alpha beta", "gamma delta"}, 32)
+	idx := tfidf.NewSearchableIndex(e)
+	idx.Add("x", "alpha beta gamma")
+
+	if got := idx.Search("alpha", 3); len(got) == 0 {
+		t.Fatal("加入后检索不到")
+	}
+	idx.Remove("x")
+	if got := idx.Search("alpha", 3); len(got) != 0 {
+		t.Fatalf("★ Remove 之后仍检索到 %d 条 —— 删除没生效", len(got))
+	}
+}
+
+// TestFingerprintAndDim 钉住元信息契约。
+func TestFingerprintAndDim(t *testing.T) {
+	e := newTrained(t, []string{"a b c"}, 24)
+	if e.Dim() != 24 {
+		t.Fatalf("Dim() = %d，期望 24", e.Dim())
+	}
+	if e.Fingerprint() == "" {
+		t.Fatal("★ Fingerprint 为空 —— 下游靠它判断缓存是否还有效")
+	}
+}