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 树浏览(前端真正用起来,而非留一个没人调的端点)
  面板加可折叠的分类树:逐级点选即把搜索范围切到该子树(原先是让人
  手打分类名)。当前范围有可见标签与「全库」复位。
This commit is contained in:
JianFeeeee
2026-09-26 14:19:34 +08:00
parent 531d7f41f4
commit ebf6df319b
14 changed files with 2071 additions and 9 deletions

View File

@ -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"),