feat: plugin apply wiring with credential-backed client and skill registration

Author: clark-fc

packages/tool-bailian-kb/skills/bailian-kb-management/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: bailian-kb-management
+description: 管理阿里云百炼知识库（建库、上传文档、部署检索服务、Chunk 运维）。当用户要创建/更新/删除知识库、上传或导入文档、部署检索服务、管理数据中心文件时使用 kscli。检索与问答不走本 skill——用原生工具 kb_search / kb_chat。
+---
+
+# 百炼知识库管理（kscli）
+
+检索面与管理面的分工：**查知识用 `kb_search`（取证据）/ `kb_chat`（成品问答）原生工具；本 skill 只覆盖管理长尾**——知识库全生命周期、文档、检索服务、Chunk、数据中心。
+
+## 前置检查
+
+1. `kscli --version` —— 未安装则运行 `npm install -g knowledge-studio-cli`（需 Node.js ≥ 18.17）；安装失败时把错误原样报告给用户，不要静默跳过。
+2. 鉴权：需要 `DASHSCOPE_API_KEY`（环境变量，或 `kscli config set --key api_key --value sk-xxx`）。
+3. workspace 解析优先级：`--workspace-id` 参数 > 环境变量 `BAILIAN_WORKSPACE_ID` > `kscli config set --key workspace_id --value ws-xxx`。
+
+## 常用工作流：建库到可检索
+
+```bash
+kscli kb create --name "my-kb" --embedding-model text-embedding-v3   # 1. 建库
+kscli doc upload --kb-id <kb-id> --file ./docs.pdf                    # 2. 上传本地文档
+kscli doc status --kb-id <kb-id> --doc-id <doc-id>                    # 3. 轮询至 COMPLETED
+kscli service create ... && kscli service deploy ...                  # 4. 建/部署检索服务 → 得到 agent_id
+```
+
+部署完成后用 `kb_service_list` 确认服务可见，再用 `kb_search` 带该 `agent_id` 验证检索。
+
+## 命令组速查
+
+`kb`（list/info/create/update/delete/stats）· `doc`（list/upload/status/delete/tag/import-oss）· `service`（list/get/create/update/deploy/delete/copy）· `chunk`（add/list/update/delete）· `file` / `collection` / `category`（数据中心）。全部命令支持 `--output json`（结构化输出）、`--dry-run`（预览请求）、`--quiet`。完整手册：https://github.com/modelstudioai/cli/blob/main/docs/knowledge-cli-guide.md
+
+## 最佳实践
+
+- 用户反复使用同一检索服务时，建议其把 agent_id 写入项目指令（如 AGENTS.md）或让 agent 记住，后续 kb_search / kb_chat 直接携带。
+- 服务有 draft/deployed 两种状态：只有 deployed 可被默认版本调用；draft 调试用 `--agent-version beta`。

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

@@ -4,7 +4,12 @@
  * @module dsh-tool-bailian-kb
  */
 
+import type { Context } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import { KbClient } from './client.js'
+import { registerSkill } from './skill.js'
+import { createKbTools } from './tools.js'
 
 export const name = 'tool-bailian-kb'
 export const inject = ['tools', 'credentials']
@@ -31,3 +36,35 @@ export const Config: z<Config> = z.object({
   agentVersion: z.string(),
   chatTimeoutMs: z.number().default(300_000),
 })
+
+/**
+ * Register the three knowledge tools over one shared client, plus the
+ * management skill when a skills registry is composed.
+ * @param ctx - registrant context carrying tools and credentials.
+ * @param config - deployment's workspace, host, pinning, and timeout choices.
+ */
+export function apply(ctx: Context, config: Config): void {
+  const client = new KbClient({
+    workspaceId: config.workspaceId,
+    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).',
+        )
+      }
+      return resolved.value
+    },
+  })
+  for (const tool of createKbTools({
+    client,
+    ...(config.defaultAgentId ? { defaultAgentId: config.defaultAgentId } : {}),
+    chatTimeoutMs: config.chatTimeoutMs,
+  })) {
+    ctx.tools.register(tool)
+  }
+  registerSkill(ctx)
+}

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

@@ -0,0 +1,30 @@
+/** Runtime skill registration: the packaged kscli-management SKILL.md joins the catalog when a skills registry is composed. */
+
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Context } from '@deepseek-ai/cordis'
+// Type-only: resolves ctx.skills for the optional inject below.
+import type {} from '@deepseek-ai/dsh-skill'
+
+const SKILL_DIR = fileURLToPath(new URL('../skills/bailian-kb-management/', import.meta.url))
+
+/**
+ * Register the management skill when the skills registry is composed; headless
+ * assemblies without the seam stay unaffected.
+ * @param ctx - the plugin context.
+ */
+export function registerSkill(ctx: Context): void {
+  ctx.inject(['skills'], (skillCtx) => {
+    const content = readFileSync(join(SKILL_DIR, 'SKILL.md'), 'utf8')
+    skillCtx.skills.register({
+      name: 'bailian-kb-management',
+      description:
+        'Manage Bailian knowledge bases with the kscli CLI: create/update KBs, upload documents, deploy '
+        + 'retrieval services, and maintain chunks. Retrieval itself uses the native kb_search/kb_chat tools.',
+      content,
+      source: 'bundled',
+      resourceBase: { kind: 'directory', path: SKILL_DIR },
+    })
+  })
+}