|
|
78806efa0f
|
fix(kbtree): 修客户端脚本三处实测暴露的缺陷
都是本机装好后逐条跑命令发现的，不是设想：
1. **token 找不到**：脚本找 `scripts/../config.json`，而实际文件在
`<skill>/config/config.json`。症状极具迷惑性——「明明配了 token 却说
没找到」。改为两种布局都试，并在注释里写明为什么不能只写一种。
2. **`-h` 也要 token**：帮助段排在 token 检查之后，`kb_tree.sh -h` 会被
拦下报「未找到访问令牌」。把 help 提到最前。
3. **`-q` 被当成命令名**：`kb_tree.sh -q 并发`（不给子命令）报
「未知命令: -q」，而这是很自然的写法。改为：第一个参数是选项时不取作
子命令，解析完选项后再定——有 -q 走 search，没有走 tree。
另外把 curl -f 换成 -w + 自行判状态码：-f 在 4xx 时只吐一行
`curl: (22) 404`，把响应体丢掉，而 404 响应体里恰是「现有分类」清单，
是排查时最需要的。现在 401/404 都会给出可行动的中文提示，
退出码 0/2/3/4/5/7/8 各有语义。
|
2026-09-26 14:47:32 +08:00 |
|
|
|
5a889007d7
|
docs(kbtree): 补客户端封装脚本 + 本机部署交接说明
SKILL.md 里原本只有 curl 示例，agent 用起来要自己拼 URL 与鉴权头。
补 scripts/kb_tree.sh（照 dify-ops 的做法把脚本随 skill 分发）：
- 子命令 tree/categories/counts/search，选项 -q/-c/-d/-i/-l
- token 读取顺序：KB_TOKEN 环境变量 → config/config.json。
**故意不接受命令行传 token**（会进 shell 历史与 ps 输出）
- 预检端口：不通时直接说明「服务未上线」并给出上线步骤，
而不是抛 curl: (7) Connection refused 让用户自己猜
- 错误翻译成人话：401 → 令牌无效；404 → 附上服务端返回的现有分类
（用 curl -w 而非 -f，否则 404 响应体里最有用的那份清单会被丢掉）
- 退出码：0 成功 / 2 参数 / 3 令牌 / 4 分类不存在 / 5 HTTP / 7 连不上 / 8 请求失败
DEPLOY.md 是给部署方的交接单：本机 kbtree 代码已合入 main 且 skill/token
已就位，但**运行中的二进制里没有 kbtree**（14:35 有人换过一版二进制），
故替换与重启留给部署方。含备份/替换/验证步骤、回滚方式、端口与 token 说明。
token 与 config.json **不入库**（config/ 目录留空），安装时由部署方从
配置库 config_kbtree 表读取后写入本机。
|
2026-09-26 14:43:46 +08:00 |
|
|
|
41d754334e
|
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 树浏览（前端真正用起来，而非留一个没人调的端点）
面板加可折叠的分类树：逐级点选即把搜索范围切到该子树（原先是让人
手打分类名）。当前范围有可见标签与「全库」复位。
|
2026-09-26 14:20:19 +08:00 |
|
