feat(kbtree): 知识库分类树的独立只读服务 + agent 技能 + WebUI 树浏览

让**外部 agent** 也能按分类树用这套知识库。HomeAgent 自己的 agent 仍
直接调内部方法（knowledge_search/create 等），走进程内直调，不经此服务。

一、内核树视图（internal/knowledge/tree.go）
  为什么不复用 TreeIndex：那个是**内部导出物**，面向 .index.json 落盘，
  每个条目带 top-20 的 TF-IDF 特征向量。直接序列化给外部有三个问题：
  体积（200 条时 .index.json 已 246KB 且冗余存了 preview，而正本在
  content.md）、泄漏（稀疏特征表 = 分词/IDF 内部表示）、语义错位
  （外部要的是"有哪些分类、每类下有什么"）。
  新增 TreeView/Subtree/Categories/CategoryCounts：不含向量，带条目数
  与可读摘要，支持 MaxDepth 懒加载、IncludeItems 只看结构。
  节点 Name 是**本级段名**（"go"）、Path 是完整路径（"tech/go"）——
  最初把全路径写进 Name，前端拼层级会得到 "tech/tech/go"，已修。

二、kbtree 插件：独立 HTTP 服务（默认 127.0.0.1:9892）
  为何不挂在 WebUI 的 /api/v1/knowledge* 下：
  1. 不共享鉴权与端口。WebUI 的 api_key 是给人操作界面用的，把它分发给
     外部 agent 等于把管理面凭据扩散出去。本服务用**独立 token** +
     独立端口，可单独关闭（token 未配置则启动时随机生成）。
  2. 只读。写入要决定分类归属与媒体处理，外部自行拼装容易造出越界/重名
     条目 —— 写入留给内核工具。
  3. 形状按树组织，而不是平铺搜索接口。
  端点：/tree（可指定 category/depth/items）、/categories、/counts、
  /search、/ （自述）。全部需 token（X-API-Key / Bearer / ?token=），
  非 GET 一律 405。无知识库时 Start 直接失败，不占端口。
  鉴权与 Slowloris/超时设置照 remotedevice 范式。

三、agent 技能（assets/skills/knowledge-base/SKILL.md）
  指令文档型 skill：教模型"先看树 → 定位分类 → 分类内检索"，并列出
  易错点（name 已含分类别再拼、只看第一条、404 附现有分类）。
  加载与校验由 internal/plugin/skill_bundled_test.go 守住 —— 这条断言
  的由来：非白名单的二级标题会被 extractToolDefs 当成工具定义，报错
  "invalid tool name"，而提示与真正原因（标题层级）毫无关联。
  kbtree 的测试还会校验文档提到的端点与代码一致，防漂移。

四、WebUI 树浏览（前端真正用起来，而非留一个没人调的端点）
  面板加可折叠的分类树：逐级点选即把搜索范围切到该子树（原先是让人
  手打分类名）。当前范围有可见标签与「全库」复位。

internal/plugins/webui/dashboard.js

@@ -1647,19 +1647,23 @@
           '</span><span class="val" id="know-count">' +
           (k?.knowledge?.item_count ?? "-") +
           "</span></div>" +
-          '<div style="margin-top:8px;display:flex;gap:4px;flex-wrap:wrap">' +
+          '<details id="know-tree-box" style="margin-top:8px">' +
+          '<summary style="cursor:pointer;font-size:12px;opacity:.8">' +
+          __("按分类浏览", "Browse by category") +
+          '</summary>' +
+          '<div id="know-tree" style="margin-top:6px;max-height:200px;overflow:auto;font-size:12px"></div>' +
+          '</details>' +
+          '<div style="margin-top:8px;display:flex;gap:4px;flex-wrap:wrap;align-items:center">' +
           '<input id="know-query" placeholder="' +
           __("搜索知识", "Search knowledge") +
           '" style="flex:1;min-width:120px">' +
-          '<input id="know-category" placeholder="' +
-          __("分类(可选)", "Category (optional)") +
-          '" style="width:110px" title="' +
-          __("限定在该分类子树内，如 tech 会搜 tech/go、tech/rust。留空则搜全库",
-             "Limit search to a category subtree, e.g. tech covers tech/go, tech/rust. Empty searches all") +
-          '">' +
+          '<span id="know-cat-scope" style="font-size:11px;opacity:.7"></span>' +
           '<button class="btn btn-primary btn-sm" onclick="searchKnowledgeChat()">' +
           __("搜索", "Search") +
           "</button>" +
+          '<button class="btn btn-sm" onclick="clearKnowledgeCategory()">' +
+          __("全库", "All") +
+          "</button>" +
           '</div><div id="know-result-chat" style="margin-top:8px;max-height:220px;overflow:auto"></div>' +
           '<div style="margin-top:12px;border-top:1px solid var(--border-color);padding-top:8px">' +
           '<input id="know-name" placeholder="' +
@@ -2990,9 +2994,92 @@
         return html;
       }
 
+      // 知识库分类树浏览。
+      //
+      // 数据来自 /knowledge/tree（只读树接口）。当前分类存 state，
+      // 搜索时自动带上 —— 这样"先定位分类再检索"这个更准的用法在 UI 上
+      // 是一步的事，而不是要求用户手打分类名。
+      var _knowCat = ""; // 当前分类的完整 path；"" = 全库
+
+      function renderKnowTree(node, depth) {
+        var html = "";
+        // 本节点的条目
+        (node.items || []).forEach(function (it) {
+          html +=
+            '<div style="padding-left:' +
+            (depth * 12 + 4) +
+            'px;padding-top:1px;padding-bottom:1px">' +
+            '<span style="opacity:.7">▸</span> ' +
+            '<span style="word-break:break-all">' +
+            knowEsc(it.name) +
+            "</span>" +
+            (it.size ? ' <span style="opacity:.5;font-size:10px">' + it.size + "B</span>" : "") +
+            (it.media && it.media.length
+              ? ' <span style="opacity:.6;font-size:10px">[' + it.media.length + __(" 媒体", " media") + "]</span>"
+              : "") +
+            "</div>";
+        });
+        // 子分类
+        (node.children || []).forEach(function (c) {
+          var isCur = _knowCat === c.path;
+          var mark = isCur ? "● " : "";
+          html +=
+            '<div style="padding-left:' +
+            (depth * 12) +
+            'px"><span onclick="selectKnowledgeCategory(\'' +
+            knowEsc(c.path).replace(/'/g, "&#39;") +
+            '\')" style="cursor:pointer;user-select:none">' +
+            mark +
+            knowEsc(c.name) +
+            ' <span style="opacity:.55;font-size:10px">' +
+            c.item_count +
+            "/" +
+            c.total_count +
+            "</span></span></div>";
+          html += renderKnowTree(c, depth + 1);
+        });
+        return html;
+      }
+
+      async function loadKnowledgeTree() {
+        var box = document.getElementById("know-tree");
+        if (!box) return;
+        box.innerHTML = '<div class="loading"></div>';
+        try {
+          var d = await api("/knowledge/tree?items=1");
+          if (!d || !d.tree) {
+            box.innerHTML =
+              '<p style="opacity:.6;font-size:11px">' + __("暂无分类", "No categories yet") + "</p>";
+            return;
+          }
+          box.innerHTML = renderKnowTree(d.tree, 0);
+        } catch (e) {
+          box.innerHTML =
+            '<p style="color:#fca5a5;font-size:11px">' + __("加载分类失败: ", "Load categories failed: ") + knowEsc(e.message) + "</p>";
+        }
+      }
+
+      function selectKnowledgeCategory(path) {
+        _knowCat = path || "";
+        var lbl = document.getElementById("know-cat-scope");
+        if (lbl) {
+          lbl.textContent = _knowCat
+            ? __("范围：", "scope: ") + _knowCat
+            : __("范围：全库", "scope: all");
+        }
+        loadKnowledgeTree();
+        // 立刻按新范围搜一次，省一次点击
+        var q = document.getElementById("know-query")?.value;
+        if (q) searchKnowledgeChat();
+      }
+
+      function clearKnowledgeCategory() {
+        selectKnowledgeCategory("");
+      }
+
       async function searchKnowledgeChat() {
         var q = document.getElementById("know-query")?.value;
-        var cat = document.getElementById("know-category")?.value || "";
+        var cat = _knowCat || "";
         var r = document.getElementById("know-result-chat");
         if (!r) return;
         if (!q) {
@@ -3082,7 +3169,14 @@
       function switchChatPanel(tab, el) {
         // 切到知识面板时拉实时计数：面板里的数字来自 state.kernel 快照，
         // 而知识条目会经工具/上传增删，快照不会自己变（实测创建后仍显示 "-"）。
-        if (tab === "knowledge") refreshKnowledgeCount();
+        if (tab === "knowledge") {
+          refreshKnowledgeCount();
+          var lbl = document.getElementById("know-cat-scope");
+          if (lbl && !lbl.textContent) {
+            lbl.textContent = _knowCat ? __("范围：", "scope: ") + _knowCat : __("范围：全库", "scope: all");
+          }
+          loadKnowledgeTree();
+        }
         var panels = {
           chat: document.getElementById("chat-panel-chat"),
           starmap: document.getElementById("chat-panel-starmap"),

internal/plugins/webui/handler.go

@@ -467,6 +467,11 @@ func (h *Handler) RegisterRoutes(mux *http.ServeMux) {
 	mux.HandleFunc("/api/v1/settings/", h.requireAPI(h.handleSettings))
 	mux.HandleFunc("/api/v1/knowledge", h.requireAPI(h.handleKnowledge))
 	mux.HandleFunc("/api/v1/knowledge/", h.requireAPI(h.handleKnowledge))
+	// 知识库的树形只读面（供外部 agent / skill 按分类导航）。
+	// 路由顺序无关：Go 1.22+ 的 ServeMux 取**最长前缀匹配**
+	// （/knowledge/ 只是子树通配，不会吃掉 /knowledge/tree）。go.mod 要求 1.25。
+	mux.HandleFunc("/api/v1/knowledge/tree", h.requireAPI(h.handleKnowledgeTree))
+	mux.HandleFunc("/api/v1/knowledge/tree/", h.requireAPI(h.handleKnowledgeTree))
 	mux.HandleFunc("/api/v1/adapters", h.requireAPI(h.handleAdapters))
 	mux.HandleFunc("/api/v1/adapters/", h.requireAPI(h.handleAdapterByID))
 	mux.HandleFunc("/api/v1/tracker", h.requireAPI(h.handleTracker))

internal/plugins/webui/handler_knowledge_tree.go

@@ -0,0 +1,150 @@
+package webui
+
+import (
+	"net/http"
+	"strconv"
+	"strings"
+
+	sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk"
+)
+
+// 知识库的**树形只读 API**。供外部 agent、skill、脚本按分类导航知识库。
+//
+// 为何只读：写入面已有 POST /api/v1/knowledge（可带媒体）。而写操作
+// 需要决定"挂到哪个分类、是否带媒体、是否重算稠密向量"，那是内核的事；
+// 让外部 agent 自己拼分类路径反而容易写出越界/重名的条目。读多写少，
+// 且读才是"让别的 agent 用起来"的关键。
+//
+// 鉴权沿用 requireAPI（api_key 或 cookie session），不新增鉴权面。
+//
+// 路由：
+//
+//	GET /api/v1/knowledge/tree                      整棵树
+//	GET /api/v1/knowledge/tree/{category}           某棵子树
+//	    ?depth=N         限制层数（0/省略 = 不限）——分类多时做懒加载
+//	    ?items=0|1       是否返回条目详情，默认 1
+//	    ?preview=N       预览字数上限，默认 120
+//	    ?q=关键词        在**该子树内**检索（分类 + 关键词组合）
+//	    ?limit=N         q 时的返回条数，默认 10
+//	GET /api/v1/knowledge/tree/categories           平铺分类列表
+//	GET /api/v1/knowledge/tree/counts               各分类条目数（倒序）
+//
+// 为什么把 categories/counts 也挂在 /tree/ 下：它们是**导航辅助**，
+// 回答"有哪些分类、哪里的内容最多"，与树形视图同源，挂在别处会割裂。
+
+// handleKnowledgeTree 处理树形只读请求。
+func (h *Handler) handleKnowledgeTree(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		writeJSON(w, http.StatusMethodNotAllowed, map[string]string{"error": "只支持 GET"})
+		return
+	}
+	if h.knowledge == nil {
+		writeJSON(w, http.StatusServiceUnavailable, map[string]string{"error": "knowledge not available"})
+		return
+	}
+
+	// path 形如 /api/v1/knowledge/tree[/sub/category]
+	sub := strings.Trim(strings.TrimPrefix(r.URL.Path, "/api/v1/knowledge/tree"), "/")
+
+	// 平铺分类列表
+	if sub == "categories" {
+		names, err := h.knowledge.Categories()
+		if err != nil {
+			writeJSON(w, http.StatusInternalServerError, map[string]string{"error": err.Error()})
+			return
+		}
+		if names == nil {
+			names = []string{}
+		}
+		writeJSON(w, http.StatusOK, map[string]interface{}{"categories": names})
+		return
+	}
+	// 各分类条目数
+	if sub == "counts" {
+		counts, err := h.knowledge.CategoryCounts()
+		if err != nil {
+			writeJSON(w, http.StatusInternalServerError, map[string]string{"error": err.Error()})
+			return
+		}
+		if counts == nil {
+			counts = []sdk.KnowledgeCategoryCount{}
+		}
+		writeJSON(w, http.StatusOK, map[string]interface{}{"counts": counts})
+		return
+	}
+
+	q := r.URL.Query()
+	opt := sdk.KnowledgeTreeOptions{
+		MaxDepth:     intQuery(q.Get("depth"), 0),
+		IncludeItems: boolQuery(q.Get("items"), true),
+		PreviewLimit: intQuery(q.Get("preview"), 0),
+	}
+
+	// 分类 + 关键词：在该子树内检索
+	if keyword := strings.TrimSpace(q.Get("q")); keyword != "" {
+		limit := intQuery(q.Get("limit"), 10)
+		if limit <= 0 || limit > 100 {
+			limit = 10
+		}
+		results, err := h.knowledge.SearchIn(keyword, sub, limit)
+		if err != nil {
+			code, msg := knowledgeStatusFor(err)
+			writeJSON(w, code, map[string]string{"error": msg})
+			return
+		}
+		views := make([]knowledgeView, 0, len(results))
+		for _, k := range results {
+			views = append(views, toKnowledgeView(k, k.Name))
+		}
+		writeJSON(w, http.StatusOK, map[string]interface{}{
+			"results":  views,
+			"category": sub,
+			"query":    keyword,
+		})
+		return
+	}
+
+	// 树视图（category 为空 = 整棵树）
+	view, err := h.knowledge.Subtree(sub, opt)
+	if err != nil {
+		code, msg := knowledgeStatusFor(err)
+		writeJSON(w, code, map[string]string{"error": msg})
+		return
+	}
+	if view == nil {
+		// 分类不存在：这是调用方能自己纠正的错误，给 404 + 现有分类便于自查
+		known, _ := h.knowledge.Categories()
+		writeJSON(w, http.StatusNotFound, map[string]interface{}{
+			"error":      "分类不存在: " + sub,
+			"categories": known,
+		})
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]interface{}{"tree": view})
+}
+
+// intQuery 解析整数查询参数；空/非法时用 def。
+func intQuery(s string, def int) int {
+	if s == "" {
+		return def
+	}
+	n, err := strconv.Atoi(s)
+	if err != nil {
+		return def
+	}
+	return n
+}
+
+// boolQuery 解析布尔查询参数；空时用 def。接受 1/0/true/false。
+func boolQuery(s string, def bool) bool {
+	if s == "" {
+		return def
+	}
+	switch strings.ToLower(s) {
+	case "1", "true", "yes", "on":
+		return true
+	case "0", "false", "no", "off":
+		return false
+	}
+	return def
+}

internal/plugins/webui/handler_knowledge_tree_test.go

@@ -0,0 +1,314 @@
+package webui
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"gitcode.com/JianFeeeee/HomeAgent/internal/knowledge"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/sdk"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/supervisor"
+	"gitcode.com/JianFeeeee/HomeAgent/pkg/types"
+)
+
+func newTreeHandler(t *testing.T) (*Handler, *knowledge.Store) {
+	t.Helper()
+	ks := knowledge.NewStore(t.TempDir())
+	if err := ks.Start(); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(ks.Stop)
+	for _, e := range []struct{ name, body string }{
+		{"tech/go/并发", "goroutine 调度 GMP 抢占"},
+		{"tech/go/context", "context 取消 超时"},
+		{"tech/rust/所有权", "borrow checker move 语义"},
+		{"life/sleep", "作息 褪黑素"},
+	} {
+		if err := ks.Add(e.name, e.body); err != nil {
+			t.Fatal(err)
+		}
+	}
+	cfg := &types.Config{Daemon: types.DaemonConfig{
+		CheckInterval: time.Minute, HeartbeatInterval: 30 * time.Second,
+	}}
+	sup := supervisor.New(cfg)
+	sup.Start()
+	t.Cleanup(sup.Shutdown)
+	return NewHandler(testSDK(sdk.SDKConfig{
+		Supervisor: supervisor.NewSDKAdapter(sup),
+		Knowledge:  sdk.NewKnowledge(ks),
+		Config:     sdk.NewConfig(cfg),
+	})), ks
+}
+
+// 路由不被 /api/v1/knowledge/ 通配吃掉（Go 1.22+ 最长前缀匹配）。
+func TestKnowledgeTreeRouteNotSwallowed(t *testing.T) {
+	h, _ := newTreeHandler(t)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	mux.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/api/v1/knowledge/tree", nil))
+	if rec.Code == http.StatusNotFound && rec.Body.Len() == 0 {
+		t.Fatal("路由未命中：/api/v1/knowledge/tree 返回了 mux 的 404")
+	}
+	// 鉴权未配置时是 503（说明命中了我们的 handler，而不是 mux 404）
+	if rec.Code != http.StatusServiceUnavailable {
+		t.Errorf("未配 api_key 时应为 503，实为 %d body=%s", rec.Code, rec.Body.String())
+	}
+}
+
+func treeGet(t *testing.T, h *Handler, path string) *httptest.ResponseRecorder {
+	t.Helper()
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, path, nil)
+	// 绕过鉴权直接打 handler：这里测的是路由与业务，鉴权另有测试覆盖
+	h.handleKnowledgeTree(rec, req)
+	return rec
+}
+
+func TestKnowledgeTreeAPI(t *testing.T) {
+	h, _ := newTreeHandler(t)
+
+	rec := treeGet(t, h, "/api/v1/knowledge/tree")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("应 200，实为 %d: %s", rec.Code, rec.Body.String())
+	}
+	var resp struct {
+		Tree struct {
+			Name       string `json:"name"`
+			Path       string `json:"path"`
+			TotalCount int    `json:"total_count"`
+			Children   []struct {
+				Name       string `json:"name"`
+				Path       string `json:"path"`
+				TotalCount int    `json:"total_count"`
+				Children   []struct {
+					ItemCount int `json:"item_count"`
+				} `json:"children"`
+			} `json:"children"`
+		} `json:"tree"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatal(err)
+	}
+	if resp.Tree.Name != "root" || resp.Tree.Path != "" {
+		t.Errorf("根应为 root/空，实为 %q/%q", resp.Tree.Name, resp.Tree.Path)
+	}
+	if resp.Tree.TotalCount != 4 {
+		t.Errorf("总条目应为 4，实为 %d", resp.Tree.TotalCount)
+	}
+	// 子节点 Name 是本级段名、Path 是全路径
+	var tech *struct {
+		Name       string `json:"name"`
+		Path       string `json:"path"`
+		TotalCount int    `json:"total_count"`
+		Children   []struct {
+			ItemCount int `json:"item_count"`
+		} `json:"children"`
+	}
+	for i := range resp.Tree.Children {
+		if resp.Tree.Children[i].Name == "tech" {
+			tech = &resp.Tree.Children[i]
+		}
+	}
+	if tech == nil {
+		t.Fatal("缺少 tech 节点")
+	}
+	if tech.Path != "tech" || tech.TotalCount != 3 {
+		t.Errorf("tech 应为 path=tech total=3，实为 %q/%d", tech.Path, tech.TotalCount)
+	}
+	if len(tech.Children) != 2 {
+		t.Errorf("tech 下应有 2 个子分类，实为 %d", len(tech.Children))
+	}
+
+	// 响应里不得出现向量
+	if containsStr(rec.Body.String(), `"vector"`) {
+		t.Error("树 API 不应返回向量")
+	}
+}
+
+// 子树路由：/tree/tech/go
+func TestKnowledgeTreeSubtreeAPI(t *testing.T) {
+	h, _ := newTreeHandler(t)
+	rec := treeGet(t, h, "/api/v1/knowledge/tree/tech/go")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("应 200，实为 %d: %s", rec.Code, rec.Body.String())
+	}
+	var resp struct {
+		Tree struct {
+			Name      string `json:"name"`
+			Path      string `json:"path"`
+			ItemCount int    `json:"item_count"`
+		} `json:"tree"`
+	}
+	json.Unmarshal(rec.Body.Bytes(), &resp)
+	if resp.Tree.Path != "tech/go" || resp.Tree.ItemCount != 2 {
+		t.Errorf("tech/go 应有 2 条，实为 %q/%d", resp.Tree.Path, resp.Tree.ItemCount)
+	}
+	if resp.Tree.Name != "go" {
+		t.Errorf("Name 应为本级段名 go，实为 %q", resp.Tree.Name)
+	}
+}
+
+// 不存在的分类：404 + 附上现有分类便于自查。
+func TestKnowledgeTreeNotFound(t *testing.T) {
+	h, _ := newTreeHandler(t)
+	rec := treeGet(t, h, "/api/v1/knowledge/tree/nope/here")
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("应 404，实为 %d: %s", rec.Code, rec.Body.String())
+	}
+	var resp struct {
+		Error      string   `json:"error"`
+		Categories []string `json:"categories"`
+	}
+	json.Unmarshal(rec.Body.Bytes(), &resp)
+	if len(resp.Categories) == 0 {
+		t.Error("404 应附带现有分类列表，便于调用方自查")
+	}
+}
+
+// 懒加载：depth=1 只给一层但计数准确；items=0 不返回条目。
+func TestKnowledgeTreeLazyLoad(t *testing.T) {
+	h, _ := newTreeHandler(t)
+	rec := treeGet(t, h, "/api/v1/knowledge/tree?depth=1&items=0")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("应 200，实为 %d", rec.Code)
+	}
+	var resp struct {
+		Tree struct {
+			TotalCount int `json:"total_count"`
+			Children   []struct {
+				Name       string `json:"name"`
+				TotalCount int    `json:"total_count"`
+				Children   []any  `json:"children"`
+			} `json:"children"`
+		} `json:"tree"`
+	}
+	json.Unmarshal(rec.Body.Bytes(), &resp)
+	if resp.Tree.TotalCount != 4 {
+		t.Errorf("剪枝不应改变总数，实为 %d", resp.Tree.TotalCount)
+	}
+	for _, c := range resp.Tree.Children {
+		if len(c.Children) != 0 {
+			t.Errorf("depth=1 时 %s 不应展开子节点", c.Name)
+		}
+	}
+	if containsStr(rec.Body.String(), `"preview"`) {
+		t.Error("items=0 时不应返回 preview")
+	}
+}
+
+// 分类内检索：/tree/tech?q=...
+func TestKnowledgeTreeSearchInCategory(t *testing.T) {
+	h, _ := newTreeHandler(t)
+	rec := treeGet(t, h, "/api/v1/knowledge/tree/tech?q=borrow")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("应 200，实为 %d: %s", rec.Code, rec.Body.String())
+	}
+	var resp struct {
+		Results  []knowledgeView `json:"results"`
+		Category string          `json:"category"`
+		Query    string          `json:"query"`
+	}
+	json.Unmarshal(rec.Body.Bytes(), &resp)
+	// 首位必须是真正相关的 rust/所有权。
+	//
+	// 不断言"只命中 1 条"：词法路对任何查询都会给全库打个低分（这是它
+	// 融合设计的已知性质——靠排序把强命中顶到前面，而不是靠过滤把弱命中
+	// 删掉），所以 tech 子树内会有 3 条候选。这是有意行为，不是缺陷。
+	if len(resp.Results) == 0 {
+		t.Fatal("tech 子树内检索 borrow 应有命中")
+	}
+	if resp.Results[0].Name != "tech/rust/所有权" {
+		t.Errorf("首位应是最相关的 rust/所有权，实为 %q", resp.Results[0].Name)
+	}
+	// 但范围外的 life/sleep 绝不能出现
+	for _, r := range resp.Results {
+		if !strings.HasPrefix(r.Name, "tech/") {
+			t.Errorf("范围外条目 %q 混入 tech 子树检索结果", r.Name)
+		}
+	}
+	if resp.Category != "tech" {
+		t.Errorf("应回显 category=tech，实为 %q", resp.Category)
+	}
+}
+
+// 平铺分类与计数端点。
+func TestKnowledgeTreeCategoriesAndCounts(t *testing.T) {
+	h, _ := newTreeHandler(t)
+
+	rec := treeGet(t, h, "/api/v1/knowledge/tree/categories")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("categories 应 200，实为 %d", rec.Code)
+	}
+	var c1 struct {
+		Categories []string `json:"categories"`
+	}
+	json.Unmarshal(rec.Body.Bytes(), &c1)
+	want := map[string]bool{"tech": true, "tech/go": true, "tech/rust": true, "life": true}
+	for _, c := range c1.Categories {
+		delete(want, c)
+	}
+	if len(want) != 0 {
+		t.Errorf("缺少 %v，实为 %v", want, c1.Categories)
+	}
+
+	rec = treeGet(t, h, "/api/v1/knowledge/tree/counts")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("counts 应 200，实为 %d", rec.Code)
+	}
+	var c2 struct {
+		Counts []struct {
+			Category string `json:"category"`
+			Count    int    `json:"count"`
+		} `json:"counts"`
+	}
+	json.Unmarshal(rec.Body.Bytes(), &c2)
+	byName := map[string]int{}
+	for _, x := range c2.Counts {
+		byName[x.Category] = x.Count
+	}
+	if byName["tech"] != 3 || byName["life"] != 1 {
+		t.Errorf("计数错误: %v", byName)
+	}
+}
+
+// 只读面：非 GET 一律拒绝（防止有人以为能通过它写入）。
+func TestKnowledgeTreeIsReadOnly(t *testing.T) {
+	h, ks := newTreeHandler(t)
+	before := len(ks.List())
+	for _, m := range []string{http.MethodPost, http.MethodDelete, http.MethodPut, http.MethodPatch} {
+		rec := httptest.NewRecorder()
+		h.handleKnowledgeTree(rec, httptest.NewRequest(m, "/api/v1/knowledge/tree", nil))
+		if rec.Code != http.StatusMethodNotAllowed {
+			t.Errorf("%s 应 405，实为 %d", m, rec.Code)
+		}
+	}
+	if len(ks.List()) != before {
+		t.Error("只读端点不应改变条目数")
+	}
+}
+
+// 知识库不可用时给 503 而不是 panic。
+func TestKnowledgeTreeUnavailable(t *testing.T) {
+	h, _ := newTestHandler(t)
+	rec := treeGet(t, h, "/api/v1/knowledge/tree")
+	if rec.Code != http.StatusServiceUnavailable {
+		t.Errorf("无知识库应 503，实为 %d", rec.Code)
+	}
+}
+
+func containsStr(hay, needle string) bool {
+	return len(hay) >= len(needle) && (func() bool {
+		for i := 0; i+len(needle) <= len(hay); i++ {
+			if hay[i:i+len(needle)] == needle {
+				return true
+			}
+		}
+		return false
+	})()
+}