docs: package and repository READMEs

Author: clark-fc

README.md

@@ -0,0 +1,50 @@
+# bailian-kb-bundle
+
+阿里云百炼知识库能力的 [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) 插件 bundle：三个 API 直连模型工具（`kb_service_list` / `kb_search` / `kb_chat`）+ kscli 管理面 skill。
+
+设计文档：deepseek-harness 工作区 `docs/superpowers/specs/2026-08-15-bailian-kb-bundle-design.md`。
+
+## 仓库结构
+
+| 包 | 职责 |
+|---|---|
+| [`packages/tool-bailian-kb`](packages/tool-bailian-kb/README.md) | 插件本体：Config、KbClient、三个工具、随包打包的管理 skill |
+| [`packages/bundle`](packages/bundle/README.md) | 分发面：`dsh.bundle` 声明 + `cordis.patch.yml` |
+
+## 安装（dsh 用户）
+
+```sh
+dsh plugin --profile web add bailian-kb-bundle   # npm 发布后；本地开发用绝对/相对路径
+```
+
+安装后 CLI 自动把 bundle 加入 profile 的层栈，无需手改 YAML。
+
+配置写入 `~/.dsh/.env`：
+
+```sh
+BAILIAN_WORKSPACE_ID=ws-xxx        # 必填：百炼工作空间 id
+DASHSCOPE_API_KEY=sk-xxx           # 必填：也可放 ~/.dsh/.credentials.yaml
+```
+
+验证：`dsh --profile web --dump-config` 应能看到 `tool-bailian-kb` row。缺 `BAILIAN_WORKSPACE_ID` 时加载期直接报错（fail loud），不会静默跳过。
+
+卸载：`dsh plugin --profile web remove bailian-kb-bundle`。
+
+## 开发
+
+依赖 dsh 的运行时包（`@deepseek-ai/dsh-tools` 等）以 peerDependencies 声明、由 dsh 安装闭包在运行时提供；开发期通过 `link:` 指向同级的 `../deepseek-harness` checkout（npm registry 尚未发布完整 dsh 闭包）。
+
+```sh
+pnpm install
+pnpm run test        # vitest 单元测试
+pnpm run typecheck
+pnpm run build       # tsc 产出 lib/
+```
+
+本地联调：`dsh plugin --profile dev add <本仓库>/packages/bundle`，patch 文件受 HMR 监听。
+
+## Known Limitations
+
+- **无 keyless snapshot / e2e 基建**：首版以单元测试 + 手动集成验收覆盖；snapshot/e2e 依赖 dsh snapshot harness 对 out-of-tree bundle 的支持情况，v0.2 跟进。
+- **kb_chat 执行期无进展显示**：服务端是分钟级 agentic loop，UI 只有 pending → 完成两态；进展会话事件 + Web 渲染器的设计见 spec 附录 A，等真实使用反馈再排期。
+- **服务清单单 scene 上限 100 条**：超出部分靠 `name_filter` 收窄（结果带 truncated 提示）。

packages/bundle/README.md

@@ -0,0 +1,36 @@
+# bailian-kb-bundle（分发包）
+
+dsh bundle 分发面：`package.json` 的 `dsh.bundle.patch` 声明 + [`cordis.patch.yml`](cordis.patch.yml)，向 profile 插入 `tool-bailian-kb` row。
+
+## Patch row
+
+```yaml
+- insert:
+    - id: tool-bailian-kb
+      name: dsh-tool-bailian-kb
+      config:
+        workspaceId: !!js process.env.BAILIAN_WORKSPACE_ID
+```
+
+`workspaceId` 默认从环境变量读取（`~/.dsh/.env` 写 `BAILIAN_WORKSPACE_ID=ws-xxx` 即可运行）；未设置时插件加载期 fail loud。
+
+## 用户覆盖
+
+用户 patch 层在本 bundle 之上，按 id 覆盖时**替换整个 config（无 deep-merge），必须连 workspaceId 一起重述**：
+
+```yaml
+# ~/.dsh/cordis.patch.yml 或 profile 的 cordis.patch.yml
+- id: tool-bailian-kb
+  config:
+    workspaceId: ws-xxx
+    defaultAgentId: aid-customer-service   # 场景固定式部署
+    chatTimeoutMs: 600000
+```
+
+禁用：`- id: tool-bailian-kb` + `disabled: true`。
+
+## 卸载
+
+```sh
+dsh plugin --profile <name> remove bailian-kb-bundle
+```

packages/tool-bailian-kb/README.md

@@ -0,0 +1,39 @@
+# dsh-tool-bailian-kb
+
+百炼知识库的 dsh 插件本体：在 `ctx.tools` 注册三个模型工具，并在 skills 服务可用时注册管理面 skill。
+
+## Config
+
+| 字段 | 类型 | 默认 | 语义 |
+|---|---|---|---|
+| `workspaceId` | string | **必填** | 百炼工作空间 id；API host 为 workspace 子域名 `https://<workspaceId>.<endpointHost>` |
+| `endpointHost` | string | `cn-beijing.maas.aliyuncs.com` | host 后缀，其他 region/私有化时替换 |
+| `defaultAgentId` | string? | — | 场景固定式部署绑定的检索服务；**配置后 `agent_id` 参数在注册期变为可选**（加载期静态决定 schema，非运行时 fallback） |
+| `agentVersion` | string? | — | `beta`（草稿调试）或已发布版本号；不暴露给模型 |
+| `chatTimeoutMs` | number | 300000 | kb_chat 超时；服务端是分钟级 agentic loop |
+
+凭证：`DASHSCOPE_API_KEY` 走 `ctx.credentials` 引用，每次调用重新解析（热更换生效），未配置时报错并附获取指引。
+
+## 工具
+
+| 工具 | 参数 | 返回 |
+|---|---|---|
+| `kb_service_list` | `scene?`（chat\|search，省略查双场景合并）、`name_filter?` | 服务清单（agent_id、名称、scene、status、绑定知识库）+ total + truncated；分页内部消化（单 scene 100 条上限） |
+| `kb_search` | `query`、`agent_id`（见 defaultAgentId）、`top_k?`（默认 5，**客户端截断**——服务端无此参数）、`images?` | chunks（text/score/来源）+ total |
+| `kb_chat` | `message`、`agent_id` | 完整答案（内部消费 SSE 流缓冲返回）+ request_id |
+
+## 错误语义
+
+- 4xx（除 401/403）：错误信息**附当前服务清单**，模型可一步纠正无效 `agent_id`；
+- 凭证缺失：指向 `~/.dsh/.env` / `.credentials.yaml` 配置方式与控制台取 key 页面；
+- chat 超时：说明服务端多轮检索特性，建议重试或改用 `kb_search`；
+- 服务端错误体截断至 500 字符进入错误信息（优先 `code: message`）。
+
+## 管理面 skill
+
+`skills/bailian-kb-management/SKILL.md` 随包分发，插件通过 `ctx.inject(['skills'])` 在 skills 服务可用时以 `source: 'bundled'` 运行时注册；无 skills 服务的组合（headless 最小装配）不受影响。内容：kscli 安装/鉴权/workspace 解析、建库→上传→部署工作流、agent_id 固定最佳实践。
+
+## Known Limitations
+
+- kb_chat 执行期无进展显示（缓冲式；进展会话事件设计见仓库根 README 与 spec 附录 A）。
+- `top_k` 是客户端截断：请求体不含该参数，服务端返回条数由检索服务配置决定，截断只影响进入模型上下文的量。