chore(deps): 更新 TypeScript 类型检查脚本及依赖锁定文件

- 修改 package.json 中 typecheck 脚本，新增对 tsconfig.web.json 的检查
- 更新 pnpm-lock.yaml 文件，增加多个依赖项和绑定包的版本信息及平台支持
- 新增 react、lightningcss 等多种平台及架构的预编译绑定库
- 添加多种类型定义依赖，提升类型覆盖范围
- 升级部分工具包及插件版本，优化构建和开发体验

Author: clark-fc

package.json

@@ -5,7 +5,7 @@
   "scripts": {
     "build": "pnpm -r run build",
     "test": "vitest run",
-    "typecheck": "tsc -b packages/tool-bailian-kb"
+    "typecheck": "tsc -b packages/tool-bailian-kb && tsc -p packages/tool-bailian-kb/tsconfig.web.json"
   },
   "devDependencies": {
     "typescript": "^5.7.2",

packages/bundle/README.md

@@ -1,6 +1,6 @@
 # bailian-kb-dsh（分发包）
 
-dsh bundle 分发面：`package.json` 的 `dsh.bundle.patch` 声明 + [`cordis.patch.yml`](cordis.patch.yml)，向 profile 插入 `tool-bailian-kb` row。
+dsh bundle 分发面：`package.json` 的 `dsh.bundle.patch` 声明 + [`cordis.patch.yml`](cordis.patch.yml)，向 profile 插入 `tool-bailian-kb` row，并随包分发浏览器端配置卡片（`dsh.client` → `lib/client.js`）。
 
 ## Patch row
 
@@ -12,25 +12,53 @@ dsh bundle 分发面：`package.json` 的 `dsh.bundle.patch` 声明 + [`cordis.p
         workspaceId: !!js process.env.BAILIAN_WORKSPACE_ID
 ```
 
-`workspaceId` 默认从环境变量读取（`~/.dsh/.env` 写 `BAILIAN_WORKSPACE_ID=ws-xxx` 即可运行）；未设置时插件加载期 fail loud。
+`workspaceId` 只是解析链的一层，不是唯一来源：config 显式值（含此环境变量读取）per-call 优先；未设置时回退到 `BAILIAN_WORKSPACE_ID` credential。同样回退覆盖 `defaultAgentId`（`BAILIAN_DEFAULT_AGENT_ID`）与 API key（`DASHSCOPE_API_KEY`）。
+
+## 三个值的解析链
+
+| 值 | 1️⃣ config 显式值（本 patch 或用户覆盖） | 2️⃣ credential（UI 卡片 / `~/.dsh/.credentials.yaml`） | 3️⃣ 都缺失时 |
+|---|---|---|---|
+| `DASHSCOPE_API_KEY` | —（无 config 面） | ✅ | 工具调用报错并引导配置 |
+| `BAILIAN_WORKSPACE_ID` | `workspaceId` | ✅ | 工具调用报错并引导配置 |
+| `BAILIAN_DEFAULT_AGENT_ID` | `defaultAgentId` | ✅ | `agent_id` 参数变必填（schema 恒 optional，运行时校验） |
+
+行为参数（`endpointHost`/`agentVersion`/`chatTimeoutMs`）只在 config 层，见 [tool-bailian-kb README](../tool-bailian-kb/README.md)。
+
+## Web UI 配置卡片
+
+装进 profile 后，Settings → Plugins 出现“百炼知识库”卡片，可配置三个 credential（写 `~/.dsh/.credentials.yaml`）：
+
+- **DashScope API Key** — write-only，`type=password` 遮罩输入草稿
+- **Bailian Workspace ID** — 明文（便于粘贴核对 workspace id）
+- **默认服务 ID（agent_id）** — 明文，附独立“清除”按钮（留空保存 = 不写，清除须显式 unset）
+
+值永不回显：字段始终空白起步，仅显示 configured/来自环境变量 徽标；来自 shell export 或 `~/.dsh/.env` 的值只读（继承环境层），输入框禁用。
 
 ## 用户覆盖
 
-用户 patch 层在本 bundle 之上，按 id 覆盖时**替换整个 config（无 deep-merge），必须连 workspaceId 一起重述**：
+用户 patch 层在本 bundle 之上，按 id 覆盖时**替换整个 config（无 deep-merge）**。`workspaceId`/`defaultAgentId` 均为可选，只需重述想显式固定的字段：
 
 ```yaml
 # ~/.dsh/cordis.patch.yml 或 profile 的 cordis.patch.yml
 - id: tool-bailian-kb
   config:
-    workspaceId: ws-xxx
-    defaultAgentId: aid-customer-service   # 场景固定式部署
+    defaultAgentId: aid-customer-service   # 场景固定式部署；省略 workspaceId 走 credential
     chatTimeoutMs: 600000
 ```
 
 禁用：`- id: tool-bailian-kb` + `disabled: true`。
 
+## 安装（本地 checkout 链接）
+
+bundle 是 `dsh.bundle` 声明层，真正的插件包 `dsh-tool-bailian-kb` 是它的依赖；`link:` 安装不携带传递依赖，**两个包都要 add**（第二个无 bundle 声明，dsh 会以 plain dependency 装入，CLI 的 warning 即预期行为）：
+
+```sh
+dsh plugin --profile web add /path/to/bailian-kb-dsh/packages/bundle
+dsh plugin --profile web add /path/to/bailian-kb-dsh/packages/tool-bailian-kb
+```
+
 ## 卸载
 
 ```sh
-dsh plugin --profile <name> remove bailian-kb-dsh
+dsh plugin --profile <name> remove bailian-kb-dsh dsh-tool-bailian-kb
 ```

packages/bundle/cordis.patch.yml

@@ -1,7 +1,9 @@
 # bailian-kb-dsh: inserts the Bailian knowledge-base consumer over dsh-base.
-# workspaceId reads BAILIAN_WORKSPACE_ID from the environment (~/.dsh/.env) so a
-# user patch is only needed to pin defaultAgentId or override the host/timeout.
-# An id-targeted user patch replaces this whole config: restate workspaceId too.
+# workspaceId here is one resolution layer, not the only one: a config value
+# (this env read included) wins per call; when it is unset the plugin resolves
+# the BAILIAN_WORKSPACE_ID credential instead (web UI card or
+# ~/.dsh/.credentials.yaml). The same fallback covers defaultAgentId via
+# BAILIAN_DEFAULT_AGENT_ID, and the API key via DASHSCOPE_API_KEY.
 
 - insert:
     - id: tool-bailian-kb

packages/tool-bailian-kb/package.json

@@ -7,23 +7,55 @@
   "types": "lib/index.d.ts",
   "exports": {
     ".": { "types": "./lib/index.d.ts", "default": "./lib/index.js" },
+    "./client": { "default": "./lib/web/client.js" },
     "./package.json": "./package.json"
   },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-api-remotes",
+        "@deepseek-ai/dsh-client-ui-settings-plugins"
+      ],
+      "platform": "web"
+    }
+  },
   "files": ["lib", "skills"],
-  "scripts": { "build": "tsc -b" },
+  "scripts": { "build": "tsc -b && tsdown" },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-tools": "*",
     "@deepseek-ai/dsh-credentials": "*",
     "@deepseek-ai/dsh-skill": "*",
-    "@deepseek-ai/schemastery": "^3.18.1"
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/dsh-api-remotes": "*",
+    "@deepseek-ai/dsh-client-connection": "*",
+    "@deepseek-ai/dsh-client-locale": "*",
+    "@deepseek-ai/dsh-client-runtime": "*",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "*",
+    "@deepseek-ai/dsh-client-ui-primitives": "*",
+    "@deepseek-ai/dsh-client-ui-slots": "*",
+    "react": "^18.2.0"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "link:../../../deepseek-harness/vendor/cordis",
     "@deepseek-ai/dsh-tools": "link:../../../deepseek-harness/packages/core/tools",
     "@deepseek-ai/dsh-credentials": "link:../../../deepseek-harness/packages/credentials/credentials",
     "@deepseek-ai/dsh-skill": "link:../../../deepseek-harness/packages/skill/skill",
     "@deepseek-ai/schemastery": "link:../../../deepseek-harness/vendor/schemastery",
-    "@types/node": "^22.0.0"
+    "@deepseek-ai/dsh-api-remotes": "link:../../../deepseek-harness/packages/api/remotes",
+    "@deepseek-ai/dsh-client-connection": "link:../../../deepseek-harness/packages/client/connection",
+    "@deepseek-ai/dsh-client-locale": "link:../../../deepseek-harness/packages/client/locale",
+    "@deepseek-ai/dsh-client-runtime": "link:../../../deepseek-harness/packages/client/runtime",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "link:../../../deepseek-harness/packages/client/ui-settings-plugins",
+    "@deepseek-ai/dsh-client-ui-primitives": "link:../../../deepseek-harness/packages/client/ui-primitives",
+    "@deepseek-ai/dsh-client-ui-slots": "link:../../../deepseek-harness/packages/client/ui-slots",
+    "@types/node": "^22.0.0",
+    "@types/react": "~18.3.1",
+    "lightningcss": "^1.32.0",
+    "react": "^18.2.0",
+    "tsdown": "^0.22.2"
   }
 }

packages/tool-bailian-kb/src/client.ts

@@ -14,7 +14,8 @@ export class KbApiError extends Error {
 }
 
 export interface KbClientOptions {
-  workspaceId: string
+  /** Resolves the current workspace id per call (patch config or credential); throws with guidance when unconfigured. */
+  resolveWorkspaceId: () => Promise<string>
   endpointHost: string
   /** Service version forwarded on search/chat when set (deployment debug choice). */
   agentVersion?: string
@@ -33,9 +34,9 @@ export class KbClient {
   }
 
   private async post(path: string, body: unknown, accept: string, signal?: AbortSignal): Promise<Response> {
-    const apiKey = await this.opts.resolveApiKey()
+    const [apiKey, workspaceId] = await Promise.all([this.opts.resolveApiKey(), this.opts.resolveWorkspaceId()])
     const fetchImpl = this.opts.fetchImpl ?? fetch
-    const url = kbEndpoint(this.opts.endpointHost, this.opts.workspaceId, path)
+    const url = kbEndpoint(this.opts.endpointHost, workspaceId, path)
     const res = await fetchImpl(url, {
       method: 'POST',
       headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json', 'Accept': accept },

packages/tool-bailian-kb/src/index.ts

@@ -16,21 +16,21 @@ export const inject = ['tools', 'credentials']
 
 /** Bailian knowledge-base plugin configuration. */
 export interface Config {
-  /** Bailian workspace id; the API host is the workspace subdomain `https://<workspaceId>.<endpointHost>`. */
-  workspaceId: string
+  /** Bailian workspace id; the API host is the workspace subdomain `https://<workspaceId>.<endpointHost>`. Optional here: an unset value falls back per call to the BAILIAN_WORKSPACE_ID credential (Settings → Plugins card or ~/.dsh/.credentials.yaml). */
+  workspaceId?: string
   /** API host suffix; replace for other regions or private deployments. */
   endpointHost: string
-  /** Retrieval-service id pinned by this deployment; when set, the tools' agent_id parameter becomes optional. */
+  /** Retrieval-service id pinned by this deployment; when unset, the per-call fallback reads the BAILIAN_DEFAULT_AGENT_ID credential. */
   defaultAgentId?: string
   /** Service version to call: `beta` (draft) or a published number; defaults to the latest published version. Never model-visible. */
   agentVersion?: string
   /** kb_chat timeout in milliseconds; the server side is a minutes-scale agentic loop. */
   chatTimeoutMs: number
 }
 
-/** Schemastery validation for {@link Config}; a missing workspaceId fails at load. */
+/** Schemastery validation for {@link Config}; workspaceId and defaultAgentId are optional — both resolve per call with a credentials fallback. */
 export const Config: z<Config> = z.object({
-  workspaceId: z.string().required(),
+  workspaceId: z.string(),
   endpointHost: z.string().default('cn-beijing.maas.aliyuncs.com'),
   defaultAgentId: z.string(),
   agentVersion: z.string(),
@@ -44,24 +44,42 @@ export const Config: z<Config> = z.object({
  * @param config - deployment's workspace, host, pinning, and timeout choices.
  */
 export function apply(ctx: Context, config: Config): void {
+  const pinnedWorkspaceId = config.workspaceId
+  const pinnedAgentId = config.defaultAgentId
   const client = new KbClient({
-    workspaceId: config.workspaceId,
+    resolveWorkspaceId: pinnedWorkspaceId === undefined
+      ? async () => {
+          const resolved = await ctx.credentials.resolve(credentialRef('BAILIAN_WORKSPACE_ID'))
+          if (!resolved) {
+            throw new Error(
+              'BAILIAN_WORKSPACE_ID is not configured. Set it in the web UI (Settings → Plugins → Bailian knowledge base) '
+              + 'or in ~/.dsh/.credentials.yaml; the workspace id appears as the subdomain of your Bailian endpoints.',
+            )
+          }
+          return resolved.value
+        }
+      : async () => pinnedWorkspaceId,
     endpointHost: config.endpointHost,
     ...(config.agentVersion ? { agentVersion: config.agentVersion } : {}),
     resolveApiKey: async () => {
       const resolved = await ctx.credentials.resolve(credentialRef('DASHSCOPE_API_KEY'))
       if (!resolved) {
         throw new Error(
-          'DASHSCOPE_API_KEY is not configured. Set it in ~/.dsh/.env or .credentials.yaml '
-          + '(create a key at https://bailian.console.aliyun.com/?tab=app#/api-key).',
+          'DASHSCOPE_API_KEY is not configured. Set it in the web UI (Settings → Plugins → Bailian knowledge base) '
+          + 'or in ~/.dsh/.credentials.yaml (create a key at https://bailian.console.aliyun.com/?tab=app#/api-key).',
         )
       }
       return resolved.value
     },
   })
   for (const tool of createKbTools({
     client,
-    ...(config.defaultAgentId ? { defaultAgentId: config.defaultAgentId } : {}),
+    resolveDefaultAgentId: pinnedAgentId !== undefined
+      ? async () => pinnedAgentId
+      : async () => {
+          const resolved = await ctx.credentials.resolve(credentialRef('BAILIAN_DEFAULT_AGENT_ID'))
+          return resolved?.value
+        },
     chatTimeoutMs: config.chatTimeoutMs,
   })) {
     ctx.tools.register(tool)

packages/tool-bailian-kb/src/tools.ts

@@ -1,6 +1,9 @@
 /**
- * The three model-facing knowledge tools. Schemas are static per deployment: a configured
- * defaultAgentId downgrades agent_id to optional at build time (never a runtime fallback chain).
+ * The three model-facing knowledge tools. agent_id stays optional in the schema
+ * regardless of deployment: the default service (patch config or credential)
+ * can change at runtime through the credentials domain, so the fallback runs
+ * per call and a missing default surfaces as an executable error instead of a
+ * load-time schema difference.
  */
 
 import { defineTool } from '@deepseek-ai/dsh-tools'
@@ -15,7 +18,8 @@ const DEFAULT_TOP_K = 5
 
 export interface KbToolDeps {
   client: KbClient
-  defaultAgentId?: string
+  /** Resolves the default agent id per call (patch config or credential); omitted means no default. */
+  resolveDefaultAgentId?: () => Promise<string | undefined>
   chatTimeoutMs: number
 }
 
@@ -49,18 +53,18 @@ async function withServiceHint(client: KbClient, err: unknown): Promise<never> {
  * @returns definitions ready for `ctx.tools.register()`.
  */
 export function createKbTools(deps: KbToolDeps) {
-  const { client, defaultAgentId, chatTimeoutMs } = deps
+  const { client, resolveDefaultAgentId, chatTimeoutMs } = deps
   const agentIdParam = {
     type: 'string' as const,
-    ...(defaultAgentId === undefined ? { required: true as const } : {}),
-    description: defaultAgentId === undefined
-      ? 'Retrieval/Q&A service id (find one via kb_service_list).'
-      : 'Retrieval/Q&A service id; omit to use this deployment\'s default service.',
+    description: 'Retrieval/Q&A service id; omit to use the default service when this deployment configures one (find ids via kb_service_list).',
   }
-  const resolveAgentId = (supplied: string | undefined): string => {
-    const agentId = supplied ?? defaultAgentId
-    if (agentId === undefined) throw new Error('agent_id is required: discover services with kb_service_list')
-    return agentId
+  const resolveAgentId = async (supplied: string | undefined): Promise<string> => {
+    if (supplied !== undefined) return supplied
+    const defaultId = resolveDefaultAgentId === undefined ? undefined : await resolveDefaultAgentId()
+    if (defaultId === undefined) {
+      throw new Error('agent_id is required: no default service is configured; discover services with kb_service_list')
+    }
+    return defaultId
   }
 
   const serviceList = defineTool({
@@ -163,7 +167,7 @@ export function createKbTools(deps: KbToolDeps) {
       const topK = args.top_k ?? DEFAULT_TOP_K
       const body: SearchRequest = {
         query: args.query,
-        agent_id: resolveAgentId(args.agent_id),
+        agent_id: await resolveAgentId(args.agent_id),
         ...(client.agentVersion ? { agent_version: client.agentVersion } : {}),
         ...(args.images && args.images.length > 0 ? { images: args.images } : {}),
       }
@@ -210,7 +214,7 @@ export function createKbTools(deps: KbToolDeps) {
       const body = {
         input: { messages: [{ role: 'user' as const, content: args.message }] },
         parameters: { agent_options: {
-          agent_id: resolveAgentId(args.agent_id),
+          agent_id: await resolveAgentId(args.agent_id),
           ...(client.agentVersion ? { agent_version: client.agentVersion } : {}),
         } },
         stream: true as const,