From eb8b0892d62ad4b2a254e31efef737cbbe95ffe3 Mon Sep 17 00:00:00 2001 From: "zeyu.fz" Date: Mon, 24 Aug 2026 15:51:16 +0800 Subject: [PATCH] =?UTF-8?q?docs(bailian-kb-dsh):=20=E4=BC=98=E5=8C=96=20RE?= =?UTF-8?q?ADME=20=E6=96=87=E6=A1=A3=E5=8F=8A=E6=8A=80=E8=83=BD=E8=AF=B4?= =?UTF-8?q?=E6=98=8E=E7=9A=84=E8=A1=A8=E8=BF=B0=E5=86=85=E5=AE=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 修正缓存管理中对 API key 和自动获取按钮的描述，更加准确表述工作区权限限制 - 更新缓存存储字段说明，明确 pipeline_list 字段不稳定，无法用作知识库标签 - 简化执行期无进展显示的描述，去除过度复杂说明 - 明确 top_k 参数为客户端截断，强调服务端返回记录数由检索服务配置决定 - 细化服务画像质量依赖服务名的说明，配合后端描述字段补齐做对应改动准备 - 微调技能最佳实践中关于服务命名指导的表述，强调无语义名称导致检索无法路由 - 说明后端描述字段补齐后，服务描述字段可自动生效，提升文档明确性 --- packages/bailian-kb-dsh/README.md | 8 ++++---- packages/bailian-kb-dsh/skills/bailian-kb/SKILL.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/bailian-kb-dsh/README.md b/packages/bailian-kb-dsh/README.md index e957c30..c3cde7e 100644 --- a/packages/bailian-kb-dsh/README.md +++ b/packages/bailian-kb-dsh/README.md @@ -135,9 +135,9 @@ Config 同时注册为 `bailian-kb` settings namespace（`installSettingsSection ### 缓存与刷新 -落点：`${DSH_HOME:-~/.dsh}/cache/bailian-kb/services-.json`（临时文件 + `rename()` 原子发布，目录 `0o700`）。按 workspace 分文件是必需的：api key 只能访问自己的 workspace（交叉组合返回 `Endpoint.AccessDenied`），而"自动获取"按钮就是为了切账号。 +落点：`${DSH_HOME:-~/.dsh}/cache/bailian-kb/services-.json`（临时文件 + `rename()` 原子发布，目录 `0o700`）。按 workspace 分文件是必需的：api key 只能访问自己的 workspace，而"自动获取"按钮就是为了切账号。 -存：`agent_id` / `agent_name` / `scene` / `status` / `modify_time`，预留 `description`（待后端补齐）。**不存 `pipeline_list`**——实测它常缺 `pipeline_name`、有时整个为空，做不了知识库标签。 +存：`agent_id` / `agent_name` / `scene` / `status` / `modify_time`，预留 `description`（待列表接口返回）。**不存 `pipeline_list`**——它不稳定携带 `pipeline_name`，做不了知识库标签。 | 刷新触发点 | 模型何时看见 | | --------------------------------------------------------- | ------------------------------------ | @@ -163,7 +163,7 @@ Config 同时注册为 `bailian-kb` settings namespace（`installSettingsSection ## Known Limitations -- kb_chat 执行期无进展显示（缓冲式；进展会话事件设计见仓库根 README 与 spec 附录 A）。 +- kb_chat 执行期无进展显示（缓冲式）。 - `top_k` 是客户端截断：请求体不含该参数，服务端返回条数由检索服务配置决定，截断只影响进入模型上下文的量。 -- **服务画像的质量上限取决于服务名**：`service list` 接口当前不返回描述字段，所以模型只能靠 `agent_name` 判断一个服务能查什么。名字模糊的部署引导能力接近于零。后端补齐描述字段后只需改三处（`api-types` 补字段名 → `services.ts` 解析 → `buildServiceCatalog` 追加并截断到 200 字符），缓存已预留 `description` 键，无需迁移。 +- **服务画像的质量上限取决于服务名**：`service list` 接口当前不返回描述字段，所以模型只能靠 `agent_name` 判断一个服务能查什么。名字模糊的部署引导能力接近于零。列表接口补齐描述字段后只需改三处（`api-types` 补字段名 → `services.ts` 解析 → `buildServiceCatalog` 追加并截断到 200 字符），缓存已预留 `description` 键，无需迁移。 - 拉取每个 scene 最多 2 页，超出时标 `truncated` 并在清单里告知。 diff --git a/packages/bailian-kb-dsh/skills/bailian-kb/SKILL.md b/packages/bailian-kb-dsh/skills/bailian-kb/SKILL.md index e7aca62..91e7ef5 100644 --- a/packages/bailian-kb-dsh/skills/bailian-kb/SKILL.md +++ b/packages/bailian-kb-dsh/skills/bailian-kb/SKILL.md @@ -89,7 +89,7 @@ bl knowledge service list --scene search --status deployed # 5. ## 最佳实践 -- **建服务时必须把名字写清楚**：`service create --name` 的名称是模型判断"这个服务能查什么"的主要依据（服务描述暂未随列表接口返回）。`检索服务1`、`test-0819` 这类名字会让后续检索无法路由；写成 `产品文档检索`、`HR制度问答` 这种能看出覆盖内容的名字。同时填 `--description`（≤1000 字符），后端补齐列表字段后即可自动生效。 +- **建服务时必须把名字写清楚**：`service create --name` 的名称是模型判断"这个服务能查什么"的主要依据（服务描述暂未随列表接口返回）。`检索服务1` 这类无语义的名字会让后续检索无法路由；写成 `产品文档检索`、`HR制度问答` 这种能看出覆盖内容的名字。同时填 `--description`（≤1000 字符），列表接口返回该字段后即可自动生效。 - 服务有 draft/deployed 两种状态：只有 deployed 可被默认版本调用，也只有 deployed 会进入模型看到的服务清单；draft 调试用 `--agent-version beta`。改已发布版本的配置：先改 beta 草稿（`service update`），验证后 `service deploy` 发新版本。 - 导入类命令（`knowledge create`、`doc upload --index-id`、`doc status`）优先带 `--wait` 轮询到终态，避免手工轮询；文档解析失败（如 PARSE_FAILED）会以非零退出码透传错误。 - `chunk add` 有 10 QPS 限流，批量脚本注意节流；响应不带 chunk id，需要 `chunk list` 反查。