What is this?
bailian-kb-dsh is a plugin (and dsh bundle) that gives a DeepSeek Harness agent access to knowledge bases hosted on Aliyun Model Studio (Bailian). It registers two model-facing tools — kb_search for raw evidence and kb_chat for grounded answers — and ships a settings page plus a management skill for the bl CLI.
Retrieval happens through retrieval services you deploy on Bailian: a service binds one or more knowledge bases to an embedding/rerank configuration and is addressed by its agent_id. The plugin keeps the list of deployed services in front of the model, so it can decide whether the question is answerable from your knowledge at all.
Features
- Two model-facing tools —
kb_search returns scored chunks with source references; kb_chat returns a complete grounded answer
- Service awareness — the workspace's deployed retrieval services are injected into the conversation, so the model knows what it can look up instead of guessing service ids
- Low-friction setup — sign in to the Bailian console from the settings page to fill in the API key and workspace id; an existing
bl CLI login is adopted automatically
- Settings page — a "Bailian KB" section in the web UI for credentials, default services, and service-cache inspection
- Management skill — bundled
bailian-kb skill teaching the agent the bl CLI workflow for creating knowledge bases, ingesting documents, and deploying services
Requirements
- DeepSeek Harness with its plugin runtime (
@deepseek-ai/dsh-*), Node.js >= 22.12
- An Aliyun Model Studio account: a workspace id and a DashScope API key (get one)
- At least one deployed retrieval or Q&A service in that workspace — create one in the console or with
bl knowledge service create / bl knowledge service deploy
- The
bl CLI (npm install -g bailian-cli) for anything on the management side — creating knowledge bases, ingesting documents, deploying services. Retrieval itself calls the API directly and never shells out, so kb_search / kb_chat work without it
Installation
dsh plugin --profile web add bailian-kb-dsh
The CLI adds the bundle to the profile's layer stack; no manual YAML editing required. To remove it:
dsh plugin --profile web remove bailian-kb-dsh
Verify the plugin is composed — dsh --profile web --dump-config should list a tool-bailian-kb row.
Configuration
Option 1 — Settings page (recommended)
After installation, Settings → Bailian KB appears in the web UI:
- Fetch from console login — opens the Bailian console in a browser on the host machine; when you finish signing in, the API key and workspace id of that account are stored on the host (the key never travels to the browser). Each login requests a freshly issued key, so switching accounts is one click.
- API key — write-only: the stored value is never echoed back, only reported as configured or not.
- Workspace id / default retrieval service / default Q&A service — editable with echo; the service ids can be picked from the cached service list. Clearing a value falls back to the layers below.
- Retrieval service cache — shows when the injected service list was last fetched, how many services it holds, and offers a manual refresh for a service you just created.
If you have already run bl auth login, the API key and workspace id are adopted once from ~/.bailian/config.json at startup. A value you deliberately clear is never re-filled.
Option 2 — Environment and credential files
# ~/.dsh/.env, or the credential store at ~/.dsh/.credentials.yaml
DASHSCOPE_API_KEY=sk-xxx # required
BAILIAN_WORKSPACE_ID=ws-xxx # required
BAILIAN_DEFAULT_RETRIEVE_AGENT_ID=aid-xxx # optional
BAILIAN_DEFAULT_CHAT_AGENT_ID=aid-xxx # optional
Option 3 — Profile patch
The bundle inserts its own entry into the profile; you can override it by id in ~/.dsh/cordis.patch.yml or the profile's patch file. An override replaces the whole config object (no deep merge):
- id: tool-bailian-kb
config:
defaultRetrieveAgentId: aid-search-service
defaultChatAgentId: aid-chat-service
chatTimeoutMs: 600000
Disable the plugin with - id: tool-bailian-kb plus disabled: true.
Config fields
The config doubles as the bailian-kb settings section, so edits in the settings page or settings document apply to the next call without a restart.
| Field | Type | Default | Meaning |
|---|
workspaceId | string? | — | Bailian workspace id; the API host is the workspace subdomain https://<workspaceId>.<endpointHost> |
endpointHost | string | cn-beijing.maas.aliyuncs.com | Host suffix; replace for another region or a private deployment |
defaultRetrieveAgentId | string? | — | Service kb_search falls back to when the caller omits agent_id |
defaultChatAgentId | string? | — | Service kb_chat falls back to when the caller omits agent_id |
agentVersion | string? | — | beta (draft) or a published version number; defaults to the latest published version. Not exposed to the model |
chatTimeoutMs | number | 300000 | kb_chat timeout — the server side is a minutes-scale agentic loop |
Resolution order
| Value | Settings layer (settings page) | Entry config (profile patch) | Credential store / env |
|---|
DASHSCOPE_API_KEY | write-only control | — | DASHSCOPE_API_KEY |
| workspace id | ✅ workspaceId | ✅ workspaceId | BAILIAN_WORKSPACE_ID |
| default retrieval service | ✅ defaultRetrieveAgentId | ✅ defaultRetrieveAgentId | BAILIAN_DEFAULT_RETRIEVE_AGENT_ID |
| default Q&A service | ✅ defaultChatAgentId | ✅ defaultChatAgentId | BAILIAN_DEFAULT_CHAT_AGENT_ID |
Every value is re-read per call, so a rotated key or a switched workspace takes effect immediately. The API key and workspace id are mandatory: without them the tools fail with a message pointing at these configuration paths. Default services are optional — when the workspace has exactly one deployed service for a scene, that one is used.
Tools
| Tool | Parameters | Returns |
|---|
kb_search | query, agent_id (required), top_k? (default 5, applied client-side), images? (image URLs for multimodal) | Scored chunks with source references, plus a total |
kb_chat | message, agent_id (required) | The complete answer plus a request_id |
agent_id is required in both schemas: the schema cannot tell the model whether this deployment pins a default, and discovering a missing default at call time wastes a round-trip. The configured default is still honoured for programmatic calls that omit it.
The list of deployed services — id, name, and scene — is injected into the conversation as a context message, refreshed periodically and whenever a bl knowledge service command changes the inventory. Long lists are truncated with the total stated, so the model never mistakes a partial list for the full inventory.
Errors
- HTTP 4xx — most often an
agent_id that no longer exists, so the service list is refreshed and appended to the error message for immediate recovery
- HTTP 5xx — passed through unchanged
- Missing credentials — the message names the configuration paths (
~/.dsh/.env, ~/.dsh/.credentials.yaml, the settings page) and links to the console key page
kb_chat timeout — the message explains the server-side multi-turn retrieval and suggests retrying or switching to kb_search
Known limitations
kb_chat buffers the server stream, so there is no progress output while it runs.top_k is a client-side cut: the request body carries no such parameter, and how many chunks the server returns is decided by the service configuration.- Service names carry the routing signal. The service list API does not return a description field yet, so the model judges what a service covers from its name alone. Name your services after their content (
Product docs retrieval, not Service 1).
- At most two pages per scene are fetched; beyond that the injected list is marked as truncated.
Development
pnpm --filter bailian-kb-dsh run build # tsc → dist/ (node half) + tsdown → dist/web/client.js (browser half)
pnpm --filter bailian-kb-dsh run typecheck # node and web tsconfigs
pnpm --filter bailian-kb-dsh run test
For local integration, add the working copy to a dev profile (the patch file is watched by HMR):
dsh plugin --profile dev add <this-repo>/packages/bailian-kb-dsh
Internal design notes — context injection strategy, service cache layout, refresh triggers — live in docs/kb-dsh/runtime-behavior.md; the maintenance checklist is docs/agents/dsh-plugin.md.
Contributing
Bug reports, feature requests, and PRs are welcome. See CONTRIBUTING.md for developer setup and the contribution workflow.
License
Apache 2.0
