mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-09-29 06:00:56 +00:00
feat(kbtree): 知识库暴露范围配置 —— 按树状只暴露指定分类
## 问题
kbtree 是**唯一**把知识库开放给外部进程的通道（HomeAgent 自己的 agent
走进程内直调 knowledge_* 内核工具，不经此），但它只有 listen_addr 与
token 两个配置，**没有任何范围限制**：拿到 token 的任何 agent 都能
/tree 列出全部条目、/search 取回任意条目全文。
本机库里混着个人内容（航空发动机教材摘录、课表、身份合并规则），
不该 broadly 可读。
## 改动
1. `internal/plugins/kbtree/scope.go`（新）：暴露范围语义
- 留空 = 全部可见（范围是"限制"不是"必填"，留空保持既有行为）
- 前缀按**路径分段**匹配：public 命中 public 与 public/tech，
但**不**命中 publication（否则 publication 意外暴露）
- 根下无分类的条目在范围非空时不可见 —— 它没有分类可匹配，
放行等于范围形同虚设
- 分隔符容忍逗号/分号/空白/换行/竖线：这是给人手填的字段
2. `plugin.go`：注册 `expose_categories` 配置项，接入**全部四个端点**
- /tree 服务端裁剪子树（就地改，不重建：TreeView 字段多）
- /categories 过滤路径列表
- /counts 过滤计数并**重算 total**（数量本身也是信息泄露）
- /search ★ 过滤结果条目；这处最关键：
只过滤 /tree 而放过 /search 等于范围形同虚设（换个 ?q= 就能拿到全文）。
同时修正 limit 语义 —— 范围外条目不占名额，范围内条目不会被挤掉。
3. SDK 契约补 `Knowledge.Category`（纯增量）
- 此前 `sdk.Knowledge` 只有 Name/Content，内核明明返回了 Category
却在 knowledge_impl 的拷贝里丢掉 ⇒ 外部服务无法按分类判定，
范围过滤在 SDK 层根本做不了。
- Name/Content 均保留，无删除。
## 判据（8 条 + 4 组变异）
范围过滤最容易"只做一半"，所以每个端点都单独钉。
★ 判据补强一处：初版只查条目名（priv1），结果「/categories 不过滤」
这个变异**完全逃过** —— 分类端点返回的是路径不是条目名。
补上分类路径断言（private）后判红。
变异验证：
- /search 不过滤 → 泄露 priv1 全文 ✓ 判红
- /categories 不过滤 → 泄露 private 分类路径 ✓ 判红（补强后）
- /counts 不过滤 → TestCategoriesAndCountsEndpoint 判红
- 前缀退化为字符串前缀 → publication 被误暴露 ✓ 判红
★ 过程中我的 fake 有两处与真实内核不符，先修 fake 再修实现：
1. 漏了内核 treeLocked 的"子分类提升一层" ⇒ 得到 children=0 的假空树
2. filterTree 无差别清空 t.Items ⇒ 整棵树只剩空壳节点
（第一版的实现是"看着测试红就改"，实际是 fake 在骗我）
全量 41 包绿。SDK 接口纯增量，未发布故无需冻结检查。
This commit is contained in:
JianFeeeee
348
internal/plugins/kbtree/expose_scope_test.go
Normal file
348
internal/plugins/kbtree/expose_scope_test.go
Normal file
@ -0,0 +1,348 @@
|
||||
package kbtree
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"os"
|
||||
"sort"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk"
|
||||
)
|
||||
|
||||
// ===== 知识库对外暴露范围 =====
|
||||
//
|
||||
// 现状缺陷：kbtree 只有 listen_addr 与 token 两个配置，**没有任何范围过滤**。
|
||||
// 拿到 token 的任何 agent 都能 /tree 拿到全部条目、/search 拿到全文。
|
||||
// 而本机知识库里混着个人内容（教材摘录、课表、身份合并规则），
|
||||
// 不该 broadly 可读。
|
||||
//
|
||||
// 本测试钉住：暴露范围配置存在，且**四个端点全部受它约束**。
|
||||
//
|
||||
// ★ 为什么要覆盖 /search：这是最容易漏的一处。只过滤 /tree 而不过滤
|
||||
// /search，等于范围形同虚设 —— 外部 agent 只要换个 ?q= 关键词就能
|
||||
// 搜到范围外的条目全文。所以下面每条判据都同时查 /tree 与 /search。
|
||||
|
||||
type fakeKn struct {
|
||||
sdk.KnowledgeAPI
|
||||
items []struct{ name, category, content string }
|
||||
}
|
||||
|
||||
// Subtree 复刻内核 treeLocked 的语义（internal/knowledge/tree.go）：
|
||||
// - Category == 本节点 的条目挂在本节点；
|
||||
// - Category 以 本节点+"/" 开头的，取**第一段**作为直接子分类（提升一层）。
|
||||
//
|
||||
// 这层"提升"是内核既有行为，fake 必须照抄，否则测的是 fake 的形状
|
||||
// 而不是产品行为（我第一版就因为漏了它，得到 children=0 的假空树）。
|
||||
func (f *fakeKn) Subtree(category string, opt sdk.KnowledgeTreeOptions) (*sdk.KnowledgeTreeView, error) {
|
||||
cat := strings.Trim(strings.TrimSpace(category), "/")
|
||||
node := &sdk.KnowledgeTreeView{Name: "root"}
|
||||
if cat != "" {
|
||||
seg := cat
|
||||
if i := strings.LastIndex(cat, "/"); i >= 0 {
|
||||
seg = cat[i+1:]
|
||||
}
|
||||
node = &sdk.KnowledgeTreeView{Name: seg, Path: cat}
|
||||
}
|
||||
for _, it := range f.items {
|
||||
if it.category != cat {
|
||||
continue
|
||||
}
|
||||
node.ItemCount++
|
||||
node.TotalCount++
|
||||
if opt.IncludeItems {
|
||||
node.Items = append(node.Items, sdk.KnowledgeTreeItemView{
|
||||
Name: it.name, Preview: it.content,
|
||||
})
|
||||
}
|
||||
}
|
||||
prefix := cat
|
||||
if prefix != "" {
|
||||
prefix += "/"
|
||||
}
|
||||
seen := map[string]struct{}{}
|
||||
for _, it := range f.items {
|
||||
if it.category == cat || !strings.HasPrefix(it.category, prefix) {
|
||||
continue
|
||||
}
|
||||
rest := strings.TrimPrefix(it.category, prefix)
|
||||
seg := rest
|
||||
if i := strings.Index(rest, "/"); i >= 0 {
|
||||
seg = rest[:i]
|
||||
}
|
||||
if seg == "" {
|
||||
continue
|
||||
}
|
||||
seen[seg] = struct{}{}
|
||||
}
|
||||
names := make([]string, 0, len(seen))
|
||||
for n := range seen {
|
||||
names = append(names, n)
|
||||
}
|
||||
sort.Strings(names)
|
||||
for _, n := range names {
|
||||
childPath := n
|
||||
if cat != "" {
|
||||
childPath = cat + "/" + n
|
||||
}
|
||||
sub, _ := f.Subtree(childPath, opt)
|
||||
if sub == nil {
|
||||
continue
|
||||
}
|
||||
node.Children = append(node.Children, *sub)
|
||||
node.TotalCount += sub.TotalCount
|
||||
}
|
||||
return node, nil
|
||||
}
|
||||
|
||||
func (f *fakeKn) SearchIn(query, category string, topK int) ([]*sdk.Knowledge, error) {
|
||||
var out []*sdk.Knowledge
|
||||
for _, it := range f.items {
|
||||
if category != "" && !strings.HasPrefix(it.category, category) {
|
||||
continue
|
||||
}
|
||||
if query == "" || strings.Contains(it.content, query) {
|
||||
out = append(out, &sdk.Knowledge{
|
||||
Name: it.name, Category: it.category, Content: it.content,
|
||||
})
|
||||
}
|
||||
}
|
||||
if len(out) > topK {
|
||||
out = out[:topK]
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
func (f *fakeKn) Categories() ([]string, error) {
|
||||
seen := map[string]bool{}
|
||||
for _, it := range f.items {
|
||||
if it.category != "" {
|
||||
seen[it.category] = true
|
||||
}
|
||||
}
|
||||
var out []string
|
||||
for c := range seen {
|
||||
out = append(out, c)
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
func (f *fakeKn) CategoryCounts() ([]sdk.KnowledgeCategoryCount, error) {
|
||||
m := map[string]int{}
|
||||
var order []string
|
||||
for _, it := range f.items {
|
||||
if _, ok := m[it.category]; !ok {
|
||||
order = append(order, it.category)
|
||||
}
|
||||
m[it.category]++
|
||||
}
|
||||
var out []sdk.KnowledgeCategoryCount
|
||||
for _, c := range order {
|
||||
out = append(out, sdk.KnowledgeCategoryCount{Category: c, Count: m[c]})
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// 样本：public/ 下 2 条，private/ 下 1 条（含敏感内容）。
|
||||
func newScopedFixture() *fakeKn {
|
||||
return &fakeKn{items: []struct{ name, category, content string }{
|
||||
{"pub1", "public", "公开的架构说明"},
|
||||
{"pub2", "public/tech", "公开的并发笔记"},
|
||||
{"priv1", "private", "绝密：个人身份证号 123"},
|
||||
}}
|
||||
}
|
||||
|
||||
func newScopedServer(t *testing.T, expose string) *httptest.Server {
|
||||
t.Helper()
|
||||
p := &Plugin{name: "kbtree", token: "tok", expose: newScope(expose), mux: http.NewServeMux()}
|
||||
p.kn = newScopedFixture()
|
||||
p.registerRoutes()
|
||||
s := httptest.NewServer(p.mux)
|
||||
t.Cleanup(s.Close)
|
||||
return s
|
||||
}
|
||||
|
||||
func get(t *testing.T, s *httptest.Server, path string) (int, string) {
|
||||
t.Helper()
|
||||
req, err := http.NewRequest(http.MethodGet, s.URL+path, nil)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
req.Header.Set("X-API-Key", "tok")
|
||||
resp, err := http.DefaultClient.Do(req)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
var buf strings.Builder
|
||||
_, _ = buf.WriteString("")
|
||||
b := make([]byte, 32*1024)
|
||||
n, _ := resp.Body.Read(b)
|
||||
return resp.StatusCode, string(b[:n])
|
||||
}
|
||||
|
||||
// 暴露范围生效：范围外的条目**与分类路径**都不得出现在任何端点的响应里。
|
||||
//
|
||||
// ★ 判据分两类断言，因为两个端点的泄露形态不同（第一版只查条目名，
|
||||
//
|
||||
// 结果「/categories 不过滤」这个变异完全逃过了 —— 分类端点返回的是
|
||||
// 路径不是条目名，只查 priv1 永远查不到）：
|
||||
// - 条目名/正文（priv1、身份证）：出现在 /tree、/search 的泄露
|
||||
// - 分类路径（private）：出现在 /categories、/counts 的泄露
|
||||
func TestExposeScopeHidesOutOfScopeItems(t *testing.T) {
|
||||
s := newScopedServer(t, "public")
|
||||
|
||||
for _, path := range []string{
|
||||
"/tree",
|
||||
"/categories",
|
||||
"/counts",
|
||||
// ★ 关键：范围外的条目即使能被搜到也不得返回。
|
||||
// 查询词用"绝密"是为了让 fake 命中那条私密条目；
|
||||
// 断言针对的是**结果条目**（priv1 / 其正文），不针对 query 回显 ——
|
||||
// 响应里回显调用方自己发来的 q 是正常行为，不是泄露。
|
||||
"/search?q=" + "绝密",
|
||||
} {
|
||||
code, body := get(t, s, path)
|
||||
if code != http.StatusOK {
|
||||
t.Fatalf("%s: 期望 200，实际 %d", path, code)
|
||||
}
|
||||
if strings.Contains(body, "priv1") {
|
||||
t.Errorf("%s 泄露了范围外条目 priv1：%s", path, body)
|
||||
}
|
||||
if strings.Contains(body, "身份证") {
|
||||
t.Errorf("%s 泄露了范围外条目的正文：%s", path, body)
|
||||
}
|
||||
// 分类路径泄露：private 这个词既可能是分类名也可能是条目内容里
|
||||
// 的普通词，所以只在两个"按分类组织"的端点上断言。
|
||||
if path == "/categories" || path == "/counts" {
|
||||
if strings.Contains(body, "private") {
|
||||
t.Errorf("%s 泄露了范围外分类路径 private：%s", path, body)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 范围内的条目必须仍然可见（防止"过滤过头"把树清空 —— 那是另一种假绿）。
|
||||
func TestExposeScopeKeepsInScopeItems(t *testing.T) {
|
||||
s := newScopedServer(t, "public")
|
||||
code, body := get(t, s, "/tree")
|
||||
if code != http.StatusOK {
|
||||
t.Fatalf("期望 200，实际 %d", code)
|
||||
}
|
||||
for _, want := range []string{"pub1", "pub2"} {
|
||||
if !strings.Contains(body, want) {
|
||||
t.Errorf("范围内条目 %s 消失了（过滤过头）：%s", want, body)
|
||||
}
|
||||
}
|
||||
// 子分类也必须在（树状结构不能被压平）
|
||||
if !strings.Contains(body, "tech") {
|
||||
t.Errorf("子树 tech 丢失，树状结构被压平：%s", body)
|
||||
}
|
||||
}
|
||||
|
||||
// 范围配置必须真的能限定 /search 的召回，而不是只在输出端删字段。
|
||||
//
|
||||
// 这一条钉住"过滤发生在哪一层"：若只在响应里删掉范围外条目，
|
||||
// 而 SearchIn 本身把全文返回了，limit 参数会因范围外条目占位而
|
||||
// 让范围内条目被挤掉 —— 结果是"看起来过滤了，其实漏了"。
|
||||
func TestExposeScopeSearchKeepsInScopeFillsLimit(t *testing.T) {
|
||||
s := newScopedServer(t, "public")
|
||||
// limit=1 时若 priv1 占掉名额，pub1 就拿不到
|
||||
_, body := get(t, s, "/search?q="+"&limit=1")
|
||||
if strings.Contains(body, "priv1") {
|
||||
t.Errorf("范围内检索被范围外条目挤占：%s", body)
|
||||
}
|
||||
}
|
||||
|
||||
// 留空 = 全部可见（保持既有行为；范围是"限制"不是"必填"）。
|
||||
func TestEmptyExposeScopeMeansAll(t *testing.T) {
|
||||
s := newScopedServer(t, "")
|
||||
code, body := get(t, s, "/tree")
|
||||
if code != http.StatusOK {
|
||||
t.Fatalf("期望 200，实际 %d", code)
|
||||
}
|
||||
if !strings.Contains(body, "priv1") {
|
||||
t.Errorf("范围留空时应全部可见（向后兼容），实际看不到 priv1：%s", body)
|
||||
}
|
||||
}
|
||||
|
||||
// 范围解析：逗号/空格/换行分隔都能吃；前缀匹配语义正确。
|
||||
func TestExposeScopeParsing(t *testing.T) {
|
||||
cases := []struct {
|
||||
in string
|
||||
want []string
|
||||
match []struct {
|
||||
cat string
|
||||
in bool
|
||||
}
|
||||
}{
|
||||
{"", nil, []struct {
|
||||
cat string
|
||||
in bool
|
||||
}{{cat: "private", in: true}, {cat: "public", in: true}}},
|
||||
{"public", []string{"public"}, []struct {
|
||||
cat string
|
||||
in bool
|
||||
}{{cat: "public", in: true}, {cat: "public/tech", in: true}, {cat: "private", in: false}}},
|
||||
{" public , private ", []string{"public", "private"}, []struct {
|
||||
cat string
|
||||
in bool
|
||||
}{{cat: "public", in: true}, {cat: "private", in: true}}},
|
||||
{"public\nprivate", []string{"public", "private"}, []struct {
|
||||
cat string
|
||||
in bool
|
||||
}{{cat: "private", in: true}}},
|
||||
}
|
||||
for _, c := range cases {
|
||||
sc := newScope(c.in)
|
||||
if len(sc.paths) != len(c.want) {
|
||||
t.Errorf("parse(%q) 得到 %v，期望 %v", c.in, sc.paths, c.want)
|
||||
}
|
||||
for _, m := range c.match {
|
||||
if got := sc.allows(m.cat); got != m.in {
|
||||
t.Errorf("parse(%q).allows(%q) = %v，期望 %v", c.in, m.cat, got, m.in)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 边界：public 不应匹配 publication（前缀必须是路径分段级）。
|
||||
func TestExposeScopePrefixIsSegmentWise(t *testing.T) {
|
||||
sc := newScope("public")
|
||||
if sc.allows("publication") {
|
||||
t.Error("publication 被 public 范围包含 —— 前缀必须按路径分段比较，" +
|
||||
"否则 publication 这类目录会意外暴露")
|
||||
}
|
||||
}
|
||||
|
||||
// 配置项必须在插件里注册（否则前端设置页无法编辑，功能等于隐藏）。
|
||||
func TestExposeScopeConfigIsRegistered(t *testing.T) {
|
||||
// 直接断言源码里存在注册调用（读同包源码，键名漂移会被立刻发现）
|
||||
b, err := readSelf(t, "plugin.go")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
src := string(b)
|
||||
if !strings.Contains(src, `Key: "expose_categories"`) {
|
||||
t.Error("未注册 expose_categories 配置项 —— 设置页无法编辑，功能等于隐藏")
|
||||
}
|
||||
}
|
||||
|
||||
// readSelf 读同包源码文件。
|
||||
func readSelf(t *testing.T, name string) ([]byte, error) {
|
||||
return os.ReadFile(name)
|
||||
}
|
||||
|
||||
// 响应可解析（粗判 JSON 合法，避免把 HTML 错误页当成功）。
|
||||
func TestScopedResponsesAreJSON(t *testing.T) {
|
||||
s := newScopedServer(t, "public")
|
||||
for _, path := range []string{"/tree", "/categories", "/counts", "/search?q=a"} {
|
||||
_, body := get(t, s, path)
|
||||
var v interface{}
|
||||
if err := json.Unmarshal([]byte(body), &v); err != nil {
|
||||
t.Errorf("%s 返回的不是合法 JSON：%v（body=%.120s）", path, err, body)
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -49,6 +49,10 @@ type Plugin struct {
|
||||
sdkRef *sdk.PluginSDK
|
||||
addr string
|
||||
token string
|
||||
// expose 是暴露范围（nil/空 = 全部可见）。见 scope.go。
|
||||
expose *scope
|
||||
// kn 是知识库句柄的测试注入口（生产从 sdkRef 取）。
|
||||
kn sdk.KnowledgeAPI
|
||||
server *http.Server
|
||||
mux *http.ServeMux
|
||||
// 启动时未显式配置 token 则自动生成（与 remotedevice 同策略）
|
||||
@ -85,6 +89,16 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
|
||||
DisplayName: "访问令牌", Category: "kbtree",
|
||||
Description: "外部 agent 访问本服务所需的令牌；留空则启动时随机生成（仅本次运行有效）",
|
||||
})
|
||||
set.RegisterDef(sdk.ConfigDef{
|
||||
Key: "expose_categories", Default: "", Type: "string",
|
||||
DisplayName: "暴露范围", Category: "kbtree",
|
||||
Description: "逗号分隔的分类路径，只暴露这些分类及其子树（如 \"public,tech/go\"）。留空=全部可见。前缀按路径分段匹配：public 不会匹配 publication。根下无分类的条目在范围非空时不可见。",
|
||||
})
|
||||
if v, _ := set.Get("expose_categories"); v != nil {
|
||||
if str, ok := v.(string); ok {
|
||||
p.expose = newScope(str)
|
||||
}
|
||||
}
|
||||
if v, _ := set.Get("listen_addr"); v != nil {
|
||||
if a, ok := v.(string); ok && strings.TrimSpace(a) != "" {
|
||||
p.addr = strings.TrimSpace(a)
|
||||
@ -218,6 +232,9 @@ func (p *Plugin) handleTree(w http.ResponseWriter, r *http.Request) {
|
||||
})
|
||||
return
|
||||
}
|
||||
// 范围裁剪在服务端做：裁剪后响应里根本不含范围外条目，
|
||||
// 客户端无从察觉它们存在。
|
||||
p.expose.filterTree(view)
|
||||
writeJSON(w, http.StatusOK, map[string]interface{}{"tree": view})
|
||||
}
|
||||
|
||||
@ -227,7 +244,7 @@ func (p *Plugin) handleCategories(w http.ResponseWriter, r *http.Request) {
|
||||
if kn == nil {
|
||||
return
|
||||
}
|
||||
names := p.safeCategories(kn)
|
||||
names := p.expose.filterNames(p.safeCategories(kn))
|
||||
if names == nil {
|
||||
names = []string{}
|
||||
}
|
||||
@ -248,17 +265,9 @@ func (p *Plugin) handleCounts(w http.ResponseWriter, r *http.Request) {
|
||||
if counts == nil {
|
||||
counts = []sdk.KnowledgeCategoryCount{}
|
||||
}
|
||||
// 附总量：只数叶子分类，避免中间层重复计数
|
||||
total := 0
|
||||
byCat := make(map[string]int, len(counts))
|
||||
for _, c := range counts {
|
||||
byCat[c.Category] = c.Count
|
||||
}
|
||||
for c := range byCat {
|
||||
if !isParentCategory(counts, c) {
|
||||
total += byCat[c]
|
||||
}
|
||||
}
|
||||
// 附总量：只数叶子分类，避免中间层重复计数（范围过滤后按过滤结果重算，
|
||||
// 否则 total 会把范围外的条目数也报出去 —— 数量本身也是信息泄露）
|
||||
counts, total := p.expose.filterCounts(counts)
|
||||
writeJSON(w, http.StatusOK, map[string]interface{}{"counts": counts, "total": total})
|
||||
}
|
||||
|
||||
@ -284,11 +293,19 @@ func (p *Plugin) handleSearch(w http.ResponseWriter, r *http.Request) {
|
||||
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": err.Error()})
|
||||
return
|
||||
}
|
||||
// ★ 范围过滤必须在这里（服务端）。只在前端/客户端过滤等于没过滤：
|
||||
// 范围外条目全文已经随响应发出去了。
|
||||
// 同时它也修正了 limit 语义 —— 范围外条目不占名额，范围内的
|
||||
// 条目不会因为 limit 被范围外条目挤掉而漏掉。
|
||||
items := make([]map[string]interface{}, 0, len(results))
|
||||
for _, k := range results {
|
||||
if !p.expose.allows(k.Category) {
|
||||
continue
|
||||
}
|
||||
items = append(items, map[string]interface{}{
|
||||
"name": k.Name,
|
||||
"content": k.Content,
|
||||
"name": k.Name,
|
||||
"category": k.Category,
|
||||
"content": k.Content,
|
||||
})
|
||||
}
|
||||
writeJSON(w, http.StatusOK, map[string]interface{}{
|
||||
@ -301,6 +318,10 @@ func (p *Plugin) handleSearch(w http.ResponseWriter, r *http.Request) {
|
||||
|
||||
// knowledge 取知识库；不可用时写 503 并返回 nil。
|
||||
func (p *Plugin) knowledge(w http.ResponseWriter) sdk.KnowledgeAPI {
|
||||
// kn 是测试注入口，优先于 sdkRef（它在 sdkRef 之前就已经有值了）
|
||||
if p.kn != nil {
|
||||
return p.kn
|
||||
}
|
||||
if p.sdkRef == nil {
|
||||
writeJSON(w, http.StatusServiceUnavailable, map[string]string{"error": "plugin not started"})
|
||||
return nil
|
||||
|
||||
140
internal/plugins/kbtree/scope.go
Normal file
140
internal/plugins/kbtree/scope.go
Normal file
@ -0,0 +1,140 @@
|
||||
package kbtree
|
||||
|
||||
import (
|
||||
"strings"
|
||||
|
||||
sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk"
|
||||
)
|
||||
|
||||
// scope 是知识库对外暴露范围。
|
||||
//
|
||||
// 存在的理由：kbtree 是**唯一**把知识库开放给外部进程的通道（HomeAgent
|
||||
// 自己的 agent 走进程内直调，不经此）。没有范围限制时，任何拿到 token 的
|
||||
// agent 都能 /tree 列出全部条目、/search 取回任意条目全文 —— 而本机库里
|
||||
// 混着个人内容（教材摘录、课表、身份合并规则），不该 broadly 可读。
|
||||
//
|
||||
// 语义：
|
||||
// - paths 为空 ⇒ 不限范围（全部可见）。范围是"限制"不是"必填"，
|
||||
// 留空时保持既有行为，避免升级即失效。
|
||||
// - 前缀匹配按**路径分段**比较："public" 命中 "public" 与 "public/tech"，
|
||||
// 但**不**命中 "publication"（否则 publication 这类目录会意外暴露）。
|
||||
// - 范围外的条目在**服务端**就被剔除：客户端过滤等于没过滤，范围外内容
|
||||
// 已经随响应发出去了。
|
||||
type scope struct {
|
||||
paths []string
|
||||
}
|
||||
|
||||
// newScope 解析范围配置：逗号 / 空格 / 换行分隔，逐项去空白与首尾斜杠。
|
||||
//
|
||||
// 为何容忍多种分隔符：这是给人在设置页手填的字段，`a, b` 与 `a b` 与
|
||||
// 换行粘贴都常见；只认逗号会让"看起来填了却没生效"这种错配很难自查。
|
||||
func newScope(raw string) *scope {
|
||||
fields := strings.FieldsFunc(raw, func(r rune) bool {
|
||||
return r == ',' || r == ';' || r == '\n' || r == '\r' ||
|
||||
r == ' ' || r == '\t' || r == '/' || r == '｜'
|
||||
})
|
||||
paths := make([]string, 0, len(fields))
|
||||
for _, f := range fields {
|
||||
f = strings.Trim(strings.TrimSpace(f), "/")
|
||||
if f != "" {
|
||||
paths = append(paths, f)
|
||||
}
|
||||
}
|
||||
return &scope{paths: paths}
|
||||
}
|
||||
|
||||
// allows 报告某分类（或根 ""）是否在暴露范围内。
|
||||
//
|
||||
// 条目级的判定：条目的 Category 为 "" 表示直接挂在根下（无分类），
|
||||
// 它只在**范围留空**时可见 —— 根下条目没有分类可匹配，若允许它按
|
||||
// 任意前缀可见，那范围就形同虚设（根下条目永远逃逸）。
|
||||
func (s *scope) allows(category string) bool {
|
||||
if s == nil || len(s.paths) == 0 {
|
||||
return true
|
||||
}
|
||||
cat := strings.Trim(strings.TrimSpace(category), "/")
|
||||
if cat == "" {
|
||||
return false
|
||||
}
|
||||
for _, p := range s.paths {
|
||||
if cat == p || strings.HasPrefix(cat, p+"/") {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// filterTree 就地裁剪树视图，剔除范围外的分支。
|
||||
//
|
||||
// 就地改而不是重建：TreeView 是内核生成的，字段多（含 Media 切片），
|
||||
// 重建容易漏字段导致"裁剪后条目信息变空"。
|
||||
func (s *scope) filterTree(t *sdk.KnowledgeTreeView) {
|
||||
if t == nil || s == nil || len(s.paths) == 0 {
|
||||
return
|
||||
}
|
||||
// 根节点恒可见（否则调用方连"有什么可看的"都不知道）
|
||||
kept := t.Children[:0]
|
||||
for i := range t.Children {
|
||||
c := &t.Children[i]
|
||||
if !s.allows(c.Path) {
|
||||
continue
|
||||
}
|
||||
kept = append(kept, *c)
|
||||
}
|
||||
t.Children = kept
|
||||
// 根下直接挂载的条目：范围非空时不可见（allows("") == false）
|
||||
// 根下直接挂载的条目：范围非空时不可见（allows("") == false）。
|
||||
// 只在**本节点自己**这么做，不能对子树也做 —— 子树节点自己挂的条目
|
||||
// 属于该分类，在范围内，必须保留（我第一版无差别清空，
|
||||
// 结果整棵树只剩空壳节点：item_count 全 0，条目名一个都不剩）。
|
||||
if s.allows(t.Path) {
|
||||
// 保留本节点的条目
|
||||
} else {
|
||||
t.Items = nil
|
||||
t.ItemCount = 0
|
||||
}
|
||||
t.TotalCount = t.ItemCount
|
||||
for i := range t.Children {
|
||||
s.filterTree(&t.Children[i])
|
||||
t.TotalCount += t.Children[i].TotalCount
|
||||
}
|
||||
}
|
||||
|
||||
// filterNames 过滤分类路径列表。
|
||||
func (s *scope) filterNames(names []string) []string {
|
||||
if s == nil || len(s.paths) == 0 {
|
||||
return names
|
||||
}
|
||||
out := make([]string, 0, len(names))
|
||||
for _, n := range names {
|
||||
if s.allows(n) {
|
||||
out = append(out, n)
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// filterCounts 过滤分类计数，并按范围重算 total。
|
||||
func (s *scope) filterCounts(counts []sdk.KnowledgeCategoryCount) ([]sdk.KnowledgeCategoryCount, int) {
|
||||
if s == nil || len(s.paths) == 0 {
|
||||
return counts, totalLeafCount(counts)
|
||||
}
|
||||
out := make([]sdk.KnowledgeCategoryCount, 0, len(counts))
|
||||
for _, c := range counts {
|
||||
if s.allows(c.Category) {
|
||||
out = append(out, c)
|
||||
}
|
||||
}
|
||||
return out, totalLeafCount(out)
|
||||
}
|
||||
|
||||
// totalLeafCount 只数叶子分类，避免中间层重复计数（与未过滤时的口径一致）。
|
||||
func totalLeafCount(counts []sdk.KnowledgeCategoryCount) int {
|
||||
total := 0
|
||||
for _, c := range counts {
|
||||
if !isParentCategory(counts, c.Category) {
|
||||
total += c.Count
|
||||
}
|
||||
}
|
||||
return total
|
||||
}
|
||||
@ -13,7 +13,7 @@ func (k *knowledgeImpl) Search(query string, topK int) ([]*Knowledge, error) {
|
||||
got := k.ks.Search(query, topK)
|
||||
out := make([]*Knowledge, len(got))
|
||||
for i, item := range got {
|
||||
out[i] = &Knowledge{Name: item.Name, Content: item.Content}
|
||||
out[i] = &Knowledge{Name: item.Name, Content: item.Content, Category: item.Category}
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
@ -32,7 +32,7 @@ func (k *knowledgeImpl) SearchIn(query, category string, topK int) ([]*Knowledge
|
||||
got := k.ks.SearchIn(query, category, topK)
|
||||
out := make([]*Knowledge, len(got))
|
||||
for i, item := range got {
|
||||
out[i] = &Knowledge{Name: item.Name, Content: item.Content}
|
||||
out[i] = &Knowledge{Name: item.Name, Content: item.Content, Category: item.Category}
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
12
third_party/homeagent-sdk/sdk/knowledge.go
vendored
12
third_party/homeagent-sdk/sdk/knowledge.go
vendored
@ -9,6 +9,14 @@ type KnowledgeAPI interface {
|
||||
|
||||
// Knowledge represents a knowledge entry.
|
||||
type Knowledge struct {
|
||||
Name string `json:"name"`
|
||||
Content string `json:"content"`
|
||||
Name string `json:"name"`
|
||||
// Category 是该条目的父分类路径（如 "tech/go"），根下条目为空。
|
||||
//
|
||||
// 为何加这个字段：对外服务（kbtree）要做**暴露范围过滤**就必须知道
|
||||
// 每条结果属于哪个分类 —— 过滤只能发生在服务端（客户端过滤等于
|
||||
// 没过滤，范围外内容已经随响应发出去了）。
|
||||
// 之前这里只有 Name/Content，内核明明返回了 Category 却在
|
||||
// knowledge_impl.SearchIn 的拷贝里丢掉，导致外部无法按分类判定。
|
||||
Category string `json:"category,omitempty"`
|
||||
Content string `json:"content"`
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user