chore(release): prepare 1.22.0

Feat/managed agent ci 添加managed agents模块的ci能力

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -39,7 +39,7 @@ body:
     attributes:
       label: Node version
       description: "Output of node --version"
-      placeholder: "v22.12.0"
+      placeholder: "v18.17.0"
     validations:
       required: true
 

.github/workflows/publish-skills.yml

@@ -0,0 +1,27 @@
+# Poke the FC publish-skills flow after skills/ changes land.
+# The FC side reconciles this repo's skills/ directory against OSS
+# (bailian-wiki/skills/) using the repo HEAD snapshot as the only
+# source of truth — the request itself carries no content. Both the
+# repo and branch params are validated against FC-side whitelists
+# (PUBLISH_REPOS / PUBLISH_BRANCHES).
+#
+# feat/cli-skill-sync is temporary for end-to-end testing; remove it
+# (here and from the FC PUBLISH_BRANCHES whitelist) once the sync
+# link is verified on main.
+name: Publish skills to OSS
+
+on:
+  push:
+    branches:
+      - main
+      - feat/cli-skill-sync
+    paths:
+      - "skills/**"
+
+jobs:
+  poke:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger FC publish-skills
+        run: |
+          curl -sf -X POST "${{ vars.FC_TRIGGER_URL }}/publish-skills?repo=modelstudioai/cli&branch=${{ github.ref_name }}"

.github/workflows/publish.yml

@@ -10,6 +10,7 @@ on:
         options:
           - bailian-cli
           - knowledge-studio-cli
+          - bailian-kb-dsh
       mode:
         description: "Publish mode"
         required: true
@@ -18,7 +19,7 @@ on:
           - channel
           - stable
       channel:
-        description: "dist-tag (channel mode only, e.g. mcp/plugin/advisor)"
+        description: "Required when mode=channel. npm dist-tag only (lowercase, digits, dashes), e.g. mcp / plugin / sync-release. bailian-cli binary CDN always overwrites sync-release.json; knowledge-studio-cli and bailian-kb-dsh are npm-only."
         required: false
         type: string
 
@@ -28,12 +29,12 @@ concurrency:
 
 jobs:
   publish-stable:
-    if: inputs.mode == 'stable'
-    name: publish stable (${{ inputs.package }}) to npm + tag
+    if: inputs.mode == 'stable' && inputs.package != 'bailian-kb-dsh'
+    name: publish stable (${{ inputs.package }}) to npm + binary + tag
     runs-on: ubuntu-latest
     environment: production # Required Reviewers gate
     permissions:
-      contents: write # push lightweight tag to origin
+      contents: write # push tag + create GitHub Release with binary assets
       id-token: write # OIDC for npm Trusted Publishing + provenance
     steps:
       - uses: actions/checkout@v6
@@ -55,19 +56,112 @@ jobs:
             | sudo tar -xz -C /usr/local/bin gitleaks
           gitleaks version
 
+      - name: Ensure zip (per-platform binary archives)
+        run: sudo apt-get update && sudo apt-get install -y zip
+
       - run: pnpm install --frozen-lockfile
 
+      # Binary compile uses `bun build --compile` CLI (not Bun.build API).
+      # Keep this pin in sync with any local smoke tests of binary-compile.mjs.
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.2.19"
+
       - name: publish-stable
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # OSS release channel runs fully in CI: upload + reconcile + manifest.json.
+          # All values come from repo Settings → Secrets — no OSS defaults live in
+          # code. Leave AK/SK unset to skip the OSS channel; once enabled,
+          # bucket/region/prefix are required.
+          BAILIAN_OSS_AK: ${{ secrets.BAILIAN_OSS_AK }}
+          BAILIAN_OSS_SK: ${{ secrets.BAILIAN_OSS_SK }}
+          BAILIAN_OSS_BUCKET: ${{ secrets.BAILIAN_OSS_BUCKET }}
+          BAILIAN_OSS_REGION: ${{ secrets.BAILIAN_OSS_REGION }}
+          BAILIAN_OSS_ENDPOINT: ${{ secrets.BAILIAN_OSS_ENDPOINT }}
+          BAILIAN_RELEASE_PREFIX: ${{ secrets.BAILIAN_RELEASE_PREFIX }}
+          BAILIAN_STATIC_PREFIX: ${{ secrets.BAILIAN_STATIC_PREFIX }}
         run: node tools/release/publish-stable.mjs ${{ inputs.package == 'knowledge-studio-cli' && '--knowledge' || '' }}
 
   publish-channel:
-    if: inputs.mode == 'channel'
-    name: publish channel (${{ inputs.package }}) to npm
+    if: inputs.mode == 'channel' && inputs.package != 'bailian-kb-dsh'
+    name: publish channel (${{ inputs.package }}) to npm + binary
     runs-on: ubuntu-latest
     permissions:
-      contents: read # no tag, no Release; just publish
+      contents: write # create prerelease GitHub Release with binary assets
       id-token: write # OIDC for npm Trusted Publishing + provenance
     steps:
+      - name: Require channel input
+        if: ${{ inputs.channel == '' }}
+        run: |
+          echo "::error::mode=channel requires the workflow input \"channel\" (npm dist-tag, e.g. mcp / plugin / sync-release). Leave mode=stable if you do not need a dist-tag."
+          exit 1
+
+      - uses: actions/checkout@v6
+
+      - uses: pnpm/action-setup@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: pnpm
+          registry-url: "https://registry.npmjs.org/"
+
+      - name: Install gitleaks
+        run: |
+          set -euo pipefail
+          GITLEAKS_VERSION=8.21.2
+          curl -sSfL \
+            "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" \
+            | sudo tar -xz -C /usr/local/bin gitleaks
+          gitleaks version
+
+      - name: Ensure zip (per-platform binary archives)
+        run: sudo apt-get update && sudo apt-get install -y zip
+
+      - run: pnpm install --frozen-lockfile
+
+      # Binary compile uses `bun build --compile` CLI (not Bun.build API).
+      # Keep this pin in sync with any local smoke tests of binary-compile.mjs.
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.2.19"
+
+      - name: publish-channel
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # OSS release channel — same Settings-injected values as stable.
+          BAILIAN_OSS_AK: ${{ secrets.BAILIAN_OSS_AK }}
+          BAILIAN_OSS_SK: ${{ secrets.BAILIAN_OSS_SK }}
+          BAILIAN_OSS_BUCKET: ${{ secrets.BAILIAN_OSS_BUCKET }}
+          BAILIAN_OSS_REGION: ${{ secrets.BAILIAN_OSS_REGION }}
+          BAILIAN_OSS_ENDPOINT: ${{ secrets.BAILIAN_OSS_ENDPOINT }}
+          BAILIAN_RELEASE_PREFIX: ${{ secrets.BAILIAN_RELEASE_PREFIX }}
+          BAILIAN_STATIC_PREFIX: ${{ secrets.BAILIAN_STATIC_PREFIX }}
+        run: node tools/release/publish-channel.mjs ${{ inputs.package == 'knowledge-studio-cli' && '--knowledge' || '' }} --channel "${{ inputs.channel }}"
+
+  # bailian-kb-dsh is the dsh plugin (downstream host adapter): independent version,
+  # tsc + tsdown build, npm-only. It shares this workflow's entry UI and setup steps
+  # but NOT publish-stable.mjs / publish-channel.mjs — those broadcast one version
+  # across the locked bl package set and produce binary artifacts, neither of which
+  # applies here. See docs/agents/dsh-plugin.md.
+  publish-kb-dsh:
+    if: inputs.package == 'bailian-kb-dsh'
+    name: publish ${{ inputs.mode }} (bailian-kb-dsh) to npm
+    runs-on: ubuntu-latest
+    # stable goes through the Required Reviewers gate, same as the bl stable job;
+    # channel stays ungated so dist-tag drops need no approval.
+    environment: ${{ inputs.mode == 'stable' && 'production' || '' }}
+    permissions:
+      contents: write # push the bailian-kb-dsh-v<version> tag (stable only)
+      id-token: write # OIDC for npm Trusted Publishing + provenance
+    steps:
+      - name: Require channel input
+        if: ${{ inputs.mode == 'channel' && inputs.channel == '' }}
+        run: |
+          echo "::error::mode=channel requires the workflow input \"channel\" (npm dist-tag, e.g. mcp / plugin). Leave mode=stable if you do not need a dist-tag."
+          exit 1
+
       - uses: actions/checkout@v6
 
       - uses: pnpm/action-setup@v6
@@ -89,5 +183,5 @@ jobs:
 
       - run: pnpm install --frozen-lockfile
 
-      - name: publish-channel
-        run: node tools/release/publish-channel.mjs ${{ inputs.package == 'knowledge-studio-cli' && '--knowledge' || '' }} --channel "${{ inputs.channel }}"
+      - name: publish-kb-dsh
+        run: node tools/release/publish-kb-dsh.mjs ${{ inputs.mode == 'channel' && format('--channel "{0}"', inputs.channel) || '' }}

.gitignore

@@ -10,9 +10,11 @@ lerna-debug.log*
 # Dependencies & build output
 node_modules
 dist
+dist-bin
 dist-ssr
 tools/generated
 .node-version
+*.tsbuildinfo
 
 *.local
 
@@ -36,7 +38,9 @@ tools/generated
 .claude/settings.local.json
 .claude/scheduled_tasks.lock
 .cursor/
+.qoder/
 .qwen/
+.qoder
 .playwright-mcp/
 .pnpm-store/
 
@@ -46,3 +50,6 @@ packages/cli/scene/**/outputs/
 
 # Environment variables (sensitive data)
 .env
+
+# Local scratch / plan drafts (never commit)
+.scratch/

.vite-hooks/pre-commit

@@ -5,6 +5,16 @@ set -eu
 pnpm run sync:skill-assets
 
 # Stage generator output so it is included in this commit.
-git add skills/bailian-cli/reference skills/bailian-cli/SKILL.md
+git add \
+  skills/bailian-protocol/SKILL.md \
+  skills/bailian-cli/SKILL.md \
+  skills/bailian-cli/reference \
+  skills/bailian-gen/SKILL.md \
+  skills/bailian-gen/reference \
+  skills/bailian-finetune/SKILL.md \
+  skills/bailian-finetune/reference \
+  skills/bailian-managed-agent/SKILL.md \
+  skills/bailian-managed-agent/reference \
+  skills/bailian-web-search/SKILL.md
 
 vp staged

AGENTS.md

@@ -11,6 +11,7 @@ monorepo 现在按"纯逻辑 → 运行时框架 → 命令库 → 产品入口"
 - `packages/commands` — `bailian-cli-commands`,可复用命令实现库,只导出 command,不决定产品路径
 - `packages/cli` — `bailian-cli`,完整 `bl` 产品入口;`src/commands.ts` 组装 `bl` 暴露的命令路径
 - `packages/kscli` — `knowledge-studio-cli`,Knowledge Studio 专用入口;`src/main.ts` 复用 commands 并重映射为 `kscli` 路径
+- `packages/bailian-kb-dsh` — `bailian-kb-dsh`,**下游宿主适配层**(依赖方向朝外):百炼知识库的 DeepSeek Harness (dsh) 插件,消费 `bl` CLI 与知识库 API,不在上面这条分层链上;版本、构建、发布都独立,见 [docs/agents/dsh-plugin.md](docs/agents/dsh-plugin.md)
 
 ### 关键文件
 
@@ -35,7 +36,7 @@ packages/core/src/auth/            # apiKey / console credential 解析与落盘
 packages/core/src/client/          # HTTP client / endpoints / console gateway
 ```
 
-Skill / 命令手册随 `skills/bailian-cli/` 经 `npx skills add modelstudioai/cli` 安装。`tools/generate-reference.ts` 从 **`packages/cli/src/commands.ts`** 生成 `skills/bailian-cli/reference/`(纳入 git);`tools/sync-skill-metadata.ts` 从 `packages/cli/package.json` 同步 `skills/bailian-cli/SKILL.md` 的 `metadata.version`。两者由根脚本 `pnpm run sync:skill-assets` 和 `.vite-hooks/pre-commit` 执行。
+Skill / 命令手册随 `skills/bailian-*/` 经 `bl skill init` 安装（装齐 registry 中全部 `bailian-*`，含共享协议 `bailian-protocol`）。业务 skill（`bailian-cli` / `bailian-gen` / `bailian-finetune` / `bailian-managed-agent` / `bailian-web-search`）执行前读 `skills/bailian-protocol/`；不要依赖 frontmatter `companions`（安装器不强制）。`tools/generate-reference.ts` 从 **`packages/cli/src/commands.ts`** 按一级命令归属表分流写入各 `skills/<skill>/reference/`(纳入 git);`tools/sync-skill-metadata.ts` 从 `packages/cli/package.json` 同步各 `skills/*/SKILL.md` 的 `metadata.version`。两者由根脚本 `pnpm run sync:skill-assets` 和 `.vite-hooks/pre-commit` 执行。hub `bailian-cli` 的路由表不复述领域命令明细；SKILL 文案 / 安装约定 / hand-off 见 [docs/agents/skill-change.md](docs/agents/skill-change.md)。
 
 约定:
 
@@ -48,30 +49,34 @@ Skill / 命令手册随 `skills/bailian-cli/` 经 `npx skills add modelstudioai/
 非代码资产:
 
 - `tools/release/` — 发版自动化（CI 驱动,见 `.github/workflows/publish.yml`）
-- `tools/generate-reference.ts` — 从 `packages/cli/src/commands.ts` 生成 `skills/bailian-cli/reference/`
-- `tools/sync-skill-metadata.ts` — 同步 `skills/bailian-cli/SKILL.md` 的 `metadata.version`
+- `tools/generate-reference.ts` — 从 `packages/cli/src/commands.ts` 按归属表生成各 `skills/<skill>/reference/`
+- `tools/sync-skill-metadata.ts` — 同步各 `skills/*/SKILL.md` 的 `metadata.version`（含 `bailian-protocol`）
 - `README.md` / `README.zh.md` — npm 和 GitHub 主页
 
 ## 业务场景索引
 
 按当前任务从下表挑一条进入对应文档:
 
-| 场景           | 何时进入                                     | 详见                                                                         |
-| -------------- | -------------------------------------------- | ---------------------------------------------------------------------------- |
-| 命令增删改     | 增加 / 删除 / 重命名 `bl xxx` 或入口命令路径 | [docs/agents/command-add-remove.md](docs/agents/command-add-remove.md)       |
-| E2E 测试维护   | 新增/改命令或 e2e 用例、补 help/缺参/dry-run | [docs/agents/cli-e2e-tests.md](docs/agents/cli-e2e-tests.md)                 |
-| 批量压测       | 改/跑多能力并发压测、`test:stress`、fixtures | [docs/agents/stress-batch-tests.md](docs/agents/stress-batch-tests.md)       |
-| 选项变更       | 给已有命令加 `--flag` 或改默认值             | [docs/agents/command-flag-change.md](docs/agents/command-flag-change.md)     |
-| 模型上下架     | 增加新模型 / 改默认模型 / 废弃旧模型         | [docs/agents/model-add-remove.md](docs/agents/model-add-remove.md)           |
-| 错误文案变更   | 改 `BailianError` 的 message 或 hint         | [docs/agents/error-hint-change.md](docs/agents/error-hint-change.md)         |
-| URL / 渠道变更 | 控制台域名 / 文档站 / 追踪参数               | [docs/agents/url-change.md](docs/agents/url-change.md)                       |
-| 鉴权扩展       | 加 OAuth / SSO / 换 token 来源               | [docs/agents/auth-change.md](docs/agents/auth-change.md)                     |
-| 配置项扩展     | 新 env var 或 `~/.bailian/config.json` 字段  | [docs/agents/config-add.md](docs/agents/config-add.md)                       |
-| Profile / 激活 | 改命名 Profile、预设或 `active_config`       | [docs/agents/config-profile-change.md](docs/agents/config-profile-change.md) |
-| 发布           | channel / stable 发布到 npm（CI 驱动）       | [docs/agents/publish.md](docs/agents/publish.md)                             |
-| Change Log     | 发版说明 / 历史版本说明                      | [docs/agents/changelog-write.md](docs/agents/changelog-write.md)             |
-| 工具链调整     | lint 规则 / 构建配置 / 依赖升级              | [docs/agents/lint-toolchain.md](docs/agents/lint-toolchain.md)               |
-| Command Pack   | 扩展包 / 白名单 / plugin 管理命令            | [docs/agents/command-pack.md](docs/agents/command-pack.md)                   |
+| 场景              | 何时进入                                         | 详见                                                                         |
+| ----------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- |
+| 命令增删改        | 增加 / 删除 / 重命名 `bl xxx` 或入口命令路径     | [docs/agents/command-add-remove.md](docs/agents/command-add-remove.md)       |
+| E2E 测试维护      | 新增/改命令或 e2e 用例、补 help/缺参/dry-run     | [docs/agents/cli-e2e-tests.md](docs/agents/cli-e2e-tests.md)                 |
+| 批量压测          | 改/跑多能力并发压测、`test:stress`、fixtures     | [docs/agents/stress-batch-tests.md](docs/agents/stress-batch-tests.md)       |
+| 选项变更          | 给已有命令加 `--flag` 或改默认值                 | [docs/agents/command-flag-change.md](docs/agents/command-flag-change.md)     |
+| 模型上下架        | 增加新模型 / 改默认模型 / 废弃旧模型             | [docs/agents/model-add-remove.md](docs/agents/model-add-remove.md)           |
+| Skill 文案 / 路由 | 改 SKILL 路由、安装约定、hand-off、hub/领域边界  | [docs/agents/skill-change.md](docs/agents/skill-change.md)                   |
+| 错误文案变更      | 改 `BailianError` 的 message 或 hint             | [docs/agents/error-hint-change.md](docs/agents/error-hint-change.md)         |
+| URL / 渠道变更    | 控制台域名 / 文档站 / 追踪参数                   | [docs/agents/url-change.md](docs/agents/url-change.md)                       |
+| 埋点变更          | 改 AEM 命令事件、后端渠道 header、User-Agent     | [docs/agents/telemetry-change.md](docs/agents/telemetry-change.md)           |
+| 鉴权扩展          | 加 OAuth / SSO / 换 token 来源                   | [docs/agents/auth-change.md](docs/agents/auth-change.md)                     |
+| 配置项扩展        | 新 env var 或 `~/.bailian/config.json` 字段      | [docs/agents/config-add.md](docs/agents/config-add.md)                       |
+| Profile / 激活    | 改命名 Profile、预设或 `active_config`           | [docs/agents/config-profile-change.md](docs/agents/config-profile-change.md) |
+| 安装文档          | 改安装、鉴权、验证流程或线上 install 页面        | [docs/agents/install-doc-change.md](docs/agents/install-doc-change.md)       |
+| 发布              | channel / stable 发布到 npm（CI 驱动）           | [docs/agents/publish.md](docs/agents/publish.md)                             |
+| Change Log        | 发版说明 / 历史版本说明                          | [docs/agents/changelog-write.md](docs/agents/changelog-write.md)             |
+| 工具链调整        | lint 规则 / 构建配置 / 依赖升级                  | [docs/agents/lint-toolchain.md](docs/agents/lint-toolchain.md)               |
+| Command Pack      | 扩展包 / 白名单 / plugin 管理命令                | [docs/agents/command-pack.md](docs/agents/command-pack.md)                   |
+| dsh 插件          | 改 `packages/bailian-kb-dsh`、dsh 依赖、插件发布 | [docs/agents/dsh-plugin.md](docs/agents/dsh-plugin.md)                       |
 
 如果当前任务无法对应任何场景,先按经验完成,然后**回来评估这是不是一类新场景** —— 是就新增 `docs/agents/<scenario>.md`,把清单沉淀下来。
 
@@ -81,12 +86,15 @@ Skill / 命令手册随 `skills/bailian-cli/` 经 `npx skills add modelstudioai/
 
 源码包的 `version` 当前保持一致: `packages/core`、`packages/runtime`、`packages/commands`、`packages/cli`、`packages/kscli`。做版本 bump 时一动多动。release 工具当前强校验 / 发布范围以 `tools/release/lib/packages.mjs` 为准;把新包纳入发布前必须同步该清单和 [publish.md](docs/agents/publish.md)。
 
+**例外**: `packages/bailian-kb-dsh` 不参与这个锁步(独立 `0.1.x`,跟随 dsh rc 节奏),也不在 release 白名单里;它走 `publish.yml` 里 `package=bailian-kb-dsh` 的独立 job(`tools/release/publish-kb-dsh.mjs`)。
+
 ### 2. 分层边界
 
 - `core` 是纯库:不依赖 `runtime` / `commands` / 产品入口;不调 `process.exit`;新增/改动时不硬编码 `bl` / `kscli` 命令名、控制台 URL 或渠道追踪参数。当前遗留项见 [error-hint-change.md](docs/agents/error-hint-change.md) 与 [url-change.md](docs/agents/url-change.md),触碰相关代码时顺手收敛
 - `runtime` 是通用 CLI 框架:可以处理 TTY、help、错误输出、middleware,但不写具体业务命令逻辑
 - `commands` 是命令实现库:不决定产品路径;不在 `usageArgs` / `exampleArgs` / hint 里硬编码产品 bin 前缀
 - `cli` / `kscli` 是产品层:负责命令路径 map、产品 identity、README、技能 reference、发版入口
+- `bailian-kb-dsh` 在这条链之外:它是别的宿主(dsh)里的插件,只允许依赖 `core`(且当前刻意零依赖),反过来 `core` / `runtime` / `commands` / 产品层**永远不许**依赖它
 - URL 集中在 `packages/runtime/src/urls.ts`(用户面控制台)和 `packages/core/src/config/schema.ts` / client 层(API)
 
 ### 3. 错误处理边界:CLI 不翻译服务端错误
@@ -119,6 +127,10 @@ CLI 只为「自己能权威解释的错误」发出语义化信号,服务端的
 
 例外: 仅当作用域极小(≤3 行)且语义从上下文完全明确时,可使用 `k`/`v`(Object.entries 的 key/value)。
 
+### 6. 用户可见 CLI 文案必须支持中英文
+
+新增或修改用户可见的 CLI 文案时必须同时提供 `en-US` / `zh-CN`;runtime 公共文案遵循同一规则,服务端错误仍按第 3 节原样透传。命令文案的具体检查项见 [command-add-remove.md](docs/agents/command-add-remove.md)。
+
 ## 完成改动后的快速验证
 
 ```sh

CHANGELOG.md

@@ -6,6 +6,331 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 [中文版](CHANGELOG.zh.md) · [README](README.md) · [Contributing](CONTRIBUTING.md)
 
+## [1.22.0] - 2026-09-08
+
+### Changed
+
+- **Project initialization** — `managed-agent project init` now creates `./managed-agent` by default. Use `--project .` to initialize in place. **(BREAKING)**
+- **Build confirmation** — `managed-agent project build` no longer requires confirmation and rejects `--yes`. Use `--dry-run` for a read-only preview; Publish still requires confirmation. **(BREAKING)**
+- **Managed Agent SDK** — upgrade to `0.7.1`. Build automatically associates active Agent-local resources while preserving explicit bindings, Skill versions, and File mount paths. Ambiguous Environment or Vault selections are rejected before writing.
+
+### Fixed
+
+- **Project diagnostics** — provide actionable project-root guidance and surface the underlying Build validation error.
+- **YAML initialization paths** — show the absolute YAML path in creation messages and existing-file errors.
+
+### Internal
+
+- Expand project initialization and Build regression coverage, and remove the obsolete Build confirmation flag from the local lifecycle E2E test.
+
+## [1.21.0] - 2026-09-07
+
+### Added
+
+- **Managed Agent directory projects** — initialize, validate, build, and publish local projects with Agent-scoped resource configuration and resource examples.
+- **Local project versions** — enable or disable snapshot versioning, list and preview history, and restore project files without Git.
+- **Project Workbench** — edit resources, review changes, publish updates, and manage local versions in a browser.
+
+### Changed
+
+- **Playground version resolution** — check npm before launch, reuse matching local versions, and fetch the latest version when needed; retain explicit version and binary overrides.
+- **Managed Agent SDK** — upgrade to `0.7.0` and consume project workspace and version services through SDK subpath exports.
+
+## [1.20.0] - 2026-09-03
+
+> Managed Agents now combines YAML-first infrastructure management with direct Bailian AgentStudio resource and runtime operations.
+
+### Added
+
+- **Managed Agent API commands** — added direct list, get, search, version, upload, download, run, pause, archive, event, and diagnostic operations for Agents, Environments, Skills, Vaults, Deployments, Sessions, and Files.
+- **Scoped YAML-backed resource creation** — `agent create`, `environment create`, `skill create`, `vault create`, `vault credential create`, and `deployment create` update `agents.yaml` and apply only the target resource without unrelated drift blocking the operation.
+- **Agent Skill attachment** — Agent creation supports existing custom or official Skill IDs as well as local Skill directories and ZIP archives.
+
+### Changed
+
+- **Bailian-only Managed Agent CLI** — `bl managed-agent` now targets the Bailian provider exclusively; provider-selection flags were removed and configurations containing other providers are rejected.
+- **Runtime mutation confirmation** — Deployment run/pause/unpause, Session archive/delete, and File delete operations require explicit high-risk confirmation.
+
+### Fixed
+
+- **Managed Agent error reporting** — Apply and scoped-create failures preserve the underlying provider diagnostic instead of ending with only `Apply failed.`.
+
+### Security
+
+- Credentials are resolved in memory and removed from the process environment; Vault credential declarations reference environment variables without persisting plaintext secrets.
+
+## [1.19.0] - 2026-09-01
+
+### Added
+
+- **`bl quota delete`** — clears all custom QPM/TPM rate limits for a model.
+
+### Changed
+
+- **High-risk operation confirmation** — high-risk commands show risk details in `--help` and Skill command references. Without `--yes`, the high-risk operation is not executed; JSON output returns exit code `7` with `error.type: "requires_confirmation"`. After confirmation, re-run with `--yes`; `--dry-run` does not require confirmation.
+
+## [1.18.2] - 2026-09-01
+
+### Changed
+
+- **Confirmation before deleting or clearing resources** — `bl finetune delete`, `bl deploy delete`, `bl dataset delete`, and `bl quota update --delete` now ask for confirmation; pass `--yes` for non-interactive use.
+
+### Fixed
+
+- **Skill installation reliability** — `bl skill init` now retries transient network failures, and completed Skill updates are no longer reported as failed when backup cleanup is blocked.
+
+## [1.18.1] - 2026-08-28
+
+### Removed
+
+- Removed API Key validation from `bl auth login`.
+
+## [1.18.0] - 2026-08-27
+
+### Added
+
+- **Automatic Profile API Key fallback** — unsupported commands use the API Key and endpoint from `default` without requiring a Profile switch; explicit credentials still take priority.
+- **Independent speech defaults** — Profiles support separate default models for TTS and ASR.
+- **Wan3.0 file-to-video** — `bl video generate --file` accepts local files or URLs and validates incompatible inputs.
+
+### Changed
+
+- **Wan3.0 is now the default video model** — regular API Key text, image, and reference video tasks default to `wan3.0-video`, with first/last-frame and reference-audio support. Token Plan defaults remain unchanged.
+- **Expanded Token Plan preset** — login adds speech defaults and missing capabilities while preserving existing user configuration.
+- **Improved speech and Skill installation experience** — streaming synthesis defaults to PCM; installation docs add a Node 18-compatible fallback and clarify the Node.js and Git prerequisites.
+
+## [1.17.1] - 2026-08-22
+
+### Fixed
+
+- **`knowledge create` now requires `--description`** — aligns with the server's required-description validation: the new `--description` flag is mandatory and its 1-500 character limit is checked locally before the request goes out. `bl knowledge create` / `kscli kb create` calls need to pass it.
+- **`knowledge service update` warned about config fields the server itself returned** — updating the draft config through scalar flags such as `--policy` reads the full draft and merges before writing back; the draft's `user_system_prompt`, `anti_leak_prompt`, `refusal_prompt`, `credibility_prompt`, `session_file_parse_mode`, and `enable_thinking` / `enable_temperature` / `enable_credibility` / `enable_max_completion_tokens` were not recognized by the CLI, so every update printed a run of `unknown agent_config field passed through` warnings. The config itself was always written correctly; the spurious warnings are gone.
+
+### Added
+
+- **`bailian-web-search` routing skill** — `bl skill init` now also installs a dedicated web-search routing skill, so agents pick the right search entry point instead of guessing.
+- **Knowledge Studio CLI command manual** — full `kscli` reference docs covering knowledge bases, documents, chunks, collections/categories, files, retrieval/Q&A services, and search/chat, with runnable examples for every command.
+
+### Changed
+
+- **Description flags explain what to write** — help text for the collection and service `--description` flags now states what the field is for (telling similar items apart in lists; for services, agents read it to pick the right one) rather than just repeating "required".
+- **`knowledge retrieve --rerank-model` documents its precondition** — help now states that the target knowledge base must already have a rerank model configured, otherwise every value is rejected.
+
+## [1.17.0] - 2026-08-18
+
+### Added
+
+- **Native Bailian Managed Agent Deployments** — `deployments` declared in `agents.yaml` now materialize as native AgentStudio resources, with server-side cron schedules, local file resource uploads, archival through `destroy`, and migration of legacy emulated state on the next `apply`.
+- **Bilingual CLI experience** — Set `language` to `en-US` or `zh-CN` through `bl config set` or Config UI to switch CLI Help, Quick Start, command examples, and Config UI between English and Chinese. The selected language follows the active config.
+
+### Fixed
+
+- **Free Tier Auto-Stop controls** — `bl usage freetier --off` can now disable Auto-Stop even when free quota remains; status rendering reflects the actual switch state, and filtered model queries avoid server-side batch-limit failures.
+
+## [1.16.0] - 2026-08-17
+
+> Full knowledge-base lifecycle management arrives in the CLI: create and configure knowledge bases, upload documents, tune chunks, and deploy retrieval/Q&A services — all from `bl knowledge` and `kscli`.
+
+### Added
+
+- **Knowledge base management** — `bl knowledge create` / `list` / `info` / `update` / `delete` manage knowledge bases end to end; `bl knowledge stats` reports document counts and usage over a past time range.
+- **Document management** — `bl knowledge doc upload` uploads local files or whole directories (recursive scan, skips unsupported formats and tool directories like `node_modules`); `doc list` / `status` / `tag` / `delete` cover the rest of the document lifecycle, and `doc import-oss` imports documents from OSS.
+- **Retrieval / Q&A service management** — `bl knowledge service list` / `get` / `create` / `update` / `deploy` / `delete` / `copy` manage retrieval and Q&A service configurations, including deploying a draft to a published version.
+- **Chunk management** — `bl knowledge chunk add` / `list` / `update` / `delete` inspect and fine-tune document chunks.
+- **Data-center management** — `bl knowledge category list` / `add` / `delete`, `bl knowledge file list` / `get` / `delete`, and `bl knowledge collection create` / `get` manage categories, raw files, and data collections.
+- **Service version selection for retrieval and chat** — `bl knowledge search` and `bl knowledge chat` accept `--agent-version` to call the beta (draft) config for debugging or a specific published version.
+- **`kscli` parity** — all new knowledge commands are also available in Knowledge Studio CLI under shorter paths, e.g. `kscli kb list`, `kscli doc upload`, `kscli service deploy`.
+
+### Removed
+
+- **`bl knowledge search --query-history` removed** — the parameter never took effect; use `bl knowledge chat` with `--message` history for multi-turn scenarios.
+
+### Internal
+
+- Requests now carry a static OpenAPI source identification header for backend channel attribution.
+- Added knowledge-base E2E suites, including five user-journey scenarios covering cold start, content ops, chunk tuning, service tuning, and the data plane.
+
+## [1.15.1] - 2026-08-17
+
+### Added
+
+- **Model permission management** — `bl permission list` shows per-model inference / fine-tune / deploy grants; `bl permission grant` and `bl permission revoke` manage them, with `--all` to one-key grant inference for every model in the workspace (including future ones).
+
+### Changed
+
+- **`bl quota request` renamed to `bl quota update`** — set per-model QPM/TPM via `--rpm`/`--tpm` and clear custom limits with the new `--delete`; omitted fields keep their current values, and the old `quota request` path keeps working as an alias.
+- **`bl quota list` reworked** — now reads the model-limits API and shows per-model and workspace-level request/usage limits plus async queue/concurrency limits in a single table.
+- **`bl model list` no longer requires Console login** — the model catalog and `--enrich` parameter-schema endpoints are public.
+- **`bl skill init` output simplified** — per-skill status is now `success`/`failed` (previously `installed`) with an aggregate `success`/`partial`/`failed` result; the `publishedAt` and `agents` fields were removed.
+
+## [1.15.0] - 2026-08-14
+
+### Added
+
+- **Responses API for `bl text chat`** — Use `--api responses` to call the DashScope Responses API with streaming, tool definitions, and structured JSON output; Chat Completions remains the default.
+- **Subscription plan usage views** — `bl usage token-plan` displays 5-hour and weekly quota usage, while `bl usage coding-plan` displays 5-hour, weekly, and monthly usage; both support text and JSON output.
+- **Authentication requirements in command help** — Help output now states whether a command requires an API Key, Console login, or Alibaba Cloud OpenAPI credentials.
+
+### Changed
+
+- **Broader speech-recognition model support** — `bl speech recognize` now routes asynchronous file-transcription and synchronous Flash ASR models to the appropriate DashScope APIs, with clear guidance for unsupported realtime models.
+- **MCP transport compatibility** — MCP commands now fall back from Streamable HTTP to classic SSE for compatible Bailian and custom endpoints.
+
+### Fixed
+
+- Binary updates now refresh installed Agent Skills after a successful CLI upgrade.
+- Fixed unavailable Token Plan quota values and missing reset times.
+- Fixed Qwen3 file-transcription result handling so waiting mode and `--out` work correctly.
+- Fixed MCP SSE chunk parsing, header timeouts, abort cleanup, and fallback status matching.
+- Network failures in JSON output now preserve the errno value in `cause.code`.
+
+## [1.14.3] - 2026-08-12
+
+### Fixed
+
+- **Free-tier quota compatibility** — `bl usage free` and `bl usage freetier` now use the current Bailian Commerce console APIs for quota queries, activation, and deactivation, with consistent asynchronous-task polling.
+
+## [1.14.2] - 2026-08-07
+
+### Added
+
+- **`bl skill init`** — Install all first-party `bailian-*` skills into detected local AI Agents in one step.
+
+### Changed
+
+- **Skill command interface** — Skill management commands now default to JSON output for Agent workflows; `bl skill add` and `bl skill update` use explicit `--all` and `--name` selectors.
+
+## [1.14.1] - 2026-08-05
+
+### Added
+
+- **Focused Bailian Skills** — `npx skills add modelstudioai/cli --all -g` now installs dedicated skills for media generation, fine-tuning, Managed Agent, and shared execution rules, improving task routing while reducing irrelevant context.
+
+### Changed
+
+- **Default image model upgraded to Qwen-Image 3.0** — image generation, image editing, pipelines, the config UI, and related documentation now default to `qwen-image-3.0` for API Key users.
+- **Broader coding-agent compatibility** — Skill installation and updates now detect more coding agents, preserve existing installation links, and automatically backfill skills into newly detected agents.
+
+## [1.14.0] - 2026-08-04
+
+### Added
+
+- **Standalone installation without Node.js** — binary packages are available for macOS on Apple Silicon and Intel, Linux x64, and Windows x64; npm installation remains supported.
+- **Exact-version updates** — binary and npm installations can use `bl update --to <version>` to update or switch to a specified version.
+
+### Changed
+
+- **Binary self-updates** — binary installations now check and download updates through a dedicated release channel. `bl update` no longer replaces the running executable, and the next invocation automatically uses the new version.
+
+## [1.13.1] - 2026-08-03
+
+### Changed
+
+- **Default text model upgraded to Qwen3.8-Max** — `bl text chat`, pipelines, API key validation, the config UI, and Managed Agent init templates now default to `qwen3.8-max`; Token Plan also moves from the preview model to the stable release.
+
+## [1.13.0] - 2026-07-30
+
+### Added
+
+- **`bl config ui` Skills / MCP / Agents / Assets inventory** — browse installed skills, MCP servers, coding agents, and generated assets in the local Web UI with click-to-open detail drawers:
+  - Skills: render `SKILL.md` as Markdown (GFM tables supported), show local vs remote origin badges, and install a skill by uploading a `.zip` archive into any supported agent's skills root.
+  - MCP: view and edit JSON configuration with secret masking and mask-preserving writes; create, update, and delete MCP entries across Claude Code, Qwen Code, OpenCode, Cursor, Windsurf, Gemini, Qoder Work, OpenClaw, and Claude Desktop.
+  - Agents: quick-launch coding agents directly from the UI (gated on the CLI binary being on PATH).
+  - Assets: categorized, time-sorted browser with preview, open-locally, and delete.
+- **Model catalog suggestion chips** — per-category model names surfaced as click-to-fill chips under each `default_*_model` field in the config UI.
+- **Profiles tile grid** — profiles displayed as a tile grid with an add-tile and a design-consistent new-profile modal.
+
+### Changed
+
+- Config UI layout: collapsible grouped sidebar with icons and persistent state, responsive breakpoint, wider main area, sticky view headers, and right-side drawers for editing.
+
+### Fixed
+
+- Symlinked skill directories are now correctly identified as an installed source.
+- Config file detection now supports environment-variable-based paths and legacy configuration schemes.
+
+## [1.12.0] - 2026-07-28
+
+### Added
+
+- **`bl config agent --key` / `--region`** — run commands generated by the Model Studio web console as-is: `--key` accepts the console's encoded API key and decodes it locally (use instead of `--api-key`), and `--region` derives the Token Plan endpoint from a region name (use instead of `--base-url`).
+- **`bl config agent --context-window`** — set the context window written to the OpenClaw configuration (default 256000).
+- **`bl config agent --wire-api`** — choose the wire protocol written to the Codex configuration; `chat` is kept for legacy Codex 0.80.0 and earlier (a warning is shown).
+
+### Changed
+
+- `bl config agent` for Codex now writes `wire_api = "responses"` by default, matching current Codex releases that no longer accept `chat`.
+- `bl config agent` for Qwen Code now writes the `DASHSCOPE_API_KEY` environment variable instead of `BAILIAN_CLI_API_KEY`.
+
+### Fixed
+
+- `bl config agent` configurations now match each agent's official format: Claude Code honors `CLAUDE_CONFIG_DIR` and removes a stale `ANTHROPIC_API_KEY`; Qwen Code uses the v3 settings schema and writes credentials so a system-level `OPENAI_API_KEY` no longer takes precedence; OpenCode accepts JSONC config files (comments and trailing commas); OpenClaw registers the primary model in the model allowlist with complete cost metadata; Hermes uses the official flat `model.*` layout; Codex writes the official `env_key` with an `auth.json` fallback.
+- `bl config agent` now preserves existing user configuration when writing: it merges instead of overwriting, avoids duplicate provider entries, and keeps custom display names.
+
+## [1.11.2] - 2026-07-28
+
+### Changed
+
+- MCP tools and WebSearch now provide activation guidance and direct marketplace links when Bailian reports that the corresponding service is not activated. WebSearch also guides users with legacy SSE connections to reactivate the service using Streamable HTTP.
+
+### Fixed
+
+- Fixed text chat and API Key validation compatibility failures caused by sending unsupported `enable_thinking` values. Text chat now sends the parameter only when thinking is explicitly enabled, while validation uses a compatible model without sending it.
+
+## [1.11.1] - 2026-07-28
+
+### Added
+
+- `bl image edit` now supports `--function` for specifying edit operations with Wanx image-edit models such as `wanx2.1-imageedit`.
+
+### Fixed
+
+- Fixed image generation and editing failures and incorrect size parameters for some image models, improving compatibility with Qwen-Image, Wan/Wanx, Z-Image, and dated `wanx-v1` variants.
+
+## [1.11.0] - 2026-07-28
+
+### Added
+
+- **`bl managed-agent`** — declaratively manage Managed Agent infrastructure through a unified CLI. The Bailian provider connects to AgentStudio, with Claude, Qoder, and Ark providers also supported:
+  - `init` / `validate` / `plan` / `apply` / `destroy` — initialize and validate `agents.yaml`, preview and apply resource changes, and destroy managed resources.
+  - `state list` / `state show` / `state rm` / `state import` — inspect and manage local resource state, including adopting an existing remote resource or removing it from local state without destroying it remotely.
+  - `session create` / `session list` / `session get` / `session delete` / `session run` / `session send` / `session events` — manage the full session lifecycle with streaming responses and structured `--output json` output.
+  - `skill-list` — browse custom and official skills; use `--source all` to return both catalogs in one call.
+
+### Changed
+
+- Model Base URLs are now normalized to the URL origin; paths, query parameters, and fragments supplied in the Base URL are no longer included when constructing API request paths.
+
+### Fixed
+
+- The installation guide no longer recommends the removed `--non-interactive` flag and now documents explicit required arguments, `--output json`, and `NO_COLOR=1` for non-interactive environments.
+
+## [1.10.1] - 2026-07-22
+
+### Changed
+
+- Token Plan defaults now use the current text, image, and dedicated text-to-video, image-to-video, and reference-to-video models.
+- The Bailian CLI Skill now distinguishes Bailian-specific tasks from ordinary host-agent work more accurately and avoids repeated consent prompts within an approved workflow.
+- Published CLI packages now support Node.js 18.17 and later, lowering the previous minimum requirement from Node.js 22.12.
+
+### Fixed
+
+- Token Plan now handles local images correctly for image editing, image-to-video, reference-to-video, and vision understanding without requiring a separately hosted URL.
+
+## [1.10.0] - 2026-07-19
+
+### Added
+
+- **`bl config agent`** — configure Claude Code, Qwen Code, OpenCode, OpenClaw, Hermes Agent, or Codex to use DashScope in one command.
+
+### Changed
+
+- The Bailian CLI Skill now routes only matching Bailian and multimodal tasks to `bl`, and asks for consent before provider-neutral remote or billable calls.
+
+### Fixed
+
+- Full `bl auth logout` now clears the model Base URL so later logins cannot inherit a stale custom or Token Plan endpoint.
+
 ## [1.9.0] - 2026-07-17
 
 ### Added

CHANGELOG.zh.md

@@ -6,6 +6,331 @@
 
 [English](CHANGELOG.md) · [README](README.zh.md) · [参与贡献](CONTRIBUTING.zh.md)
 
+## [1.22.0] - 2026-09-08
+
+### 变更
+
+- **项目初始化** —— `managed-agent project init` 默认创建 `./managed-agent` 子目录；如需原地初始化，请使用 `--project .`。**(BREAKING)**
+- **Build 确认机制** —— `managed-agent project build` 无需确认，并且不再接受 `--yes`。使用 `--dry-run` 可只读预览；Publish 仍需显式确认。**(BREAKING)**
+- **Managed Agent SDK** —— 升级至 `0.7.1`。Build 自动关联 Agent 目录下已启用的资源，保留显式引用、Skill 版本和 File 挂载路径；Environment 或 Vault 选择存在歧义时，在写入前报错。
+
+### 修复
+
+- **项目诊断** —— 提供可操作的项目根目录提示，并展示 Build 校验失败的具体原因。
+- **YAML 初始化路径** —— 创建成功及文件已存在的错误信息均展示 YAML 绝对路径。
+
+### 内部
+
+- 补充项目初始化和 Build 回归覆盖，移除本地闭环 E2E 测试中过时的 Build 确认参数。
+
+## [1.21.0] - 2026-09-07
+
+### 新增
+
+- **Managed Agent 目录项目** —— 支持初始化、校验、构建和发布本地项目，按 Agent 组织资源配置，并提供资源示例。
+- **本地项目版本管理** —— 无需 Git 即可启停快照版本管理、查看和预览历史，以及恢复项目文件。
+- **项目 Workbench** —— 在浏览器中编辑资源、审阅变更、发布更新和管理本地版本。
+
+### 变更
+
+- **Playground 版本选择** —— 启动前查询 npm，复用版本一致的本地安装，否则按需下载最新版；保留显式版本和启动文件覆盖。
+- **Managed Agent SDK** —— 升级至 `0.7.0`，通过 SDK 子路径复用项目目录和版本服务。
+
+## [1.20.0] - 2026-09-03
+
+> Managed Agent 现在同时提供 YAML-first 基础设施管理与百炼 AgentStudio 资源、运行时 API 操作。
+
+### 新增
+
+- **Managed Agent API 命令** —— 新增 Agent、Environment、Skill、Vault、Deployment、Session 和 File 的列表、详情、搜索、版本、上传、下载、运行、暂停、归档、事件及诊断等操作。
+- **基于 YAML 的单资源创建** —— `agent create`、`environment create`、`skill create`、`vault create`、`vault credential create` 和 `deployment create` 会更新 `agents.yaml`，并且只 Apply 目标资源，不受无关资源 Drift 阻塞。
+- **Agent Skill 挂载** —— 创建 Agent 时支持引用已有的自定义或官方 Skill ID，也支持本地 Skill 目录和 ZIP 文件。
+
+### 变更
+
+- **Managed Agent CLI 限定为百炼 Provider** —— `bl managed-agent` 现在只面向百炼，移除 Provider 选择参数，并拒绝包含其他 Provider 的配置。
+- **运行时变更增加确认** —— Deployment 运行/暂停/恢复、Session 归档/删除以及 File 删除操作需要显式进行高风险确认。
+
+### 修复
+
+- **Managed Agent 错误输出** —— Apply 和单资源创建失败时会保留底层 Provider 的具体诊断，不再只显示 `Apply failed.`。
+
+### 安全
+
+- 凭证仅在内存中解析并从进程环境清除；Vault Credential 声明通过环境变量引用 Secret，不会持久化明文。
+
+## [1.19.0] - 2026-09-01
+
+### 新增
+
+- **`bl quota delete`** — 清除指定模型的全部自定义 QPM/TPM 限流配置。
+
+### 变更
+
+- **高风险操作确认** — 高风险命令会在 `--help` 和 Skill 命令参考中展示风险说明。未传入 `--yes` 时，高风险操作不会执行；JSON 输出会返回退出码 `7` 和 `error.type: "requires_confirmation"`。确认后可添加 `--yes` 重新执行；`--dry-run` 无需确认。
+
+## [1.18.2] - 2026-09-01
+
+### 变更
+
+- **删除与清除操作增加确认** —— `bl finetune delete`、`bl deploy delete`、`bl dataset delete` 和 `bl quota update --delete` 现在会在执行前要求确认；非交互场景请传入 `--yes`。
+
+### 修复
+
+- **Skill 安装可靠性** —— `bl skill init` 现在会重试临时性网络故障；备份清理受阻时，已完成的 Skill 更新不再被误报为失败。
+
+## [1.18.1] - 2026-08-28
+
+### 已移除
+
+- 移除 `bl auth login` 的 API Key 校验。
+
+## [1.18.0] - 2026-08-27
+
+### 新增
+
+- **Profile API Key 自动回退** —— 当前 Profile 不支持某条命令时，自动使用 `default` 中的 API Key 和接入地址，无需手动切换 Profile；显式凭证仍然优先。
+- **语音合成与识别支持独立默认模型** —— Profile 支持分别配置 TTS 和 ASR 默认模型。
+- **Wan3.0 文件生视频** —— `bl video generate --file` 支持本地文件或 URL，并校验互斥输入。
+
+### 变更
+
+- **视频默认模型升级至 Wan3.0** —— 普通 API Key 的文生、图生和参考生视频默认使用 `wan3.0-video`，并支持首尾帧与参考音频；Token Plan 默认模型保持不变。
+- **扩展 Token Plan 预设** —— 登录后自动补充语音默认模型和缺失能力，同时保留用户已有配置。
+- **优化语音与 Skill 安装体验** —— 流式语音合成默认输出 PCM；Skill 安装文档补充兼容 Node 18 的降级方式及 Node.js、Git 前置条件。
+
+## [1.17.1] - 2026-08-22
+
+### 修复
+
+- **`knowledge create` 的 `--description` 更新为必填** —— 对齐服务端对知识库描述的必填校验：新增 `--description` 参数并设为必填，在发出请求前于本地校验 1–500 个字符的长度限制。`bl knowledge create` / `kscli kb create` 调用需带上该参数。
+- **`knowledge service update` 对服务端自己返回的配置字段误报警告** —— 通过 `--policy` 等标量参数更新草稿配置时，CLI 会先读取完整草稿再合并回写；草稿中的 `user_system_prompt`、`anti_leak_prompt`、`refusal_prompt`、`credibility_prompt`、`session_file_parse_mode` 以及 `enable_thinking` / `enable_temperature` / `enable_credibility` / `enable_max_completion_tokens` 此前不被 CLI 识别，导致每次更新都刷出一串 `unknown agent_config field passed through` 警告。配置本身始终被正确写入，现在不再误报。
+
+### 新增
+
+- **`bailian-web-search` 路由技能** —— `bl skill init` 现在会一并安装专门的联网搜索路由技能，让 agent 直接选中正确的搜索入口，不再靠猜。
+- **Knowledge Studio CLI 命令手册** —— 完整的 `kscli` 参考文档，覆盖知识库、文档、切片、集合/类目、文件、检索/问答服务以及 search/chat，每条命令均附可运行示例。
+
+### 变更
+
+- **描述类参数说明写清该填什么** —— 数据集合与服务的 `--description` 帮助文案现在会说明该字段的用途（在列表中区分同类项；服务描述供 agent 判断该调用哪个服务），不再只是重复「必填」。
+- **`knowledge retrieve --rerank-model` 补充前置条件说明** —— 帮助文案现在会说明目标知识库必须已配置重排序模型，否则任何取值都会被拒绝。
+
+## [1.17.0] - 2026-08-18
+
+### 新增
+
+- **百炼原生 Managed Agent Deployment** —— `agents.yaml` 中声明的 `deployments` 现在会创建原生 AgentStudio 资源，支持服务端 Cron 调度、本地文件资源上传、通过 `destroy` 归档，以及在下次 `apply` 时迁移旧版模拟 Deployment state。
+- **CLI 中英文体验** —— 可通过 `bl config set` 或 Config UI 将 `language` 设置为 `en-US` 或 `zh-CN`，在英文和中文的 CLI Help、Quick Start、命令示例及 Config UI 之间切换；所选语言跟随当前激活的配置。
+
+### 修复
+
+- **Free Tier Auto-Stop 控制** —— `bl usage freetier --off` 现在可在免费额度尚有剩余时关闭 Auto-Stop；状态展示会反映实际开关状态，并仅查询筛选后的模型，避免触发服务端批量查询上限。
+
+## [1.16.0] - 2026-08-17
+
+> CLI 迎来知识库全生命周期管理：从创建配置知识库、上传文档、调优切片，到部署检索/问答服务，均可通过 `bl knowledge` 与 `kscli` 完成。
+
+### 新增
+
+- **知识库管理** —— `bl knowledge create` / `list` / `info` / `update` / `delete` 覆盖知识库的完整生命周期；`bl knowledge stats` 查询指定过去时间段内的文档数量与用量统计。
+- **文档管理** —— `bl knowledge doc upload` 支持上传本地文件或整个目录（递归扫描，自动跳过不支持的格式及 `node_modules` 等工具目录）；`doc list` / `status` / `tag` / `delete` 覆盖文档生命周期其余环节，`doc import-oss` 支持从 OSS 导入文档。
+- **检索 / 问答服务管理** —— `bl knowledge service list` / `get` / `create` / `update` / `deploy` / `delete` / `copy` 管理检索与问答服务配置，支持将草稿部署为正式版本。
+- **切片管理** —— `bl knowledge chunk add` / `list` / `update` / `delete` 查看并精调文档切片。
+- **数据中心管理** —— `bl knowledge category list` / `add` / `delete`、`bl knowledge file list` / `get` / `delete`、`bl knowledge collection create` / `get` 管理类目、原始文件与数据集。
+- **检索与问答支持指定服务版本** —— `bl knowledge search` 和 `bl knowledge chat` 新增 `--agent-version`，可调用 beta（草稿）配置进行调试，或指定已发布的版本号。
+- **`kscli` 同步支持** —— 全部新知识库命令在 Knowledge Studio CLI 中以更短路径提供，如 `kscli kb list`、`kscli doc upload`、`kscli service deploy`。
+
+### 移除
+
+- **移除 `bl knowledge search --query-history`** —— 该参数此前并未实际生效；多轮场景请改用 `bl knowledge chat` 并通过 `--message` 传入对话历史。
+
+### 内部
+
+- 请求现在携带静态的 OpenAPI 来源标识请求头，用于后端渠道归因。
+- 新增知识库 E2E 测试套件，含冷启动、内容运营、切片调优、服务调优、数据面五条用户旅程场景。
+
+## [1.15.1] - 2026-08-17
+
+### 新增
+
+- **模型权限管理** —— `bl permission list` 查看各模型的推理 / 微调 / 部署授权；`bl permission grant` 与 `bl permission revoke` 负责授予和回收，支持 `--all` 一键为工作区全部模型（含后续新增模型）开启推理授权。
+
+### 变更
+
+- **`bl quota request` 更名为 `bl quota update`** —— 通过 `--rpm`/`--tpm` 设置单模型 QPM/TPM，新增 `--delete` 一键清除自定义限制；未指定的字段保持当前值，旧命令 `quota request` 仍作为别名可用。
+- **`bl quota list` 重构** —— 改从模型限制接口读取数据，单表展示模型级与工作区级的请求/用量限制及异步队列/并发限制。
+- **`bl model list` 不再需要控制台登录** —— 模型目录与 `--enrich` 参数结构端点均为公开接口。
+- **`bl skill init` 输出精简** —— 单技能状态改为 `success`/`failed`（原为 `installed`），新增 `success`/`partial`/`failed` 汇总结果；移除 `publishedAt` 与 `agents` 字段。
+
+## [1.15.0] - 2026-08-14
+
+### 新增
+
+- **`bl text chat` 支持 Responses API** —— 可通过 `--api responses` 调用 DashScope Responses API，支持流式输出、工具定义和结构化 JSON 输出；默认仍使用 Chat Completions。
+- **订阅套餐用量视图** —— `bl usage token-plan` 支持查看 5 小时和每周额度，`bl usage coding-plan` 支持查看 5 小时、每周和每月额度；两者均提供文本与 JSON 输出。
+- **命令帮助展示鉴权要求** —— Help 输出现在会明确标注命令需要 API Key、控制台登录还是阿里云 OpenAPI 凭证。
+
+### 变更
+
+- **扩展语音识别模型支持** —— `bl speech recognize` 现在会将异步文件转写和同步 Flash ASR 模型路由至对应的 DashScope API，并为暂不支持的实时模型提供明确提示。
+- **增强 MCP 传输兼容性** —— MCP 命令现在可为兼容的百炼及自定义端点从 Streamable HTTP 自动回退至经典 SSE。
+
+### 修复
+
+- 二进制方式升级 CLI 成功后，现在会同步刷新已安装的 Agent Skills。
+- 修复 Token Plan 额度不可用或缺少重置时间时的展示问题。
+- 修复 Qwen3 文件转写结果处理，使等待模式和 `--out` 能够正常工作。
+- 修复 MCP SSE 分块解析、响应头超时、中止清理和回退状态匹配问题。
+- JSON 输出中的网络错误现在会在 `cause.code` 中保留 errno。
+
+## [1.14.3] - 2026-08-12
+
+### 修复
+
+- **免费额度兼容性** —— `bl usage free` 和 `bl usage freetier` 现在使用最新的 Bailian Commerce 控制台 API 查询、开通和关闭免费额度，并统一处理异步任务轮询。
+
+## [1.14.2] - 2026-08-07
+
+### 新增
+
+- **`bl skill init`** —— 一次性将全部官方 `bailian-*` Skill 安装到本机检测到的 AI Agent。
+
+### 变更
+
+- **Skill 命令接口** —— Skill 管理命令现在默认输出适合 Agent 工作流的 JSON；`bl skill add` 和 `bl skill update` 使用明确的 `--all` 与 `--name` 选择参数。
+
+## [1.14.1] - 2026-08-05
+
+### 新增
+
+- **百炼 Skill 按领域拆分** —— 通过 `npx skills add modelstudioai/cli --all -g` 可统一安装图片与视频生成、模型微调、Managed Agent 和共享执行协议等专用 Skill，提升任务路由准确性并减少无关上下文。
+
+### 变更
+
+- **默认图片模型升级至 Qwen-Image 3.0** —— 普通 API Key 用户的图片生成、图片编辑、Pipeline、配置 UI 和相关文档现在默认使用 `qwen-image-3.0`。
+- **扩展 Coding Agent 兼容范围** —— Skill 安装与更新现在能够识别更多 Coding Agent，保留已有安装链接，并自动将 Skill 补充到新识别的 Agent。
+
+## [1.14.0] - 2026-08-04
+
+### 新增
+
+- **免 Node.js 的二进制安装** — 支持 macOS Apple Silicon / Intel、Linux x64 和 Windows x64；npm 安装方式继续保留。
+- **指定版本更新** — 二进制和 npm 安装均可通过 `bl update --to <version>` 更新或切换到指定版本。
+
+### 变更
+
+- **二进制自更新** — 二进制安装现在通过独立的发布通道检查和下载更新；执行 `bl update` 时不会覆盖正在运行的程序，下次运行自动使用新版本。
+
+## [1.13.1] - 2026-08-03
+
+### 变更
+
+- **默认文本模型升级至 Qwen3.8-Max** — `bl text chat`、Pipeline、API Key 登录校验、配置 UI 和 Managed Agent 初始化模板现在默认使用 `qwen3.8-max`；Token Plan 也由预览版切换至正式版。
+
+## [1.13.0] - 2026-07-30
+
+### 新增
+
+- **`bl config ui` 技能 / MCP / 代理 / 资产清单** — 在本地 Web UI 中浏览已安装的技能、MCP 服务器、编码代理和生成的资产，点击打开右侧详情抽屉：
+  - 技能：将 `SKILL.md` 渲染为 Markdown（支持 GFM 表格），展示本地/远程来源徽章，支持上传 `.zip` 压缩包将技能安装到任意受支持代理的技能目录。
+  - MCP：查看和编辑 JSON 配置，支持密钥掩码与掩码保真写回；支持在 Claude Code、Qwen Code、OpenCode、Cursor、Windsurf、Gemini、Qoder Work、OpenClaw 和 Claude Desktop 中创建、更新、删除 MCP 条目。
+  - 代理：从 UI 一键启动编码代理（需对应 CLI 二进制在 PATH 中）。
+  - 资产：按类别分组、按时间排序的浏览器，支持预览、本地打开和删除。
+- **模型目录建议芯片** — 在配置 UI 的每个 `default_*_model` 字段下方展示按类别分组的模型名称，点击即可填入。
+- **Profile 磁贴网格** — 配置文件以磁贴网格展示，新增添加磁贴和设计一致的新建 Profile 弹窗。
+
+### 变更
+
+- 配置 UI 布局：可折叠分组侧边栏（带图标和持久化状态）、响应式断点、更宽的主区域、吸顶视图标题、右侧抽屉式编辑。
+
+### 修复
+
+- 修复软链接技能目录未被正确识别为已安装来源的问题。
+- 配置文件检测现支持基于环境变量的路径和旧版配置方案。
+
+## [1.12.0] - 2026-07-28
+
+### 新增
+
+- **`bl config agent --key` / `--region`** —— 百炼控制台生成的命令可直接运行：`--key` 接收控制台编码后的 API Key 并在本地解码（与 `--api-key` 二选一）；`--region` 根据地域名自动派生 Token Plan 接入地址（与 `--base-url` 二选一）。
+- **`bl config agent --context-window`** —— 设置写入 OpenClaw 配置的上下文窗口大小（默认 256000）。
+- **`bl config agent --wire-api`** —— 选择写入 Codex 配置的通信协议；`chat` 仅保留给 Codex 0.80.0 及更早版本（会显示警告）。
+
+### 变更
+
+- `bl config agent` 配置 Codex 时默认写入 `wire_api = "responses"`，以适配已不再支持 `chat` 的新版 Codex。
+- `bl config agent` 配置 Qwen Code 时改用 `DASHSCOPE_API_KEY` 环境变量，不再使用 `BAILIAN_CLI_API_KEY`。
+
+### 修复
+
+- `bl config agent` 写入的配置现已与各 Agent 官方格式对齐：Claude Code 尊重 `CLAUDE_CONFIG_DIR` 并清理残留的 `ANTHROPIC_API_KEY`；Qwen Code 采用 v3 配置 schema 并正确写入凭证，避免被系统级 `OPENAI_API_KEY` 干扰；OpenCode 支持带注释和尾部逗号的 JSONC 配置文件；OpenClaw 会将主模型注册进模型白名单并补齐计费元数据；Hermes 改用官方扁平 `model.*` 结构；Codex 写入官方 `env_key` 并支持 `auth.json` 兜底。
+- `bl config agent` 写入配置时现会保留用户已有配置：合并而非覆盖，避免重复添加 provider 条目，并保留用户自定义的显示名。
+
+## [1.11.2] - 2026-07-28
+
+### 变更
+
+- MCP 工具或 WebSearch 因对应服务未开通而不可用时，CLI 现在会提供开通指引和市场直达链接；对于使用旧版 SSE 连接的 WebSearch，还会提示重新开通以切换至 Streamable HTTP。
+
+### 修复
+
+- 修复文本对话与 API Key 登录校验因传递不受支持的 `enable_thinking` 参数值而产生的兼容性错误。文本对话仅在用户明确开启思考模式时传递该参数，登录校验则改用兼容模型且不再传递该参数。
+
+## [1.11.1] - 2026-07-28
+
+### 新增
+
+- `bl image edit` 新增 `--function` 参数，支持为万相图片编辑模型（如 `wanx2.1-imageedit`）指定编辑功能。
+
+### 修复
+
+- 修复部分图片模型在图片生成与编辑时的调用失败和尺寸参数错误，并完善 Qwen-Image、Wan/Wanx、Z-Image 系列及 `wanx-v1` 日期版本的兼容性。
+
+## [1.11.0] - 2026-07-28
+
+### 新增
+
+- **`bl managed-agent`** —— 通过统一 CLI 声明式管理 Managed Agent 基础设施；百炼 Provider 对接 AgentStudio，并支持 Claude、Qoder 和 Ark：
+  - `init` / `validate` / `plan` / `apply` / `destroy` —— 基于 `agents.yaml` 初始化、校验、预览和执行资源变更，以及销毁已托管资源。
+  - `state list` / `state show` / `state rm` / `state import` —— 查看和管理本地资源状态，包括纳管已有远端资源或仅解除本地跟踪。
+  - `session create` / `session list` / `session get` / `session delete` / `session run` / `session send` / `session events` —— 完整的会话生命周期操作，支持流式响应和结构化的 `--output json` 输出。
+  - `skill-list` —— 浏览自定义与官方 Skill；使用 `--source all` 可一次返回两个来源。
+
+### 变更
+
+- 模型 Base URL 现在统一仅保留 URL Origin；传入的路径、查询参数和 Fragment 不再参与后续 API 请求路径拼接。
+
+### 修复
+
+- 安装指南不再推荐已移除的 `--non-interactive`，改为说明显式传入必填参数，并使用 `--output json` 或 `NO_COLOR=1` 适配非交互环境。
+
+## [1.10.1] - 2026-07-22
+
+### 变更
+
+- Token Plan 默认模型已更新为当前文本、图片，以及文生视频、图生视频和参考生视频的专用模型。
+- 百炼 CLI Skill 现在能更准确地区分百炼专属任务与普通宿主 Agent 任务，并避免在已授权的工作流中重复征求同意。
+- 已发布的 CLI 包现在支持 Node.js 18.17 及以上版本，最低版本要求由 Node.js 22.12 下调至 18.17。
+
+### 修复
+
+- Token Plan 现在能在图片编辑、图生视频、参考生视频和视觉理解中正确处理本地图片，无需另行托管为 URL。
+
+## [1.10.0] - 2026-07-19
+
+### 新增
+
+- **`bl config agent`** —— 一键配置 Claude Code、Qwen Code、OpenCode、OpenClaw、Hermes Agent 和 Codex 接入百炼模型服务。
+
+### 变更
+
+- 百炼 CLI Skill 现在只将匹配的百炼任务与多模态任务路由到 `bl`，并会在调用与平台无关的远程或计费能力前征求同意。
+
+### 修复
+
+- 完整执行 `bl auth logout` 时会同时清除模型 Base URL，避免后续登录继承失效的自定义或 Token Plan 接入地址。
+
 ## [1.9.0] - 2026-07-17
 
 ### 新增

CONTRIBUTING.md

@@ -6,7 +6,8 @@ Developer guide for `bailian-cli` — the official CLI for Aliyun Model Studio (
 
 ## Prerequisites
 
-- Node.js ≥ 22.12
+- Node.js ≥ 22.12 (required for developing this repo)
+- End users installing the published CLI only need Node.js >= 18.17
 - pnpm 10.33.2 (`npm i -g pnpm@10.33.2`)
 - A DashScope API key for running e2e tests
 
@@ -15,11 +16,17 @@ Developer guide for `bailian-cli` — the official CLI for Aliyun Model Studio (
 ```
 bailian-cli/
 ├── packages/
-│   ├── cli/              # `bailian-cli` — CLI entry, commands, UI
-│   └── core/             # `bailian-cli-core` — auth, HTTP, types
-├── docs/agents/          # Scenario-based maintenance guides
-├── tools/                # Release automation & reference generation
-├── AGENTS.md             # Contract for AI agents
+│   ├── core/           # `bailian-cli-core` — auth, config, HTTP client, errors, types
+│   ├── runtime/        # `bailian-cli-runtime` — CLI framework: parsing, help, middleware, output
+│   ├── commands/       # `bailian-cli-commands` — reusable command implementations
+│   ├── cli/            # `bailian-cli` — the full `bl` product entry
+│   ├── kscli/          # `knowledge-studio-cli` — `kscli` entry, reuses commands/
+│   ├── e2e/            # Shared e2e harness utilities (private)
+│   └── bailian-kb-dsh/ # `bailian-kb-dsh` — DeepSeek Harness plugin (independent version & release)
+├── skills/             # Agent skills installed by `bl skill init`
+├── docs/agents/        # Scenario-based maintenance guides
+├── tools/              # Release automation & reference generation
+├── AGENTS.md           # Contract for AI agents
 └── README.md
 ```
 

CONTRIBUTING.zh.md

@@ -6,8 +6,9 @@
 
 ## 环境要求
 
-- Node.js ≥ 22.12
-- pnpm 10.33.2(`npm i -g pnpm@10.33.2`)
+- 参与本仓库开发：Node.js ≥ 22.12
+- 仅安装/使用已发布的 CLI：Node.js >= 18.17
+- pnpm 10.33.2（`npm i -g pnpm@10.33.2`）
 - 跑 e2e 需要一个百炼 API Key
 
 ## 仓库结构
@@ -15,11 +16,17 @@
 ```
 bailian-cli/
 ├── packages/
-│   ├── cli/              # `bailian-cli` —— CLI 入口、命令、UI
-│   └── core/             # `bailian-cli-core` —— 鉴权、HTTP、类型
-├── docs/agents/          # 场景化维护文档
-├── tools/                # 发版自动化与命令手册生成
-├── AGENTS.md             # AI agent 维护契约
+│   ├── core/           # `bailian-cli-core` —— 鉴权、配置、HTTP client、错误、类型
+│   ├── runtime/        # `bailian-cli-runtime` —— CLI 运行时:参数解析、help、middleware、输出
+│   ├── commands/       # `bailian-cli-commands` —— 可复用命令实现库
+│   ├── cli/            # `bailian-cli` —— 完整 `bl` 产品入口
+│   ├── kscli/          # `knowledge-studio-cli` —— `kscli` 入口,复用 commands/
+│   ├── e2e/            # e2e 共享工具(不发布)
+│   └── bailian-kb-dsh/ # `bailian-kb-dsh` —— DeepSeek Harness 插件(版本与发布独立)
+├── skills/             # `bl skill init` 安装的 Agent skill
+├── docs/agents/        # 场景化维护文档
+├── tools/              # 发版自动化与命令手册生成
+├── AGENTS.md           # AI agent 维护契约
 └── README.md
 ```
 

INSTALL.md

@@ -1,59 +1,76 @@
 # 阿里云百炼CLI 安装说明（供 AI Agent 阅读）
 
-本文档面向 **AI Agent**：按下列步骤为用户安装并校验 **阿里云百炼CLI**（npm 包名 `bailian-cli`，命令 `bl` / `bailian`）。用户通常通过 **npm 全局安装** 使用，**无需**访问本仓库源码。不要臆造版本号或路径；以用户环境为准。
+本文档面向 **AI Agent**：按下列步骤为用户安装并校验 **阿里云百炼CLI**（命令 `bl` / `bailian`）。**优先**在已有 Node.js（**≥ 18.17.0**）的环境用 npm 安装；若没有可用 Node / npm，再走二进制一键安装。不要臆造版本号或路径；以用户环境为准。
 
-## 1. 安装前检查
+## 1. 推荐：npm 安装（要求 **≥ 18.17.0**）
 
-**原则**：先执行检查；若 **Node / 包管理器 / 网络** 任一不满足下文要求，Agent 应 **在本机终端内主动完成安装或配置**（例如升级 Node、切换镜像、配置 `npm` 代理等），再继续 `bailian-cli` 安装。仅在无权限或环境无法自动化时，再向用户说明原因并请其配合。
-
-1. **Node.js**
-   - 要求 **≥ 22.12.0**，执行 `node -v` 确认。
-   - 未安装或版本不足：由 Agent 自行安装或升级 Node。
-
-2. **npm**（**唯一**允许的包管理器）
-   - 执行 `npm -v` 确认可用。
-   - 未安装或不可用：由 Agent **安装或修复 npm**（不要改用 pnpm/yarn 装 `bailian-cli`），再执行 `npm install -g bailian-cli`。
-   - 即使本机已安装 `pnpm`、`yarn` 等，**也仅用于其它项目**；装 `bailian-cli` 时仍必须用 `npm`。
-
-3. **网络**
-   - 需能访问 npm registry（默认 **registry.npmjs.org**）。
-   - 不可达：由 Agent 自行配置镜像或代理后重试。
-
----
-
-## 2. 安装 CLI 与 Skills
-
-**仅允许以下命令**（不要用 `pnpm add -g`、`yarn global add` 等）。按顺序执行，上一步通过后再进行下一步。
-
-**2.1 安装 CLI**
+1. `node -v` 确认版本 ≥ 18.17.0。
+2. `npm -v` 确认可用（**仅允许 npm** 全局安装，不要用 pnpm/yarn）。
+3. 执行：
 
 ```bash
 npm install -g bailian-cli
 ```
 
-安装成功后，应能在 PATH 中找到：
+4. 校验：`bl --version`。
+5. 按下方「安装 skills」安装。
 
-- `bl`（短别名）
-- `bailian`（全名）
+### 安装 skills
 
-**校验**（Agent 应执行并检查退出码与输出）：
+**Supported（优先）：** 用 CLI 内置命令一次装齐 registry 中全部 `bailian-*`（含共享协议 `bailian-protocol`）：
+
+```bash
+bl skill init
+```
+
+**降级：** 若 `bl skill init` 失败，先确认本机同时满足两个条件：`node -v` / `npm -v` 成功，**且** `git --version` 成功。两个条件都成立时，再回退到：
+
+```bash
+npx skills@1.5.18 add modelstudioai/cli --all -g
+```
+
+> 必须使用 `skills@1.5.18`：这是最后兼容 Node ≥18 的版本（与 Bailian CLI 的 Node ≥18.17.0 一致）；
+
+安装成功后，按第 5 节向用户说明语言切换与能力 tip（若也装了 skills，一并简要说明）。
+
+## 2. 备选：二进制安装（无需 Node）
+
+当环境没有 Node / npm，或 Node 版本过低无法走 npm 时，使用二进制安装脚本。脚本安装 CLI 成功后会自动执行 `bl skill init`。
+
+```bash
+curl -fsSL https://bailian.aliyun.com/cli/install.sh | bash
+```
+
+可选：正式安装读 CDN 上的 `manifest.json`。预发 / channel 验证一律读 `sync-release.json`（bailian-cli 的 channel 发版都会覆盖它）：
+
+```bash
+curl -fsSL https://bailian.aliyun.com/cli/install.sh | bash -s -- --channel sync-release
+```
+
+也可用 `--version` / `--cdn`（或环境变量 `BAILIAN_CLI_CDN`）覆盖资源根。安装脚本本身不在本仓库维护。
+
+Windows PowerShell：
+
+```powershell
+# 正式（manifest.json）
+irm https://bailian.aliyun.com/cli/install.ps1 | iex
+
+# channel / 预发验证（sync-release.json）
+$env:BAILIAN_CHANNEL = 'sync-release'; irm 'https://bailian.aliyun.com/cli/install.ps1' | iex
+```
+
+带其它参时先落盘再执行（`irm | iex` 不便传参），或使用仓外静态资源文档中的预发入口。
+
+二进制安装布局为 `versions/<ver>/` + `current` 指针；`bl update` 只切换指针并清理旧版本（保留当前与上一版）。更新进程退出后，下次执行 `bl` 即使用新版本（无需「重启应用」）。
+
+校验：
 
 ```bash
 bl --version
-which bl   # Windows 可用 where bl
+which bl   # Windows: where.exe bl
 ```
 
-若 `command not found`：检查全局 bin 是否在 PATH（`npm config get prefix`，其下 `bin` 目录应加入 PATH）。
-
-**2.2 安装 Skills**
-
-CLI 校验通过后，在本机终端执行：
-
-```bash
-npx skills add modelstudioai/cli --all -g
-```
-
-安装成功后，用中文简要说明已安装的 skills 及用户可做什么。
+> CDN / GitHub Release 未就绪或下载失败时，若本机已有合格 Node，回退到上方 npm 安装。
 
 ---
 
@@ -61,57 +78,65 @@ npx skills add modelstudioai/cli --all -g
 
 ### 推荐：浏览器登录（控制台会话）
 
-适用于本机交互式安装，无需用户手动复制 API Key：
-
 1. 执行 `bl auth status --output json`，判断是否已配置。
-2. 若未配置，在**用户本机终端**执行 `bl auth login --console`；命令会拉起浏览器完成阿里云控制台登录授权。
+2. 若未配置，在**用户本机终端**执行 `bl auth login --console`。
 3. 登录成功后执行 `bl auth status --output json` 确认；汇报时只使用 masked 字段，**禁止**回显完整凭据。
 
-> 此方式同时打通 `app list`、`usage free` 等控制台能力，并自动配置 API Key 调用所需的鉴权信息。
+### 备选：API Key / Token Plan
 
-### 备选：由 Agent 引导用户输入 API Key 后登录
-
-适用于无法拉起浏览器的对话式安装（远程 SSH、CI 调试、纯终端环境等）：
-
-- 获取入口：[百炼控制台 API Key](https://bailian.console.aliyun.com/cn-beijing/?tab=app#/api-key)
-
-1. 执行 `bl auth status --output json`，判断是否已配置。
-2. 若未配置或后续 API 校验失败，**请用户粘贴 API Key**（可说明从上述控制台复制；勿要求用户发到公开渠道）。
-3. 用户提供了 Key 之后，在**用户本机终端**执行（Agent 用终端工具跑，勿把 Key 写进回复正文）：`bl auth login --api-key <用户提供的_Key>`
-4. 登录成功后执行 `bl auth status --output json` 确认；汇报时只使用 masked 字段，**禁止**回显完整 Key。
-
-### 其他方式
-
-- **环境变量**（不落盘到配置文件）：在 shell 中配置 API Key 环境变量；变量名见 `bl auth status --help`，勿在对话中向用户解释底层命名。
-- **写入配置文件**（持久化，与 `auth login` 落盘相同）：`bl config set --key api_key --value <key>`（`--key api-key` 亦可）。**不会**像 `bl auth login --api-key` 那样先校验 Key 是否可用；Agent 引导安装时仍**优先**用 `auth login`。
-- **命令行临时传入**：需要 API Key 的 `bl` 子命令可在**当次**执行附加全局 `--api-key <key>`，仅本次生效、不落盘（例：`bl text chat --api-key sk-xxx --message "你好"`）。与上文持久化方式不是同一用途。
+- 普通 Key：`bl auth login --api-key <Key>`
+- Token Plan：`bl auth login --config token-plan --api-key <Key>`
 
 ### Agent 安全约束
 
 - **禁止**把真实 API Key 写入仓库、日志、Skill、聊天记录的可公开部分。
-- CI / 非交互环境：使用 `bl ... --non-interactive`；通过密钥管理或环境变量注入，勿在脚本中硬编码 Key。
+- CI / 非交互环境：显式传入必填参数并使用 `--output json` 获取机器可读结果；如需纯文本输出，设置 `NO_COLOR=1`。通过密钥管理或环境变量注入，勿在脚本中硬编码 Key。
 
 ---
 
-## 4. 最小功能验证
-
-在鉴权配置完成后执行：
+## 4. 配置验证
 
 ```bash
 bl auth status --output json
-bl text chat --message "ping" --non-interactive --output json
 ```
 
-若失败：根据 stderr / JSON 中的 `hint` 或 `message` 排查（网络、Key 无效、`base_url` 等）。DashScope 端点：使用 `--base-url` / `bl config set --key base_url` / `DASHSCOPE_BASE_URL`，默认中国大陆 `https://dashscope.aliyuncs.com`。
+## 5. 安装成功后向用户说明（必做）
 
----
+安装与校验完成后，**主动**用中文向用户说明下列两项；不要等用户追问。可执行 `bl`（已登录时）对照终端 tip，但以下列表为准，勿臆造。
 
-## 5. 常见问题（Agent 排障清单）
+### 5.1 界面语言
 
-| 现象                    | 可能原因             | 建议动作                                                        |
-| ----------------------- | -------------------- | --------------------------------------------------------------- |
-| `bl: command not found` | 全局 bin 不在 PATH   | 检查 `npm prefix -g` 与 PATH                                    |
-| 安装报错 engines        | Node 版本过低        | 升级到 ≥ 22.12                                                  |
-| 401 / 鉴权失败          | 未 login 或 Key 无效 | 引导用户更新 Key 并 `bl auth login --api-key`                   |
-| 企业网络无法访问 npm    | 代理 / 镜像          | 配置 registry 或代理后再装                                      |
-| 本机只有 pnpm、没有 npm | Agent 误用 pnpm 安装 | 先装/修好 **npm**，再用 `npm install -g bailian-cli`；勿用 pnpm |
+Bailian CLI 支持中英文界面（help / 欢迎语 / Quick Start 主次文案）。默认 `en-US`，可切换为 `zh-CN`：
+
+```bash
+bl config set --key language --value zh-CN
+bl config set --key language --value en-US
+```
+
+向用户说明：可随时用上述命令切换语言。
+
+### 5.2 能力 tip（Quick Start）
+
+向用户展示「试试使用Bailian CLI完成这些任务」及下列 5 条（中英各一行，与 `bl` 根帮助 tip 一致）：
+
+1. 帮我创建一个能够生成短片分镜和视频的 Managed Agent。  
+   Help me create a Managed Agent that can generate short-film storyboards and videos.
+2. 生成一张穿着太空服的猫站在火星上的图片，再把它制作成一段视频。  
+   Generate an image of a cat in a spacesuit standing on Mars, then turn it into a video.
+3. 查看最近的模型用量、免费额度和限流情况。  
+   Check my recent model usage, free quota, and rate limits.
+4. 推荐一个适合图片理解和智能客服的模型。  
+   Recommend a model suitable for image understanding and intelligent customer service.
+5. 介绍一下 Bailian CLI 能帮我完成哪些任务，并根据我的需求推荐使用方式。  
+   Explain what Bailian CLI can help me accomplish, and recommend how to use it based on my needs.
+
+## 6. 常见问题
+
+| 现象                     | 可能原因                     | 建议动作                                                                                       |
+| ------------------------ | ---------------------------- | ---------------------------------------------------------------------------------------------- |
+| `bl: command not found`  | bin 不在 PATH                | 检查 `~/.local/bin` 或 `npm prefix -g`                                                         |
+| curl 安装 404            | GitHub Release 资产未上传    | 改用 `npm install -g bailian-cli`                                                              |
+| Windows `bl update` 失败 | 旧布局 / 文件锁 / 网络       | 重跑 `irm .../install.ps1 \| iex` 迁移布局后重试                                               |
+| `plugin` 需要 npm        | 二进制安装无本机 npm         | 安装 Node，或改用 npm 版 CLI                                                                   |
+| 安装报错 engines         | Node 版本过低（仅 npm 路径） | 升级到 ≥ 18.17.0                                                                               |
+| `bl skill init` 失败     | 网络 / registry 不可达等     | 有 Node 且有 Git 时降级 `npx skills@1.5.18 add modelstudioai/cli --all -g`；否则重试或告知用户 |

README.md

@@ -5,7 +5,7 @@
 **The official command-line interface for Aliyun Model Studio (DashScope) AI Platform**
 
 [![npm version](https://img.shields.io/npm/v/bailian-cli?color=0969da&label=npm)](https://www.npmjs.com/package/bailian-cli)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D22.12-brightgreen)](https://nodejs.org)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.17-brightgreen)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)](https://www.typescriptlang.org)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
 
@@ -13,8 +13,9 @@
 
 ---
 
-_Chat with Qwen, generate images & videos, understand images, call agents,_
-_manage memory, search the web — all from your terminal._
+_Chat with Qwen, generate and edit images and videos, understand images, synthesize_
+_and recognize speech, call apps, manage memory, retrieve knowledge, search the web —_
+_every AI capability, one command away._
 
 _Built for AI Agents. Every command works as a structured tool call._
 
@@ -22,27 +23,16 @@ _Built for AI Agents. Every command works as a structured tool call._
 
 ## Features
 
-Equip your AI Agent out-of-the-box with these capabilities, composable across complex tasks:
+- **Model generation** — Full-modality generation across text, image, video, and speech, with editing and reference-based generation
+- **Asset understanding** — Parse and ask questions about images, documents, audio, and long videos
+- **App orchestration** — Call Managed Agents, agents, and workflows published on Aliyun Model Studio, wired to knowledge bases, memory, web search, and MCP tools
+- **Training & deployment** — Validate and upload datasets, fine-tune models, deploy dedicated models as endpoints
+- **Account operations** — Login, UI-based configuration, model marketplace, usage and quota, rate-limit increases, team seat management
+- **Plan onboarding** — Connect subscription plans such as Token Plan to the CLI and common coding agents in one step
 
-- **Text chat** — Qwen3.7-max: major gains in agentic coding, frontend coding, and vibe coding
-- **Multimodal (Omni)** — Full omni-modal support across text + image + audio + video
-- **Image generation & editing** — Qwen-Image 2.0: pro text rendering, photorealism, strong semantic adherence, multi-image composition
-- **Video generation & editing** — happyhorse-1.1 series: text-/image-/reference-to-video and natural-language video editing (up to 9-image reference)
-- **Speech synthesis & recognition** — CosyVoice streaming TTS, voice cloning from 5–20s samples; FunAudio-ASR covers 30 languages including 7 Chinese dialects and 20+ Mandarin accents
-- **Image & video understanding** — Qwen-VL: long-form video analysis, chart/document parsing, visual reasoning, multilingual OCR
+> **Note:** App orchestration, training & deployment, account operations, and plan onboarding are currently available only to China site (aliyun.com) account holders and are not yet supported for international / global site accounts.
 
-> **Note:** The features below are currently available only to China site (aliyun.com) account holders and are not yet supported for international / global site accounts.
-
-- **Knowledge base & memory** — Multimodal RAG retrieval and cross-session memory for personalized, coherent dialogue
-- **App calls** — Invoke agents and workflows already published on Aliyun Model Studio
-- **MCP integration** — Orchestrate Bailian MCP servers: list services, inspect tools, and invoke any tool directly from the terminal
-- **Web search** — Real-time internet retrieval for up-to-date, accurate answers
-- **Model recommendation** — Describe your scenario and get best-fit model suggestions; supports scoped search, model comparison, and alternative discovery
-- **Fine-tuning & deployment** — Upload datasets, create text/audio/image fine-tune jobs (`finetune text|audio|image create`; text covers SFT/LoRA/DPO/CPT), probe job status non-blockingly (`finetune watch`), query per-model training capability (`finetune capability`), and deploy trained models as endpoints (`deploy text|audio|image create`)
-- **Console capabilities** — Browse the model marketplace (`model list`) and Bailian apps (`app list`), review a unified usage view (`usage summary`), check free-tier quota (`usage free`), view model usage statistics (`usage stats`), manage workspaces (`workspace list`), and manage rate limits (`quota list/request/check/history`)
-- **Local file auto-upload** — Every URL parameter accepts a local path; uploaded to free temp storage with 48-hour validity
-
-## Showcase: One-Sentence Cinematic Video
+## Showcase 1: A Cinematic Short Film from One Sentence
 
 <p align="center">
   <a href="https://cloud.video.taobao.com/vod/dS2F4huqbw5Nfe5L3wwb3grz2q2DNYD3retq8dU-iHo.mp4">
@@ -55,132 +45,114 @@ Equip your AI Agent out-of-the-box with these capabilities, composable across co
 A complete **2-minute, 16:9 cinematic short film** — produced end-to-end from a single natural-language sentence, with **zero manual editing**. This showcase demonstrates how an AI Agent can compose a multi-step creative pipeline by orchestrating three primitives:
 
 - **[Qwen Code](https://github.com/QwenLM/qwen-code)** — the agentic coding model that interprets the user's intent and drives the workflow
-- **[Aliyun Model Studio CLI](https://bailian.console.aliyun.com/cli?source_channel=cli_github&)** — invokes **HappyHorse 1.1**, Aliyun Model Studio's text-/image-/reference-to-video generation model
+- **[Aliyun Model Studio CLI](https://github.com/modelstudioai/cli/)** — invokes **HappyHorse 1.1**, Aliyun Model Studio's text-/image-/reference-to-video generation model
 - **[spark-video Skill](https://github.com/JohnKeating1997/spark-video)** — handles scene decomposition, storyboarding, shot continuity, and final stitching
 
 ### The single prompt
 
 > _"Generate a roughly 2-minute video in Japanese cinematic style — a sweet, innocent first-love story about a high-school girl. The plot should be heart-fluttering enough to make viewers want to fall in love. Aspect ratio: 16:9."_
->
-> _(Original: "帮我生成一段日系影视风格，高中女生的青涩初恋故事，剧情高甜，让人看了想谈恋爱，2分钟左右的视频，尺寸是16:9")_
 
-### How it works
+## Showcase 2: A Short-Film Director Managed Agent from One Sentence
 
-1. **Qwen Code** parses the request, plans the narrative beats, and decides which tools to call.
-2. The **spark-video Skill** breaks the story into shots, writes per-shot prompts, and enforces visual continuity (characters, lighting, palette, lens language).
-3. **`bl video generate`** dispatches each shot to **HappyHorse 1.1** in parallel.
-4. The skill stitches all clips back together into a single 16:9 / ~2-min deliverable.
+<p align="center">
+  <a href="https://cloud.video.taobao.com/vod/2v0GYLbJSQb2saj4iopTJDW3iRIHsintYlK-wTKbhqE.mp4">
+    <img src="https://img.alicdn.com/imgextra/i4/6000000001674/O1CN01xhzixhxltbH3LxWu_!!6000000001674-0-tbvideo.jpg" alt="Click to play the demo video" width="720" />
+  </a>
+</p>
 
-No timeline scrubbing. No frame-by-frame editing. Just one sentence → one video.
+<p align="center"><i>👆 Click the cover to play the full demo</i></p>
+
+One sentence builds a reusable cloud-side short-film director for storyboarding, storyboard image generation, and video creation:
+
+- **[Qwen Code](https://github.com/QwenLM/qwen-code)** — understands the requirement and generates the agent configuration
+- **[Aliyun Model Studio CLI](https://github.com/modelstudioai/cli/)** — validates the configuration, previews the changes, and completes the deployment
+- **[Managed Agent](https://bailian.console.aliyun.com/cn-beijing/?tab=managed-agents#/managed-agents/quick-start)** — runs the director role along with its skills and tools in the cloud
+
+### The single prompt
+
+> _"Build me a Managed Agent app that can produce short films — a director expert that generates videos and can also design the matching storyboards."_
 
 ## Installation
 
-```bash
-npm install -g bailian-cli
-npx skills add modelstudioai/cli --all -g
+**Agent install (recommended)**
+
+Send the following to your Agent — it will detect your environment, then install and verify the CLI for you:
+
+```text
+Please read https://bailian.aliyun.com/cli/install.md and install the Aliyun Model Studio CLI for me
 ```
 
-> Requires Node.js >= 22.12.
+**Install with NPM**
+
+```bash
+npm install -g bailian-cli
+bl skill init
+```
+
+> Requires Node.js >= 18.17.
+
+**Install on macOS/Linux**
+
+```bash
+curl -fsSL https://bailian.aliyun.com/cli/install.sh | bash
+```
+
+> No Node.js required. The installer automatically installs Bailian Skills.
+
+**Install on Windows**
+
+```powershell
+irm https://bailian.aliyun.com/cli/install.ps1 | iex
+```
+
+> No Node.js required. The installer automatically installs Bailian Skills.
 
 ## Quick Start
 
-```bash
-# Authenticate, recommended
-bl auth login --console
+Once installed, just describe your task to your AI Agent — no need to assemble commands by hand.
 
-# Or authenticate with an API key
-bl auth login --api-key sk-xxxxx
-
-# Chat with Qwen
-bl text chat --message "What is DashScope?"
-
-# Multimodal chat (text + image + audio + video)
-bl omni --message "Describe this image" --image ./photo.jpg
-
-# Generate an image
-bl image generate --prompt "A cat in a spacesuit" --out-dir ./images/
-
-# Generate a video from local image
-bl video generate --image ./cat.png --prompt "Make the cat move" --download cat.mp4
-
-# Model recommendation — find the best model for your use case
-bl advisor recommend --message "I need a visual-understanding chatbot"
-
-# Compare specific models
-bl advisor recommend --message "qwen-max vs deepseek-v3 for code generation"
-
-# Browser login (required for console capability commands)
-bl auth login --console
-
-# Fine-tune & deploy — a one-shot train-to-serve workflow
-bl dataset upload --file ./train.jsonl                 # Upload a .jsonl dataset (validated first)
-bl finetune text create --model qwen3-8b --datasets ./train.jsonl --training-type sft-lora  # Local paths auto-upload
-bl finetune watch --job-id ft-xxx --output json       # Non-blocking probe (running/succeeded return 0; failed/canceled report an error)
-bl finetune capability --model qwen3-8b               # Which training types a model supports
-bl deploy text create --model qwen3-8b --name my-svc --plan mu  # Deploy the trained model as an endpoint
-
-# Browse models / apps / free-tier quota / usage statistics / workspaces
-bl model list                                        # Browse model families and pricing
-bl app list
-bl usage summary                                     # Unified view: free-tier quota + recent usage overview
-bl usage free                                         # Free-tier quota across models (add --model/--expiring/--sort)
-bl usage stats --workspace-id <id>                    # Model usage statistics (add --model for per-model)
-bl workspace list                                     # List all workspaces
-
-# Rate limit management (list / check / request / history)
-bl quota list                                         # View RPM/TPM limits (add --model to filter)
-bl quota check                                        # Current usage vs rate limits (add --model/--period)
-bl quota request --model qwen3.6-plus --tpm 6000000   # Request a temporary TPM increase
-bl quota history                                      # View quota-change history
-
-# Token Plan team management (requires AK/SK, see auth below)
-bl token-plan list-seats                                # View subscription seat details
-bl token-plan add-member --account-name dev --org-id org_xxx
-bl token-plan assign-seats --workspace-id ws_xxx --seat-type standard --account-id acc_xxx
-bl token-plan create-key --account-id acc_xxx --workspace-id ws_xxx
-```
+| Scenario                 | What to say to your Agent                                                         |
+| ------------------------ | --------------------------------------------------------------------------------- |
+| Managed Agent            | "Create a Managed Agent that can generate short-film storyboards and videos."     |
+| Image & video generation | "Generate an image of a cat in a spacesuit on Mars, then turn it into a video."   |
+| Usage & quota            | "Show my recent model usage, free-tier quota, and rate limits."                   |
+| Model selection          | "Recommend a model for image understanding and customer support."                 |
+| About Bailian CLI        | "Tell me what Bailian CLI can do for me, and suggest how to use it for my needs." |
 
 > More examples and scenarios: [Aliyun Model Studio CLI Site](https://bailian.console.aliyun.com/cli?source_channel=cli_github&)
 
 ## Authentication
 
-### DashScope API Key
+### API Key
 
 Required for most commands. Get your key from the [DashScope Console](https://bailian.console.aliyun.com/cn-beijing/?source_channel=key_github&tab=app#/api-key).
 
 ```bash
-# Option 1: Environment variable
-export DASHSCOPE_API_KEY=sk-xxxxx
-
-# Option 2: Login command (persisted to ~/.bailian/config.json)
 bl auth login --api-key sk-xxxxx
+```
 
-# Option 3: Per-command flag
-bl text chat --api-key sk-xxxxx --message "Hello"
+Get or copy your Token Plan API key from the [Token Plan subscription overview](https://bailian.console.aliyun.com/cn-beijing?tab=plan#/efm/subscription/overview).
+
+```bash
+bl auth login --config token-plan --api-key sk-sp-xxxxx
 ```
 
 ### Console Login (OAuth)
 
-Required for console capability commands (`model list`, `app list`, `usage summary/free/stats`, `workspace list`, `quota list/request/check/history`). Opens the Bailian console in your browser to sign in.
+Required for console capability commands (model list, app list, MCP list, workspace, usage queries, rate-limit increases, direct console calls). Opens the Bailian console in your browser to sign in.
 
 ```bash
 bl auth login --console
 ```
 
-### Alibaba Cloud OpenAPI AK/SK (Token Plan only)
+### Alibaba Cloud OpenAPI AK/SK
 
-Required for the `token-plan` command group. Get your AccessKey from [RAM Console](https://ram.console.aliyun.com/manage/ak).
+Token Plan seat and member management requires an Alibaba Cloud AccessKey. Get yours from the [RAM Console](https://ram.console.aliyun.com/manage/ak).
 
 > Recommended: create a RAM sub-account with minimum privileges instead of using the root account's AK/SK.
 
 ```bash
-# Option 1: Login command (persisted to ~/.bailian/config.json)
 bl auth login --open-api --access-key-id LTAI5t... --access-key-secret ...
-
-# Option 2: Environment variables
-export ALIBABA_CLOUD_ACCESS_KEY_ID=LTAI5t...
-export ALIBABA_CLOUD_ACCESS_KEY_SECRET=...
-export BAILIAN_WORKSPACE_ID=ws-...
 ```
 
 ## Configuration
@@ -189,17 +161,34 @@ export BAILIAN_WORKSPACE_ID=ws-...
 # View current config
 bl config show
 
-# Set defaults
-bl config set --key base_url --value https://dashscope-us.aliyuncs.com
-bl config set --key default_text_model --value qwen-turbo
-bl config set --key timeout --value 600
+# List all config profiles
+bl config list
 
-# Self-update to latest version
-bl update
+# Switch config profile
+bl config use --name token-plan
+
+# Switch the CLI interface to Chinese
+bl config set --key language --value zh-CN
 ```
 
 Config file location: `~/.bailian/config.json`
 
+## Update
+
+```bash
+bl update
+```
+
+Upgrades the CLI to the latest version and refreshes the installed Agent Skills. Release notes for every version live in [CHANGELOG.md](https://github.com/modelstudioai/cli/blob/main/CHANGELOG.md).
+
+## Contributing
+
+Bug reports, feature requests, and PRs are welcome. See [CONTRIBUTING.md](https://github.com/modelstudioai/cli/blob/main/CONTRIBUTING.md) for developer setup, repo layout, and the workflow for adding or changing commands.
+
+Scan the QR code to join the Aliyun Model Studio CLI DingTalk user group for usage help, troubleshooting, bug reports, and tips from other users.
+
+<img src="https://img.alicdn.com/imgextra/i3/O1CN015uuhYGb6j0L12xJZ_!!6000000006304-2-tps-516-485.png" alt="Aliyun Model Studio CLI DingTalk user group" width="240" />
+
 ## Links
 
 | Resource                     | URL                                                                                       |
@@ -209,12 +198,5 @@ Config file location: `~/.bailian/config.json`
 | Qwen Model List              | https://help.aliyun.com/zh/model-studio/getting-started/models                            |
 | Aliyun Model Studio Console  | https://bailian.console.aliyun.com/?source_channel=cli_github                             |
 | Get API Key                  | https://bailian.console.aliyun.com/cn-beijing/?source_channel=key_github&tab=app#/api-key |
+| Get Token Plan API Key       | https://bailian.console.aliyun.com/cn-beijing?tab=plan#/efm/subscription/overview         |
 | Get AccessKey                | https://ram.console.aliyun.com/manage/ak                                                  |
-
-## Changelog
-
-Release notes for every version live in [CHANGELOG.md](https://github.com/modelstudioai/cli/blob/main/CHANGELOG.md).
-
-## Contributing
-
-Bug reports, feature requests, and PRs are welcome. See [CONTRIBUTING.md](https://github.com/modelstudioai/cli/blob/main/CONTRIBUTING.md) for developer setup, repo layout, and the workflow for adding or changing commands.

README.zh.md

@@ -5,7 +5,7 @@
 **阿里云百炼 (DashScope) AI 平台命令行工具**
 
 [![npm version](https://img.shields.io/npm/v/bailian-cli?color=0969da&label=npm)](https://www.npmjs.com/package/bailian-cli)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D22.12-brightgreen)](https://nodejs.org)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.17-brightgreen)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)](https://www.typescriptlang.org)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
 
@@ -22,27 +22,16 @@ _专为 AI Agent 打造，每个命令均可作为结构化工具调用。_
 
 ## 功能特性
 
-让您的 AI Agent 开箱即具备以下能力，并可在复杂任务中自动组合调用：
+- **模型生成** — 文本、图像、视频、语音全模态生成，支持编辑与参考生成
+- **素材理解** — 图像、文档、音频、长视频的解析与问答
+- **应用编排** — 调用百炼已发布的 Managed Agent、智能体和工作流，接入知识库、记忆库、联网搜索与 MCP 工具
+- **模型训推** — 数据集校验上传、模型精调、专属模型部署上线
+- **账号运维** — 授权登录、界面化配置、模型市场、用量与额度、限流提额、团队席位管理
+- **套餐接入** — 支持 Token Plan 等订阅计划一键接到 CLI 和常见 Coding Agent
 
-- **文本对话** — Qwen3.7-max：Agentic coding、前端编程、Vibe coding 等能力显著增强
-- **全模态对话** — 文本 + 图像 + 音频 + 视频全模态支持
-- **图像生成与编辑** — Qwen-Image 2.0：专业文字渲染、真实质感、强语义遵循、多图合成
-- **视频生成与编辑** — happyhorse-1.1 系列，支持文生 / 图生 / 参考生（最多 9 张图参考）/ 自然语言视频编辑
-- **语音合成与识别** — CosyVoice 实时流式合成，5-20s 样本即可克隆；FunAudio-ASR 覆盖 30 种语种，含汉语七大方言与 20+ 口音官话
-- **图像与视频理解** — Qwen-VL：长视频解析、复杂图表与文档识别、视觉推理、多语种 OCR
+> **注意：** 应用编排、模型训推、账号运维和套餐接入目前仅支持中国站（aliyun.com）账号，暂不支持国际站 / 全球站账号。
 
-> **注意：** 以下功能目前仅对中国站（aliyun.com）账号开放，国际站 / 全球站账号暂不支持。
-
-- **知识库与记忆库** — 多模态 RAG 检索 + 跨会话记忆，提供个性化连贯对话体验
-- **应用调用** — 调用已发布在阿里云百炼平台上的智能体与工作流应用
-- **MCP 集成** — 统一调度百炼 MCP 服务：列出服务、查看工具、直接在终端调用任意工具
-- **联网搜索** — 实时互联网信息检索，提升回答准确性及时效性
-- **模型推荐** — 描述你的场景，智能推荐最适合的模型；支持限定范围搜索、模型对比和替代发现
-- **微调与部署** — 上传数据集、创建文本/音频/图像调优任务（`finetune text|audio|image create`；文本涵盖 SFT/LoRA/DPO/CPT）、非阻塞探测任务状态（`finetune watch`）、按模型查训练能力（`finetune capability`），并把训练好的模型部署为推理服务（`deploy text|audio|image create`）
-- **控制台能力** — 浏览模型市场（`model list`）和百炼应用（`app list`），查看统一用量视图（`usage summary`），查询模型免费额度（`usage free`），查看模型用量统计（`usage stats`），管理业务空间（`workspace list`），管理限流与提额（`quota list/request/check/history`）
-- **本地文件自动上传** — 所有 URL 参数同时支持本地路径，免费临时存储 48 小时
-
-## 示例:一句话生成一部电影短片
+## 示例 1：一句话生成一部电影短片
 
 <p align="center">
   <a href="https://cloud.video.taobao.com/vod/dS2F4huqbw5Nfe5L3wwb3grz2q2DNYD3retq8dU-iHo.mp4">
@@ -52,133 +41,117 @@ _专为 AI Agent 打造，每个命令均可作为结构化工具调用。_
 
 <p align="center"><i>👆 点击封面播放完整 2 分钟演示</i></p>
 
-一部完整的 **2 分钟、16:9 电影感短片** —— 由一句自然语言端到端生成,**全程零手动剪辑**。这个示例展示了 AI Agent 如何把三个基础能力编排成一条多步创作流水线:
+一部完整的 **2 分钟、16:9 电影感短片** —— 由一句自然语言端到端生成，**全程零手动剪辑**。这个示例展示了 AI Agent 如何把三个基础能力编排成一条多步创作流水线：
 
-- **[Qwen Code](https://github.com/QwenLM/qwen-code)** —— Agentic coding 模型,解析用户意图、驱动整个工作流
-- **[阿里云百炼 CLI](https://github.com/modelstudioai/cli/)** —— 调用 **HappyHorse 1.1**,百炼的文生/图生/参考生视频模型
+- **[Qwen Code](https://github.com/QwenLM/qwen-code)** —— Agentic coding 模型，解析用户意图、驱动整个工作流
+- **[阿里云百炼 CLI](https://github.com/modelstudioai/cli/)** —— 调用 **HappyHorse 1.1**，百炼的文生/图生/参考生视频模型
 - **[spark-video Skill](https://github.com/JohnKeating1997/spark-video)** —— 负责场景拆分、分镜设计、镜头连贯性和最终拼接
 
 ### 唯一的提示词
 
-> _"帮我生成一段日系影视风格,高中女生的青涩初恋故事,剧情高甜,让人看了想谈恋爱,2 分钟左右的视频,尺寸是 16:9"_
+> _“帮我生成一段日系影视风格，高中女生的青涩初恋故事，剧情高甜，让人看了想谈恋爱，2 分钟左右的视频，尺寸是 16:9。”_
 
-### 工作流程
+## 示例 2：一句话构建短片导演 Managed Agent
 
-1. **Qwen Code** 解析需求、规划叙事节奏,决定要调用哪些工具。
-2. **spark-video Skill** 把故事拆成镜头、为每个镜头写提示词,并保证视觉连贯性(角色、光线、色调、镜头语言)。
-3. **`bl video generate`** 把每个镜头并行下发给 **HappyHorse 1.1**。
-4. Skill 把所有片段拼成最终的 16:9 / 约 2 分钟成片。
+<p align="center">
+  <a href="https://cloud.video.taobao.com/vod/2v0GYLbJSQb2saj4iopTJDW3iRIHsintYlK-wTKbhqE.mp4">
+    <img src="https://img.alicdn.com/imgextra/i4/6000000001674/O1CN01xhzixhxltbH3LxWu_!!6000000001674-0-tbvideo.jpg" alt="点击播放演示视频" width="720" />
+  </a>
+</p>
 
-没有时间线拖拽,没有逐帧剪辑。一句话 → 一部短片。
+<p align="center"><i>👆 点击封面播放完整演示</i></p>
+
+一句话构建一个可复用的云端短片导演，用于分镜设计、分镜图生成和视频创作：
+
+- **[Qwen Code](https://github.com/QwenLM/qwen-code)** —— 理解需求并生成 Agent 配置
+- **[阿里云百炼 CLI](https://github.com/modelstudioai/cli/)** —— 校验配置、预览变更并完成部署
+- **[Managed Agent](https://bailian.console.aliyun.com/cn-beijing/?tab=managed-agents#/managed-agents/quick-start)** —— 在云端运行导演角色及其 Skill 和工具
+
+### 唯一的提示词
+
+> _“帮我构建一个 managedagent 应用，能够实现短片拍摄，导演专家生成视频，然后也能进行设计对应的分镜图。”_
 
 ## 安装
 
-```bash
-npm install -g bailian-cli
-npx skills add modelstudioai/cli --all -g
+**Agent 安装（推荐）**
+
+把下面这句话发给你的 Agent，它会自行判断环境并完成安装与校验：
+
+```text
+请阅读：https://bailian.aliyun.com/cli/install.md 并按照说明为我安装阿里云百炼 CLI
 ```
 
-> 需要预先安装 Node.js >= 22.12。
+**NPM 安装**
+
+```bash
+npm install -g bailian-cli
+bl skill init
+```
+
+> 需要预先安装 Node.js >= 18.17。
+
+**macOS/Linux 安装**
+
+```bash
+curl -fsSL https://bailian.aliyun.com/cli/install.sh | bash
+```
+
+> 无需预先安装 Node.js，安装脚本会自动安装 Bailian Skills。
+
+**Windows 安装**
+
+```powershell
+irm https://bailian.aliyun.com/cli/install.ps1 | iex
+```
+
+> 无需预先安装 Node.js，安装脚本会自动安装 Bailian Skills。
 
 ## 快速开始
 
-```bash
-# 认证（推荐浏览器登录）
-bl auth login --console
+安装完成后，直接在 AI Agent 中描述你的任务，无需手动拼接命令。
 
-# 或使用 API key 认证
-bl auth login --api-key sk-xxxxx
-
-# 和通义千问对话
-bl text chat --message "你好，介绍一下阿里云百炼平台"
-
-# 多模态对话（文本 + 图片 + 音频 + 视频）
-bl omni --message "描述这张图片" --image ./photo.jpg
-
-# 生成图片
-bl image generate --prompt "一只穿太空服的猫在火星上" --out-dir ./images/
-
-# 图生视频（本地文件自动上传）
-bl video generate --image ./cat.png --prompt "让画面中的猫动起来" --download cat.mp4
-
-# 模型推荐 — 根据场景推荐最适合的模型
-bl advisor recommend --message "我要做一个能理解图片的客服机器人"
-
-# 对比特定模型
-bl advisor recommend --message "qwen-max 和 deepseek-v3 哪个更适合做代码生成"
-
-# 浏览器登录（控制台能力相关命令需要）
-bl auth login --console
-
-# 微调与部署 — 从训练到服务的一站式流程
-bl dataset upload --file ./train.jsonl                 # 上传 .jsonl 数据集（先校验）
-bl finetune text create --model qwen3-8b --datasets ./train.jsonl --training-type sft-lora  # 本地路径自动上传
-bl finetune watch --job-id ft-xxx --output json       # 非阻塞探测（运行中/成功返回 0；失败/取消报错）
-bl finetune capability --model qwen3-8b               # 查询模型支持哪些训练方式
-bl deploy text create --model qwen3-8b --name my-svc --plan mu  # 把训练好的模型部署为推理服务
-
-# 浏览模型 / 应用 / 免费额度 / 用量统计 / 业务空间
-bl model list                                        # 浏览模型系列与价格信息
-bl app list
-bl usage summary                                     # 统一视图：免费额度 + 近期用量概览
-bl usage free                                         # 各模型免费额度（可加 --model/--expiring/--sort）
-bl usage stats --workspace-id <id>                    # 模型用量统计（加 --model 查单模型）
-bl workspace list                                     # 列出所有业务空间
-
-# 限流管理与提额（list / check / request / history）
-bl quota list                                         # 查看 RPM/TPM 限额（加 --model 过滤）
-bl quota check                                        # 当前用量 vs 限流阈值（加 --model/--period）
-bl quota request --model qwen3.6-plus --tpm 6000000   # 申请临时 TPM 提额
-bl quota history                                      # 查看提额历史记录
-
-# Token Plan 团队版管理（需 AK/SK，见下方认证说明）
-bl token-plan list-seats                                # 查看订阅席位明细
-bl token-plan add-member --account-name dev --org-id org_xxx
-bl token-plan assign-seats --workspace-id ws_xxx --seat-type standard --account-id acc_xxx
-bl token-plan create-key --account-id acc_xxx --workspace-id ws_xxx
-```
+| 场景             | 可以这样对 Agent 说                                                     |
+| ---------------- | ----------------------------------------------------------------------- |
+| Managed Agent    | “帮我创建一个能够生成短片分镜和视频的 Managed Agent。”                  |
+| 图片和视频生成   | “生成一张穿着太空服的猫站在火星上的图片，再把它制作成一段视频。”        |
+| 用量与额度       | “查看最近的模型用量、免费额度和限流情况。”                              |
+| 模型选型         | “推荐一个适合图片理解和智能客服的模型。”                                |
+| 了解 Bailian CLI | “介绍一下 Bailian CLI 能帮我完成哪些任务，并根据我的需求推荐使用方式。” |
 
 > 更多案例与使用场景：[阿里云百炼 CLI 官方主页](https://bailian.console.aliyun.com/cli?source_channel=cli_github&)
 
 ## 认证方式
 
-### DashScope API Key
+### API Key
 
 大部分命令均需要 API Key。前往 [DashScope 控制台](https://bailian.console.aliyun.com/cn-beijing/?source_channel=key_github&tab=app#/api-key) 获取。
 
 ```bash
-# 方式一：环境变量
-export DASHSCOPE_API_KEY=sk-xxxxx
-
-# 方式二：登录命令（持久化到 ~/.bailian/config.json）
 bl auth login --api-key sk-xxxxx
+```
 
-# 方式三：命令行参数
-bl text chat --api-key sk-xxxxx --message "你好"
+Token Plan 的 API Key 前往 [Token Plan 订阅详情](https://bailian.console.aliyun.com/cn-beijing?tab=plan#/efm/subscription/overview) 获取或复制。
+
+```bash
+bl auth login --config token-plan --api-key sk-sp-xxxxx
 ```
 
 ### 控制台登录（OAuth）
 
-控制台能力命令（`model list`、`app list`、`usage summary/free/stats`、`workspace list`、`quota list/request/check/history`）需要使用此登录方式。打开浏览器跳转百炼控制台完成登录。
+控制台能力命令（模型列表、应用列表、MCP 列表、工作空间、用量查询、限流提额、控制台直调）需要使用此登录方式。打开浏览器跳转百炼控制台完成登录。
 
 ```bash
 bl auth login --console
 ```
 
-### 阿里云 OpenAPI AK/SK（仅 Token Plan）
+### 阿里云 OpenAPI AK/SK
 
-`token-plan` 命令组需要阿里云 AccessKey。前往 [RAM 控制台](https://ram.console.aliyun.com/manage/ak) 获取。
+Token Plan 的席位与成员管理需要阿里云 AccessKey。前往 [RAM 控制台](https://ram.console.aliyun.com/manage/ak) 获取。
 
 > 建议：创建 RAM 子账号并授予最小权限，避免使用主账号 AK/SK。
 
 ```bash
-# 方式一：登录命令（持久化到 ~/.bailian/config.json）
 bl auth login --open-api --access-key-id LTAI5t... --access-key-secret ...
-
-# 方式二：环境变量
-export ALIBABA_CLOUD_ACCESS_KEY_ID=LTAI5t...
-export ALIBABA_CLOUD_ACCESS_KEY_SECRET=...
-export BAILIAN_WORKSPACE_ID=ws-...
 ```
 
 ## 配置
@@ -187,17 +160,34 @@ export BAILIAN_WORKSPACE_ID=ws-...
 # 查看当前配置
 bl config show
 
-# 设置默认值
-bl config set --key base_url --value https://dashscope-us.aliyuncs.com
-bl config set --key default_text_model --value qwen-turbo
-bl config set --key timeout --value 600
+# 查看全部配置档
+bl config list
 
-# 自更新到最新版本
-bl update
+# 切换配置档
+bl config use --name token-plan
+
+# 将 CLI 界面切换为中文
+bl config set --key language --value zh-CN
 ```
 
 配置文件位置：`~/.bailian/config.json`
 
+## 更新
+
+```bash
+bl update
+```
+
+升级 CLI 至最新版本，并同步更新已安装的 Agent Skills。每个版本的变更详情记录在 [CHANGELOG.zh.md](https://github.com/modelstudioai/cli/blob/main/CHANGELOG.zh.md)。
+
+## 参与贡献
+
+欢迎提 Issue、Feature Request 和 PR。开发环境搭建、仓库结构、新增/修改命令的工作流请见 [CONTRIBUTING.zh.md](https://github.com/modelstudioai/cli/blob/main/CONTRIBUTING.zh.md)。
+
+欢迎扫码加入阿里云百炼 CLI 钉钉用户交流群，获取使用答疑、问题排查、Bug 反馈和使用经验交流支持。
+
+<img src="https://img.alicdn.com/imgextra/i3/O1CN015uuhYGb6j0L12xJZ_!!6000000006304-2-tps-516-485.png" alt="阿里云百炼 CLI 钉钉用户交流群" width="240" />
+
 ## 相关链接
 
 | 资源                    | 地址                                                                                      |
@@ -207,12 +197,5 @@ bl update
 | 通义千问模型列表        | https://help.aliyun.com/zh/model-studio/getting-started/models                            |
 | 阿里云百炼控制台        | https://bailian.console.aliyun.com/?source_channel=cli_github                             |
 | 获取 API Key            | https://bailian.console.aliyun.com/cn-beijing/?source_channel=key_github&tab=app#/api-key |
+| 获取 Token Plan API Key | https://bailian.console.aliyun.com/cn-beijing?tab=plan#/efm/subscription/overview         |
 | 获取 AccessKey          | https://ram.console.aliyun.com/manage/ak                                                  |
-
-## 更新日志
-
-每个版本的变更详情记录在 [CHANGELOG.zh.md](https://github.com/modelstudioai/cli/blob/main/CHANGELOG.zh.md)。
-
-## 参与贡献
-
-欢迎提 Issue、Feature Request 和 PR。开发环境搭建、仓库结构、新增/修改命令的工作流请见 [CONTRIBUTING.zh.md](https://github.com/modelstudioai/cli/blob/main/CONTRIBUTING.zh.md)。

docs/agents/auth-change.md

@@ -25,7 +25,7 @@ defineCommand({ auth }) → runtime/authStage → ctx.client → command.run(ctx
 当前 command 鉴权域(`AuthRequirement`):
 
 - `apiKey` — DashScope / OpenAI-compatible 模型域,用 API key 与 model base URL
-- `console` — Bailian Console Gateway,用 console access token + region/site/switchAgent/workspace
+- `console` — Bailian Console Gateway,用 console access token + region/site/switchAgent;`workspace_id` 是独立的 Settings 作用域,不属于 credential
 - `openapi` — 阿里云 OpenAPI 签名域,用 AccessKey ID/Secret 调用 Token Plan 等 OpenAPI
 - `none` — 本地命令、登录/配置类命令、无需 credential 的命令
 
@@ -33,19 +33,23 @@ defineCommand({ auth }) → runtime/authStage → ctx.client → command.run(ctx
 
 `~/.bailian/config.json` 可同时保存 `api_key`、`access_token` 与 `access_key_*`。登录任一种方式不得删除另一种:
 
-- `bl auth login --api-key ...` 只更新 `api_key` / `base_url`
+- `bl auth login --api-key ...` 更新 `api_key`;显式 `base_url` 会一并写入，所选命名 Profile 若命中内置套餐预设（当前为 `token-plan`），则在尚未保存 `base_url` 时补写预设地址，并把该预设的默认模型物化写入。API Key 落盘成功后，`api_key_capabilities` 保留已有项并追加当前 preset 中缺少的项，不自动删除任何已有能力；无 preset 的自定义 Profile 不做合并。登录仍不得删除其他鉴权域的凭证
 - `bl auth login --console` 只更新 `access_token` 以及回调携带的 console 作用域字段
-- `bl auth login --open-api ...` 只更新 `access_key_id` / `access_key_secret`
+- `bl auth login --open-api ...` 更新 `access_key_id` / `access_key_secret`,同时会调用 OpenAPI 生成 CLI `access_token` 并一并写入;即一次 `--open-api` 登录同时产生 `openapi` 与 `console` 域凭证
 - `bl auth logout --console` 只清 `access_token`
 - `bl auth logout --open-api` 只清 `access_key_id` / `access_key_secret` / `security_token`
-- `bl auth logout` 清 `api_key` + `access_token` + `access_key_*`
+- `bl auth logout` 清 `api_key` + `base_url` + `access_token` + `access_key_*`
 
 解析分工:
 
 - `resolveApiKey()` — `auth: "apiKey"` 命令;优先级 `--api-key` > `DASHSCOPE_API_KEY` > config `api_key`
-- `resolveModelBaseUrl()` — model base URL;优先级 `--base-url` > `DASHSCOPE_BASE_URL` > config `base_url` > `REGIONS.cn`，返回前统一去除 query、fragment、尾斜杠和已知 SDK/API Base 后缀，同时保留自定义网关前缀
-- `--config` 只选择 config 文件 block，不提升该 block 的字段优先级；内置套餐 Profile（当前为 `token-plan`）的预设仅在登录时物化写入，运行时继续走统一的 flag > env > selected config file > 默认值
-- 显式 `auth login --config <name>` 在凭证验证并落盘成功后自动激活目标 Profile；未传
+- `resolveModelBaseUrl()` — model base URL;优先级 `--base-url` > `DASHSCOPE_BASE_URL` > config `base_url` > `REGIONS.cn`，返回前统一归一化为 URL origin（仅保留协议、host 和显式端口，去除 path、query、fragment）
+- `--config` 只选择 config 文件 block，不提升该 block 的字段优先级。对 `auth: "apiKey"` 命令，runtime 会先按叶子命令路径检查所选 Profile 的 `api_key_capabilities`:
+  - `--api-key` / `--base-url` 或 `DASHSCOPE_API_KEY` / `DASHSCOPE_BASE_URL` 任一显式连接覆盖存在时，完全跳过自动降级，继续走统一的 flag > env > selected config file > 默认值
+  - 配置文件显式声明 `api_key_capabilities` 后，命中能力时保留所选 Profile，未命中时仅把 file-backed `api_key` / `base_url` 来源切到顶层 `default`，其他 Settings 仍来自所选 Profile
+  - 字段缺失时不启用降级，包括命中内置套餐预设的 Profile；preset 只在 API Key 登录落盘成功后物化写入，升级 preset 需要重新登录
+  - fallback 反馈写 stderr:text 模式输出本地化句子，`--output json` 输出两空格缩进的多行 `warning` 对象;若后续鉴权失败，warning 与多行 `error` 对象以空行分隔，stdout 仍只保留命令结果
+- 显式 `auth login --config <name>` 在凭证落盘成功后自动激活目标 Profile；未传
   `--config` 时继续写当前激活项，失败和 dry-run 不切换
 - `resolveConsole()` — `auth: "console"` 命令;当前 token 来自 config `access_token`,region/site/switchAgent 来自 flag > config > 默认
 - `resolveOpenApi()` — `auth: "openapi"` 命令;优先级 `--access-key-id/--access-key-secret` > `ALIBABA_CLOUD_ACCESS_KEY_ID/ALIBABA_CLOUD_ACCESS_KEY_SECRET` > config `access_key_*`。兼容读取旧字段 `openapi_access_key_*`,新写入只写短字段
@@ -53,6 +57,25 @@ defineCommand({ auth }) → runtime/authStage → ctx.client → command.run(ctx
 
 命令不要直接解析 token、env 或 config。业务请求统一走 `ctx.client`;登录/配置命令通过 `ctx.authStore` / `ctx.configStore` 的窄接口操作落盘。
 
+### 例外:agent 命令的分层鉴权与 SDK 凭证内存注入
+
+`bl managed-agent *` 按调用链分两层:
+
+- **离线命令** — `init`、`validate`、`state list/show/rm`:`auth: "none"`，只读写本地文件，无需登录;引擎侧传 `credentials: "none"` 跳过凭证断言
+- **联网命令** — `plan`、`apply`、`destroy`、`state import`、`skill-list`、全部 `session *`:统一声明 `auth: "apiKey"` 硬门禁，authStage 经 `resolveApiKey(sources)` 解析 Bailian 凭证(flag > env > active profile config)，缺失报统一 AUTH;引擎层再断言 Bailian key 非空。例外:`plan --no-refresh` / `plan --dry-run` 传 `credentials: "none"` 并强制 `refresh: false`（不联网、不回写 state，不查 provider key），其中 `--dry-run` 连登录也不要求（authStage 的 dry-run 豁免），`--no-refresh` 仍需登录。
+
+`bl managed-agent` 是 Bailian-only 产品入口：命令不暴露 `--provider`，`init` 只生成 `providers.bailian`，所有远端调用固定传 `provider: "bailian"`。`resolveAgentProjectConfig` 在创建 SDK runtime 前通过 `assertBailianOnlyProviders` 拒绝包含非 Bailian Provider 的手写配置；共享 `@openagentpack/sdk` 仍可保留多 Provider 能力。
+
+凭证不以真实值写入 `process.env`，而是经 `packages/commands/src/commands/managed-agent/_engine/` 的**内存注入管道**(`resolveAgentProjectConfig`)注入 SDK，管道五步:
+
+1. `prepareProviderEnv()` — 调用 SDK 的凭证 bootstrap，再把凭证类 env(`CREDENTIAL_ENV_KEYS`，含兼容别名)中仍为 undefined 的项占位为 `""`，使 agents.yaml 插值阶段能够完成并由 CLI 输出明确的 Bailian-only 配置错误
+2. `resolveProjectConfig` — 完成插值；随后 `normalizeInterpolatedProviderBlocks()` 把插值为空导致的 YAML `null` 归一为 `""`，避免空 key 在 SDK zod 层提前报 "received null"
+3. `injectProviderCredentials()` — 用 `ctx.client.exportApiCredential()`(lint 限定 `managed-agent/_engine/**` 可用)覆写内存 config 对象的 bailian 块:有凭证时 `api_key` 无条件覆写;`base_url`(拼 `/api/v1/agentstudio` 后缀，无凭证时用 client 默认域名补齐以满足 schema)/`workspace_id`(取 `settings.workspaceId`)仅在引用且为空时填充
+4. `scrubCredentialEnv()` — 从 `process.env` 删除全部凭证变量(真实凭证此后只存于 config 对象 → provider adapter 实例内存，不驻留 env / 不被子进程继承)
+5. `assertBailianOnlyProviders(providers)` — 拒绝非 Bailian Provider；随后 `assertProviderCredentials(providers)` 在 Bailian `api_key` 为空时给出 CLI 权威 `AUTH` 错误和登录 hint；离线命令传 `credentials: "none"` 跳过 key 断言，但仍执行 Bailian-only 配置校验
+
+禁止命令层直接 `readConfigFile` 裸读凭证；Bailian 字段以 CLI 鉴权链为唯一信源。SDK bootstrap 期间读取到的兼容凭证变量也会在配置解析后统一清扫。
+
 ## 必查清单
 
 ### A. core 层(类型 + 解析)
@@ -61,6 +84,9 @@ defineCommand({ auth }) → runtime/authStage → ctx.client → command.run(ctx
   - 如新增鉴权域,扩展 `AuthRequirement`
   - 更新 `credentialFlagDefs()` 暴露该域可见的 flag
   - 必要时新增 `*_AUTH_FLAGS`
+  - `workspace_id` 是作用域字段而非 credential,不要把它放进 `ConsoleCredential`;读取方式按命令 `auth` 域区分:
+    - `auth: "console"` 命令通过 `CONSOLE_AUTH_FLAGS` 自动获得 `--workspace-id`,由 `buildSettings()` 解析到 `settings.workspaceId`,命令统一从 `settings.workspaceId` 读取
+    - `auth: "apiKey"`/`"openapi"`/`"none"` 命令如需 `--workspace-id`,必须自声明 flag;因它不会进入 credential/global flags,命令从 `ctx.flags.workspaceId` 读取(可回退到 `settings.workspaceId`)
 - [ ] `packages/core/src/auth/types.ts`:
   - 新增 credential 类型 / source / scope 字段
 - [ ] `packages/core/src/auth/resolver.ts`:
@@ -104,7 +130,7 @@ defineCommand({ auth }) → runtime/authStage → ctx.client → command.run(ctx
 ### D. 用户面文档
 
 - [ ] `README.md` / `README.zh.md` "Authentication" 段落
-- [ ] `skills/bailian-cli/reference/` 通过 `pnpm run sync:skill-assets` 重建
+- [ ] 各 `skills/<skill>/reference/` 通过 `pnpm run sync:skill-assets` 重建
 
 ### E. 测试
 
@@ -114,6 +140,8 @@ defineCommand({ auth }) → runtime/authStage → ctx.client → command.run(ctx
 
 ## 完成后自查
 
+本仓库同时存在 `bl`(packages/cli) 与 `kscli`(packages/kscli) 两个入口,二者共享 core/runtime 鉴权链路,但暴露的命令不同。如果改动会影响两个入口共用的命令或错误提示,再分别验证它们各自实际暴露的路径;不要假设 `kscli` 也有 `bl auth *` 命令。
+
 ```sh
 # 各种凭证组合
 unset DASHSCOPE_API_KEY ALIBABA_CLOUD_ACCESS_KEY_ID ALIBABA_CLOUD_ACCESS_KEY_SECRET
@@ -133,9 +161,11 @@ Console 登录/网关相关改动:
 
 ```sh
 pnpm -F bailian-cli exec tsx src/main.ts auth login --console
-pnpm -F bailian-cli exec tsx src/main.ts usage stats --dry-run --output json
+pnpm -F bailian-cli exec tsx src/main.ts usage stats --dry-run --output json --workspace-id ws-xxx
 ```
 
+注意:`usage stats --dry-run` 仍会先校验 workspace,必须传入 `--workspace-id`(或 `BAILIAN_WORKSPACE_ID` / config `workspace_id`)。
+
 ## 常见漏点
 
 - ✗ 加了新 token 来源但忘了改 resolver 优先级,实际不生效

docs/agents/branch-merge-review.md

@@ -56,7 +56,7 @@ git diff --name-only <base>...<head>
 
 - [ ] **新命令 / 新 flag** 已同步到用户面文档:
   - [README.md](README.md) + [README.zh.md](README.zh.md)(中英文都要,常漏 `_CN`)
-  - `skills/bailian-cli/reference/` + `skills/bailian-cli/SKILL.md` 通过 `pnpm run sync:skill-assets` 更新并提交
+  - 各 `skills/<skill>/reference/` + 对应 `SKILL.md` 通过 `pnpm run sync:skill-assets` 更新并提交
 - [ ] **`bl <cmd> --help`** 文案完整:`description` / `examples` 都填了
 - [ ] **demo / quickstart**:用户可调用的新命令至少有一个示例
 - [ ] **行为变化的老命令**:在 commit message / CHANGELOG 注明用户感知的差异

docs/agents/cli-e2e-tests.md

@@ -2,15 +2,16 @@
 
 ## 架构分层
 
-| 层级            | 路径                                                  | 测什么                                                                                   |
-| --------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| **共享基建**    | `packages/e2e`                                        | gating、子进程 runner、output、globalSetup（`private`，不发布）                          |
-| **命令 E2E**    | `packages/commands/tests/e2e`                         | help、缺参、dry-run、live（gated）；每用例最小路由                                       |
-| **bl smoke**    | `packages/cli/tests/e2e/registry.smoke.e2e.test.ts`   | 产品 map 全部 path `--help`、分组 help、根 help                                          |
-| **kscli smoke** | `packages/kscli/tests/e2e/registry.smoke.e2e.test.ts` | 从 `kscli/src/commands.ts` 推导 path/分组；identity（`--version`、`search --help` path） |
-| **runtime**     | `packages/runtime/tests`                              | `proxy.e2e`、console 跨域 flag 拒绝                                                      |
+| 层级            | 路径                                                  | 测什么                                                                                  |
+| --------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| **共享基建**    | `packages/e2e`                                        | gating、子进程 runner、registry help 捕获、output、globalSetup（`private`，不发布）     |
+| **命令 E2E**    | `packages/commands/tests/e2e`                         | 进程内 help、子进程缺参/dry-run/live（gated）；每用例最小路由                           |
+| **Journey E2E** | `packages/commands/tests/e2e/knowledge/journeys`      | 用户旅程全链路（跨命令回路 + 标记词召回闭环），全部 live gated；见 `journeys/README.md` |
+| **bl smoke**    | `packages/cli/tests/e2e/registry.smoke.e2e.test.ts`   | 产品 map 全部 path/分组的进程内 help；根 help、鉴权域等代表性子进程冒烟                 |
+| **kscli smoke** | `packages/kscli/tests/e2e/registry.smoke.e2e.test.ts` | map 全部 path/分组的进程内 help；`--version`、`search --help` 等代表性子进程冒烟        |
+| **runtime**     | `packages/runtime/tests`                              | `proxy.e2e`、console 跨域 flag 拒绝                                                     |
 
-**依赖边界**：`e2e` → `core`；`commands/tests` → `e2e` + `commands/src`；产品 tests → `e2e` + 各自 `src`。**禁止**产品 import `commands/tests/**`（子进程 spawn harness 路径除外）。
+**依赖边界**：`e2e` → `core`；`commands/tests` → `e2e` + `commands/src`；产品 tests → `e2e` + 各自 `src` + `runtime` 公共 API。**禁止**产品 import `commands/tests/**`（子进程 spawn harness 路径除外）。
 
 ## 触发条件
 
@@ -27,8 +28,9 @@
 
 ### commands E2E
 
-- 路径：`packages/commands/tests/e2e/<kebab-topic>.e2e.test.ts`
-- 子进程：`runCommandE2e(routes, args)` from `./helpers.ts`（spawn `harness/main.ts`，`routes` 为本 topic 最小 path → export 映射）
+- 路径：`packages/commands/tests/e2e/<kebab-topic>.e2e.test.ts`；knowledge 领域集中在 `packages/commands/tests/e2e/knowledge/` 子目录（新增 knowledge 命令测试放这里）
+- help：`runCommandHelp(routes, [...path, "--help"])` from `./helpers.ts`（当前 Vitest worker 内用真实 command + `CommandRegistry` 渲染，不启动子进程）
+- 子进程：缺参、dry-run、live 使用 `runCommandE2e(routes, args)`（spawn `harness/main.ts`，`routes` 为本 topic 最小 path → export 映射）
 - fixtures：`packages/commands/tests/e2e/fixtures/`
 - 路由常量：`topic-routes.ts`（按 topic 维护，**非**全量产品 map）
 
@@ -36,10 +38,12 @@
 
 - bl：`runCli` from `packages/cli/tests/e2e/helpers.ts`
 - kscli：`runKscli` from `packages/kscli/tests/e2e/helpers.ts`
+- 全量 leaf/group help 使用产品 `commands` 创建 `CommandRegistry`，先通过 `resolve([...path, "--help"])` 检查 help 路由，再用 `captureRegistryHelp` 检查完整 Usage；禁止在 `test.each(commandPaths/groupPaths)` 中逐条启动 `tsx` 子进程
+- 真实子进程只保留根 help/version、产品身份、代表性叶子 help/鉴权域和缺参退出码等 shell/stdio/env 契约
 
 ### 共享
 
-- gating / output / runner：`e2e/gating`、`e2e/output`、`e2e/runner`
+- gating / output / runner：`e2e/gating`、`e2e/output`、`e2e/runner`；runner 使用 `node --import tsx` 执行 TypeScript 入口，不启动 tsx CLI IPC server
 - globalSetup：根 `vite.config.ts` → `packages/e2e/src/global-setup.ts`
 - 解析 JSON stdout：`parseStdoutJson`；输出目录：`makeE2eOutputDir(e2eLabelFromMetaUrl(import.meta.url))`
 - 长任务：`cliTimeoutPrefix()`；视频用例加 `test(..., 3_600_000)` 等显式超时
@@ -47,9 +51,12 @@
 ## 双层 describe（固定结构）
 
 ```ts
-// 1) 不 skip：--help，无密钥、无真实 API（分组 help 由 bl registry.smoke 覆盖）
+// 1) 不 skip：进程内 --help，无密钥、无真实 API（分组 help 由 bl registry.smoke 覆盖）
 describe("e2e: <topic>", () => {
-  test("<subcommand> --help 正常退出", ...);
+  test("<subcommand> --help 正常退出", async () => {
+    const result = await runCommandHelp(FOO_ROUTES, ["foo", "bar", "--help"]);
+    expect(result.exitCode, result.stderr).toBe(0);
+  });
 });
 
 // 2) skipIf：缺参 / dry-run / 真实集成
@@ -73,11 +80,26 @@ describe.skipIf(<ready>)("e2e: <topic>（DashScope …）", () => {
 
 ## 用例类型
 
-1. **--help**：`runCommandE2e(ROUTES, [..., "--help"])` → stderr 含主要 flags
+1. **--help**：`runCommandHelp(ROUTES, [..., "--help"])` → stderr 含主要 flags；产品层另保留少量真实子进程 help 验证 shell/stdio/env
 2. **缺参**：带无害全局 flag（如 `--quiet`）且不传 required flag → `exitCode === 2`
 3. **--dry-run**：实现在联网/上传/写盘**之前**返回；断言 stdout JSON/文本
 4. **真实集成**：放在 skip 块**末尾**
 
+高风险命令额外要求：
+
+- `--help` 展示 runtime 注入的 `--yes`
+- 无 `--yes` 返回 exit code 7 和 JSON `type: "requires_confirmation"`
+- `--dry-run` 无需 `--yes`，且必须证明在任何远端请求或本地写入之前返回
+- runtime 的离线 high-risk fixture 必须覆盖带 `--yes` 确实进入 `run()`，并断言 `yes` 不进入 command 自有 flags
+
+## Journey 层（用户旅程全链路）
+
+- **定位**：命令 E2E 验单命令契约；journey 验“用户带着目标跨命令走通回路”，结构性断言不在 journey 重复
+- **闭环断言**：fixture 埋独特标记词，以“标记词能否被召回”判定回路闭合；硬断言 fail，软断言 `recordSoft` 落报告人工复核
+- **日志产物**：`createJourneyReporter` 在 `test/output/<session>/` 落盘 `journey-report.md`、分步 stdout/stderr、`resources.json`（未清理资源警示）
+- **入口**：`pnpm run test:journey`；旅程清单与约定见 [journeys/README.md](../../packages/commands/tests/e2e/knowledge/journeys/README.md)
+- **新增命令时**：评估是否属于某条旅程的环节，是则纳入对应 journey 并更新 README 映射表
+
 ## 增删命令同步
 
 - **commands export** + **topic 路由**（`topic-routes.ts` 或测试文件内 `ROUTES`）+ **产品 map**（`cli/commands.ts` / `kscli/commands.ts`）
@@ -85,7 +107,8 @@ describe.skipIf(<ready>)("e2e: <topic>（DashScope …）", () => {
 
 ## 安全与例外
 
-- **禁止真实破坏性操作**：`auth logout` 只用 `--dry-run`；`config set` 只用 `--dry-run`
+- **禁止破坏真实用户配置**：`auth logout` 和 `config set` 默认只用 `--dry-run`；只有验证持久化契约时，才允许通过
+  `BAILIAN_CONFIG_DIR` 指向每个用例独占的临时目录实际落盘，并必须在 `finally` 中清理；禁止写入或复用真实 `~/.bailian`
 - **不加 dry-run**：`dryRun` 在 `resolveFileUrl` / `resolveCredential` / 上传**之后**的命令（如 `image edit`、`speech recognize` 带 `--url`）
 - **`--list-voices` 等旁路**：先于 `--text` 校验的 flag，缺参用例勿带该 flag
 - 新增 required option → 至少一条缺参用例；改 dry-run 输出 → 更新对应断言
@@ -94,8 +117,8 @@ describe.skipIf(<ready>)("e2e: <topic>（DashScope …）", () => {
 
 - [ ] `packages/commands/src/index.ts` 导出 + `packages/cli/src/commands.ts` 暴露路径 + `topic-routes.ts` 补最小路由
 - [ ] `packages/commands/tests/e2e/<topic>.e2e.test.ts`（新建或扩展）
-- [ ] 若改了 `usageArgs` / `flags` / `exampleArgs`,跑 `pnpm --filter bailian-cli run generate:reference` 更新 `skills/bailian-cli/reference/` 并提交
-- [ ] 子命令 `--help`（分组 help 由 bl `registry.smoke` 覆盖）
+- [ ] 若改了 `usageArgs` / `flags` / `exampleArgs`,跑 `pnpm --filter bailian-cli run generate:reference` 更新各 `skills/<skill>/reference/` 并提交
+- [ ] 子命令 `--help` 使用 `runCommandHelp`（分组 help 由 bl `registry.smoke` 覆盖）
 - [ ] skip 块：每个 required flag 缺参；可 dry-run 则加一条
 - [ ] 至少一条真实集成（或说明为何仅 smoke）；不破坏已有集成用例顺序
 - [ ] `vp test packages/commands/tests/e2e/<file>` 通过

docs/agents/command-add-remove.md

@@ -56,7 +56,7 @@ packages/commands/src/index.ts
 - **`packages/cli/src/commands.ts`**:`bl` 产品命令 map;新增/删除/重命名 `bl` 命令必须改这里
 - **`packages/kscli/src/main.ts`**:`kscli` 产品命令 map;只有该入口需要暴露/变更时才改
 - **`packages/runtime/src/registry.ts`**:通用 registry,从传入 map 建树;不要在这里登记业务命令
-- **`tools/generate-reference.ts`**:pre-commit / `pnpm run sync:skill-assets` 时读 `packages/cli/src/commands.ts`,写 `skills/bailian-cli/reference/index.md` + `<一级命令>.md`。该目录**纳入 git**,勿手改
+- **`tools/generate-reference.ts`**:pre-commit / `pnpm run sync:skill-assets` 时读 `packages/cli/src/commands.ts`,按 `GROUP_OWNER_SKILL` 归属表分流写到各 `skills/<skill>/reference/index.md` + `<一级命令>.md`。未显式归属的一级组默认进 `bailian-cli`。各目录**纳入 git**,勿手改。新增一级命令组若应归领域 skill,记得改归属表。
 
 已删除/勿再引用:旧的 `packages/cli/src/commands/catalog.ts`、旧的 `packages/cli/src/commands/index.ts` catalog re-export、`packages/cli/src/registry.ts`、`skipDefaultApiKeySetup`、`ensureApiKey` 启动拦截、`config/export-schema.ts`。
 
@@ -71,9 +71,12 @@ packages/commands/src/index.ts
   - `usageArgs`(不含 bin/path 前缀)
   - `exampleArgs`(不含 bin/path 前缀)
   - `validate`(跨 flag 校验)
+  - 高风险命令必须声明 `risk: { level: "high", message: <双语文案> }`;`--yes` 由 runtime 注入,命令不得自行声明
   - 普通业务命令的 `run(ctx)` 只读 `ctx.flags` / `ctx.settings` / `ctx.client`
+  - 声明 `risk` 的 `run(ctx)` 必须在任何远端请求或本地写入之前处理 `ctx.settings.dryRun` 并返回预览;runtime 只负责确认闸门,不替命令实现 dry-run
   - `commands/auth/**` 可用 `ctx.authStore`,`commands/config/**` 可用 `ctx.configStore`;不要把这些持久化能力扩散到普通业务命令
   - `commands/plugin/**` 可用 `ctx.commandPacks`;产品 policy 由 runtime 绑定,命令不要自行 import 产品入口
+- [ ] 用户可见 Help 文案在命令文件中就近提供 `en-US` / `zh-CN`:命令 `description`、flag `description`、`notes` 和包含自然语言的 `exampleArgs`;纯命令语法示例可保留为字符串,服务端错误不翻译
 - [ ] `packages/commands/src/index.ts`:新增或移除对应 export
 - [ ] 如果命令调用 Console Gateway,设置 `auth: "console"`;不要重复声明 console 凭证域 flags
 - [ ] 如果命令不需要网络或自己管理配置/登录,设置 `auth: "none"`;不要绕过 runtime auth stage
@@ -87,9 +90,10 @@ packages/commands/src/index.ts
 
 ### C. 文档层
 
-- [ ] 运行 `pnpm run sync:skill-assets`(或正常 `git commit` 走 pre-commit),刷新 `skills/bailian-cli/reference/` 与 `SKILL.md` 的 `metadata.version` 并提交
+- [ ] 运行 `pnpm run sync:skill-assets`(或正常 `git commit` 走 pre-commit),刷新各 `skills/<skill>/reference/` 与 `SKILL.md` 的 `metadata.version` 并提交
 - [ ] `README.md` / `README.zh.md`:Quick Start、命令一览、认证说明(用户向,与 help 对齐)
-- [ ] `skills/bailian-cli/SKILL.md`:若安装说明或能力边界有变,同步更新
+- [ ] 相关 `skills/<skill>/SKILL.md`:若安装说明或能力边界有变,同步更新;新一级命令组若属领域 skill,同步改 `tools/generate-reference.ts` 的 `GROUP_OWNER_SKILL`
+- [ ] **拥有方** skill 的「When to use which command」(或等价路由表)补上新意图;hub `bailian-cli` 仅加/改 hand-off 行,**不要**把领域子命令与默认模型抄进 hub 表(约定见 [skill-change.md](skill-change.md))
 
 ### D. 测试层
 
@@ -105,7 +109,7 @@ packages/commands/src/index.ts
   - `packages/cli/src/commands.ts` map key
   - `packages/kscli/src/commands.ts` map key(如适用)
   - 用户可见 hint / README / tests
-  - `skills/bailian-cli/reference/`(重建后检查并提交)
+  - `skills/*/reference/`(重建后检查并提交)
 - [ ] 检查 `usageArgs` / `exampleArgs` 没有硬编码旧的 `bl <path>` 前缀
 
 ## 完成后自查
@@ -127,7 +131,9 @@ pnpm -F knowledge-studio-cli exec tsx src/main.ts <command> --help
 
 - ✗ 只新增 `packages/commands/src/commands/...` 文件,忘了在 `packages/commands/src/index.ts` 导出
 - ✗ 只导出了命令实现,忘了在 `packages/cli/src/commands.ts` 暴露路径 → `bl --help` 看不到
-- ✗ 手改 `skills/bailian-cli/reference/*.md` → 下次 generate 被覆盖;应改 command metadata 后重新 generate 并提交
+- ✗ 手改 `skills/*/reference/*.md` → 下次 generate 被覆盖;应改 command metadata 后重新 generate 并提交
+- ✗ 新一级命令组忘改 `tools/generate-reference.ts` 的 `GROUP_OWNER_SKILL` → reference 会落到 hub `bailian-cli`(未必是预期)
+- ✗ 只改 reference / hub,忘改拥有方 skill 路由表;或把领域命令明细重新抄回 `bailian-cli` SKILL → 与 [skill-change.md](skill-change.md) 分层冲突
 - ✗ 在 `usageArgs` / `exampleArgs` 写死 `bl text chat` → `kscli` 等入口复用时 help 错
 - ✗ Console Gateway 命令忘设 `auth: "console"` → console flags / credential 注入都不生效
 - ✗ 单 action 的子组是反模式,新增时优先拍平为两级

docs/agents/command-flag-change.md

@@ -19,6 +19,7 @@
   - 类型由 `ParsedFlags<typeof FLAGS>` 推导;避免手写 `flags.x as number` 这类断言
   - 单 flag 必填用 `required: true`;跨 flag / 值相关校验放 `validate`
   - 默认值 fallback 写在命令实现或 `Settings` 解析层,不要重复解析 env/config
+  - 需要在高风险确认前检查本地路径时,可用异步 `validate`;runtime 会在鉴权和确认前等待它完成。这里只允许本地只读检查,不写文件、不请求远端。非缺参的环境错误应抛出 `BailianError`,避免裸命令调用被当成缺参而仅显示 help。
 
 ### B. 鉴权 / 全局选项
 
@@ -30,7 +31,7 @@
 ### C. 文档层
 
 - [ ] `README.md` / `README.zh.md` 如果在示例里展示了相关命令,补充新 flag
-- [ ] 跑 `pnpm --filter bailian-cli run generate:reference`,让 `skills/bailian-cli/reference/` 与命令一致(勿手改;改完提交)
+- [ ] 跑 `pnpm --filter bailian-cli run generate:reference`,让各 `skills/<skill>/reference/` 与命令一致(勿手改;改完提交)
 
 ### D. 测试层
 

docs/agents/command-pack.md

@@ -32,6 +32,8 @@
 - [ ] Command Pack 不能覆盖内置命令、其他 pack 命令或重声明保留 flag。
 - [ ] 普通网络请求走 `ctx.client`；基础 Context 提供 `identity/settings/flags/client/output/errors`，不提供原始凭据。
 - [ ] `ctx.credentials.apiKey()` 仅限 policy 显式声明 `credentialAccess: ["apiKey"]`，且命令自身为 `auth: "apiKey"`。
+- [ ] API Key capability ID 由 host 按实际叶子命令路径生成（例如 `agent credential` → `agent.credential`）；Command Pack 不声明额外元数据，Profile allowlist 对 pack 命令同样 fail closed。
+- [ ] `ctx.credentials.apiKey()` 必须返回 `authStage` 已注入 `ctx.client` 的实际凭证，不能重新读取原 Profile 绕过 capability fallback。
 - [ ] 不向 Command Pack 暴露原始 Console Token、OpenAPI AK/SK、`authStore` 或 `configStore`。
 - [ ] 不向 Command Pack 暴露宿主的 `commandPacks` manager，避免 pack 安装或删除其他 pack。
 - [ ] 单包失败必须 fail-open：保留内置命令和其他合法 pack。
@@ -40,10 +42,11 @@
 ## 测试与文档
 
 - [ ] `packages/runtime/tests/command-packs.test.ts` 覆盖产品 policy、安装目录隔离、协议版本、前缀和导出契约。
+- [ ] Command Pack 测试覆盖 capability 格式/鉴权域、adapter 保留字段，以及 raw API Key 委托使用 fallback 后的实际 Base URL。
 - [ ] `packages/cli/tests/e2e/command-packs.e2e.test.ts` 覆盖 help、link、执行、output/errors、凭据授权、list、remove。
 - [ ] `packages/kscli/tests/e2e/command-packs.e2e.test.ts` 覆盖统一 host 和 runtime 默认空 policy 下不暴露管理命令。
 - [ ] fixture 的包名必须在测试白名单内，且构建入口不依赖工作区运行时解析。
-- [ ] 更新生成的 `skills/bailian-cli/reference/plugin.md`；公开 `README.md` / `README.zh.md` 等正式对外发布时再补。
+- [ ] 更新生成的 `skills/bailian-cli/reference/plugin.md`（或归属表指定的 skill reference）；公开 `README.md` / `README.zh.md` 等正式对外发布时再补。
 
 验证：
 

docs/agents/config-add.md

@@ -29,6 +29,7 @@ config 文件     ─┘
   - `ConfigFile`(disk 形状,snake_case)加新字段(如果允许写文件)
   - `parseConfigFile()` 解析新字段
   - 如果是 enum 字段,加校验
+  - 如果是数组字段,明确“缺失 / 空数组 / 非法值”的不同语义；安全策略字段的非法值必须 fail closed
 
 ### B. 加载逻辑
 
@@ -51,6 +52,7 @@ config 文件     ─┘
 - [ ] 配置展示 / 修改命令同步:
   - `packages/commands/src/commands/config/show.ts` 显示新字段
   - `packages/commands/src/commands/config/set.ts` 的 `VALID_KEYS` / `KEY_ALIASES` / description 允许 set
+  - `packages/commands/src/commands/config/ui.ts` / `ui-html.ts` 能按原类型往返数组字段,不能把 `[]` 保存成字段缺失
 
 ### E. 文档
 
@@ -61,6 +63,7 @@ config 文件     ─┘
 - [ ] 单测覆盖优先级:flag > env > file
 - [ ] 校验失败抛错(非法值)
 - [ ] 默认值正确
+- [ ] 数组配置覆盖 CLI 逗号/JSON 输入、Config UI 往返、去重和显式空数组
 
 ## 完成后自查
 
@@ -82,3 +85,4 @@ cat ~/.bailian/config.json
 - ✗ 全局 switch 没标 `type: "switch"`,被当成需要值的 `--xxx <value>`
 - ✗ 加了 env var 但 README 表格没更新,用户不知道有这条
 - ✗ `config show` 不显示新字段,用户改了无法回查
+- ✗ UI 用 `String([])` 把显式空数组渲染为空串,保存后意外关闭安全策略

docs/agents/config-profile-change.md

@@ -18,15 +18,19 @@
 - 解析阶段用局部变量保留“是否显式传入 `--config`”的信息；完成 Config 选择后不进入 `Settings`。
 - `--config default` 必须显式选择顶层配置并绕过命名激活项。
 - 普通命令的显式 `--config` 只覆盖本次选择，不修改持久化激活状态；例外是
-  `auth login --config ...`，凭证验证并落盘成功后自动激活该 Profile。
+  `auth login --config ...`，凭证落盘成功后自动激活该 Profile。
 - 激活状态只选择配置 block，不改变字段优先级；字段仍为 flag > env > selected config > 默认值。
+- API Key capability fallback 是窄例外：命名 Profile 显式配置 `api_key_capabilities` 后，不在白名单中的 `auth: "apiKey"` 叶子命令只把 file 层 `api_key` / `base_url` 切到顶层 `default`；所选 Profile 的其他 settings 和 `active_config` 均不变。如果 `--api-key` / `--base-url` 或 `DASHSCOPE_API_KEY` / `DASHSCOPE_BASE_URL` 任一提供了更高优先级的模型连接参数，则整个 capability fallback 跳过，file 层也不切换；未显式提供的另一部分继续按 flag > env > 所选 Profile 解析。
+- Profile 是否启用 capability fallback 只看持久化的 `api_key_capabilities`，与名称无关：字段缺失表示关闭策略，`[]` 表示全部 API Key 命令 fallback。runtime 不注入内置 preset；升级内置 Plan Profile 的 preset 需要重新登录。
+- 对命中内置 preset 的 Profile，API Key 登录落盘成功后会把当前 preset 中缺少的 capability 追加落盘，同时保留已有项且不做删除；Console/OpenAPI 登录、自定义 Profile、dry-run 和失败登录均不修改该白名单。
+- Capability ID 直接使用产品实际叶子命令路径并以 `.` 连接（例如 `video task get` → `video.task.get`）；不新增命令元数据。新增或改名后的 API Key 路由未进入白名单时自然 fail closed。
 - Pipeline 等进程内调用链也要复用统一的 `buildSources()`，避免绕过激活状态。
 - Console access token 自动刷新等后台读写必须携带 `settings.configName`，不得直接读写顶层 default。
 
 ## 3. 保持读写命令交互一致
 
 - `auth login`、`config set` 等写命令未传 `--config` 时修改当前激活项。
-- `auth login --config <name>` 显式指定不存在的 Profile 时，仅在凭证验证成功并实际落盘时
+- `auth login --config <name>` 显式指定不存在的 Profile 时，仅在凭证实际落盘时
   创建和激活；`config set --config <name>` 可创建但不自动激活。
 - `config show`、`auth status` 和业务消费等读命令不得因为显式指定不存在的名称而创建 Profile。
 - `auth logout` 默认只清理当前激活项；显式 `--config` 只清理指定项。
@@ -46,13 +50,17 @@
 - `config list` 标识所有 Profile 与当前激活项。
 - `config show`、`auth status` 只输出本次最终选择的 `config` 和 `config_file`，不重复携带激活状态。
 - `config ui` 从持久化元数据读取激活项，提供显式激活操作，并在删除激活项后刷新为 `default`。
-- `config ui` 保存时只替换 UI 管理的字段；Profile 中未展示但仍属于 `ConfigFile` 的合法字段必须保留，不能因打开并保存 UI 而丢失。
+- `config ui` 展示并可编辑完整 `ConfigFile`（含 `console_*`、`telemetry`），保存时按类型（数字/布尔/枚举）归一化写回；`config set` 仍只暴露较窄的 `VALID_KEYS`。UI 未管理的顶层元数据（如 `active_config`）不进入 Profile block，仍由写盘逻辑单独保留。
+- `config ui` 只读展示本地 agent 生态：Skills 跨全部 agent skill 目录（`~/.agents/skills` 及各 agent 的 `skills/`，含软链接）按 id 聚合并标注安装来源；MCP、Agents 从各 agent 本地配置读取。
+- `config ui` 提供 Assets 资产管理：扫描 `output_dir`（默认 `~/bailian-output`）下的 `images/videos/speech/omni` 分类及根目录散落文件，按分类与生成时间（mtime）标记，支持按分类筛选、内联预览（图/视频/音频）与删除单个文件；文件读取与删除均通过限定在输出目录内的路径校验（防目录穿越）。
 - 同步 E2E topic routes、Skill setup 和自动生成 reference。
 
 ## 6. 最小测试矩阵
 
 - 旧配置无 `active_config` -> `default`。
 - 激活命名 Profile 后，无 `--config` 的命令选择该 Profile。
+- 任意名称 Profile 的叶子路由 capability 命中时使用自身 API Key；未命中或空白名单时使用 `default` API Key；`--api-key` / `--base-url` 和 `DASHSCOPE_API_KEY` / `DASHSCOPE_BASE_URL` 任一覆盖时跳过 fallback。
+- 旧内置 Plan Profile 缺 capability 字段时不启用 fallback；重新登录后使用并持久化当前 preset，显式配置（含 `[]`）按文件值生效。
 - 显式命名 `--config` 和 `--config default` 均覆盖激活项且不修改磁盘状态。
 - 激活不存在的 Profile 失败且不写盘。
 - 悬空 `active_config` 明确失败。
@@ -61,8 +69,12 @@
 - 显式 `auth login --config <name>` 成功后激活该 Profile，失败或 dry-run 不创建、不切换；
   `--config default` 成功后切回 `default`。
 - Console token 自动刷新不从其他 Profile 借用 AK/SK，也不把新 token 写入其他 Profile。
+- Console/OpenAPI/none 命令不参与 API Key capability fallback；fallback 后的 Client 特殊端点行为必须跟随最终解析的 `base_url`，不能根据原 `settings.configName` 推断端点类型。
+- Fallback 反馈只描述 CLI 能权威确认的本地行为：当前 Profile 不支持空格分隔的用户可见叶子命令，本次将从 `default` 读取 API Key 配置；不得声称整个 Profile 已切换，也不得展示 capability ID 或 `<undeclared>` 等内部值。存在 `--api-key` / `--base-url` 或 `DASHSCOPE_API_KEY` / `DASHSCOPE_BASE_URL` 任一显式覆盖时必须跳过 fallback 且不输出反馈。
+- Fallback 反馈写 stderr，`--quiet` 抑制；text 模式输出本地化句子，`--output json` 输出两空格缩进的多行 `warning` 对象。dry-run 和后续鉴权失败仍保留反馈；JSON 模式下多个 diagnostics 以空行分隔，任何模式都不得输出凭证值。
 - `config list/show/use/ui`、`auth status` 和依赖默认模型的消费命令覆盖对应 E2E。
-- `config ui` 覆盖保存时保留未管理字段，并继续允许空值清除 UI 管理字段。
+- `config ui` 覆盖保存时保留顶层元数据（如 `active_config`），继续允许空值清除字段，并覆盖 `console_*`/`telemetry` 的类型归一化与枚举校验。
+- Assets:`listAssets` 覆盖分类归类、时间倒序、目录缺失返回空；`resolveAssetPath` 覆盖目录穿越拦截;`contentType` 覆盖常见扩展名映射。
 
 ## 7. 完成检查
 

docs/agents/dsh-plugin.md

@@ -0,0 +1,125 @@
+# dsh 插件维护（packages/bailian-kb-dsh）
+
+## 触发条件
+
+- 改 `packages/bailian-kb-dsh` 的工具（`kb_search` / `kb_chat`）、服务缓存、settings / 凭据解析
+- 改 web 半（Settings 配置页 React 组件、CSS Modules）
+- 升级 `@deepseek-ai/dsh-*` peer 依赖
+- 改插件包名、bundle 声明或产物布局
+- 发布插件到 npm
+
+## 这个包和其他 packages 不一样的地方
+
+它是**下游宿主适配层**：依赖方向朝外（消费 `bl` CLI 与百炼 API，装进 DeepSeek Harness 运行），不是 `core → runtime → commands → 产品入口` 这条链上的一环。由此带来四条与 `packages/*` 通行约定的**故意偏离**：
+
+| 项       | 本包                                                                   | 其他包                                        | 原因                                                                                             |
+| -------- | ---------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| 版本     | 独立 `0.1.x`                                                           | core/runtime/commands/cli/kscli 锁步          | 跟随 dsh 的 rc 节奏，与 `bl` 发版无关；不在 `tools/release/lib/packages.mjs` 白名单里            |
+| 构建     | `tsc` + `tsdown`                                                       | `vp pack`                                     | 浏览器半需要 `__ModuleLoader__` banner/footer 与 lightningcss CSS Modules 内联，`vp pack` 产不出 |
+| 发布     | `publish.yml` 里 `package=bailian-kb-dsh` job，走 `publish-kb-dsh.mjs` | `publish.yml` 里 `publish-stable/channel.mjs` | 不在 `bailian-cli` 依赖闭包内，版本与构建都不同，不能与 `bl` 共用同一条 script                   |
+| tsconfig | 三个                                                                   | 一个                                          | 见下                                                                                             |
+
+## tsconfig 三件套（改动前先读）
+
+| 文件                  | 谁在用                       | 作用                                                                                                            |
+| --------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `tsconfig.json`       | oxlint / `vp check` 自动发现 | **纯类型检查**，覆盖 `src` + `tests` 两半：`noEmit` + `jsx: react-jsx` + DOM lib + `allowImportingTsExtensions` |
+| `tsconfig.build.json` | `build` script（`tsc -b`）   | **产出** node 半到 `dist/`，`exclude: src/web`                                                                  |
+| `tsconfig.web.json`   | `build` / `typecheck` script | web 半的**隔离检查**：`types: []`，确保浏览器代码不误用 node 全局                                               |
+
+- 不要把 `tsconfig.json` 改成产出配置：`allowImportingTsExtensions` 与 emit 互斥，一改 oxlint 就再也检查不了 `.tsx`（报 TS17004 `--jsx` not set）。
+- web 半的隔离检查挂在 `build` script 里，因为 CI 只跑 `build` / 根 `check` / 根 `test`，`typecheck` script 没有调用点。
+
+## 必查清单
+
+### A. 包身份（改包名时三处必须一起改）
+
+- [ ] `package.json` 的 `name`
+- [ ] `cordis.patch.yml` 的 `insert[].name`（profile 层栈按这个名字解析插件）
+- [ ] `tsdown.config.ts` 的 `PLUGIN_ID`（进 `window.__ModuleLoader__.load({ id })` 与 `<style data-plugin>`）
+
+漏任何一处都不会在构建期报错，只会在 dsh 里运行时崩。验证：`grep -rn "<新包名>" package.json cordis.patch.yml tsdown.config.ts` 三处齐全，且 `dist/web/client.js` 首行的 `id` 是新名。
+
+### B. 产物布局
+
+- [ ] 产物落 `dist/`（node 半）与 `dist/web/client.js`（浏览器半）；根 `.gitignore` 忽略 `dist` 与 `*.tsbuildinfo`，**不要**改回 `lib/`（那会把产物提交进库）
+- [ ] `package.json` 的 `main` / `types` / `exports["."]` / `exports["./client"]` / `files` 与实际产物一致
+- [ ] tsdown 的 `clean` 保持 `false`：默认 clean 会清掉 `tsc` 刚产出的 node 半
+
+### C. web 半的模块边界
+
+- [ ] 只 import tsdown `CLIENT_EXTERNALS` 名单里的 `@deepseek-ai/*`（宿主 frozen module table 只能应答这些）——构建期由 `dsh-client-bundle-purity` 插件把关
+- [ ] 不 import `node:*` 与本仓 CLI 包（`bailian-cli-core` 等）——根 `vite.config.ts` 的 `no-restricted-imports` override 在 lint 期把关
+- [ ] 跨插件协作走 cordis service，不做 value import（type-only import 会被擦除，不受限制）
+
+### D. skill 资产
+
+- [ ] `skills/bailian-kb/` 留在**包内**，不要挪到仓库顶层 `skills/`：`.github/workflows/publish-skills.yml` 把 `skills/**` 全量对账到 OSS registry，`bl skill init` 会装给所有 `bl` 用户，而这个 skill 讲的 `kb_search` / `kb_chat` 原生工具只在 dsh 里存在
+- [ ] skill 只有一个手写 `SKILL.md`，**不带 `reference/`**：它不是 CLI，没有义务维护一份 `bl` 参数手册。`bl` 命令的 flag 详情交给 `bl <命令> --help`（权威的 `bl` reference 由 `tools/generate-reference.ts` 写到 `skills/bailian-cli/reference/`，与本包无关）。SKILL.md 里写到的 `bl` 命令/flag 修改时手动核对 `packages/commands/src/commands/`，不要锚版本号
+
+### E. 文档（README 是 npm 主页，双语）
+
+- [ ] 用户可见行为变了（工具参数、配置字段、环境变量、设置页、安装/卸载命令）→ `README.md` 与 `README.zh.md` **一起改**；两份互为镜像，头部互链
+- [ ] README 只写用户要知道的事；"为什么这么设计"（上下文注入载体、缓存布局、刷新触发点、桥接路由）写进 [../kb-dsh/runtime-behavior.md](../kb-dsh/runtime-behavior.md)，不要回流 README
+- [ ] 包根保留 `LICENSE`（npm 无条件打包），与 `package.json` 的 `license` 一致
+
+### F. 依赖与测试约定
+
+- [ ] `@deepseek-ai/dsh-*` 同时列在 `peerDependencies`（运行时由 dsh 安装闭包提供）和 `devDependencies`（本地类型检查）——升级时两处同步
+- [ ] 测试从 `vite-plus/test` 导入（仓库统一约定），不要用 `vitest`
+- [ ] 忽略的 catch 绑定与 mock 签名参数用 `_` 前缀（根 `vite.config.ts` 已为本包放开 `no-unused-vars` 的对应 pattern）
+
+### G. 改完跑
+
+```sh
+pnpm --filter bailian-kb-dsh run build   # tsc 出 dist/ + web 半隔离检查 + tsdown 出 client.js
+pnpm run check                           # 根 lint + 格式 + 类型
+npx vp test packages/bailian-kb-dsh
+```
+
+手动集成（改了 bundle 声明 / web 半 / 工具 schema 时必做）：
+
+```sh
+dsh plugin --profile dev add <本仓库>/packages/bailian-kb-dsh
+dsh --profile dev --dump-config          # 应能看到 tool-bailian-kb row
+```
+
+## 发布
+
+入口与 `bl` 共用：Actions → **Publish** → `package=bailian-kb-dsh` + `mode=stable|channel`。共享的只有 workflow 入口与 checkout/pnpm/node/gitleaks/install 几步 setup；它走自己的 `tools/release/publish-kb-dsh.mjs`，**不**复用 `publish-stable.mjs` / `publish-channel.mjs`。
+
+|           | stable                                                              | channel                                                 |
+| --------- | ------------------------------------------------------------------- | ------------------------------------------------------- |
+| 版本      | `package.json` 当前值（先手动 bump 并提交）                         | 临时 `0.0.0-beta-<sha>-<stamp>`，`finally` 还原，不提交 |
+| npm tag   | `latest`                                                            | 你传的 `channel`（dist-tag）                            |
+| preflight | 工作区干净 + 必须在 `main`                                          | 无                                                      |
+| git tag   | `bailian-kb-dsh-v<version>`（与 `bl` 的 `v<version>` 错开命名空间） | 不打 tag                                                |
+| 审批      | `environment: production`（Required Reviewers）                     | 无                                                      |
+| 产物      | npm only                                                            | npm only                                                |
+
+两种模式都跑：`build`（tsc + web 隔离检查 + tsdown）→ 幂等性查重 → `pnpm pack` → `publint` + `gitleaks` → `pnpm publish --provenance`。
+
+本地验证（不真发，需本地装 gitleaks）：
+
+```sh
+node tools/release/publish-kb-dsh.mjs --dry-run
+node tools/release/publish-kb-dsh.mjs --dry-run --channel dsh-beta
+```
+
+### 首发前的 npm 侧前置（仓外操作，一次性）
+
+1. 占住包名 `bailian-kb-dsh`（OIDC Trusted Publishing 无法给不存在的包首发）
+2. 在 npm 包设置里绑 Trusted Publisher：仓库 `modelstudioai/cli`、workflow `publish.yml`；stable 走 environment `production`，channel 无 environment
+
+未完成这两步前触发 workflow 会在 `pnpm publish --provenance` 这一步失败（前面的 build / scan 仍会正常跑完）。
+
+### 已知待办
+
+- `publint` 会报一条 warning：`exports["./client"]` 是 CJS 但包为 `type: module`，建议改 `.cjs` 扩展名。这是迁移前就存在的状态，warning 不阻断发布；真要改得同时动宿主按 `exports["./client"]` 解析 `/plugins/<id>/client.js` 的 URL 契约，需 dsh 侧一起验证，不要单方面改
+
+## 相关文档
+
+- 设计与实现计划归档：[docs/kb-dsh/](../kb-dsh/)
+- 运行时行为与设计取舍（内部）：[docs/kb-dsh/runtime-behavior.md](../kb-dsh/runtime-behavior.md)
+- 用户面说明：[packages/bailian-kb-dsh/README.md](../../packages/bailian-kb-dsh/README.md) / [README.zh.md](../../packages/bailian-kb-dsh/README.zh.md)
+- skill 文案与路由约定：[skill-change.md](skill-change.md)

docs/agents/error-hint-change.md

@@ -46,6 +46,7 @@ runtime/error-handler.ts:
   - 内部 AUTH/USAGE/NETWORK/TIMEOUT → 走 enhanceHint(只 AUTH 还有增强)
   - TypeError("fetch failed") → 读 err.cause.code 翻成 NETWORK
   - Node fs errno → 翻成 GENERAL + errno hint
+  - `--output json` → stderr 输出两空格缩进的多行 error JSON；前面已有结构化 warning 时，两个 diagnostics 以空行分隔
   - 其它 Error → 默认走 cause 链
   ↓
 process.exit(err.exitCode)

docs/agents/install-doc-change.md

@@ -0,0 +1,42 @@
+# 安装文档变更
+
+## 触发条件
+
+- 修改根目录 `INSTALL.md` 的安装、鉴权或验证流程
+- 修改发布包 Node.js 要求、全局 flag 或安装文档引用的命令
+- 同步或发布 `https://bailian.aliyun.com/cli/install.md`
+
+## 必查清单
+
+### A. CLI 契约
+
+- [ ] `INSTALL.md` 中的 `bl` 命令路径存在于 `packages/cli/src/commands.ts`
+- [ ] 示例 flag 属于 `GLOBAL_FLAGS`、命令鉴权域 flag 或命令自身 `flags`
+- [ ] Node.js 用户安装要求与 `packages/cli/package.json` 的 `engines.node` 一致，不使用根 `package.json` 的开发环境要求
+- [ ] 鉴权流程与 `packages/commands/src/commands/auth/` 的实际校验、保存和 Profile 激活行为一致
+
+### B. 静态副本
+
+- [ ] 将 `INSTALL.md` 同步到 `bailian-cli-static-resources/public/install.txt`
+- [ ] 使用 `cmp -s` 确认两份文档逐字节一致
+- [ ] 静态资源仓库单独创建分支、提交和发布，不把跨仓库改动遗漏在 CLI PR 之外
+
+### C. 线上验证
+
+- [ ] 发布后读取 `https://bailian.aliyun.com/cli/install.md`，确认内容来自最新静态副本
+- [ ] 带随机 query 参数复查，区分 CDN 缓存与源站未更新
+- [ ] 验证线上文档中的安装命令、Node.js 要求和配置验证段落，不只检查页面可访问
+
+## 完成后自查
+
+```sh
+pnpm -F bailian-cli test -- tests/install-doc.test.ts
+cmp -s INSTALL.md ../bailian-cli-static-resources/public/install.txt
+curl -L -s "https://bailian.aliyun.com/cli/install.md?verify=$(date +%s)"
+```
+
+## 常见漏点
+
+- `--non-interactive` 已从 CLI 移除，但旧安装文档和静态副本仍把它当作全局 flag
+- 根 `package.json` 是开发工具链 Node.js 要求；用户安装要求以 `packages/cli/package.json` 为准
+- 静态仓库文件名是 `public/install.txt`，线上稳定地址是 `/cli/install.md`；只更新其中一侧不会自动证明发布成功

docs/agents/lint-toolchain.md

@@ -12,7 +12,7 @@
 
 ### A. 版本一致性
 
-- [ ] `package.json` 的 `engines.node` 与 README 的 Node.js 徽章一致
+- [ ] 发布包（`cli` 等）的 `engines.node` 与 README 的 Node.js 徽章一致；根/e2e 开发要求（`>=22.12`）与 CONTRIBUTING 一致
 - [ ] `pnpm-lock.yaml` 同步生成(运行 `pnpm install`)
 - [ ] 各源码包 `tsconfig.json`(根 + core + runtime + commands + cli + kscli)的 target / module 设置一致
 

docs/agents/model-add-remove.md

@@ -26,7 +26,8 @@
 
 ### C. 命令手册
 
-- [ ] 若 `--model` 的 description 含 default,改命令后跑 `pnpm --filter bailian-cli run generate:reference` 更新 `skills/bailian-cli/reference/<group>.md` 并提交
+- [ ] 若 `--model` 的 description 含 default,改命令后跑 `pnpm --filter bailian-cli run generate:reference` 更新对应 `skills/<skill>/reference/<group>.md` 并提交
+- [ ] 同步**拥有该命令的领域 skill**「When to use which command」表中的 Default model(现主要是 `bailian-gen`;精调相关看 `bailian-finetune` 正文示例)。hub `bailian-cli` 已瘦身,一般**不必**再写领域默认模型(见 [skill-change.md](skill-change.md))
 
 ### D. 用户面文档
 
@@ -49,6 +50,7 @@ pnpm -F bailian-cli exec tsx src/main.ts <command> --model <new-model> --message
 
 ## 常见漏点
 
-- ✗ 改了命令默认模型,但 SKILL.md frontmatter 仍写老型号 → AI agent 调用时仍按老型号宣传
+- ✗ 改了命令默认模型,但 SKILL.md frontmatter 或领域路由表 Default model 仍写老型号 → AI agent 调用时仍按老型号宣传
+- ✗ 只改了 `reference/` / flag description,忘改 `bailian-gen`(等) SKILL 路由表
 - ✗ 废弃模型时只删了代码,e2e 测试还在跑,CI 红
 - ✗ 新模型 endpoint 不一致,但只改了 default,没加 endpoint 分支判断

docs/agents/publish.md

@@ -1,27 +1,57 @@
-# 发布（npm publish）
+# 发布（npm + GitHub Release 二进制）
 
 ## 触发条件
 
-- 准备发布 channel（beta/mcp/plugin 等）或正式版到 npm
-- 准备打 git tag
+- 准备发布 channel（mcp/plugin 等）或正式版到 npm **与** GitHub Releases 二进制
+- 准备打 git tag（仅 stable）
 
-## 发布方式：GitHub Actions + npm OIDC
+## 发布方式：GitHub Actions 总入口
 
 发版**必须**通过 CI 完成，不要本地手动 `pnpm publish`。
 
 入口：GitHub Actions → **Publish** workflow（`.github/workflows/publish.yml`）→ Run workflow。
 
+**编排关系（重要）：**
+
+```text
+publish-stable.mjs / publish-channel.mjs   ← 唯一发版入口
+        ├─ npm（pnpm publish）
+        └─ binary（lib/binary-release
+              → binary-build
+              → gh-release
+              → oss-direct-upload）
+```
+
+`tools/release/lib/binary-release.mjs` 等是实现，一般不要单独当发版入口（调试可用）。
+
+### bailian-kb-dsh（独立版本、npm-only）
+
+同一个 Publish 入口，`package=bailian-kb-dsh`。它走单独的 `tools/release/publish-kb-dsh.mjs`，不复用 `publish-stable.mjs` / `publish-channel.mjs`（版本独立、无 binary、无 OSS CDN）。详见 [dsh-plugin.md](dsh-plugin.md#发布)。
+
 两种模式：
 
-| 模式    | 用途                           | 触发方式                                           |
-| ------- | ------------------------------ | -------------------------------------------------- |
-| channel | 发 channel 版本到指定 dist-tag | 选 mode=channel，填 dist-tag 名称（如 mcp/plugin） |
-| stable  | 正式发版到 latest              | 选 mode=stable，需 production environment 审批     |
+| 模式    | 用途                                                                                    | 触发方式                                     |
+| ------- | --------------------------------------------------------------------------------------- | -------------------------------------------- |
+| channel | npm dist-tag +（仅 bailian-cli）二进制 + CDN **一律**覆盖 `sync-release.json`           | mode=channel，channel 填 **npm dist-tag** 名 |
+| stable  | npm latest + GitHub Release `v<ver>` + CDN **`manifest.json`**（及 `latest.json` 别名） | mode=stable，需 production environment 审批  |
+
+可选 flag：`--skip-binary`（仅发 npm，紧急逃生）。
+
+### CDN 滚动指针（bailian-cli）
+
+| 发布模式 | CDN 指针                           | 本机安装 / 更新                                                   |
+| -------- | ---------------------------------- | ----------------------------------------------------------------- |
+| channel  | 始终覆盖 `sync-release.json`       | `BAILIAN_CHANNEL=sync-release` / `install --channel sync-release` |
+| stable   | `manifest.json`（+ `latest.json`） | 默认安装 / `bl update`（无 channel）                              |
+
+workflow 的 `channel` 输入**只决定 npm dist-tag**（如 `mcp` / `plugin` / `sync-release`），**不再**生成 `release-test.json` 这类旁路文件。
 
 ### channel 发布
 
-1. 在 GitHub 触发 Publish workflow，package 选 `bailian-cli` 或 `knowledge-studio-cli`，mode 选 `channel`，channel 填 dist-tag 名（如 `mcp`）
-2. CI 自动：生成 `0.0.0-beta-<sha7>-<date>` 版本号 → 临时 bump 对应包集合 → 自检 → 构建 → 发布到指定 dist-tag
+1. 在 GitHub 触发 Publish workflow，mode 选 `channel`，channel 填 npm dist-tag 名：
+   - **`bailian-cli`**：npm 发到该 tag；二进制同时刷新 CDN `sync-release.json`（与 tag 名无关）。本机验证：`BAILIAN_CHANNEL=sync-release`
+   - **`knowledge-studio-cli`**：仅 npm（自动跳过 binary，不碰 `sync-release.json`）
+2. CI 自动：生成 `0.0.0-beta-<sha7>-<YYYYMMDDHHMM>`（UTC 到分钟；同 commit 同分钟重跑会覆盖同号）→ 临时 bump → 自检 → **npm 发到 dist-tag** →（bailian-cli）**Bun 编二进制 + GH prerelease + 覆盖 `sync-release.json`** → 还原 package.json
 3. 对应脚本：`tools/release/publish-channel.mjs`
 
 ### stable 发布
@@ -29,7 +59,7 @@
 1. 确保当前 release tooling 覆盖的包(`tools/release/lib/packages.mjs`)已升到目标版本且一致;当前基础集合为 `packages/core` / `packages/runtime` / `packages/commands` / `packages/cli`，`knowledge-studio-cli` 发布会额外包含 `packages/kscli`
 2. 在 GitHub 触发 Publish workflow，package 选目标包集合，mode 选 `stable`
 3. 需要 production environment 审批人批准
-4. CI 自动：自检 → 构建 → 检查 npm 已发布版本 → 发布到 latest → 打 git tag
+4. CI 自动：自检 → **npm 发到 latest** → **推送 git tag `v<ver>`** → **Bun 编二进制并创建/更新 GitHub Release** →（bailian-cli）维护 CDN **`manifest.json`** → 完成
 5. 如果所选发布集合的当前版本已全部存在于 npm，stable 发布会失败并提示先升级版本号；如果只有部分包已发布，CI 会继续补发缺失包
 6. 对应脚本：`tools/release/publish-stable.mjs`
 
@@ -37,17 +67,17 @@
 
 两种模式都会先跑 `check.mjs`，覆盖以下检查：
 
-| 检查项                           | 说明                                                                                             |
-| -------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `pnpm install --frozen-lockfile` | lockfile 一致性                                                                                  |
-| README 同步                      | `packages/cli/README.md` 与根 README 一致                                                        |
-| 版本号一致                       | `tools/release/lib/packages.mjs` 中待发布包集合 version 相同                                     |
-| `workspace:*` 替换               | 发布包间 workspace 依赖解析为真实版本号                                                          |
-| 构建                             | 基础发布构建 core/runtime/commands 依赖和 cli;`--knowledge` 额外构建 `knowledge-studio-cli`      |
-| 生成资产                         | 重建 `skills/bailian-cli/reference/`;非 channel 模式还同步 `skills/bailian-cli/SKILL.md` version |
-| pnpm pack                        | 打 tarball                                                                                       |
-| publint                          | 包元数据校验                                                                                     |
-| gitleaks                         | 敏感信息扫描                                                                                     |
+| 检查项                           | 说明                                                                                                            |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `pnpm install --frozen-lockfile` | lockfile 一致性                                                                                                 |
+| README 同步                      | `packages/cli/README.md` 与根 README 一致                                                                       |
+| 版本号一致                       | `tools/release/lib/packages.mjs` 中待发布包集合 version 相同                                                    |
+| `workspace:*` 替换               | 发布包间 workspace 依赖解析为真实版本号                                                                         |
+| 构建                             | 基础发布构建 core/runtime/commands 依赖和 cli;`--knowledge` 额外构建 `knowledge-studio-cli`                     |
+| 生成资产                         | 重建各 `skills/<skill>/reference/`;非 channel 模式还同步各 `skills/*/SKILL.md` version（含 `bailian-protocol`） |
+| pnpm pack                        | 打 tarball                                                                                                      |
+| publint                          | 包元数据校验                                                                                                    |
+| gitleaks                         | 敏感信息扫描                                                                                                    |
 
 本地可以 dry-run 验证：
 
@@ -59,7 +89,9 @@ node tools/release/publish-channel.mjs --channel test --knowledge --dry-run
 ## CI 基础设施
 
 - **认证**：npm OIDC Trusted Publishing（无 token），需要 `id-token: write` 权限
+- **GitHub Release**：`contents: write` + `GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}`（stable / channel 均需）
 - **Node 版本**：24（npm 11.5+ 才支持 OIDC token 交换）
+- **Bun**：`oven-sh/setup-bun`，版本钉死在 workflow 中
 - **Actions 版本**：checkout/setup-node/pnpm-action 均为 v6（Node 24 兼容）
 - **npm 配置**：当前 release tooling 发布的包(`bailian-cli-core` / `bailian-cli-runtime` / `bailian-cli-commands` / `bailian-cli` / `knowledge-studio-cli`)的 Trusted Publisher 指向 `modelstudioai/cli` 的 `publish.yml`;新增发布包时同步 npm Trusted Publisher
 
@@ -93,15 +125,17 @@ node tools/release/publish-channel.mjs --channel test --knowledge --dry-run
 
 ## 常见漏点（基于历史踩坑）
 
-| 漏点                                                     | 后果                                                                               |
-| -------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| 只升部分包,漏升 runtime/commands/kscli                   | 当前 check.mjs 按所选发布集合校验,但未选择 `knowledge-studio-cli` 时不会覆盖 kscli |
-| 新增发布包但没加 `tools/release/lib/packages.mjs`        | CI 不会 bump/publish/校验该包                                                      |
-| cli 升版号但 core 没升                                   | check.mjs 会拦下                                                                   |
-| 发版漏更 CHANGELOG，或分类写成规范外的 `优化`/`Improved` | 用户看不到本次变更，分类与历史不一致                                               |
-| `1.0.0` 当 beta 直接发                                   | 占了 `latest` tag，所有用户被强升，撤回成本极高                                    |
-| README 写的 bin 名实际 `package.json.bin` 没注册         | 用户复制命令报 `command not found`                                                 |
-| Node 徽章 `>=18`、engines `>=22.12` 不一致               | 用户在 Node 18 上 `npm i` 被 engine 警告或直接失败                                 |
-| npm Trusted Publisher 的 workflow filename 改了没同步    | OIDC 匹配不上，publish 报 404                                                      |
-| CI 用 Node 22（npm 10）跑 publish                        | npm 10 不支持 OIDC token 交换，publish 报 404                                      |
-| stable 发布前没有升级版本号                              | 所选发布集合的版本已全部存在于 npm，CI 明确报错并要求先升级版本号                  |
+| 漏点                                                                | 后果                                                                               |
+| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| 只升部分包,漏升 runtime/commands/kscli                              | 当前 check.mjs 按所选发布集合校验,但未选择 `knowledge-studio-cli` 时不会覆盖 kscli |
+| 新增发布包但没加 `tools/release/lib/packages.mjs`                   | CI 不会 bump/publish/校验该包                                                      |
+| cli 升版号但 core 没升                                              | check.mjs 会拦下                                                                   |
+| 发版漏更 CHANGELOG，或分类写成规范外的 `优化`/`Improved`            | 用户看不到本次变更，分类与历史不一致                                               |
+| `1.0.0` 当 beta 直接发                                              | 占了 `latest` tag，所有用户被强升，撤回成本极高                                    |
+| README 写的 bin 名实际 `package.json.bin` 没注册                    | 用户复制命令报 `command not found`                                                 |
+| Node 徽章与 `cli/package.json.engines` 不一致（当前应为 `>=18.17`） | 用户在声明外的 Node 上 `npm i` 被 engine 警告或直接失败                            |
+| npm Trusted Publisher 的 workflow filename 改了没同步               | OIDC 匹配不上，publish 报 404                                                      |
+| CI 用 Node 22（npm 10）跑 publish                                   | npm 10 不支持 OIDC token 交换，publish 报 404                                      |
+| stable 发布前没有升级版本号                                         | 所选发布集合的版本已全部存在于 npm，CI 明确报错并要求先升级版本号                  |
+| channel job 缺少 `contents: write`                                  | `gh release create` 失败                                                           |
+| stable 未先推 tag 就建 Release                                      | `--verify-tag` 失败                                                                |

docs/agents/skill-change.md

@@ -0,0 +1,80 @@
+# Skill 文案 / 路由 / 安装约定
+
+## 触发条件
+
+- 改 `skills/*/SKILL.md` 的 description、路由表、consent、安全闸、hand-off、references 落款
+- 调整 `bailian-protocol` 与业务 skill 的关系，或业务 skill 之间的软 hand-off 约定
+- 新增 / 拆分 / 合并 `bailian-*` 业务 skill，或改 `tools/generate-reference.ts` 的 `GROUP_OWNER_SKILL` 归属（与命令增删改交叉时两边都看）
+- 给业务 skill 补安装说明、README，或统一「勿猜 flag → `reference/`」类约定
+
+纯改生成物 `skills/*/reference/*.md`（由命令 metadata 驱动）→ 走 [command-add-remove.md](command-add-remove.md) / [command-flag-change.md](command-flag-change.md)，**不要手改 reference**。
+
+## 统一口径（安装）
+
+1. **Supported install：** `bl skill init`（装齐 registry 中全部 `bailian-*`，含 `bailian-protocol`）
+2. **`bailian-protocol` 是共享协议 skill**，业务 skill 执行前应 Read 它
+3. **不要**在 frontmatter 写 `companions`，也不要对外说「companions = 安装器硬依赖」
+4. 子集安装：`bl skill add --name bailian-protocol,<skill>`；漏装 protocol 会导致相对路径 Read 失败
+5. **`bl skill add --all`：** 安装 registry 全量（含 `spark-video` 等非 bailian 技能）；一键安装 / `bl update` 用 `skill init`，不要用 `--all`
+
+## 概念图
+
+```text
+bailian-protocol          ← 共享协议（consent / 鉴权 / 版本 / 错误上报）
+        ▲                   靠 `bl skill init` 与业务 skill 同装；非安装器强制 companions
+        │
+┌───────┴────────┬────────────────┬──────────────────┬───────────────────┐
+bailian-gen      bailian-finetune  bailian-managed-agent   bailian-web-search
+（领域路由表）    （领域工作流）     （IaC 安全闸）          （搜索路由+兜底）
+        │                │                  │                     │
+        └────────────────┼──────────────────┴─────────────────────┘
+                         ▼ 软 hand-off（按 skill 名）
+                   bailian-cli（hub）
+                   hub 路由表：本职命令 + 领域 hand-off 行
+                   细节 → 各 skill reference/（生成）
+```
+
+## 必查清单
+
+### A. 分层边界
+
+- [ ] **整包装齐**：安装/升级文案主推 `bl skill init`；业务 skill **不**声明 `companions`
+- [ ] **协议读取**：CRITICAL / references 可链 `../bailian-protocol/…`；若读不到 → 停止执行 `bl`，提示 `bl skill init`
+- [ ] **高风险确认**：统一由 `bailian-protocol` 定义；reference / leaf help 以 `risk: high` 明示风险，业务 skill 不得引导 Agent 自动补 `--yes`。遇到 exit code 7 / `requires_confirmation` 时停止执行并请求确认；目标或范围变化后重新确认
+- [ ] **正常控制流**：`requires_confirmation` 不是 CLI bug，`assets/issue-reporting.md` 必须将 exit code 7 保持在 EXCLUDE 范围
+- [ ] **软 hand-off**：兄弟业务 skill **只写 skill 名**；已安装则 Read，未安装则 `bl … --help` 或提示整包安装；**不要**把 `../bailian-gen/…` 等写成执行前提
+- [ ] **Hub vs 领域**：`bailian-cli` 的「When to use which command」只列 hub 拥有的意图；媒体 / 精调 / managed-agent 各留 hand-off 行，**不抄**领域默认模型与子命令明细
+- [ ] **渐进披露**：SKILL 写意图路由与领域硬规则；flags / usage / examples 以 `reference/` 或 `bl <command> --help` 为准，表后保留「勿猜 flag」指向句
+
+### B. 文案与落款一致性
+
+- [ ] 领域 skill（gen / finetune / managed-agent）路由或命令表后有指向 `reference/` 的句；文末 `## references`（protocol + reference）与家族对齐
+- [ ] description 含 WHAT + WHEN + 反触发；安装说明指向 `bl skill init`，不写 companions 必装
+- [ ] Quick examples 只演示本 skill 职责（hub 不示范 `bl image` / `bl video` 等）
+- [ ] 若改了安装方式：同步 `README.md` / `README.zh.md` / `INSTALL.md` / `skills/*/README*` / `skills/bailian-protocol/assets/setup.md` 中的 `bl skill init` / `bl skill add …` 示例（改 `INSTALL.md` 时按 [install-doc-change.md](install-doc-change.md) 同步静态页）
+
+### C. 归属与生成
+
+- [ ] 新一级命令组归属领域时：改 `tools/generate-reference.ts` 的 `GROUP_OWNER_SKILL`，并更新**拥有方** skill 的路由表；hub 最多加一行 hand-off
+- [ ] 跑 `pnpm run sync:skill-assets`（或 commit 走 pre-commit），提交生成的 `reference/` 与 version 同步结果
+- [ ] 高风险命令生成的 reference 必须包含 `Risk` / `Risk message` 和简短 Agent safety 提示；带 `--yes` 的示例必须标注只能在确认后执行，不要手改生成物
+- [ ] 默认模型若写在领域路由表（如 `bailian-gen`）：与命令 default / [model-add-remove.md](model-add-remove.md) 一并核对
+
+## 完成后自查
+
+```sh
+pnpm run sync:skill-assets
+# 已发布版本试装
+bl skill init
+```
+
+抽查：打开 `skills/bailian-cli/SKILL.md` 确认无领域子命令明细表、无 `companions`；打开对应领域 skill 确认有「勿猜 flag」与 hand-off。
+
+## 常见漏点
+
+- ✗ hub 路由表再次抄回 image / video / finetune / managed-agent 明细 → token 膨胀且与领域 skill 双份漂移
+- ✗ 重新加回 `companions` 并宣称安装器硬依赖 → 与 `bl skill add` 合同不符
+- ✗ 软 hand-off 写成硬路径 `../bailian-*/SKILL.md` 当执行前提 → 子集安装断链
+- ✗ 只改 SKILL、忘改 `GROUP_OWNER_SKILL` → reference 落错 skill
+- ✗ 手改 `skills/*/reference/*.md` → 下次 generate 被覆盖
+- ✗ 改默认模型只动 flag description / reference，忘改领域 SKILL「When to use which command」表（见 [model-add-remove.md](model-add-remove.md)）

docs/agents/telemetry-change.md

@@ -0,0 +1,168 @@
+# 埋点变更
+
+## 触发条件
+
+- 调整 AEM 命令事件、事件字段或参数 allowlist
+- 调整 `User-Agent`、`x-dashscope-source-config` 或其他后端渠道标识
+- 新增鉴权域、请求网关或绕开统一 Client 的网络出口
+- 排查命令量、成功率、版本、鉴权域或后端渠道数据不一致
+
+## 当前数据流
+
+三套鉴权对应三套请求域，但不代表三套网关使用相同的后端埋点。命令侧另有一套覆盖所有实际执行命令的 AEM 客户端事件，两者必须分开理解。
+
+```text
+命令进入 run
+  ├─ telemetryStage
+  │    ├─ ~/.bailian/telemetry.jsonl
+  │    └─ AEM(pid=bailian-cli-node, event name=命令路径)
+  │
+  └─ confirmationStage
+       └─ versionCheckStage → authStage
+            ├─ apiKey  → DashScope / 模型域
+            ├─ console → Bailian Console Gateway
+            ├─ openapi → 阿里云 OpenAPI
+            └─ none    → 无凭证域；本地命令也仍有 AEM 命令事件
+```
+
+### 1. 三套鉴权与埋点标识
+
+| 命令声明          | 凭证 / 请求域                                       | 主要请求出口                                                                          | 后端埋点标识                                  | 前端埋点标识（AEM）                              |
+| ----------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------ |
+| `auth: "apiKey"`  | API Key；DashScope / OpenAI-compatible 模型域       | `Client.request/requestJson`、`McpClient`、Managed Agent instrumented fetch、上传策略 | 有：`User-Agent`、`x-dashscope-source-config` | 有：`pid=bailian-cli-node`、`authMethod=apiKey`  |
+| `auth: "console"` | Console access token；Bailian Console Gateway       | `callConsoleGateway()` → `/cli/api.json`                                              | 有：Console Gateway 后端直接标识              | 有：`pid=bailian-cli-node`、`authMethod=console` |
+| `auth: "openapi"` | AccessKey ID/Secret，可选 STS token；阿里云 OpenAPI | `Client.openApiJson()`                                                                | 有：`x-dashscope-source-config`               | 有：`pid=bailian-cli-node`、`authMethod=openapi` |
+| `auth: "none"`    | 无凭证域                                            | 本地逻辑或命令自行管理的登录/配置流程                                                 | 无                                            | 有：`pid=bailian-cli-node`、`authMethod=none`    |
+
+`authMethod` 记录的是命令声明的鉴权域，不是凭证来源。它不会区分 API Key 来自 flag、env 还是 config。
+鉴权域是命令的准入门槛和主请求域，不保证命令内部只有一种网络出口；例如部分 `apiKey` 命令也可能读取匿名 Console 公共目录，Managed Agent 还可能访问其他 provider。
+
+表中的后端埋点按该鉴权域的主要业务请求填写：
+
+- Managed Agent 的 `User-Agent` 对所有 SDK 请求注入；`x-dashscope-source-config` 仅对阿里云 host 注入
+- DashScope 上传策略 `getPolicy` 只有 `x-dashscope-source-config`，没有显式 CLI `User-Agent`
+- Console Gateway 用户数据由后端直接区分，不依赖 `x-dashscope-source-config`；AEM 的 `authMethod=console` 是独立的命令侧统计
+- OpenAPI 的 ACS 签名头，以及 Console Gateway 的 `product`、`action`、`api` 是鉴权或路由字段，不计为埋点标识
+
+### 2. 后端渠道参数
+
+当前 `x-dashscope-source-config` 结构为：
+
+```json
+{
+  "channel": "bailian-cli",
+  "tags": {
+    "t1": "public",
+    "t2": "bl 或 kscli",
+    "t3": "实际 CLI 版本"
+  }
+}
+```
+
+- `t2` 取产品 `identity.binName`：完整 CLI 为 `bl`，Knowledge Studio CLI 为 `kscli`
+- `t3` 取产品 `identity.version`，由产品入口的 `package.json` 注入
+- `channel` 与 `t1` 是当前固定口径
+- `User-Agent` 是独立标识：`bl` 为 `bailian-cli/<version>`，`kscli` 为 `knowledge-studio-cli/<version>`
+
+source-config 只用于百炼 / DashScope API 侧消费，不发送到通用网络传输：
+
+| 请求                                 | source-config |
+| ------------------------------------ | ------------- |
+| 模型 API、任务提交与轮询             | 有            |
+| Bailian MCP / OpenAPI                | 有            |
+| DashScope 上传策略 `getPolicy`       | 有            |
+| OSS 文件上传                         | 无            |
+| 图片、视频、音频、转录结果下载       | 无            |
+| npm / 二进制更新检查、Skill registry | 无            |
+
+当前已知例外：Pipeline runtime 自建的 `Identity.version` 为 `0.0.0-dev`，因此 Pipeline 内部模型请求的 `t3` 不代表产品包版本；现阶段不纳入本轮收敛。
+
+### 3. 全命令 AEM 客户端埋点
+
+`packages/runtime/src/middleware.ts` 的 `telemetryStage` 包裹确认闸门、`authStage` 与命令执行，因此成功、确认未通过、业务失败、网络失败和鉴权失败都会形成一次命令事件。事件名是空格连接的命令路径，例如 `text chat`。确认闸门仍位于版本检查、鉴权和业务执行之前，不会因为埋点而放行高风险操作。
+
+以下情况不会形成命令事件，因为没有进入 middleware 的 `run`：
+
+- 根帮助、子命令 `--help`、`--version`
+- 未识别命令、参数解析失败、缺少必填参数
+- `defineCommand.validate` 在 dispatch 阶段拒绝的请求
+
+遥测默认开启；`DO_NOT_TRACK=1` 一票否决，配置文件 `telemetry: false` 也可关闭。关闭后本地和远端均不记录。
+
+单条 `TrackingEvent` 当前包含：
+
+- `command`、`timestamp`、`durationMs`、`success`
+- `cliVersion`、`nodeVersion`、`os`
+- `authMethod`
+- 失败时的 `errorMessage`、`exitCode`、`httpStatus`、`requestId`
+- 安全 allowlist 过滤后的 `params`
+
+参数默认不上传，只有 `packages/core/src/telemetry/tracker.ts` 的 `PARAM_ALLOWLIST` 中字段会进入事件。不得加入 prompt、凭证、文件路径、URL、账号/租户/工作空间 ID 或其他用户内容。
+
+事件同时写入两处：
+
+1. 本地 `~/.bailian/telemetry.jsonl`：权限 `0600`，超过 5 MB 后重建
+2. AEM：`pid=bailian-cli-node`，源码运行自动使用 `env=dev`，npm 安装或编译二进制使用 `env=prod`
+
+底层 Node tracker 还会附加公共设备字段：OS 类型/版本、Node 应用名与版本、平台，以及由本机网络标识计算的 MD5 `device_id`。
+
+当前 AEM 事件没有 `binName` 或 `clientName` 产品维度，并且 `bl`、`kscli` 共用 `pid=bailian-cli-node`。两边相同路径的 `config show`、`config set`、`update` 无法仅凭当前事件稳定区分产品；Knowledge 命令虽然因路径映射不同而表现为 `knowledge chat` 与 `chat`，也不应把命令路径当作长期产品标识。后端 source-config 的 `t2` 已能区分 `bl/kscli`，但这个维度尚未进入 AEM 客户端事件。
+
+AEM 映射：
+
+| AEM 字段   | 内容                                                               |
+| ---------- | ------------------------------------------------------------------ |
+| event name | 命令路径                                                           |
+| `et`       | `EXP`                                                              |
+| `ext`      | 除 `command`、`params` 外的结构化事件字段，包含失败时的 `exitCode` |
+| `c1`       | allowlist 参数                                                     |
+| `c2`       | `success` / `failure`                                              |
+| `c3`       | HTTP status                                                        |
+| `c4`       | 错误文案，最多 500 字符                                            |
+| `c5`       | request ID                                                         |
+
+远端发送是 best-effort，不得阻塞命令或改变退出码。正常退出最多等待 1 秒，SIGINT 最多等待 500 ms。
+
+## 必查清单
+
+### A. 新增或调整命令
+
+- [ ] `defineCommand({ auth })` 必须声明真实请求域；AEM 的 `authMethod` 直接读取该值
+- [ ] 新命令进入 `run` 后自动有基础事件，不得在命令内重复发送同名事件
+- [ ] 需要按产品分析 AEM 数据时，必须显式设计产品字段；不得从命令路径推断 `bl/kscli`
+- [ ] 只有可枚举、数值或布尔等低风险字段才可加入 `PARAM_ALLOWLIST`
+- [ ] 新增 console raw API flag 时只允许记录公开 API 名，不得记录请求 `data`
+
+### B. 调整后端渠道参数
+
+- [ ] 同时核对 `packages/core/src/client/http.ts`、`mcp.ts`、`instrumented-fetch.ts`、`client.ts` 与 `files/upload.ts`
+- [ ] 产品身份必须来自 `Identity`；不得从命令路径、环境变量或 `process.argv` 猜测
+- [ ] `bl` 与 `kscli` 必须分别验证 `binName`、`clientName`、`version`
+- [ ] OSS、结果文件、npm、二进制和 Skill 下载不得为了业务渠道统计新增 source-config
+- [ ] 改 URL / host 范围时同时执行 [URL / 渠道变更](url-change.md) 清单
+
+### C. 调整 AEM 事件
+
+- [ ] 更新 `TrackingEvent`、`createTrackingEvent()` 与 `buildRemoteAemOptions()` 的字段映射
+- [ ] 本地 JSONL 与远端 AEM 必须基于同一结构化事件，不能维护两套字段口径
+- [ ] 成功与失败均覆盖；遥测异常必须静默且不改变业务退出码
+- [ ] runtime 本地语义错误应记录 `exitCode`；新增字段默认随 AEM `ext` 上报，无需占用新的 `c1`—`c5`
+- [ ] 检查 `DO_NOT_TRACK=1` 与 `telemetry: false` 两个关闭入口
+- [ ] 错误字段不得额外拼接 token、请求体、prompt 或本地路径
+
+## 完成后自查
+
+```sh
+rg -n "trackingHeaders|x-dashscope-source-config|User-Agent" packages --glob '*.ts'
+rg -n "trackCommandExecution|PARAM_ALLOWLIST|buildRemoteAemOptions" packages/core packages/runtime --glob '*.ts'
+vp check
+vp test packages/core/tests packages/commands/tests/e2e/auth.e2e.test.ts
+```
+
+## 常见漏点
+
+- ✗ 只看 AEM 命令事件，误以为它能替代网关侧请求渠道统计
+- ✗ 把 `authMethod` 当成实际凭证来源；它只是命令声明的鉴权域
+- ✗ 新增 bypass `fetch` 后漏掉应由网关消费的 source-config，或把它发给 OSS / npm / 第三方下载地址
+- ✗ 只改 `bl` 入口，导致 `kscli` 的产品名或版本标签错误
+- ✗ 把帮助、版本或参数校验失败算进“全部命令”；这些路径当前没有进入 telemetry middleware

docs/agents/url-change.md

@@ -19,6 +19,9 @@ runtime/src/urls.ts                      ← 用户面控制台 URL(cn-only)
   BAILIAN_CONSOLE_ROOT      bailian.console.aliyun.com
   BAILIAN_CONSOLE           BAILIAN_CONSOLE_ROOT/cn-beijing
   API_KEY_PAGE              BAILIAN_CONSOLE/?tab=app#/api-key
+  TOKEN_PLAN_PAGE           BAILIAN_CONSOLE_ROOT/cn-beijing?tab=plan#/efm/subscription/overview
+  MCP_WEBSEARCH_PAGE        mcpMarketplaceDetailPage("WebSearch")
+  mcpMarketplaceDetailPage    BAILIAN_CONSOLE?tab=mcp#/mcp-market/detail/<serverCode>
 
 core/files/upload.ts                     ← 文件上传 endpoint(cn-pinned)
   UPLOAD_API                ${REGIONS.cn}/api/v1/uploads
@@ -48,7 +51,7 @@ grep -rnE "https://dashscope[a-z-]*\.aliyuncs\.com" packages/ --include="*.ts" \
 
 ### B. 非 TS 文件(只能人工同步,无法 import)
 
-- [ ] `skills/bailian-cli/reference/` 各 `<group>.md` 中 API/控制台 URL(`generate:reference` 重建后核对并提交)
+- [ ] `skills/*/reference/` 各 `<group>.md` 中 API/控制台 URL(`generate:reference` 重建后核对并提交)
 - [ ] `README.md` / `README.zh.md` 中所有 URL
 
 ### C. 渠道追踪参数

docs/kb-dsh/2026-08-15-bailian-kb-bundle-design.md

@@ -0,0 +1,195 @@
+# 百炼知识库 dsh 插件（out-of-tree bundle）设计
+
+> 状态：设计已确认并实现（v0.1.0 待真实 API smoke 后打 tag）。
+
+## 1. 背景与目标
+
+为 DeepSeek Harness（dsh）提供阿里云百炼知识库（Knowledge Studio / RAG）垂类能力。经对比 MCP、CLI、API 三种接入通道后确定分层混合架构：
+
+- **高频检索面走 API 直连原生工具**：结构化 schema、进程内 HTTP、结果可 snapshot、体验可打磨；
+- **低频管理长尾走 kscli + skill**：`knowledge-studio-cli`（与 `bl knowledge` 同源实现的轻量发行面）覆盖建库/上传/部署等 34 个子命令，渐进式披露，零插件维护成本；
+- **不做 MCP 通道**：托管 rag MCP 面向不拥有 API/CLI 的第三方宿主，非本方案投入点。
+
+## 2. 范围
+
+**做：**
+
+- 三个模型面工具：`kb_service_list`、`kb_search`、`kb_chat`（API 直连）；
+- 一个管理面 skill（引导 agent 使用 kscli）；
+- bundle 分发形态与配置、凭证、错误、测试设计。
+
+**不做（含理由）：**
+
+| 项                           | 理由                                                                          |
+| ---------------------------- | ----------------------------------------------------------------------------- |
+| `retrieve` 工具              | 服务端已弃用（`search` 取代）；新表面不携带 deprecated 能力，避免近义工具混淆 |
+| MCP 通道                     | 见 §1                                                                         |
+| chat 进展流式 UI（模式 4）   | 一期用缓冲式 + 期望管理，看真实使用反馈再决定（见 §7 与附录 A）               |
+| `run_in_background` 后台模式 | dsh jobs 机制已备好，出现真实需求再加                                         |
+| skills 生态独立分发（B-3）   | 一期 skill 随 bundle 注册；跨宿主分发留待后续                                 |
+| 运行时 API/CLI fallback      | 每个操作固定一条通道；双实现漂移与故障掩盖的代价大于收益                      |
+
+## 3. 总体形态
+
+独立仓库维护的 **out-of-tree bundle**：`package.json` 声明 `dsh.bundle` 指向 patch 文件，安装进 dsh profile 的 patch 层；不进入 deepseek-harness 主仓库，不改变 modelstudioai/cli 仓库的定位。
+
+命名：
+
+- bundle 包：`bailian-kb-bundle`
+- 插件包：`dsh-tool-bailian-kb`
+
+仓库为独立 pnpm workspace（目录 `workspace/bailian-kb-bundle`，独立 git 仓库），两包结构：`packages/tool-bailian-kb`（插件本体：Config、client、三个工具、随包打包的 `skills/bailian-kb-management/SKILL.md`）与 `packages/bundle`（分发面：`dsh.bundle` 声明、`cordis.patch.yml`，`dependencies` 含插件包）。拆分依据：patch row 的 bare 插件名必须出现在 bundle 的 `dependencies`，插件包保持纯净（仅 `@deepseek-ai/cordis` peer + dsh 能力包依赖）。
+
+插件为函数插件形态（`name` / `inject: ['tools']` / `Config` / `apply`），在 `apply(ctx, config)` 中构建共享 API client 并注册三个工具。
+
+### 3.1 接入与配置流程
+
+**bundle 侧接入契约**（`@deepseek-ai/dsh-base` 为模板）：
+
+- `package.json` 声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`，并在 `exports` 暴露 `./cordis.patch.yml`；
+- `cordis.patch.yml` 用 `insert` 插入插件 row 与 skill 注册 row；row 中的 bare 插件名必须出现在 bundle 自身的 `dependencies`；
+- 发布到 npm，或直接以 git spec 分发（`github:<org>/<repo>`）。
+
+**用户安装**：
+
+```sh
+dsh plugin --profile web add bailian-kb-bundle
+```
+
+CLI 转发 pnpm 将 bundle 装为 profile dependency；安装后自动 reconcile——检测到 `dsh.bundle` 声明即加入 `dsh.profile.bundles` 层栈，无需手改 YAML。boot 层序为 `dsh-base` → … → 本 bundle patch → profile `cordis.patch.yml` → 家目录 `cordis.patch.yml`，用户 patch 层在本 bundle 之上，插入的任何 row 均可被按 id 覆盖或禁用。卸载 `dsh plugin --profile web remove bailian-kb-bundle` 自动收回层栈。
+
+**配置落点**：用户 patch 是整 config 替换（无 deep-merge），因此 bundle row 的 config 默认从环境读取：
+
+```yaml
+config:
+  workspaceId: !!js process.env.BAILIAN_WORKSPACE_ID
+```
+
+用户将 `BAILIAN_WORKSPACE_ID` 写入 `~/.dsh/.env` 即可运行（`DASHSCOPE_API_KEY` 放同处或 `.credentials.yaml`）；需要精细控制的部署再以 id-targeted patch 覆盖整个 config。`workspaceId` 缺失时按 §6 在加载期 fail loud，错误信息指向 `.env` 配置方式。验证入口：`dsh --profile web --dump-config` 可见本 bundle 的 row。
+
+**本地开发迭代**：checkout 内 `dsh plugin --profile dev add .`（相对路径锚定调用目录）；patch 文件受 HMR 监听，编辑后自动 recompose。
+
+## 4. 模型面工具
+
+### 4.1 `kb_service_list`
+
+发现当前 workspace 的检索/问答服务（百炼"检索服务"，即 `agent_id` 的来源）。
+
+| 参数          | 类型                    | 必填 | 语义                                                                                                               |
+| ------------- | ----------------------- | ---- | ------------------------------------------------------------------------------------------------------------------ |
+| `scene`       | enum `chat` \| `search` | 否   | 省略时插件内部对两个 scene 各查一次并合并；每个条目携带 scene 标记（指明该服务配 `kb_chat` 还是 `kb_search` 使用） |
+| `name_filter` | string                  | 否   | 服务名模糊匹配，透传服务端 `agent_name`                                                                            |
+
+返回：服务条目数组（`agent_id`、名称、描述、scene、status、绑定的知识库）+ `total`。
+
+**分页内部消化**：固定 `page_size=100, page_number=1`（服务端上限 100）。`total > 100` 时结果末尾附提示 `listed first 100 of N services; narrow with name_filter`。不向模型暴露翻页参数——模型的导航原语是名字过滤，不是页码。
+
+**status 不作为参数**：条目携带 `status` 字段，description 提示优先使用 `deployed`；draft 服务仅在 `agentVersion: beta` 的调试部署下可调（部署期概念，不占模型参数面）。
+
+### 4.2 `kb_search`
+
+语义检索，返回原始知识片段供 agent 综合与引用。
+
+| 参数       | 类型     | 必填       | 语义                                                                                                                                     |
+| ---------- | -------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `query`    | string   | 是         | 检索文本                                                                                                                                 |
+| `agent_id` | string   | 见 §5      | 检索服务 id（scene=search 的服务）；检索范围与策略（多库加权、路由、重排）由服务端配置决定                                               |
+| `top_k`    | integer  | 否，默认 5 | 返回片段数上限。服务端 search API 无此参数（条数由检索服务配置决定），插件对按 score 降序的 `nodes` 做客户端截断；description 写明该语义 |
+| `images`   | string[] | 否         | 多模态检索的图片 URL                                                                                                                     |
+
+返回：chunks 数组（内容 + 来源引用）。
+
+### 4.3 `kb_chat`
+
+知识库成品问答。服务端为 agentic loop（分析 → 多轮检索 → 生成），耗时可达分钟级。
+
+| 参数       | 类型   | 必填  | 语义                      |
+| ---------- | ------ | ----- | ------------------------- |
+| `message`  | string | 是    | 问题                      |
+| `agent_id` | string | 见 §5 | 问答服务 id（scene=chat） |
+
+返回：完整答案文本（含 API 提供的引用信息时一并返回）。
+
+### 4.4 description 路由策略
+
+`kb_search` 与 `kb_chat` 的 description **互相指名分界**，把"该用谁"写成可判断条件而非形容词：
+
+- `kb_search`：returns raw knowledge chunks with source references；用于需要核实、引用、或与其他上下文结合推理的场景；
+- `kb_chat`：a complete, domain-tuned answer produced by a specialized RAG pipeline (retrieval + reranking + grounded generation)；知识问答场景通常优于自行检索综合（typically outperforms searching and synthesizing yourself when the question can be answered by the knowledge base alone）；并注明 may take a few minutes。
+
+## 5. `agent_id` 的三种场景覆盖
+
+| 场景          | 机制                                                                                                        | 插件成本                 |
+| ------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------ |
+| 发现式        | `kb_service_list` → 选服务 → search/chat；`agent_id` 缺失或无效时，错误信息直接附当前服务清单，模型一步纠正 | 发现工具 + 错误增强      |
+| 用户习惯固定  | 宿主 memory / 项目指令记住常用 `agent_id`                                                                   | 零（skill 写入最佳实践） |
+| 场景/部署固定 | Config 可选 `defaultAgentId`；配置后注册时将 `agent_id` 参数降为可选，description 注明缺省服务              | 一个可选配置字段         |
+
+**Schema 形态在加载期由配置静态决定**（未配 `defaultAgentId` 则 `agent_id` 必填），不是运行时 fallback；每个部署只有一条清晰规则，KV cache 前缀与 snapshot 均稳定。与 dsh preset 组合可实现按场景绑定（如客服 preset 固定客服库）。
+
+## 6. 配置与凭证
+
+```ts
+interface Config {
+  /** 百炼工作空间 id。知识库 API 的 host 为 workspace 子域名：`https://<workspaceId>.<endpointHost>`。必填。 */
+  workspaceId: string;
+  /** 知识库 API 的 host 后缀。默认 `cn-beijing.maas.aliyuncs.com`；其他 region/私有化部署时替换。 */
+  endpointHost: string;
+  /** 场景固定式部署绑定的检索服务 id。可选。 */
+  defaultAgentId?: string;
+  /** 调用的服务版本：beta（草稿调试）或已发布版本号。可选，缺省最新发布版。不暴露给模型。 */
+  agentVersion?: string;
+  /** kb_chat 超时毫秒数。chat 为分钟级 loop，部署必须可调。默认 300000（5 分钟）。 */
+  chatTimeoutMs: number;
+}
+```
+
+- schemastery 校验；缺失/非法配置在**加载期 fail loud**；
+- API Key 走 `ctx.credentials` 引用（`DASHSCOPE_API_KEY`，env/.env provider），不进 Config、不进会话日志、不被 `--dump-config` 打印；
+- URL 拼接是 `(endpointHost, workspaceId, path) → endpoint` 的纯函数（`https://${workspaceId}.${endpointHost}${path}`，与 kscli 的 `ragEndpoint` 同构），与请求构造、错误翻译一起收在插件内部的共享 client 中（协议路径为代码常量，不进配置）。
+
+## 7. 执行语义
+
+- **`kb_chat` 缓冲式**（与 bash 前台/subagent 同构的仓库惯例：dsh 中没有工具向模型或 UI 中途推流）：`execute` 内部消费完 SSE，一次性返回完整答案。UI 呈现为 `presentCall` pending 卡片 → `presentResult` 完成卡片（`generic` 卡，纯函数、replay-safe）；
+- **期望管理**：description 与 pending 卡片标题注明 may take a few minutes；
+- **超时**：`chatTimeoutMs` 显式可配（dsh tool-timeout guard 可另行部署级配置）；
+- **超长输出**：声明依赖 dsh spill 子系统兜底，插件不自造截断。
+
+## 8. 管理面 skill
+
+- SKILL.md 随插件包打包；插件在 skills 服务可用时通过 `ctx.inject(['skills'], …)` 以 `ctx.skills.register()` 运行时注册（`source: 'bundled'`，`resourceBase` 指向包内 skill 目录），无 skills 服务的组合不受影响；工具与 skill 同版本发布，互相引用不漂移；
+- 内容：kscli 安装引导（`npm install -g knowledge-studio-cli`）、API Key 与 workspace 解析（flag > `BAILIAN_WORKSPACE_ID` > 配置文件）、典型工作流（建库 → 上传 → 等解析 → 部署服务 → 检索验证）、"常用 `agent_id` 写入项目指令/记忆"最佳实践、检索面与管理面的分工说明（search/chat 用原生工具，不走 kscli）；
+- kscli 未安装时管理操作 fail loud 并给出安装命令；检索面不受影响。
+
+## 9. 错误处理
+
+- HTTP 错误翻译为模型可操作的文本：无效 `agent_id` → 附当前服务清单；鉴权失败 → 指向 API Key 获取与配置方式；超时 → 说明 chat 可能耗时并建议重试或改用 search；
+- 凭证缺失在首次可解析点大声失败，不静默降级；
+- 服务端非 2xx 的响应体原样摘要进错误信息（截断至安全长度），便于模型与用户诊断。
+
+## 10. 测试策略
+
+| 层       | 内容                                                                                          |
+| -------- | --------------------------------------------------------------------------------------------- |
+| 单元测试 | endpoint 拼接、请求体构造（scene 合并、分页内化、`defaultAgentId` 解析）、错误翻译            |
+| snapshot | mock HTTP fixture 的可重放 keyless snapshot，macOS/Linux 均可回放；覆盖三工具的调用与渲染卡片 |
+| e2e      | 真实 DashScope API，无 `DASHSCOPE_API_KEY` 时自跳过                                           |
+
+## 附录 A：预留扩展（已设计方向，未排期）
+
+- **chat 进展流式（模式 4）**：`execute` 消费 SSE 时 append 工具自有会话事件（如 `bailian/chat-progress`，`ignorable: true`），Web 客户端注册 `ConversationNodeDefinition` 渲染器实时显示；模型面不变（logged ≠ model-visible）。触发条件：真实用户对 chat 等待体验的负反馈；
+- **后台模式**：`kb_chat` 增加 `run_in_background`，挂 `ctx.jobs`，`job_output` 收取；
+- **skills 生态分发（B-3）**：以 bundle 仓库的 SKILL.md 为唯一源，发布到 `npx skills add` 生态覆盖其他宿主；
+- **能力缝升级**：出现第二种传输（如私有化内网网关）时，将共享 client 提为 `ctx.<key>` 服务，按 Service Definition / Provider / Consumer 三角色拆分。
+
+## 附录 B：关键决策记录
+
+| 决策            | 结论                                        | 理由摘要                                                            |
+| --------------- | ------------------------------------------- | ------------------------------------------------------------------- |
+| 接入通道        | API（检索面）+ CLI（管理面），不做 MCP      | 频率×能力深度×控制权分层；API/CLI 均为己方资产                      |
+| CLI 选型        | kscli 而非 bl                               | 同源实现零能力损失；命令面窄、鉴权单一、onboarding 短               |
+| `retrieve`      | 不做                                        | 已弃用，避免近义工具                                                |
+| `kb_chat` 门控  | 不门控，常驻注册                            | 服务端 RAG 管线在知识问答场景更专业，description 写明场景让模型路由 |
+| `agent_id` 归属 | 模型参数 + 发现工具 + 可选 `defaultAgentId` | 检索服务是用户运行时资产，插件与部署配置不应假设                    |
+| chat 流式       | 一期缓冲式                                  | 仓库惯例（bash/subagent 同构）；进展流式留待反馈                    |
+| 分页            | 内部消化（page_size=100 + 溢出提示）        | 模型导航原语是 name 过滤，非页码                                    |

docs/kb-dsh/runtime-behavior.md

@@ -0,0 +1,143 @@
+# bailian-kb-dsh 运行时行为（内部说明）
+
+面向维护者：记录 `packages/bailian-kb-dsh` 里那些**为什么这么做**的选择。用户面文档在 [packages/bailian-kb-dsh/README.md](../../packages/bailian-kb-dsh/README.md)（中文版 `README.zh.md`），改动清单在 [docs/agents/dsh-plugin.md](../agents/dsh-plugin.md)。
+
+## Bundle 声明与配置分层
+
+`package.json` 的 `dsh.bundle.patch` 指向 `cordis.patch.yml`，向 profile 插入插件行：
+
+```yaml
+- insert:
+    - id: tool-bailian-kb
+      name: "bailian-kb-dsh"
+      config:
+        workspaceId: !!js process.env.BAILIAN_WORKSPACE_ID
+```
+
+`workspaceId` 只是解析链的一层，不是唯一来源：Config 同时注册为 `bailian-kb` settings namespace，patch entry 作 base 层，设置页 / 设置文档的用户层叠在其上；都未设置时 per-call 回退到 `BAILIAN_WORKSPACE_ID` credential。同样的回退覆盖 `defaultRetrieveAgentId`（`BAILIAN_DEFAULT_RETRIEVE_AGENT_ID`）、`defaultChatAgentId`（`BAILIAN_DEFAULT_CHAT_AGENT_ID`）与 API key（`DASHSCOPE_API_KEY`，无 settings 面）。
+
+settings 注册是**手写**的，没有用 `installSettingsSection`：需要两个它不带的东西 —— `expose` opt-in（设置页从浏览器改这个 section）和凭据迁移要写入的 scope handle。所有值每次调用经 source thunk 读取，因此设置改动无需重启或重注册工具。
+
+### 四个值的解析链
+
+| 值                                  | 1️⃣ settings 用户层（设置页可编辑、回显） | 2️⃣ entry config（patch 或用户覆盖，作 base 层） | 3️⃣ credential（`~/.dsh/.credentials.yaml` / env） | 4️⃣ 都缺失时                                                       |
+| ----------------------------------- | ---------------------------------------- | ----------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------- |
+| `DASHSCOPE_API_KEY`                 | —（无 settings 面）                      | —（无 config 面）                               | ✅                                                | 工具调用报错并引导配置                                            |
+| `BAILIAN_WORKSPACE_ID`              | ✅ `workspaceId`                         | ✅ `workspaceId`                                | ✅                                                | 工具调用报错并引导配置                                            |
+| `BAILIAN_DEFAULT_RETRIEVE_AGENT_ID` | ✅ `defaultRetrieveAgentId`              | ✅ `defaultRetrieveAgentId`                     | ✅                                                | 该 scene 只有一个已部署服务时取它；否则省略 `agent_id` 的调用报错 |
+| `BAILIAN_DEFAULT_CHAT_AGENT_ID`     | ✅ `defaultChatAgentId`                  | ✅ `defaultChatAgentId`                         | ✅                                                | 同上                                                              |
+
+"唯一服务即默认"这一层是 2C 部署的零配置路径：只有一个服务时没有可选项，逼用户在设置里点一次名字买不到任何东西。注意 `agent_id` 在两个工具的 schema 中**恒必填**，模型路径不会触发默认服务回退；回退保留是为程序化调用与 credential 热切换。
+
+行为参数（`endpointHost` / `agentVersion` / `chatTimeoutMs`）只在 config/settings 层（设置文档可改，实时生效）。
+
+解析后的 workspaceId 还经 `shellEnv` 注册导出为 `BAILIAN_WORKSPACE_ID`，否则 settings 文档里的值对 bash 子进程（`bl knowledge …`）不可见。
+
+### 用户覆盖
+
+用户 patch 层在本 bundle 之上，按 id 覆盖时**替换整个 config（无 deep-merge）**：
+
+```yaml
+# ~/.dsh/cordis.patch.yml 或 profile 的 cordis.patch.yml
+- id: tool-bailian-kb
+  config:
+    defaultRetrieveAgentId: aid-search-service
+    defaultChatAgentId: aid-chat-service
+    chatTimeoutMs: 600000
+```
+
+禁用：`- id: tool-bailian-kb` + `disabled: true`。
+
+## Web UI 配置页
+
+装进 profile 后，Settings 左侧导航出现"百炼知识库"页（`settings.section` 槽位）：
+
+- **DashScope API Key** — write-only，`type=password` 遮罩输入草稿，仅显示 configured / 来自环境变量 徽标；写 `~/.dsh/.credentials.yaml`
+- **Bailian Workspace ID / 默认检索服务 ID / 默认对话服务 ID** — 回显：读写 `bailian-kb` settings 用户层，预填当前解析值；清空保存 = 移除用户层，回退 entry config → credential。两个服务 ID 可从服务缓存里选
+- **自动获取** — 按钮调 Host 桥接路由 `/bailian-kb/autofill`：Host 在宿主机拉起浏览器登录百炼控制台（不经 `bl` 命令），回调落到本机 loopback 端口后直接把 API 密钥写入凭据存储、工作空间 ID 写入 settings，明文 key 不过浏览器；面板轮询到完成后自动刷新（无需再次点击）。登录 URL 始终请求签发新 key，因此每次都与当前账号配对，切换账号直接点一次即可
+- **检索服务缓存** — 经 `/bailian-kb/services` 读缓存诊断（上次拉取时间、各 scene 条数、是否截断）并提供强制刷新按钮：面板存在的意义就是"开发者认为缓存不对"的那一刻
+
+桥接路由（`/bailian-kb/settings`、`/bailian-kb/services`、`/bailian-kb/autofill`）而不是 settings wire：wire 需要 apiproxy 白名单，而 composition 不给树外 namespace 授权。GET 和 POST 共用一次 exact-route 注册 —— webServer map 按 (kind, path) 建键，同路径注册两次会抛 "duplicate route"。
+
+首次接入 seed：启动时若 API key / workspaceId 从未被设置过（settings、credential、env 均无值），自动从 `~/.bailian/config.json` 采纳一次；`seededFields` 字段（settings 文档内，面板不可编辑）记账已消费 / 已由用户管理的字段，用户主动清空的值永不会被重新填回。
+
+降级：远程浏览器（非 loopback，settings RPC 不可达）或未组合 settings 服务时，ID 字段退回旧的 write-only credential 控件，页面顶部显示提示。
+
+## 检索服务缓存与上下文注入
+
+模型要判断"该不该检索"，靠的是看到本 workspace 部署了哪些检索服务。插件内部经 `/api/v1/indices/rag/app/list` 拉取该清单并缓存，**不对模型暴露服务发现工具**（`kb_service_list` 不会回归：它会把"先 list 再 search"的额外一轮重新引入）；管理面仍用 bl。
+
+补查型工具（"只按关键词查、不列全部"的 `service_find`）也评估过，同样不做。理由不是成本而是**收益已被占掉**：唯一能支撑它的论据是"兜底走 bash + bl 不一定可用"，而管理面本来就以 bl 为前提；catalog 那条通道是零轮次、无条件注入、且带截断告知与默认收敛策略，再开第三个入口只会跟它抢事实源。真正要补的是兜底路径本身——见下面两小节。
+
+### 载体：上下文消息，不是工具描述
+
+两个工具的 **description 保持静态**（不含任何服务 id）。清单经 `agent/pre-step` 注入为一条带 source 的 `UserMessage`（`{ kind: 'plugin', plugin: 'tool-bailian-kb/services', form: 'catalog' }`），而不是烘进 tool description。两个原因：
+
+1. **插件加载是每进程一次，不是每会话一次。** 描述在 `apply()` 时定型，长驻宿主里 TTL 只会被评估一次，用户在控制台新建的服务要等重启才能被感知；
+2. **重注册工具会废掉 prompt 前缀缓存**（从第一个变化的 schema token 起）。走上下文消息则让 schema 永久稳定。
+
+**变化抑制是正确性要求，不是优化**：`pre-step` 每个"步"（= 一次模型请求）触发一次，一轮里调 5 次工具就触发 6 次。只有清单内容变化时才重发，且判定叠加**可见性**（`session.surface.nodes`）—— 压缩把清单消息裁掉后会自动重新注入，否则模型会静默失去清单。
+
+### 清单内容策略
+
+| 情形                     | 注入内容                                                                             |
+| ------------------------ | ------------------------------------------------------------------------------------ |
+| 配了默认服务             | 只列该服务 + "另有 N 个" 提示                                                        |
+| 未配默认，deployed ≤ 10  | 全量 `agent_id` + 名称                                                               |
+| 未配默认，deployed > 10  | 按 `modify_time` 倒序取 10 条，**显式标明截断**与总数                                |
+| 缓存里 0 个服务          | 注入 `buildNoServiceNotice()`：禁止编 id，并给出建服务/部署服务的路径（控制台或 bl） |
+| 无缓存文档（含拉取失败） | 不注入（工具仍可用）                                                                 |
+
+英文框架 + 服务名原样保留；空 scene 整节省略；截断必须告知（静默截断会让模型把清单当全集，进而断言"没有对应知识库"）。
+
+最后两行的差别是**能不能下断言**：缓存里有文档但 0 条，是权威的"这个 workspace 没有可调服务"，说出来比沉默好——`agent_id` 恒必填，沉默只会让模型编一个 id（换来服务端裸报错）或静默放弃检索，两者在用户看来都像插件坏了。没有文档则意味着首拉还没落地或一直失败，此时任何断言都是猜，交给后台刷新在后续 step 自愈。
+
+注意这与"空 scene 整节省略"不冲突：空的**节**是噪音（另一节仍在给 id），空的**清单**是模型手里一个 id 都没有。
+
+### bl 引导只出现在动态载体上
+
+工具描述是静态的，每次请求都付；而"怎么进一步查"取决于当下部署了什么。所以 `agent_id` 的参数描述**只指向上下文清单**，不写 `bl` 命令；`bl` 出现在两处动态文本里，且**每次出现都带安装方式**（`npm install -g bailian-cli`）：
+
+- catalog 中真正推荐了命令的分支（截断、收敛到默认服务）；
+- 4xx 之后追加的服务清单（`buildRefreshedSceneList`）。
+
+带安装行是必需的：插件走 API 直连、从不 shell out，所以一个凭据齐全的部署完全可能没装 `bl`。而安装引导原本只写在 `skills/bailian-kb/SKILL.md` 的前置检查里，那是二阶决策——要模型先决定加载 skill 才读到，恰好漏掉走工具描述兜底的那个模型。
+
+### 缓存与刷新
+
+落点：`${DSH_HOME:-~/.dsh}/cache/bailian-kb/services-<workspaceId>.json`（临时文件 + `rename()` 原子发布，目录 `0o700`）。按 workspace 分文件是必需的：api key 只能访问自己的 workspace，而"自动获取"按钮就是为了切账号。
+
+存：`agent_id` / `agent_name` / `scene` / `status` / `modify_time`，预留 `description`（待列表接口返回）。**不存 `pipeline_list`** —— 它不稳定携带 `pipeline_name`，做不了知识库标签。
+
+| 刷新触发点                                                                         | 模型何时看见                         |
+| ---------------------------------------------------------------------------------- | ------------------------------------ |
+| pre-step 间隔调度（超 TTL 30 分钟，后台异步，**不阻塞**）                          | 下一步                               |
+| 控制台登录成功（`/bailian-kb/autofill` 回调）                                      | 下一步                               |
+| agent 跑了 `bl knowledge service create/deploy/delete/copy`（`tools/result` 观察） | 下一步                               |
+| 面板强制刷新（`POST /bailian-kb/services`）                                        | 下一步                               |
+| 调用撞 4xx（agent_id 已失效）                                                      | **本步**，刷新后的列表追加进错误消息 |
+| workspaceId / apiKey 变更                                                          | 下一步                               |
+
+`tools/result` 的匹配是在序列化参数里找命令串，而不是认某个具体工具名：agent 可能用 bash、终端工具或 run_code 跑 `bl`。宽匹配是故意的 —— 误判只多花一次 list 请求，漏判则退回 TTL。
+
+刷新失败只 warn，保留旧文档；并发刷新共享一个请求（pre-step 每步都会检查）。pre-step 监听器**永不抛异常** —— 抛出会使用户当前这一步失败。未组合 `agents` 的 headless 装配只是没有清单，工具照常可用。
+
+## 错误语义
+
+- HTTP 错误：4xx 时刷新服务缓存并把当前可用服务追加进错误消息（这两个接口上 `agent_id` 是唯一的调用方标识符，所以 4xx 大多是 id 已失效）；刷新后该 scene **一个服务都没有**时也照样追加说明（明确"别换 id 重试"+ 建服务路径），而不是放裸错误过去——裸的 `invalid agent_id` 读起来就是"再试一个"；5xx 与刷新本身失败则原错误透传；
+- 凭证缺失：指向 `~/.dsh/.env` / `.credentials.yaml` 配置方式与控制台取 key 页面；
+- chat 超时：说明服务端多轮检索特性，建议重试或改用 `kb_search`；
+- 服务端错误体截断至 500 字符进入错误信息（优先 `code: message`）。
+
+## 管理面 skill
+
+`skills/bailian-kb/SKILL.md` 随包分发，插件通过 `ctx.inject(['skills'])` 在 skills 服务可用时以 `source: 'bundled'` 运行时注册；无 skills 服务的组合（headless 最小装配）不受影响。文件的 YAML frontmatter 是 name / description 的**单一事实源**，注册时会被剥离（`SkillDefinition.content` 契约上是已去元数据的正文，而 runtime 注册路径不做任何解析）。
+
+内容：bl CLI 安装 / 鉴权 / workspace 解析、建库 → 上传 → 部署工作流、服务清单的行为语义。**skill 不承担"该不该检索"的引导**（那是工具描述与上下文清单的事：skill 正文要模型先决定加载才能读到，是二阶决策）；它反过来承担一件工具做不到的事：**引导 agent 在 `service create` 时把服务名写清楚**。无 desc 时服务名是唯一语义来源，管理面的动作直接决定检索面的效果。
+
+## 已知限制的成因
+
+- kb_chat 执行期无进展显示（缓冲式消费 SSE）。
+- `top_k` 是客户端截断：请求体不含该参数，服务端返回条数由检索服务配置决定，截断只影响进入模型上下文的量。
+- **服务画像的质量上限取决于服务名**：`service list` 接口当前不返回描述字段，所以模型只能靠 `agent_name` 判断一个服务能查什么。名字模糊的部署引导能力接近于零。列表接口补齐描述字段后只需改三处（`api-types` 补字段名 → `services.ts` 解析 → `buildServiceCatalog` 追加并截断到 200 字符），缓存已预留 `description` 键，无需迁移。
+- 拉取每个 scene 最多 2 页，超出时标 `truncated` 并在清单里告知。

docs/knowledge/chunk.md

@@ -0,0 +1,248 @@
+# Chunk 管理命令手册
+
+Chunk 是知识库中最小的检索单元。文档导入后自动切分为 chunk，也可以手动添加。
+
+> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](../knowledge-cli-guide.md#通用约定)。
+
+---
+
+#### `bl knowledge chunk add`
+
+直接向知识库添加 chunk。
+
+**用法**
+
+```bash
+bl knowledge chunk add --index-id <id> (--content <text> | --field <k=v>) [flags]
+```
+
+**参数**
+
+| 参数                    | 类型   | 必填 | 说明                                                                                        |
+| ----------------------- | ------ | ---- | ------------------------------------------------------------------------------------------- |
+| `--index-id <id>`       | string | 是   | 知识库 ID                                                                                   |
+| `--doc-id <id>`         | string | 否²  | 所属文档 ID；表格/图片知识库必填，文档型可选                                                |
+| `--content <text>`      | string | 否¹  | Chunk 正文，最多 6000 字符（文档型）；与 `--content-file` 互斥                              |
+| `--content-file <path>` | string | 否¹  | 从 UTF-8 文本文件读取正文（`.md`/`.txt` 等）；与 `--content` 互斥                           |
+| `--title <text>`        | string | 否   | Chunk 标题，最多 50 字符（文档型）                                                          |
+| `--image-url <url>`     | array  | 否   | Chunk 图片 URL（可重复，最多 10 个；文档型）                                                |
+| `--field <key=value>`   | array  | 否¹  | 任意字段键值对（可重复），用于表格/图片知识库，键为 Excel 列名；与 content/title/image 互斥 |
+
+> ¹ `--content`/`--content-file`/`--title`/`--image-url` 与 `--field` 互斥，必须提供其一。
+> ² 表格/图片知识库必须提供 `--doc-id`。文档型知识库可选。
+
+**参数约束**
+
+- `--field` 与 `--content`/`--content-file`/`--title`/`--image-url` 互斥
+- `--content` 与 `--content-file` 互斥
+- `--content` 最多 6000 字符
+- `--title` 最多 50 字符
+- `--image-url` 最多 10 个
+
+**输出**
+
+text 模式：
+
+```
+chunk created (pipeline: idx-xxx)
+List chunks to find the new chunk id.
+```
+
+quiet 模式：无输出（成功退出码 0）。
+
+json 模式：返回 API 原始响应（不含 chunk ID）。
+
+**注意事项**
+
+- 支持文档/表格/图片知识库；音视频知识库不支持。
+- API 响应不含 chunk ID，需用 `chunk list` 查找新 chunk。
+- API 幂等但限流 10 次/秒，批量脚本需自行节流。
+- 表格/图片知识库用 `--field`，键为 Excel 列名，值为字符串。
+
+**示例**
+
+```bash
+# 添加文本 chunk
+bl knowledge chunk add --index-id idx-xxx --content "chunk text" --title intro --workspace-id ws-xxx
+
+# 添加表格行（字段方式）
+bl knowledge chunk add --index-id idx-xxx --field 列A=v1 --field 列B=v2
+
+# 从文件读取内容
+bl knowledge chunk add --index-id idx-xxx --content-file ./chunk.md --doc-id doc-xxx
+```
+
+---
+
+#### `bl knowledge chunk list`
+
+列出知识库中的 chunk，含内容和状态。
+
+**用法**
+
+```bash
+bl knowledge chunk list --index-id <id> [flags]
+```
+
+**参数**
+
+| 参数                | 类型   | 必填 | 说明                           |
+| ------------------- | ------ | ---- | ------------------------------ |
+| `--index-id <id>`   | string | 是   | 知识库 ID                      |
+| `--doc-id <id>`     | string | 否   | 只显示属于此文档的 chunk       |
+| `--page-number <n>` | number | 否   | 页码（默认：1）                |
+| `--page-size <n>`   | number | 否   | 每页条数（默认：20，最大 100） |
+
+**参数约束**
+
+- `--page-size` 范围 1-100
+
+**输出**
+
+text 模式：
+
+```
+[chunk] chunk-xxx  (doc: intro.md, doc_id: file-xxx)  status: COMPLETED
+  chunk content preview (truncated at 200 chars)…
+total: 1
+```
+
+> 如果 chunk 被排除检索，行尾会显示 `[excluded from retrieval]`。
+
+quiet 模式：每行一个 `metadata._id`（chunk ID），用于管道传给 update/delete。
+
+json 模式：返回 API 原始响应，`data.nodes[]` 含完整 chunk 数据。
+
+**注意事项**
+
+- 用 `metadata._id` 作为 chunk ID，`metadata.doc_id` 作为文档 ID，在 chunk update/delete 中使用。
+- 页大小默认 20，最大 100。
+
+**示例**
+
+```bash
+# 列出所有 chunk
+bl knowledge chunk list --index-id idx-xxx --workspace-id ws-xxx
+
+# 只看某文档的 chunk
+bl knowledge chunk list --index-id idx-xxx --doc-id file-xxx --page-size 50
+```
+
+---
+
+#### `bl knowledge chunk update`
+
+更新 chunk 内容或切换其检索可见性。
+
+**用法**
+
+```bash
+bl knowledge chunk update --index-id <id> --chunk-id <id> --doc-id <id> [flags]
+```
+
+**参数**
+
+| 参数                    | 类型   | 必填 | 说明                                                   |
+| ----------------------- | ------ | ---- | ------------------------------------------------------ |
+| `--index-id <id>`       | string | 是   | 知识库 ID                                              |
+| `--chunk-id <id>`       | string | 是   | Chunk ID（`metadata._id`，来自 chunk list 输出）       |
+| `--doc-id <id>`         | string | 是   | 所属文档 ID（`metadata.doc_id`，来自 chunk list 输出） |
+| `--content <text>`      | string | 否¹  | 新内容，10-6000 字符；与 `--content-file` 互斥         |
+| `--content-file <path>` | string | 否¹  | 从 UTF-8 文本文件读取新内容                            |
+| `--title <text>`        | string | 否   | Chunk 标题，0-50 字符（空字符串清除标题；不传则不变）  |
+| `--exclude`             | switch | 否²  | 将此 chunk 排除出检索                                  |
+| `--include`             | switch | 否²  | 将此 chunk 恢复检索（默认行为）                        |
+
+> ¹ `--content` 与 `--content-file` 互斥。
+> ² `--exclude` 与 `--include` 互斥。
+
+**参数约束**
+
+- `--content` 与 `--content-file` 互斥
+- `--exclude` 与 `--include` 互斥
+- 至少提供一个更新项（`--content`/`--content-file`/`--title`/`--exclude`/`--include`）
+- `--content` 长度 10-6000 字符
+- `--title` 最多 50 字符
+
+**输出**
+
+text 模式：
+
+```
+updated: chunk-xxx
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 内容必须 10-6000 字符，且不超过知识库的 max chunk size。
+- `--content-file` 期望 UTF-8 纯文本文件，不解析 `.docx`/`.pdf` 等文档格式。
+- 仅切换 `--exclude`/`--include` 而不提供新内容时，CLI 自动读回当前内容并重新提交（API 要求 content 字段必填，CLI 隐藏了此限制）。
+
+**示例**
+
+```bash
+# 修改内容
+bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --content "corrected text" --workspace-id ws-xxx
+
+# 排除 chunk 不参与检索
+bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --exclude
+
+# 恢复检索
+bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --include
+```
+
+---
+
+#### `bl knowledge chunk delete`
+
+从知识库中删除 chunk（不可逆）。
+
+**用法**
+
+```bash
+bl knowledge chunk delete --index-id <id> --chunk-id <id> [flags]
+```
+
+**参数**
+
+| 参数              | 类型   | 必填 | 说明                                             |
+| ----------------- | ------ | ---- | ------------------------------------------------ |
+| `--index-id <id>` | string | 是   | 知识库 ID                                        |
+| `--chunk-id <id>` | array  | 是   | Chunk ID（可重复，每批最多 10 个，超出自动分批） |
+| `--yes`           | switch | 否   | 显式确认执行高风险操作                           |
+
+**输出**
+
+text 模式：
+
+```
+deleted: 2 chunk(s) in 1 batch(es)
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 `{ deleted_count, batches }`。
+
+**注意事项**
+
+- 服务端每次最多接受 10 个 chunk ID，CLI 自动分批。
+- 如果某批失败，操作停止，已删除的批次会在错误 hint 中列出。
+- Chunk 被永久移除，不可恢复。
+
+**示例**
+
+```bash
+# 删除多个 chunk
+bl knowledge chunk delete --index-id idx-xxx --chunk-id chunk-a --chunk-id chunk-b --workspace-id ws-xxx
+
+# 跳过确认
+bl knowledge chunk delete --index-id idx-xxx --chunk-id chunk-a --yes
+```
+
+---
+
+← [返回总览](../knowledge-cli-guide.md)

docs/knowledge/collection-category.md

@@ -0,0 +1,268 @@
+# 数据中心集合与分类命令手册
+
+集合（collection）是数据中心的顶层容器，对应服务端的 connector。分类（category）用于组织集合内的文件，支持多级嵌套。
+
+> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](../knowledge-cli-guide.md#通用约定)。
+
+---
+
+#### `bl knowledge collection create`
+
+创建 FILE 数据集合。
+
+**用法**
+
+```bash
+bl knowledge collection create --name <text> --description <text> [flags]
+```
+
+**参数**
+
+| 参数                   | 类型   | 必填 | 说明                                                             |
+| ---------------------- | ------ | ---- | ---------------------------------------------------------------- |
+| `--name <text>`        | string | 是   | 集合名称（1-20 字符）                                            |
+| `--description <text>` | string | 是   | 集合描述                                                         |
+| `--store-type <type>`  | string | 否   | 存储类型：`platform`（托管，默认）或 `custom`（自有 OSS bucket） |
+| `--oss-region <id>`    | string | 否   | OSS region ID（`--store-type custom` 时必填）                    |
+| `--oss-bucket <name>`  | string | 否   | OSS bucket 名称（`--store-type custom` 时必填）                  |
+
+**参数约束**
+
+- `--name` 长度 1-20 字符
+- `--store-type` 只能是 `platform` 或 `custom`
+- `--store-type custom` 时 `--oss-region` 和 `--oss-bucket` 必填
+
+**输出**
+
+text 模式：
+
+```
+created: conn-xxx  (my-collection, PLATFORM)
+```
+
+quiet 模式：输出集合 ID。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- `platform` 使用平台托管存储；`custom` 使用已授权的 OSS bucket。
+- 自定义 bucket 必须携带标签 `bailian-connector-access=ReadAndWrite`（百炼的标签访问控制），否则服务端报 `setBucketCORS failed` 误导性错误。
+- **无集合删除 API**，创建需谨慎。
+
+**示例**
+
+```bash
+# 创建平台托管的集合
+bl knowledge collection create --name my-collection --description "team docs" --workspace-id ws-xxx
+
+# 创建使用自有 OSS bucket 的集合
+bl knowledge collection create --name oss-coll --description "own bucket" --store-type custom --oss-region cn-beijing --oss-bucket my-bucket
+```
+
+---
+
+#### `bl knowledge collection get`
+
+查看数据集合详情。
+
+**用法**
+
+```bash
+bl knowledge collection get (--collection-id <id> | --name <text>) [flags]
+```
+
+**参数**
+
+| 参数                   | 类型   | 必填 | 说明     |
+| ---------------------- | ------ | ---- | -------- |
+| `--collection-id <id>` | string | 否¹  | 集合 ID  |
+| `--name <text>`        | string | 否¹  | 集合名称 |
+
+> ¹ `--collection-id` 和 `--name` 二选一，必须提供其一。
+
+**参数约束**
+
+- `--collection-id` 和 `--name` 互斥，必须提供其一
+
+**输出**
+
+text 模式：
+
+```
+id: conn-xxx
+name: my-collection
+description: team docs
+```
+
+quiet 模式：输出集合 ID。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- getConnector 不返回 `fileConnectorConfig`（`storeType`/`regionId`/`bucketName`），这些字段仅在创建时通过请求体传入，查询时不可读回。
+
+**示例**
+
+```bash
+# 按 ID 查询
+bl knowledge collection get --collection-id conn-xxx --workspace-id ws-xxx
+
+# 按名称查询
+bl knowledge collection get --name my-collection
+```
+
+---
+
+#### `bl knowledge category list`
+
+列出数据中心分类。
+
+**用法**
+
+```bash
+bl knowledge category list [flags]
+```
+
+**参数**
+
+| 参数                   | 类型   | 必填 | 说明                                                   |
+| ---------------------- | ------ | ---- | ------------------------------------------------------ |
+| `--collection-id <id>` | string | 否   | 按集合 ID 过滤                                         |
+| `--parent-id <id>`     | string | 否   | 列出此分类的子分类                                     |
+| `--name <text>`        | string | 否   | 按分类名称过滤（精确匹配，与知识库列表的模糊匹配不同） |
+| `--next-token <token>` | string | 否   | 游标分页令牌                                           |
+| `--max-result <n>`     | number | 否   | 每页条数（默认：20）                                   |
+
+**输出**
+
+text 模式：
+
+```
+cate-xxx  product-docs
+cate-yyy  system-docs  [default]
+next: --next-token eyJ...
+```
+
+> 标记 `[default]` 的是文件未指定分类时的默认归属。
+
+quiet 模式：每行一个 `categoryId`。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 分页是游标方式：使用输出的 `next: --next-token <token>` 继续翻页。
+
+**示例**
+
+```bash
+# 列出所有分类
+bl knowledge category list --workspace-id ws-xxx
+
+# 按名称过滤
+bl knowledge category list --name my-category
+
+# 翻页
+bl knowledge category list --next-token eyJ...
+```
+
+---
+
+#### `bl knowledge category add`
+
+创建数据中心分类。
+
+**用法**
+
+```bash
+bl knowledge category add --name <text> [flags]
+```
+
+**参数**
+
+| 参数                   | 类型   | 必填 | 说明                             |
+| ---------------------- | ------ | ---- | -------------------------------- |
+| `--name <text>`        | string | 是   | 分类名称（1-20 字符）            |
+| `--parent-id <id>`     | string | 否   | 创建为指定分类的子分类           |
+| `--collection-id <id>` | string | 否   | 创建在此集合下（默认：平台集合） |
+
+**参数约束**
+
+- `--name` 长度 1-20 字符
+
+**输出**
+
+text 模式：
+
+```
+created: cate-xxx  (product-docs)
+```
+
+quiet 模式：输出分类 ID。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 用分类按业务域组织数据中心文件。
+
+**示例**
+
+```bash
+# 创建分类
+bl knowledge category add --name product-docs --workspace-id ws-xxx
+
+# 创建子分类
+bl knowledge category add --name sub --parent-id cate-xxx
+```
+
+---
+
+#### `bl knowledge category delete`
+
+删除数据中心分类。
+
+**用法**
+
+```bash
+bl knowledge category delete --category-id <id> [flags]
+```
+
+**参数**
+
+| 参数                 | 类型   | 必填 | 说明                   |
+| -------------------- | ------ | ---- | ---------------------- |
+| `--category-id <id>` | string | 是   | 分类 ID                |
+| `--yes`              | switch | 否   | 显式确认执行高风险操作 |
+
+**输出**
+
+text 模式：
+
+```
+deleted: cate-xxx
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 含文件或子分类的分类的删除行为由服务端定义——服务端错误原样透传。
+
+**示例**
+
+```bash
+# 删除分类（交互确认）
+bl knowledge category delete --category-id cate-xxx --workspace-id ws-xxx
+
+# 跳过确认
+bl knowledge category delete --category-id cate-xxx --yes
+```
+
+---
+
+← [返回总览](../knowledge-cli-guide.md)

docs/knowledge/doc.md

@@ -0,0 +1,344 @@
+# 文档管理命令手册
+
+文档管理覆盖文件上传、OSS 导入、解析状态跟踪、文档删除和标签管理。文档导入知识库后自动解析为 chunk。
+
+> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](../knowledge-cli-guide.md#通用约定)。
+
+---
+
+#### `bl knowledge doc list`
+
+列出知识库中的文档及其解析/索引状态。
+
+**用法**
+
+```bash
+bl knowledge doc list --index-id <id> [flags]
+```
+
+**参数**
+
+| 参数                | 类型   | 必填 | 说明                           |
+| ------------------- | ------ | ---- | ------------------------------ |
+| `--index-id <id>`   | string | 是   | 知识库 ID                      |
+| `--page-number <n>` | number | 否   | 页码（默认：1）                |
+| `--page-size <n>`   | number | 否   | 每页条数（默认：10，最大 100） |
+
+**参数约束**
+
+- `--page-size` 范围 1-100
+
+**输出**
+
+text 模式：每行一个文档，`FAILED` 状态的文档红色高亮。
+
+```
+doc-xxx  COMPLETED  intro.md  md  1024
+total: 1
+```
+
+quiet 模式：每行一个 `doc_id`。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- `doc_id` 与 `file_id` 的关系：通过 `knowledge create --doc-id` 导入的文档，`doc_id` 等于 `fileId`；通过 `knowledge doc upload --index-id` 导入的，`doc_id` 可能包含 workspace 后缀。
+- 页大小默认 10（服务端默认），最大 100。
+
+**示例**
+
+```bash
+# 列出文档
+bl knowledge doc list --index-id idx-xxx --workspace-id ws-xxx
+
+# 每页 100 条
+bl knowledge doc list --index-id idx-xxx --page-size 100
+```
+
+---
+
+#### `bl knowledge doc status`
+
+查看知识库导入任务状态。
+
+**用法**
+
+```bash
+bl knowledge doc status --index-id <id> --job-id <id> [flags]
+```
+
+**参数**
+
+| 参数                        | 类型   | 必填 | 说明                                                |
+| --------------------------- | ------ | ---- | --------------------------------------------------- |
+| `--index-id <id>`           | string | 是   | 知识库 ID                                           |
+| `--job-id <id>`             | string | 是   | 导入任务 ID（`ingestionId`，由 create/upload 返回） |
+| `--page-number <n>`         | number | 否   | 页码                                                |
+| `--page-size <n>`           | number | 否   | 每页条数                                            |
+| `--wait`                    | switch | 否   | 轮询直到任务到达终态                                |
+| `--poll-interval <seconds>` | number | 否   | 轮询间隔秒数（默认：5）                             |
+
+**输出**
+
+text 模式：
+
+```
+status: COMPLETED
+  doc-xxx  COMPLETED  intro.md
+```
+
+quiet 模式：输出任务状态（`PENDING`/`RUNNING`/`COMPLETED`）。
+
+json 模式：返回 API 原始响应，`data.rows[]` 包含每个文档的状态。
+
+**注意事项**
+
+- `--index-id` 和 `--job-id` 服务端均要求必传，只传一个会返回 `SystemError`。
+- 整体任务状态为 `PENDING` / `RUNNING` / `COMPLETED`（无 `FAILED` 值）。
+- 单个文档可能解析失败（如 `PARSE_FAILED`），此时 CLI 以非零退出码报错，服务端消息原样透传。
+- 如果服务端对空闲知识库返回 `SystemError`，说明该 job 可能不存在。
+
+**示例**
+
+```bash
+# 查看任务状态
+bl knowledge doc status --index-id idx-xxx --job-id job-xxx --workspace-id ws-xxx
+
+# 轮询等待完成，10 秒间隔
+bl knowledge doc status --index-id idx-xxx --job-id job-xxx --wait --poll-interval 10
+```
+
+---
+
+#### `bl knowledge doc upload`
+
+上传本地文件或目录到数据中心，可选导入到知识库。
+
+**用法**
+
+```bash
+bl knowledge doc upload --file <path> [flags]
+```
+
+**参数**
+
+| 参数                        | 类型   | 必填 | 说明                                                             |
+| --------------------------- | ------ | ---- | ---------------------------------------------------------------- |
+| `--file <path>`             | array  | 是   | 本地文件或目录路径（可重复）。目录递归扫描，不支持的格式自动跳过 |
+| `--index-id <id>`           | string | 否   | 上传后导入到此知识库（所有文件合并为一个导入任务）               |
+| `--category-id <id>`        | string | 否   | 目标数据中心分类（默认：工作区默认分类）                         |
+| `--tag <text>`              | array  | 否   | 文件标签（可重复），应用到每个上传的文件                         |
+| `--wait`                    | switch | 否   | 轮询导入任务直到终态（需要 `--index-id`）                        |
+| `--poll-interval <seconds>` | number | 否   | 轮询间隔秒数（默认：5）                                          |
+
+**参数约束**
+
+- `--wait` 要求同时指定 `--index-id`
+
+**输出**
+
+text 模式：
+
+```
+intro.md  file-xxx  registered
+job: job-xxx
+status: COMPLETED
+
+Uploaded 1 file.
+```
+
+quiet 模式：每行一个 `fileId`。
+
+json 模式：返回自定义结构，包含 `files`（路径和 fileId）、`skipped`、`index_id`、`ingestion_id`、`final_status`。
+
+**注意事项**
+
+- 上传管道：申请 lease → PUT 到 OSS → 注册文件 →（可选）创建导入任务。
+- 目录递归扫描，`node_modules`、`.git` 等自动跳过。
+- 多文件按顺序处理（无并发），避免 OSS 限流。
+- 支持的文件格式：`.pdf .doc .docx .ppt .pptx .xls .xlsx .csv .md .txt .html .png .jpg .jpeg .bmp .gif`
+- 部分文件上传失败时，已注册的 fileId 会在错误 hint 中列出。
+
+**示例**
+
+```bash
+# 上传单个文件
+bl knowledge doc upload --file ./a.md --workspace-id ws-xxx
+
+# 上传多个文件并导入到知识库，等待完成
+bl knowledge doc upload --file ./a.md --file ./b.pdf --index-id idx-xxx --wait
+
+# 上传整个目录
+bl knowledge doc upload --file ./docs/ --workspace-id ws-xxx
+
+# 干跑预览（查看将上传和跳过的文件）
+bl knowledge doc upload --file ./docs/ --dry-run --verbose
+```
+
+---
+
+#### `bl knowledge doc delete`
+
+从知识库中删除文档及其 chunk。
+
+**用法**
+
+```bash
+bl knowledge doc delete --index-id <id> --doc-id <id> [flags]
+```
+
+**参数**
+
+| 参数              | 类型   | 必填 | 说明               |
+| ----------------- | ------ | ---- | ------------------ |
+| `--index-id <id>` | string | 是   | 知识库 ID          |
+| `--doc-id <id>`   | array  | 是   | 文档 ID（可重复）  |
+| `--yes`           | switch | 否   | 显式确认高风险操作 |
+
+**输出**
+
+text 模式：
+
+```
+deleted: 2 document(s)
+  doc-a
+  doc-b
+```
+
+quiet 模式：每行一个已删除的 `doc_id`。
+
+json 模式：返回 API 原始响应，`data.deleted[]` 为实际删除的 ID 列表。
+
+**注意事项**
+
+- 只从知识库索引中移除文档，数据中心源文件不受影响（用 `file delete` 删除源文件）。
+- `doc_id` 应从 `knowledge doc list --quiet` 获取，而非 `doc upload` 返回的 `fileId`。
+- 删除是异步的：服务端立即返回 Success，但 `doc list` 中可能仍显示该文档（约 30 秒后传播完成）。
+- 输出的是服务端实际删除的 ID 列表，可能与请求的数量不一致（会在 stderr 警告）。
+
+**示例**
+
+```bash
+# 删除单个文档
+bl knowledge doc delete --index-id idx-xxx --doc-id doc-xxx --workspace-id ws-xxx
+
+# 用户明确确认后批量删除
+bl knowledge doc delete --index-id idx-xxx --doc-id doc-a --doc-id doc-b --yes
+```
+
+---
+
+#### `bl knowledge doc tag`
+
+批量更新数据中心文件的标签。
+
+**用法**
+
+```bash
+bl knowledge doc tag --doc-id <id> --tag <text> [flags]
+```
+
+**参数**
+
+| 参数            | 类型   | 必填 | 说明                                                   |
+| --------------- | ------ | ---- | ------------------------------------------------------ |
+| `--doc-id <id>` | array  | 是   | 数据中心文件 ID（可重复，最多 20 个/次）               |
+| `--tag <text>`  | array  | 是   | 标签（可重复），应用到每个 `--doc-id`                  |
+| `--mode <mode>` | string | 否   | 更新模式：`append`（默认，追加）或 `overwrite`（覆盖） |
+
+**参数约束**
+
+- `--doc-id` 最多 20 个/次
+- `--tag` 最多 100 个
+- 每个标签最多 32 字符
+- 标签总长度最多 700 字符
+- `--mode` 只能是 `append` 或 `overwrite`
+
+**输出**
+
+text 模式：
+
+```
+tagged: 2 file(s) with [project-a, draft]
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 同一组标签应用到所有 `--doc-id`；不同标签集需多次执行。
+
+**示例**
+
+```bash
+# 追加标签
+bl knowledge doc tag --doc-id file-xxx --tag project-a --tag draft --workspace-id ws-xxx
+
+# 覆盖标签
+bl knowledge doc tag --doc-id file-a --doc-id file-b --tag final --mode overwrite
+```
+
+---
+
+#### `bl knowledge doc import-oss`
+
+从已授权的 OSS bucket 批量导入文件到数据中心。
+
+**用法**
+
+```bash
+bl knowledge doc import-oss --bucket <name> --region <id> --oss-key <key> [flags]
+```
+
+**参数**
+
+| 参数                 | 类型   | 必填 | 说明                                  |
+| -------------------- | ------ | ---- | ------------------------------------- |
+| `--bucket <name>`    | string | 是   | 已授权的 OSS bucket 名称              |
+| `--region <id>`      | string | 是   | OSS region ID（如 `cn-beijing`）      |
+| `--oss-key <key>`    | array  | 是   | OSS 对象 key（可重复，最多 10 个/次） |
+| `--category-id <id>` | string | 否   | 目标数据中心分类（默认：默认分类）    |
+| `--tag <text>`       | array  | 否   | 文件标签（可重复，最多 10 个）        |
+| `--overwrite`        | switch | 否   | 覆盖之前从相同 OSS key 导入的文件     |
+
+**参数约束**
+
+- `--oss-key` 最多 10 个/次
+- `--tag` 最多 10 个
+
+**输出**
+
+text 模式：
+
+```
+imported: 2 file(s)
+  file-a  SUCCESS  docs/a.pdf
+  file-b  SUCCESS  docs/b.docx
+```
+
+quiet 模式：每行一个 `fileId`。
+
+json 模式：返回 API 原始响应，`data.addFileResultList[]` 包含每个文件的 fileId、status 和 ossKey。
+
+**注意事项**
+
+- bucket 必须事先授权给平台服务角色（RAM 中的 `AliyunServiceRoleForBailian`）。
+- 文件名取自 OSS key 的 basename。
+- `--overwrite` 会替换之前导入的文件并生成**新的 fileId**（旧 fileId 失效）。
+
+**示例**
+
+```bash
+# 导入单个文件
+bl knowledge doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --workspace-id ws-xxx
+
+# 导入多个文件并覆盖
+bl knowledge doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --oss-key docs/b.docx --overwrite
+```
+
+---
+
+← [返回总览](../knowledge-cli-guide.md)

docs/knowledge/file.md

@@ -0,0 +1,157 @@
+# 数据中心文件管理命令手册
+
+数据中心是知识库文件的存储层。文件通过 `doc upload` 或 `doc import-oss` 进入数据中心，再导入到知识库。数据中心文件可被多个知识库引用。
+
+> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](../knowledge-cli-guide.md#通用约定)。
+
+---
+
+#### `bl knowledge file list`
+
+列出数据中心分类下的文件。
+
+**用法**
+
+```bash
+bl knowledge file list --category-id <id> [flags]
+```
+
+**参数**
+
+| 参数                   | 类型   | 必填 | 说明                                               |
+| ---------------------- | ------ | ---- | -------------------------------------------------- |
+| `--category-id <id>`   | string | 是   | 分类 ID（通过 `category list` 或 `file get` 获取） |
+| `--name <text>`        | string | 否   | 按文件名过滤                                       |
+| `--file-id <id>`       | array  | 否   | 按文件 ID 过滤（可重复）                           |
+| `--next-token <token>` | string | 否   | 游标分页令牌（从上次输出获取）                     |
+| `--max-result <n>`     | number | 否   | 每页条数                                           |
+
+**输出**
+
+text 模式：
+
+```
+file-xxx  SUCCESS  intro.md  1024
+next: --next-token eyJ...
+```
+
+quiet 模式：每行一个 `fileId`。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- `--category-id` 必须是真实的分类 ID。与上传 API 不同，字面量 `default` 在此不被解析，传入会返回空列表。通过 `file get` 的 category 字段或 `category list` 获取真实 ID。
+- 分页是游标方式：使用输出的 `next: --next-token <token>` 继续翻页。
+
+**示例**
+
+```bash
+# 列出分类下文件
+bl knowledge file list --category-id cate-xxx --workspace-id ws-xxx
+
+# 按名称过滤
+bl knowledge file list --category-id cate-xxx --name report
+
+# 翻页
+bl knowledge file list --category-id cate-xxx --next-token eyJ...
+```
+
+---
+
+#### `bl knowledge file get`
+
+查看数据中心文件详情。
+
+**用法**
+
+```bash
+bl knowledge file get --file-id <id> [flags]
+```
+
+**参数**
+
+| 参数             | 类型   | 必填 | 说明            |
+| ---------------- | ------ | ---- | --------------- |
+| `--file-id <id>` | string | 是   | 数据中心文件 ID |
+
+**输出**
+
+text 模式：
+
+```
+id: file-xxx
+name: intro.md
+type: md
+size: 1024
+status: SUCCESS
+parser: AUTO_SELECT
+category: cate-xxx
+uploaded: 2026-01-01T00:00:00Z
+tags: project-a, draft
+```
+
+quiet 模式：输出 JSON 格式。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 无特殊注意事项。
+
+**示例**
+
+```bash
+# 查看文件详情
+bl knowledge file get --file-id file-xxx --workspace-id ws-xxx
+```
+
+---
+
+#### `bl knowledge file delete`
+
+从数据中心永久删除文件。
+
+**用法**
+
+```bash
+bl knowledge file delete --file-id <id> [flags]
+```
+
+**参数**
+
+| 参数             | 类型   | 必填 | 说明                   |
+| ---------------- | ------ | ---- | ---------------------- |
+| `--file-id <id>` | string | 是   | 数据中心文件 ID        |
+| `--yes`          | switch | 否   | 显式确认执行高风险操作 |
+
+**输出**
+
+text 模式：
+
+```
+deleted: file-xxx
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- **不可逆操作**：如果知识库引用了此文件，相关文档索引会失效。
+- 与 `doc delete` 的区别：`doc delete` 只从单个知识库索引中移除文档，数据中心源文件保留；`file delete` 删除源文件本身，影响所有引用它的知识库。
+
+**示例**
+
+```bash
+# 删除文件（交互确认）
+bl knowledge file delete --file-id file-xxx --workspace-id ws-xxx
+
+# 跳过确认
+bl knowledge file delete --file-id file-xxx --yes
+```
+
+---
+
+← [返回总览](../knowledge-cli-guide.md)

docs/knowledge/kb.md

@@ -0,0 +1,342 @@
+# 知识库管理命令手册
+
+知识库（Knowledge Base / pipeline / index）是 RAG 的核心载体，存储文档解析后的向量索引。本组命令覆盖知识库的创建、查看、更新、删除和监控。
+
+> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](../knowledge-cli-guide.md#通用约定)。
+
+---
+
+#### `bl knowledge list`
+
+列出工作区中的知识库。
+
+**用法**
+
+```bash
+bl knowledge list [flags]
+```
+
+**参数**
+
+| 参数                | 类型   | 必填 | 说明                              |
+| ------------------- | ------ | ---- | --------------------------------- |
+| `--name <text>`     | string | 否   | 按知识库名称模糊过滤（1-20 字符） |
+| `--page-number <n>` | number | 否   | 页码（默认：1）                   |
+| `--page-size <n>`   | number | 否   | 每页条数（默认：20，最大 100）    |
+
+**参数约束**
+
+- `--name` 长度 1-20 字符
+- `--page-size` 范围 1-100
+
+**输出**
+
+text 模式：每行一个知识库，字段以双空格分隔，末尾显示总数。
+
+```
+idx-xxx  my-kb  text-embedding-v4  600  product docs
+total: 1
+```
+
+quiet 模式：每行一个知识库 ID。
+
+json 模式：返回 API 原始响应，`data.rows[]` 包含完整知识库信息。
+
+**注意事项**
+
+- 返回的 `id` 字段作为后续命令的 `--index-id` 使用。
+
+**示例**
+
+```bash
+# 列出所有知识库
+bl knowledge list --workspace-id ws-xxx
+
+# 按名称过滤，第二页
+bl knowledge list --name demo --page-number 2 --page-size 50
+```
+
+---
+
+#### `bl knowledge info`
+
+查看知识库配置详情。
+
+**用法**
+
+```bash
+bl knowledge info --index-id <id> [flags]
+```
+
+**参数**
+
+| 参数              | 类型   | 必填 | 说明      |
+| ----------------- | ------ | ---- | --------- |
+| `--index-id <id>` | string | 是   | 知识库 ID |
+
+**输出**
+
+text 模式：按诊断维度分组展示。
+
+```
+Basic:
+  id: idx-xxx
+  name: my-kb
+  description: product docs
+  dataType: ...
+Indexing:   [immutable — recreate required to change]
+  embeddingModelName: text-embedding-v4
+  embeddingDimension: 1024
+  chunkSize: 600
+  overlapSize: ...
+  chunkMode: ...
+  separator: ...
+Retrieval:
+  rerankModelName: ...
+  rerankMinScore: ...
+  rerankTopN: ...
+  rerankMode: ...
+  enableRewrite: ...
+  denseSimilarityTopK: ...
+  sparseSimilarityTopK: ...
+Data:
+  sourceType: ...
+  connectorId: ...
+```
+
+quiet 模式：输出知识库 ID。
+
+json 模式：返回知识库完整配置 JSON。
+
+**注意事项**
+
+- 索引设置（向量模型、切片大小等）不可变，修改需重建知识库。
+
+**示例**
+
+```bash
+# 查看知识库详情
+bl knowledge info --index-id idx-xxx --workspace-id ws-xxx
+```
+
+---
+
+#### `bl knowledge create`
+
+创建知识库并导入数据中心文件或分类。
+
+**用法**
+
+```bash
+bl knowledge create --name <text> --description <text> (--doc-id <id> | --category-id <id>) [flags]
+```
+
+**参数**
+
+| 参数                        | 类型   | 必填 | 说明                                                     |
+| --------------------------- | ------ | ---- | -------------------------------------------------------- |
+| `--name <text>`             | string | 是   | 知识库名称（1-20 字符，工作区内唯一）                    |
+| `--description <text>`      | string | 是   | 知识库装了什么内容、给谁用（1-500 字符）                 |
+| `--doc-id <id>`             | array  | 否¹  | 数据中心文件 ID（可重复）；与 `--category-id` 互斥       |
+| `--category-id <id>`        | array  | 否¹  | 按分类导入该分类下所有文件（可重复）；与 `--doc-id` 互斥 |
+| `--embedding-model <name>`  | string | 否   | 向量模型名称（默认：`text-embedding-v4`）                |
+| `--chunk-size <n>`          | number | 否   | 切片大小，字符数（默认：600，建议 300-800）              |
+| `--wait`                    | switch | 否   | 轮询初始导入任务直到终态                                 |
+| `--poll-interval <seconds>` | number | 否   | 轮询间隔秒数（默认：5）                                  |
+
+> ¹ `--doc-id` 和 `--category-id` 二选一，必须提供其一。
+
+**参数约束**
+
+- `--name` 长度 1-20 字符
+- `--description` 长度 1-500 字符，缺失或超长会在本地被拦截
+- `--doc-id` 和 `--category-id` 互斥，必须提供其一
+
+**输出**
+
+text 模式：
+
+```
+index_id: idx-xxx
+ingestion_id: job-xxx
+status: COMPLETED
+Next: check the import job status, then search against this knowledge base.
+```
+
+quiet 模式：只输出知识库 ID。
+
+json 模式：返回 API 原始响应，包含 `pipelineId`（知识库 ID）和 `ingestionId`（导入任务 ID）。`--wait` 时追加 `final_status` 字段。
+
+**注意事项**
+
+- 结构/存储类型固定为默认文档知识库（非结构化，BUILT_IN 存储）。
+- 返回知识库 ID（`pipelineId`）和初始导入任务 ID（`ingestionId`）。
+- 使用 `doc status` 或 `--wait` 跟踪导入进度。
+- 如果 `--wait` 后部分文档解析失败，CLI 以非零退出码报错，知识库已创建成功的事实会在 hint 中提示。
+
+**示例**
+
+```bash
+# 从指定文件创建知识库
+bl knowledge create --name demo --description '产品文档' --doc-id file-xxx --workspace-id ws-xxx
+
+# 从分类导入并等待导入完成
+bl knowledge create --name demo --description '产品文档' --category-id cate-xxx --wait
+
+# 指定向量模型和切片大小
+bl knowledge create --name my-kb --description '产品文档 v2' --doc-id file-a --doc-id file-b --embedding-model text-embedding-v4 --chunk-size 400 --workspace-id ws-xxx
+```
+
+---
+
+#### `bl knowledge update`
+
+更新知识库名称、描述或 rerank 阈值。
+
+**用法**
+
+```bash
+bl knowledge update --index-id <id> [flags]
+```
+
+**参数**
+
+| 参数                         | 类型   | 必填 | 说明                                                     |
+| ---------------------------- | ------ | ---- | -------------------------------------------------------- |
+| `--index-id <id>`            | string | 是   | 知识库 ID                                                |
+| `--name <text>`              | string | 否   | 新名称（1-20 字符）                                      |
+| `--description <text>`       | string | 否   | 新描述                                                   |
+| `--rerank-min-score <score>` | number | 否   | rerank 最低分数阈值，范围 0-1（低于此分的 chunk 被过滤） |
+
+**参数约束**
+
+- 至少提供 `--name`、`--description`、`--rerank-min-score` 之一，否则报错 "Nothing to update"
+- `--name` 长度 1-20 字符
+- `--rerank-min-score` 范围 0-1
+
+**输出**
+
+text 模式：
+
+```
+updated: idx-xxx
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 索引设置（向量模型、切片大小等）不可变，修改需重建知识库。
+
+**示例**
+
+```bash
+# 更新描述
+bl knowledge update --index-id idx-xxx --description "product docs v2" --workspace-id ws-xxx
+
+# 调整 rerank 阈值
+bl knowledge update --index-id idx-xxx --rerank-min-score 0.3
+```
+
+---
+
+#### `bl knowledge delete`
+
+删除知识库及其所有文档和 chunk。
+
+**用法**
+
+```bash
+bl knowledge delete --index-id <id> [flags]
+```
+
+**参数**
+
+| 参数              | 类型   | 必填 | 说明                   |
+| ----------------- | ------ | ---- | ---------------------- |
+| `--index-id <id>` | string | 是   | 知识库 ID              |
+| `--yes`           | switch | 否   | 显式确认执行高风险操作 |
+
+**输出**
+
+text 模式：
+
+```
+deleted: idx-xxx
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- **不可逆操作**：知识库及所有索引内容被永久删除。
+- 数据中心中的源文件不受影响，仅删除知识库索引。
+- 不带 `--yes` 时，runtime 会在调用知识库业务 API、执行删除前返回确认请求。
+
+**示例**
+
+```bash
+# 删除（交互确认）
+bl knowledge delete --index-id idx-xxx --workspace-id ws-xxx
+
+# 跳过确认
+bl knowledge delete --index-id idx-xxx --yes
+```
+
+---
+
+#### `bl knowledge stats`
+
+查看知识库存储和 QPS 监控数据。
+
+**用法**
+
+```bash
+bl knowledge stats --index-id <id> [flags]
+```
+
+**参数**
+
+| 参数              | 类型   | 必填 | 说明                                            |
+| ----------------- | ------ | ---- | ----------------------------------------------- |
+| `--index-id <id>` | string | 是   | 知识库 ID                                       |
+| `--start <time>`  | string | 否   | 范围起始：Unix 秒或 ISO 日期（默认：24 小时前） |
+| `--end <time>`    | string | 否   | 范围结束：Unix 秒或 ISO 日期（默认：当前时间）  |
+
+**输出**
+
+text 模式：
+
+```
+plan: ...
+storage: 100 / 1000
+peak qps: 5
+qps windows: 24 data point(s)
+```
+
+quiet 模式：输出 json 格式。
+
+json 模式：返回 API 原始响应，包含 `storageMonitorData` 和 `qpsMonitorData`。
+
+**注意事项**
+
+- 默认查询最近 24 小时数据。
+- 时间戳自动转换为 epoch 秒（API 要求秒级字符串）。13 位毫秒时间戳会自动降为秒。
+
+**示例**
+
+```bash
+# 查看最近 24 小时监控
+bl knowledge stats --index-id idx-xxx --workspace-id ws-xxx
+
+# 指定日期范围
+bl knowledge stats --index-id idx-xxx --start 2026-07-30 --end 2026-07-31
+```
+
+---
+
+← [返回总览](../knowledge-cli-guide.md)

docs/knowledge/knowledge-cli-guide.md

@@ -0,0 +1,822 @@
+# `bl knowledge` 命令完整用法指南
+
+> `bl knowledge` / `kscli` 知识库 CLI 命令总览，覆盖全部 34 个子命令。完整参数与示例请参阅各子域手册。
+
+---
+
+## 目录
+
+1. [概述](#概述)
+2. [核心概念与实体关系](#核心概念与实体关系)
+3. [通用约定](#通用约定)
+4. [典型工作流](#典型工作流)
+5. [命令手册](#命令手册)
+   - [知识库管理](#知识库管理) → [完整手册](knowledge/kb.md)
+   - [文档管理](#文档管理) → [完整手册](knowledge/doc.md)
+   - [检索服务管理](#检索服务管理) → [完整手册](knowledge/service.md)
+   - [Chunk 管理](#chunk-管理) → [完整手册](knowledge/chunk.md)
+   - [数据中心文件管理](#数据中心文件管理) → [完整手册](knowledge/file.md)
+   - [数据中心集合与分类](#数据中心集合与分类) → [完整手册](knowledge/collection-category.md)
+   - [检索与对话](#检索与对话) → [完整手册](knowledge/search-chat.md)
+6. [常见错误与排查](#常见错误与排查)
+7. [附录：命令速查表](#附录命令速查表)
+
+---
+
+## 概述
+
+`bl knowledge` 是阿里云百炼 CLI 的知识库命令组，覆盖 RAG（检索增强生成）全链路能力：
+
+- **知识库全生命周期管理**：创建、查看、更新、删除、监控
+- **文档管理**：上传本地文件、从 OSS 批量导入、查看解析状态、删除、打标签
+- **Chunk 级运维**：直接增删改查知识库中的内容切片
+- **检索服务管理**：创建/部署/复制/删除 Q&A 和检索服务（agent），管理 draft 与发布版本
+- **数据中心管理**：文件、集合（connector）、分类的增删查
+- **检索与对话**：语义检索（search）、多轮对话（chat）、兼容旧检索（retrieve）
+
+共 34 个子命令，按功能域分为 7 组。所有命令均使用 DashScope API Key 鉴权。
+
+---
+
+## 核心概念与实体关系
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     数据中心 (Data Center)                    │
+│                                                             │
+│  集合 (Collection) ──┬── 分类 (Category) ── 文件 (File)      │
+│                      │   "connector"        可多级嵌套       │
+│                      └── 默认分类                              │
+│                                                             │
+│  文件来源：doc upload(本地上传) / doc import-oss(OSS导入)     │
+└──────────────────────────┬──────────────────────────────────┘
+                           │ 导入 (import job)
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    知识库 (Knowledge Base)                    │
+│                                                             │
+│  知识库 (KB / pipeline / index)                              │
+│    ├── 文档 (Doc) ── 解析状态: PENDING/RUNNING/COMPLETED     │
+│    │     └── Chunk ── 内容切片，可增删改查、排除/恢复检索     │
+│    └── 索引设置 (immutable): 向量模型、切片大小等             │
+│                                                             │
+│  知识库管理命令: create / list / info / update / delete / stats │
+└──────────────────────────┬──────────────────────────────────┘
+                           │ 绑定 (agent_config.kb_search_configs)
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                  检索服务 (Service / Agent)                   │
+│                                                             │
+│  Service (agent)                                            │
+│    ├── scene: chat (Q&A) 或 search (检索)                    │
+│    ├── 版本: beta (草稿) → 1, 2, 3... (已发布)               │
+│    ├── 状态: draft → deployed → edited → deleted            │
+│    └── 配置: 模型、温度、策略、rerank 等                      │
+│                                                             │
+│  消费方式: search (语义检索) / chat (多轮对话)               │
+│  管理命令: create / update / deploy / copy / delete / list / get │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**关键关系**：
+
+- **数据中心文件 → 知识库**：通过 `knowledge create --doc-id` 或 `knowledge doc upload --index-id` 导入，文件解析后自动生成 chunk
+- **知识库 → 检索服务**：一个服务可绑定多个知识库，服务配置中 `kb_search_configs` 指定关联的知识库 ID
+- **检索服务 → 检索/对话**：`search` 和 `chat` 命令通过 `--agent-id` 指定服务来执行检索或对话
+
+---
+
+## 通用约定
+
+### 鉴权
+
+所有 `bl knowledge` 命令均使用 **DashScope API Key**（Bearer token）鉴权。获取方式：百炼控制台 API Key 页面。
+
+优先级（高 → 低）：
+
+1. `--api-key <key>` 命令行参数
+2. `DASHSCOPE_API_KEY` 环境变量
+3. 配置文件中的 `api_key`（`bl config set api_key <key>`）
+
+### Workspace ID
+
+知识库 API 使用 workspace 级域名（`{workspaceId}.cn-beijing.maas.aliyuncs.com`），因此 **几乎所有 knowledge 命令都需要 workspace ID**。
+
+优先级（高 → 低）：
+
+1. `--workspace-id <id>` 命令行参数
+2. `BAILIAN_WORKSPACE_ID` 环境变量
+3. 配置文件中的 `workspace_id`（`bl config set workspace_id <id>`）
+
+缺失时报错：`Workspace ID is required.`
+
+### 全局通用参数
+
+以下参数在所有 `bl knowledge` 子命令中通用，后续命令手册中不再逐条列出：
+
+| 参数                  | 类型   | 说明                                                        |
+| --------------------- | ------ | ----------------------------------------------------------- |
+| `--output <format>`   | string | 输出格式：`text`（默认，人类友好）或 `json`（API 原始响应） |
+| `--api-key <key>`     | string | DashScope API Key                                           |
+| `--base-url <url>`    | string | API 基地址（一般不需要指定）                                |
+| `--timeout <seconds>` | number | 请求超时秒数                                                |
+| `--quiet`             | switch | 静默模式，只输出关键结果（如 ID 列表）                      |
+| `--verbose`           | switch | 详细模式，打印 HTTP 请求/响应详情到 stderr                  |
+| `--dry-run`           | switch | 干跑模式，预览将发送的请求结构，不实际调用 API              |
+| `--config <name>`     | string | 使用指定配置 profile 执行命令                               |
+
+> **注意**：命令手册中每个命令的参数表只列出该命令**特有**的参数。上述全局参数对所有命令有效。
+
+### 输出格式约定
+
+- **text 模式**（默认）：人类友好的表格/结构化文本，适合终端查看。不同命令的输出格式见各命令的「输出」部分。
+- **json 模式**（`--output json`）：返回 API 原始 JSON 响应，适合程序化处理和 agent 解析。
+- **quiet 模式**（`--quiet`）：只输出最精简的结果（通常只有 ID），适合管道串联。
+
+### 危险操作确认
+
+涉及删除的命令（`kb delete`、`doc delete`、`chunk delete`、`file delete`、`category delete`、`service delete`、`service deploy`）属于高风险操作。未带 `--yes` 时 CLI 不会执行，也不会弹出交互式 Y/N，而是返回 exit code 7 和 `requires_confirmation`；确认后在原命令中添加 `--yes` 重新执行。
+
+### Dry-run 模式
+
+`--dry-run` 模式下，命令会输出将发送的 endpoint 和 request body，但**不实际发起网络请求**。部分命令在 dry-run 下仍会执行本地校验（如文件扩展名检查、参数约束检查）。
+
+---
+
+## 典型工作流
+
+### 场景 A：从零搭建知识库并检索
+
+```bash
+# 1. 上传本地文件到数据中心，同时导入到新知识库
+bl knowledge doc upload --file ./docs/intro.md --workspace-id ws-xxx
+# → 返回 file-id
+
+# 2. 用文件创建知识库
+bl knowledge create --name my-kb --description '产品文档' --doc-id file-xxx --workspace-id ws-xxx --wait
+# → 返回 index-id (pipelineId) 和导入任务状态
+
+# 3. 创建检索服务（search 场景）
+bl knowledge service create --name my-search --scene search --index-id idx-xxx --workspace-id ws-xxx
+# → 返回 agent-id
+
+# 4. 部署服务
+bl knowledge service deploy --agent-id aid-xxx --workspace-id ws-xxx --yes
+
+# 5. 执行检索
+bl knowledge search --query "什么是RAG" --agent-id aid-xxx --workspace-id ws-xxx
+```
+
+### 场景 B：上传目录并导入到已有知识库
+
+```bash
+# 1. 上传整个目录到数据中心并直接导入到知识库（一步到位）
+bl knowledge doc upload --file ./docs/ --index-id idx-xxx --workspace-id ws-xxx --wait
+# → 文件逐个上传到 OSS → 注册到数据中心 → 创建合并导入任务 → 轮询到完成
+
+# 2. 检查文档状态
+bl knowledge doc list --index-id idx-xxx --workspace-id ws-xxx
+# → 查看 doc_id 和解析状态
+
+# 3. 如果有文档解析失败，查看导入任务详情
+bl knowledge doc status --index-id idx-xxx --job-id job-xxx --workspace-id ws-xxx
+```
+
+### 场景 C：创建并部署 Q&A 服务
+
+```bash
+# 1. 创建 chat 场景的检索服务
+bl knowledge service create --name my-qa --scene chat --index-id idx-xxx --workspace-id ws-xxx
+# → 初始状态: draft, 版本: beta
+
+# 2. 调整配置（如修改模型、温度）
+bl knowledge service update --agent-id aid-xxx --model qwen-max --temperature 0.7 --workspace-id ws-xxx
+
+# 3. 用 beta 版本测试
+bl knowledge chat --message "什么是RAG?" --agent-id aid-xxx --agent-version beta --workspace-id ws-xxx
+
+# 4. 测试通过后发布
+bl knowledge service deploy --agent-id aid-xxx --version-desc "首版" --workspace-id ws-xxx --yes
+```
+
+### 场景 D：知识库内容运维
+
+```bash
+# 1. 查看 chunk 列表
+bl knowledge chunk list --index-id idx-xxx --workspace-id ws-xxx
+# → 返回 metadata._id (chunk id) 和 metadata.doc_id (document id)
+
+# 2. 修改 chunk 内容
+bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id doc-xxx --content "修正后的内容" --workspace-id ws-xxx
+
+# 3. 排除某个 chunk 不参与检索（不删除内容）
+bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id doc-xxx --exclude --workspace-id ws-xxx
+
+# 4. 手动添加新 chunk
+bl knowledge chunk add --index-id idx-xxx --content "新增的知识片段" --title "补充说明" --workspace-id ws-xxx
+
+# 5. 删除 chunk（批量，自动分批每 10 个一组）
+bl knowledge chunk delete --index-id idx-xxx --chunk-id chunk-a --chunk-id chunk-b --yes --workspace-id ws-xxx
+```
+
+### 场景 E：服务迁移/复用
+
+```bash
+# 1. 复制现有服务为新草稿
+bl knowledge service copy --agent-id aid-source --workspace-id ws-xxx
+# → 返回新的 agent-id，名称加 copy_ 前缀
+
+# 2. 修改新服务配置
+bl knowledge service update --agent-id aid-new --name "改进版" --temperature 0.5 --workspace-id ws-xxx
+
+# 3. 测试并发布
+bl knowledge chat --message "测试" --agent-id aid-new --agent-version beta --workspace-id ws-xxx
+bl knowledge service deploy --agent-id aid-new --workspace-id ws-xxx --yes
+```
+
+### 场景 F：从 OSS 批量导入文件
+
+```bash
+# 1. 从已授权的 OSS bucket 批量导入文件到数据中心
+bl knowledge doc import-oss \
+  --bucket my-bucket --region cn-beijing \
+  --oss-key docs/a.pdf --oss-key docs/b.docx \
+  --workspace-id ws-xxx
+# → 返回各文件的 fileId
+
+# 2. 创建知识库并导入这些文件
+bl knowledge create --name oss-kb --description 'OSS 导入文档' --doc-id file-a --doc-id file-b --workspace-id ws-xxx --wait
+
+# 3. 检索
+bl knowledge search --query "相关内容" --agent-id aid-xxx --workspace-id ws-xxx
+```
+
+---
+
+## 命令手册
+
+以下按功能域分组，覆盖全部 34 个子命令。每个条目包含功能说明、用法签名（kscli 前缀）和详细手册链接。
+
+> 完整参数表、参数约束、输出说明、注意事项与示例请参阅各子域手册。子域手册中的用法签名使用 `bl knowledge` 前缀。
+
+---
+
+### 知识库管理
+
+> 📖 [完整手册](knowledge/kb.md) — 6 个命令
+
+#### `kscli kb list`
+
+列出工作区中的知识库。
+
+```bash
+kscli kb list [flags]
+```
+
+→ [完整参数与示例](knowledge/kb.md#bl-knowledge-list)
+
+---
+
+#### `kscli kb info`
+
+查看知识库配置详情。
+
+```bash
+kscli kb info --index-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/kb.md#bl-knowledge-info)
+
+---
+
+#### `kscli kb create`
+
+创建知识库并导入数据中心文件或分类。
+
+```bash
+kscli kb create --name <text> (--doc-id <id> | --category-id <id>) [flags]
+```
+
+→ [完整参数与示例](knowledge/kb.md#bl-knowledge-create)
+
+---
+
+#### `kscli kb update`
+
+更新知识库名称、描述或 rerank 阈值。
+
+```bash
+kscli kb update --index-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/kb.md#bl-knowledge-update)
+
+---
+
+#### `kscli kb delete`
+
+删除知识库及其所有文档和 chunk。
+
+```bash
+kscli kb delete --index-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/kb.md#bl-knowledge-delete)
+
+---
+
+#### `kscli kb stats`
+
+查看知识库存储和 QPS 监控数据。
+
+```bash
+kscli kb stats --index-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/kb.md#bl-knowledge-stats)
+
+---
+
+### 文档管理
+
+> 📖 [完整手册](knowledge/doc.md) — 6 个命令
+
+#### `kscli doc list`
+
+列出知识库中的文档及其解析/索引状态。
+
+```bash
+kscli doc list --index-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/doc.md#bl-knowledge-doc-list)
+
+---
+
+#### `kscli doc status`
+
+查看知识库导入任务状态。
+
+```bash
+kscli doc status --index-id <id> --job-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/doc.md#bl-knowledge-doc-status)
+
+---
+
+#### `kscli doc upload`
+
+上传本地文件或目录到数据中心，可选导入到知识库。
+
+```bash
+kscli doc upload --file <path> [flags]
+```
+
+→ [完整参数与示例](knowledge/doc.md#bl-knowledge-doc-upload)
+
+---
+
+#### `kscli doc delete`
+
+从知识库中删除文档及其 chunk。
+
+```bash
+kscli doc delete --index-id <id> --doc-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/doc.md#bl-knowledge-doc-delete)
+
+---
+
+#### `kscli doc tag`
+
+批量更新数据中心文件的标签。
+
+```bash
+kscli doc tag --doc-id <id> --tag <text> [flags]
+```
+
+→ [完整参数与示例](knowledge/doc.md#bl-knowledge-doc-tag)
+
+---
+
+#### `kscli doc import-oss`
+
+从已授权的 OSS bucket 批量导入文件到数据中心。
+
+```bash
+kscli doc import-oss --bucket <name> --region <id> --oss-key <key> [flags]
+```
+
+→ [完整参数与示例](knowledge/doc.md#bl-knowledge-doc-import-oss)
+
+---
+
+### 检索服务管理
+
+> 📖 [完整手册](knowledge/service.md) — 7 个命令
+
+#### `kscli service list`
+
+列出工作区中的检索/Q&A 服务。
+
+```bash
+kscli service list --scene <chat|search> [flags]
+```
+
+→ [完整参数与示例](knowledge/service.md#bl-knowledge-service-list)
+
+---
+
+#### `kscli service get`
+
+查看服务详情，含各版本配置。
+
+```bash
+kscli service get --agent-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/service.md#bl-knowledge-service-get)
+
+---
+
+#### `kscli service create`
+
+创建检索/Q&A 服务，初始状态为 draft，版本为 beta。
+
+```bash
+kscli service create --name <text> --scene <chat|search> [flags]
+```
+
+→ [完整参数与示例](knowledge/service.md#bl-knowledge-service-create)
+
+---
+
+#### `kscli service update`
+
+更新服务名称、描述或草稿配置。
+
+```bash
+kscli service update --agent-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/service.md#bl-knowledge-service-update)
+
+---
+
+#### `kscli service deploy`
+
+发布 beta 草稿为新版本。
+
+```bash
+kscli service deploy --agent-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/service.md#bl-knowledge-service-deploy)
+
+---
+
+#### `kscli service delete`
+
+删除检索/Q&A 服务（软删除，幂等）。
+
+```bash
+kscli service delete --agent-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/service.md#bl-knowledge-service-delete)
+
+---
+
+#### `kscli service copy`
+
+复制服务为新草稿（名称自动加 `copy_` 前缀）。
+
+```bash
+kscli service copy --agent-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/service.md#bl-knowledge-service-copy)
+
+---
+
+### Chunk 管理
+
+> 📖 [完整手册](knowledge/chunk.md) — 4 个命令
+
+#### `kscli chunk add`
+
+直接向知识库添加 chunk。
+
+```bash
+kscli chunk add --index-id <id> (--content <text> | --field <k=v>) [flags]
+```
+
+→ [完整参数与示例](knowledge/chunk.md#bl-knowledge-chunk-add)
+
+---
+
+#### `kscli chunk list`
+
+列出知识库中的 chunk，含内容和状态。
+
+```bash
+kscli chunk list --index-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/chunk.md#bl-knowledge-chunk-list)
+
+---
+
+#### `kscli chunk update`
+
+更新 chunk 内容或切换其检索可见性。
+
+```bash
+kscli chunk update --index-id <id> --chunk-id <id> --doc-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/chunk.md#bl-knowledge-chunk-update)
+
+---
+
+#### `kscli chunk delete`
+
+从知识库中删除 chunk（不可逆）。
+
+```bash
+kscli chunk delete --index-id <id> --chunk-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/chunk.md#bl-knowledge-chunk-delete)
+
+---
+
+### 数据中心文件管理
+
+> 📖 [完整手册](knowledge/file.md) — 3 个命令
+
+#### `kscli file list`
+
+列出数据中心分类下的文件。
+
+```bash
+kscli file list --category-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/file.md#bl-knowledge-file-list)
+
+---
+
+#### `kscli file get`
+
+查看数据中心文件详情。
+
+```bash
+kscli file get --file-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/file.md#bl-knowledge-file-get)
+
+---
+
+#### `kscli file delete`
+
+从数据中心永久删除文件。
+
+```bash
+kscli file delete --file-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/file.md#bl-knowledge-file-delete)
+
+---
+
+### 数据中心集合与分类
+
+> 📖 [完整手册](knowledge/collection-category.md) — 5 个命令
+
+#### `kscli collection create`
+
+创建 FILE 数据集合。
+
+```bash
+kscli collection create --name <text> --description <text> [flags]
+```
+
+→ [完整参数与示例](knowledge/collection-category.md#bl-knowledge-collection-create)
+
+---
+
+#### `kscli collection get`
+
+查看数据集合详情。
+
+```bash
+kscli collection get (--collection-id <id> | --name <text>) [flags]
+```
+
+→ [完整参数与示例](knowledge/collection-category.md#bl-knowledge-collection-get)
+
+---
+
+#### `kscli category list`
+
+列出数据中心分类。
+
+```bash
+kscli category list [flags]
+```
+
+→ [完整参数与示例](knowledge/collection-category.md#bl-knowledge-category-list)
+
+---
+
+#### `kscli category add`
+
+创建数据中心分类。
+
+```bash
+kscli category add --name <text> [flags]
+```
+
+→ [完整参数与示例](knowledge/collection-category.md#bl-knowledge-category-add)
+
+---
+
+#### `kscli category delete`
+
+删除数据中心分类。
+
+```bash
+kscli category delete --category-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/collection-category.md#bl-knowledge-category-delete)
+
+---
+
+### 检索与对话
+
+> 📖 [完整手册](knowledge/search-chat.md) — 3 个命令
+
+#### `kscli retrieve`
+
+从知识库检索（已废弃，请用 `search` 替代）。
+
+```bash
+kscli retrieve --index-id <id> --query <text> [flags]
+```
+
+→ [完整参数与示例](knowledge/search-chat.md#bl-knowledge-retrieve)
+
+---
+
+#### `kscli search`
+
+对知识库执行语义检索（RAG 检索）。
+
+```bash
+kscli search --query <text> --agent-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/search-chat.md#bl-knowledge-search)
+
+---
+
+#### `kscli chat`
+
+与知识库进行 RAG 对话（流式输出）。
+
+```bash
+kscli chat --message <text> --agent-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/search-chat.md#bl-knowledge-chat)
+
+---
+
+## 常见错误与排查
+
+### Workspace ID 缺失
+
+**报错**：`Workspace ID is required.`
+
+**原因**：所有 knowledge 管理命令都需要 workspace ID 来构造 API 端点（`{workspaceId}.cn-beijing.maas.aliyuncs.com`）。
+
+**解决**：
+
+```bash
+# 方式1：命令行参数
+bl knowledge list --workspace-id ws-xxx
+
+# 方式2：环境变量
+export BAILIAN_WORKSPACE_ID=ws-xxx
+
+# 方式3：配置文件
+bl config set workspace_id ws-xxx
+```
+
+### 知识库 ID 不存在
+
+**报错**：`Knowledge base not found: idx-xxx`
+
+**原因**：`--index-id` 指定的知识库在当前 workspace 中不存在。
+
+**解决**：先 `bl knowledge list` 确认知识库 ID。
+
+### 导入任务 SystemError
+
+**报错**：服务端返回 `SystemError`
+
+**原因**：`doc status` 传入了不存在的 job ID，或知识库空闲无任务。
+
+**解决**：检查 `doc list` 输出中的 `ingestionId`，或从 `doc upload`/`knowledge create` 的返回值获取。
+
+### doc_id 与 fileId 混淆
+
+**问题**：`doc delete` 时用了 `doc upload` 返回的 `fileId` 而非 `doc list` 返回的 `doc_id`。
+
+**原因**：通过 `knowledge create --doc-id` 导入的文档，`doc_id` 等于 `fileId`；但通过 `doc upload --index-id` 导入的，`doc_id` 可能含 workspace 后缀。
+
+**解决**：始终用 `doc list --quiet` 获取 `doc_id`。
+
+### retrieve 已废弃
+
+**问题**：`retrieve` 命令输出废弃警告。
+
+**解决**：改用 `search` 命令。`search` 通过 `--agent-id` 驱动检索策略，支持多知识库、路由、rerank 等高级特性。`retrieve` 直接操作 `--index-id`，功能受限且不再迭代。
+
+### OSS 导入权限错误
+
+**报错**：服务端返回权限相关错误。
+
+**原因**：OSS bucket 未授权给平台服务角色。
+
+**解决**：检查 RAM 控制台中的 `AliyunServiceRoleForBailian` 角色是否已正确授权。
+
+### Chat SSE error
+
+**报错**：`Chat API error` + API error code。
+
+**原因**：流式对话过程中服务端返回 error 事件。
+
+**解决**：检查 `--agent-id` 是否存在、服务是否已部署、API Key 是否有效。错误消息和 code 原样透传，不二次包装。
+
+### file list 返回空
+
+**问题**：`file list --category-id default` 返回空列表。
+
+**原因**：与上传 API 不同，`file list` 不解析字面量 `default`，需要真实分类 ID。
+
+**解决**：通过 `file get` 的 category 字段或 `category list` 获取真实分类 ID。
+
+### 集合无法删除
+
+**问题**：没有 `collection delete` 命令。
+
+**原因**：暂不支持通过 CLI 删除。
+
+**解决**：创建集合需谨慎。如需隔离，创建新集合并迁移文件。
+
+---
+
+## 附录：命令速查表
+
+| 命令                      | 功能         | 关键参数                                                    |
+| ------------------------- | ------------ | ----------------------------------------------------------- |
+| `kscli kb list`           | 列出知识库   | `--name`                                                    |
+| `kscli kb info`           | 知识库详情   | `--index-id`                                                |
+| `kscli kb create`         | 创建知识库   | `--name`, `--doc-id`/`--category-id`                        |
+| `kscli kb update`         | 更新知识库   | `--index-id`, `--name`/`--description`/`--rerank-min-score` |
+| `kscli kb delete`         | 删除知识库   | `--index-id`, `--yes`                                       |
+| `kscli kb stats`          | 监控数据     | `--index-id`, `--start`/`--end`                             |
+| `kscli doc list`          | 文档列表     | `--index-id`                                                |
+| `kscli doc status`        | 导入任务状态 | `--index-id`, `--job-id`, `--wait`                          |
+| `kscli doc upload`        | 上传文件     | `--file`, `--index-id`, `--wait`                            |
+| `kscli doc delete`        | 删除文档     | `--index-id`, `--doc-id`                                    |
+| `kscli doc tag`           | 文件打标签   | `--doc-id`, `--tag`, `--mode`                               |
+| `kscli doc import-oss`    | OSS 导入     | `--bucket`, `--region`, `--oss-key`                         |
+| `kscli service list`      | 服务列表     | `--scene`                                                   |
+| `kscli service get`       | 服务详情     | `--agent-id`                                                |
+| `kscli service create`    | 创建服务     | `--name`, `--scene`, `--index-id`                           |
+| `kscli service update`    | 更新服务     | `--agent-id`, 配置参数                                      |
+| `kscli service deploy`    | 发布服务     | `--agent-id`, `--yes`                                       |
+| `kscli service delete`    | 删除服务     | `--agent-id`, `--yes`                                       |
+| `kscli service copy`      | 复制服务     | `--agent-id`                                                |
+| `kscli chunk add`         | 添加 chunk   | `--index-id`, `--content`/`--field`                         |
+| `kscli chunk list`        | chunk 列表   | `--index-id`, `--doc-id`                                    |
+| `kscli chunk update`      | 更新 chunk   | `--index-id`, `--chunk-id`, `--doc-id`                      |
+| `kscli chunk delete`      | 删除 chunk   | `--index-id`, `--chunk-id`, `--yes`                         |
+| `kscli file list`         | 文件列表     | `--category-id`                                             |
+| `kscli file get`          | 文件详情     | `--file-id`                                                 |
+| `kscli file delete`       | 删除文件     | `--file-id`, `--yes`                                        |
+| `kscli collection create` | 创建集合     | `--name`, `--description`                                   |
+| `kscli collection get`    | 集合详情     | `--collection-id`/`--name`                                  |
+| `kscli category list`     | 分类列表     | `--collection-id`, `--parent-id`                            |
+| `kscli category add`      | 创建分类     | `--name`, `--parent-id`                                     |
+| `kscli category delete`   | 删除分类     | `--category-id`, `--yes`                                    |
+| `kscli retrieve`          | 检索（废弃） | `--index-id`, `--query`                                     |
+| `kscli search`            | 语义检索     | `--query`, `--agent-id`                                     |
+| `kscli chat`              | RAG 对话     | `--message`, `--agent-id`                                   |

docs/knowledge/search-chat.md

@@ -0,0 +1,218 @@
+# 检索与对话命令手册
+
+以下命令通过检索服务（agent）消费知识库。`search` 用于语义检索，`chat` 用于多轮对话。`retrieve` 已废弃。
+
+> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](../knowledge-cli-guide.md#通用约定)。
+
+---
+
+#### `bl knowledge retrieve`
+
+从知识库检索（已废弃，请用 `search` 替代）。
+
+**用法**
+
+```bash
+bl knowledge retrieve --index-id <id> --query <text> [flags]
+```
+
+**参数**
+
+| 参数                            | 类型   | 必填 | 说明                                                |
+| ------------------------------- | ------ | ---- | --------------------------------------------------- |
+| `--index-id <id>`               | string | 是   | 知识库 ID                                           |
+| `--query <text>`                | string | 是   | 检索查询文本                                        |
+| `--dense-similarity-top-k <n>`  | number | 否   | 稠密检索 top K                                      |
+| `--sparse-similarity-top-k <n>` | number | 否   | 稀疏检索 top K                                      |
+| `--rerank`                      | switch | 否   | 启用 rerank                                         |
+| `--rerank-top-n <n>`            | number | 否   | rerank 返回 top N 结果                              |
+| `--rerank-model <name>`         | string | 否   | rerank 模型名，如 `qwen3-rerank-hybrid`             |
+| `--rerank-mode <mode>`          | string | 否   | rerank 模式：`qa`、`similar` 或 `custom`            |
+| `--rerank-instruct <text>`      | string | 否   | 自定义 rerank 指令（`--rerank-mode custom` 时使用） |
+| `--top-k <n>`                   | number | 否   | 返回结果数（已废弃，用 `--rerank-top-n` 替代）      |
+
+**输出**
+
+text/quiet 模式：
+
+```
+[1] (score: 0.9512)
+检索到的文本内容...
+
+[2] (score: 0.8734)
+另一段文本内容...
+```
+
+> 无结果时输出 `No results found.`
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- **已废弃**，推荐使用 `search` 命令。`search` 通过 agent_id 驱动检索策略，支持更多高级特性。
+- `--top-k` 已废弃，使用 `--rerank-top-n` 替代，传入 `--top-k` 会输出 stderr 警告。
+- 此命令直接用 `--index-id` 检索，不需要创建检索服务。
+
+**示例**
+
+```bash
+# 基础检索
+bl knowledge retrieve --index-id idx-xxx --query "How to use Alibaba Cloud Bailian" --workspace-id ws-xxx
+
+# 启用 rerank
+bl knowledge retrieve --index-id idx-xxx --query "RAG retrieval" --rerank --rerank-model qwen3-rerank-hybrid
+```
+
+---
+
+#### `bl knowledge search`
+
+对知识库执行语义检索（RAG 检索）。
+
+**用法**
+
+```bash
+bl knowledge search --query <text> --agent-id <id> [flags]
+```
+
+**参数**
+
+| 参数                        | 类型   | 必填 | 说明                                                                |
+| --------------------------- | ------ | ---- | ------------------------------------------------------------------- |
+| `--query <text>`            | string | 是   | 检索查询文本（不可为空）                                            |
+| `--agent-id <id>`           | string | 是   | 检索服务 ID（在控制台知识检索页面获取，或通过 `service list` 查看） |
+| `--agent-version <version>` | string | 否   | 服务版本：`beta`（调试草稿）或已发布版本号；默认调用最新已发布版本  |
+| `--image <url>`             | array  | 否   | 图片 URL（可重复），用于多模态检索                                  |
+
+**参数约束**
+
+- `--query` 不可为空（API 要求 `minLength: 1`）
+
+**输出**
+
+text/quiet 模式：
+
+```
+[1] (score: 0.9512)
+检索到的文本内容...
+
+[2] (score: 0.8734)
+另一段文本内容...
+```
+
+> 无结果时输出 `No results found.`
+
+json 模式：返回 API 原始响应，`data.nodes[]` 包含检索结果。
+
+**注意事项**
+
+- 检索范围和策略（多知识库加权、路由、rerank 等）由 `--agent-id` 对应的服务配置驱动。只需 `--query` 和 `--agent-id` 即可调用。
+- `--agent-version beta` 调试草稿配置进行调试，部署前验证效果。
+- 与 `retrieve` 的区别：`search` 通过 agent_id 间接驱动检索策略（支持多知识库、路由、rerank 等），`retrieve` 直接操作 index_id 且功能较少。
+
+**示例**
+
+```bash
+# 基础检索
+bl knowledge search --query "What is RAG?" --agent-id aid-xxx --workspace-id ws-xxx
+
+# 多模态检索（带图片）
+bl knowledge search --query "describe this image" --agent-id aid-xxx --workspace-id ws-xxx --image https://example.com/img.jpg
+
+# 调试草稿版本
+bl knowledge search --query "test" --agent-id aid-xxx --agent-version beta --workspace-id ws-xxx
+```
+
+---
+
+#### `bl knowledge chat`
+
+与知识库进行 RAG 对话（流式输出）。
+
+**用法**
+
+```bash
+bl knowledge chat --message <text> --agent-id <id> [flags]
+```
+
+**参数**
+
+| 参数                        | 类型   | 必填 | 说明                                                                                                                           |
+| --------------------------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `--message <text>`          | array  | 是¹  | 消息文本（可重复）。支持 `role:content` 前缀设置角色（如 `user:hello`），默认角色为 `user`。也支持完整 JSON 对象传递结构化消息 |
+| `--agent-id <id>`           | string | 是   | Q&A 服务 ID（在控制台知识问答页面获取，或通过 `service list --scene chat` 查看）                                               |
+| `--agent-version <version>` | string | 否   | 服务版本：`beta`（调试草稿）或已发布版本号；默认调用最新已发布版本                                                             |
+| `--image <url>`             | array  | 否   | 图片 URL（可重复）。附加到最后一条 user 消息作为多模态内容                                                                     |
+
+> ¹ `--message` 或 `--image` 至少提供其一。纯图片查询可以只传 `--image`（CLI 会自动创建空 user 消息承载图片）。
+
+**参数约束**
+
+- `--message` 或 `--image` 至少提供一个
+- `--image` 不能与已包含 `image_url` 内容部分的消息同时使用
+
+**输出**
+
+**TTY text 模式**（实时流式）：
+
+```
+🔍 Retrieving...
+✍️ Generating...
+这是AI生成的回答内容，逐字流式输出...
+```
+
+> 进度标签由 SSE `step_change` 事件驱动：`tool_calling`（检索中）→ `plan_start`（规划中）→ `generation_start`（生成中）。
+
+**非 TTY text 模式**（缓冲输出）：
+
+```
+完整的回答文本...
+```
+
+**json 模式**（`--output json`）：
+
+```json
+{
+  "answer": "完整的回答文本...",
+  "request_id": "xxx"
+}
+```
+
+quiet 模式：输出完整的回答文本。
+
+**注意事项**
+
+- API 仅支持 SSE 流式响应。TTY 环境下实时打印 token；非 TTY 环境缓冲后输出完整文本。
+- SSE 事件生命周期：`tool_calling` → `tool_return` → `plan_start` → `planning` → `plan_end` → `generation_start` → `generating` → `generation_end`。`tool_calling` → `tool_return` 可能循环多次。
+- 多轮对话：用 `--message "user:..."` 和 `--message "assistant:..."` 传递对话历史。
+- `--agent-version beta` 调用草稿配置进行调试。
+- `--image` 附加到最后一条 user 消息上。如果消息中已包含 `image_url` 内容部分，则不能再用 `--image`。
+- `--verbose` 模式下，所有 SSE 事件详情会输出到 stderr。
+
+**示例**
+
+```bash
+# 单轮对话
+bl knowledge chat --message "What is RAG?" --agent-id aid-xxx --workspace-id ws-xxx
+
+# 多轮对话（带历史）
+bl knowledge chat \
+  --message "user:What is RAG?" \
+  --message "assistant:RAG is retrieval-augmented generation..." \
+  --message "How does it work?" \
+  --agent-id aid-xxx --workspace-id ws-xxx
+
+# 多模态对话（带图片）
+bl knowledge chat \
+  --message "Describe these images" \
+  --image https://example.com/a.png \
+  --image https://example.com/b.png \
+  --agent-id aid-xxx --workspace-id ws-xxx
+
+# 调试草稿版本
+bl knowledge chat --message "test" --agent-id aid-xxx --agent-version beta --workspace-id ws-xxx
+```
+
+---
+
+← [返回总览](../knowledge-cli-guide.md)

docs/knowledge/service.md

@@ -0,0 +1,401 @@
+# 检索服务管理命令手册
+
+检索服务（也称 agent）是知识库的检索入口。通过 `--agent-id` 在 search/chat 命令中使用。服务有 `chat`（问答）和 `search`（检索）两种场景。
+
+> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](../knowledge-cli-guide.md#通用约定)。
+
+---
+
+#### `bl knowledge service list`
+
+列出工作区中的检索/Q&A 服务。
+
+**用法**
+
+```bash
+bl knowledge service list --scene <chat|search> [flags]
+```
+
+**参数**
+
+| 参数                     | 类型   | 必填 | 说明                                                    |
+| ------------------------ | ------ | ---- | ------------------------------------------------------- |
+| `--scene <chat\|search>` | string | 是   | 服务场景：`chat`（Q&A）或 `search`（检索）              |
+| `--status <status>`      | string | 否   | 按状态过滤：`draft`、`deployed`（含 edited）、`deleted` |
+| `--name <text>`          | string | 否   | 按服务名称模糊过滤                                      |
+| `--agent-id <id>`        | string | 否   | 按精确 agent ID 过滤                                    |
+| `--index-id <id>`        | string | 否   | 按关联知识库 ID 过滤                                    |
+| `--page-number <n>`      | number | 否   | 页码（默认：1）                                         |
+| `--page-size <n>`        | number | 否   | 每页条数（默认：10，最大 100）                          |
+
+**参数约束**
+
+- `--scene` 只能是 `chat` 或 `search`
+- `--status` 只能是 `draft`、`deployed`、`deleted`
+- `--page-size` 范围 1-100
+
+**输出**
+
+text 模式：
+
+```
+aid-xxx  deployed  2  my-qa  (kb: my-kb)
+total: 1
+Use an agent_id above with the knowledge chat command.
+```
+
+> 最后一行根据 scene 自动提示用 `search` 还是 `chat` 命令消费。
+
+quiet 模式：每行一个 `agent_id`。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 服务端要求 `--scene` 必填，要查看两种场景的服务需分别执行。
+
+**示例**
+
+```bash
+# 列出 chat 服务
+bl knowledge service list --scene chat --workspace-id ws-xxx
+
+# 只看已部署的检索服务
+bl knowledge service list --scene search --status deployed
+```
+
+---
+
+#### `bl knowledge service get`
+
+查看服务详情，含各版本配置。
+
+**用法**
+
+```bash
+bl knowledge service get --agent-id <id> [flags]
+```
+
+**参数**
+
+| 参数                        | 类型   | 必填 | 说明                                                      |
+| --------------------------- | ------ | ---- | --------------------------------------------------------- |
+| `--agent-id <id>`           | string | 是   | 服务（agent）ID                                           |
+| `--agent-version <version>` | string | 否   | 指定版本查看（`beta` 或已发布版本号）；不传则返回所有版本 |
+
+**输出**
+
+text 模式：
+
+```
+Basic:
+  id: aid-xxx
+  name: my-qa
+  desc: product Q&A
+  scene: chat
+  status: deployed
+Version beta:
+  desc: draft
+  policy: turbo
+  model: qwen-max
+  temperature: 0.7
+  kb: idx-xxx (my-kb)
+Version 1:
+  published: 2026-01-01
+  ...
+```
+
+quiet 模式：输出 JSON 格式。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 不传 `--agent-version` 时返回所有版本（beta 草稿 + 已发布版本号）。
+- 版本值原样传递，有效值集合由服务端维护。
+
+**示例**
+
+```bash
+# 查看服务完整详情
+bl knowledge service get --agent-id aid-xxx --workspace-id ws-xxx
+
+# 只看 beta 草稿配置
+bl knowledge service get --agent-id aid-xxx --agent-version beta
+```
+
+---
+
+#### `bl knowledge service create`
+
+创建检索/Q&A 服务，初始状态为 draft，版本为 beta。
+
+**用法**
+
+```bash
+bl knowledge service create --name <text> --scene <chat|search> [flags]
+```
+
+**参数**
+
+| 参数                     | 类型   | 必填 | 说明                                              |
+| ------------------------ | ------ | ---- | ------------------------------------------------- |
+| `--name <text>`          | string | 是   | 服务名称（最多 200 字符，同一场景下工作区内唯一） |
+| `--scene <chat\|search>` | string | 是   | 服务场景：`chat`（Q&A）或 `search`（检索）        |
+| `--description <text>`   | string | 建议 | 这个服务能回答什么、给谁用（最多 1000 字符）      |
+| `--index-id <id>`        | string | 否   | 绑定此知识库；其他配置使用服务端默认值            |
+
+**参数约束**
+
+- `--name` 最多 200 字符
+- `--scene` 只能是 `chat` 或 `search`
+- `--description` 最多 1000 字符；建议填写 —— agent 靠它判断该调用哪个服务
+
+**输出**
+
+text 模式：
+
+```
+created: aid-xxx  (status: draft, version: beta)
+Test the draft with --agent-version beta on search/chat, then deploy it to publish.
+```
+
+quiet 模式：输出 agent ID。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 不指定 `--index-id` 时，服务端使用默认 agent 配置。
+- beta 草稿可通过 search/chat 的 `--agent-version beta` 测试，部署后才生效。
+- 需要工作区的知识库创建权限。
+
+**示例**
+
+```bash
+# 创建 Q&A 服务
+bl knowledge service create --name my-qa --scene chat --workspace-id ws-xxx
+
+# 创建检索服务并绑定知识库
+bl knowledge service create --name my-search --scene search --index-id idx-xxx
+```
+
+---
+
+#### `bl knowledge service update`
+
+更新服务名称、描述或草稿配置。
+
+**用法**
+
+```bash
+bl knowledge service update --agent-id <id> [flags]
+```
+
+**参数**
+
+| 参数                           | 类型   | 必填 | 说明                                                                                     |
+| ------------------------------ | ------ | ---- | ---------------------------------------------------------------------------------------- |
+| `--agent-id <id>`              | string | 是   | 服务（agent）ID                                                                          |
+| `--name <text>`                | string | 否   | 新名称（最多 200 字符）                                                                  |
+| `--description <text>`         | string | 否   | 新描述（最多 1000 字符）                                                                 |
+| `--agent-version <version>`    | string | 否   | 目标版本（默认：beta 草稿。已发布版本只接受 `--version-desc`）                           |
+| `--version-desc <text>`        | string | 否   | 版本描述                                                                                 |
+| `--policy <policy>`            | string | 否   | Agent 策略：`turbo`（快速）或 `agentic`（多轮）                                          |
+| `--model <name>`               | string | 否   | 生成模型代码（须在平台白名单中）                                                         |
+| `--temperature <n>`            | number | 否   | 采样温度，范围 0-2                                                                       |
+| `--max-llm-calls <n>`          | number | 否   | 单次请求最大 LLM 调用次数，范围 1-30                                                     |
+| `--enable-session-file <bool>` | string | 否   | 启用会话文件：`true` 或 `false`                                                          |
+| `--enable-refusal <bool>`      | string | 否   | 启用拒答：`true` 或 `false`                                                              |
+| `--enable-anti-leak <bool>`    | string | 否   | 启用防泄漏：`true` 或 `false`                                                            |
+| `--enable-rich-text <bool>`    | string | 否   | 启用富文本输出：`true` 或 `false`                                                        |
+| `--enable-citation <bool>`     | string | 否   | 启用引用标注：`true` 或 `false`                                                          |
+| `--config-file <path>`         | string | 否   | JSON 文件替换整个 `agent_config`（含嵌套设置如 `kb_search_configs`）；与标量配置参数互斥 |
+
+**参数约束**
+
+- 至少提供一个更新项（`--name`/`--description`/`--version-desc`/`--config-file`/标量配置参数），否则报错 "Nothing to update"
+- `--config-file` 与标量配置参数（`--policy`/`--model`/`--temperature` 等）互斥
+- 已发布版本 + 配置变更 → 报错（已发布版本只接受 `--version-desc`）
+- `--name` 最多 200 字符；`--description` 最多 1000 字符
+- `--policy` 只能是 `turbo` 或 `agentic`
+- `--temperature` 范围 0-2
+- `--max-llm-calls` 范围 1-30
+- 布尔参数（`--enable-*`）只能是 `true` 或 `false`
+
+**输出**
+
+text 模式：
+
+```
+updated: aid-xxx
+Draft config changed — verify with --agent-version beta, then deploy.
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 配置变更只作用于 beta 草稿；已发布版本只接受 `--version-desc`。
+- 标量配置参数采用 read-merge-write：CLI 先读取当前 beta 配置，再合并变更后整体提交（API 是整替换语义）。
+- `--config-file` 替换整个配置，适合设置嵌套字段（如 `kb_search_configs`）。
+- 修改草稿后用 `--agent-version beta` 在 search/chat 上测试，通过后 `service deploy` 发布。
+
+**示例**
+
+```bash
+# 调整温度
+bl knowledge service update --agent-id aid-xxx --temperature 0.7 --workspace-id ws-xxx
+
+# 用 JSON 文件替换整个配置
+bl knowledge service update --agent-id aid-xxx --config-file ./agent-config.json
+
+# 给已发布版本 1 加描述
+bl knowledge service update --agent-id aid-xxx --agent-version 1 --version-desc "first stable release"
+```
+
+---
+
+#### `bl knowledge service deploy`
+
+发布 beta 草稿为新版本。
+
+**用法**
+
+```bash
+bl knowledge service deploy --agent-id <id> [flags]
+```
+
+**参数**
+
+| 参数                    | 类型   | 必填 | 说明                   |
+| ----------------------- | ------ | ---- | ---------------------- |
+| `--agent-id <id>`       | string | 是   | 服务（agent）ID        |
+| `--version-desc <text>` | string | 否   | 新版本的描述说明       |
+| `--yes`                 | switch | 否   | 显式确认执行高风险操作 |
+
+**输出**
+
+text 模式：
+
+```
+deployed: aid-xxx  version 2
+```
+
+quiet 模式：输出新版本号。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 版本号自动递增，状态变为 `deployed`。
+- 发布影响线上调用方，确认提示会警告。
+- 如果当前状态为 `edited`（已发布后又改了草稿），确认提示会额外警告「发布会覆盖线上行为」。
+- 需要工作区的知识库修改权限。
+
+**示例**
+
+```bash
+# 发布（交互确认）
+bl knowledge service deploy --agent-id aid-xxx --workspace-id ws-xxx
+
+# 带描述并跳过确认
+bl knowledge service deploy --agent-id aid-xxx --version-desc "tuned rerank params" --yes
+```
+
+---
+
+#### `bl knowledge service delete`
+
+删除检索/Q&A 服务（软删除，幂等）。
+
+**用法**
+
+```bash
+bl knowledge service delete --agent-id <id> [flags]
+```
+
+**参数**
+
+| 参数              | 类型   | 必填 | 说明                   |
+| ----------------- | ------ | ---- | ---------------------- |
+| `--agent-id <id>` | string | 是   | 服务（agent）ID        |
+| `--yes`           | switch | 否   | 显式确认执行高风险操作 |
+
+**输出**
+
+text 模式：
+
+```
+deleted: aid-xxx  (status: deleted)
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 删除不可撤销，`agent_id` 不再可用于 search/chat 调用。
+- API 是幂等的：删除已删除的服务不会报错。
+- 如果服务状态为 `deployed` 或 `edited`，确认提示会额外警告「此服务正在线上运行」。
+- 需要工作区的知识库删除权限。
+
+**示例**
+
+```bash
+# 删除（交互确认）
+bl knowledge service delete --agent-id aid-xxx --workspace-id ws-xxx
+
+# 跳过确认
+bl knowledge service delete --agent-id aid-xxx --yes
+```
+
+---
+
+#### `bl knowledge service copy`
+
+复制服务为新草稿（名称自动加 `copy_` 前缀）。
+
+**用法**
+
+```bash
+bl knowledge service copy --agent-id <id> [flags]
+```
+
+**参数**
+
+| 参数              | 类型   | 必填 | 说明              |
+| ----------------- | ------ | ---- | ----------------- |
+| `--agent-id <id>` | string | 是   | 源服务（agent）ID |
+
+**输出**
+
+text 模式：
+
+```
+new agent_id: aid-new  (name: copy_my-qa, status: draft)
+Test the draft with --agent-version beta on search/chat, then deploy it to publish.
+```
+
+quiet 模式：输出新 agent ID。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 副本初始为 beta 草稿，测试后需 deploy 发布。
+- 需要工作区的知识库创建权限。
+
+**示例**
+
+```bash
+# 复制服务
+bl knowledge service copy --agent-id aid-source --workspace-id ws-xxx
+```
+
+---
+
+← [返回总览](../knowledge-cli-guide.md)

docs/kscli/chunk.md

@@ -0,0 +1,248 @@
+# Chunk 管理命令手册
+
+Chunk 是知识库中最小的检索单元。文档导入后自动切分为 chunk，也可以手动添加。
+
+> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。
+
+---
+
+#### `kscli chunk add`
+
+直接向知识库添加 chunk。
+
+**用法**
+
+```bash
+kscli chunk add --index-id <id> (--content <text> | --field <k=v>) [flags]
+```
+
+**参数**
+
+| 参数                    | 类型   | 必填 | 说明                                                                                        |
+| ----------------------- | ------ | ---- | ------------------------------------------------------------------------------------------- |
+| `--index-id <id>`       | string | 是   | 知识库 ID                                                                                   |
+| `--doc-id <id>`         | string | 否²  | 所属文档 ID；表格/图片知识库必填，文档型可选                                                |
+| `--content <text>`      | string | 否¹  | Chunk 正文，最多 6000 字符（文档型）；与 `--content-file` 互斥                              |
+| `--content-file <path>` | string | 否¹  | 从 UTF-8 文本文件读取正文（`.md`/`.txt` 等）；与 `--content` 互斥                           |
+| `--title <text>`        | string | 否   | Chunk 标题，最多 50 字符（文档型）                                                          |
+| `--image-url <url>`     | array  | 否   | Chunk 图片 URL（可重复，最多 10 个；文档型）                                                |
+| `--field <key=value>`   | array  | 否¹  | 任意字段键值对（可重复），用于表格/图片知识库，键为 Excel 列名；与 content/title/image 互斥 |
+
+> ¹ `--content`/`--content-file`/`--title`/`--image-url` 与 `--field` 互斥，必须提供其一。
+> ² 表格/图片知识库必须提供 `--doc-id`。文档型知识库可选。
+
+**参数约束**
+
+- `--field` 与 `--content`/`--content-file`/`--title`/`--image-url` 互斥
+- `--content` 与 `--content-file` 互斥
+- `--content` 最多 6000 字符
+- `--title` 最多 50 字符
+- `--image-url` 最多 10 个
+
+**输出**
+
+text 模式：
+
+```
+chunk created (pipeline: idx-xxx)
+List chunks to find the new chunk id.
+```
+
+quiet 模式：无输出（成功退出码 0）。
+
+json 模式：返回 API 原始响应（不含 chunk ID）。
+
+**注意事项**
+
+- 支持文档/表格/图片知识库；音视频知识库不支持。
+- API 响应不含 chunk ID，需用 `chunk list` 查找新 chunk。
+- API 幂等但限流 10 次/秒，批量脚本需自行节流。
+- 表格/图片知识库用 `--field`，键为 Excel 列名，值为字符串。
+
+**示例**
+
+```bash
+# 添加文本 chunk
+kscli chunk add --index-id idx-xxx --content "chunk text" --title intro --workspace-id ws-xxx
+
+# 添加表格行（字段方式）
+kscli chunk add --index-id idx-xxx --field 列A=v1 --field 列B=v2
+
+# 从文件读取内容
+kscli chunk add --index-id idx-xxx --content-file ./chunk.md --doc-id doc-xxx
+```
+
+---
+
+#### `kscli chunk list`
+
+列出知识库中的 chunk，含内容和状态。
+
+**用法**
+
+```bash
+kscli chunk list --index-id <id> [flags]
+```
+
+**参数**
+
+| 参数                | 类型   | 必填 | 说明                           |
+| ------------------- | ------ | ---- | ------------------------------ |
+| `--index-id <id>`   | string | 是   | 知识库 ID                      |
+| `--doc-id <id>`     | string | 否   | 只显示属于此文档的 chunk       |
+| `--page-number <n>` | number | 否   | 页码（默认：1）                |
+| `--page-size <n>`   | number | 否   | 每页条数（默认：20，最大 100） |
+
+**参数约束**
+
+- `--page-size` 范围 1-100
+
+**输出**
+
+text 模式：
+
+```
+[chunk] chunk-xxx  (doc: intro.md, doc_id: file-xxx)  status: COMPLETED
+  chunk content preview (truncated at 200 chars)…
+total: 1
+```
+
+> 如果 chunk 被排除检索，行尾会显示 `[excluded from retrieval]`。
+
+quiet 模式：每行一个 `metadata._id`（chunk ID），用于管道传给 update/delete。
+
+json 模式：返回 API 原始响应，`data.nodes[]` 含完整 chunk 数据。
+
+**注意事项**
+
+- 用 `metadata._id` 作为 chunk ID，`metadata.doc_id` 作为文档 ID，在 chunk update/delete 中使用。
+- 页大小默认 20，最大 100。
+
+**示例**
+
+```bash
+# 列出所有 chunk
+kscli chunk list --index-id idx-xxx --workspace-id ws-xxx
+
+# 只看某文档的 chunk
+kscli chunk list --index-id idx-xxx --doc-id file-xxx --page-size 50
+```
+
+---
+
+#### `kscli chunk update`
+
+更新 chunk 内容或切换其检索可见性。
+
+**用法**
+
+```bash
+kscli chunk update --index-id <id> --chunk-id <id> --doc-id <id> [flags]
+```
+
+**参数**
+
+| 参数                    | 类型   | 必填 | 说明                                                   |
+| ----------------------- | ------ | ---- | ------------------------------------------------------ |
+| `--index-id <id>`       | string | 是   | 知识库 ID                                              |
+| `--chunk-id <id>`       | string | 是   | Chunk ID（`metadata._id`，来自 chunk list 输出）       |
+| `--doc-id <id>`         | string | 是   | 所属文档 ID（`metadata.doc_id`，来自 chunk list 输出） |
+| `--content <text>`      | string | 否¹  | 新内容，10-6000 字符；与 `--content-file` 互斥         |
+| `--content-file <path>` | string | 否¹  | 从 UTF-8 文本文件读取新内容                            |
+| `--title <text>`        | string | 否   | Chunk 标题，0-50 字符（空字符串清除标题；不传则不变）  |
+| `--exclude`             | switch | 否²  | 将此 chunk 排除出检索                                  |
+| `--include`             | switch | 否²  | 将此 chunk 恢复检索（默认行为）                        |
+
+> ¹ `--content` 与 `--content-file` 互斥。
+> ² `--exclude` 与 `--include` 互斥。
+
+**参数约束**
+
+- `--content` 与 `--content-file` 互斥
+- `--exclude` 与 `--include` 互斥
+- 至少提供一个更新项（`--content`/`--content-file`/`--title`/`--exclude`/`--include`）
+- `--content` 长度 10-6000 字符
+- `--title` 最多 50 字符
+
+**输出**
+
+text 模式：
+
+```
+updated: chunk-xxx
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 内容必须 10-6000 字符，且不超过知识库的 max chunk size。
+- `--content-file` 期望 UTF-8 纯文本文件，不解析 `.docx`/`.pdf` 等文档格式。
+- 仅切换 `--exclude`/`--include` 而不提供新内容时，CLI 自动读回当前内容并重新提交（API 要求 content 字段必填，CLI 隐藏了此限制）。
+
+**示例**
+
+```bash
+# 修改内容
+kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --content "corrected text" --workspace-id ws-xxx
+
+# 排除 chunk 不参与检索
+kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --exclude
+
+# 恢复检索
+kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --include
+```
+
+---
+
+#### `kscli chunk delete`
+
+从知识库中删除 chunk（不可逆）。
+
+**用法**
+
+```bash
+kscli chunk delete --index-id <id> --chunk-id <id> [flags]
+```
+
+**参数**
+
+| 参数              | 类型   | 必填 | 说明                                             |
+| ----------------- | ------ | ---- | ------------------------------------------------ |
+| `--index-id <id>` | string | 是   | 知识库 ID                                        |
+| `--chunk-id <id>` | array  | 是   | Chunk ID（可重复，每批最多 10 个，超出自动分批） |
+| `--yes`           | switch | 否   | 显式确认执行高风险操作                           |
+
+**输出**
+
+text 模式：
+
+```
+deleted: 2 chunk(s) in 1 batch(es)
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 `{ deleted_count, batches }`。
+
+**注意事项**
+
+- 服务端每次最多接受 10 个 chunk ID，CLI 自动分批。
+- 如果某批失败，操作停止，已删除的批次会在错误 hint 中列出。
+- Chunk 被永久移除，不可恢复。
+
+**示例**
+
+```bash
+# 删除多个 chunk
+kscli chunk delete --index-id idx-xxx --chunk-id chunk-a --chunk-id chunk-b --workspace-id ws-xxx
+
+# 跳过确认
+kscli chunk delete --index-id idx-xxx --chunk-id chunk-a --yes
+```
+
+---
+
+← [返回总览](./kscli-cli-guide.md)

docs/kscli/collection-category.md

@@ -0,0 +1,268 @@
+# 数据中心集合与分类命令手册
+
+集合（collection）是数据中心的顶层容器，对应服务端的 connector。分类（category）用于组织集合内的文件，支持多级嵌套。
+
+> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。
+
+---
+
+#### `kscli collection create`
+
+创建 FILE 数据集合。
+
+**用法**
+
+```bash
+kscli collection create --name <text> --description <text> [flags]
+```
+
+**参数**
+
+| 参数                   | 类型   | 必填 | 说明                                                             |
+| ---------------------- | ------ | ---- | ---------------------------------------------------------------- |
+| `--name <text>`        | string | 是   | 集合名称（1-20 字符）                                            |
+| `--description <text>` | string | 是   | 集合描述                                                         |
+| `--store-type <type>`  | string | 否   | 存储类型：`platform`（托管，默认）或 `custom`（自有 OSS bucket） |
+| `--oss-region <id>`    | string | 否   | OSS region ID（`--store-type custom` 时必填）                    |
+| `--oss-bucket <name>`  | string | 否   | OSS bucket 名称（`--store-type custom` 时必填）                  |
+
+**参数约束**
+
+- `--name` 长度 1-20 字符
+- `--store-type` 只能是 `platform` 或 `custom`
+- `--store-type custom` 时 `--oss-region` 和 `--oss-bucket` 必填
+
+**输出**
+
+text 模式：
+
+```
+created: conn-xxx  (my-collection, PLATFORM)
+```
+
+quiet 模式：输出集合 ID。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- `platform` 使用平台托管存储；`custom` 使用已授权的 OSS bucket。
+- 自定义 bucket 必须携带标签 `bailian-connector-access=ReadAndWrite`（百炼的标签访问控制），否则服务端报 `setBucketCORS failed` 误导性错误。
+- **无集合删除 API**，创建需谨慎。
+
+**示例**
+
+```bash
+# 创建平台托管的集合
+kscli collection create --name my-collection --description "team docs" --workspace-id ws-xxx
+
+# 创建使用自有 OSS bucket 的集合
+kscli collection create --name oss-coll --description "own bucket" --store-type custom --oss-region cn-beijing --oss-bucket my-bucket
+```
+
+---
+
+#### `kscli collection get`
+
+查看数据集合详情。
+
+**用法**
+
+```bash
+kscli collection get (--collection-id <id> | --name <text>) [flags]
+```
+
+**参数**
+
+| 参数                   | 类型   | 必填 | 说明     |
+| ---------------------- | ------ | ---- | -------- |
+| `--collection-id <id>` | string | 否¹  | 集合 ID  |
+| `--name <text>`        | string | 否¹  | 集合名称 |
+
+> ¹ `--collection-id` 和 `--name` 二选一，必须提供其一。
+
+**参数约束**
+
+- `--collection-id` 和 `--name` 互斥，必须提供其一
+
+**输出**
+
+text 模式：
+
+```
+id: conn-xxx
+name: my-collection
+description: team docs
+```
+
+quiet 模式：输出集合 ID。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- getConnector 不返回 `fileConnectorConfig`（`storeType`/`regionId`/`bucketName`），这些字段仅在创建时通过请求体传入，查询时不可读回。
+
+**示例**
+
+```bash
+# 按 ID 查询
+kscli collection get --collection-id conn-xxx --workspace-id ws-xxx
+
+# 按名称查询
+kscli collection get --name my-collection
+```
+
+---
+
+#### `kscli category list`
+
+列出数据中心分类。
+
+**用法**
+
+```bash
+kscli category list [flags]
+```
+
+**参数**
+
+| 参数                   | 类型   | 必填 | 说明                                                   |
+| ---------------------- | ------ | ---- | ------------------------------------------------------ |
+| `--collection-id <id>` | string | 否   | 按集合 ID 过滤                                         |
+| `--parent-id <id>`     | string | 否   | 列出此分类的子分类                                     |
+| `--name <text>`        | string | 否   | 按分类名称过滤（精确匹配，与知识库列表的模糊匹配不同） |
+| `--next-token <token>` | string | 否   | 游标分页令牌                                           |
+| `--max-result <n>`     | number | 否   | 每页条数（默认：20）                                   |
+
+**输出**
+
+text 模式：
+
+```
+cate-xxx  product-docs
+cate-yyy  system-docs  [default]
+next: --next-token eyJ...
+```
+
+> 标记 `[default]` 的是文件未指定分类时的默认归属。
+
+quiet 模式：每行一个 `categoryId`。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 分页是游标方式：使用输出的 `next: --next-token <token>` 继续翻页。
+
+**示例**
+
+```bash
+# 列出所有分类
+kscli category list --workspace-id ws-xxx
+
+# 按名称过滤
+kscli category list --name my-category
+
+# 翻页
+kscli category list --next-token eyJ...
+```
+
+---
+
+#### `kscli category add`
+
+创建数据中心分类。
+
+**用法**
+
+```bash
+kscli category add --name <text> [flags]
+```
+
+**参数**
+
+| 参数                   | 类型   | 必填 | 说明                             |
+| ---------------------- | ------ | ---- | -------------------------------- |
+| `--name <text>`        | string | 是   | 分类名称（1-20 字符）            |
+| `--parent-id <id>`     | string | 否   | 创建为指定分类的子分类           |
+| `--collection-id <id>` | string | 否   | 创建在此集合下（默认：平台集合） |
+
+**参数约束**
+
+- `--name` 长度 1-20 字符
+
+**输出**
+
+text 模式：
+
+```
+created: cate-xxx  (product-docs)
+```
+
+quiet 模式：输出分类 ID。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 用分类按业务域组织数据中心文件。
+
+**示例**
+
+```bash
+# 创建分类
+kscli category add --name product-docs --workspace-id ws-xxx
+
+# 创建子分类
+kscli category add --name sub --parent-id cate-xxx
+```
+
+---
+
+#### `kscli category delete`
+
+删除数据中心分类。
+
+**用法**
+
+```bash
+kscli category delete --category-id <id> [flags]
+```
+
+**参数**
+
+| 参数                 | 类型   | 必填 | 说明                   |
+| -------------------- | ------ | ---- | ---------------------- |
+| `--category-id <id>` | string | 是   | 分类 ID                |
+| `--yes`              | switch | 否   | 显式确认执行高风险操作 |
+
+**输出**
+
+text 模式：
+
+```
+deleted: cate-xxx
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 含文件或子分类的分类的删除行为由服务端定义——服务端错误原样透传。
+
+**示例**
+
+```bash
+# 删除分类（交互确认）
+kscli category delete --category-id cate-xxx --workspace-id ws-xxx
+
+# 跳过确认
+kscli category delete --category-id cate-xxx --yes
+```
+
+---
+
+← [返回总览](./kscli-cli-guide.md)

docs/kscli/doc.md

@@ -0,0 +1,344 @@
+# 文档管理命令手册
+
+文档管理覆盖文件上传、OSS 导入、解析状态跟踪、文档删除和标签管理。文档导入知识库后自动解析为 chunk。
+
+> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。
+
+---
+
+#### `kscli doc list`
+
+列出知识库中的文档及其解析/索引状态。
+
+**用法**
+
+```bash
+kscli doc list --index-id <id> [flags]
+```
+
+**参数**
+
+| 参数                | 类型   | 必填 | 说明                           |
+| ------------------- | ------ | ---- | ------------------------------ |
+| `--index-id <id>`   | string | 是   | 知识库 ID                      |
+| `--page-number <n>` | number | 否   | 页码（默认：1）                |
+| `--page-size <n>`   | number | 否   | 每页条数（默认：10，最大 100） |
+
+**参数约束**
+
+- `--page-size` 范围 1-100
+
+**输出**
+
+text 模式：每行一个文档，`FAILED` 状态的文档红色高亮。
+
+```
+doc-xxx  COMPLETED  intro.md  md  1024
+total: 1
+```
+
+quiet 模式：每行一个 `doc_id`。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- `doc_id` 与 `file_id` 的关系：通过 `kb create --doc-id` 导入的文档，`doc_id` 等于 `fileId`；通过 `doc upload --index-id` 导入的，`doc_id` 可能包含 workspace 后缀。
+- 页大小默认 10（服务端默认），最大 100。
+
+**示例**
+
+```bash
+# 列出文档
+kscli doc list --index-id idx-xxx --workspace-id ws-xxx
+
+# 每页 100 条
+kscli doc list --index-id idx-xxx --page-size 100
+```
+
+---
+
+#### `kscli doc status`
+
+查看知识库导入任务状态。
+
+**用法**
+
+```bash
+kscli doc status --index-id <id> --job-id <id> [flags]
+```
+
+**参数**
+
+| 参数                        | 类型   | 必填 | 说明                                                |
+| --------------------------- | ------ | ---- | --------------------------------------------------- |
+| `--index-id <id>`           | string | 是   | 知识库 ID                                           |
+| `--job-id <id>`             | string | 是   | 导入任务 ID（`ingestionId`，由 create/upload 返回） |
+| `--page-number <n>`         | number | 否   | 页码                                                |
+| `--page-size <n>`           | number | 否   | 每页条数                                            |
+| `--wait`                    | switch | 否   | 轮询直到任务到达终态                                |
+| `--poll-interval <seconds>` | number | 否   | 轮询间隔秒数（默认：5）                             |
+
+**输出**
+
+text 模式：
+
+```
+status: COMPLETED
+  doc-xxx  COMPLETED  intro.md
+```
+
+quiet 模式：输出任务状态（`PENDING`/`RUNNING`/`COMPLETED`）。
+
+json 模式：返回 API 原始响应，`data.rows[]` 包含每个文档的状态。
+
+**注意事项**
+
+- `--index-id` 和 `--job-id` 服务端均要求必传，只传一个会返回 `SystemError`。
+- 整体任务状态为 `PENDING` / `RUNNING` / `COMPLETED`（无 `FAILED` 值）。
+- 单个文档可能解析失败（如 `PARSE_FAILED`），此时 CLI 以非零退出码报错，服务端消息原样透传。
+- 如果服务端对空闲知识库返回 `SystemError`，说明该 job 可能不存在。
+
+**示例**
+
+```bash
+# 查看任务状态
+kscli doc status --index-id idx-xxx --job-id job-xxx --workspace-id ws-xxx
+
+# 轮询等待完成，10 秒间隔
+kscli doc status --index-id idx-xxx --job-id job-xxx --wait --poll-interval 10
+```
+
+---
+
+#### `kscli doc upload`
+
+上传本地文件或目录到数据中心，可选导入到知识库。
+
+**用法**
+
+```bash
+kscli doc upload --file <path> [flags]
+```
+
+**参数**
+
+| 参数                        | 类型   | 必填 | 说明                                                             |
+| --------------------------- | ------ | ---- | ---------------------------------------------------------------- |
+| `--file <path>`             | array  | 是   | 本地文件或目录路径（可重复）。目录递归扫描，不支持的格式自动跳过 |
+| `--index-id <id>`           | string | 否   | 上传后导入到此知识库（所有文件合并为一个导入任务）               |
+| `--category-id <id>`        | string | 否   | 目标数据中心分类（默认：工作区默认分类）                         |
+| `--tag <text>`              | array  | 否   | 文件标签（可重复），应用到每个上传的文件                         |
+| `--wait`                    | switch | 否   | 轮询导入任务直到终态（需要 `--index-id`）                        |
+| `--poll-interval <seconds>` | number | 否   | 轮询间隔秒数（默认：5）                                          |
+
+**参数约束**
+
+- `--wait` 要求同时指定 `--index-id`
+
+**输出**
+
+text 模式：
+
+```
+intro.md  file-xxx  registered
+job: job-xxx
+status: COMPLETED
+
+Uploaded 1 file.
+```
+
+quiet 模式：每行一个 `fileId`。
+
+json 模式：返回自定义结构，包含 `files`（路径和 fileId）、`skipped`、`index_id`、`ingestion_id`、`final_status`。
+
+**注意事项**
+
+- 上传管道：申请 lease → PUT 到 OSS → 注册文件 →（可选）创建导入任务。
+- 目录递归扫描，`node_modules`、`.git` 等自动跳过。
+- 多文件按顺序处理（无并发），避免 OSS 限流。
+- 支持的文件格式：`.pdf .doc .docx .ppt .pptx .xls .xlsx .csv .md .txt .html .png .jpg .jpeg .bmp .gif`
+- 部分文件上传失败时，已注册的 fileId 会在错误 hint 中列出。
+
+**示例**
+
+```bash
+# 上传单个文件
+kscli doc upload --file ./a.md --workspace-id ws-xxx
+
+# 上传多个文件并导入到知识库，等待完成
+kscli doc upload --file ./a.md --file ./b.pdf --index-id idx-xxx --wait
+
+# 上传整个目录
+kscli doc upload --file ./docs/ --workspace-id ws-xxx
+
+# 干跑预览（查看将上传和跳过的文件）
+kscli doc upload --file ./docs/ --dry-run --verbose
+```
+
+---
+
+#### `kscli doc delete`
+
+从知识库中删除文档及其 chunk。
+
+**用法**
+
+```bash
+kscli doc delete --index-id <id> --doc-id <id> [flags]
+```
+
+**参数**
+
+| 参数              | 类型   | 必填 | 说明               |
+| ----------------- | ------ | ---- | ------------------ |
+| `--index-id <id>` | string | 是   | 知识库 ID          |
+| `--doc-id <id>`   | array  | 是   | 文档 ID（可重复）  |
+| `--yes`           | switch | 否   | 显式确认高风险操作 |
+
+**输出**
+
+text 模式：
+
+```
+deleted: 2 document(s)
+  doc-a
+  doc-b
+```
+
+quiet 模式：每行一个已删除的 `doc_id`。
+
+json 模式：返回 API 原始响应，`data.deleted[]` 为实际删除的 ID 列表。
+
+**注意事项**
+
+- 只从知识库索引中移除文档，数据中心源文件不受影响（用 `file delete` 删除源文件）。
+- `doc_id` 应从 `doc list --quiet` 获取，而非 `doc upload` 返回的 `fileId`。
+- 删除是异步的：服务端立即返回 Success，但 `doc list` 中可能仍显示该文档（约 30 秒后传播完成）。
+- 输出的是服务端实际删除的 ID 列表，可能与请求的数量不一致（会在 stderr 警告）。
+
+**示例**
+
+```bash
+# 删除单个文档
+kscli doc delete --index-id idx-xxx --doc-id doc-xxx --workspace-id ws-xxx
+
+# 用户明确确认后批量删除
+kscli doc delete --index-id idx-xxx --doc-id doc-a --doc-id doc-b --yes
+```
+
+---
+
+#### `kscli doc tag`
+
+批量更新数据中心文件的标签。
+
+**用法**
+
+```bash
+kscli doc tag --doc-id <id> --tag <text> [flags]
+```
+
+**参数**
+
+| 参数            | 类型   | 必填 | 说明                                                   |
+| --------------- | ------ | ---- | ------------------------------------------------------ |
+| `--doc-id <id>` | array  | 是   | 数据中心文件 ID（可重复，最多 20 个/次）               |
+| `--tag <text>`  | array  | 是   | 标签（可重复），应用到每个 `--doc-id`                  |
+| `--mode <mode>` | string | 否   | 更新模式：`append`（默认，追加）或 `overwrite`（覆盖） |
+
+**参数约束**
+
+- `--doc-id` 最多 20 个/次
+- `--tag` 最多 100 个
+- 每个标签最多 32 字符
+- 标签总长度最多 700 字符
+- `--mode` 只能是 `append` 或 `overwrite`
+
+**输出**
+
+text 模式：
+
+```
+tagged: 2 file(s) with [project-a, draft]
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 同一组标签应用到所有 `--doc-id`；不同标签集需多次执行。
+
+**示例**
+
+```bash
+# 追加标签
+kscli doc tag --doc-id file-xxx --tag project-a --tag draft --workspace-id ws-xxx
+
+# 覆盖标签
+kscli doc tag --doc-id file-a --doc-id file-b --tag final --mode overwrite
+```
+
+---
+
+#### `kscli doc import-oss`
+
+从已授权的 OSS bucket 批量导入文件到数据中心。
+
+**用法**
+
+```bash
+kscli doc import-oss --bucket <name> --region <id> --oss-key <key> [flags]
+```
+
+**参数**
+
+| 参数                 | 类型   | 必填 | 说明                                  |
+| -------------------- | ------ | ---- | ------------------------------------- |
+| `--bucket <name>`    | string | 是   | 已授权的 OSS bucket 名称              |
+| `--region <id>`      | string | 是   | OSS region ID（如 `cn-beijing`）      |
+| `--oss-key <key>`    | array  | 是   | OSS 对象 key（可重复，最多 10 个/次） |
+| `--category-id <id>` | string | 否   | 目标数据中心分类（默认：默认分类）    |
+| `--tag <text>`       | array  | 否   | 文件标签（可重复，最多 10 个）        |
+| `--overwrite`        | switch | 否   | 覆盖之前从相同 OSS key 导入的文件     |
+
+**参数约束**
+
+- `--oss-key` 最多 10 个/次
+- `--tag` 最多 10 个
+
+**输出**
+
+text 模式：
+
+```
+imported: 2 file(s)
+  file-a  SUCCESS  docs/a.pdf
+  file-b  SUCCESS  docs/b.docx
+```
+
+quiet 模式：每行一个 `fileId`。
+
+json 模式：返回 API 原始响应，`data.addFileResultList[]` 包含每个文件的 fileId、status 和 ossKey。
+
+**注意事项**
+
+- bucket 必须事先授权给平台服务角色（RAM 中的 `AliyunServiceRoleForBailian`）。
+- 文件名取自 OSS key 的 basename。
+- `--overwrite` 会替换之前导入的文件并生成**新的 fileId**（旧 fileId 失效）。
+
+**示例**
+
+```bash
+# 导入单个文件
+kscli doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --workspace-id ws-xxx
+
+# 导入多个文件并覆盖
+kscli doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --oss-key docs/b.docx --overwrite
+```
+
+---
+
+← [返回总览](./kscli-cli-guide.md)

docs/kscli/file.md

@@ -0,0 +1,157 @@
+# 数据中心文件管理命令手册
+
+数据中心是知识库文件的存储层。文件通过 `doc upload` 或 `doc import-oss` 进入数据中心，再导入到知识库。数据中心文件可被多个知识库引用。
+
+> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。
+
+---
+
+#### `kscli file list`
+
+列出数据中心分类下的文件。
+
+**用法**
+
+```bash
+kscli file list --category-id <id> [flags]
+```
+
+**参数**
+
+| 参数                   | 类型   | 必填 | 说明                                               |
+| ---------------------- | ------ | ---- | -------------------------------------------------- |
+| `--category-id <id>`   | string | 是   | 分类 ID（通过 `category list` 或 `file get` 获取） |
+| `--name <text>`        | string | 否   | 按文件名过滤                                       |
+| `--file-id <id>`       | array  | 否   | 按文件 ID 过滤（可重复）                           |
+| `--next-token <token>` | string | 否   | 游标分页令牌（从上次输出获取）                     |
+| `--max-result <n>`     | number | 否   | 每页条数                                           |
+
+**输出**
+
+text 模式：
+
+```
+file-xxx  SUCCESS  intro.md  1024
+next: --next-token eyJ...
+```
+
+quiet 模式：每行一个 `fileId`。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- `--category-id` 必须是真实的分类 ID。与上传 API 不同，字面量 `default` 在此不被解析，传入会返回空列表。通过 `file get` 的 category 字段或 `category list` 获取真实 ID。
+- 分页是游标方式：使用输出的 `next: --next-token <token>` 继续翻页。
+
+**示例**
+
+```bash
+# 列出分类下文件
+kscli file list --category-id cate-xxx --workspace-id ws-xxx
+
+# 按名称过滤
+kscli file list --category-id cate-xxx --name report
+
+# 翻页
+kscli file list --category-id cate-xxx --next-token eyJ...
+```
+
+---
+
+#### `kscli file get`
+
+查看数据中心文件详情。
+
+**用法**
+
+```bash
+kscli file get --file-id <id> [flags]
+```
+
+**参数**
+
+| 参数             | 类型   | 必填 | 说明            |
+| ---------------- | ------ | ---- | --------------- |
+| `--file-id <id>` | string | 是   | 数据中心文件 ID |
+
+**输出**
+
+text 模式：
+
+```
+id: file-xxx
+name: intro.md
+type: md
+size: 1024
+status: SUCCESS
+parser: AUTO_SELECT
+category: cate-xxx
+uploaded: 2026-01-01T00:00:00Z
+tags: project-a, draft
+```
+
+quiet 模式：输出 JSON 格式。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 无特殊注意事项。
+
+**示例**
+
+```bash
+# 查看文件详情
+kscli file get --file-id file-xxx --workspace-id ws-xxx
+```
+
+---
+
+#### `kscli file delete`
+
+从数据中心永久删除文件。
+
+**用法**
+
+```bash
+kscli file delete --file-id <id> [flags]
+```
+
+**参数**
+
+| 参数             | 类型   | 必填 | 说明                   |
+| ---------------- | ------ | ---- | ---------------------- |
+| `--file-id <id>` | string | 是   | 数据中心文件 ID        |
+| `--yes`          | switch | 否   | 显式确认执行高风险操作 |
+
+**输出**
+
+text 模式：
+
+```
+deleted: file-xxx
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- **不可逆操作**：如果知识库引用了此文件，相关文档索引会失效。
+- 与 `doc delete` 的区别：`doc delete` 只从单个知识库索引中移除文档，数据中心源文件保留；`file delete` 删除源文件本身，影响所有引用它的知识库。
+
+**示例**
+
+```bash
+# 删除文件（交互确认）
+kscli file delete --file-id file-xxx --workspace-id ws-xxx
+
+# 跳过确认
+kscli file delete --file-id file-xxx --yes
+```
+
+---
+
+← [返回总览](./kscli-cli-guide.md)

docs/kscli/kb.md

@@ -0,0 +1,342 @@
+# 知识库管理命令手册
+
+知识库（Knowledge Base / pipeline / index）是 RAG 的核心载体，存储文档解析后的向量索引。本组命令覆盖知识库的创建、查看、更新、删除和监控。
+
+> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。
+
+---
+
+#### `kscli kb list`
+
+列出工作区中的知识库。
+
+**用法**
+
+```bash
+kscli kb list [flags]
+```
+
+**参数**
+
+| 参数                | 类型   | 必填 | 说明                              |
+| ------------------- | ------ | ---- | --------------------------------- |
+| `--name <text>`     | string | 否   | 按知识库名称模糊过滤（1-20 字符） |
+| `--page-number <n>` | number | 否   | 页码（默认：1）                   |
+| `--page-size <n>`   | number | 否   | 每页条数（默认：20，最大 100）    |
+
+**参数约束**
+
+- `--name` 长度 1-20 字符
+- `--page-size` 范围 1-100
+
+**输出**
+
+text 模式：每行一个知识库，字段以双空格分隔，末尾显示总数。
+
+```
+idx-xxx  my-kb  text-embedding-v4  600  product docs
+total: 1
+```
+
+quiet 模式：每行一个知识库 ID。
+
+json 模式：返回 API 原始响应，`data.rows[]` 包含完整知识库信息。
+
+**注意事项**
+
+- 返回的 `id` 字段作为后续命令的 `--index-id` 使用。
+
+**示例**
+
+```bash
+# 列出所有知识库
+kscli kb list --workspace-id ws-xxx
+
+# 按名称过滤，第二页
+kscli kb list --name demo --page-number 2 --page-size 50
+```
+
+---
+
+#### `kscli kb info`
+
+查看知识库配置详情。
+
+**用法**
+
+```bash
+kscli kb info --index-id <id> [flags]
+```
+
+**参数**
+
+| 参数              | 类型   | 必填 | 说明      |
+| ----------------- | ------ | ---- | --------- |
+| `--index-id <id>` | string | 是   | 知识库 ID |
+
+**输出**
+
+text 模式：按诊断维度分组展示。
+
+```
+Basic:
+  id: idx-xxx
+  name: my-kb
+  description: product docs
+  dataType: ...
+Indexing:   [immutable — recreate required to change]
+  embeddingModelName: text-embedding-v4
+  embeddingDimension: 1024
+  chunkSize: 600
+  overlapSize: ...
+  chunkMode: ...
+  separator: ...
+Retrieval:
+  rerankModelName: ...
+  rerankMinScore: ...
+  rerankTopN: ...
+  rerankMode: ...
+  enableRewrite: ...
+  denseSimilarityTopK: ...
+  sparseSimilarityTopK: ...
+Data:
+  sourceType: ...
+  connectorId: ...
+```
+
+quiet 模式：输出知识库 ID。
+
+json 模式：返回知识库完整配置 JSON。
+
+**注意事项**
+
+- 索引设置（向量模型、切片大小等）不可变，修改需重建知识库。
+
+**示例**
+
+```bash
+# 查看知识库详情
+kscli kb info --index-id idx-xxx --workspace-id ws-xxx
+```
+
+---
+
+#### `kscli kb create`
+
+创建知识库并导入数据中心文件或分类。
+
+**用法**
+
+```bash
+kscli kb create --name <text> --description <text> (--doc-id <id> | --category-id <id>) [flags]
+```
+
+**参数**
+
+| 参数                        | 类型   | 必填 | 说明                                                     |
+| --------------------------- | ------ | ---- | -------------------------------------------------------- |
+| `--name <text>`             | string | 是   | 知识库名称（1-20 字符，工作区内唯一）                    |
+| `--description <text>`      | string | 是   | 知识库装了什么内容、给谁用（1-500 字符）                 |
+| `--doc-id <id>`             | array  | 否¹  | 数据中心文件 ID（可重复）；与 `--category-id` 互斥       |
+| `--category-id <id>`        | array  | 否¹  | 按分类导入该分类下所有文件（可重复）；与 `--doc-id` 互斥 |
+| `--embedding-model <name>`  | string | 否   | 向量模型名称（默认：`text-embedding-v4`）                |
+| `--chunk-size <n>`          | number | 否   | 切片大小，字符数（默认：600，建议 300-800）              |
+| `--wait`                    | switch | 否   | 轮询初始导入任务直到终态                                 |
+| `--poll-interval <seconds>` | number | 否   | 轮询间隔秒数（默认：5）                                  |
+
+> ¹ `--doc-id` 和 `--category-id` 二选一，必须提供其一。
+
+**参数约束**
+
+- `--name` 长度 1-20 字符
+- `--description` 长度 1-500 字符，缺失或超长会在本地被拦截
+- `--doc-id` 和 `--category-id` 互斥，必须提供其一
+
+**输出**
+
+text 模式：
+
+```
+index_id: idx-xxx
+ingestion_id: job-xxx
+status: COMPLETED
+Next: check the import job status, then search against this knowledge base.
+```
+
+quiet 模式：只输出知识库 ID。
+
+json 模式：返回 API 原始响应，包含 `pipelineId`（知识库 ID）和 `ingestionId`（导入任务 ID）。`--wait` 时追加 `final_status` 字段。
+
+**注意事项**
+
+- 结构/存储类型固定为默认文档知识库（非结构化，BUILT_IN 存储）。
+- 返回知识库 ID（`pipelineId`）和初始导入任务 ID（`ingestionId`）。
+- 使用 `doc status` 或 `--wait` 跟踪导入进度。
+- 如果 `--wait` 后部分文档解析失败，CLI 以非零退出码报错，知识库已创建成功的事实会在 hint 中提示。
+
+**示例**
+
+```bash
+# 从指定文件创建知识库
+kscli kb create --name demo --description '产品文档' --doc-id file-xxx --workspace-id ws-xxx
+
+# 从分类导入并等待导入完成
+kscli kb create --name demo --description '产品文档' --category-id cate-xxx --wait
+
+# 指定向量模型和切片大小
+kscli kb create --name my-kb --description '产品文档 v2' --doc-id file-a --doc-id file-b --embedding-model text-embedding-v4 --chunk-size 400 --workspace-id ws-xxx
+```
+
+---
+
+#### `kscli kb update`
+
+更新知识库名称、描述或 rerank 阈值。
+
+**用法**
+
+```bash
+kscli kb update --index-id <id> [flags]
+```
+
+**参数**
+
+| 参数                         | 类型   | 必填 | 说明                                                     |
+| ---------------------------- | ------ | ---- | -------------------------------------------------------- |
+| `--index-id <id>`            | string | 是   | 知识库 ID                                                |
+| `--name <text>`              | string | 否   | 新名称（1-20 字符）                                      |
+| `--description <text>`       | string | 否   | 新描述                                                   |
+| `--rerank-min-score <score>` | number | 否   | rerank 最低分数阈值，范围 0-1（低于此分的 chunk 被过滤） |
+
+**参数约束**
+
+- 至少提供 `--name`、`--description`、`--rerank-min-score` 之一，否则报错 "Nothing to update"
+- `--name` 长度 1-20 字符
+- `--rerank-min-score` 范围 0-1
+
+**输出**
+
+text 模式：
+
+```
+updated: idx-xxx
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 索引设置（向量模型、切片大小等）不可变，修改需重建知识库。
+
+**示例**
+
+```bash
+# 更新描述
+kscli kb update --index-id idx-xxx --description "product docs v2" --workspace-id ws-xxx
+
+# 调整 rerank 阈值
+kscli kb update --index-id idx-xxx --rerank-min-score 0.3
+```
+
+---
+
+#### `kscli kb delete`
+
+删除知识库及其所有文档和 chunk。
+
+**用法**
+
+```bash
+kscli kb delete --index-id <id> [flags]
+```
+
+**参数**
+
+| 参数              | 类型   | 必填 | 说明                   |
+| ----------------- | ------ | ---- | ---------------------- |
+| `--index-id <id>` | string | 是   | 知识库 ID              |
+| `--yes`           | switch | 否   | 显式确认执行高风险操作 |
+
+**输出**
+
+text 模式：
+
+```
+deleted: idx-xxx
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- **不可逆操作**：知识库及所有索引内容被永久删除。
+- 数据中心中的源文件不受影响，仅删除知识库索引。
+- 不带 `--yes` 时，runtime 会在调用知识库业务 API、执行删除前返回确认请求。
+
+**示例**
+
+```bash
+# 删除（交互确认）
+kscli kb delete --index-id idx-xxx --workspace-id ws-xxx
+
+# 跳过确认
+kscli kb delete --index-id idx-xxx --yes
+```
+
+---
+
+#### `kscli kb stats`
+
+查看知识库存储和 QPS 监控数据。
+
+**用法**
+
+```bash
+kscli kb stats --index-id <id> [flags]
+```
+
+**参数**
+
+| 参数              | 类型   | 必填 | 说明                                            |
+| ----------------- | ------ | ---- | ----------------------------------------------- |
+| `--index-id <id>` | string | 是   | 知识库 ID                                       |
+| `--start <time>`  | string | 否   | 范围起始：Unix 秒或 ISO 日期（默认：24 小时前） |
+| `--end <time>`    | string | 否   | 范围结束：Unix 秒或 ISO 日期（默认：当前时间）  |
+
+**输出**
+
+text 模式：
+
+```
+plan: ...
+storage: 100 / 1000
+peak qps: 5
+qps windows: 24 data point(s)
+```
+
+quiet 模式：输出 json 格式。
+
+json 模式：返回 API 原始响应，包含 `storageMonitorData` 和 `qpsMonitorData`。
+
+**注意事项**
+
+- 默认查询最近 24 小时数据。
+- 时间戳自动转换为 epoch 秒（API 要求秒级字符串）。13 位毫秒时间戳会自动降为秒。
+
+**示例**
+
+```bash
+# 查看最近 24 小时监控
+kscli kb stats --index-id idx-xxx --workspace-id ws-xxx
+
+# 指定日期范围
+kscli kb stats --index-id idx-xxx --start 2026-07-30 --end 2026-07-31
+```
+
+---
+
+← [返回总览](./kscli-cli-guide.md)

docs/kscli/kscli-cli-guide.md

@@ -0,0 +1,929 @@
+# `kscli` 命令完整用法指南
+
+> Knowledge Studio CLI（`kscli`）命令总览，覆盖全部 37 个命令：34 个知识库命令 + 3 个配置/维护命令。完整参数与示例请参阅各子域手册。
+
+---
+
+## 目录
+
+1. [概述](#概述)
+2. [核心概念与实体关系](#核心概念与实体关系)
+3. [通用约定](#通用约定)
+4. [典型工作流](#典型工作流)
+5. [命令手册](#命令手册)
+   - [知识库管理](#知识库管理) → [完整手册](kb.md)
+   - [文档管理](#文档管理) → [完整手册](doc.md)
+   - [检索服务管理](#检索服务管理) → [完整手册](service.md)
+   - [Chunk 管理](#chunk-管理) → [完整手册](chunk.md)
+   - [数据中心文件管理](#数据中心文件管理) → [完整手册](file.md)
+   - [数据中心集合与分类](#数据中心集合与分类) → [完整手册](collection-category.md)
+   - [检索与对话](#检索与对话) → [完整手册](search-chat.md)
+   - [配置与维护](#配置与维护)
+6. [常见错误与排查](#常见错误与排查)
+7. [附录：命令速查表](#附录命令速查表)
+
+---
+
+## 概述
+
+`kscli`（`knowledge-studio-cli`）是面向 RAG 开发者的知识库专用 CLI，把知识库能力铺平成一级命令组，覆盖 RAG（检索增强生成）全链路：
+
+- **知识库全生命周期管理**：创建、查看、更新、删除、监控
+- **文档管理**：上传本地文件或目录、从 OSS 批量导入、查看解析状态、删除、打标签
+- **Chunk 级运维**：直接增删改查知识库中的内容切片
+- **检索服务管理**：创建/部署/复制/删除 Q&A 和检索服务（agent），管理 draft 与发布版本
+- **数据中心管理**：文件、集合（connector）、分类的增删查
+- **检索与对话**：语义检索（search）、多轮对话（chat）、兼容旧检索（retrieve）
+- **配置与维护**：查看/修改本地配置、自更新 CLI
+
+共 37 个命令：34 个知识库命令（按功能域分为 7 组）+ `config show` / `config set` / `update`。所有知识库命令均使用 DashScope API Key 鉴权。
+
+> **与 `bl` 的关系**：`kscli` 与 `bl knowledge` 复用同一套命令实现，flag 名、行为逻辑、校验规则完全一致，只有命令路径不同 —— `kscli` 把知识库能力铺平（`kscli kb list`、`kscli file list`），`bl` 则把它们收在 `bl knowledge` 之下。用 `bl` 的读者请参阅 [`bl knowledge` 指南](../knowledge/knowledge-cli-guide.md)。
+
+安装与运行：
+
+```bash
+# 免安装执行（推荐，版本可控）
+npx knowledge-studio-cli@latest --help
+
+# 全局安装后使用 kscli
+npm install -g knowledge-studio-cli
+kscli --help
+```
+
+> 后文示例统一写作 `kscli <command>`；若未全局安装，把 `kscli` 换成 `npx knowledge-studio-cli@latest` 即可。
+
+---
+
+## 核心概念与实体关系
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     数据中心 (Data Center)                    │
+│                                                             │
+│  集合 (Collection) ──┬── 分类 (Category) ── 文件 (File)      │
+│                      │   "connector"        可多级嵌套       │
+│                      └── 默认分类                            │
+│                                                             │
+│  文件来源：doc upload(本地上传) / doc import-oss(OSS导入)     │
+└──────────────────────────┬──────────────────────────────────┘
+                           │ 导入 (import job)
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    知识库 (Knowledge Base)                    │
+│                                                             │
+│  知识库 (KB / pipeline / index)                              │
+│    ├── 文档 (Doc) ── 解析状态: PENDING/RUNNING/COMPLETED     │
+│    │     └── Chunk ── 内容切片，可增删改查、排除/恢复检索     │
+│    └── 索引设置 (immutable): 向量模型、切片大小等             │
+│                                                             │
+│  知识库管理命令: kb create / list / info / update / delete / stats │
+└──────────────────────────┬──────────────────────────────────┘
+                           │ 绑定 (agent_config.kb_search_configs)
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                  检索服务 (Service / Agent)                   │
+│                                                             │
+│  Service (agent)                                            │
+│    ├── scene: chat (Q&A) 或 search (检索)                    │
+│    ├── 版本: beta (草稿) → 1, 2, 3... (已发布)               │
+│    ├── 状态: draft → deployed → edited → deleted            │
+│    └── 配置: 模型、温度、策略、rerank 等                      │
+│                                                             │
+│  消费方式: search (语义检索) / chat (多轮对话)               │
+│  管理命令: create / update / deploy / copy / delete / list / get │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**关键关系**：
+
+- **数据中心文件 → 知识库**：通过 `kscli kb create --doc-id` 或 `kscli doc upload --index-id` 导入，文件解析后自动生成 chunk
+- **知识库 → 检索服务**：一个服务可绑定多个知识库，服务配置中 `kb_search_configs` 指定关联的知识库 ID
+- **检索服务 → 检索/对话**：`kscli search` 和 `kscli chat` 通过 `--agent-id` 指定服务来执行检索或对话
+
+---
+
+## 通用约定
+
+### 鉴权
+
+所有知识库命令均使用 **DashScope API Key**（Bearer token）鉴权。获取方式：百炼控制台 API Key 页面。
+
+优先级（高 → 低）：
+
+1. `--api-key <key>` 命令行参数
+2. `DASHSCOPE_API_KEY` 环境变量
+3. 配置文件中的 `api_key`（`kscli config set --key api_key --value <key>`）
+
+### Workspace ID
+
+知识库 API 使用 workspace 级域名（`{workspaceId}.cn-beijing.maas.aliyuncs.com`），因此 **几乎所有知识库命令都需要 workspace ID**。
+
+优先级（高 → 低）：
+
+1. `--workspace-id <id>` 命令行参数
+2. `BAILIAN_WORKSPACE_ID` 环境变量
+3. 配置文件中的 `workspace_id`（`kscli config set --key workspace_id --value <id>`）
+
+缺失时报错：`Workspace ID is required.`
+
+### 全局通用参数
+
+以下参数在所有知识库命令中通用，后续命令手册中不再逐条列出：
+
+| 参数                  | 类型   | 说明                                                        |
+| --------------------- | ------ | ----------------------------------------------------------- |
+| `--output <format>`   | string | 输出格式：`text`（默认，人类友好）或 `json`（API 原始响应） |
+| `--api-key <key>`     | string | DashScope API Key                                           |
+| `--base-url <url>`    | string | API 基地址（一般不需要指定）                                |
+| `--timeout <seconds>` | number | 请求超时秒数                                                |
+| `--quiet`             | switch | 静默模式，只输出关键结果（如 ID 列表）                      |
+| `--verbose`           | switch | 详细模式，打印 HTTP 请求/响应详情到 stderr                  |
+| `--dry-run`           | switch | 干跑模式，预览将发送的请求结构，不实际调用 API              |
+| `--config <name>`     | string | 使用指定配置 profile 执行命令                               |
+
+> **注意**：命令手册中每个命令的参数表只列出该命令**特有**的参数。上述全局参数对所有命令有效。
+
+### 输出格式约定
+
+- **text 模式**（默认）：人类友好的表格/结构化文本，适合终端查看。不同命令的输出格式见各命令的「输出」部分。
+- **json 模式**（`--output json`）：返回 API 原始 JSON 响应，适合程序化处理和 agent 解析。
+- **quiet 模式**（`--quiet`）：只输出最精简的结果（通常只有 ID），适合管道串联。
+
+### 危险操作确认
+
+涉及删除的命令（`kb delete`、`doc delete`、`chunk delete`、`file delete`、`category delete`、`service delete`）以及 `service deploy` 属于高风险操作。未带 `--yes` 时 CLI 不会执行，也不会弹出交互式 Y/N，而是返回 exit code 7 和 `requires_confirmation`；确认后在原命令中添加 `--yes` 重新执行。
+
+### Dry-run 模式
+
+`--dry-run` 模式下，命令会输出将发送的 endpoint 和 request body，但**不实际发起网络请求**。部分命令在 dry-run 下仍会执行本地校验（如文件扩展名检查、参数约束检查）。
+
+---
+
+## 典型工作流
+
+### 场景 A：从零搭建知识库并检索
+
+```bash
+# 1. 上传本地文件到数据中心
+kscli doc upload --file ./docs/intro.md --workspace-id ws-xxx
+# → 返回 file-id
+
+# 2. 用文件创建知识库
+kscli kb create --name my-kb --description '产品文档' --doc-id file-xxx --workspace-id ws-xxx --wait
+# → 返回 index-id (pipelineId) 和导入任务状态
+
+# 3. 创建检索服务（search 场景）
+kscli service create --name my-search --scene search --index-id idx-xxx --workspace-id ws-xxx
+# → 返回 agent-id
+
+# 4. 部署服务
+kscli service deploy --agent-id aid-xxx --workspace-id ws-xxx --yes
+
+# 5. 执行检索
+kscli search --query "什么是RAG" --agent-id aid-xxx --workspace-id ws-xxx
+```
+
+### 场景 B：上传目录并导入到已有知识库
+
+```bash
+# 1. 上传整个目录到数据中心并直接导入到知识库（一步到位）
+kscli doc upload --file ./docs/ --index-id idx-xxx --workspace-id ws-xxx --wait
+# → 文件逐个上传到 OSS → 注册到数据中心 → 创建合并导入任务 → 轮询到完成
+
+# 2. 检查文档状态
+kscli doc list --index-id idx-xxx --workspace-id ws-xxx
+# → 查看 doc_id 和解析状态
+
+# 3. 如果有文档解析失败，查看导入任务详情
+kscli doc status --index-id idx-xxx --job-id job-xxx --workspace-id ws-xxx
+```
+
+### 场景 C：创建并部署 Q&A 服务
+
+```bash
+# 1. 创建 chat 场景的检索服务
+kscli service create --name my-qa --scene chat --index-id idx-xxx --workspace-id ws-xxx
+# → 初始状态: draft, 版本: beta
+
+# 2. 调整配置（如修改模型、温度）
+kscli service update --agent-id aid-xxx --model qwen-max --temperature 0.7 --workspace-id ws-xxx
+
+# 3. 用 beta 版本测试
+kscli chat --message "什么是RAG?" --agent-id aid-xxx --agent-version beta --workspace-id ws-xxx
+
+# 4. 测试通过后发布
+kscli service deploy --agent-id aid-xxx --version-desc "首版" --workspace-id ws-xxx --yes
+```
+
+### 场景 D：知识库内容运维
+
+```bash
+# 1. 查看 chunk 列表
+kscli chunk list --index-id idx-xxx --workspace-id ws-xxx
+# → 返回 metadata._id (chunk id) 和 metadata.doc_id (document id)
+
+# 2. 修改 chunk 内容
+kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id doc-xxx --content "修正后的内容" --workspace-id ws-xxx
+
+# 3. 排除某个 chunk 不参与检索（不删除内容）
+kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id doc-xxx --exclude --workspace-id ws-xxx
+
+# 4. 手动添加新 chunk
+kscli chunk add --index-id idx-xxx --content "新增的知识片段" --title "补充说明" --workspace-id ws-xxx
+
+# 5. 删除 chunk（批量，自动分批每 10 个一组）
+kscli chunk delete --index-id idx-xxx --chunk-id chunk-a --chunk-id chunk-b --yes --workspace-id ws-xxx
+```
+
+### 场景 E：服务迁移/复用
+
+```bash
+# 1. 复制现有服务为新草稿
+kscli service copy --agent-id aid-source --workspace-id ws-xxx
+# → 返回新的 agent-id，名称加 copy_ 前缀
+
+# 2. 修改新服务配置
+kscli service update --agent-id aid-new --name "改进版" --temperature 0.5 --workspace-id ws-xxx
+
+# 3. 测试并发布
+kscli chat --message "测试" --agent-id aid-new --agent-version beta --workspace-id ws-xxx
+kscli service deploy --agent-id aid-new --workspace-id ws-xxx --yes
+```
+
+### 场景 F：从 OSS 批量导入文件
+
+```bash
+# 1. 从已授权的 OSS bucket 批量导入文件到数据中心
+kscli doc import-oss \
+  --bucket my-bucket --region cn-beijing \
+  --oss-key docs/a.pdf --oss-key docs/b.docx \
+  --workspace-id ws-xxx
+# → 返回各文件的 fileId
+
+# 2. 创建知识库并导入这些文件
+kscli kb create --name oss-kb --description 'OSS 导入文档' --doc-id file-a --doc-id file-b --workspace-id ws-xxx --wait
+
+# 3. 检索
+kscli search --query "相关内容" --agent-id aid-xxx --workspace-id ws-xxx
+```
+
+---
+
+## 命令手册
+
+以下按功能域分组，覆盖全部 37 个命令。每个条目包含功能说明、用法签名和详细手册链接。
+
+> 完整参数表、参数约束、输出说明、注意事项与示例请参阅各子域手册。
+
+---
+
+### 知识库管理
+
+> 📖 [完整手册](kb.md) — 6 个命令
+
+#### `kscli kb list`
+
+列出工作区中的知识库。
+
+```bash
+kscli kb list [flags]
+```
+
+→ [完整参数与示例](kb.md#kscli-kb-list)
+
+---
+
+#### `kscli kb info`
+
+查看知识库配置详情。
+
+```bash
+kscli kb info --index-id <id> [flags]
+```
+
+→ [完整参数与示例](kb.md#kscli-kb-info)
+
+---
+
+#### `kscli kb create`
+
+创建知识库并导入数据中心文件或分类。
+
+```bash
+kscli kb create --name <text> --description <text> (--doc-id <id> | --category-id <id>) [flags]
+```
+
+→ [完整参数与示例](kb.md#kscli-kb-create)
+
+---
+
+#### `kscli kb update`
+
+更新知识库名称、描述或 rerank 阈值。
+
+```bash
+kscli kb update --index-id <id> [flags]
+```
+
+→ [完整参数与示例](kb.md#kscli-kb-update)
+
+---
+
+#### `kscli kb delete`
+
+删除知识库及其所有文档和 chunk。
+
+```bash
+kscli kb delete --index-id <id> [flags]
+```
+
+→ [完整参数与示例](kb.md#kscli-kb-delete)
+
+---
+
+#### `kscli kb stats`
+
+查看知识库存储和 QPS 监控数据。
+
+```bash
+kscli kb stats --index-id <id> [flags]
+```
+
+→ [完整参数与示例](kb.md#kscli-kb-stats)
+
+---
+
+### 文档管理
+
+> 📖 [完整手册](doc.md) — 6 个命令
+
+#### `kscli doc list`
+
+列出知识库中的文档及其解析/索引状态。
+
+```bash
+kscli doc list --index-id <id> [flags]
+```
+
+→ [完整参数与示例](doc.md#kscli-doc-list)
+
+---
+
+#### `kscli doc status`
+
+查看知识库导入任务状态。
+
+```bash
+kscli doc status --index-id <id> --job-id <id> [flags]
+```
+
+→ [完整参数与示例](doc.md#kscli-doc-status)
+
+---
+
+#### `kscli doc upload`
+
+上传本地文件或目录到数据中心，可选导入到知识库。
+
+```bash
+kscli doc upload --file <path> [flags]
+```
+
+→ [完整参数与示例](doc.md#kscli-doc-upload)
+
+---
+
+#### `kscli doc delete`
+
+从知识库中删除文档及其 chunk。
+
+```bash
+kscli doc delete --index-id <id> --doc-id <id> [flags]
+```
+
+→ [完整参数与示例](doc.md#kscli-doc-delete)
+
+---
+
+#### `kscli doc tag`
+
+批量更新数据中心文件的标签。
+
+```bash
+kscli doc tag --doc-id <id> --tag <text> [flags]
+```
+
+→ [完整参数与示例](doc.md#kscli-doc-tag)
+
+---
+
+#### `kscli doc import-oss`
+
+从已授权的 OSS bucket 批量导入文件到数据中心。
+
+```bash
+kscli doc import-oss --bucket <name> --region <id> --oss-key <key> [flags]
+```
+
+→ [完整参数与示例](doc.md#kscli-doc-import-oss)
+
+---
+
+### 检索服务管理
+
+> 📖 [完整手册](service.md) — 7 个命令
+
+#### `kscli service list`
+
+列出工作区中的检索/Q&A 服务。
+
+```bash
+kscli service list --scene <chat|search> [flags]
+```
+
+→ [完整参数与示例](service.md#kscli-service-list)
+
+---
+
+#### `kscli service get`
+
+查看服务详情，含各版本配置。
+
+```bash
+kscli service get --agent-id <id> [flags]
+```
+
+→ [完整参数与示例](service.md#kscli-service-get)
+
+---
+
+#### `kscli service create`
+
+创建检索/Q&A 服务，初始状态为 draft，版本为 beta。
+
+```bash
+kscli service create --name <text> --scene <chat|search> [flags]
+```
+
+→ [完整参数与示例](service.md#kscli-service-create)
+
+---
+
+#### `kscli service update`
+
+更新服务名称、描述或草稿配置。
+
+```bash
+kscli service update --agent-id <id> [flags]
+```
+
+→ [完整参数与示例](service.md#kscli-service-update)
+
+---
+
+#### `kscli service deploy`
+
+发布 beta 草稿为新版本。
+
+```bash
+kscli service deploy --agent-id <id> [flags]
+```
+
+→ [完整参数与示例](service.md#kscli-service-deploy)
+
+---
+
+#### `kscli service delete`
+
+删除检索/Q&A 服务（软删除，幂等）。
+
+```bash
+kscli service delete --agent-id <id> [flags]
+```
+
+→ [完整参数与示例](service.md#kscli-service-delete)
+
+---
+
+#### `kscli service copy`
+
+复制服务为新草稿（名称自动加 `copy_` 前缀）。
+
+```bash
+kscli service copy --agent-id <id> [flags]
+```
+
+→ [完整参数与示例](service.md#kscli-service-copy)
+
+---
+
+### Chunk 管理
+
+> 📖 [完整手册](chunk.md) — 4 个命令
+
+#### `kscli chunk add`
+
+直接向知识库添加 chunk。
+
+```bash
+kscli chunk add --index-id <id> (--content <text> | --field <k=v>) [flags]
+```
+
+→ [完整参数与示例](chunk.md#kscli-chunk-add)
+
+---
+
+#### `kscli chunk list`
+
+列出知识库中的 chunk，含内容和状态。
+
+```bash
+kscli chunk list --index-id <id> [flags]
+```
+
+→ [完整参数与示例](chunk.md#kscli-chunk-list)
+
+---
+
+#### `kscli chunk update`
+
+更新 chunk 内容或切换其检索可见性。
+
+```bash
+kscli chunk update --index-id <id> --chunk-id <id> --doc-id <id> [flags]
+```
+
+→ [完整参数与示例](chunk.md#kscli-chunk-update)
+
+---
+
+#### `kscli chunk delete`
+
+从知识库中删除 chunk（不可逆）。
+
+```bash
+kscli chunk delete --index-id <id> --chunk-id <id> [flags]
+```
+
+→ [完整参数与示例](chunk.md#kscli-chunk-delete)
+
+---
+
+### 数据中心文件管理
+
+> 📖 [完整手册](file.md) — 3 个命令
+
+#### `kscli file list`
+
+列出数据中心分类下的文件。
+
+```bash
+kscli file list --category-id <id> [flags]
+```
+
+→ [完整参数与示例](file.md#kscli-file-list)
+
+---
+
+#### `kscli file get`
+
+查看数据中心文件详情。
+
+```bash
+kscli file get --file-id <id> [flags]
+```
+
+→ [完整参数与示例](file.md#kscli-file-get)
+
+---
+
+#### `kscli file delete`
+
+从数据中心永久删除文件。
+
+```bash
+kscli file delete --file-id <id> [flags]
+```
+
+→ [完整参数与示例](file.md#kscli-file-delete)
+
+---
+
+### 数据中心集合与分类
+
+> 📖 [完整手册](collection-category.md) — 5 个命令
+
+#### `kscli collection create`
+
+创建 FILE 数据集合。
+
+```bash
+kscli collection create --name <text> --description <text> [flags]
+```
+
+→ [完整参数与示例](collection-category.md#kscli-collection-create)
+
+---
+
+#### `kscli collection get`
+
+查看数据集合详情。
+
+```bash
+kscli collection get (--collection-id <id> | --name <text>) [flags]
+```
+
+→ [完整参数与示例](collection-category.md#kscli-collection-get)
+
+---
+
+#### `kscli category list`
+
+列出数据中心分类。
+
+```bash
+kscli category list [flags]
+```
+
+→ [完整参数与示例](collection-category.md#kscli-category-list)
+
+---
+
+#### `kscli category add`
+
+创建数据中心分类。
+
+```bash
+kscli category add --name <text> [flags]
+```
+
+→ [完整参数与示例](collection-category.md#kscli-category-add)
+
+---
+
+#### `kscli category delete`
+
+删除数据中心分类。
+
+```bash
+kscli category delete --category-id <id> [flags]
+```
+
+→ [完整参数与示例](collection-category.md#kscli-category-delete)
+
+---
+
+### 检索与对话
+
+> 📖 [完整手册](search-chat.md) — 3 个命令
+
+#### `kscli retrieve`
+
+从知识库检索（已废弃，请用 `search` 替代）。
+
+```bash
+kscli retrieve --index-id <id> --query <text> [flags]
+```
+
+→ [完整参数与示例](search-chat.md#kscli-retrieve)
+
+---
+
+#### `kscli search`
+
+对知识库执行语义检索（RAG 检索）。
+
+```bash
+kscli search --query <text> --agent-id <id> [flags]
+```
+
+→ [完整参数与示例](search-chat.md#kscli-search)
+
+---
+
+#### `kscli chat`
+
+与知识库进行 RAG 对话（流式输出）。
+
+```bash
+kscli chat --message <text> --agent-id <id> [flags]
+```
+
+→ [完整参数与示例](search-chat.md#kscli-chat)
+
+---
+
+### 配置与维护
+
+这 3 个命令不调用知识库 API，用于管理本地配置与 CLI 自身版本。配置文件默认位于 `~/.bailian/config.json`（可用 `BAILIAN_CONFIG_DIR` 改写目录）。
+
+#### `kscli config show`
+
+显示当前生效配置（含 base_url、output、timeout、profile 名和配置文件路径；密钥类字段自动脱敏）。
+
+```bash
+kscli config show [--output json]
+```
+
+示例：
+
+```bash
+# 查看当前配置
+kscli config show
+
+# JSON 输出，便于脚本解析
+kscli config show --output json
+```
+
+---
+
+#### `kscli config set`
+
+写入一个配置项到配置文件。
+
+```bash
+kscli config set --key <key> --value <value>
+```
+
+| 参数              | 类型   | 必填 | 说明                                                                                                                                                                                        |
+| ----------------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--key <key>`     | string | 是   | 配置项名称：`language`、`base_url`、`output`、`output_dir`、`timeout`、`api_key`、`access_token`、`access_key_id`、`access_key_secret`、`security_token`、`default_*_model`、`workspace_id` |
+| `--value <value>` | string | 是   | 要写入的值（按 key 类型校验并转换）                                                                                                                                                         |
+
+示例：
+
+```bash
+# 持久化 API Key
+kscli config set --key api_key --value sk-xxx
+
+# 持久化 workspace，省去每次传 --workspace-id
+kscli config set --key workspace_id --value ws-xxx
+
+# 默认输出 JSON
+kscli config set --key output --value json
+```
+
+**注意事项**
+
+- `--dry-run` 只打印将写入的键值和配置文件路径，不落盘。
+- 密钥类字段（`api_key`、`access_token` 等）在回显时被掩码。
+- 配合 `--config <name>` 可写入指定 profile。
+
+---
+
+#### `kscli update`
+
+将 CLI 自更新到最新版本，或用 `--to` 指定目标版本。
+
+```bash
+kscli update [--to <version>]
+```
+
+| 参数             | 类型   | 必填 | 说明                                                                      |
+| ---------------- | ------ | ---- | ------------------------------------------------------------------------- |
+| `--to <version>` | string | 否   | 目标版本（semver，如 `1.13.0` / `v1.13.0` / `0.0.0-beta-<sha>-<时间戳>`） |
+
+示例：
+
+```bash
+# 更新到最新版
+kscli update
+
+# 回滚/固定到指定版本
+kscli update --to 1.13.0
+```
+
+**注意事项**
+
+- 更新方式按安装来源自动选择（npm 全局安装或二进制安装）。
+- `--to` 传入非法 semver 会在本地被拦截并报错。
+
+---
+
+## 常见错误与排查
+
+### Workspace ID 缺失
+
+**报错**：`Workspace ID is required.`
+
+**原因**：所有知识库管理命令都需要 workspace ID 来构造 API 端点（`{workspaceId}.cn-beijing.maas.aliyuncs.com`）。
+
+**解决**：
+
+```bash
+# 方式1：命令行参数
+kscli kb list --workspace-id ws-xxx
+
+# 方式2：环境变量
+export BAILIAN_WORKSPACE_ID=ws-xxx
+
+# 方式3：配置文件
+kscli config set --key workspace_id --value ws-xxx
+```
+
+### 知识库 ID 不存在
+
+**报错**：`Knowledge base not found: idx-xxx`
+
+**原因**：`--index-id` 指定的知识库在当前 workspace 中不存在。
+
+**解决**：先 `kscli kb list` 确认知识库 ID。
+
+### 导入任务 SystemError
+
+**报错**：服务端返回 `SystemError`
+
+**原因**：`doc status` 传入了不存在的 job ID，或知识库空闲无任务。
+
+**解决**：检查 `doc list` 输出中的 `ingestionId`，或从 `doc upload` / `kb create` 的返回值获取。
+
+### doc_id 与 fileId 混淆
+
+**问题**：`doc delete` 时用了 `doc upload` 返回的 `fileId` 而非 `doc list` 返回的 `doc_id`。
+
+**原因**：通过 `kb create --doc-id` 导入的文档，`doc_id` 等于 `fileId`；但通过 `doc upload --index-id` 导入的，`doc_id` 可能含 workspace 后缀。
+
+**解决**：始终用 `kscli doc list --quiet` 获取 `doc_id`。
+
+### retrieve 已废弃
+
+**问题**：`retrieve` 命令输出废弃警告。
+
+**解决**：改用 `search` 命令。`search` 通过 `--agent-id` 驱动检索策略，支持多知识库、路由、rerank 等高级特性。`retrieve` 直接操作 `--index-id`，功能受限且不再迭代。
+
+### OSS 导入权限错误
+
+**报错**：服务端返回权限相关错误。
+
+**原因**：OSS bucket 未授权给平台服务角色。
+
+**解决**：检查 RAM 控制台中的 `AliyunServiceRoleForBailian` 角色是否已正确授权。
+
+### Chat SSE error
+
+**报错**：`Chat API error` + API error code。
+
+**原因**：流式对话过程中服务端返回 error 事件。
+
+**解决**：检查 `--agent-id` 是否存在、服务是否已部署、API Key 是否有效。错误消息和 code 原样透传，不二次包装。
+
+### file list 返回空
+
+**问题**：`file list --category-id default` 返回空列表。
+
+**原因**：与上传 API 不同，`file list` 不解析字面量 `default`，需要真实分类 ID。
+
+**解决**：通过 `file get` 的 category 字段或 `category list` 获取真实分类 ID。
+
+### 集合无法删除
+
+**问题**：没有 `collection delete` 命令。
+
+**原因**：暂不支持通过 CLI 删除。
+
+**解决**：创建集合需谨慎。如需隔离，创建新集合并迁移文件。
+
+---
+
+## 附录：命令速查表
+
+| 命令                      | 功能         | 关键参数                                                    |
+| ------------------------- | ------------ | ----------------------------------------------------------- |
+| `kscli kb list`           | 列出知识库   | `--name`                                                    |
+| `kscli kb info`           | 知识库详情   | `--index-id`                                                |
+| `kscli kb create`         | 创建知识库   | `--name`, `--description`, `--doc-id`/`--category-id`       |
+| `kscli kb update`         | 更新知识库   | `--index-id`, `--name`/`--description`/`--rerank-min-score` |
+| `kscli kb delete`         | 删除知识库   | `--index-id`, `--yes`                                       |
+| `kscli kb stats`          | 监控数据     | `--index-id`, `--start`/`--end`                             |
+| `kscli doc list`          | 文档列表     | `--index-id`                                                |
+| `kscli doc status`        | 导入任务状态 | `--index-id`, `--job-id`, `--wait`                          |
+| `kscli doc upload`        | 上传文件     | `--file`, `--index-id`, `--wait`                            |
+| `kscli doc delete`        | 删除文档     | `--index-id`, `--doc-id`                                    |
+| `kscli doc tag`           | 文件打标签   | `--doc-id`, `--tag`, `--mode`                               |
+| `kscli doc import-oss`    | OSS 导入     | `--bucket`, `--region`, `--oss-key`                         |
+| `kscli service list`      | 服务列表     | `--scene`                                                   |
+| `kscli service get`       | 服务详情     | `--agent-id`                                                |
+| `kscli service create`    | 创建服务     | `--name`, `--scene`, `--index-id`                           |
+| `kscli service update`    | 更新服务     | `--agent-id`, 配置参数                                      |
+| `kscli service deploy`    | 发布服务     | `--agent-id`, `--yes`                                       |
+| `kscli service delete`    | 删除服务     | `--agent-id`, `--yes`                                       |
+| `kscli service copy`      | 复制服务     | `--agent-id`                                                |
+| `kscli chunk add`         | 添加 chunk   | `--index-id`, `--content`/`--field`                         |
+| `kscli chunk list`        | chunk 列表   | `--index-id`, `--doc-id`                                    |
+| `kscli chunk update`      | 更新 chunk   | `--index-id`, `--chunk-id`, `--doc-id`                      |
+| `kscli chunk delete`      | 删除 chunk   | `--index-id`, `--chunk-id`, `--yes`                         |
+| `kscli file list`         | 文件列表     | `--category-id`                                             |
+| `kscli file get`          | 文件详情     | `--file-id`                                                 |
+| `kscli file delete`       | 删除文件     | `--file-id`, `--yes`                                        |
+| `kscli collection create` | 创建集合     | `--name`, `--description`                                   |
+| `kscli collection get`    | 集合详情     | `--collection-id`/`--name`                                  |
+| `kscli category list`     | 分类列表     | `--collection-id`, `--parent-id`                            |
+| `kscli category add`      | 创建分类     | `--name`, `--parent-id`                                     |
+| `kscli category delete`   | 删除分类     | `--category-id`, `--yes`                                    |
+| `kscli retrieve`          | 检索（废弃） | `--index-id`, `--query`                                     |
+| `kscli search`            | 语义检索     | `--query`, `--agent-id`                                     |
+| `kscli chat`              | RAG 对话     | `--message`, `--agent-id`                                   |
+| `kscli config show`       | 查看配置     | `--output`                                                  |
+| `kscli config set`        | 写入配置     | `--key`, `--value`                                          |
+| `kscli update`            | 自更新 CLI   | `--to`                                                      |

docs/kscli/search-chat.md

@@ -0,0 +1,218 @@
+# 检索与对话命令手册
+
+以下命令通过检索服务（agent）消费知识库。`search` 用于语义检索，`chat` 用于多轮对话。`retrieve` 已废弃。
+
+> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。
+
+---
+
+#### `kscli retrieve`
+
+从知识库检索（已废弃，请用 `search` 替代）。
+
+**用法**
+
+```bash
+kscli retrieve --index-id <id> --query <text> [flags]
+```
+
+**参数**
+
+| 参数                            | 类型   | 必填 | 说明                                                |
+| ------------------------------- | ------ | ---- | --------------------------------------------------- |
+| `--index-id <id>`               | string | 是   | 知识库 ID                                           |
+| `--query <text>`                | string | 是   | 检索查询文本                                        |
+| `--dense-similarity-top-k <n>`  | number | 否   | 稠密检索 top K                                      |
+| `--sparse-similarity-top-k <n>` | number | 否   | 稀疏检索 top K                                      |
+| `--rerank`                      | switch | 否   | 启用 rerank                                         |
+| `--rerank-top-n <n>`            | number | 否   | rerank 返回 top N 结果                              |
+| `--rerank-model <name>`         | string | 否   | rerank 模型名，如 `qwen3-rerank-hybrid`             |
+| `--rerank-mode <mode>`          | string | 否   | rerank 模式：`qa`、`similar` 或 `custom`            |
+| `--rerank-instruct <text>`      | string | 否   | 自定义 rerank 指令（`--rerank-mode custom` 时使用） |
+| `--top-k <n>`                   | number | 否   | 返回结果数（已废弃，用 `--rerank-top-n` 替代）      |
+
+**输出**
+
+text/quiet 模式：
+
+```
+[1] (score: 0.9512)
+检索到的文本内容...
+
+[2] (score: 0.8734)
+另一段文本内容...
+```
+
+> 无结果时输出 `No results found.`
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- **已废弃**，推荐使用 `search` 命令。`search` 通过 agent_id 驱动检索策略，支持更多高级特性。
+- `--top-k` 已废弃，使用 `--rerank-top-n` 替代，传入 `--top-k` 会输出 stderr 警告。
+- 此命令直接用 `--index-id` 检索，不需要创建检索服务。
+
+**示例**
+
+```bash
+# 基础检索
+kscli retrieve --index-id idx-xxx --query "How to use Alibaba Cloud Bailian" --workspace-id ws-xxx
+
+# 启用 rerank
+kscli retrieve --index-id idx-xxx --query "RAG retrieval" --rerank --rerank-model qwen3-rerank-hybrid
+```
+
+---
+
+#### `kscli search`
+
+对知识库执行语义检索（RAG 检索）。
+
+**用法**
+
+```bash
+kscli search --query <text> --agent-id <id> [flags]
+```
+
+**参数**
+
+| 参数                        | 类型   | 必填 | 说明                                                                |
+| --------------------------- | ------ | ---- | ------------------------------------------------------------------- |
+| `--query <text>`            | string | 是   | 检索查询文本（不可为空）                                            |
+| `--agent-id <id>`           | string | 是   | 检索服务 ID（在控制台知识检索页面获取，或通过 `service list` 查看） |
+| `--agent-version <version>` | string | 否   | 服务版本：`beta`（调试草稿）或已发布版本号；默认调用最新已发布版本  |
+| `--image <url>`             | array  | 否   | 图片 URL（可重复），用于多模态检索                                  |
+
+**参数约束**
+
+- `--query` 不可为空（API 要求 `minLength: 1`）
+
+**输出**
+
+text/quiet 模式：
+
+```
+[1] (score: 0.9512)
+检索到的文本内容...
+
+[2] (score: 0.8734)
+另一段文本内容...
+```
+
+> 无结果时输出 `No results found.`
+
+json 模式：返回 API 原始响应，`data.nodes[]` 包含检索结果。
+
+**注意事项**
+
+- 检索范围和策略（多知识库加权、路由、rerank 等）由 `--agent-id` 对应的服务配置驱动。只需 `--query` 和 `--agent-id` 即可调用。
+- `--agent-version beta` 调试草稿配置进行调试，部署前验证效果。
+- 与 `retrieve` 的区别：`search` 通过 agent_id 间接驱动检索策略（支持多知识库、路由、rerank 等），`retrieve` 直接操作 index_id 且功能较少。
+
+**示例**
+
+```bash
+# 基础检索
+kscli search --query "What is RAG?" --agent-id aid-xxx --workspace-id ws-xxx
+
+# 多模态检索（带图片）
+kscli search --query "describe this image" --agent-id aid-xxx --workspace-id ws-xxx --image https://example.com/img.jpg
+
+# 调试草稿版本
+kscli search --query "test" --agent-id aid-xxx --agent-version beta --workspace-id ws-xxx
+```
+
+---
+
+#### `kscli chat`
+
+与知识库进行 RAG 对话（流式输出）。
+
+**用法**
+
+```bash
+kscli chat --message <text> --agent-id <id> [flags]
+```
+
+**参数**
+
+| 参数                        | 类型   | 必填 | 说明                                                                                                                           |
+| --------------------------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `--message <text>`          | array  | 是¹  | 消息文本（可重复）。支持 `role:content` 前缀设置角色（如 `user:hello`），默认角色为 `user`。也支持完整 JSON 对象传递结构化消息 |
+| `--agent-id <id>`           | string | 是   | Q&A 服务 ID（在控制台知识问答页面获取，或通过 `service list --scene chat` 查看）                                               |
+| `--agent-version <version>` | string | 否   | 服务版本：`beta`（调试草稿）或已发布版本号；默认调用最新已发布版本                                                             |
+| `--image <url>`             | array  | 否   | 图片 URL（可重复）。附加到最后一条 user 消息作为多模态内容                                                                     |
+
+> ¹ `--message` 或 `--image` 至少提供其一。纯图片查询可以只传 `--image`（CLI 会自动创建空 user 消息承载图片）。
+
+**参数约束**
+
+- `--message` 或 `--image` 至少提供一个
+- `--image` 不能与已包含 `image_url` 内容部分的消息同时使用
+
+**输出**
+
+**TTY text 模式**（实时流式）：
+
+```
+🔍 Retrieving...
+✍️ Generating...
+这是AI生成的回答内容，逐字流式输出...
+```
+
+> 进度标签由 SSE `step_change` 事件驱动：`tool_calling`（检索中）→ `plan_start`（规划中）→ `generation_start`（生成中）。
+
+**非 TTY text 模式**（缓冲输出）：
+
+```
+完整的回答文本...
+```
+
+**json 模式**（`--output json`）：
+
+```json
+{
+  "answer": "完整的回答文本...",
+  "request_id": "xxx"
+}
+```
+
+quiet 模式：输出完整的回答文本。
+
+**注意事项**
+
+- API 仅支持 SSE 流式响应。TTY 环境下实时打印 token；非 TTY 环境缓冲后输出完整文本。
+- SSE 事件生命周期：`tool_calling` → `tool_return` → `plan_start` → `planning` → `plan_end` → `generation_start` → `generating` → `generation_end`。`tool_calling` → `tool_return` 可能循环多次。
+- 多轮对话：用 `--message "user:..."` 和 `--message "assistant:..."` 传递对话历史。
+- `--agent-version beta` 调用草稿配置进行调试。
+- `--image` 附加到最后一条 user 消息上。如果消息中已包含 `image_url` 内容部分，则不能再用 `--image`。
+- `--verbose` 模式下，所有 SSE 事件详情会输出到 stderr。
+
+**示例**
+
+```bash
+# 单轮对话
+kscli chat --message "What is RAG?" --agent-id aid-xxx --workspace-id ws-xxx
+
+# 多轮对话（带历史）
+kscli chat \
+  --message "user:What is RAG?" \
+  --message "assistant:RAG is retrieval-augmented generation..." \
+  --message "How does it work?" \
+  --agent-id aid-xxx --workspace-id ws-xxx
+
+# 多模态对话（带图片）
+kscli chat \
+  --message "Describe these images" \
+  --image https://example.com/a.png \
+  --image https://example.com/b.png \
+  --agent-id aid-xxx --workspace-id ws-xxx
+
+# 调试草稿版本
+kscli chat --message "test" --agent-id aid-xxx --agent-version beta --workspace-id ws-xxx
+```
+
+---
+
+← [返回总览](./kscli-cli-guide.md)

docs/kscli/service.md

@@ -0,0 +1,401 @@
+# 检索服务管理命令手册
+
+检索服务（也称 agent）是知识库的检索入口。通过 `--agent-id` 在 search/chat 命令中使用。服务有 `chat`（问答）和 `search`（检索）两种场景。
+
+> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。
+
+---
+
+#### `kscli service list`
+
+列出工作区中的检索/Q&A 服务。
+
+**用法**
+
+```bash
+kscli service list --scene <chat|search> [flags]
+```
+
+**参数**
+
+| 参数                     | 类型   | 必填 | 说明                                                    |
+| ------------------------ | ------ | ---- | ------------------------------------------------------- |
+| `--scene <chat\|search>` | string | 是   | 服务场景：`chat`（Q&A）或 `search`（检索）              |
+| `--status <status>`      | string | 否   | 按状态过滤：`draft`、`deployed`（含 edited）、`deleted` |
+| `--name <text>`          | string | 否   | 按服务名称模糊过滤                                      |
+| `--agent-id <id>`        | string | 否   | 按精确 agent ID 过滤                                    |
+| `--index-id <id>`        | string | 否   | 按关联知识库 ID 过滤                                    |
+| `--page-number <n>`      | number | 否   | 页码（默认：1）                                         |
+| `--page-size <n>`        | number | 否   | 每页条数（默认：10，最大 100）                          |
+
+**参数约束**
+
+- `--scene` 只能是 `chat` 或 `search`
+- `--status` 只能是 `draft`、`deployed`、`deleted`
+- `--page-size` 范围 1-100
+
+**输出**
+
+text 模式：
+
+```
+aid-xxx  deployed  2  my-qa  (kb: my-kb)
+total: 1
+Use an agent_id above with the chat command.
+```
+
+> 最后一行根据 scene 自动提示用 `search` 还是 `chat` 命令消费。
+
+quiet 模式：每行一个 `agent_id`。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 服务端要求 `--scene` 必填，要查看两种场景的服务需分别执行。
+
+**示例**
+
+```bash
+# 列出 chat 服务
+kscli service list --scene chat --workspace-id ws-xxx
+
+# 只看已部署的检索服务
+kscli service list --scene search --status deployed
+```
+
+---
+
+#### `kscli service get`
+
+查看服务详情，含各版本配置。
+
+**用法**
+
+```bash
+kscli service get --agent-id <id> [flags]
+```
+
+**参数**
+
+| 参数                        | 类型   | 必填 | 说明                                                      |
+| --------------------------- | ------ | ---- | --------------------------------------------------------- |
+| `--agent-id <id>`           | string | 是   | 服务（agent）ID                                           |
+| `--agent-version <version>` | string | 否   | 指定版本查看（`beta` 或已发布版本号）；不传则返回所有版本 |
+
+**输出**
+
+text 模式：
+
+```
+Basic:
+  id: aid-xxx
+  name: my-qa
+  desc: product Q&A
+  scene: chat
+  status: deployed
+Version beta:
+  desc: draft
+  policy: turbo
+  model: qwen-max
+  temperature: 0.7
+  kb: idx-xxx (my-kb)
+Version 1:
+  published: 2026-01-01
+  ...
+```
+
+quiet 模式：输出 JSON 格式。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 不传 `--agent-version` 时返回所有版本（beta 草稿 + 已发布版本号）。
+- 版本值原样传递，有效值集合由服务端维护。
+
+**示例**
+
+```bash
+# 查看服务完整详情
+kscli service get --agent-id aid-xxx --workspace-id ws-xxx
+
+# 只看 beta 草稿配置
+kscli service get --agent-id aid-xxx --agent-version beta
+```
+
+---
+
+#### `kscli service create`
+
+创建检索/Q&A 服务，初始状态为 draft，版本为 beta。
+
+**用法**
+
+```bash
+kscli service create --name <text> --scene <chat|search> [flags]
+```
+
+**参数**
+
+| 参数                     | 类型   | 必填 | 说明                                              |
+| ------------------------ | ------ | ---- | ------------------------------------------------- |
+| `--name <text>`          | string | 是   | 服务名称（最多 200 字符，同一场景下工作区内唯一） |
+| `--scene <chat\|search>` | string | 是   | 服务场景：`chat`（Q&A）或 `search`（检索）        |
+| `--description <text>`   | string | 建议 | 这个服务能回答什么、给谁用（最多 1000 字符）      |
+| `--index-id <id>`        | string | 否   | 绑定此知识库；其他配置使用服务端默认值            |
+
+**参数约束**
+
+- `--name` 最多 200 字符
+- `--scene` 只能是 `chat` 或 `search`
+- `--description` 最多 1000 字符；建议填写 —— agent 靠它判断该调用哪个服务
+
+**输出**
+
+text 模式：
+
+```
+created: aid-xxx  (status: draft, version: beta)
+Test the draft with --agent-version beta on search/chat, then deploy it to publish.
+```
+
+quiet 模式：输出 agent ID。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 不指定 `--index-id` 时，服务端使用默认 agent 配置。
+- beta 草稿可通过 search/chat 的 `--agent-version beta` 测试，部署后才生效。
+- 需要工作区的知识库创建权限。
+
+**示例**
+
+```bash
+# 创建 Q&A 服务
+kscli service create --name my-qa --scene chat --workspace-id ws-xxx
+
+# 创建检索服务并绑定知识库
+kscli service create --name my-search --scene search --index-id idx-xxx
+```
+
+---
+
+#### `kscli service update`
+
+更新服务名称、描述或草稿配置。
+
+**用法**
+
+```bash
+kscli service update --agent-id <id> [flags]
+```
+
+**参数**
+
+| 参数                           | 类型   | 必填 | 说明                                                                                     |
+| ------------------------------ | ------ | ---- | ---------------------------------------------------------------------------------------- |
+| `--agent-id <id>`              | string | 是   | 服务（agent）ID                                                                          |
+| `--name <text>`                | string | 否   | 新名称（最多 200 字符）                                                                  |
+| `--description <text>`         | string | 否   | 新描述（最多 1000 字符）                                                                 |
+| `--agent-version <version>`    | string | 否   | 目标版本（默认：beta 草稿。已发布版本只接受 `--version-desc`）                           |
+| `--version-desc <text>`        | string | 否   | 版本描述                                                                                 |
+| `--policy <policy>`            | string | 否   | Agent 策略：`turbo`（快速）或 `agentic`（多轮）                                          |
+| `--model <name>`               | string | 否   | 生成模型代码（须在平台白名单中）                                                         |
+| `--temperature <n>`            | number | 否   | 采样温度，范围 0-2                                                                       |
+| `--max-llm-calls <n>`          | number | 否   | 单次请求最大 LLM 调用次数，范围 1-30                                                     |
+| `--enable-session-file <bool>` | string | 否   | 启用会话文件：`true` 或 `false`                                                          |
+| `--enable-refusal <bool>`      | string | 否   | 启用拒答：`true` 或 `false`                                                              |
+| `--enable-anti-leak <bool>`    | string | 否   | 启用防泄漏：`true` 或 `false`                                                            |
+| `--enable-rich-text <bool>`    | string | 否   | 启用富文本输出：`true` 或 `false`                                                        |
+| `--enable-citation <bool>`     | string | 否   | 启用引用标注：`true` 或 `false`                                                          |
+| `--config-file <path>`         | string | 否   | JSON 文件替换整个 `agent_config`（含嵌套设置如 `kb_search_configs`）；与标量配置参数互斥 |
+
+**参数约束**
+
+- 至少提供一个更新项（`--name`/`--description`/`--version-desc`/`--config-file`/标量配置参数），否则报错 "Nothing to update"
+- `--config-file` 与标量配置参数（`--policy`/`--model`/`--temperature` 等）互斥
+- 已发布版本 + 配置变更 → 报错（已发布版本只接受 `--version-desc`）
+- `--name` 最多 200 字符；`--description` 最多 1000 字符
+- `--policy` 只能是 `turbo` 或 `agentic`
+- `--temperature` 范围 0-2
+- `--max-llm-calls` 范围 1-30
+- 布尔参数（`--enable-*`）只能是 `true` 或 `false`
+
+**输出**
+
+text 模式：
+
+```
+updated: aid-xxx
+Draft config changed — verify with --agent-version beta, then deploy.
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 配置变更只作用于 beta 草稿；已发布版本只接受 `--version-desc`。
+- 标量配置参数采用 read-merge-write：CLI 先读取当前 beta 配置，再合并变更后整体提交（API 是整替换语义）。
+- `--config-file` 替换整个配置，适合设置嵌套字段（如 `kb_search_configs`）。
+- 修改草稿后用 `--agent-version beta` 在 search/chat 上测试，通过后 `service deploy` 发布。
+
+**示例**
+
+```bash
+# 调整温度
+kscli service update --agent-id aid-xxx --temperature 0.7 --workspace-id ws-xxx
+
+# 用 JSON 文件替换整个配置
+kscli service update --agent-id aid-xxx --config-file ./agent-config.json
+
+# 给已发布版本 1 加描述
+kscli service update --agent-id aid-xxx --agent-version 1 --version-desc "first stable release"
+```
+
+---
+
+#### `kscli service deploy`
+
+发布 beta 草稿为新版本。
+
+**用法**
+
+```bash
+kscli service deploy --agent-id <id> [flags]
+```
+
+**参数**
+
+| 参数                    | 类型   | 必填 | 说明                   |
+| ----------------------- | ------ | ---- | ---------------------- |
+| `--agent-id <id>`       | string | 是   | 服务（agent）ID        |
+| `--version-desc <text>` | string | 否   | 新版本的描述说明       |
+| `--yes`                 | switch | 否   | 显式确认执行高风险操作 |
+
+**输出**
+
+text 模式：
+
+```
+deployed: aid-xxx  version 2
+```
+
+quiet 模式：输出新版本号。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 版本号自动递增，状态变为 `deployed`。
+- 发布影响线上调用方，确认提示会警告。
+- 如果当前状态为 `edited`（已发布后又改了草稿），确认提示会额外警告「发布会覆盖线上行为」。
+- 需要工作区的知识库修改权限。
+
+**示例**
+
+```bash
+# 发布（交互确认）
+kscli service deploy --agent-id aid-xxx --workspace-id ws-xxx
+
+# 带描述并跳过确认
+kscli service deploy --agent-id aid-xxx --version-desc "tuned rerank params" --yes
+```
+
+---
+
+#### `kscli service delete`
+
+删除检索/Q&A 服务（软删除，幂等）。
+
+**用法**
+
+```bash
+kscli service delete --agent-id <id> [flags]
+```
+
+**参数**
+
+| 参数              | 类型   | 必填 | 说明                   |
+| ----------------- | ------ | ---- | ---------------------- |
+| `--agent-id <id>` | string | 是   | 服务（agent）ID        |
+| `--yes`           | switch | 否   | 显式确认执行高风险操作 |
+
+**输出**
+
+text 模式：
+
+```
+deleted: aid-xxx  (status: deleted)
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 删除不可撤销，`agent_id` 不再可用于 search/chat 调用。
+- API 是幂等的：删除已删除的服务不会报错。
+- 如果服务状态为 `deployed` 或 `edited`，确认提示会额外警告「此服务正在线上运行」。
+- 需要工作区的知识库删除权限。
+
+**示例**
+
+```bash
+# 删除（交互确认）
+kscli service delete --agent-id aid-xxx --workspace-id ws-xxx
+
+# 跳过确认
+kscli service delete --agent-id aid-xxx --yes
+```
+
+---
+
+#### `kscli service copy`
+
+复制服务为新草稿（名称自动加 `copy_` 前缀）。
+
+**用法**
+
+```bash
+kscli service copy --agent-id <id> [flags]
+```
+
+**参数**
+
+| 参数              | 类型   | 必填 | 说明              |
+| ----------------- | ------ | ---- | ----------------- |
+| `--agent-id <id>` | string | 是   | 源服务（agent）ID |
+
+**输出**
+
+text 模式：
+
+```
+new agent_id: aid-new  (name: copy_my-qa, status: draft)
+Test the draft with --agent-version beta on search/chat, then deploy it to publish.
+```
+
+quiet 模式：输出新 agent ID。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 副本初始为 beta 草稿，测试后需 deploy 发布。
+- 需要工作区的知识库创建权限。
+
+**示例**
+
+```bash
+# 复制服务
+kscli service copy --agent-id aid-source --workspace-id ws-xxx
+```
+
+---
+
+← [返回总览](./kscli-cli-guide.md)

docs/token-plan-profile-integration.md

@@ -1,565 +0,0 @@
-# Token Plan Profile 与激活配置接入方案
-
-> 状态：Token Plan 模型消费、Config 激活状态与通用 Base URL 归一化均已实现。
->
-> 目标分支：`feat/cli-access-token`。
-
-## 结论摘要
-
-Token Plan 的模型消费能力继续使用现有 `apiKey` 鉴权域和模型 Client，不新增 Token Plan 鉴权模式或专用 Client。
-
-本次接入拆为三类相互独立的能力，并按业务紧急度而不是最终调用链顺序交付：
-
-1. 优先完成 `token-plan` 内置 Profile 预设、登录和文本/图片消费。
-2. 然后完成 Config 激活状态，允许用户选择未传 `--config` 时默认使用的命名配置。
-3. 最后以独立 commit 完成通用模型 Base URL 归一化，覆盖所有输入来源，不只服务 Token Plan。
-
-`token-plan` 是有默认值的内置 Profile 名，不是 `active_auth_mode`，也不是新的 `AuthRequirement`。
-
-## 背景与边界
-
-当前分支已经包含以下 Token Plan 管控命令：
-
-```text
-token-plan list-seats
-token-plan create-key
-token-plan assign-seats
-token-plan add-member
-```
-
-这些命令属于管理面，继续使用 OpenAPI AK/SK。本方案增加的是模型消费面：用户把 `create-key` 获得的 `PlainApiKey` 保存到 Profile，然后通过现有文本和图片命令调用模型。
-
-```text
-OpenAPI AK/SK
-  -> token-plan create-key
-  -> PlainApiKey
-  -> auth login --config token-plan
-  -> text/image model command
-```
-
-### 目标
-
-- 将 Token Plan 模型 API Key 作为普通 `apiKey` credential 使用。
-- 将 `token-plan` 作为内置命名 Profile 管理。
-- 支持 Config 激活状态和默认切换。
-- 复用现有文本、图片命令与 Client。
-- 对所有来源的模型 Base URL 做统一归一化。
-- 登录验证成功后原子保存 API Key 和 Base URL。
-- 服务端错误保持原消息，不在 CLI 内翻译。
-
-### 非目标
-
-- 不重写现有 Token Plan 管控命令。
-- 不把模型消费 API Key 合并到 OpenAPI AK/SK 鉴权域。
-- 不新增 Token Plan 专用 Client。
-- 基础阶段不承诺视频、语音和音频模型消费。
-- 暂不维护会阻断请求的本地模型白名单。
-- 暂不把服务端错误翻译成 CLI 自定义错误。
-
-## 用户交互
-
-### 1. 配置 Token Plan
-
-`token-plan` 提供默认 Base URL，因此推荐登录命令不要求用户输入地址：
-
-```sh
-bl auth login \
-  --config token-plan \
-  --api-key sk-sp-xxx
-```
-
-CLI 应解析并保存以下配置：
-
-```json
-{
-  "active_config": "token-plan",
-  "token-plan": {
-    "api_key": "<TOKEN_PLAN_API_KEY>",
-    "base_url": "https://token-plan.cn-beijing.maas.aliyuncs.com",
-    "default_text_model": "qwen3.7-max",
-    "default_image_model": "qwen-image-2.0"
-  }
-}
-```
-
-凭证验证和配置落盘成功后，CLI 在同一次配置文件写入中将 `token-plan` 设为激活项；验证失败和
-dry-run 不创建、不切换 Profile。
-
-用户仍可显式覆盖 Base URL，用于代理、测试或未来新增地域：
-
-```sh
-bl auth login \
-  --config token-plan \
-  --api-key sk-sp-xxx \
-  --base-url https://proxy.example.com/bailian/compatible-mode/v1
-```
-
-显式地址归一化后应保存为：
-
-```text
-https://proxy.example.com/bailian
-```
-
-推荐路径仍是不传 `--base-url`，直接使用 `token-plan` 预设中的 canonical 根地址。显式覆盖时可以传服务根地址、自定义代理前缀，或带 `/compatible-mode/v1`、`/apps/anthropic` 的 SDK Base URL；CLI 会在验证和落盘前统一归一化。
-
-### 2. 单次选择 Config
-
-`--config` 只影响当前命令，不修改激活状态：
-
-```sh
-bl text chat --config token-plan --message "你好"
-bl image generate --config token-plan --prompt "一只猫"
-```
-
-### 3. 激活 Config
-
-登录时显式选择的 Profile 会自动激活；之后也可以主动切换：
-
-```sh
-bl config use --name token-plan
-```
-
-激活后，未传 `--config` 的命令默认使用 `token-plan`：
-
-```sh
-bl text chat --message "你好"
-bl image generate --prompt "一只猫"
-```
-
-切回顶层默认配置：
-
-```sh
-bl config use --name default
-```
-
-单次绕过当前激活项、临时使用其他 Profile：
-
-```sh
-bl text chat --config staging --message "你好"
-```
-
-单次显式使用顶层默认配置：
-
-```sh
-bl text chat --config default --message "你好"
-```
-
-上述两种单次覆盖都不得改变持久化的激活状态。
-
-### 4. 查看 Config
-
-新增列表能力，用于展示所有 Profile 和当前激活项：
-
-```sh
-bl config list
-```
-
-示例输出：
-
-```text
-NAME         ACTIVE
-default
-staging
-token-plan   *
-```
-
-`config show` 和 `auth status` 的行为：
-
-- 未传 `--config`：展示当前激活的 Config。
-- 传 `--config <name>`：展示指定 Config，不改变激活状态。
-- 输出中包含最终选择的 `config` 和 `config_file`；激活状态统一由 `config list` / `config ui` 展示。
-
-`config ui` 应展示当前激活项，并提供激活操作。
-
-## Config 激活状态设计
-
-### 存储形状
-
-激活状态保存在 `~/.bailian/config.json` 顶层元数据中：
-
-```json
-{
-  "active_config": "token-plan",
-  "api_key": "<DEFAULT_API_KEY>",
-  "token-plan": {
-    "api_key": "<TOKEN_PLAN_API_KEY>",
-    "base_url": "https://token-plan.cn-beijing.maas.aliyuncs.com"
-  }
-}
-```
-
-`active_config` 只允许出现在顶层，不属于单个 Profile 的业务字段。允许值为：
-
-- `default`：顶层默认配置。
-- 一个实际存在的命名 Profile。
-
-旧配置没有 `active_config` 时等价于：
-
-```json
-{
-  "active_config": "default"
-}
-```
-
-因此该能力对现有用户向后兼容。
-
-### 选择优先级
-
-Config block 的选择顺序为：
-
-```text
-显式 --config <name>
-  > active_config
-  > default
-```
-
-需要保留“参数是否出现”的信息：
-
-- 未传 `--config`：读取 `active_config`。
-- `--config default`：明确选择顶层配置，不能被 `active_config` 替换。
-- `--config <name>`：明确选择该命名 Profile。
-
-当前 `normalizeConfigName("default")` 会返回 `undefined`，实现时不能只根据归一化结果判断参数是否出现。
-
-Config 激活只改变配置文件 block 的选择，`--config` 本身不提升所选 block 的字段优先级。运行时和 Base URL 登录验证保持“具体字段 flag > 环境变量 > selected config file > Profile 预设或系统默认值”。环境变量只影响本次有效值，不复制进 Profile；登录成功时，如果 Token Plan Profile 尚未保存 `base_url`，仍物化写入官方预设地址。Token Plan 默认模型是例外：每次登录都重置为内置版本。`config show` / `auth status` 应展示最终生效来源，避免用户误判套餐流量去向。
-
-### 异常状态
-
-- 激活不存在的 Profile：`config use` 返回 usage error，不写入状态。
-- 配置文件中的 `active_config` 指向不存在的 Profile：命令失败并提示切回 `default`，不得静默使用其他凭证。
-- 删除当前激活的 Profile：删除操作同时切回 `default`，或者要求用户先切换；不能保留悬空引用。
-- `config use --name token-plan` 只切换状态，不创建 Profile，也不执行登录。
-- `auth login --config token-plan` 在凭证验证并落盘成功后自动激活该 Profile；验证失败和
-  dry-run 不创建、不切换。
-
-## `token-plan` 内置 Profile 预设
-
-`token-plan` 是允许用户选择的内置 Profile 名，不应加入非法名称列表。它提供以下默认值：
-
-```text
-base_url:           https://token-plan.cn-beijing.maas.aliyuncs.com
-default_text_model: qwen3.7-max
-default_image_model: qwen-image-2.0
-```
-
-Token Plan Base URL 预设只在登录写入阶段提供最低优先级的缺省值：
-
-```text
-显式命令参数
-  > 环境变量
-  > 已保存的 Profile 字段
-  > token-plan 预设值
-```
-
-登录成功时应把显式 Base URL 或缺失的预设 Base URL，以及默认模型写入 Profile，使 `config show --config token-plan` 能看到完整配置。环境变量不复制进 Profile。运行时不再合并预设；如果手工删除字段，则按统一的环境变量、配置文件和系统默认值链继续解析。
-
-默认模型采用更简单的固定策略：每次执行 `auth login --config token-plan`，都将 `default_text_model` 重置为 `qwen3.7-max`，将 `default_image_model` 重置为 `qwen-image-2.0`。登录不保留用户之前写入的其他 Profile 默认模型；用户需要临时调用其他 Token Plan 模型时，通过具体模型命令的 `--model` 覆盖，不修改这两个内置默认值。
-
-预设建议通过集中 registry 表达，不在 resolver、命令和 Client 中散落名称判断：
-
-```ts
-const MODEL_PROFILE_PRESETS = {
-  "token-plan": {
-    baseUrl: "https://token-plan.cn-beijing.maas.aliyuncs.com",
-    defaultTextModel: "qwen3.7-max",
-    defaultImageModel: "qwen-image-2.0",
-  },
-};
-```
-
-Profile 预设不改变命令协议：
-
-```text
-Selected Profile
-  -> API Key Credential
-  -> Client
-  -> Command Endpoint
-```
-
-## 通用模型 Base URL 归一化
-
-Base URL 归一化是独立的通用能力，不针对 Token Plan hostname 做特判。
-
-### 语义
-
-CLI 中 `base_url` 表示模型服务根地址或自定义网关前缀，不包含 CLI 已知的 SDK/API Base 后缀。
-
-建议新增统一函数：
-
-```text
-normalizeModelBaseUrl(input) -> canonical base URL
-```
-
-通用规则：
-
-1. 去除首尾空白。
-2. 使用 `URL` 解析，只接受 `http:` 和 `https:`。
-3. 去除 query 和 fragment。
-4. 去除末尾 `/`。
-5. 保留协议、hostname、端口和自定义代理路径。
-6. 去除末尾已知 SDK/API Base 后缀，例如：
-   - `/compatible-mode/v1`
-   - `/apps/anthropic`
-7. 不无条件返回 `url.origin`，避免破坏自定义代理路径。
-
-示例：
-
-| 用户输入                                                             | 归一化结果                                        |
-| -------------------------------------------------------------------- | ------------------------------------------------- |
-| `https://dashscope.aliyuncs.com/`                                    | `https://dashscope.aliyuncs.com`                  |
-| `https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1` | `https://token-plan.cn-beijing.maas.aliyuncs.com` |
-| `https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic`     | `https://token-plan.cn-beijing.maas.aliyuncs.com` |
-| `https://proxy.example.com/bailian/`                                 | `https://proxy.example.com/bailian`               |
-| `https://proxy.example.com/bailian/compatible-mode/v1`               | `https://proxy.example.com/bailian`               |
-
-### 覆盖入口
-
-所有模型 Base URL 来源都必须经过同一个函数：
-
-- 模型命令的 `--base-url`。
-- `DASHSCOPE_BASE_URL`。
-- `config.json` 中的 `base_url`。
-- `config set --key base_url`。
-- `config ui`。
-- `auth login --base-url`。
-- Console 登录回调返回的 `base_url`。
-- 手工修改的旧配置。
-- 内置默认地址和 Profile 预设地址。
-
-归一化采用双层防线：
-
-- 写入前归一化，保证磁盘配置整洁。
-- `resolveModelBaseUrl()` 返回前防御性归一化，兼容旧配置和手工修改。
-
-### URL 拼接
-
-归一化后，命令继续拼接已有 endpoint：
-
-```text
-text:  <base_url>/compatible-mode/v1/chat/completions
-image: <base_url>/api/v1/services/aigc/.../generation
-```
-
-最终 URL 中不得重复出现 `/compatible-mode/v1`。
-
-## API Key 登录与原子保存
-
-当前登录流程可能先写入 `base_url`，再验证 API Key。该顺序需要独立修复：
-
-```text
-解析 Profile 和预设
-  -> 归一化 Base URL
-  -> 使用最终 Base URL 验证 API Key
-  -> 验证成功后一次写入 api_key + base_url + 默认模型
-```
-
-验证失败时，不得产生以下半配置状态：
-
-```json
-{
-  "token-plan": {
-    "base_url": "https://token-plan.cn-beijing.maas.aliyuncs.com"
-  }
-}
-```
-
-登录验证使用的模型必须在目标 Profile 中可用。基础阶段 Token Plan 预设使用 `qwen3.7-max`；后续如不同订阅计划的模型集合分化，应将验证模型纳入 Profile 预设，而不是继续在登录函数里硬编码唯一模型。
-
-## 模型消费范围
-
-基础阶段承诺：
-
-| 能力           | 默认模型         | 调用方式                           |
-| -------------- | ---------------- | ---------------------------------- |
-| 文本生成和推理 | `qwen3.7-max`    | OpenAI Compatible Chat Completions |
-| 图片生成和编辑 | `qwen-image-2.0` | DashScope 原生图片接口             |
-
-Token Plan 当前模型快照中还包含其他文本、视觉理解和图片模型，但该列表可能由后端调整。基础接入不维护阻断请求的本地白名单；用户可通过具体模型命令的 `--model` 临时覆盖本次请求，但再次登录时 Profile 默认模型仍重置为内置版本。
-
-视频、语音和音频不作为本阶段支持承诺。现有命令仍保持通用实现，但 Token Plan Profile 的验收不包含这些模态。
-
-## 错误处理
-
-CLI 继续遵循“服务端错误消息原样透传”的规则。
-
-例如服务端返回：
-
-```json
-{
-  "code": "InvalidParameter",
-  "message": "Model not exist."
-}
-```
-
-CLI 保留 `Model not exist.`，不改写成“Token Plan 不支持该模态”，因为本地没有权威、实时的模型开放列表。
-
-## Commit 拆分
-
-以下 commit 按紧急度和必要依赖提交，每个 commit 都应能独立通过对应测试和静态检查。前三个 commit 组成可优先交付的 Token Plan 模型消费 MVP，后两个 commit 再补齐默认激活体验和通用 URL 输入兼容。
-
-### Commit 1：Token Plan 内置 Profile 预设（已实现）
-
-建议提交信息：
-
-```text
-feat(core): add token-plan model profile preset
-```
-
-完成内容：
-
-- 将 `token-plan` 注册为内置、可选择的 Profile 名。
-- 提供 canonical 默认 Base URL、文本模型和图片模型。
-- Base URL 登录验证遵循 flag > 环境变量 > 已保存 Profile > 预设；环境变量不复制进 Profile。
-- Profile 缺少 Base URL 时物化预设地址；每次 Token Plan 登录都重置并写入内置默认文本和图片模型。
-- 运行时 loader/resolver 不再合并预设。
-- 不新增 AuthRequirement，不修改 Token Plan 管控命令。
-- 补充预设值单元测试；不重复增加 Token Plan 专属消费 E2E。
-- 不依赖通用 Base URL 归一化；预设直接使用规范化后的根地址。
-
-### Commit 2：Token Plan API Key 登录（已实现）
-
-建议提交信息：
-
-```text
-feat(auth): support token-plan API key login
-```
-
-完成内容：
-
-- 支持 `bl auth login --config token-plan --api-key ...`。
-- 未传 `--base-url` 且没有更高优先级的环境变量或已保存地址时，使用 Token Plan Profile 预设地址。
-- 使用 Token Plan 预设文本模型验证 API Key。
-- 登录验证前不写配置。
-- 验证成功后一次写入 API Key、canonical Base URL 和默认模型。
-- 每次登录都将默认模型重置为 `qwen3.7-max` 和 `qwen-image-2.0`。
-- 验证失败不留下半配置。
-- 补充一个最小 Token Plan 登录 E2E，覆盖命名 Profile 落盘、环境变量不复制、预设 Base URL 物化和默认模型重置；通用 API Key 登录 E2E 继续覆盖成功原子保存和失败不写半配置。
-- 该 commit 暂不承诺自动归一化用户显式输入的 SDK Base URL。
-
-### Commit 3：Token Plan 文本与图片消费验收（已实现）
-
-建议提交信息：
-
-```text
-feat(cli): enable token-plan text and image consumption
-```
-
-完成内容：
-
-- Token Plan 消费复用现有 API Key、文本和图片调用链，不重复增加专属 E2E。
-- 发布前按需人工验证 `auth login --config token-plan --api-key ...`、文本和图片调用。
-- 更新 Token Plan 消费方案文档和 Skill reference。
-- 到该 commit 为止即可先交付显式 `--config token-plan` 的紧急消费能力。
-
-### 运营文档 TODO
-
-- [ ] 由运营同事补充 `README.md` 和 `README.zh.md` 的 Token Plan 模型消费说明。
-- [ ] 区分 `sk-sp-...` 模型消费 API Key 与管控命令使用的 OpenAPI AK/SK。
-- [ ] 增加 `auth login --config token-plan --api-key ...`、文本消费和图片消费示例。
-- [ ] 与届时实际上线范围核对模型名称、服务地域、限制条件和用户措辞。
-
-### Commit 4：Config 激活状态与切换命令（已实现）
-
-建议提交信息：
-
-```text
-feat(config): add active profile selection
-```
-
-完成内容：
-
-- 增加顶层 `active_config` 元数据。
-- 实现 `--config > active_config > default` 的选择顺序。
-- 保证 `--config default` 能显式覆盖激活项。
-- 新增 `bl config list`。
-- 新增 `bl config use --name <name>`。
-- `config show`、`auth status` 展示最终选择项，`config list` 和 `config ui` 展示激活状态。
-- 删除激活 Profile 时处理状态一致性。
-- 验证激活 `token-plan` 后不传 `--config` 的文本和图片请求。
-- 验证临时 `--config default` 不改变激活状态。
-- 更新命令导出、`packages/cli/src/commands.ts`、E2E 和生成 reference。
-
-实现选择：删除当前激活的命名 Profile 时，在同一次配置文件写入中将 `active_config` 重置为
-`default`。普通命令的显式 `--config` 仍只作用于本次命令；`auth login --config <name>` 是
-例外，在凭证验证和落盘成功的同一次配置写入中激活目标 Profile。`--config default` 登录成功后
-切回默认配置。
-
-相关写入交互统一为：`auth login`、`auth logout` 和 `config set` 未传 `--config` 时作用于当前激活项；显式指定名称时作用于该名称。写命令可在成功落盘时创建不存在的 Profile，读命令不创建。Console access token 自动刷新同样限定在当前选中的 Profile，不得回退读写顶层 default。
-
-激活项选择的是完整 Config，而不是只选择模型消费凭证。激活 `token-plan` 后，Token Plan 管控命令也会从该 Profile 解析 OpenAPI AK/SK，Console 命令也会从该 Profile 解析 Console 凭证。如果相应凭证仍保存在顶层 `default`，用户需要为单次命令显式传入 `--config default`，或将对应凭证域登录到 `token-plan`；CLI 不为不同鉴权域做隐式跨 Profile 回退。
-
-### Commit 5：通用模型 Base URL 归一化（已实现）
-
-建议提交信息：
-
-```text
-fix(core): normalize model base URLs across all sources
-```
-
-完成内容：
-
-- 新增 `normalizeModelBaseUrl()`。
-- 保留自定义网关路径，去除尾斜杠、query、fragment 和已知 API Base 后缀。
-- `resolveModelBaseUrl()` 对 flag、env、配置文件和默认值统一归一化。
-- `auth login`、Console callback、`config set`、`config ui` 写入前归一化。
-- 验证 Token Plan 显式输入 `/compatible-mode/v1` 和 `/apps/anthropic` 的兼容行为。
-- 补充通用 URL 单元测试和各来源解析测试。
-- 更新 README、中文 README、Skill reference 和本方案状态。
-
-## 验证清单
-
-### Base URL
-
-- 根地址和自定义路径正确保留。
-- 尾部 `/` 被移除。
-- `/compatible-mode/v1` 和 `/apps/anthropic` 后缀被移除。
-- query 和 fragment 不进入最终请求地址。
-- flag、env、配置文件和所有写入入口结果一致。
-- 最终文本 URL 只包含一次 `/compatible-mode/v1`。
-
-### Config 激活
-
-- 旧配置缺少 `active_config` 时继续使用 `default`。
-- `config use` 只能激活存在的 Profile。
-- 未传 `--config` 时使用激活项。
-- 显式 `--config` 优先且不修改激活项。
-- `--config default` 能绕过命名激活项。
-- 悬空激活项不会静默回退到其他凭证。
-- 删除激活项后状态保持一致。
-- `config list/show/ui` 正确标识激活项。
-
-### Token Plan
-
-- `token-plan` 登录初始化时缺省写入官方根地址。
-- 显式 Base URL 覆盖预设并经过通用归一化。
-- 登录验证失败不写入任何 Token Plan 半配置。
-- 文本默认使用 `qwen3.7-max`。
-- 图片默认使用 `qwen-image-2.0`。
-- 文本和图片均复用现有 `apiKey` Client。
-- 管控命令继续使用 OpenAPI AK/SK，不受模型 Profile 影响。
-
-## 完成后检查
-
-```sh
-pnpm run sync:skill-assets
-vp check
-vp test
-```
-
-“Profile 预设与激活状态”的维护要求已沉淀到 `docs/agents/config-profile-change.md`。
-
-## 最终结论
-
-Token Plan 模型消费最终表现为一个可激活的内置 Profile：
-
-```text
-通用 Base URL 归一化
-  -> Config 选择与激活
-  -> 登录时物化 token-plan 预设
-  -> 普通 apiKey Client
-  -> 文本/图片 endpoint
-```
-
-用户执行 `auth login --config token-plan` 成功后，该 Profile 会成为默认激活配置；仍可通过
-显式 `--config` 做单次覆盖，或使用 `bl config use --name <name>` 主动切换。整个过程不引入
-Token Plan 模式，也不复制现有模型调用实现。

package.json

@@ -21,10 +21,12 @@
     "bl": "pnpm -F bailian-cli dev",
     "kscli": "pnpm -F knowledge-studio-cli dev",
     "test": "vp test",
+    "test:journey": "vp test packages/commands/tests/e2e/knowledge/journeys",
     "release:check": "node tools/release/check.mjs",
     "wiki:crawl": "node tools/wiki-crawler/index.mjs",
     "test:stress": "node packages/cli/tests/stress/run.mjs"
   },
+  "dependencies": {},
   "devDependencies": {
     "tsx": "catalog:",
     "vite-plus": "catalog:"

packages/bailian-kb-dsh/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Aliyun Model Studio (DashScope) AI Platform
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

packages/bailian-kb-dsh/README.md

@@ -0,0 +1,159 @@
+<div align="center">
+
+# Bailian Knowledge Base for DeepSeek Harness
+
+**Knowledge-base retrieval tools for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), backed by Aliyun Model Studio (Bailian).**
+
+[![npm version](https://img.shields.io/npm/v/bailian-kb-dsh?color=0969da&label=npm)](https://www.npmjs.com/package/bailian-kb-dsh)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22.12-brightgreen)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)](https://www.typescriptlang.org)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+
+[Bailian Console](https://bailian.console.aliyun.com/) · [中文文档](README.zh.md) · [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) · [API Documentation](https://help.aliyun.com/zh/model-studio/)
+
+</div>
+
+## 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](https://bailian.console.aliyun.com/) (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](https://www.npmjs.com/package/bailian-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](https://bailian.console.aliyun.com/?tab=app#/api-key))
+- At least one **deployed** retrieval or Q&A service in that workspace — create one in the [console](https://bailian.console.aliyun.com/) or with `bl knowledge service create` / `bl knowledge service deploy`
+- The [`bl` CLI](https://www.npmjs.com/package/bailian-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
+
+```sh
+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:
+
+```sh
+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
+
+```sh
+# ~/.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):
+
+```yaml
+- 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
+
+```sh
+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):
+
+```sh
+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](https://github.com/modelstudioai/cli/blob/main/docs/kb-dsh/runtime-behavior.md); the maintenance checklist is [docs/agents/dsh-plugin.md](https://github.com/modelstudioai/cli/blob/main/docs/agents/dsh-plugin.md).
+
+## Contributing
+
+Bug reports, feature requests, and PRs are welcome. See [CONTRIBUTING.md](https://github.com/modelstudioai/cli/blob/main/CONTRIBUTING.md) for developer setup and the contribution workflow.
+
+## License
+
+[Apache 2.0](LICENSE)

packages/bailian-kb-dsh/README.zh.md

@@ -0,0 +1,159 @@
+<div align="center">
+
+# 百炼知识库 for DeepSeek Harness
+
+**基于阿里云百炼（Aliyun Model Studio）的知识库检索工具，供 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 使用。**
+
+[![npm version](https://img.shields.io/npm/v/bailian-kb-dsh?color=0969da&label=npm)](https://www.npmjs.com/package/bailian-kb-dsh)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22.12-brightgreen)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)](https://www.typescriptlang.org)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+
+[百炼控制台](https://bailian.console.aliyun.com/) · [English](README.md) · [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) · [API 文档](https://help.aliyun.com/zh/model-studio/)
+
+</div>
+
+## 这是什么？
+
+`bailian-kb-dsh` 是一个 DeepSeek Harness 插件（同时是 dsh bundle），让 agent 能检索托管在[阿里云百炼](https://bailian.console.aliyun.com/)上的知识库。它注册两个面向模型的工具 —— `kb_search` 取原始证据、`kb_chat` 出成品答案 —— 并附带一个设置页和一份面向 [`bl` CLI](https://www.npmjs.com/package/bailian-cli) 的管理 skill。
+
+检索经由你在百炼上部署的**检索服务**完成：一个服务把一个或多个知识库绑定到指定的向量 / 排序配置上，通过 `agent_id` 寻址。插件会把已部署服务的清单持续呈现给模型，让它能判断用户的问题是否落在你的知识范围内。
+
+## 功能特性
+
+- **两个面向模型的工具** — `kb_search` 返回带分数和来源的知识切片；`kb_chat` 返回基于知识的完整答案
+- **服务感知** — 工作空间里已部署的检索服务会注入到会话上下文，模型据此知道自己能查什么，不必猜 `agent_id`
+- **低门槛配置** — 在设置页登录百炼控制台即可自动填入 API 密钥与工作空间 ID；已有的 `bl` CLI 登录会被自动采纳
+- **设置页** — Web UI 中的"百炼知识库"页，管理凭据、默认服务，并可查看服务缓存状态
+- **管理 skill** — 随包分发的 `bailian-kb` skill，教 agent 用 `bl` CLI 完成建库、文档导入、服务部署
+
+## 环境要求
+
+- DeepSeek Harness 及其插件运行时（`@deepseek-ai/dsh-*`），Node.js >= 22.12
+- 阿里云百炼账号：一个**工作空间 ID** 和一个 **DashScope API 密钥**（[去获取](https://bailian.console.aliyun.com/?tab=app#/api-key)）
+- 该工作空间下至少有一个**已部署**的检索或问答服务 —— 可在[控制台](https://bailian.console.aliyun.com/)创建，或用 `bl knowledge service create` / `bl knowledge service deploy`
+- 管理面的事（建库、导入文档、部署服务）需要 [`bl` CLI](https://www.npmjs.com/package/bailian-cli)（`npm install -g bailian-cli`）。检索本身直连 API、从不起子进程，所以 `kb_search` / `kb_chat` 不装也能用
+
+## 安装
+
+```sh
+dsh plugin --profile web add bailian-kb-dsh
+```
+
+CLI 会自动把 bundle 加入 profile 的层栈，无需手改 YAML。卸载：
+
+```sh
+dsh plugin --profile web remove bailian-kb-dsh
+```
+
+验证插件已装配：`dsh --profile web --dump-config` 应能看到 `tool-bailian-kb` row。
+
+## 配置
+
+### 方式一 — 设置页（推荐）
+
+安装后，Web UI 的 **Settings → 百炼知识库** 页出现：
+
+- **自动获取** — 在宿主机浏览器中拉起百炼控制台登录；登录完成后，该账号的 API 密钥与工作空间 ID 直接落到宿主机（明文密钥不经过浏览器）。每次登录都会请求签发新密钥，因此切换账号点一次即可。
+- **API 密钥** — 只写不回显：存下的值不会再次显示，只显示"已配置 / 未配置"。
+- **工作空间 ID / 默认检索服务 / 默认对话服务** — 可编辑且回显；两个服务 ID 可从缓存的服务清单里选。清空保存则回退到下层来源。
+- **检索服务缓存** — 展示注入清单的上次拉取时间、各场景服务条数、是否被截断，并提供手动刷新（刚新建完服务想立刻生效时用）。
+
+如果此前已运行过 `bl auth login`，启动时会从 `~/.bailian/config.json` 一次性采纳 API 密钥与工作空间 ID。被你主动清空的值不会被重新填回。
+
+### 方式二 — 环境变量与凭据文件
+
+```sh
+# ~/.dsh/.env，或凭据存储 ~/.dsh/.credentials.yaml
+DASHSCOPE_API_KEY=sk-xxx                    # 必填
+BAILIAN_WORKSPACE_ID=ws-xxx                 # 必填
+BAILIAN_DEFAULT_RETRIEVE_AGENT_ID=aid-xxx   # 选填
+BAILIAN_DEFAULT_CHAT_AGENT_ID=aid-xxx       # 选填
+```
+
+### 方式三 — Profile patch
+
+bundle 会向 profile 插入自己的 entry，你可以在 `~/.dsh/cordis.patch.yml` 或 profile 的 patch 文件里按 id 覆盖。覆盖时**替换整个 config 对象（无 deep-merge）**：
+
+```yaml
+- id: tool-bailian-kb
+  config:
+    defaultRetrieveAgentId: aid-search-service
+    defaultChatAgentId: aid-chat-service
+    chatTimeoutMs: 600000
+```
+
+禁用插件：`- id: tool-bailian-kb` 加 `disabled: true`。
+
+### 配置字段
+
+Config 同时注册为 `bailian-kb` settings section，因此在设置页或设置文档里的修改会在下一次调用生效，无需重启。
+
+| 字段                     | 类型    | 默认值                         | 语义                                                                              |
+| ------------------------ | ------- | ------------------------------ | --------------------------------------------------------------------------------- |
+| `workspaceId`            | string? | —                              | 百炼工作空间 ID；API host 为工作空间子域名 `https://<workspaceId>.<endpointHost>` |
+| `endpointHost`           | string  | `cn-beijing.maas.aliyuncs.com` | host 后缀，其他 region 或私有化部署时替换                                         |
+| `defaultRetrieveAgentId` | string? | —                              | 调用方省略 `agent_id` 时 `kb_search` 使用的服务                                   |
+| `defaultChatAgentId`     | string? | —                              | 调用方省略 `agent_id` 时 `kb_chat` 使用的服务                                     |
+| `agentVersion`           | string? | —                              | `beta`（草稿调试）或已发布版本号；默认调用最新发布版本。不暴露给模型              |
+| `chatTimeoutMs`          | number  | `300000`                       | `kb_chat` 超时时间 —— 服务端是分钟级的多轮检索循环                                |
+
+### 解析优先级
+
+| 值                  | settings 用户层（设置页）   | entry config（profile patch） | 凭据存储 / 环境变量                 |
+| ------------------- | --------------------------- | ----------------------------- | ----------------------------------- |
+| `DASHSCOPE_API_KEY` | 只写控件                    | —                             | `DASHSCOPE_API_KEY`                 |
+| 工作空间 ID         | ✅ `workspaceId`            | ✅ `workspaceId`              | `BAILIAN_WORKSPACE_ID`              |
+| 默认检索服务        | ✅ `defaultRetrieveAgentId` | ✅ `defaultRetrieveAgentId`   | `BAILIAN_DEFAULT_RETRIEVE_AGENT_ID` |
+| 默认对话服务        | ✅ `defaultChatAgentId`     | ✅ `defaultChatAgentId`       | `BAILIAN_DEFAULT_CHAT_AGENT_ID`     |
+
+所有值每次调用重新解析，因此轮换密钥或切换工作空间即时生效。API 密钥与工作空间 ID 是必填项：缺失时工具调用会报错并指出上述配置路径。默认服务是选填的 —— 当某个场景下工作空间只有一个已部署服务时，直接用它。
+
+## 工具
+
+| 工具        | 参数                                                                                     | 返回                           |
+| ----------- | ---------------------------------------------------------------------------------------- | ------------------------------ |
+| `kb_search` | `query`、`agent_id`（必填）、`top_k?`（默认 5，客户端截断）、`images?`（多模态图片 URL） | 带来源引用的评分切片，以及总数 |
+| `kb_chat`   | `message`、`agent_id`（必填）                                                            | 完整答案，以及 `request_id`    |
+
+两个工具的 schema 中 `agent_id` 均为必填：schema 无法告诉模型这套部署是否配了默认服务，而"调用时才发现没有默认值"会白费一轮。配置的默认服务仍对省略该参数的程序化调用生效。
+
+已部署服务的清单（ID、名称、场景）以上下文消息的形式注入会话，周期性刷新，`bl knowledge service` 命令改动服务清单时也会刷新。清单过长时会截断并注明总数，避免模型把部分清单当成全部。
+
+## 错误处理
+
+- **HTTP 4xx** — 多数情况是 `agent_id` 已失效，因此会刷新服务清单并追加到错误信息里，便于立即纠正
+- **HTTP 5xx** — 原样透传
+- **凭据缺失** — 错误信息指出配置路径（`~/.dsh/.env`、`~/.dsh/.credentials.yaml`、设置页）并给出控制台取密钥的链接
+- **`kb_chat` 超时** — 错误信息说明服务端多轮检索的特性，建议重试或改用 `kb_search`
+
+## 已知限制
+
+- `kb_chat` 会缓冲服务端流式输出，执行期间没有进展显示。
+- `top_k` 是客户端截断：请求体不含该参数，服务端返回多少切片由检索服务配置决定。
+- **服务名承载了路由信号。** 服务列表接口目前不返回描述字段，模型只能靠服务名判断一个服务能查什么。请按内容命名（`产品文档检索`，而不是`检索服务1`）。
+- 每个场景最多拉取两页，超出时注入的清单会标明已截断。
+
+## 开发
+
+```sh
+pnpm --filter bailian-kb-dsh run build       # tsc 出 dist/（node 半）+ tsdown 出 dist/web/client.js（浏览器半）
+pnpm --filter bailian-kb-dsh run typecheck   # node 与 web 两套 tsconfig
+pnpm --filter bailian-kb-dsh run test
+```
+
+本地联调时把工作副本装进 dev profile（patch 文件受 HMR 监听）：
+
+```sh
+dsh plugin --profile dev add <本仓库>/packages/bailian-kb-dsh
+```
+
+内部设计说明（上下文注入策略、服务缓存布局、刷新触发点）见 [docs/kb-dsh/runtime-behavior.md](https://github.com/modelstudioai/cli/blob/main/docs/kb-dsh/runtime-behavior.md)；维护清单见 [docs/agents/dsh-plugin.md](https://github.com/modelstudioai/cli/blob/main/docs/agents/dsh-plugin.md)。
+
+## 参与贡献
+
+欢迎提交 Bug 报告、功能建议和 PR。开发环境搭建与贡献流程见 [CONTRIBUTING.md](https://github.com/modelstudioai/cli/blob/main/CONTRIBUTING.md)。
+
+## 许可证
+
+[Apache 2.0](LICENSE)

packages/bailian-kb-dsh/cordis.patch.yml

@@ -0,0 +1,13 @@
+# bailian-kb-dsh: inserts the Bailian knowledge-base consumer over dsh-base.
+# 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 defaultRetrieveAgentId
+# via BAILIAN_DEFAULT_RETRIEVE_AGENT_ID, defaultChatAgentId via
+# BAILIAN_DEFAULT_CHAT_AGENT_ID, and the API key via DASHSCOPE_API_KEY.
+
+- insert:
+    - id: tool-bailian-kb
+      name: "bailian-kb-dsh"
+      config:
+        workspaceId: !!js process.env.BAILIAN_WORKSPACE_ID

packages/bailian-kb-dsh/package.json

@@ -0,0 +1,118 @@
+{
+  "name": "bailian-kb-dsh",
+  "version": "0.1.19",
+  "description": "Bailian knowledge-base tools for DeepSeek Harness: kb_search and kb_chat over the DashScope RAG API, plus the bl CLI management skill.",
+  "keywords": [
+    "alibaba-cloud",
+    "aliyun",
+    "bailian",
+    "dashscope",
+    "deepseek-harness",
+    "dsh",
+    "knowledge-base",
+    "rag"
+  ],
+  "homepage": "https://github.com/modelstudioai/cli/tree/main/packages/bailian-kb-dsh",
+  "bugs": {
+    "url": "https://github.com/modelstudioai/cli/issues"
+  },
+  "license": "Apache-2.0",
+  "author": "Aliyun Model Studio",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/modelstudioai/cli.git",
+    "directory": "packages/bailian-kb-dsh"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "cordis.patch.yml"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "default": "./dist/web/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json && tsc -p tsconfig.web.json && tsdown",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.web.json",
+    "test": "vp test",
+    "check": "vp check"
+  },
+  "dependencies": {
+    "yaml": "catalog:"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-connection": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-skill": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@types/node": "catalog:",
+    "@types/react": "~18.3.1",
+    "lightningcss": "^1.32.0",
+    "react": "^18.2.0",
+    "tsdown": "^0.22.2",
+    "typescript": "catalog:",
+    "vite-plus": "catalog:",
+    "yaml": "catalog:"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-connection": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-skill": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "react": "^18.2.0"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "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"
+      ],
+      "platform": "web"
+    }
+  }
+}

packages/bailian-kb-dsh/skills/bailian-kb/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: bailian-kb
+description: >-
+  管理阿里云百炼知识库（建库、上传文档、部署检索服务、Chunk 运维、数据中心文件管理），命令行工具为 bl（bailian-cli）。
+  当用户要创建/更新/删除知识库、上传或导入文档（本地/OSS）、创建/部署/调参检索或问答服务、
+  增删改查 Chunk、管理数据中心类目/文件/集合时使用本 skill。
+  检索与问答不走本 skill——用原生工具 kb_search（取证据）/ kb_chat（成品问答）；
+  bl knowledge search / chat 仅用于部署后的验证调试（如 --agent-version beta 调试草稿版）。
+  kb_search / kb_chat 的凭据与工作空间由插件自动解析（~/.dsh/settings.yaml 的 bailian-kb 段、
+  ~/.dsh/.credentials.yaml 的 DASHSCOPE_API_KEY），不要自己去读或传。
+  普通问答、编程、写作、翻译、泛搜索不触发本 skill。
+---
+
+# 百炼知识库管理（bl）
+
+检索面与管理面的分工：**查知识用 `kb_search`（取证据）/ `kb_chat`（成品问答）原生工具；本 skill 只覆盖管理长尾**——知识库全生命周期、文档、检索服务、Chunk、数据中心。
+
+本 skill **不负责**判断何时该检索。可用检索服务的清单（含 agent_id）由插件自动注入到会话上下文里，`kb_search` / `kb_chat` 直接取用；不需要为了检索先加载本 skill。
+
+## 检索服务清单的行为语义
+
+- 清单由插件从百炼 API 拉取后缓存，按会话周期性刷新（约 30 分钟），只含 **deployed** 状态的服务；
+- **刚用 `bl` 新建或部署的服务不会立刻出现在清单里**。不用等刷新——命令输出里刚拿到的 `agent_id` 直接可用；
+- 服务很多时清单只列最近修改的若干条并标明总数。要找特定服务用 `bl knowledge service list --scene search --name <关键词>`；
+- 清单里确实没有能回答用户问题的服务时，如实告知用户，**不要挑一个最像的 agent_id 去试**。
+
+## 前置检查
+
+1. 安装校验：运行 `bl knowledge list --help`。若报 `Unknown command` 或 bl 未安装，执行
+   `npm install -g bailian-cli`（需 Node.js ≥ 18.17）；已安装但命令缺失时先 `bl update` 升级。
+   安装失败时把错误原样报告给用户，不要静默跳过。
+2. 鉴权：需要 `DASHSCOPE_API_KEY`（环境变量，或 `bl auth login --api-key sk-xxx`，或 `bl config set --key api_key --value sk-xxx`）。
+3. workspace 解析优先级：`--workspace-id` 参数 > 环境变量 `BAILIAN_WORKSPACE_ID` > `bl config set --key workspace_id --value ws-xxx`。
+
+## 何时用哪个命令
+
+| 用户意图                                 | 命令                                                | 备注                             |
+| ---------------------------------------- | --------------------------------------------------- | -------------------------------- |
+| 查知识 / 问答（日常检索）                | 原生工具 `kb_search` / `kb_chat`                    | 不走 bl                          |
+| 建库 / 查看 / 改名 / 删库 / 监控         | `bl knowledge create/list/info/update/delete/stats` | `bl knowledge create --help`     |
+| 上传本地文档、看解析状态、删文档、打标签 | `bl knowledge doc upload/list/status/delete/tag`    | `bl knowledge doc upload --help` |
+| 从 OSS 批量导入                          | `bl knowledge doc import-oss`                       | Bucket 需预先授权服务角色        |
+| 创建 / 部署 / 调参检索（问答）服务       | `bl knowledge service create/update/deploy/…`       | `bl knowledge service --help`    |
+| 修正错误切片、屏蔽某段内容               | `bl knowledge chunk add/list/update/delete`         | `bl knowledge chunk --help`      |
+| 数据中心类目 / 文件 / 集合管理           | `bl knowledge category/file/collection …`           | `bl knowledge category --help`   |
+| CLI 配置、升级                           | `bl config show/set`、`bl update`                   | `bl config --help`               |
+| 部署后验证、调试草稿版服务               | `bl knowledge search/chat --agent-version beta`     | `bl knowledge search --help`     |
+
+## 核心工作流：建库到可检索
+
+```bash
+bl knowledge doc upload --file ./docs/ --workspace-id ws-xxx                # 1. 上传本地文件/目录 → 得 fileId
+bl knowledge create --name my-kb --description '产品文档' --doc-id <fileId> --wait                # 2. 建库并导入 → 得 index-id (pipelineId)
+bl knowledge service create --name my-search --scene search --index-id <index-id>   # 3. 建检索服务 → 得 agent-id（draft）
+bl knowledge service deploy --agent-id <agent-id> --yes                     # 4. 发布服务（此后可被默认版本调用）
+bl knowledge service list --scene search --status deployed                  # 5. 确认服务可见
+```
+
+部署完成后用原生工具 `kb_search` 带该 `agent_id` 验证检索；若要在部署前调试草稿配置，用 `bl knowledge search --agent-id <id> --agent-version beta`。
+
+已有文件再入库的简写：`bl knowledge doc upload --file ./a.md --index-id <index-id> --wait`（上传+导入一步完成）。
+
+## ID 速查（极易混淆）
+
+| ID                      | 来源                                                    | 用在哪                                                                              |
+| ----------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `index-id`              | `knowledge create` 返回的 pipelineId / `knowledge list` | 所有 knowledge/doc/chunk 命令的 `--index-id`                                        |
+| `fileId`                | `doc upload` / `doc import-oss` 返回                    | 数据中心命令（`file get/delete`、`knowledge create --doc-id`、`doc tag`）           |
+| `doc_id`（库内文档 ID） | `doc list` 输出                                         | `doc delete`、`chunk add/update` 的 `--doc-id`；**可能带 workspace 后缀，≠ fileId** |
+| `job-id`                | 导入命令返回的 ingestionId                              | `doc status`（必须同时给 `--index-id` 和 `--job-id`）                               |
+| chunk id                | `chunk list` 输出的 `metadata._id`                      | `chunk update/delete` 的 `--chunk-id`                                               |
+| `agent-id`              | `service create/list`                                   | `service *`、`kb_search`/`kb_chat`、`bl knowledge search/chat`                      |
+
+## 命令参考
+
+执行不熟悉的命令前，跑 `bl <命令> --help` 查看完整 Usage / Flags / Notes / Examples。**不要猜 flag。**
+全部命令支持 `--output json`（结构化输出）、`--dry-run`（预览请求）、`--quiet`、`--verbose`。
+
+## 危险与不可逆操作
+
+执行以下操作前须向用户确认，脚本化时才用 `--yes` 跳过交互确认：
+
+- `knowledge delete`：不可逆，库和全部索引内容永久删除（数据中心源文件保留）。
+- `file delete`：不可逆，且引用该文件的知识库文档索引会失效；只想从单个库移除用 `doc delete`。
+- `chunk delete`：不可逆。
+- `service deploy`：发布影响线上调用方；`service delete` 后 agent_id 不可再用（软删、幂等）。
+- `collection create`：**没有删除 API**，创建集合要慎重。
+- 索引配置（embedding 模型、chunk size 等）建库后不可改，只能重建。
+
+## 最佳实践
+
+- **建服务时必须把名字写清楚**：`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` 反查。
+- `service list` 必须带 `--scene chat|search`，两个场景要分别查询。

packages/bailian-kb-dsh/src/api-types.ts

@@ -0,0 +1,72 @@
+/** Request/response fields of the DashScope search and chat endpoints. */
+
+/** Retrieval-service scenes; the server requires one per list query. */
+export type ServiceScene = "chat" | "search";
+
+export interface ServiceListRequest {
+  agent_scene: ServiceScene;
+  /** Filter to deployed services (spelling required by the server). */
+  agent_status?: "deployed";
+  agent_name?: string;
+  page_number: number;
+  page_size: number;
+}
+
+/**
+ * One row of the service list.
+ *
+ * `description` is not included: the listing endpoint does not currently return
+ * it, even for services created with a description. Add it here once it starts
+ * appearing on the wire.
+ *
+ * `pipeline_list` is typed but deliberately never consumed: it can omit
+ * `pipeline_name` or come back empty, so it cannot serve as a knowledge-base
+ * label.
+ */
+export interface ServiceListRow {
+  agent_id?: string;
+  agent_name?: string;
+  agent_scene?: string;
+  agent_status?: string;
+  agent_version?: string;
+  create_time?: string;
+  modify_time?: string;
+  pipeline_list?: { pipeline_id?: string; pipeline_name?: string }[];
+}
+
+export interface ServiceListResponse {
+  code?: string;
+  message?: string;
+  data?: { total_count?: number; rows?: ServiceListRow[] };
+}
+
+export interface SearchRequest {
+  query: string;
+  agent_id: string;
+  agent_version?: string;
+  images?: string[];
+}
+
+export interface SearchResponse {
+  request_id?: string;
+  data?: {
+    total?: number;
+    nodes?: { score: number; text: string; metadata?: Record<string, unknown> }[];
+  };
+}
+
+export interface ChatRequest {
+  input: { messages: { role: "user" | "assistant"; content: string }[] };
+  parameters: { agent_options: { agent_id: string; agent_version?: string } };
+  stream: true;
+}
+
+export interface ChatStreamChunk {
+  output?: {
+    choices?: {
+      message?: { content?: string; extra?: { step_change?: string } };
+      finish_reason?: string;
+    }[];
+  };
+  request_id?: string;
+}

packages/bailian-kb-dsh/src/bl-cli.ts

@@ -0,0 +1,57 @@
+/**
+ * Host-side bridge to the locally installed `bl` CLI (bailian-cli): reads the
+ * credentials an earlier `bl auth login` already stored, so a user who has
+ * already set the CLI up does not have to configure this plugin a second time.
+ *
+ * Reading the CLI's credential file (`~/.bailian/config.json`) is the only way
+ * to obtain the value programmatically — CLI commands mask stored keys on
+ * output, so there is nothing to parse from stdout.
+ *
+ * Starting a login is NOT done through the CLI; see `console-login.ts`.
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** The two values this plugin can adopt from the bl CLI credential file. */
+export interface BlCliConfig {
+  /** DashScope api key (`api_key`, top-level default profile). */
+  apiKey?: string;
+  /** Bailian workspace id (`workspace_id`), present when the console login callback carried one. */
+  workspaceId?: string;
+}
+
+/** Default location of the bl CLI credential file (default profile at top level). */
+export function blCliConfigPath(): string {
+  return join(homedir(), ".bailian", "config.json");
+}
+
+/**
+ * Read the api key and workspace id from the bl CLI credential file.
+ * Best-effort: a missing, unreadable, or malformed file reads as empty —
+ * callers treat that the same as "the CLI has not logged in yet".
+ * @param configPath - override for tests; defaults to `~/.bailian/config.json`.
+ * @returns the values found; fields are absent rather than blank.
+ */
+export function readBlCliConfig(configPath = blCliConfigPath()): BlCliConfig {
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, "utf8")) as unknown;
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {};
+    const record = parsed as Record<string, unknown>;
+    const apiKey =
+      typeof record.api_key === "string" && record.api_key.trim() !== ""
+        ? record.api_key.trim()
+        : undefined;
+    const workspaceId =
+      typeof record.workspace_id === "string" && record.workspace_id.trim() !== ""
+        ? record.workspace_id.trim()
+        : undefined;
+    return {
+      ...(apiKey !== undefined ? { apiKey } : {}),
+      ...(workspaceId !== undefined ? { workspaceId } : {}),
+    };
+  } catch (_unreadable) {
+    return {};
+  }
+}

packages/bailian-kb-dsh/src/chat.ts

@@ -0,0 +1,46 @@
+/** Buffered consumption of the knowledge chat SSE stream: deltas concatenate into one complete answer. */
+
+import type { ChatStreamChunk } from "./api-types.js";
+import { KbApiError } from "./client.js";
+import { parseSseStream } from "./sse.js";
+
+export interface ChatResult {
+  answer: string;
+  requestId?: string;
+}
+
+/**
+ * Consume one chat SSE response to completion.
+ * @param res - the SSE response from KbClient.postSse.
+ * @returns the concatenated answer and the last seen request id.
+ */
+export async function consumeChatStream(res: Response): Promise<ChatResult> {
+  if (!res.body) throw new KbApiError("knowledge chat returned no response body");
+  let answer = "";
+  let requestId: string | undefined;
+  for await (const event of parseSseStream(res.body)) {
+    if (event.data === "[DONE]") break;
+    if (event.event === "error") {
+      let message = `knowledge chat stream error: ${event.data}`;
+      try {
+        const err = JSON.parse(event.data) as { code?: string; message?: string };
+        if (err.message)
+          message = `knowledge chat stream error${err.code ? ` (${err.code})` : ""}: ${err.message}`;
+      } catch {
+        /* non-JSON error payload: keep the raw data in the message */
+      }
+      throw new KbApiError(message);
+    }
+    let parsed: ChatStreamChunk;
+    try {
+      parsed = JSON.parse(event.data) as ChatStreamChunk;
+    } catch {
+      continue;
+    } // unparseable keep-alive/comment payloads carry no answer content
+    if (parsed.request_id) requestId = parsed.request_id;
+    for (const choice of parsed.output?.choices ?? []) {
+      if (choice.message?.content) answer += choice.message.content;
+    }
+  }
+  return { answer, requestId };
+}

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

@@ -0,0 +1,101 @@
+/** Shared HTTP client for the knowledge endpoints: per-call Bearer auth, JSON/SSE POST, and error translation. */
+
+import { kbEndpoint } from "./endpoints.js";
+
+/** Maximum error-body characters kept in a translated message. */
+const ERROR_BODY_LIMIT = 500;
+
+/** One knowledge API failure: HTTP status plus a bounded server-body summary. */
+export class KbApiError extends Error {
+  constructor(
+    message: string,
+    readonly status?: number,
+  ) {
+    super(message);
+    this.name = "KbApiError";
+  }
+}
+
+export interface KbClientOptions {
+  /** 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;
+  /** Resolves the current DASHSCOPE_API_KEY per call; throws with guidance when unconfigured. */
+  resolveApiKey: () => Promise<string>;
+  /** Test seam; defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+}
+
+export class KbClient {
+  constructor(private readonly opts: KbClientOptions) {}
+
+  /** The deployment's configured service version, exposed for request builders. */
+  get agentVersion(): string | undefined {
+    return this.opts.agentVersion;
+  }
+
+  private async post(
+    path: string,
+    body: unknown,
+    accept: string,
+    signal?: AbortSignal,
+  ): Promise<Response> {
+    const [apiKey, workspaceId] = await Promise.all([
+      this.opts.resolveApiKey(),
+      this.opts.resolveWorkspaceId(),
+    ]);
+    const fetchImpl = this.opts.fetchImpl ?? fetch;
+    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,
+      },
+      body: JSON.stringify(body),
+      signal,
+    });
+    if (!res.ok) {
+      const raw = (await res.text().catch(() => "")).slice(0, ERROR_BODY_LIMIT);
+      let detail = raw;
+      try {
+        const parsed = JSON.parse(raw) as { message?: string; code?: string };
+        if (parsed.message)
+          detail = parsed.code ? `${parsed.code}: ${parsed.message}` : parsed.message;
+      } catch {
+        /* non-JSON error body: keep the bounded raw text */
+      }
+      throw new KbApiError(
+        `knowledge API ${path} failed (HTTP ${res.status}): ${detail}`,
+        res.status,
+      );
+    }
+    return res;
+  }
+
+  /**
+   * POST one JSON request and parse the JSON response.
+   * @param path - one KB_PATHS value.
+   * @param body - JSON-serializable request body.
+   * @param signal - optional abort/timeout signal.
+   * @returns the parsed response.
+   */
+  async postJson<T>(path: string, body: unknown, signal?: AbortSignal): Promise<T> {
+    const res = await this.post(path, body, "application/json", signal);
+    return (await res.json()) as T;
+  }
+
+  /**
+   * POST one JSON request expecting an SSE response stream.
+   * @param path - one KB_PATHS value.
+   * @param body - JSON-serializable request body.
+   * @param signal - abort/timeout signal (kb_chat passes its configured timeout).
+   * @returns the raw Response whose body is the SSE stream.
+   */
+  async postSse(path: string, body: unknown, signal?: AbortSignal): Promise<Response> {
+    return await this.post(path, body, "text/event-stream", signal);
+  }
+}

packages/bailian-kb-dsh/src/console-login.ts

@@ -0,0 +1,311 @@
+/**
+ * Self-contained Bailian console login: the plugin drives the console's browser
+ * login itself and persists what comes back, rather than shelling out to the
+ * `bl` CLI.
+ *
+ * Driving the flow here lets it always request a freshly issued api key, so the
+ * key and the workspace id both come from the account that just signed in, and
+ * the values land straight in the dsh stores.
+ *
+ * Shape of the flow: bind a loopback-only port, open the console login page
+ * pointed at that port, then accept one callback carrying the credentials as
+ * query parameters or a JSON / form-encoded body.
+ */
+
+import { execFile } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import http from "node:http";
+
+/** Console web origins by site, keyed as the CLI's `--console-site` values. */
+const CONSOLE_ORIGINS: Record<string, string> = {
+  domestic: "https://bailian.console.aliyun.com",
+  international: "https://modelstudio.console.alibabacloud.com",
+};
+
+/** How long the loopback listener waits for the browser callback. */
+const LOGIN_TIMEOUT_MS = 15 * 60 * 1000;
+
+/** Upper bound on a callback body. */
+const MAX_CALLBACK_BODY = 65536;
+
+/** Credentials the console callback can carry. */
+export interface ConsoleLoginCredentials {
+  /** Freshly issued DashScope api key. */
+  apiKey?: string;
+  /** Workspace id of the account that signed in. */
+  workspaceId?: string;
+}
+
+/**
+ * Where the login flow stands. Deliberately carries no secret: the plain key
+ * is handed to the completion callback and never retained here, so polling
+ * this state from the browser cannot leak it.
+ */
+export type ConsoleLoginState =
+  | { phase: "idle" }
+  | { phase: "waiting"; loginUrl: string }
+  | { phase: "done"; fields: string[] }
+  | { phase: "failed"; reason: string };
+
+/** The single in-flight flow: one browser login at a time. */
+let active: { server: http.Server } | undefined;
+let state: ConsoleLoginState = { phase: "idle" };
+
+/** Read the current flow state (safe to expose to the panel). */
+export function consoleLoginState(): ConsoleLoginState {
+  return state;
+}
+
+/** Pick the first non-blank string among the given keys. */
+function stringField(source: Record<string, unknown>, ...keys: string[]): string | undefined {
+  for (const key of keys) {
+    const value = source[key];
+    if (typeof value === "string" && value.trim() !== "") return value.trim();
+  }
+  return undefined;
+}
+
+/** Read a bounded UTF-8 request body; an oversized body reads as empty. */
+function readBody(req: http.IncomingMessage): Promise<string> {
+  return new Promise((resolve) => {
+    const chunks: Buffer[] = [];
+    let size = 0;
+    req.on("data", (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > MAX_CALLBACK_BODY) {
+        req.destroy();
+        resolve("");
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      resolve(Buffer.concat(chunks).toString("utf8"));
+    });
+    req.on("error", () => {
+      resolve("");
+    });
+  });
+}
+
+/**
+ * Parse a callback body as JSON (optionally wrapped in `data`) or as form
+ * encoding. Content-type is a hint only: both shapes occur in practice, so both
+ * are attempted.
+ * @param raw - the raw request body.
+ * @returns the flattened fields; an unparseable body yields no fields.
+ */
+export function parseCallbackBody(raw: string): Record<string, unknown> {
+  const text = raw.replace(/^\uFEFF/, "").trim();
+  if (text === "") return {};
+  let json: unknown;
+  let parsedAsJson = false;
+  try {
+    json = JSON.parse(text);
+    parsedAsJson = true;
+  } catch (_notJson) {
+    /* fall through to form parsing */
+  }
+  if (parsedAsJson) {
+    // Valid JSON that is not an object carries no fields. Returning here rather
+    // than falling through matters: form parsing would turn the whole payload
+    // into one junk key.
+    if (json === null || typeof json !== "object" || Array.isArray(json)) return {};
+    const record = json as Record<string, unknown>;
+    const inner = record.data;
+    if (inner !== null && typeof inner === "object" && !Array.isArray(inner)) {
+      // Merge the envelope's `data` under the top level, top level winning.
+      return { ...(inner as Record<string, unknown>), ...record };
+    }
+    return record;
+  }
+  try {
+    return Object.fromEntries(new URLSearchParams(text));
+  } catch (_notForm) {
+    return {};
+  }
+}
+
+/**
+ * Pick the api key and workspace id out of a callback's fields, query
+ * parameters taking priority over the body.
+ * @param query - the callback URL's query parameters.
+ * @param body - the parsed callback body.
+ * @returns the credentials found; fields are absent rather than blank.
+ */
+export function pickCallbackCredentials(
+  query: Record<string, unknown>,
+  body: Record<string, unknown>,
+): ConsoleLoginCredentials {
+  const apiKey = stringField(query, "api_key", "apiKey") ?? stringField(body, "api_key", "apiKey");
+  const workspaceId =
+    stringField(query, "workspace_id", "workspaceId") ??
+    stringField(body, "workspace_id", "workspaceId");
+  return {
+    ...(apiKey !== undefined ? { apiKey } : {}),
+    ...(workspaceId !== undefined ? { workspaceId } : {}),
+  };
+}
+
+/** Extract the credentials from a callback, query parameters taking priority. */
+async function extractCredentials(
+  req: http.IncomingMessage,
+  url: URL,
+): Promise<ConsoleLoginCredentials> {
+  const method = req.method ?? "GET";
+  const body =
+    method === "POST" || method === "PUT" || method === "PATCH"
+      ? parseCallbackBody(await readBody(req))
+      : {};
+  return pickCallbackCredentials(Object.fromEntries(url.searchParams), body);
+}
+
+/** Open a URL with the OS default handler; never routed through a shell. */
+function openInBrowser(url: string): Promise<void> {
+  const cmd =
+    process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, { windowsHide: true }, (err) => {
+      if (err) reject(err);
+      else resolve();
+    });
+  });
+}
+
+/** Bind an http server to a loopback-only port chosen by the OS. */
+function listenLoopback(server: http.Server): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const onError = (err: Error): void => {
+      reject(err);
+    };
+    server.once("error", onError);
+    server.listen({ port: 0, host: "127.0.0.1", exclusive: true }, () => {
+      server.off("error", onError);
+      const address = server.address();
+      if (address === null || typeof address === "string") {
+        reject(new Error("expected a TCP address"));
+        return;
+      }
+      resolve(address.port);
+    });
+  });
+}
+
+/** Outcome of asking the host to start a console login. */
+export type ConsoleLoginStart =
+  | { status: "started"; loginUrl: string }
+  | { status: "already-running"; loginUrl: string }
+  | { status: "failed"; reason: string };
+
+/**
+ * Start a console login on the host: binds a loopback listener, opens the
+ * console login page in the host's default browser, and hands the credentials
+ * from the callback to `onComplete` (which persists them). Fire-and-forget —
+ * this resolves once the browser has been opened; poll {@link consoleLoginState}
+ * for the outcome.
+ * @param opts.site - console site, `domestic` (default) or `international`.
+ * @param opts.onComplete - persists the received credentials; its resolved
+ * field names become the `done` state's `fields`.
+ * @returns whether the flow started, plus the URL to open manually if needed.
+ */
+export async function startConsoleLogin(opts: {
+  site?: string;
+  onComplete: (credentials: ConsoleLoginCredentials) => Promise<string[]>;
+}): Promise<ConsoleLoginStart> {
+  if (active !== undefined) {
+    return {
+      status: "already-running",
+      loginUrl: state.phase === "waiting" ? state.loginUrl : "",
+    };
+  }
+  const expectedState = randomBytes(16).toString("hex");
+  let settled = false;
+  const server = http.createServer((req, res) => {
+    void (async () => {
+      if (req.method === "OPTIONS") {
+        // The console page posts cross-origin; answer its preflight.
+        res.writeHead(204, {
+          "Access-Control-Allow-Origin": "*",
+          "Access-Control-Allow-Methods": "GET, POST, PUT, PATCH, OPTIONS",
+          "Access-Control-Allow-Headers": "Content-Type",
+        });
+        res.end();
+        return;
+      }
+      const url = new URL(req.url ?? "/", "http://127.0.0.1");
+      if (url.searchParams.get("state") !== expectedState) {
+        // Not our callback (or a forged one): refuse without ending the flow.
+        res.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
+        res.end("bad state\n");
+        return;
+      }
+      const credentials = await extractCredentials(req, url);
+      res.writeHead(200, {
+        "Content-Type": "text/plain; charset=utf-8",
+        "Access-Control-Allow-Origin": "*",
+      });
+      res.end("OK\n");
+      if (credentials.apiKey === undefined && credentials.workspaceId === undefined) {
+        // A callback with neither value (e.g. a bare probe): keep waiting.
+        return;
+      }
+      settled = true;
+      try {
+        const fields = await opts.onComplete(credentials);
+        state = { phase: "done", fields };
+      } catch (err) {
+        state = { phase: "failed", reason: err instanceof Error ? err.message : "persist failed" };
+      }
+      server.close();
+    })().catch(() => {
+      res.statusCode = 500;
+      res.end();
+    });
+  });
+
+  let port: number;
+  try {
+    port = await listenLoopback(server);
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : "could not bind a local port";
+    state = { phase: "failed", reason };
+    return { status: "failed", reason };
+  }
+
+  // Ask for a freshly issued key, so the key and the workspace id cannot end up
+  // belonging to two different accounts.
+  const origin =
+    (opts.site !== undefined ? CONSOLE_ORIGINS[opts.site] : undefined) ?? CONSOLE_ORIGINS.domestic!;
+  const loginUrl =
+    `${origin}/console-login?notice=127.0.0.1:${port}` +
+    `?state=${encodeURIComponent(expectedState)}&needapikey=true`;
+
+  active = { server };
+  state = { phase: "waiting", loginUrl };
+  const timer = setTimeout(() => {
+    server.close();
+  }, LOGIN_TIMEOUT_MS);
+  timer.unref?.();
+  server.once("close", () => {
+    clearTimeout(timer);
+    active = undefined;
+    if (!settled && state.phase === "waiting") {
+      state = { phase: "failed", reason: "the login timed out before the console called back" };
+    }
+  });
+
+  try {
+    await openInBrowser(loginUrl);
+  } catch (_browserRefused) {
+    // Headless or locked-down host: the panel shows `loginUrl` to open by hand.
+  }
+  return { status: "started", loginUrl };
+}
+
+/** Abandon an in-flight login (closes the listener). */
+export function cancelConsoleLogin(): void {
+  active?.server.close();
+  active = undefined;
+  state = { phase: "idle" };
+}

packages/bailian-kb-dsh/src/endpoints.ts

@@ -0,0 +1,24 @@
+/** Protocol path constants and the workspace-subdomain URL builder (external API spec; not configurable). */
+
+/**
+ * DashScope knowledge API paths. `serviceList` backs the plugin's internal
+ * service cache only — it is deliberately NOT exposed as a model tool (a
+ * discovery tool reintroduces the "list before you search" round trip this
+ * design exists to remove); the management surface uses the bl CLI instead.
+ */
+export const KB_PATHS = {
+  serviceList: "/api/v1/indices/rag/app/list",
+  search: "/api/v1/indices/knowledge/search",
+  chat: "/api/v2/apps/knowledge/chat",
+} as const;
+
+/**
+ * Build one knowledge API endpoint.
+ * @param endpointHost - host suffix, e.g. `cn-beijing.maas.aliyuncs.com`.
+ * @param workspaceId - Bailian workspace id used as the subdomain.
+ * @param path - one {@link KB_PATHS} value.
+ * @returns the absolute endpoint URL.
+ */
+export function kbEndpoint(endpointHost: string, workspaceId: string, path: string): string {
+  return `https://${workspaceId}.${endpointHost}${path}`;
+}

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

@@ -0,0 +1,615 @@
+/**
+ * Bailian knowledge-base consumer plugin: registers kb_search and kb_chat over the DashScope RAG API,
+ * plus the bl management skill.
+ * @module dsh-tool-bailian-kb
+ */
+
+import type { Context } from "@deepseek-ai/cordis";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import z from "@deepseek-ai/schemastery";
+import { credentialRef } from "@deepseek-ai/dsh-credentials";
+import {
+  settingsNamespace,
+  SettingsProvider,
+  type SettingsRegisterOptions,
+  type SettingsScope,
+} from "@deepseek-ai/dsh-settings";
+import { readBlCliConfig } from "./bl-cli.js";
+import { consoleLoginState, startConsoleLogin } from "./console-login.js";
+import { KbClient } from "./client.js";
+import { registerSkill } from "./skill.js";
+import { ServiceCache } from "./service-cache.js";
+import { buildRefreshedSceneList } from "./service-catalog.js";
+import { installServiceContext } from "./service-context.js";
+import type { ServiceScene } from "./api-types.js";
+import { createKbTools } from "./tools.js";
+
+/** Minimal webServer route shape (declared inline to avoid a host-package dependency). */
+interface WebRoute {
+  kind: "exact" | "prefix";
+  path: string;
+  handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+}
+/** Shell-environment registration shape (declared inline to avoid a host-package dependency). */
+interface ShellEnvRegistration {
+  name: string;
+  variables: Record<string, { description: string }>;
+  resolve: () => Record<string, string | undefined>;
+}
+declare module "@deepseek-ai/cordis" {
+  interface Context {
+    webServer: {
+      register(route: WebRoute): () => void;
+    };
+    shellEnv: {
+      register(registration: ShellEnvRegistration): void;
+    };
+  }
+}
+
+export const name = "tool-bailian-kb";
+export const inject = ["tools", "credentials"];
+
+/** Settings namespace this plugin registers when a settings service is composed. */
+const SETTINGS_NS = settingsNamespace("bailian-kb");
+
+/** Settings fields seeded once from their credential references ({@link seedFromCredentials}). */
+const CREDENTIAL_SEEDS = [
+  ["workspaceId", "BAILIAN_WORKSPACE_ID"],
+  ["defaultRetrieveAgentId", "BAILIAN_DEFAULT_RETRIEVE_AGENT_ID"],
+  ["defaultChatAgentId", "BAILIAN_DEFAULT_CHAT_AGENT_ID"],
+] as const;
+
+/**
+ * Every {@link Config} field the bridge route accepts. A static allowlist,
+ * NOT `key in current()`: optional fields with no default and no base
+ * (the default service ids) vanish from the resolved config once cleared,
+ * and a membership test against it would silently drop their next write.
+ */
+const CONFIG_FIELDS = new Set<string>([
+  "workspaceId",
+  "endpointHost",
+  "defaultRetrieveAgentId",
+  "defaultChatAgentId",
+  "agentVersion",
+  "chatTimeoutMs",
+]);
+
+/**
+ * One-time migration: before this section existed, the workspace and
+ * default-service ids lived only as credentials, which the wire never echoes.
+ * Seed each field the resolved section does not answer from the WRITABLE
+ * credential layer (`file`), so the page shows the value the deployment
+ * already runs with; env-sourced values stay where they are — freezing one
+ * into the document would shadow later environment changes.
+ * @param ctx - registrant context carrying credentials.
+ * @param scope - the registered `bailian-kb` scope the seed writes through.
+ */
+async function seedFromCredentials(ctx: Context, scope: SettingsScope<Config>): Promise<void> {
+  try {
+    const seeds: Partial<Record<(typeof CREDENTIAL_SEEDS)[number][0], string>> = {};
+    for (const [field, ref] of CREDENTIAL_SEEDS) {
+      if (scope.get()[field]) continue;
+      const resolved = await ctx.credentials.resolve(credentialRef(ref));
+      if (resolved?.source !== "file") continue;
+      seeds[field] = resolved.value;
+    }
+    if (Object.keys(seeds).length > 0) await scope.update(seeds);
+  } catch (_migrationFailure) {
+    // Best-effort: a failed seed leaves the credential fallback in place, so
+    // resolution still answers — the page merely starts blank.
+  }
+}
+
+/**
+ * One-time adoption of the bl CLI's stored login (`~/.bailian/config.json`):
+ * fields never set anywhere are filled from the CLI's credential file, so a
+ * `bl auth login --console` done before installing the plugin "just works".
+ * `seededFields` is the consumed-once ledger — a field is marked when it was
+ * seeded here, or when it already had a value (user-managed elsewhere) — so
+ * a value the user later clears deliberately is never resurrected.
+ * @param ctx - registrant context carrying credentials.
+ * @param scope - the registered `bailian-kb` scope the seed writes through.
+ */
+async function seedFromBlCli(ctx: Context, scope: SettingsScope<Config>): Promise<void> {
+  try {
+    const done = new Set(scope.get().seededFields ?? []);
+    if (done.has("apiKey") && done.has("workspaceId")) return;
+    const bl = readBlCliConfig();
+    const marks: string[] = [];
+    if (!done.has("apiKey")) {
+      const existing = await ctx.credentials.resolve(credentialRef("DASHSCOPE_API_KEY"));
+      if (existing) {
+        // Already configured (env or file): user-managed, never seed later.
+        marks.push("apiKey");
+      } else if (bl.apiKey !== undefined) {
+        try {
+          await ctx.credentials.set(credentialRef("DASHSCOPE_API_KEY"), bl.apiKey);
+          marks.push("apiKey");
+        } catch (_readOnlyShadow) {
+          // A read-only source refuses the write; leave unmarked so a later
+          // startup (once the shadow is gone) can still seed.
+        }
+      }
+      // Neither configured nor available from the CLI: leave unmarked so a
+      // later startup (after `bl auth login --console`) can seed.
+    }
+    if (!done.has("workspaceId")) {
+      const configured =
+        scope.get().workspaceId ||
+        (await ctx.credentials.resolve(credentialRef("BAILIAN_WORKSPACE_ID"))) !== undefined;
+      if (configured) {
+        marks.push("workspaceId");
+      } else if (bl.workspaceId !== undefined) {
+        await scope.update({ workspaceId: bl.workspaceId });
+        marks.push("workspaceId");
+      }
+    }
+    if (marks.length > 0) {
+      await scope.update({
+        seededFields: [...new Set([...(scope.get().seededFields ?? []), ...marks])],
+      });
+    }
+  } catch (_seedFailure) {
+    // Best-effort: an unseeded field still resolves through the normal
+    // credential fallback chain, and the panel's autofill button remains.
+  }
+}
+
+/** Bailian knowledge-base plugin configuration. */
+export interface Config {
+  /** 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 (env/.env or ~/.dsh/.credentials.yaml). Editable with echo on the Settings → 百炼知识库 page (settings layer). */
+  workspaceId?: string;
+  /** API host suffix; replace for other regions or private deployments. */
+  endpointHost: string;
+  /** Retrieval-service id pinned by this deployment; when unset, the per-call fallback reads the BAILIAN_DEFAULT_RETRIEVE_AGENT_ID credential. */
+  defaultRetrieveAgentId?: string;
+  /** Q&A-service id pinned by this deployment; when unset, the per-call fallback reads the BAILIAN_DEFAULT_CHAT_AGENT_ID credential. */
+  defaultChatAgentId?: 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;
+  /** Consumed-once ledger of {@link seedFromBlCli}: fields listed here are never auto-seeded again, so a deliberately cleared value stays cleared. Maintained by the host; not editable from the panel. */
+  seededFields?: string[];
+}
+
+/** Schemastery validation for {@link Config}; workspaceId and default agent ids are optional — both resolve per call with a credentials fallback. */
+export const Config: z<Config> = z.object({
+  workspaceId: z.string(),
+  endpointHost: z.string().default("cn-beijing.maas.aliyuncs.com"),
+  defaultRetrieveAgentId: z.string(),
+  defaultChatAgentId: z.string(),
+  agentVersion: z.string(),
+  chatTimeoutMs: z.number().default(300_000),
+  seededFields: z.array(z.string()),
+});
+
+/**
+ * Register the two knowledge tools over one shared client, plus the
+ * management skill when a skills registry is composed. The Config doubles as
+ * the `bailian-kb` settings section (entry config as the base layer), so
+ * every value is read through the live source thunk per call — tool schemas
+ * are static (agent_id stays required regardless), so a settings edit needs
+ * no re-registration.
+ * @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 {
+  // The active configuration source: the composition entry until a settings
+  // service attaches, then the resolved section (schema defaults → entry
+  // base → user layer). Detach falls back to the entry automatically.
+  // Hand-rolled instead of `installSettingsSection` for two extras it does
+  // not carry: the `expose` opt-in (this page edits the section from the
+  // browser) and the scope handle the credential migration writes through.
+  let current: () => Config = () => config;
+  let scope: SettingsScope<Config> | undefined;
+  /** The settings provider, captured for `mutate` (path-level unset) access. */
+  let settings: SettingsProvider | undefined;
+  /**
+   * Mark fields as consumed in the {@link seedFromBlCli} ledger — called on
+   * every user-driven write or clear, so a managed field is never re-seeded.
+   * Best-effort: a failed mark only risks one extra seed attempt.
+   */
+  const markSeeded = async (fields: readonly string[]): Promise<void> => {
+    if (!scope) return;
+    try {
+      const done = new Set(scope.get().seededFields ?? []);
+      const added = fields.filter((field) => !done.has(field));
+      if (added.length === 0) return;
+      await scope.update({ seededFields: [...done, ...added] });
+    } catch (_markFailure) {
+      /* best-effort */
+    }
+  };
+  ctx.inject(["settings"], (sctx) => {
+    settings = sctx.settings;
+    // `expose` is the wire opt-in the harness documents as deferred work; the
+    // assertion keeps this compiling against pristine upstream types, which do
+    // not declare it yet. Until upstream lands it the option is ignored and
+    // the browser page degrades to its credentials-only fallback.
+    const options = { base: config, expose: true } as SettingsRegisterOptions<Config>;
+    scope = sctx.settings.register(SETTINGS_NS, Config, options);
+    current = () => scope!.get();
+    sctx.effect(
+      () => () => {
+        current = () => config;
+      },
+      "tool-bailian-kb: settings source fallback",
+    );
+    void seedFromCredentials(ctx, scope).then(() => seedFromBlCli(ctx, scope!));
+    // Any api-key write or clear — this panel, the Models page, an external
+    // file edit — means the user manages the credential: consume the seed so
+    // a deliberately cleared key is never resurrected at the next startup.
+    sctx.on("credentials/updated", (ref) => {
+      if (ref === "DASHSCOPE_API_KEY") void markSeeded(["apiKey"]);
+    });
+  });
+
+  const client = new KbClient({
+    resolveWorkspaceId: async () => {
+      const pinned = current().workspaceId;
+      if (pinned) return pinned;
+      const resolved = await ctx.credentials.resolve(credentialRef("BAILIAN_WORKSPACE_ID"));
+      if (!resolved) {
+        throw new Error(
+          "BAILIAN_WORKSPACE_ID is not configured. Set the workspace id in the web UI (Settings → 百炼知识库) " +
+            "or in ~/.dsh/.credentials.yaml; it appears as the subdomain of your Bailian endpoints.",
+        );
+      }
+      return resolved.value;
+    },
+    // Live settings reads: the client keeps no copy, so a committed edit to
+    // the section applies on the next call.
+    get endpointHost() {
+      return current().endpointHost;
+    },
+    get agentVersion() {
+      return current().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 the web UI (Settings → 百炼知识库) " +
+            "or in ~/.dsh/.credentials.yaml (create a key at https://bailian.console.aliyun.com/?tab=app#/api-key).",
+        );
+      }
+      return resolved.value;
+    },
+  });
+
+  /** The workspace id if configured, without the client's guidance throw. */
+  const resolveWorkspaceIdOrUndefined = async (): Promise<string | undefined> => {
+    const pinned = current().workspaceId;
+    if (pinned) return pinned;
+    const resolved = await ctx.credentials.resolve(credentialRef("BAILIAN_WORKSPACE_ID"));
+    return resolved?.value;
+  };
+
+  const serviceCache = new ServiceCache({
+    client,
+    resolveWorkspaceId: async () => {
+      const workspaceId = await resolveWorkspaceIdOrUndefined();
+      if (workspaceId === undefined) throw new Error("workspace id is not configured");
+      return workspaceId;
+    },
+    get endpointHost() {
+      return current().endpointHost;
+    },
+    warn: (message) => {
+      ctx.logger.warn(message);
+    },
+  });
+
+  /** The user's explicitly configured default for one scene: settings layer, then credential. */
+  const configuredDefaultAgentId = async (scene: ServiceScene): Promise<string | undefined> => {
+    const pinned =
+      scene === "search" ? current().defaultRetrieveAgentId : current().defaultChatAgentId;
+    if (pinned) return pinned;
+    const ref =
+      scene === "search" ? "BAILIAN_DEFAULT_RETRIEVE_AGENT_ID" : "BAILIAN_DEFAULT_CHAT_AGENT_ID";
+    const resolved = await ctx.credentials.resolve(credentialRef(ref));
+    return resolved?.value;
+  };
+
+  /**
+   * The default service for one scene, falling back to the sole deployed service
+   * when the workspace has exactly one. That last layer is the zero-configuration
+   * path for the common 2C deployment: with one service there is nothing to
+   * choose, so making the user name it in settings buys nothing.
+   */
+  const resolveDefaultAgentId = async (scene: ServiceScene): Promise<string | undefined> => {
+    const configured = await configuredDefaultAgentId(scene);
+    if (configured !== undefined) return configured;
+    const workspaceId = await resolveWorkspaceIdOrUndefined();
+    if (workspaceId === undefined) return undefined;
+    const forScene =
+      serviceCache.peek(workspaceId)?.entries.filter((entry) => entry.scene === scene) ?? [];
+    return forScene.length === 1 ? forScene[0]?.agent_id : undefined;
+  };
+  for (const tool of createKbTools({
+    client,
+    resolveDefaultRetrieveAgentId: async () => await resolveDefaultAgentId("search"),
+    resolveDefaultChatAgentId: async () => await resolveDefaultAgentId("chat"),
+    // Self-heal for a cached id the server has since rejected: refresh once and
+    // put the current list in the error, which reaches the model this step. An
+    // empty result is reported too rather than dropped — a bare "invalid
+    // agent_id" reads as "try another one", and when nothing is deployed no id
+    // can work.
+    describeServicesAfterRefresh: async (scene) => {
+      await serviceCache.refresh();
+      const workspaceId = await resolveWorkspaceIdOrUndefined();
+      if (workspaceId === undefined) return undefined;
+      return buildRefreshedSceneList(scene, serviceCache.entriesFor(workspaceId, scene));
+    },
+    get chatTimeoutMs() {
+      return current().chatTimeoutMs;
+    },
+  })) {
+    ctx.tools.register(tool);
+  }
+  registerSkill(ctx);
+
+  // A management command that changes the service inventory invalidates the
+  // cache immediately, so the next session sees the new service instead of
+  // waiting out the TTL. `tools/result` is observe-only (it returns undefined and
+  // sits after the pipeline), so listening here cannot affect tool execution.
+  //
+  // The command string is matched inside the serialized arguments rather than
+  // against a specific tool name: the agent may run `bl` through bash, a
+  // terminal tool, or a run_code program. A loose match is deliberate — a false
+  // positive costs one list request, while a miss falls back to the TTL.
+  ctx.on("tools/result", (_exec, result) => {
+    if (result.isError) return;
+    const args = JSON.stringify((_exec as { arguments?: unknown }).arguments ?? "");
+    if (!/bl\s+knowledge\s+service\s+(create|deploy|delete|copy)/.test(args)) return;
+    serviceCache.invalidate();
+    void serviceCache.refresh();
+  });
+
+  // The service catalog rides an `agent/pre-step` context message rather than the
+  // tool descriptions: descriptions freeze at plugin load, and a plugin loads
+  // once per process, so in a long-running host a service created elsewhere
+  // would never be seen. Optional inject — a headless assembly without `agents`
+  // simply gets no catalog, and both tools keep working.
+  ctx.inject(["agents"], (actx) => {
+    installServiceContext(actx, {
+      cache: serviceCache,
+      resolveWorkspaceId: resolveWorkspaceIdOrUndefined,
+      resolveDefaultRetrieveAgentId: async () => await configuredDefaultAgentId("search"),
+      resolveDefaultChatAgentId: async () => await configuredDefaultAgentId("chat"),
+      warn: (message) => {
+        actx.logger.warn(message);
+      },
+    });
+  });
+
+  // Export the resolved workspace id as a shell environment variable so
+  // management CLI commands (`bl knowledge list`, `bl knowledge service list`, etc.)
+  // running in bash can see the value the settings service resolved.
+  // Without this, the settings.yaml value is invisible to child processes.
+  ctx.inject(["shellEnv"], (envCtx) => {
+    envCtx.shellEnv.register({
+      name: "bailian-kb",
+      variables: {
+        BAILIAN_WORKSPACE_ID: {
+          description:
+            "Bailian workspace id resolved from settings (Settings → 百炼知识库) or credentials.",
+        },
+      },
+      resolve: () => {
+        const wsId = current().workspaceId;
+        return wsId ? { BAILIAN_WORKSPACE_ID: wsId } : {};
+      },
+    });
+  });
+
+  // Bridge routes let the browser settings page read and write the resolved
+  // section without riding the settings wire (which requires an apiproxy
+  // allowlist entry the composition does not grant out-of-tree namespaces).
+  // GET and POST share one exact-route registration: the webServer map keys
+  // on (kind, path), so two registrations for the same path throw
+  // "duplicate route" and the second handler silently replaces the first.
+  ctx.inject(["webServer"], (wctx) => {
+    wctx.effect(
+      () =>
+        wctx.webServer.register({
+          kind: "exact",
+          path: "/bailian-kb/settings",
+          handler: async (req: IncomingMessage, res: ServerResponse) => {
+            if (req.method === "GET" || req.method === "HEAD") {
+              sendJson(res, 200, current());
+              return;
+            }
+            if (req.method !== "POST") {
+              sendJson(res, 405, { error: "use GET or POST" });
+              return;
+            }
+            if (!scope) {
+              sendJson(res, 503, { error: "settings service unavailable" });
+              return;
+            }
+            let body: unknown;
+            try {
+              body = await readJsonBody(req);
+            } catch (err) {
+              sendJson(res, 400, { error: err instanceof Error ? err.message : "bad request" });
+              return;
+            }
+            if (typeof body !== "object" || body === null) {
+              sendJson(res, 400, { error: "expected JSON object" });
+              return;
+            }
+            // Build a settings update patch. null-valued keys are removals (the
+            // field falls back to the entry config and then the credential store).
+            const patch: Record<string, unknown> = {};
+            const removals = new Set<string>();
+            for (const [key, value] of Object.entries(body as Record<string, unknown>)) {
+              if (!CONFIG_FIELDS.has(key)) continue;
+              if (value === null) {
+                removals.add(key);
+                continue;
+              }
+              patch[key] = value;
+            }
+            try {
+              // Apply non-removal patches first (scope.update merges into the user
+              // layer without disturbing other fields).
+              if (Object.keys(patch).length > 0) await scope.update(patch);
+              // Remove fields via path-level unset ops: this deletes the key from
+              // the user layer so it re-inherits the entry base and schema defaults.
+              // Using scope.replace() with the resolved config would bake defaults
+              // (endpointHost, chatTimeoutMs) and entry values into the user layer,
+              // shadowing future entry changes and polluting the stored document.
+              if (removals.size > 0 && settings) {
+                for (const key of removals) {
+                  await settings.mutate(SETTINGS_NS, [{ op: "unset", path: [key] }]);
+                }
+              }
+              // A user-driven workspace write or clear consumes its bl-CLI seed:
+              // a deliberately cleared value must never be resurrected at startup.
+              if ("workspaceId" in patch || removals.has("workspaceId"))
+                await markSeeded(["workspaceId"]);
+              sendJson(res, 200, scope.get());
+            } catch (err) {
+              sendJson(res, 500, {
+                error: err instanceof Error ? err.message : "settings write failed",
+              });
+            }
+          },
+        }),
+      "tool-bailian-kb: settings bridge route",
+    );
+
+    // Service cache bridge: the panel's only window into cache freshness.
+    // GET returns the diagnostic snapshot plus the pickable services; POST
+    // forces a refresh and returns the same shape, so the numbers the developer
+    // sees update in place.
+    wctx.effect(
+      () =>
+        wctx.webServer.register({
+          kind: "exact",
+          path: "/bailian-kb/services",
+          handler: async (req: IncomingMessage, res: ServerResponse) => {
+            if (req.method !== "GET" && req.method !== "HEAD" && req.method !== "POST") {
+              sendJson(res, 405, { error: "use GET or POST" });
+              return;
+            }
+            const workspaceId = await resolveWorkspaceIdOrUndefined();
+            if (workspaceId === undefined) {
+              sendJson(res, 200, { configured: false });
+              return;
+            }
+            if (req.method === "POST") {
+              // Force a fetch regardless of TTL: the button exists precisely for the
+              // case where the developer believes the cache is wrong.
+              serviceCache.invalidate();
+              await serviceCache.refresh();
+            }
+            sendJson(res, 200, {
+              configured: true,
+              status: serviceCache.status(workspaceId),
+              search: serviceCache.entriesFor(workspaceId, "search"),
+              chat: serviceCache.entriesFor(workspaceId, "chat"),
+            });
+          },
+        }),
+      "tool-bailian-kb: service cache bridge route",
+    );
+
+    // Autofill bridge: fetch credentials by signing in to the Bailian console
+    // (panel button). `login` drives the console's callback protocol on the
+    // host and persists what comes back — the plain key never rides the wire
+    // to the browser; `loginStatus` lets the panel poll for the outcome.
+    wctx.effect(
+      () =>
+        wctx.webServer.register({
+          kind: "exact",
+          path: "/bailian-kb/autofill",
+          handler: async (req: IncomingMessage, res: ServerResponse) => {
+            if (req.method !== "POST") {
+              sendJson(res, 405, { error: "use POST" });
+              return;
+            }
+            let action = "login";
+            try {
+              const body = await readJsonBody(req);
+              if (
+                typeof body === "object" &&
+                body !== null &&
+                (body as { action?: unknown }).action === "loginStatus"
+              )
+                action = "loginStatus";
+            } catch (_emptyOrMalformedBody) {
+              /* default to login */
+            }
+            if (action === "loginStatus") {
+              sendJson(res, 200, consoleLoginState());
+              return;
+            }
+            // Drive the console flow ourselves, requesting a freshly issued key,
+            // so the key and the workspace id both belong to the account signing
+            // in now. Persisting here keeps the plain key on the host.
+            const started = await startConsoleLogin({
+              onComplete: async (credentials) => {
+                const written: string[] = [];
+                if (credentials.apiKey !== undefined) {
+                  await ctx.credentials.set(credentialRef("DASHSCOPE_API_KEY"), credentials.apiKey);
+                  written.push("apiKey");
+                }
+                if (credentials.workspaceId !== undefined && scope) {
+                  await scope.update({ workspaceId: credentials.workspaceId });
+                  written.push("workspaceId");
+                }
+                if (written.length > 0) await markSeeded(written);
+                // A completed console login is the one unambiguous signal that the
+                // account may have changed. Without this the next session would
+                // build its catalog from the previous account's services, which is
+                // worse than having no cache at all.
+                if (written.length > 0) {
+                  serviceCache.invalidate();
+                  void serviceCache.refresh();
+                }
+                return written;
+              },
+            });
+            sendJson(res, 200, started);
+          },
+        }),
+      "tool-bailian-kb: autofill bridge route",
+    );
+  });
+}
+
+/** Write a JSON response. */
+function sendJson(res: ServerResponse, status: number, data: unknown): void {
+  res.statusCode = status;
+  res.setHeader("Content-Type", "application/json; charset=utf-8");
+  res.end(JSON.stringify(data));
+}
+
+/** Read a UTF-8 JSON body up to a size limit. */
+function readJsonBody(req: IncomingMessage, maxBytes = 16384): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let total = 0;
+    req.on("data", (chunk: Buffer) => {
+      total += chunk.length;
+      if (total > maxBytes) {
+        req.destroy();
+        reject(new Error("body too large"));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      try {
+        resolve(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+      } catch (err) {
+        reject(err);
+      }
+    });
+    req.on("error", reject);
+  });
+}

packages/bailian-kb-dsh/src/service-cache.ts

@@ -0,0 +1,290 @@
+/**
+ * On-disk cache of the workspace's deployed retrieval services.
+ *
+ * Landing spot: `${DSH_HOME:-~/.dsh}/cache/bailian-kb/services-<workspaceId>.json`.
+ * Per-workspace files are required: an api key is scoped to one workspace, and
+ * the panel's "autofill" button exists to switch accounts, so one shared file
+ * would blend services from different accounts.
+ *
+ * Why not `ctx.storage`: the storage hub is absent from every shipped agent
+ * preset, so `inject(['storage'])` may never fire for a third-party plugin, and
+ * the JSON backend's on-disk location is decided by its own `root` config — the
+ * plugin could not tell anyone where the data went. Why not `settings.yaml`: that
+ * document is the user's, and it hot-reloads, so writing machine-refreshed data
+ * there both fights the user for the file and republishes configuration for no
+ * reason.
+ *
+ * Every read is best-effort and total: a missing, malformed, foreign, or
+ * stale-schema file reads as a miss. Callers run inside `agent/pre-step`, where a
+ * throw fails the user's step.
+ */
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import type { KbClient } from "./client.js";
+import { listServices, type ServiceEntry } from "./services.js";
+
+/** Bumped whenever the stored shape changes; a mismatch reads as a miss (no migration). */
+const CACHE_VERSION = 1;
+
+/** Refresh interval. Evaluated per `agent/pre-step`, so a short window genuinely takes effect. */
+export const CACHE_TTL_MS = 30 * 60 * 1000;
+
+/**
+ * Refresh interval applied when the cached list is EMPTY.
+ *
+ * An empty list is almost never a settled fact — it is the intermediate state of
+ * a workspace being set up. Caching that negative result for the full TTL breaks
+ * the standard first-run path: configure the plugin against a fresh workspace (0
+ * services) → create a knowledge base and a service → and then wait up to half an
+ * hour before the catalog appears. Re-asking every minute while the answer is
+ * "nothing yet" has a bounded cost and removes that trap.
+ */
+export const EMPTY_CACHE_TTL_MS = 60 * 1000;
+
+/** The stored document. */
+export interface ServiceCacheDocument {
+  version: number;
+  /** Epoch millis of the fetch that produced `entries`. */
+  fetchedAt: number;
+  /** Guards against reading a file written for another account or region. */
+  workspaceId: string;
+  endpointHost: string;
+  entries: ServiceEntry[];
+  total: number;
+  truncated: boolean;
+}
+
+/** Resolve the harness home the same way `settings-file` does. */
+function dshHome(): string {
+  const fromEnv = process.env.DSH_HOME;
+  return fromEnv !== undefined && fromEnv !== "" ? fromEnv : join(homedir(), ".dsh");
+}
+
+/**
+ * Build the cache path for one workspace.
+ * @param workspaceId - the resolved Bailian workspace id.
+ * @param home - override for tests; defaults to `$DSH_HOME` or `~/.dsh`.
+ * @returns the absolute file path.
+ */
+export function serviceCachePath(workspaceId: string, home: string = dshHome()): string {
+  return join(home, "cache", "bailian-kb", `services-${workspaceId}.json`);
+}
+
+/**
+ * Read a cache document, validating it belongs to this workspace and schema.
+ * @param path - the cache file path.
+ * @param workspaceId - the workspace the caller is serving.
+ * @param endpointHost - the host the caller is serving.
+ * @returns the document, or undefined for any miss (absent, malformed, foreign, or wrong version).
+ */
+export function readServiceCache(
+  path: string,
+  workspaceId: string,
+  endpointHost: string,
+): ServiceCacheDocument | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch (_unreadableOrMalformed) {
+    return undefined;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined;
+  const doc = parsed as Partial<ServiceCacheDocument>;
+  if (doc.version !== CACHE_VERSION) return undefined;
+  if (doc.workspaceId !== workspaceId || doc.endpointHost !== endpointHost) return undefined;
+  if (typeof doc.fetchedAt !== "number" || !Array.isArray(doc.entries)) return undefined;
+  return {
+    version: CACHE_VERSION,
+    fetchedAt: doc.fetchedAt,
+    workspaceId,
+    endpointHost,
+    entries: doc.entries,
+    total: typeof doc.total === "number" ? doc.total : doc.entries.length,
+    truncated: doc.truncated === true,
+  };
+}
+
+/**
+ * Publish a cache document atomically: a reader either sees the previous file or
+ * the complete new one, never a half-written mix.
+ * @param path - the cache file path.
+ * @param doc - the document to store.
+ */
+export function writeServiceCache(path: string, doc: ServiceCacheDocument): void {
+  const dir = dirname(path);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const temp = `${path}.${process.pid}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(doc, undefined, 2)}\n`, { mode: 0o600 });
+  renameSync(temp, path);
+}
+
+/** What the settings panel shows about the cache; see {@link ServiceCache.status}. */
+export interface ServiceCacheStatus {
+  workspaceId: string;
+  /** Epoch millis of the last successful fetch; absent when nothing is cached. */
+  fetchedAt?: number;
+  searchCount: number;
+  chatCount: number;
+  /** Server-reported total, which exceeds the counts above when the fetch was capped. */
+  total: number;
+  truncated: boolean;
+  stale: boolean;
+}
+
+export interface ServiceCacheOptions {
+  client: KbClient;
+  /** Resolves the current workspace id; a failure means "not configured yet". */
+  resolveWorkspaceId: () => Promise<string>;
+  endpointHost: string;
+  /** Reports refresh failures without escalating them. */
+  warn: (message: string) => void;
+  /** Test seams. */
+  home?: string;
+  now?: () => number;
+}
+
+/**
+ * The service cache: a synchronous in-memory view over the on-disk document,
+ * plus a deduplicated background refresh.
+ */
+export class ServiceCache {
+  /** Last document read or written; undefined until one is available. */
+  private document: ServiceCacheDocument | undefined;
+  /** The in-flight refresh, if any. One per instance: `pre-step` asks on every model request. */
+  private inFlight: Promise<void> | undefined;
+  /** Workspace of {@link document}, so a workspace switch invalidates in memory too. */
+  private loadedFor: string | undefined;
+
+  constructor(private readonly opts: ServiceCacheOptions) {}
+
+  private get now(): number {
+    return (this.opts.now ?? Date.now)();
+  }
+
+  /**
+   * The cached entries for a workspace, loading the file on first use.
+   * Synchronous and total — safe to call from `agent/pre-step`.
+   * @param workspaceId - the workspace being served.
+   * @returns the document, or undefined when nothing usable is cached.
+   */
+  peek(workspaceId: string): ServiceCacheDocument | undefined {
+    if (this.loadedFor !== workspaceId) {
+      this.document = readServiceCache(
+        serviceCachePath(workspaceId, this.opts.home ?? dshHome()),
+        workspaceId,
+        this.opts.endpointHost,
+      );
+      this.loadedFor = workspaceId;
+    }
+    return this.document;
+  }
+
+  /**
+   * Whether the cached document is missing or older than its TTL.
+   * An empty list expires on the much shorter {@link EMPTY_CACHE_TTL_MS}.
+   * @param workspaceId - the workspace being served.
+   * @returns true when a refresh is due.
+   */
+  isStale(workspaceId: string): boolean {
+    const doc = this.peek(workspaceId);
+    if (doc === undefined) return true;
+    const ttl = doc.entries.length === 0 ? EMPTY_CACHE_TTL_MS : CACHE_TTL_MS;
+    return this.now - doc.fetchedAt >= ttl;
+  }
+
+  /** Drop the in-memory view and force the next `peek` to re-read from disk. */
+  invalidate(): void {
+    this.document = undefined;
+    this.loadedFor = undefined;
+  }
+
+  /**
+   * A diagnostic snapshot for the settings panel.
+   *
+   * The panel exists because this cache's staleness is otherwise invisible: a
+   * developer whose agent silently stops retrieving cannot tell an empty
+   * workspace from a stale list without reading the JSON file. `fetchedAt` plus
+   * the per-scene counts answer that in one glance.
+   * @param workspaceId - the workspace being served.
+   * @returns the snapshot; `fetchedAt` is undefined when nothing is cached.
+   */
+  status(workspaceId: string): ServiceCacheStatus {
+    const doc = this.peek(workspaceId);
+    if (doc === undefined) {
+      return { workspaceId, searchCount: 0, chatCount: 0, total: 0, truncated: false, stale: true };
+    }
+    return {
+      workspaceId,
+      fetchedAt: doc.fetchedAt,
+      searchCount: doc.entries.filter((entry) => entry.scene === "search").length,
+      chatCount: doc.entries.filter((entry) => entry.scene === "chat").length,
+      total: doc.total,
+      truncated: doc.truncated,
+      stale: this.isStale(workspaceId),
+    };
+  }
+
+  /**
+   * The cached entries of one scene, most recently modified first.
+   * Backs the panel's service picker, which exists so a default service can be
+   * chosen by name instead of by pasting a 36-character hex id.
+   * @param workspaceId - the workspace being served.
+   * @param scene - `search` or `chat`.
+   * @returns the entries, newest first.
+   */
+  entriesFor(workspaceId: string, scene: ServiceEntry["scene"]): ServiceEntry[] {
+    const doc = this.peek(workspaceId);
+    if (doc === undefined) return [];
+    return doc.entries
+      .filter((entry) => entry.scene === scene)
+      .sort((left, right) => (right.modify_time ?? "").localeCompare(left.modify_time ?? ""));
+  }
+
+  /**
+   * Fetch and store the current service list.
+   * Never rejects: failures are warned and leave the previous document in place.
+   * Concurrent calls share one request.
+   * @returns a promise resolving once the attempt finishes.
+   */
+  async refresh(): Promise<void> {
+    // Without this guard `pre-step` would start a fetch on every model request
+    // while the first is still outstanding.
+    this.inFlight ??= this.runRefresh().finally(() => {
+      this.inFlight = undefined;
+    });
+    return await this.inFlight;
+  }
+
+  private async runRefresh(): Promise<void> {
+    try {
+      const workspaceId = await this.opts.resolveWorkspaceId();
+      const list = await listServices(this.opts.client);
+      // Both scenes failing means the fetch produced nothing; keep the old file.
+      if (list.failedScenes.length === 2) {
+        this.opts.warn("bailian-kb service cache not refreshed: both scene queries failed");
+        return;
+      }
+      if (list.failedScenes.length > 0) {
+        this.opts.warn(
+          `bailian-kb service cache refreshed without scene(s): ${list.failedScenes.join(", ")}`,
+        );
+      }
+      const doc: ServiceCacheDocument = {
+        version: CACHE_VERSION,
+        fetchedAt: this.now,
+        workspaceId,
+        endpointHost: this.opts.endpointHost,
+        entries: list.entries,
+        total: list.total,
+        truncated: list.truncated,
+      };
+      writeServiceCache(serviceCachePath(workspaceId, this.opts.home ?? dshHome()), doc);
+      this.document = doc;
+      this.loadedFor = workspaceId;
+    } catch (failed) {
+      this.opts.warn(`bailian-kb service cache refresh failed: ${String(failed)}`);
+    }
+  }
+}

packages/bailian-kb-dsh/src/service-catalog.ts

@@ -0,0 +1,246 @@
+/**
+ * Renders the deployed-service catalog the model reads before deciding whether
+ * to retrieve, plus the notice for a workspace that deploys nothing at all.
+ *
+ * These are pure functions on purpose: the selection branches below are the
+ * whole routing policy, and they are far easier to pin down in tests than
+ * through a live pre-step.
+ *
+ * Rendering conventions (settled):
+ * - English frame, service names verbatim — same language as the tool
+ *   descriptions, so the model is not switched between languages mid-prompt.
+ * - Truncation is always stated. Silently cutting the list makes the model treat
+ *   it as complete and flatly answer "there is no such knowledge base".
+ * - An empty scene omits its whole section. `no chat services` is pure noise and
+ *   invites the model to handle a case that does not exist. An empty CATALOG is
+ *   the opposite case and does get a message: see {@link buildNoServiceNotice}.
+ * - `bl` is only ever recommended together with how to get it. This plugin talks
+ *   to the API directly and never shells out, so a fully configured deployment
+ *   can have no `bl` on PATH at all.
+ */
+
+import type { ServiceScene } from "./api-types.js";
+import type { ServiceEntry } from "./services.js";
+
+/** Entries rendered per scene before switching to "most recently modified" mode. */
+export const CATALOG_ENTRY_LIMIT = 10;
+
+/** Truncation applied to a service description once the backend returns one. */
+const DESCRIPTION_LIMIT = 200;
+
+/**
+ * Appended once whenever the text tells the model to look further with `bl`.
+ *
+ * The install line belongs next to the recommendation, not in the tool
+ * descriptions: those are static and every token there is spent on every
+ * request, while this is needed only in the branches that actually name the
+ * command. A single-service catalog never carries it.
+ */
+const BL_AVAILABILITY_NOTE =
+  "(`bl` is the Bailian CLI — install it with `npm install -g bailian-cli` if the command is not found.)";
+
+export interface CatalogInput {
+  entries: readonly ServiceEntry[];
+  /** Server-reported total, which may exceed `entries` when the fetch itself was capped. */
+  total: number;
+  /** True when the fetch stopped before the server ran out of rows. */
+  truncated: boolean;
+  defaultRetrieveAgentId?: string;
+  defaultChatAgentId?: string;
+}
+
+const SCENE_LABEL: Record<ServiceScene, string> = {
+  search: "kb_search (retrieval)",
+  chat: "kb_chat (grounded Q&A)",
+};
+
+/** Render one entry as a single line. */
+function renderEntry(entry: ServiceEntry): string {
+  const name = entry.agent_name === "" ? "(unnamed)" : entry.agent_name;
+  const description =
+    entry.description === undefined || entry.description.trim() === ""
+      ? undefined
+      : entry.description.trim().length > DESCRIPTION_LIMIT
+        ? `${entry.description.trim().slice(0, DESCRIPTION_LIMIT - 1)}…`
+        : entry.description.trim();
+  return `- ${entry.agent_id} — ${name}${description === undefined ? "" : `: ${description}`}`;
+}
+
+/** Most recently modified first; entries without a timestamp sort last. */
+function byRecency(left: ServiceEntry, right: ServiceEntry): number {
+  const l = left.modify_time ?? "";
+  const r = right.modify_time ?? "";
+  if (l === r) return 0;
+  if (l === "") return 1;
+  if (r === "") return -1;
+  return l < r ? 1 : -1;
+}
+
+/**
+ * Render one scene's section, or undefined when the scene has no services.
+ * @param entries - all cached entries (any scene).
+ * @param scene - the scene to render.
+ * @param defaultAgentId - this scene's configured default service, when set.
+ * @param truncatedFetch - whether the fetch itself left rows unread.
+ * @returns the section lines, or undefined to omit the section entirely.
+ */
+function renderScene(
+  entries: readonly ServiceEntry[],
+  scene: ServiceScene,
+  defaultAgentId: string | undefined,
+  truncatedFetch: boolean,
+): { lines: string[]; usedLookupHint: boolean } | undefined {
+  const forScene = entries.filter((entry) => entry.scene === scene);
+  if (forScene.length === 0) return undefined;
+  const lines = [`${SCENE_LABEL[scene]}:`];
+
+  const configured =
+    defaultAgentId === undefined
+      ? undefined
+      : forScene.find((entry) => entry.agent_id === defaultAgentId);
+  if (configured !== undefined) {
+    // A configured default is the user's own pick: the highest-quality signal
+    // available, so it is the only entry worth spending context on.
+    lines.push(renderEntry(configured));
+    const others = forScene.length - 1;
+    if (others > 0) {
+      lines.push(
+        `  (default service; ${others} other${others === 1 ? "" : "s"} exist — ` +
+          `run \`bl knowledge service list --scene ${scene}\` to see them)`,
+      );
+      return { lines, usedLookupHint: true };
+    }
+    return { lines, usedLookupHint: false };
+  }
+
+  if (forScene.length <= CATALOG_ENTRY_LIMIT && !truncatedFetch) {
+    lines.push(...forScene.map(renderEntry));
+    return { lines, usedLookupHint: false };
+  }
+
+  const shown = [...forScene].sort(byRecency).slice(0, CATALOG_ENTRY_LIMIT);
+  lines.push(...shown.map(renderEntry));
+  // State the shortfall: the model must know this list is partial before it
+  // concludes no service covers the question.
+  const knownTotal = Math.max(forScene.length, shown.length);
+  lines.push(
+    `  (showing ${shown.length} most recently modified of ${truncatedFetch ? "more than " : ""}` +
+      `${knownTotal} deployed ${scene} services — run \`bl knowledge service list --scene ${scene} ` +
+      "--name <keyword>` to look for others)",
+  );
+  return { lines, usedLookupHint: true };
+}
+
+/**
+ * The notice injected when the workspace is reachable but deploys nothing the
+ * tools can call.
+ *
+ * This deliberately contradicts the "omit what does not exist" rule above, and
+ * the cases are not symmetric: an empty SECTION is noise because the other
+ * section still hands the model ids, whereas an empty CATALOG leaves it with no
+ * id at all while `agent_id` stays required. With nothing said, the model either
+ * invents an id — earning a raw server rejection — or silently drops the
+ * retrieval; both read to the user as a broken plugin when the real answer is
+ * "deploy a service". Naming the fix is the only way out that does not require
+ * the model to already have loaded the management skill.
+ * @returns the model-facing notice text.
+ */
+export function buildNoServiceNotice(): string {
+  return [
+    "<system-reminder>",
+    "The Bailian knowledge tools (kb_search / kb_chat) are configured, but this workspace has no " +
+      "deployed knowledge service, so neither tool can be called: both require an `agent_id` and there " +
+      "is none to use. Do not call them, and do not invent an id.",
+    "",
+    "If the user asks for something that should come from their knowledge base, tell them a service has " +
+      "to be created and deployed first — in the Bailian console (https://bailian.console.aliyun.com/), " +
+      "or with `bl knowledge service create` followed by `bl knowledge service deploy`. " +
+      BL_AVAILABILITY_NOTE,
+    "</system-reminder>",
+  ].join("\n");
+}
+
+/**
+ * The service list appended to a call the server rejected, rendered from a
+ * just-refreshed cache.
+ *
+ * Lives here rather than at the call site so every model-facing rendering obeys
+ * the one set of conventions documented at the top of this file — in particular
+ * that a shortfall is stated and that `bl` never appears without its install
+ * line.
+ * @param scene - the scene the failed call targeted.
+ * @param entries - that scene's entries as of the refresh, newest first.
+ * @returns the text to append to the failure.
+ */
+export function buildRefreshedSceneList(
+  scene: ServiceScene,
+  entries: readonly ServiceEntry[],
+): string {
+  if (entries.length === 0) return buildNoSceneServiceNotice(scene);
+  const shown = entries.slice(0, CATALOG_ENTRY_LIMIT);
+  const more = entries.length - shown.length;
+  return [
+    `Deployed ${scene} services in this workspace, re-read just now:`,
+    ...shown.map(renderEntry),
+    ...(more > 0
+      ? [
+          `(and ${more} more — run \`bl knowledge service list --scene ${scene}\` to see them) ` +
+            BL_AVAILABILITY_NOTE,
+        ]
+      : []),
+  ].join("\n");
+}
+
+/**
+ * What a rejected call is told when the refreshed list holds no service for that
+ * scene at all.
+ *
+ * The tool has already failed by this point, so this text is the model's only
+ * instruction. Without it the bare server rejection ("invalid agent_id") invites
+ * a retry with another guess, and no guess can succeed.
+ * @param scene - the scene whose services came back empty.
+ * @returns the text to append to the failure.
+ */
+function buildNoSceneServiceNotice(scene: ServiceScene): string {
+  return (
+    `This workspace has no deployed ${scene} services at all (re-checked just now), so no agent_id can ` +
+    "work — do not retry with a different id. Tell the user one has to be created and deployed, in the " +
+    "Bailian console (https://bailian.console.aliyun.com/) or with `bl knowledge service create` " +
+    `followed by \`bl knowledge service deploy\`. ${BL_AVAILABILITY_NOTE}`
+  );
+}
+
+/**
+ * Build the catalog text for one cached service list.
+ * @param input - the cached entries plus the deployment's configured defaults.
+ * @returns the model-facing text, or undefined when there is nothing worth injecting.
+ */
+export function buildServiceCatalog(input: CatalogInput): string | undefined {
+  const search = renderScene(
+    input.entries,
+    "search",
+    input.defaultRetrieveAgentId,
+    input.truncated,
+  );
+  const chat = renderScene(input.entries, "chat", input.defaultChatAgentId, input.truncated);
+  if (search === undefined && chat === undefined) return undefined;
+  const usedLookupHint = search?.usedLookupHint === true || chat?.usedLookupHint === true;
+  return [
+    "<system-reminder>",
+    // The header must not name the tools: a scene with no services omits its
+    // section, and naming that tool anyway would invite passing an id from the
+    // other scene, which the service rejects. Section labels carry the mapping.
+    "Bailian knowledge services deployed in this workspace, grouped by the tool that accepts them. " +
+      "Pass an id from the matching section as that tool's `agent_id` argument — it is required and " +
+      "cannot be guessed.",
+    "",
+    ...(search?.lines ?? []),
+    ...(search !== undefined && chat !== undefined ? [""] : []),
+    ...(chat?.lines ?? []),
+    "",
+    "If none of these services covers what the user is asking about, say so plainly rather than " +
+      "trying the closest-looking id — an unrelated retrieval result is worse than none.",
+    ...(usedLookupHint ? [BL_AVAILABILITY_NOTE] : []),
+    "</system-reminder>",
+  ].join("\n");
+}

packages/bailian-kb-dsh/src/service-context.ts

@@ -0,0 +1,152 @@
+/**
+ * Publishes the cached service catalog into each request as a sourced context
+ * message, on the `agent/pre-step` waterfall.
+ *
+ * Why a context message rather than the tool descriptions: a tool description is
+ * fixed when the plugin loads, and a plugin loads once per PROCESS, not once per
+ * session. In a long-running host the TTL would be evaluated exactly once at
+ * `apply()` and a service created elsewhere would never be noticed until a
+ * restart. Re-registering tools to refresh a description instead invalidates the
+ * prompt prefix cache from the first changed schema token. Injecting context
+ * keeps the tool schemas byte-stable forever and still refreshes per step.
+ *
+ * Two hard constraints follow from `agent/pre-step` semantics:
+ *
+ * 1. `pre-step` fires once per STEP, and a step is one model request — a turn with
+ *    five tool calls fires it six times. Re-injecting each time would insert six
+ *    copies into one turn and void the KV cache from the first insertion onward,
+ *    so change suppression is a correctness requirement, not an optimization.
+ * 2. A throwing listener fails the proposed step, i.e. the user's turn stalls.
+ *    Everything here is therefore wrapped: any failure degrades to "inject
+ *    nothing this step".
+ */
+
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent, PreStepDecision } from "@deepseek-ai/dsh-agent";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import type { UserMessage } from "@deepseek-ai/dsh-session";
+import { buildNoServiceNotice, buildServiceCatalog } from "./service-catalog.js";
+import type { ServiceCache } from "./service-cache.js";
+
+/** Marks this plugin's own injections in the durable log. */
+const SOURCE_PLUGIN = "tool-bailian-kb/services";
+
+export interface ServiceContextOptions {
+  cache: ServiceCache;
+  /** Resolves the workspace being served; undefined means "not configured yet". */
+  resolveWorkspaceId: () => Promise<string | undefined>;
+  /** Resolves the configured default retrieval service (settings then credential). */
+  resolveDefaultRetrieveAgentId: () => Promise<string | undefined>;
+  /** Resolves the configured default chat service (settings then credential). */
+  resolveDefaultChatAgentId: () => Promise<string | undefined>;
+  warn: (message: string) => void;
+}
+
+/** Whether one durable message came from this module. */
+function isOwnInjection(source: { kind: string; plugin?: string }): boolean {
+  return source.kind === "plugin" && source.plugin === SOURCE_PLUGIN;
+}
+
+/** Concatenate a message's text parts, which is what the model actually reads. */
+function messageText(message: UserMessage): string {
+  return message.content.flatMap((part) => (part.type === "text" ? [part.text] : [])).join("\n");
+}
+
+/**
+ * The catalog text this session last injected AND still shows the model.
+ *
+ * The visibility test is the subtle half. Scanning only for "did we ever publish
+ * this" would make compaction permanent data loss: once the catalog message is
+ * dropped from the surface, an identical digest would suppress every future
+ * injection and the model would silently spend the rest of the session without a
+ * service list.
+ * @param agent - the subject agent.
+ * @returns the visible catalog text, or undefined when none is currently visible.
+ */
+function visibleCatalogText(agent: Agent): string | undefined {
+  const visible = new Set(agent.session.surface.nodes);
+  const events = agent.session.events;
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index];
+    if (event === undefined) continue;
+    if (event.type !== "user/message" || !isOwnInjection(event.data.source)) continue;
+    return visible.has(event.seq) ? messageText(event.data) : undefined;
+  }
+  return undefined;
+}
+
+/** This module's proposed-but-not-yet-entered message, if the batch already carries one. */
+function pendingCatalog(messages: readonly UserMessage[]): UserMessage | undefined {
+  return messages.find((message) => isOwnInjection(message.source));
+}
+
+/**
+ * Install the pre-step listener that keeps the catalog present and current.
+ * @param ctx - a context with `agents` available.
+ * @param opts - the cache plus the deployment's resolved workspace and defaults.
+ */
+export function installServiceContext(ctx: Context, opts: ServiceContextOptions): void {
+  ctx.on(
+    "agent/pre-step",
+    async ({ agent, signal }, next): Promise<PreStepDecision> => {
+      const decision = await next();
+      if (decision.kind === "reject" || signal.aborted) return decision;
+      try {
+        const workspaceId = await opts.resolveWorkspaceId();
+        // Nothing is configured yet: the tools themselves will explain that.
+        if (workspaceId === undefined || workspaceId === "") return decision;
+
+        // Refresh scheduling lives here, not at plugin load, so a long-running
+        // process still notices services created elsewhere. Never awaited: a slow
+        // list request must not delay the user's request.
+        if (opts.cache.isStale(workspaceId)) void opts.cache.refresh();
+
+        const document = opts.cache.peek(workspaceId);
+        // No document at all means the first fetch has not landed (or is
+        // failing): we know nothing, so claiming anything would be a guess. The
+        // refresh above self-corrects this on a later step.
+        if (document === undefined) return decision;
+        const [defaultRetrieveAgentId, defaultChatAgentId] = await Promise.all([
+          opts.resolveDefaultRetrieveAgentId(),
+          opts.resolveDefaultChatAgentId(),
+        ]);
+        if (signal.aborted) return decision;
+        // A document with zero entries is the opposite: an authoritative "this
+        // workspace deploys nothing callable". Saying so beats silence, which
+        // leaves the model to invent a required agent_id.
+        const text =
+          buildServiceCatalog({
+            entries: document.entries,
+            total: document.total,
+            truncated: document.truncated,
+            ...(defaultRetrieveAgentId !== undefined ? { defaultRetrieveAgentId } : {}),
+            ...(defaultChatAgentId !== undefined ? { defaultChatAgentId } : {}),
+          }) ?? buildNoServiceNotice();
+
+        // Identical to what the model already sees: stay out of the way. This is
+        // the branch that runs on nearly every step.
+        if (visibleCatalogText(agent) === text) return decision;
+
+        const pending = pendingCatalog(decision.messages);
+        if (pending !== undefined && messageText(pending) === text) return decision;
+
+        const catalog = createUserMessage({
+          content: [{ type: "text", text }],
+          source: { kind: "plugin", plugin: SOURCE_PLUGIN, form: "catalog" },
+        });
+        return {
+          kind: "enter",
+          messages:
+            pending === undefined
+              ? [...decision.messages, catalog]
+              : decision.messages.map((message) => (message.id === pending.id ? catalog : message)),
+        };
+      } catch (failed) {
+        // A throw here would fail the user's step; a missing catalog is far cheaper.
+        opts.warn(`bailian-kb service catalog not injected: ${String(failed)}`);
+        return decision;
+      }
+    },
+    { prepend: true },
+  );
+}

packages/bailian-kb-dsh/src/services.ts

@@ -0,0 +1,109 @@
+/**
+ * Retrieval-service discovery for the plugin's internal cache. Not a model tool:
+ * see `KB_PATHS.serviceList`.
+ *
+ * Listing is paged, and a workspace can hold far more services than are useful
+ * for routing, so this module stops after {@link MAX_PAGES} and reports the
+ * shortfall rather than paging through everything. Only deployed services are
+ * requested: anything else is not callable by the default service version, so it
+ * would be noise in the catalog the model reads.
+ */
+
+import type { ServiceListResponse, ServiceScene } from "./api-types.js";
+import type { KbClient } from "./client.js";
+import { KB_PATHS } from "./endpoints.js";
+
+/** Page size requested per listing call. */
+const PAGE_SIZE = 100;
+
+/** Pages fetched per scene before reporting truncation; well past the useful routing range. */
+const MAX_PAGES = 2;
+
+/** One deployed retrieval or Q&A service, reduced to the fields that inform routing. */
+export interface ServiceEntry {
+  agent_id: string;
+  agent_name: string;
+  scene: ServiceScene;
+  /** Deployment status as reported for the service; only callable states are listed. */
+  status: string;
+  /** Last modification timestamp; the only signal for "which of these is in use". */
+  modify_time?: string;
+  /** Service description, when the listing provides one. */
+  description?: string;
+}
+
+export interface ServiceList {
+  entries: ServiceEntry[];
+  /** Server-reported total across the queried scenes, including rows never fetched. */
+  total: number;
+  /** True when a scene reported more rows than {@link MAX_PAGES} pages returned. */
+  truncated: boolean;
+  /** Scenes whose query failed; a partial list stays usable. */
+  failedScenes: ServiceScene[];
+}
+
+const SCENES: readonly ServiceScene[] = ["search", "chat"];
+
+/**
+ * Fetch the deployed services of one scene, stopping at the page cap.
+ * @param client - the shared knowledge API client.
+ * @param scene - `search` or `chat`.
+ * @returns the scene's entries, its server-reported total, and whether rows were left unfetched.
+ */
+async function listScene(
+  client: KbClient,
+  scene: ServiceScene,
+): Promise<{ entries: ServiceEntry[]; total: number; truncated: boolean }> {
+  const entries: ServiceEntry[] = [];
+  let total = 0;
+  for (let page = 1; page <= MAX_PAGES; page += 1) {
+    const res = await client.postJson<ServiceListResponse>(KB_PATHS.serviceList, {
+      agent_scene: scene,
+      agent_status: "deployed",
+      page_number: page,
+      page_size: PAGE_SIZE,
+    });
+    total = res.data?.total_count ?? total;
+    const rows = res.data?.rows ?? [];
+    for (const row of rows) {
+      const agentId = row.agent_id ?? "";
+      // A row without an id cannot be called, so it has no reason to exist here.
+      if (agentId === "") continue;
+      entries.push({
+        agent_id: agentId,
+        agent_name: row.agent_name ?? "",
+        scene,
+        status: row.agent_status ?? "",
+        ...(typeof row.modify_time === "string" ? { modify_time: row.modify_time } : {}),
+      });
+    }
+    // A short page is the last page; the server has nothing further to give.
+    if (rows.length < PAGE_SIZE) return { entries, total, truncated: false };
+  }
+  return { entries, total, truncated: total > entries.length };
+}
+
+/**
+ * List the deployed services of both scenes.
+ * A scene that fails is recorded and skipped rather than failing the whole
+ * refresh: half a list still routes better than none.
+ * @param client - the shared knowledge API client.
+ * @returns merged entries plus totals, truncation, and per-scene failures.
+ */
+export async function listServices(client: KbClient): Promise<ServiceList> {
+  const entries: ServiceEntry[] = [];
+  const failedScenes: ServiceScene[] = [];
+  let total = 0;
+  let truncated = false;
+  for (const scene of SCENES) {
+    try {
+      const result = await listScene(client, scene);
+      entries.push(...result.entries);
+      total += result.total;
+      truncated = truncated || result.truncated;
+    } catch (_sceneFailed) {
+      failedScenes.push(scene);
+    }
+  }
+  return { entries, total, truncated, failedScenes };
+}

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

@@ -0,0 +1,138 @@
+/**
+ * Runtime skill registration: the packaged bailian-kb SKILL.md joins the catalog
+ * when a skills registry is composed.
+ *
+ * The file's YAML frontmatter is the single source of truth for the routing name
+ * and description — duplicating them here drifts, and the copy that loses is the
+ * one nobody reads. The frontmatter must also be STRIPPED from the registered
+ * body: `SkillDefinition.content` is contractually the body a provider has
+ * already cleaned of its own metadata, and `ctx.skills.register()` parses
+ * nothing, so handing over the raw file ships the YAML block into the model's
+ * context.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+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/", import.meta.url));
+
+/** The registrable fields carried by one skill file. */
+export interface ParsedSkillFile {
+  /** Kebab-case skill name from frontmatter. */
+  name: string;
+  /** Routing description from frontmatter (the catalog truncates at 500 chars). */
+  description: string;
+  /** Optional extra routing guidance. */
+  whenToUse?: string;
+  /** Optional frontmatter `metadata` object. */
+  metadata?: Record<string, unknown>;
+  /** Markdown body with the frontmatter block removed. */
+  content: string;
+}
+
+/**
+ * Locate the frontmatter block, mirroring the filesystem provider's delimiters
+ * so a file that loads from disk behaves identically when bundled.
+ * @param raw - the file's full text.
+ * @returns the frontmatter YAML and the body after it, or undefined when unfenced.
+ */
+function splitFrontmatter(raw: string): { yaml: string; body: string } | undefined {
+  const firstLineEnd = raw.indexOf("\n");
+  if (firstLineEnd < 0) return undefined;
+  if (raw.slice(0, firstLineEnd).replace(/\r$/, "") !== "---") return undefined;
+  const start = firstLineEnd + 1;
+  let lineStart = start;
+  while (lineStart <= raw.length) {
+    const nextNewline = raw.indexOf("\n", lineStart);
+    const lineEnd = nextNewline < 0 ? raw.length : nextNewline;
+    if (raw.slice(lineStart, lineEnd).replace(/\r$/, "") === "---") {
+      return {
+        yaml: raw.slice(start, lineStart),
+        body: raw.slice(nextNewline < 0 ? raw.length : nextNewline + 1),
+      };
+    }
+    if (nextNewline < 0) return undefined;
+    lineStart = nextNewline + 1;
+  }
+  return undefined;
+}
+
+/**
+ * Parse one skill file into its registrable fields.
+ * @param raw - the file's full text.
+ * @returns the parsed fields, or undefined when the frontmatter is absent, unparsable, or missing name/description.
+ */
+export function parseSkillFile(raw: string): ParsedSkillFile | undefined {
+  const split = splitFrontmatter(raw);
+  if (split === undefined) return undefined;
+  let data: unknown;
+  try {
+    data = parseYaml(split.yaml);
+  } catch (_invalidYaml) {
+    return undefined;
+  }
+  if (typeof data !== "object" || data === null || Array.isArray(data)) return undefined;
+  const record = data as Record<string, unknown>;
+  const name = typeof record.name === "string" ? record.name.trim() : "";
+  const description = typeof record.description === "string" ? record.description.trim() : "";
+  // The registry rejects a blank description outright; failing here keeps the
+  // diagnostic on the file instead of on the registration call.
+  if (name === "" || description === "") return undefined;
+  const whenToUse = typeof record.whenToUse === "string" ? record.whenToUse.trim() : "";
+  const metadata =
+    typeof record.metadata === "object" &&
+    record.metadata !== null &&
+    !Array.isArray(record.metadata)
+      ? (record.metadata as Record<string, unknown>)
+      : undefined;
+  return {
+    name,
+    description,
+    ...(whenToUse !== "" ? { whenToUse } : {}),
+    ...(metadata !== undefined ? { metadata } : {}),
+    content: split.body,
+  };
+}
+
+/**
+ * Register the management skill when the skills registry is composed; headless
+ * assemblies without the seam stay unaffected. An unreadable or malformed file
+ * degrades to a warning — a broken bundled asset must not fail plugin load.
+ * @param ctx - the plugin context.
+ */
+export function registerSkill(ctx: Context): void {
+  ctx.inject(["skills"], (skillCtx) => {
+    const path = join(SKILL_DIR, "SKILL.md");
+    let raw: string;
+    try {
+      raw = readFileSync(path, "utf8");
+    } catch (unreadable) {
+      skillCtx.logger.warn(
+        `bailian-kb skill not registered: cannot read ${path}: ${String(unreadable)}`,
+      );
+      return;
+    }
+    const parsed = parseSkillFile(raw);
+    if (parsed === undefined) {
+      skillCtx.logger.warn(
+        `bailian-kb skill not registered: ${path} needs YAML frontmatter carrying name and description`,
+      );
+      return;
+    }
+    skillCtx.skills.register({
+      name: parsed.name,
+      description: parsed.description,
+      ...(parsed.whenToUse !== undefined ? { whenToUse: parsed.whenToUse } : {}),
+      ...(parsed.metadata !== undefined ? { metadata: parsed.metadata } : {}),
+      content: parsed.content,
+      source: "bundled",
+      path,
+      resourceBase: { kind: "directory", path: SKILL_DIR },
+    });
+  });
+}

packages/bailian-kb-dsh/src/sse.ts

@@ -0,0 +1,51 @@
+/** Minimal SSE parser for the knowledge chat stream: `event:`/`data:` lines, events split on blank lines. */
+
+export interface SseEvent {
+  event?: string;
+  data: string;
+}
+
+/**
+ * Parse one SSE byte stream into events.
+ * @param body - the response body stream.
+ * @returns events in stream order; multi-`data:` events join with newlines per the SSE spec.
+ */
+export async function* parseSseStream(body: ReadableStream<Uint8Array>): AsyncGenerator<SseEvent> {
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let event: string | undefined;
+  let data: string[] = [];
+
+  const flush = (): SseEvent | undefined => {
+    if (data.length === 0) return undefined;
+    const out = { event, data: data.join("\n") };
+    event = undefined;
+    data = [];
+    return out;
+  };
+
+  const reader = body.getReader();
+  while (true) {
+    const { done, value } = await reader.read();
+    buffer += done ? "" : decoder.decode(value, { stream: true });
+    let newline: number;
+    while ((newline = buffer.indexOf("\n")) !== -1) {
+      const line = buffer.slice(0, newline).replace(/\r$/, "");
+      buffer = buffer.slice(newline + 1);
+      if (line === "") {
+        const out = flush();
+        if (out) yield out;
+      } else if (line.startsWith("event:")) {
+        event = line.slice(6).trim();
+      } else if (line.startsWith("data:")) {
+        data.push(line.slice(5).trimStart());
+      }
+      // comment/id/retry lines are irrelevant to this API and are skipped
+    }
+    if (done) {
+      const out = flush();
+      if (out) yield out;
+      return;
+    }
+  }
+}

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

@@ -0,0 +1,292 @@
+/**
+ * The two model-facing knowledge tools (kb_search, kb_chat). agent_id is REQUIRED in the schema:
+ * a model cannot know from the tool spec whether this deployment configures a default service, and a
+ * missing default previously only surfaced at call time, forcing a wasted round-trip. The per-call
+ * fallback to a configured default (settings/config or credential) is retained as defense-in-depth,
+ * but note defineTool validates args against the schema before execute, so through that entry point
+ * the fallback is inert; the model-facing contract is explicit.
+ *
+ * These descriptions are deliberately STATIC. The available service ids are
+ * deployment state that changes while the process runs, and re-registering a tool
+ * to refresh its description invalidates the prompt prefix cache from the first
+ * changed schema token. The live catalog therefore rides an `agent/pre-step`
+ * context message instead (see `service-context.ts`), leaving these schemas
+ * byte-stable for the life of the process.
+ *
+ * Being static is also why recovery instructions do NOT live here: how to look
+ * further depends on what is actually deployed, and a token spent in a
+ * description is spent on every request. The dynamic carriers own that — the
+ * catalog message states a shortfall where one exists, and a rejected call comes
+ * back with the services that do exist (`service-catalog.ts`).
+ */
+
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import type { SearchRequest, SearchResponse } from "./api-types.js";
+import { KbApiError, type KbClient } from "./client.js";
+import { consumeChatStream } from "./chat.js";
+import { KB_PATHS } from "./endpoints.js";
+
+/** Client-side chunk cap applied when the model omits top_k. */
+const DEFAULT_TOP_K = 5;
+
+export interface KbToolDeps {
+  client: KbClient;
+  /** Resolves the default retrieval agent id per call (settings/patch config or credential); omitted means no default for kb_search. */
+  resolveDefaultRetrieveAgentId?: () => Promise<string | undefined>;
+  /** Resolves the default chat agent id per call (settings/patch config or credential); omitted means no default for kb_chat. */
+  resolveDefaultChatAgentId?: () => Promise<string | undefined>;
+  /**
+   * Refreshes the service cache and summarizes what the workspace currently
+   * deploys for one scene. Called only after a client-side API failure, so a
+   * stale cached id self-corrects within the same step instead of waiting for the
+   * next scheduled refresh.
+   */
+  describeServicesAfterRefresh?: (scene: "search" | "chat") => Promise<string | undefined>;
+  /** Read per call (a live-settings deployment supplies a getter). */
+  chatTimeoutMs: number;
+}
+
+/**
+ * Rethrow an API failure, appending a freshly refreshed service list when the
+ * server rejected the request.
+ *
+ * On these two endpoints `agent_id` is the only caller-supplied identifier, so a
+ * 4xx is most often a service id that no longer exists — the recovery the model
+ * needs is the current list, delivered in the error message. The message is
+ * ordinary conversation text appended at the tail, so unlike a re-registered
+ * description it does not disturb the request prefix.
+ */
+async function withServiceHint(
+  err: unknown,
+  scene: "search" | "chat",
+  describe: KbToolDeps["describeServicesAfterRefresh"],
+): Promise<never> {
+  if (describe === undefined || !(err instanceof KbApiError)) throw err;
+  const status = err.status;
+  if (status === undefined || status < 400 || status >= 500) throw err;
+  // Best-effort enrichment: a failing refresh must not replace the real error.
+  const summary = await describe(scene).catch(() => undefined);
+  if (summary === undefined) throw err;
+  throw new KbApiError(
+    `${err.message}
+
+${summary}`,
+    status,
+  );
+}
+
+/**
+ * Build the two tool definitions over one shared client.
+ * @param deps - client plus the deployment's explicit pinning and timeout choices.
+ * @returns definitions ready for `ctx.tools.register()`.
+ */
+export function createKbTools(deps: KbToolDeps) {
+  // chatTimeoutMs is deliberately NOT destructured: reading it off deps at
+  // execute time keeps a live-settings getter live.
+  const { client, resolveDefaultRetrieveAgentId, resolveDefaultChatAgentId } = deps;
+  const agentIdParam = {
+    type: "string" as const,
+    required: true as const,
+    description:
+      "Retrieval/Q&A service id. REQUIRED: the schema cannot know whether this deployment " +
+      "configures a default service, so always pass one. This conversation carries a context message " +
+      "listing the services deployed in the workspace — take the id from the section matching the tool " +
+      "you are calling. When that list is absent, or none of its services covers the question, say so " +
+      "rather than guessing: a rejected id is answered with the services that do exist, so a guess buys " +
+      "nothing.",
+  };
+  const resolveRetrieveAgentId = async (supplied: string | undefined): Promise<string> => {
+    if (supplied !== undefined) return supplied;
+    const defaultId =
+      resolveDefaultRetrieveAgentId === undefined
+        ? undefined
+        : await resolveDefaultRetrieveAgentId();
+    if (defaultId === undefined) {
+      throw new Error(
+        "agent_id is required: no default retrieval service is configured. Pass agent_id explicitly " +
+          "(find ids: `bl knowledge service list --scene search --workspace-id <workspaceId>`), or configure a " +
+          "default: bailian-kb.defaultRetrieveAgentId in ~/.dsh/settings.yaml or " +
+          "BAILIAN_DEFAULT_RETRIEVE_AGENT_ID in ~/.dsh/.credentials.yaml.",
+      );
+    }
+    return defaultId;
+  };
+  const resolveChatAgentId = async (supplied: string | undefined): Promise<string> => {
+    if (supplied !== undefined) return supplied;
+    const defaultId =
+      resolveDefaultChatAgentId === undefined ? undefined : await resolveDefaultChatAgentId();
+    if (defaultId === undefined) {
+      throw new Error(
+        "agent_id is required: no default chat service is configured. Pass agent_id explicitly " +
+          "(find ids: `bl knowledge service list --scene chat --workspace-id <workspaceId>`), or configure a " +
+          "default: bailian-kb.defaultChatAgentId in ~/.dsh/settings.yaml or " +
+          "BAILIAN_DEFAULT_CHAT_AGENT_ID in ~/.dsh/.credentials.yaml.",
+      );
+    }
+    return defaultId;
+  };
+
+  const search = defineTool({
+    name: "kb_search",
+    description:
+      "Semantic search over a Bailian knowledge base. Returns raw knowledge chunks with scores and source " +
+      "references for you to verify, cite, or combine with other context. Retrieval scope and strategy " +
+      "(multi-KB weighting, routing, reranking) come from the service configuration. " +
+      "top_k caps how many chunks return (client-side cut of the score-ranked results). " +
+      "Use kb_chat instead when the user question can be answered by the knowledge base alone. " +
+      "Credentials and workspace resolve automatically from DSH config " +
+      "(bailian-kb in ~/.dsh/settings.yaml, DASHSCOPE_API_KEY in ~/.dsh/.credentials.yaml) — " +
+      "never read or pass them yourself. agent_id is REQUIRED (see its parameter description). " +
+      "If no listed service covers what the user is asking about, say so plainly rather than trying " +
+      "the closest-looking id: unrelated evidence is worse for the user than none.",
+    parameters: {
+      query: { type: "string", required: true, description: "Search query text." },
+      agent_id: agentIdParam,
+      top_k: {
+        type: "integer",
+        description: `Maximum chunks to return; defaults to ${DEFAULT_TOP_K}.`,
+      },
+      images: {
+        type: "array",
+        items: { type: "string" },
+        description: "Image URLs for multimodal retrieval.",
+      },
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          chunks: {
+            type: "array",
+            required: true,
+            items: {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                text: { type: "string", required: true },
+                score: { type: "number", required: true },
+                doc_name: { type: "string" },
+                doc_id: { type: "string" },
+                title: { type: "string" },
+              },
+            },
+          },
+          total: { type: "integer", required: true },
+        },
+      },
+      render: (_args, value) => [
+        {
+          type: "text",
+          text:
+            value.chunks.length === 0
+              ? "No matching knowledge chunks."
+              : value.chunks
+                  .map(
+                    (c, i) =>
+                      `[${i + 1}] (score ${c.score.toFixed(2)}${c.doc_name ? `, ${c.doc_name}` : ""}) ${c.text}`,
+                  )
+                  .join("\n"),
+        },
+      ],
+    },
+    async execute(args) {
+      const topK = args.top_k ?? DEFAULT_TOP_K;
+      const body: SearchRequest = {
+        query: args.query,
+        agent_id: await resolveRetrieveAgentId(args.agent_id),
+        ...(client.agentVersion ? { agent_version: client.agentVersion } : {}),
+        ...(args.images && args.images.length > 0 ? { images: args.images } : {}),
+      };
+      const res = await client
+        .postJson<SearchResponse>(KB_PATHS.search, body)
+        .catch(
+          async (err) => await withServiceHint(err, "search", deps.describeServicesAfterRefresh),
+        );
+      const nodes = (res.data?.nodes ?? []).slice(0, topK);
+      return {
+        chunks: nodes.map((n) => ({
+          text: n.text,
+          score: n.score,
+          ...(typeof n.metadata?.doc_name === "string" ? { doc_name: n.metadata.doc_name } : {}),
+          ...(typeof n.metadata?.doc_id === "string" ? { doc_id: n.metadata.doc_id } : {}),
+          ...(typeof n.metadata?.title === "string" ? { title: n.metadata.title } : {}),
+        })),
+        total: res.data?.total ?? nodes.length,
+      };
+    },
+    presentCall: (args) => ({
+      card: "generic",
+      title: "Search knowledge base",
+      kind: "search",
+      rawInput: args,
+    }),
+  });
+
+  const chat = defineTool({
+    name: "kb_chat",
+    description:
+      "Ask the knowledge base directly and get a complete, domain-tuned answer from a specialized RAG pipeline " +
+      "(multi-round retrieval + reranking + grounded generation). For knowledge Q&A this typically outperforms " +
+      "searching and synthesizing yourself when the question can be answered by the knowledge base alone; " +
+      "use kb_search instead when you need raw chunks to verify, cite, or combine with other work. " +
+      "The pipeline runs an internal analysis/retrieval loop and may take a few minutes. " +
+      "Credentials and workspace resolve automatically from DSH config " +
+      "(bailian-kb in ~/.dsh/settings.yaml, DASHSCOPE_API_KEY in ~/.dsh/.credentials.yaml) — " +
+      "never read or pass them yourself. agent_id is REQUIRED (see its parameter description). " +
+      "If no listed service covers what the user is asking about, say so plainly rather than trying " +
+      "the closest-looking id.",
+    parameters: {
+      message: { type: "string", required: true, description: "The question to ask." },
+      agent_id: agentIdParam,
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          answer: { type: "string", required: true },
+          request_id: { type: "string" },
+        },
+      },
+      render: (_args, value) => [
+        { type: "text", text: value.answer.length === 0 ? "(empty answer)" : value.answer },
+      ],
+    },
+    async execute(args) {
+      const chatTimeoutMs = deps.chatTimeoutMs;
+      const body = {
+        input: { messages: [{ role: "user" as const, content: args.message }] },
+        parameters: {
+          agent_options: {
+            agent_id: await resolveChatAgentId(args.agent_id),
+            ...(client.agentVersion ? { agent_version: client.agentVersion } : {}),
+          },
+        },
+        stream: true as const,
+      };
+      let res: Response;
+      try {
+        res = await client.postSse(KB_PATHS.chat, body, AbortSignal.timeout(chatTimeoutMs));
+      } catch (err) {
+        if (err instanceof Error && err.name === "TimeoutError") {
+          throw new Error(
+            `knowledge chat timed out after ${chatTimeoutMs}ms; the pipeline runs a multi-round retrieval loop ` +
+              "and long questions can exceed the deployment timeout. Retry, or use kb_search for raw chunks instead.",
+          );
+        }
+        return await withServiceHint(err, "chat", deps.describeServicesAfterRefresh);
+      }
+      const { answer, requestId } = await consumeChatStream(res);
+      return { answer, ...(requestId ? { request_id: requestId } : {}) };
+    },
+    presentCall: (args) => ({
+      card: "generic",
+      title: "Ask knowledge base (may take a few minutes)",
+      kind: "fetch",
+      rawInput: args,
+    }),
+  });
+
+  return [search, chat];
+}

packages/bailian-kb-dsh/src/web/BailianCard.module.css

@@ -0,0 +1,319 @@
+/* Bailian settings page: title row, credential fields, clear control, and
+   save footer, in the settings-panel design language (16/24 title, 14/22
+   intro, `--dsw-alias-*` tokens — an out-of-tree bundle cannot value-import
+   the host section components, only their platform primitives). */
+
+.section {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  max-width: 720px;
+  color: var(--dsw-alias-label-primary);
+}
+
+.headRow {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.title {
+  margin: 0;
+  font-size: 16px;
+  line-height: 24px;
+  font-weight: 500;
+  color: var(--dsw-alias-label-primary);
+}
+
+.intro {
+  margin: 0;
+  font-size: 14px;
+  line-height: 22px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+/* The three controls grouped as one outlined object on the panel fill. */
+.form {
+  margin-top: 12px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 12px;
+  padding: 4px 16px 12px;
+  background: var(--dsw-alias-bg-layer-3);
+}
+
+/* Autofill control between the intro and the form: button + one-line status. */
+.autofillRow {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+/* Carried beside the title so a scrolled page still says it holds edits. */
+.pending {
+  flex: none;
+  border-radius: 999px;
+  padding: 1px 8px;
+  font-size: 11px;
+  line-height: 17px;
+  font-weight: 500;
+  white-space: nowrap;
+  background: var(--dsw-alias-bg-module-platform);
+  color: var(--dsw-alias-label-secondary);
+}
+
+/* Degraded-transport notice: the write-only fallback explains itself once. */
+.notice {
+  margin: 8px 0 0;
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-state-warn-label);
+}
+
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 0;
+}
+
+.field + .field {
+  border-top: 1px solid var(--dsw-alias-border-l2);
+}
+
+.head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.label {
+  font-size: 13px;
+  font-weight: 500;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-primary);
+}
+
+.labelWrap {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 0;
+}
+
+.getLink {
+  flex: none;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--dsw-alias-brand-primary);
+  text-decoration: none;
+  white-space: nowrap;
+}
+
+.getLink:hover {
+  text-decoration: underline;
+}
+
+.badges {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.badge {
+  border-radius: 999px;
+  padding: 1px 8px;
+  font-size: 11px;
+  line-height: 17px;
+  white-space: nowrap;
+  font-weight: 500;
+  background: var(--dsw-alias-bg-module-platform);
+  color: var(--dsw-alias-label-secondary);
+}
+
+.badgeSuccess {
+  border-radius: 999px;
+  padding: 1px 8px;
+  font-size: 11px;
+  line-height: 17px;
+  white-space: nowrap;
+  font-weight: 500;
+  background: var(--dsw-alias-state-success-tertiary);
+  color: var(--dsw-alias-state-success-primary);
+}
+
+.badgeMuted {
+  border-radius: 999px;
+  padding: 1px 8px;
+  font-size: 11px;
+  line-height: 17px;
+  white-space: nowrap;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.clear {
+  border: none;
+  background: none;
+  padding: 0;
+  font: inherit;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-secondary);
+  cursor: pointer;
+}
+
+.clear:hover:not(:disabled) {
+  color: var(--dsw-alias-label-primary);
+}
+
+.clear:disabled {
+  cursor: default;
+}
+
+.input {
+  height: 34px;
+  padding: 0 12px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 8px;
+  background: var(--dsw-alias-bg-layer-3);
+  font: inherit;
+  font-size: 13px;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-primary);
+}
+
+.input:focus-visible {
+  outline: none;
+  border-color: var(--dsw-alias-brand-primary);
+}
+
+.input:disabled {
+  color: var(--dsw-alias-label-tertiary);
+  cursor: default;
+}
+
+.hint {
+  margin: 0;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.autofillNoticeSuccess {
+  margin: 0;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--dsw-alias-state-success-primary);
+}
+
+.advancedSection {
+  border-top: none;
+}
+
+.field + .advancedSection,
+.notice + .advancedSection {
+  border-top: 1px solid var(--dsw-alias-border-l2);
+}
+
+.advancedToggle {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  padding: 12px 0;
+  border: none;
+  background: none;
+  font: inherit;
+  font-size: 13px;
+  font-weight: 500;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-primary);
+  cursor: pointer;
+}
+
+.advancedToggle:hover {
+  color: var(--dsw-alias-label-secondary);
+}
+
+.advancedToggle::after {
+  content: "";
+  display: inline-block;
+  width: 6px;
+  height: 6px;
+  border-right: 1.5px solid currentColor;
+  border-bottom: 1.5px solid currentColor;
+  transform: translateY(-2px) rotate(45deg);
+  transition: transform 0.2s ease;
+}
+
+.advancedToggle[aria-expanded="true"]::after {
+  transform: translateY(1px) rotate(-135deg);
+}
+
+.advancedFields {
+  display: flex;
+  flex-direction: column;
+}
+
+.advancedFields .field:first-child {
+  padding-top: 0;
+  border-top: 1px solid var(--dsw-alias-border-l2);
+}
+
+.footer {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 8px;
+  padding: 12px 0 0;
+  border-top: 1px solid var(--dsw-alias-border-l2);
+}
+
+.failed {
+  flex: 1;
+  min-width: 0;
+  margin: 0;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-error);
+}
+
+.discard,
+.save {
+  appearance: none;
+  border: 1px solid transparent;
+  border-radius: 8px;
+  padding: 5px 14px;
+  font: inherit;
+  font-size: 13px;
+  line-height: 1.5;
+  cursor: pointer;
+}
+
+.discard {
+  border-color: var(--dsw-alias-border-l2);
+  background: none;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.discard:hover:not(:disabled) {
+  color: var(--dsw-alias-label-primary);
+  border-color: var(--dsw-alias-label-dimmed);
+}
+
+.save {
+  background: var(--dsw-alias-label-primary);
+  color: var(--dsw-alias-bg-layer-3);
+}
+
+.discard:disabled,
+.save:disabled {
+  opacity: 0.4;
+  cursor: default;
+}
+
+.discard:focus-visible,
+.save:focus-visible {
+  outline: 2px solid var(--dsw-alias-brand-primary);
+  outline-offset: 1px;
+}

packages/bailian-kb-dsh/src/web/BailianCard.tsx

@@ -0,0 +1,403 @@
+/**
+ * The Bailian knowledge-base settings page: one section page in the
+ * Settings left nav. The workspace, default-retrieval-service and
+ * default-chat-service ids echo from the `bailian-kb` settings section
+ * while the scope is ready (clearing one falls back down the resolution
+ * chain), and degrade to write-only credential controls otherwise; the
+ * API key is always write-only — it drafts behind a password mask,
+ * starts blank, and reports only configured/unconfigured.
+ */
+
+import { useState } from "react";
+import type { InjectFace, PropsLocale, PropsRuntime } from "@deepseek-ai/dsh-client-ui-slots";
+import {
+  dirtyOf,
+  echoedValue,
+  SETTINGS_FIELDS,
+  type BailianCardFace,
+  type BailianCardState,
+  type BailianFieldKey,
+} from "./bailian-card-controller.ts";
+import type { BailianKbLocaleKey } from "./locales.ts";
+import css from "./BailianCard.module.css";
+
+/** Bailian console URL that lets the user create or copy an API key. */
+const BAILIAN_CONSOLE_API_KEY_URL =
+  "https://bailian.console.aliyun.com/cn-beijing?tab=globalset#/efm/api_key";
+
+/** Props the renderer binds for the Bailian section page. */
+export type BailianCardProps = PropsRuntime<"settings.section"> &
+  PropsLocale<"tool-bailian-kb"> &
+  InjectFace<BailianCardFace>;
+
+/** One field's render description. */
+interface FieldView {
+  key: BailianFieldKey;
+  labelKey: BailianKbLocaleKey;
+  /** Locale key for the "get" link shown next to the label. */
+  getKey?: BailianKbLocaleKey;
+  /** Echo-mode explanation (settings-backed value, blank save = fall back). */
+  hintKey: BailianKbLocaleKey;
+  /** Write-only explanation (credential store, blank = keep the stored value). */
+  fallbackHintKey: BailianKbLocaleKey;
+  setKey: BailianKbLocaleKey;
+  unsetKey: BailianKbLocaleKey;
+  /** Password-masked drafting; only the API key is an actual secret. */
+  secret: boolean;
+  /** When true the field is hidden inside the collapsible advanced section. */
+  advanced?: boolean;
+  /** External console URL for the "get" link. */
+  getUrl?: string;
+}
+
+/**
+ * The controls, in page order.
+ *
+ * The two default-service ids are NOT here: they render as pickers inside the
+ * advanced section instead, driven by the cached service list. A free-text id
+ * field beside a picker for the same setting is the same value twice, and the
+ * pair drifts the moment one of them writes.
+ */
+const FIELDS: readonly FieldView[] = [
+  {
+    key: "DASHSCOPE_API_KEY",
+    labelKey: "apiKey",
+    getKey: "apiKeyGet",
+    hintKey: "apiKeyHint",
+    fallbackHintKey: "apiKeyHint",
+    setKey: "apiKeySet",
+    unsetKey: "apiKeyUnset",
+    secret: true,
+    advanced: true,
+    getUrl: BAILIAN_CONSOLE_API_KEY_URL,
+  },
+  {
+    key: "BAILIAN_WORKSPACE_ID",
+    labelKey: "workspaceId",
+    getKey: "workspaceIdGet",
+    hintKey: "workspaceIdHint",
+    fallbackHintKey: "workspaceIdHintFallback",
+    setKey: "workspaceIdSet",
+    unsetKey: "workspaceIdUnset",
+    secret: false,
+    advanced: true,
+    getUrl: BAILIAN_CONSOLE_API_KEY_URL,
+  },
+];
+
+const ADVANCED_FIELDS = FIELDS.filter((field) => field.advanced);
+
+/** Whether both the API key and the workspace id already hold values. */
+function fullyConfigured(state: BailianCardState): boolean {
+  const apiKeyConfigured = state.credentials.DASHSCOPE_API_KEY.configured;
+  const workspaceConfigured =
+    state.credentials.BAILIAN_WORKSPACE_ID.configured ||
+    echoedValue(state, "BAILIAN_WORKSPACE_ID") !== "";
+  return apiKeyConfigured && workspaceConfigured;
+}
+
+/**
+ * Render the Bailian section page.
+ * @param props - locale copy, the page snapshot, and its actions.
+ * @returns the section page.
+ */
+export function BailianCard(props: BailianCardProps) {
+  const { t } = props;
+  const [advancedOpen, setAdvancedOpen] = useState(false);
+  const state = props.useBailianCard((snapshot) => snapshot);
+  const dirty = dirtyOf(state);
+  const busy = state.saving || state.clearing;
+
+  // The flow spans a browser login, so the button stays disabled until it settles.
+  const autofillBusy = state.autofill === "running" || state.autofill === "awaitingLogin";
+
+  // Pick the notice under the autofill button: settled outcome first, then
+  // a green "already configured" hint, then the default invitation.
+  let autofillNotice: BailianKbLocaleKey | undefined;
+  let autofillNoticeSuccess = false;
+  if (state.autofill === "done") {
+    autofillNotice = "autofillDone";
+    autofillNoticeSuccess = true;
+  } else if (state.autofill === "awaitingLogin") {
+    autofillNotice = "autofillAwaitingLogin";
+  } else if (state.autofill === "failed") {
+    autofillNotice = "autofillFailed";
+  } else if (fullyConfigured(state)) {
+    autofillNotice = "autofillConfigured";
+    autofillNoticeSuccess = true;
+  }
+
+  const renderField = (field: FieldView) => {
+    const credential = state.credentials[field.key];
+    // Echo mode: the settings scope answers with the resolved value, so
+    // the control is an ordinary pre-filled input. Otherwise the control
+    // is write-only and the badge is all the state there is.
+    const echo = SETTINGS_FIELDS[field.key] !== undefined && state.settings.status === "ready";
+    const echoed = echoedValue(state, field.key);
+    const value = state.drafts[field.key] ?? (echo ? echoed : "");
+    const disabled = busy || (echo ? !state.settings.writable : !credential.writable);
+    // The launch environment wins over the credential store and refuses
+    // writes; in echo mode a non-empty settings value shadows both, so
+    // the badge only reports the fallback under an empty input.
+    const badge = echo
+      ? echoed !== ""
+        ? undefined
+        : credential.configured
+          ? { label: t("fallbackConfigured"), set: true }
+          : { label: t(field.unsetKey), set: false }
+      : credential.configured
+        ? { label: credential.writable ? t(field.setKey) : t("fromEnv"), set: true }
+        : { label: t(field.unsetKey), set: false };
+    const showClear =
+      (field.key === "BAILIAN_DEFAULT_RETRIEVE_AGENT_ID" ||
+        field.key === "BAILIAN_DEFAULT_CHAT_AGENT_ID") &&
+      (credential.configured || (echo && echoed !== ""));
+    return (
+      <div className={css.field} key={field.key}>
+        <div className={css.head}>
+          <span className={css.labelWrap}>
+            <label className={css.label} htmlFor={`bailian-kb-${field.key}`}>
+              {t(field.labelKey)}
+            </label>
+            {field.getUrl !== undefined && field.getKey !== undefined ? (
+              <a className={css.getLink} href={field.getUrl} target="_blank" rel="noreferrer">
+                {t(field.getKey)}
+              </a>
+            ) : null}
+          </span>
+          <span className={css.badges}>
+            {showClear ? (
+              <button
+                type="button"
+                className={css.clear}
+                disabled={busy}
+                onClick={() => {
+                  void props.clearDefaultAgent(
+                    field.key as
+                      | "BAILIAN_DEFAULT_RETRIEVE_AGENT_ID"
+                      | "BAILIAN_DEFAULT_CHAT_AGENT_ID",
+                  );
+                }}
+              >
+                {t(state.clearing ? "clearing" : "clear")}
+              </button>
+            ) : null}
+            {badge !== undefined ? (
+              <span className={badge.set ? css.badgeSuccess : css.badgeMuted}>{badge.label}</span>
+            ) : null}
+          </span>
+        </div>
+        <input
+          id={`bailian-kb-${field.key}`}
+          className={css.input}
+          type={field.secret ? "password" : "text"}
+          autoComplete="off"
+          value={value}
+          disabled={disabled}
+          onChange={(event) => {
+            props.edit(field.key, event.target.value);
+          }}
+        />
+        <p className={css.hint}>{t(echo ? field.hintKey : field.fallbackHintKey)}</p>
+      </div>
+    );
+  };
+
+  /**
+   * One scene's default-service picker — the sole control for that setting.
+   *
+   * The cached list is the menu, but a value already pinned outside this list
+   * (the fetch is capped, so an older service can be absent) is prepended as its
+   * own option: dropping it would make the panel silently forget a live setting.
+   */
+  function renderPicker(scene: "search" | "chat") {
+    const cache = state.cache;
+    const entries = scene === "search" ? cache.search : cache.chat;
+    const pinned =
+      scene === "search"
+        ? state.settings.values.defaultRetrieveAgentId
+        : state.settings.values.defaultChatAgentId;
+    const isPinned = pinned !== undefined && pinned !== "";
+    const pinnedIsListed = isPinned && entries.some((entry) => entry.agent_id === pinned);
+    return (
+      <div className={css.field}>
+        <div className={css.head}>
+          <span className={css.label}>
+            {t(scene === "search" ? "retrieveAgentId" : "chatAgentId")}
+          </span>
+          {isPinned ? (
+            <button
+              type="button"
+              className={css.clear}
+              disabled={busy}
+              onClick={() => {
+                void props.selectDefaultAgent(scene, undefined);
+              }}
+            >
+              {t(state.clearing ? "clearing" : "pickerClear")}
+            </button>
+          ) : null}
+        </div>
+        <select
+          className={css.input}
+          value={pinned ?? ""}
+          disabled={busy || cache.status !== "ready"}
+          onChange={(event) => {
+            const next = event.target.value;
+            // The empty option is the clear path, which must remove the value
+            // from both the settings layer and the credential store.
+            void props.selectDefaultAgent(scene, next === "" ? undefined : next);
+          }}
+        >
+          <option value="">{t("pickerNone")}</option>
+          {isPinned && !pinnedIsListed ? <option value={pinned}>{pinned}</option> : null}
+          {entries.map((entry) => (
+            <option key={entry.agent_id} value={entry.agent_id}>
+              {entry.agent_name === "" ? entry.agent_id : entry.agent_name}
+            </option>
+          ))}
+        </select>
+        <p className={css.hint}>
+          {entries.length === 0
+            ? t("cacheEmpty")
+            : t(scene === "search" ? "retrieveAgentIdHint" : "chatAgentIdHint")}
+        </p>
+      </div>
+    );
+  }
+
+  /**
+   * The service-cache diagnostics: last fetch, per-scene counts, refresh.
+   *
+   * This stays OUTSIDE the advanced fold on purpose. It is the answer to "why did
+   * the agent stop retrieving" — an empty workspace and a stale list look
+   * identical from the outside, and before this the only way to tell them apart
+   * was reading the cache JSON off disk.
+   */
+  function renderCacheStatus() {
+    const cache = state.cache;
+    if (cache.status === "loading") return <p className={css.hint}>{t("cacheLoading")}</p>;
+    if (cache.status === "unconfigured")
+      return <p className={css.notice}>{t("cacheUnconfigured")}</p>;
+    if (cache.status === "unavailable")
+      return <p className={css.notice}>{t("cacheUnavailable")}</p>;
+
+    const fetched =
+      cache.fetchedAt === undefined ? t("cacheNever") : new Date(cache.fetchedAt).toLocaleString();
+
+    return (
+      <div className={css.field}>
+        <div className={css.head}>
+          <span className={css.label}>{t("cacheTitle")}</span>
+          <button
+            type="button"
+            className={css.clear}
+            disabled={cache.refreshing}
+            onClick={() => {
+              void props.refreshServices();
+            }}
+          >
+            {t(cache.refreshing ? "cacheRefreshing" : "cacheRefresh")}
+          </button>
+        </div>
+        <p className={css.hint}>
+          {t("cacheFetchedAt")}: {fetched}
+          {cache.stale ? ` (${t("cacheStale")})` : ""}
+          {" · "}
+          {t("cacheSearchCount")}: {cache.searchCount}
+          {" · "}
+          {t("cacheChatCount")}: {cache.chatCount}
+        </p>
+        {cache.truncated ? <p className={css.notice}>{t("cacheTruncated")}</p> : null}
+        {cache.searchCount === 0 && cache.chatCount === 0 ? (
+          <p className={css.notice}>{t("cacheEmpty")}</p>
+        ) : null}
+        <p className={css.hint}>{t("cacheHint")}</p>
+      </div>
+    );
+  }
+
+  return (
+    <section className={css.section}>
+      <div className={css.headRow}>
+        <h2 className={css.title}>{t("title")}</h2>
+        {dirty ? <span className={css.pending}>{t("unsaved")}</span> : null}
+      </div>
+      <p className={css.intro}>{t("description")}</p>
+      <div className={css.autofillRow}>
+        <button
+          type="button"
+          className={css.discard}
+          disabled={busy || autofillBusy}
+          onClick={() => {
+            void props.autofill();
+          }}
+        >
+          {t(state.autofill === "running" ? "autofilling" : "autofill")}
+        </button>
+        <span className={autofillNoticeSuccess ? css.autofillNoticeSuccess : css.hint}>
+          {autofillNotice !== undefined ? t(autofillNotice) : t("autofillHint")}
+          {/* The host opens the page itself; this link is the fallback when it cannot. */}
+          {state.autofillLoginUrl !== undefined && state.autofillLoginUrl !== "" ? (
+            <>
+              {" "}
+              <a href={state.autofillLoginUrl} target="_blank" rel="noreferrer">
+                {t("autofillOpenUrl")}
+              </a>
+            </>
+          ) : null}
+        </span>
+      </div>
+      <div className={css.form}>
+        {state.settings.status === "unavailable" ? (
+          <p className={css.notice}>{t("settingsUnavailable")}</p>
+        ) : null}
+        {renderCacheStatus()}
+        <div className={css.advancedSection}>
+          <button
+            type="button"
+            className={css.advancedToggle}
+            aria-expanded={advancedOpen}
+            onClick={() => {
+              setAdvancedOpen((open) => !open);
+            }}
+          >
+            {t("advancedConfig")}
+          </button>
+          {advancedOpen ? (
+            <div className={css.advancedFields}>
+              {ADVANCED_FIELDS.map(renderField)}
+              {renderPicker("search")}
+              {renderPicker("chat")}
+              <div className={css.footer}>
+                {state.failed ? (
+                  <p className={css.failed} role="status">
+                    {t("saveFailed")}
+                  </p>
+                ) : null}
+                <button
+                  type="button"
+                  className={css.discard}
+                  disabled={!dirty || busy}
+                  onClick={props.discard}
+                >
+                  {t("discard")}
+                </button>
+                <button
+                  type="button"
+                  className={css.save}
+                  disabled={!dirty || busy}
+                  onClick={() => {
+                    void props.save();
+                  }}
+                >
+                  {t(state.saving ? "saving" : "save")}
+                </button>
+              </div>
+            </div>
+          ) : null}
+        </div>
+      </div>
+    </section>
+  );
+}

packages/bailian-kb-dsh/src/web/bailian-card-controller.ts

@@ -0,0 +1,652 @@
+/**
+ * The Bailian page's controller: a hybrid form over two domains.
+ *
+ * The workspace, default-retrieval-service and default-chat-service ids live
+ * in the `bailian-kb` settings section the Host half registers. The Host
+ * exposes them over a bridge route (`/bailian-kb/settings`) so the page can
+ * read and write without riding the settings wire (which requires an apiproxy
+ * allowlist entry the composition does not grant out-of-tree namespaces).
+ *
+ * The API key always rides its credential reference (write-only by design:
+ * the wire is structurally value-free), so that control starts blank and
+ * reports only configured/unconfigured.
+ */
+
+import type { IApiClient } from "@deepseek-ai/dsh-client-connection/client";
+import { createSnapshotStore, type SnapshotStore } from "@deepseek-ai/dsh-client-runtime/client";
+
+/** The credential references this page addresses, keyed by their ref names. */
+export const BAILIAN_CARD_REFS = [
+  "DASHSCOPE_API_KEY",
+  "BAILIAN_WORKSPACE_ID",
+  "BAILIAN_DEFAULT_RETRIEVE_AGENT_ID",
+  "BAILIAN_DEFAULT_CHAT_AGENT_ID",
+] as const;
+
+/** One page field, addressed by its credential reference. */
+export type BailianFieldKey = (typeof BAILIAN_CARD_REFS)[number];
+
+/** Settings-section field names of the echoing controls. */
+export type BailianSettingsField = "workspaceId" | "defaultRetrieveAgentId" | "defaultChatAgentId";
+
+/** Credential reference → settings-section field, for the hybrid controls. */
+export const SETTINGS_FIELDS: Partial<Record<BailianFieldKey, BailianSettingsField>> = {
+  BAILIAN_WORKSPACE_ID: "workspaceId",
+  BAILIAN_DEFAULT_RETRIEVE_AGENT_ID: "defaultRetrieveAgentId",
+  BAILIAN_DEFAULT_CHAT_AGENT_ID: "defaultChatAgentId",
+};
+
+/** The section subset this page reads and writes (the namespace holds the whole plugin Config). */
+export interface BailianKbSection {
+  workspaceId?: string;
+  defaultRetrieveAgentId?: string;
+  defaultChatAgentId?: string;
+}
+
+/** What the credentials domain reports for one reference (never the value). */
+export interface BailianCredentialView {
+  /** Whether any layer supplies a value for the reference. */
+  configured: boolean;
+  /** Whether `credentials.set` can affect it; false disables the control. */
+  writable: boolean;
+}
+
+/** The page's mirror of the settings scope. */
+export interface BailianSettingsView {
+  /** `ready` enables echo; `unavailable` degrades to write-only credentials. */
+  status: "loading" | "ready" | "unavailable";
+  /** Whether the Host settings document accepts writes. */
+  writable: boolean;
+  /** Resolved section values (entry base + user layer) for the two hybrid controls. */
+  values: BailianKbSection;
+}
+
+/** Where the autofill flow (adopt a Bailian console login) currently stands. */
+export type BailianAutofillStatus = "idle" | "running" | "awaitingLogin" | "done" | "failed";
+
+/** One cached retrieval or Q&A service, as the picker lists it. */
+export interface BailianServiceEntry {
+  agent_id: string;
+  agent_name: string;
+  scene: "search" | "chat";
+  status: string;
+  modify_time?: string;
+}
+
+/**
+ * The service cache as the panel shows it.
+ *
+ * This exists because cache staleness is otherwise invisible: an agent that
+ * silently stops retrieving looks identical whether the workspace is empty or the
+ * list is merely out of date. `fetchedAt` with the per-scene counts distinguishes
+ * those two in one glance, which is the whole reason the panel earns its space.
+ */
+export interface BailianCacheView {
+  /** `unconfigured` = no workspace id yet; `unavailable` = the bridge route failed. */
+  status: "loading" | "ready" | "unconfigured" | "unavailable";
+  /** Epoch millis of the last successful fetch; absent when nothing is cached. */
+  fetchedAt?: number;
+  searchCount: number;
+  chatCount: number;
+  /** Server-reported total, which exceeds the counts when the fetch was capped. */
+  total: number;
+  truncated: boolean;
+  stale: boolean;
+  search: BailianServiceEntry[];
+  chat: BailianServiceEntry[];
+  /** Whether a forced refresh is in flight. */
+  refreshing: boolean;
+}
+
+/** What the Bailian page renders. */
+export interface BailianCardState {
+  /** Staged drafts; undefined = untouched (the control shows the echoed value). */
+  drafts: Record<BailianFieldKey, string | undefined>;
+  /** Last credentials-domain answer per reference; unknown refs read as writable. */
+  credentials: Record<BailianFieldKey, BailianCredentialView>;
+  /** Settings-scope echo state for the id fields. */
+  settings: BailianSettingsView;
+  /** Whether a save is in flight. */
+  saving: boolean;
+  /** Whether a default-service clear is in flight. */
+  clearing: boolean;
+  /** Whether the last save or clear was refused; drafts are kept for correction. */
+  failed: boolean;
+  /** The autofill flow's state; feeds the button label and its result notice. */
+  autofill: BailianAutofillStatus;
+  /** Console login URL while `awaitingLogin`, shown in case the host could not open a browser. */
+  autofillLoginUrl?: string;
+  /** Service cache diagnostics and the pickable services. */
+  cache: BailianCacheView;
+}
+
+/** The registration-side face the page's slot entry injects. */
+export interface BailianCardFace {
+  hooks: {
+    /** Page snapshot bound by the renderer as useBailianCard. */
+    bailianCard: SnapshotStore<BailianCardState>;
+  };
+  /** Stage one draft. */
+  edit: (key: BailianFieldKey, text: string) => void;
+  /** Write every staged draft through its domain, then re-read. */
+  save: () => Promise<void>;
+  /** Drop every staged draft. */
+  discard: () => void;
+  /** Remove the stored default service from every writable layer, then re-read. */
+  clearDefaultAgent: (
+    key: "BAILIAN_DEFAULT_RETRIEVE_AGENT_ID" | "BAILIAN_DEFAULT_CHAT_AGENT_ID",
+  ) => Promise<void>;
+  /** Adopt a Bailian console login (api key + workspace id) via the Host. */
+  autofill: () => Promise<void>;
+  /** Force a service-cache refresh, bypassing the TTL. */
+  refreshServices: () => Promise<void>;
+  /**
+   * Pin one scene's default service, or clear it when `agentId` is undefined.
+   * Clearing removes the value from the settings user layer AND the credential
+   * store, so the fallback chain cannot resurrect what the user just cleared.
+   */
+  selectDefaultAgent: (scene: "search" | "chat", agentId: string | undefined) => Promise<void>;
+}
+
+/** The text a field's control shows when its draft is untouched. */
+export function echoedValue(state: BailianCardState, key: BailianFieldKey): string {
+  const field = SETTINGS_FIELDS[key];
+  if (field === undefined || state.settings.status !== "ready") return "";
+  return state.settings.values[field] ?? "";
+}
+
+/** Whether one field stages a change a save would write. */
+function staged(state: BailianCardState, key: BailianFieldKey): boolean {
+  const draft = state.drafts[key];
+  if (draft === undefined) return false;
+  const field = SETTINGS_FIELDS[key];
+  if (field !== undefined && state.settings.status === "ready") {
+    return draft !== echoedValue(state, key);
+  }
+  // Write-only control: blank means untouched, never "erase the stored value".
+  return draft !== "";
+}
+
+/** Whether any field stages a change (enables Save/Discard). */
+export function dirtyOf(state: BailianCardState): boolean {
+  return BAILIAN_CARD_REFS.some((key) => staged(state, key));
+}
+
+/** Bridge the settings bridge route and the credentials domain onto the page. */
+export class BailianCardController {
+  private readonly store: SnapshotStore<BailianCardState>;
+
+  /**
+   * @param api - wire face used for the four credential references.
+   */
+  constructor(private readonly api: Pick<IApiClient, "credentials">) {
+    this.store = createSnapshotStore<BailianCardState>({
+      drafts: {
+        DASHSCOPE_API_KEY: undefined,
+        BAILIAN_WORKSPACE_ID: undefined,
+        BAILIAN_DEFAULT_RETRIEVE_AGENT_ID: undefined,
+        BAILIAN_DEFAULT_CHAT_AGENT_ID: undefined,
+      },
+      credentials: {
+        DASHSCOPE_API_KEY: { configured: false, writable: true },
+        BAILIAN_WORKSPACE_ID: { configured: false, writable: true },
+        BAILIAN_DEFAULT_RETRIEVE_AGENT_ID: { configured: false, writable: true },
+        BAILIAN_DEFAULT_CHAT_AGENT_ID: { configured: false, writable: true },
+      },
+      settings: { status: "loading", writable: false, values: {} },
+      saving: false,
+      clearing: false,
+      failed: false,
+      autofill: "idle",
+      autofillLoginUrl: undefined,
+      cache: {
+        status: "loading",
+        searchCount: 0,
+        chatCount: 0,
+        total: 0,
+        truncated: false,
+        stale: true,
+        search: [],
+        chat: [],
+        refreshing: false,
+      },
+    });
+    void this.fetchSettings();
+    void this.fetchServices();
+    void this.read();
+  }
+
+  /**
+   * Fetch the current settings from the Host bridge route. Called at
+   * construction and after every mutation (save, clear).
+   */
+  async fetchSettings(): Promise<void> {
+    try {
+      const resp = await fetch("/bailian-kb/settings");
+      if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+      const value = (await resp.json()) as Record<string, unknown>;
+      this.store.update((draft) => {
+        draft.settings = {
+          status: "ready",
+          writable: true,
+          values: {
+            ...(typeof value.workspaceId === "string" ? { workspaceId: value.workspaceId } : {}),
+            ...(typeof value.defaultRetrieveAgentId === "string"
+              ? { defaultRetrieveAgentId: value.defaultRetrieveAgentId }
+              : {}),
+            ...(typeof value.defaultChatAgentId === "string"
+              ? { defaultChatAgentId: value.defaultChatAgentId }
+              : {}),
+          },
+        };
+      });
+    } catch (_fetchFailure) {
+      this.store.update((draft) => {
+        draft.settings = { status: "unavailable", writable: false, values: {} };
+      });
+    }
+  }
+
+  /**
+   * Read the service cache snapshot from the Host bridge route.
+   * @param force - POST instead of GET, making the Host refetch regardless of TTL.
+   */
+  async fetchServices(force = false): Promise<void> {
+    if (force)
+      this.store.update((draft) => {
+        draft.cache.refreshing = true;
+      });
+    try {
+      const resp = await fetch("/bailian-kb/services", { method: force ? "POST" : "GET" });
+      if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+      const value = (await resp.json()) as {
+        configured?: boolean;
+        status?: {
+          fetchedAt?: number;
+          searchCount?: number;
+          chatCount?: number;
+          total?: number;
+          truncated?: boolean;
+          stale?: boolean;
+        };
+        search?: BailianServiceEntry[];
+        chat?: BailianServiceEntry[];
+      };
+      this.store.update((draft) => {
+        draft.cache.refreshing = false;
+        if (value.configured !== true) {
+          // No workspace id yet: the panel says so rather than showing zeros,
+          // which would read as "the workspace has no services".
+          draft.cache.status = "unconfigured";
+          return;
+        }
+        draft.cache.status = "ready";
+        draft.cache.fetchedAt = value.status?.fetchedAt;
+        draft.cache.searchCount = value.status?.searchCount ?? 0;
+        draft.cache.chatCount = value.status?.chatCount ?? 0;
+        draft.cache.total = value.status?.total ?? 0;
+        draft.cache.truncated = value.status?.truncated === true;
+        draft.cache.stale = value.status?.stale === true;
+        draft.cache.search = value.search ?? [];
+        draft.cache.chat = value.chat ?? [];
+      });
+    } catch (_routeFailure) {
+      this.store.update((draft) => {
+        draft.cache.refreshing = false;
+        draft.cache.status = "unavailable";
+      });
+    }
+  }
+
+  /** Force a refresh, bypassing the TTL, and show the updated numbers. */
+  async refreshServices(): Promise<void> {
+    if (this.store.getSnapshot().cache.refreshing) return;
+    await this.fetchServices(true);
+  }
+
+  /**
+   * Pin or clear one scene's default service.
+   *
+   * Clearing delegates to {@link clearDefaultAgent}, which removes the value from
+   * the settings user layer AND the credential store — without the second
+   * removal the fallback chain would resurrect what the user just cleared.
+   * @param scene - which tool's default to set.
+   * @param agentId - the service id to pin, or undefined to clear.
+   */
+  async selectDefaultAgent(scene: "search" | "chat", agentId: string | undefined): Promise<void> {
+    const key =
+      scene === "search" ? "BAILIAN_DEFAULT_RETRIEVE_AGENT_ID" : "BAILIAN_DEFAULT_CHAT_AGENT_ID";
+    if (agentId === undefined) {
+      await this.clearDefaultAgent(key);
+      return;
+    }
+    const field: BailianSettingsField =
+      scene === "search" ? "defaultRetrieveAgentId" : "defaultChatAgentId";
+    this.store.update((draft) => {
+      draft.saving = true;
+    });
+    try {
+      const resp = await fetch("/bailian-kb/settings", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ [field]: agentId }),
+      });
+      if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+      this.store.update((draft) => {
+        draft.failed = false;
+      });
+    } catch (_writeFailure) {
+      this.store.update((draft) => {
+        draft.failed = true;
+      });
+    } finally {
+      this.store.update((draft) => {
+        draft.saving = false;
+      });
+      await this.fetchSettings();
+    }
+  }
+
+  /**
+   * Stage one draft; any edit clears the failure mark so the banner does not
+   * outlive the correction it asks for.
+   * @param key - the field's credential reference.
+   * @param text - the staged text.
+   */
+  edit(key: BailianFieldKey, text: string): void {
+    this.store.update((draft) => {
+      draft.drafts[key] = text;
+      draft.failed = false;
+    });
+  }
+
+  /**
+   * Write every staged draft through its domain: echoing fields go to the
+   * settings user layer via the bridge route (blank = removal, falling back
+   * to entry config and the credential store), write-only fields go to
+   * `credentials.set`. A refused credential write keeps its draft; a refused
+   * settings write self-heals by re-fetching the Host value.
+   */
+  async save(): Promise<void> {
+    const state = this.store.getSnapshot();
+    if (state.saving || !dirtyOf(state)) return;
+    this.store.update((draft) => {
+      draft.saving = true;
+    });
+    let failed = false;
+    const settingsPatch: Record<string, unknown> = {};
+    let hasSettingsWrite = false;
+    const credentialWrites: Promise<void>[] = [];
+    const settled: BailianFieldKey[] = [];
+    for (const key of BAILIAN_CARD_REFS) {
+      if (!staged(state, key)) continue;
+      const text = state.drafts[key] as string;
+      const field = SETTINGS_FIELDS[key];
+      if (field !== undefined && state.settings.status === "ready") {
+        settingsPatch[field] = text === "" ? null : text;
+        hasSettingsWrite = true;
+        settled.push(key);
+        continue;
+      }
+      credentialWrites.push(
+        (async () => {
+          try {
+            const response = await this.api.credentials.set({ ref: key, value: text });
+            if (response.result.ok) settled.push(key);
+            else failed = true;
+          } catch (_credentialWriteFailure) {
+            failed = true;
+          }
+        })(),
+      );
+    }
+    if (hasSettingsWrite) {
+      try {
+        await this.saveSettings(settingsPatch);
+      } catch (_settingsWriteFailure) {
+        failed = true;
+      }
+    }
+    await Promise.all(credentialWrites);
+    this.store.update((draft) => {
+      draft.saving = false;
+      draft.failed = failed;
+      for (const key of settled) draft.drafts[key] = undefined;
+    });
+    await this.fetchSettings();
+    await this.read();
+  }
+
+  /** Drop every staged draft and the failure mark. */
+  discard(): void {
+    this.store.update((draft) => {
+      for (const ref of BAILIAN_CARD_REFS) draft.drafts[ref] = undefined;
+      draft.failed = false;
+    });
+  }
+
+  /**
+   * Fetch credentials by signing in to the Bailian console. The Host drives
+   * the console browser login itself, always requesting a freshly issued api
+   * key, then persists the key into the credential store and the workspace id
+   * into the settings section — so both values belong to the account that just
+   * signed in, and the plain key never rides the wire to this page.
+   *
+   * Deliberately does NOT adopt the bl CLI's stored login: that path can pair
+   * one account's key with another account's workspace id, and nothing would
+   * flag the mismatch until a knowledge-base call fails.
+   */
+  async autofill(): Promise<void> {
+    const phase = this.store.getSnapshot().autofill;
+    if (phase === "running" || phase === "awaitingLogin") return;
+    this.store.update((draft) => {
+      draft.autofill = "running";
+      draft.autofillLoginUrl = undefined;
+    });
+    await this.runConsoleLogin();
+    await this.fetchSettings();
+    await this.read();
+  }
+
+  /**
+   * Ask the Host to open the console login page, then poll for the outcome.
+   * The Host persists the credentials itself when the callback lands, always
+   * requesting a freshly issued key — so the key and the workspace id both come
+   * from the account signing in.
+   */
+  private async runConsoleLogin(): Promise<void> {
+    let started: { status?: string; loginUrl?: string };
+    try {
+      started = (await this.postAutofill("login")) as { status?: string; loginUrl?: string };
+    } catch (_routeFailure) {
+      this.store.update((draft) => {
+        draft.autofill = "failed";
+      });
+      return;
+    }
+    if (started.status !== "started" && started.status !== "already-running") {
+      this.store.update((draft) => {
+        draft.autofill = "failed";
+      });
+      return;
+    }
+    this.store.update((draft) => {
+      draft.autofill = "awaitingLogin";
+      draft.autofillLoginUrl = started.loginUrl;
+    });
+    await this.pollConsoleLogin();
+  }
+
+  /**
+   * Poll the Host until the console login resolves. Bounded so a login the
+   * user abandons does not leave the button spinning forever; the Host keeps
+   * its own (longer) timeout, so a late callback still persists and shows up
+   * on the next page read.
+   */
+  private async pollConsoleLogin(): Promise<void> {
+    const deadline = Date.now() + 5 * 60 * 1000;
+    while (Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+      let phase: string | undefined;
+      try {
+        phase = ((await this.postAutofill("loginStatus")) as { phase?: string }).phase;
+      } catch (_pollFailure) {
+        continue;
+      }
+      if (phase === "done") {
+        this.store.update((draft) => {
+          draft.autofill = "done";
+          draft.autofillLoginUrl = undefined;
+        });
+        return;
+      }
+      if (phase === "failed") {
+        this.store.update((draft) => {
+          draft.autofill = "failed";
+          draft.autofillLoginUrl = undefined;
+        });
+        return;
+      }
+    }
+    this.store.update((draft) => {
+      draft.autofill = "failed";
+    });
+  }
+
+  /**
+   * Remove the stored default service from every writable layer — the
+   * settings user layer AND the credential store, so the fallback chain does
+   * not resurrect the value the user just cleared. Both removals are
+   * idempotent; the credential unset is skipped when nothing is stored there.
+   * @param key - which default service credential to clear.
+   */
+  async clearDefaultAgent(
+    key: "BAILIAN_DEFAULT_RETRIEVE_AGENT_ID" | "BAILIAN_DEFAULT_CHAT_AGENT_ID",
+  ): Promise<void> {
+    const settingsField: BailianSettingsField =
+      key === "BAILIAN_DEFAULT_RETRIEVE_AGENT_ID" ? "defaultRetrieveAgentId" : "defaultChatAgentId";
+    const state = this.store.getSnapshot();
+    if (state.clearing) return;
+    this.store.update((draft) => {
+      draft.clearing = true;
+    });
+    let failed = false;
+    if (state.settings.status === "ready") {
+      try {
+        await this.saveSettings({ [settingsField]: null });
+      } catch (_settingsWriteFailure) {
+        failed = true;
+      }
+    }
+    if (state.credentials[key].configured) {
+      try {
+        const response = await this.api.credentials.unset({ ref: key });
+        if (!response.result.ok) failed = true;
+      } catch (_credentialWriteFailure) {
+        failed = true;
+      }
+    }
+    this.store.update((draft) => {
+      draft.clearing = false;
+      draft.failed = failed;
+      draft.drafts[key] = undefined;
+    });
+    await this.fetchSettings();
+    await this.read();
+  }
+
+  /**
+   * Re-read after the Host reports a change to a reference this page watches.
+   *
+   * A value can be written from somewhere else — the Models page addresses
+   * DASHSCOPE_API_KEY too, and the file store accepts external edits — so
+   * without this the badges keep reporting a state the Host already replaced.
+   * (Settings-document changes reach the page through the scope instead.)
+   * @param ref - the reference the Host reports as changed.
+   */
+  refresh(ref: string): void {
+    if (!(BAILIAN_CARD_REFS as readonly string[]).includes(ref)) return;
+    void this.read();
+  }
+
+  /**
+   * Build the face the page's slot registration injects.
+   * @returns the page's snapshot and its actions.
+   */
+  inject(): BailianCardFace {
+    return {
+      hooks: { bailianCard: this.store },
+      edit: (key, text) => {
+        this.edit(key, text);
+      },
+      save: () => this.save(),
+      discard: () => {
+        this.discard();
+      },
+      clearDefaultAgent: (key) => this.clearDefaultAgent(key),
+      autofill: () => this.autofill(),
+      refreshServices: () => this.refreshServices(),
+      selectDefaultAgent: (scene, agentId) => this.selectDefaultAgent(scene, agentId),
+    };
+  }
+
+  /**
+   * Post one autofill action to the Host bridge route.
+   * @param action - `login` starts the console browser flow; `loginStatus`
+   * reads that flow's progress.
+   * @returns the route's JSON answer.
+   */
+  private async postAutofill(action: "login" | "loginStatus"): Promise<unknown> {
+    const resp = await fetch("/bailian-kb/autofill", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ action }),
+    });
+    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+    return resp.json();
+  }
+
+  /**
+   * Send a settings patch to the Host bridge route. `null`-valued keys are
+   * removals (the field falls back to the entry config and then the
+   * credential store); other values are merged into the user layer.
+   * @param patch - the partial settings update.
+   */
+  private async saveSettings(patch: Record<string, unknown>): Promise<void> {
+    const resp = await fetch("/bailian-kb/settings", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(patch),
+    });
+    if (!resp.ok) {
+      const body = (await resp.json().catch(() => ({}))) as { error?: string };
+      throw new Error(body.error ?? `HTTP ${resp.status}`);
+    }
+  }
+
+  /**
+   * Ask the credentials domain about all four references and publish the
+   * answer. A failed read keeps the last known state: the page stays usable
+   * and a write still reaches the Host.
+   */
+  private async read(): Promise<void> {
+    let response: Awaited<ReturnType<IApiClient["credentials"]["describe"]>>;
+    try {
+      response = await this.api.credentials.describe({ refs: [...BAILIAN_CARD_REFS] });
+    } catch (_credentialReadFailure) {
+      return;
+    }
+    if (!response.result.ok) return;
+    const view = response.result.value.credentials;
+    this.store.update((draft) => {
+      for (const ref of BAILIAN_CARD_REFS) {
+        // An unknown reference reads as writable: the control stays usable and
+        // the Host is what refuses, rather than the page guessing a refusal.
+        draft.credentials[ref] = {
+          configured: view[ref]?.configured ?? false,
+          writable: view[ref]?.writable ?? true,
+        };
+      }
+    });
+  }
+}

packages/bailian-kb-dsh/src/web/css-modules.d.ts

@@ -0,0 +1,9 @@
+/**
+ * CSS Modules for the browser half: the bundler (tsdown client preset) inlines
+ * `*.module.css` imports as hashed class maps, this declaration gives the
+ * import its type in the browser-only project.
+ */
+declare module "*.module.css" {
+  const classes: Record<string, string>;
+  export default classes;
+}

packages/bailian-kb-dsh/src/web/index.ts

@@ -0,0 +1,78 @@
+/**
+ * Bailian knowledge-base plugin, browser half: one section page in the
+ * Settings left nav. The workspace, default-retrieval-service and
+ * default-chat-service ids ride the Host bridge route
+ * (`/bailian-kb/settings`) the Host half registers, bypassing the settings
+ * wire (which requires an apiproxy allowlist entry the composition does not
+ * grant out-of-tree namespaces); the API key stays pure credentials-domain
+ * and never echoes.
+ */
+
+import type { ConnectionHandle } from "@deepseek-ai/dsh-client-connection/client";
+// Type-only: the locale plugin's Context merge (ctx.locale).
+import type {} from "@deepseek-ai/dsh-client-locale/client";
+import type { ClientContext } from "@deepseek-ai/dsh-client-runtime/client";
+// Type-only: the remote service's Context merge (ctx.remote) and the forwarded
+// credential-update events.
+import type {} from "@deepseek-ai/dsh-api-remotes/client";
+import type {} from "@deepseek-ai/dsh-client-ui-slots";
+// The 'settings.section' SlotMap merge AND the ctx.settingsScope service,
+// both declared by the settings domain base (type-only: the service arrives
+// through cordis, never a value import).
+import type {} from "@deepseek-ai/dsh-client-ui-settings/client";
+import { BailianCard } from "./BailianCard.tsx";
+import { BailianCardController } from "./bailian-card-controller.ts";
+import { en, zh, type BailianKbLocaleKey } from "./locales.ts";
+declare module "@deepseek-ai/dsh-client-ui-slots" {
+  interface LocaleNamespaceMap {
+    /** The Bailian section page's copy. */
+    "tool-bailian-kb": BailianKbLocaleKey;
+  }
+}
+
+/** Dictionary namespace owned by this plugin. */
+const NS = "tool-bailian-kb";
+
+/** Required services (cordis fiber inject). */
+export const inject = ["slots", "locale", "connection", "remote"];
+
+/**
+ * Mount the Bailian section page into the Settings left nav.
+ * @param ctx - the browser plugin context.
+ */
+export function apply(ctx: ClientContext): void {
+  const { api } = ctx.get("connection") as ConnectionHandle;
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), "tool-bailian-kb: dictionaries");
+
+  // Registration-time text: the nav label is a thunk the shell resolves per
+  // render, so copy freshness rides the locale revision without re-registering.
+  const t = ctx.locale.bind(NS);
+
+  // The echo transport: the Host bridge route (`/bailian-kb/settings`) lets
+  // the page read and write the resolved section without riding the settings
+  // wire (which requires an apiproxy allowlist entry).
+  const card = new BailianCardController(api);
+  // Values can change elsewhere (Models page, external file edits); the badges
+  // must follow the Host, not the card's last write.
+  ctx.effect(
+    () =>
+      ctx.remote.$on("credentials/updated", (ref) => {
+        card.refresh(ref);
+      }),
+    "tool-bailian-kb: credential invalidations",
+  );
+
+  ctx.slots.inject("settings.section", () =>
+    ctx.slots.register(
+      {
+        name: "settings.section",
+        id: "bailian-kb",
+        order: 20,
+        label: () => t("nav"),
+        locale: NS,
+        inject: () => card.inject(),
+      },
+      BailianCard,
+    ),
+  );
+}

packages/bailian-kb-dsh/src/web/locales.ts

@@ -0,0 +1,190 @@
+/**
+ * Locale bundles for the Bailian knowledge-base settings page. The workspace,
+ * default-retrieval-service and default-chat-service ids echo from the
+ * settings section while it is available and fall back to write-only
+ * credential controls otherwise; the API key copy is always written for a
+ * write-only control: state is reported as configured/unconfigured, and a
+ * stored key is never echoed back.
+ */
+
+/** Locale keys this page renders. */
+export type BailianKbLocaleKey =
+  | "nav"
+  | "title"
+  | "description"
+  | "settingsUnavailable"
+  | "fallbackConfigured"
+  | "apiKey"
+  | "apiKeyHint"
+  | "apiKeySet"
+  | "apiKeyUnset"
+  | "apiKeyGet"
+  | "workspaceId"
+  | "workspaceIdHint"
+  | "workspaceIdHintFallback"
+  | "workspaceIdSet"
+  | "workspaceIdUnset"
+  | "workspaceIdGet"
+  | "retrieveAgentId"
+  | "retrieveAgentIdHint"
+  | "chatAgentId"
+  | "chatAgentIdHint"
+  | "fromEnv"
+  | "clear"
+  | "clearing"
+  | "save"
+  | "saving"
+  | "discard"
+  | "unsaved"
+  | "saveFailed"
+  | "advancedConfig"
+  | "autofill"
+  | "autofilling"
+  | "autofillHint"
+  | "autofillDone"
+  | "autofillAwaitingLogin"
+  | "autofillOpenUrl"
+  | "autofillFailed"
+  | "autofillConfigured"
+  | "cacheTitle"
+  | "cacheHint"
+  | "cacheLoading"
+  | "cacheUnconfigured"
+  | "cacheUnavailable"
+  | "cacheFetchedAt"
+  | "cacheNever"
+  | "cacheStale"
+  | "cacheSearchCount"
+  | "cacheChatCount"
+  | "cacheTruncated"
+  | "cacheEmpty"
+  | "cacheRefresh"
+  | "cacheRefreshing"
+  | "pickerNone"
+  | "pickerClear";
+
+/** English copy. */
+export const en: Record<BailianKbLocaleKey, string> = {
+  nav: "Bailian KB",
+  title: "Bailian knowledge base",
+  description: "Account for the knowledge tools: API key, workspace, and default services.",
+  settingsUnavailable:
+    "The settings document is not reachable from this browser; values below are write-only and stored in the credential store.",
+  fallbackConfigured: "Falling back to a configured credential-store value.",
+  apiKey: "API key",
+  apiKeyHint:
+    "DashScope API key. Stored in the credentials store and never shown again; leave blank to keep the current one.",
+  apiKeySet: "A key is configured.",
+  apiKeyUnset: "No key is configured; knowledge tools fail until one is.",
+  apiKeyGet: "Get",
+  workspaceId: "Workspace id",
+  workspaceIdHint:
+    "Bailian workspace id — the subdomain of your endpoints. Stored in the settings document; clear and save to fall back to the credential store.",
+  workspaceIdHintFallback:
+    "Bailian workspace id — the subdomain of your endpoints. Leave blank to keep the current one.",
+  workspaceIdSet: "A workspace is configured.",
+  workspaceIdUnset: "No workspace is configured; knowledge tools fail until one is.",
+  workspaceIdGet: "Get",
+  retrieveAgentId: "Default retrieval service",
+  retrieveAgentIdHint:
+    "The agent_id kb_search falls back to. Left unset, the injected catalog lists every deployed service instead.",
+  chatAgentId: "Default Q&A service",
+  chatAgentIdHint:
+    "The agent_id kb_chat falls back to. Left unset, the injected catalog lists every deployed service instead.",
+  fromEnv: "Set by the environment (read-only here)",
+  clear: "Clear default",
+  clearing: "Clearing…",
+  save: "Save",
+  saving: "Saving…",
+  discard: "Discard",
+  unsaved: "Unsaved",
+  saveFailed: "The Host did not accept these values; they were left for you to correct.",
+  advancedConfig: "Advanced configuration",
+  autofill: "Fetch from console login",
+  autofilling: "Starting…",
+  autofillHint:
+    "Sign in to the Bailian console to fill in that account’s API key and workspace id.",
+  autofillDone: "Credentials adopted; the fields below reflect the new values.",
+  autofillAwaitingLogin:
+    "Waiting for the Bailian console login to finish in a browser on the host machine…",
+  autofillOpenUrl: "Open the login page manually",
+  autofillFailed:
+    "Auto-fill failed — the credential may be locked by an environment variable, the Host refused the write, or the login was abandoned.",
+  autofillConfigured:
+    "Configured. Click button to fetch this account’s API key and workspace id again.",
+  cacheTitle: "Retrieval service cache",
+  cacheHint:
+    "The service list injected into each conversation. Refreshes on its own; refresh here when you have just created a service and want it picked up now.",
+  cacheLoading: "Reading…",
+  cacheUnconfigured: "Set a workspace id first.",
+  cacheUnavailable: "Not reachable from this browser.",
+  cacheFetchedAt: "Last fetched",
+  cacheNever: "never",
+  cacheStale: "refresh due",
+  cacheSearchCount: "Retrieval services",
+  cacheChatCount: "Q&A services",
+  cacheTruncated: "List truncated — the workspace holds more than were fetched.",
+  cacheEmpty: "No deployed services cached. If you just created one, refresh.",
+  cacheRefresh: "Refresh",
+  cacheRefreshing: "Refreshing…",
+  pickerNone: "Not set — the full list is injected instead",
+  pickerClear: "Clear",
+};
+
+/** Simplified Chinese copy. */
+export const zh: Record<BailianKbLocaleKey, string> = {
+  nav: "百炼知识库",
+  title: "百炼知识库",
+  description: "知识库工具的账号信息：API 密钥、工作空间与默认服务。",
+  settingsUnavailable: "当前浏览器无法访问设置文档；以下字段仅可写入凭据存储，不回显。",
+  fallbackConfigured: "回退：凭据存储中已有值。",
+  apiKey: "API 密钥",
+  apiKeyHint: "DashScope API key。保存在凭据存储中且不会再次显示；留空表示保持当前值。",
+  apiKeySet: "已配置密钥。",
+  apiKeyUnset: "未配置密钥；配置前知识库工具不可用。",
+  apiKeyGet: "去获取",
+  workspaceId: "工作空间 ID",
+  workspaceIdHint:
+    "百炼工作空间 ID，即终端节点地址的子域名。存入设置文档；清空并保存则回退到凭据存储。",
+  workspaceIdHintFallback: "百炼工作空间 ID，即终端节点地址的子域名。留空表示保持当前值。",
+  workspaceIdSet: "已配置工作空间。",
+  workspaceIdUnset: "未配置工作空间；配置前知识库工具不可用。",
+  workspaceIdGet: "去获取",
+  retrieveAgentId: "默认检索服务",
+  retrieveAgentIdHint: "kb_search 缺省使用的 agent_id。不设置时，注入的清单会列出全部已部署服务。",
+  chatAgentId: "默认对话服务",
+  chatAgentIdHint: "kb_chat 缺省使用的 agent_id。不设置时，注入的清单会列出全部已部署服务。",
+  fromEnv: "来自环境变量（此处只读）",
+  clear: "清除默认",
+  clearing: "清除中…",
+  save: "保存",
+  saving: "保存中…",
+  discard: "放弃",
+  unsaved: "未保存",
+  saveFailed: "宿主未接受这些值，已保留供你修改。",
+  advancedConfig: "高级配置",
+  autofill: "自动获取",
+  autofilling: "启动中…",
+  autofillHint: "登录百炼控制台，自动填入该账号的 API 密钥与工作空间 ID。",
+  autofillDone: "已回填凭据，下方字段已更新。",
+  autofillAwaitingLogin: "等待在宿主机浏览器中完成百炼控制台登录…",
+  autofillOpenUrl: "手动打开登录页",
+  autofillFailed: "自动获取失败——凭据可能被环境变量锁定、宿主拒绝了写入，或登录未完成。",
+  autofillConfigured: "已配置完成，点击按钮重新获取该账号的 API 密钥与工作空间 ID。",
+  cacheTitle: "检索服务缓存",
+  cacheHint: "注入到每次对话的服务清单。会自动刷新；刚建完服务想立即生效时在这里刷一下。",
+  cacheLoading: "读取中…",
+  cacheUnconfigured: "请先设置工作空间 ID。",
+  cacheUnavailable: "当前浏览器无法访问。",
+  cacheFetchedAt: "上次拉取",
+  cacheNever: "尚未拉取",
+  cacheStale: "待刷新",
+  cacheSearchCount: "检索服务",
+  cacheChatCount: "问答服务",
+  cacheTruncated: "清单已截断 —— 工作空间里的服务多于已拉取的数量。",
+  cacheEmpty: "缓存里没有已部署的服务。如果刚创建过，请刷新。",
+  cacheRefresh: "刷新",
+  cacheRefreshing: "刷新中…",
+  pickerNone: "未设置 —— 会注入完整清单",
+  pickerClear: "清空",
+};

packages/bailian-kb-dsh/tests/bl-cli.test.ts

@@ -0,0 +1,47 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vite-plus/test";
+import { readBlCliConfig } from "../src/bl-cli.js";
+
+const dir = mkdtempSync(join(tmpdir(), "bl-cli-test-"));
+
+function fileWith(name: string, content: string): string {
+  const path = join(dir, name);
+  writeFileSync(path, content);
+  return path;
+}
+
+describe("readBlCliConfig", () => {
+  it("reads api_key and workspace_id from the default profile (top level)", () => {
+    const path = fileWith(
+      "full.json",
+      JSON.stringify({
+        api_key: "sk-abc",
+        workspace_id: "ws-1",
+        output: "text",
+        timeout: 600,
+      }),
+    );
+    expect(readBlCliConfig(path)).toEqual({ apiKey: "sk-abc", workspaceId: "ws-1" });
+  });
+
+  it("omits absent, blank, and non-string fields instead of returning empties", () => {
+    const path = fileWith(
+      "partial.json",
+      JSON.stringify({
+        api_key: "  ",
+        workspace_id: 42,
+      }),
+    );
+    expect(readBlCliConfig(path)).toEqual({});
+    const keyOnly = fileWith("key-only.json", JSON.stringify({ api_key: "sk-abc" }));
+    expect(readBlCliConfig(keyOnly)).toEqual({ apiKey: "sk-abc" });
+  });
+
+  it("reads a missing, malformed, or non-object file as empty", () => {
+    expect(readBlCliConfig(join(dir, "nope.json"))).toEqual({});
+    expect(readBlCliConfig(fileWith("broken.json", "{oops"))).toEqual({});
+    expect(readBlCliConfig(fileWith("array.json", '["sk-abc"]'))).toEqual({});
+  });
+});

packages/bailian-kb-dsh/tests/chat.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vite-plus/test";
+import { consumeChatStream } from "../src/chat.js";
+
+function sse(text: string): Response {
+  return new Response(text, { status: 200 });
+}
+
+function chunk(content: string, finish = ""): string {
+  return `data: ${JSON.stringify({ output: { choices: [{ message: { content }, finish_reason: finish }] }, request_id: "r-1" })}\n\n`;
+}
+
+describe("consumeChatStream", () => {
+  it("concatenates delta content across chunks until [DONE]", async () => {
+    const res = sse(chunk("Hello") + chunk(" world", "stop") + "data: [DONE]\n\n");
+    const out = await consumeChatStream(res);
+    expect(out.answer).toBe("Hello world");
+    expect(out.requestId).toBe("r-1");
+  });
+
+  it("ignores step_change progress chunks with empty content", async () => {
+    const progress = `data: ${JSON.stringify({ output: { choices: [{ message: { content: "", extra: { step_change: "tool_calling" } }, finish_reason: "" }] } })}\n\n`;
+    const res = sse(progress + chunk("answer", "stop") + "data: [DONE]\n\n");
+    expect((await consumeChatStream(res)).answer).toBe("answer");
+  });
+
+  it("throws on an SSE error event with the server message", async () => {
+    const res = sse('event: error\ndata: {"code":"Throttling","message":"rate limited"}\n\n');
+    await expect(consumeChatStream(res)).rejects.toThrow(/Throttling.*rate limited/);
+  });
+});

packages/bailian-kb-dsh/tests/client.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it, vi } from "vite-plus/test";
+import { KbApiError, KbClient } from "../src/client.js";
+
+function makeClient(fetchImpl: typeof fetch) {
+  return new KbClient({
+    resolveWorkspaceId: async () => "ws-1",
+    endpointHost: "cn-beijing.maas.aliyuncs.com",
+    resolveApiKey: async () => "sk-test",
+    fetchImpl,
+  });
+}
+
+describe("KbClient.postJson", () => {
+  it("sends Bearer auth to the workspace endpoint and returns parsed JSON", async () => {
+    const fetchImpl = vi.fn(async () => new Response(JSON.stringify({ ok: 1 }), { status: 200 }));
+    const client = makeClient(fetchImpl as unknown as typeof fetch);
+    const result = await client.postJson<{ ok: number }>("/api/v1/indices/knowledge/search", {
+      query: "q",
+    });
+    expect(result.ok).toBe(1);
+    const [url, init] = fetchImpl.mock.calls[0] as unknown as [string, RequestInit];
+    expect(url).toBe("https://ws-1.cn-beijing.maas.aliyuncs.com/api/v1/indices/knowledge/search");
+    expect((init.headers as Record<string, string>).Authorization).toBe("Bearer sk-test");
+    expect(init.method).toBe("POST");
+  });
+
+  it("translates a non-2xx into KbApiError with status and a bounded body summary", async () => {
+    const body = JSON.stringify({ code: "InvalidParameter", message: "agent not found" });
+    const fetchImpl = vi.fn(async () => new Response(body, { status: 400 }));
+    const client = makeClient(fetchImpl as unknown as typeof fetch);
+    const err = await client
+      .postJson("/api/v1/indices/knowledge/search", {})
+      .catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(KbApiError);
+    expect((err as KbApiError).status).toBe(400);
+    expect((err as KbApiError).message).toContain("agent not found");
+  });
+
+  it("re-resolves the API key per call (credential hot-swap contract)", async () => {
+    const resolveApiKey = vi.fn(async () => "sk-test");
+    const fetchImpl = vi.fn(async () => new Response("{}", { status: 200 }));
+    const client = new KbClient({
+      resolveWorkspaceId: async () => "ws-1",
+      endpointHost: "h",
+      resolveApiKey,
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+    await client.postJson("/p", {});
+    await client.postJson("/p", {});
+    expect(resolveApiKey).toHaveBeenCalledTimes(2);
+  });
+
+  it("re-resolves the workspace id per call (credential hot-swap contract)", async () => {
+    let workspaceId = "ws-1";
+    const fetchImpl = vi.fn(async () => new Response("{}", { status: 200 }));
+    const client = new KbClient({
+      resolveWorkspaceId: async () => workspaceId,
+      endpointHost: "h",
+      resolveApiKey: async () => "sk-test",
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+    await client.postJson("/p", {});
+    workspaceId = "ws-2";
+    await client.postJson("/p", {});
+    const urls = fetchImpl.mock.calls.map((call) => (call as unknown as [string])[0]);
+    expect(urls).toEqual(["https://ws-1.h/p", "https://ws-2.h/p"]);
+  });
+});

packages/bailian-kb-dsh/tests/config.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vite-plus/test";
+import { Config } from "../src/index.js";
+
+describe("Config", () => {
+  it("applies defaults and accepts a pinned workspaceId", () => {
+    const resolved = new Config({ workspaceId: "ws-1" } as never);
+    expect(resolved.workspaceId).toBe("ws-1");
+    expect(resolved.endpointHost).toBe("cn-beijing.maas.aliyuncs.com");
+    expect(resolved.chatTimeoutMs).toBe(300_000);
+    expect(resolved.defaultRetrieveAgentId).toBeUndefined();
+    expect(resolved.defaultChatAgentId).toBeUndefined();
+  });
+
+  it("accepts a missing workspaceId (per-call credentials fallback)", () => {
+    const resolved = new Config({} as never);
+    expect(resolved.workspaceId).toBeUndefined();
+    expect(resolved.endpointHost).toBe("cn-beijing.maas.aliyuncs.com");
+  });
+
+  it("carries the bl-CLI seed ledger through validation", () => {
+    const resolved = new Config({ seededFields: ["apiKey"] } as never);
+    expect(resolved.seededFields).toEqual(["apiKey"]);
+  });
+});

packages/bailian-kb-dsh/tests/console-login.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vite-plus/test";
+import {
+  consoleLoginState,
+  parseCallbackBody,
+  pickCallbackCredentials,
+} from "../src/console-login.js";
+
+describe("parseCallbackBody", () => {
+  it("reads a plain JSON callback", () => {
+    expect(parseCallbackBody('{"api_key":"sk-abc","workspace_id":"ws-1"}')).toMatchObject({
+      api_key: "sk-abc",
+      workspace_id: "ws-1",
+    });
+  });
+
+  it("flattens a `data` envelope, the top level winning", () => {
+    const parsed = parseCallbackBody(
+      '{"data":{"api_key":"sk-inner","workspace_id":"ws-1"},"api_key":"sk-outer"}',
+    );
+    expect(parsed).toMatchObject({ api_key: "sk-outer", workspace_id: "ws-1" });
+  });
+
+  it("reads a form-encoded callback", () => {
+    expect(parseCallbackBody("api_key=sk-abc&workspace_id=ws-1")).toMatchObject({
+      api_key: "sk-abc",
+      workspace_id: "ws-1",
+    });
+  });
+
+  it("tolerates a BOM, surrounding space, and an empty or broken body", () => {
+    expect(parseCallbackBody('\uFEFF  {"api_key":"sk-abc"}  ')).toMatchObject({
+      api_key: "sk-abc",
+    });
+    expect(parseCallbackBody("")).toEqual({});
+    expect(parseCallbackBody("   ")).toEqual({});
+    // A non-object JSON value carries no fields, and neither does an array.
+    expect(parseCallbackBody('["sk-abc"]')).toEqual({});
+  });
+});
+
+describe("pickCallbackCredentials", () => {
+  it("accepts both snake_case and camelCase field names", () => {
+    expect(pickCallbackCredentials({}, { apiKey: "sk-abc", workspaceId: "ws-1" })).toEqual({
+      apiKey: "sk-abc",
+      workspaceId: "ws-1",
+    });
+    expect(pickCallbackCredentials({}, { api_key: "sk-abc", workspace_id: "ws-1" })).toEqual({
+      apiKey: "sk-abc",
+      workspaceId: "ws-1",
+    });
+  });
+
+  it("lets query parameters win over the body", () => {
+    expect(pickCallbackCredentials({ api_key: "sk-query" }, { api_key: "sk-body" })).toEqual({
+      apiKey: "sk-query",
+    });
+  });
+
+  it("omits absent, blank, and non-string fields instead of returning empties", () => {
+    expect(pickCallbackCredentials({}, {})).toEqual({});
+    expect(pickCallbackCredentials({}, { api_key: "   ", workspace_id: 42 })).toEqual({});
+    expect(pickCallbackCredentials({}, { api_key: " sk-abc " })).toEqual({ apiKey: "sk-abc" });
+  });
+});
+
+describe("consoleLoginState", () => {
+  it("starts idle, carrying no secret", () => {
+    expect(consoleLoginState()).toEqual({ phase: "idle" });
+  });
+});

packages/bailian-kb-dsh/tests/endpoints.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from "vite-plus/test";
+import { KB_PATHS, kbEndpoint } from "../src/endpoints.js";
+
+describe("kbEndpoint", () => {
+  it("builds the workspace-subdomain URL", () => {
+    expect(kbEndpoint("cn-beijing.maas.aliyuncs.com", "ws-1", KB_PATHS.search)).toBe(
+      "https://ws-1.cn-beijing.maas.aliyuncs.com/api/v1/indices/knowledge/search",
+    );
+  });
+
+  it("keeps protocol paths as constants", () => {
+    expect(KB_PATHS.chat).toBe("/api/v2/apps/knowledge/chat");
+    expect(KB_PATHS.search).toBe("/api/v1/indices/knowledge/search");
+  });
+});

packages/bailian-kb-dsh/tests/service-cache.test.ts

@@ -0,0 +1,301 @@
+import {
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+  writeFileSync,
+  mkdirSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { describe, expect, it, vi } from "vite-plus/test";
+import type { KbClient } from "../src/client.js";
+import {
+  CACHE_TTL_MS,
+  EMPTY_CACHE_TTL_MS,
+  ServiceCache,
+  readServiceCache,
+  serviceCachePath,
+  writeServiceCache,
+  type ServiceCacheDocument,
+} from "../src/service-cache.js";
+
+const HOST = "cn-beijing.maas.aliyuncs.com";
+
+function tempHome(): string {
+  return mkdtempSync(join(tmpdir(), "bailian-kb-cache-"));
+}
+
+function doc(overrides: Partial<ServiceCacheDocument> = {}): ServiceCacheDocument {
+  return {
+    version: 1,
+    fetchedAt: 1_000,
+    workspaceId: "llm-a",
+    endpointHost: HOST,
+    entries: [{ agent_id: "aid-1", agent_name: "svc", scene: "search", status: "deployed" }],
+    total: 1,
+    truncated: false,
+    ...overrides,
+  };
+}
+
+/** Write raw text to the cache path, bypassing the writer's validation. */
+function seedRaw(home: string, workspaceId: string, text: string): string {
+  const path = serviceCachePath(workspaceId, home);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, text);
+  return path;
+}
+
+describe("serviceCachePath", () => {
+  it("separates workspaces by filename", () => {
+    // An api key only reaches its own workspace, so one shared file would blend accounts.
+    expect(serviceCachePath("llm-a", "/home")).toBe("/home/cache/bailian-kb/services-llm-a.json");
+    expect(serviceCachePath("llm-b", "/home")).not.toBe(serviceCachePath("llm-a", "/home"));
+  });
+});
+
+describe("readServiceCache", () => {
+  it("round-trips a document written by writeServiceCache", () => {
+    const home = tempHome();
+    const path = serviceCachePath("llm-a", home);
+    writeServiceCache(path, doc());
+    expect(readServiceCache(path, "llm-a", HOST)).toEqual(doc());
+  });
+
+  it("reads every unusable file as a miss instead of throwing", () => {
+    const home = tempHome();
+    // Absent.
+    expect(readServiceCache(serviceCachePath("nope", home), "nope", HOST)).toBeUndefined();
+    // Malformed JSON.
+    expect(readServiceCache(seedRaw(home, "a", "{oops"), "a", HOST)).toBeUndefined();
+    // Non-object roots.
+    expect(readServiceCache(seedRaw(home, "b", '["x"]'), "b", HOST)).toBeUndefined();
+    // Newer or older schema: treated as a miss, never migrated.
+    expect(
+      readServiceCache(seedRaw(home, "c", JSON.stringify(doc({ version: 2 }))), "c", HOST),
+    ).toBeUndefined();
+    // Required fields of the wrong type.
+    expect(
+      readServiceCache(
+        seedRaw(home, "d", JSON.stringify(doc({ fetchedAt: "soon" as never }))),
+        "d",
+        HOST,
+      ),
+    ).toBeUndefined();
+  });
+
+  it("refuses a document belonging to another workspace or host", () => {
+    const home = tempHome();
+    const path = seedRaw(home, "llm-a", JSON.stringify(doc({ workspaceId: "llm-other" })));
+    expect(readServiceCache(path, "llm-a", HOST)).toBeUndefined();
+    const hostPath = seedRaw(
+      home,
+      "llm-b",
+      JSON.stringify(doc({ workspaceId: "llm-b", endpointHost: "other.host" })),
+    );
+    expect(readServiceCache(hostPath, "llm-b", HOST)).toBeUndefined();
+  });
+});
+
+describe("writeServiceCache", () => {
+  it("publishes atomically and leaves no temp file behind", () => {
+    const home = tempHome();
+    const path = serviceCachePath("llm-a", home);
+    writeServiceCache(path, doc());
+    const names = readdirSync(dirname(path));
+    expect(names).toEqual(["services-llm-a.json"]);
+    expect(JSON.parse(readFileSync(path, "utf8"))).toEqual(doc());
+  });
+
+  it("creates the cache directory owner-only", () => {
+    const home = tempHome();
+    const path = serviceCachePath("llm-a", home);
+    writeServiceCache(path, doc());
+    expect(statSync(dirname(path)).mode & 0o777).toBe(0o700);
+  });
+});
+
+/** A cache wired to a client returning one page per scene. */
+function cacheWith(home: string, onPost: () => Promise<unknown>, now: () => number = () => 5_000) {
+  const warn = vi.fn();
+  const postJson = vi.fn(onPost);
+  const cache = new ServiceCache({
+    client: { postJson } as unknown as KbClient,
+    resolveWorkspaceId: async () => "llm-a",
+    endpointHost: HOST,
+    warn,
+    home,
+    now,
+  });
+  return { cache, warn, postJson };
+}
+
+describe("ServiceCache", () => {
+  const emptyPage = { code: "Success", data: { total_count: 0, rows: [] } };
+
+  it("treats a missing document as stale and a fresh one as current", () => {
+    const home = tempHome();
+    const { cache } = cacheWith(home, async () => emptyPage);
+    expect(cache.isStale("llm-a")).toBe(true);
+
+    writeServiceCache(serviceCachePath("llm-a", home), doc({ fetchedAt: 5_000 }));
+    cache.invalidate();
+    expect(cache.isStale("llm-a")).toBe(false);
+  });
+
+  it("goes stale once the TTL elapses", () => {
+    const home = tempHome();
+    writeServiceCache(serviceCachePath("llm-a", home), doc({ fetchedAt: 0 }));
+    const { cache } = cacheWith(
+      home,
+      async () => emptyPage,
+      () => CACHE_TTL_MS,
+    );
+    expect(cache.isStale("llm-a")).toBe(true);
+  });
+
+  it("expires an EMPTY list on the much shorter negative TTL", () => {
+    // The trap this closes: configure the plugin against a fresh workspace (0
+    // services) → create a service → and then wait out the full TTL before the
+    // catalog appears. An empty list is a setup-in-progress state, not a fact.
+    const home = tempHome();
+    writeServiceCache(
+      serviceCachePath("llm-a", home),
+      doc({ fetchedAt: 0, entries: [], total: 0 }),
+    );
+    const justAfterEmptyTtl = cacheWith(
+      home,
+      async () => emptyPage,
+      () => EMPTY_CACHE_TTL_MS,
+    );
+    expect(justAfterEmptyTtl.cache.isStale("llm-a")).toBe(true);
+
+    // A non-empty list of the same age is still fresh, so the short window costs
+    // nothing once services exist.
+    writeServiceCache(serviceCachePath("llm-b", home), doc({ workspaceId: "llm-b", fetchedAt: 0 }));
+    const nonEmpty = cacheWith(
+      home,
+      async () => emptyPage,
+      () => EMPTY_CACHE_TTL_MS,
+    );
+    expect(nonEmpty.cache.isStale("llm-b")).toBe(false);
+    expect(EMPTY_CACHE_TTL_MS).toBeLessThan(CACHE_TTL_MS);
+  });
+
+  it('reports a panel snapshot that separates "empty workspace" from "stale list"', () => {
+    const home = tempHome();
+    const { cache } = cacheWith(
+      home,
+      async () => emptyPage,
+      () => 5_000,
+    );
+    // Nothing cached at all: the panel must be able to say "never fetched"
+    // rather than showing a zero that reads as "the workspace is empty".
+    const empty = cache.status("llm-a");
+    expect(empty).not.toHaveProperty("fetchedAt");
+    expect(empty).toMatchObject({ searchCount: 0, chatCount: 0, stale: true });
+
+    writeServiceCache(
+      serviceCachePath("llm-a", home),
+      doc({
+        fetchedAt: 5_000,
+        entries: [
+          {
+            agent_id: "aid-1",
+            agent_name: "a",
+            scene: "search",
+            status: "deployed",
+            modify_time: "2026-08-01",
+          },
+          {
+            agent_id: "aid-2",
+            agent_name: "b",
+            scene: "search",
+            status: "deployed",
+            modify_time: "2026-08-09",
+          },
+          { agent_id: "aid-3", agent_name: "c", scene: "chat", status: "deployed" },
+        ],
+        total: 900,
+        truncated: true,
+      }),
+    );
+    cache.invalidate();
+    expect(cache.status("llm-a")).toMatchObject({
+      fetchedAt: 5_000,
+      searchCount: 2,
+      chatCount: 1,
+      total: 900,
+      truncated: true,
+      stale: false,
+    });
+    // The picker lists newest first so the likely-in-use service is on top.
+    expect(cache.entriesFor("llm-a", "search").map((e) => e.agent_id)).toEqual(["aid-2", "aid-1"]);
+    expect(cache.entriesFor("llm-a", "chat").map((e) => e.agent_id)).toEqual(["aid-3"]);
+  });
+
+  it("re-reads from disk when the workspace changes", () => {
+    const home = tempHome();
+    writeServiceCache(serviceCachePath("llm-a", home), doc({ fetchedAt: 5_000 }));
+    const { cache } = cacheWith(home, async () => emptyPage);
+    expect(cache.peek("llm-a")?.workspaceId).toBe("llm-a");
+    // Switching accounts must not keep serving the previous workspace's list.
+    expect(cache.peek("llm-b")).toBeUndefined();
+  });
+
+  it("shares one in-flight request across concurrent refreshes", async () => {
+    const home = tempHome();
+    // pre-step runs on every model request, so an unguarded refresh would pile up.
+    const { cache, postJson } = cacheWith(home, async () => emptyPage);
+    await Promise.all([cache.refresh(), cache.refresh(), cache.refresh()]);
+    // Two calls total: one per scene, from a single shared refresh.
+    expect(postJson).toHaveBeenCalledTimes(2);
+  });
+
+  it("stores a fetched list and serves it synchronously afterwards", async () => {
+    const home = tempHome();
+    const { cache } = cacheWith(home, async () => ({
+      code: "Success",
+      data: {
+        total_count: 1,
+        rows: [{ agent_id: "aid-9", agent_name: "svc", agent_status: "deployed" }],
+      },
+    }));
+    await cache.refresh();
+    const stored = cache.peek("llm-a");
+    expect(stored?.entries.map((e) => e.agent_id)).toEqual(["aid-9", "aid-9"]); // one per scene
+    expect(stored?.fetchedAt).toBe(5_000);
+    // And it survives as a file for the next process.
+    expect(readServiceCache(serviceCachePath("llm-a", home), "llm-a", HOST)).toEqual(stored);
+  });
+
+  it("never rejects on failure and keeps the previous document", async () => {
+    const home = tempHome();
+    writeServiceCache(serviceCachePath("llm-a", home), doc({ fetchedAt: 5_000 }));
+    const { cache, warn } = cacheWith(home, async () => {
+      throw new Error("network down");
+    });
+    expect(cache.peek("llm-a")?.entries).toHaveLength(1);
+    await expect(cache.refresh()).resolves.toBeUndefined();
+    expect(warn).toHaveBeenCalled();
+    // The stale-but-usable list is still there.
+    expect(cache.peek("llm-a")?.entries).toHaveLength(1);
+  });
+
+  it("does not reject when the workspace is not configured yet", async () => {
+    const home = tempHome();
+    const warn = vi.fn();
+    const cache = new ServiceCache({
+      client: { postJson: vi.fn() } as unknown as KbClient,
+      resolveWorkspaceId: async () => {
+        throw new Error("workspace id is not configured");
+      },
+      endpointHost: HOST,
+      warn,
+      home,
+    });
+    await expect(cache.refresh()).resolves.toBeUndefined();
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("refresh failed"));
+  });
+});

packages/bailian-kb-dsh/tests/service-catalog.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, it } from "vite-plus/test";
+import {
+  CATALOG_ENTRY_LIMIT,
+  buildNoServiceNotice,
+  buildRefreshedSceneList,
+  buildServiceCatalog,
+} from "../src/service-catalog.js";
+import type { ServiceEntry } from "../src/services.js";
+
+function entry(overrides: Partial<ServiceEntry> & { agent_id: string }): ServiceEntry {
+  return {
+    agent_name: `name-${overrides.agent_id}`,
+    scene: "search",
+    status: "deployed",
+    ...overrides,
+  };
+}
+
+function catalog(
+  entries: ServiceEntry[],
+  extra: Partial<Parameters<typeof buildServiceCatalog>[0]> = {},
+) {
+  return buildServiceCatalog({ entries, total: entries.length, truncated: false, ...extra });
+}
+
+describe("buildServiceCatalog", () => {
+  it("returns undefined when there is no service to render", () => {
+    // Nothing to route to; the caller substitutes buildNoServiceNotice(), which
+    // is the branch that tells the model what to do about it.
+    expect(catalog([])).toBeUndefined();
+  });
+
+  it("lists every service when the count is within the limit", () => {
+    const text = catalog([
+      entry({ agent_id: "aid-1", agent_name: "RAG学习-检索" }),
+      entry({ agent_id: "aid-2", agent_name: "产品文档" }),
+    ]);
+    expect(text).toContain("aid-1 — RAG学习-检索");
+    expect(text).toContain("aid-2 — 产品文档");
+    // Nothing was cut, so nothing should claim otherwise.
+    expect(text).not.toContain("showing");
+  });
+
+  it("omits a scene with no services entirely", () => {
+    const text = catalog([entry({ agent_id: "aid-1" })]);
+    expect(text).toContain("kb_search");
+    // "no chat services" is noise that invites handling a case that does not exist.
+    expect(text).not.toContain("kb_chat");
+    expect(text).not.toMatch(/no chat/i);
+  });
+
+  it("renders both scenes without mixing their services", () => {
+    const text =
+      catalog([
+        entry({ agent_id: "aid-s", scene: "search" }),
+        entry({ agent_id: "aid-c", scene: "chat" }),
+      ]) ?? "";
+    const searchAt = text.indexOf("kb_search");
+    const chatAt = text.indexOf("kb_chat");
+    expect(searchAt).toBeGreaterThanOrEqual(0);
+    expect(chatAt).toBeGreaterThan(searchAt);
+    // Each id belongs to its own section.
+    expect(text.indexOf("aid-s")).toBeLessThan(chatAt);
+    expect(text.indexOf("aid-c")).toBeGreaterThan(chatAt);
+  });
+
+  it("shows only the configured default and says how many others exist", () => {
+    const entries = Array.from({ length: 5 }, (_x, i) => entry({ agent_id: `aid-${i}` }));
+    const text = catalog(entries, { defaultRetrieveAgentId: "aid-3" }) ?? "";
+    expect(text).toContain("aid-3");
+    expect(text).not.toContain("aid-0");
+    expect(text).toContain("4 others exist");
+  });
+
+  it("falls back to the full list when the configured default is not in the cache", () => {
+    // A stale or mistyped default must not hide the services that do exist.
+    const text =
+      catalog([entry({ agent_id: "aid-1" })], { defaultRetrieveAgentId: "aid-gone" }) ?? "";
+    expect(text).toContain("aid-1");
+    expect(text).not.toContain("default service");
+  });
+
+  it("caps the list at the limit, newest first, and states the shortfall", () => {
+    const entries = Array.from({ length: 14 }, (_x, i) =>
+      entry({
+        agent_id: `aid-${i}`,
+        // aid-13 newest, aid-0 oldest.
+        modify_time: `2026-08-${String(i + 1).padStart(2, "0")}T00:00:00`,
+      }),
+    );
+    const text = catalog(entries) ?? "";
+    expect(text).toContain("aid-13");
+    // The four oldest fall outside the window.
+    expect(text).not.toContain("aid-0 ");
+    expect(text).toContain(`showing ${CATALOG_ENTRY_LIMIT} most recently modified of 14`);
+    // Silent truncation would make the model treat the list as complete.
+    expect(text).toContain("--name <keyword>");
+  });
+
+  it("marks a capped fetch as a lower bound rather than an exact total", () => {
+    // The fetch itself stopped early, so even the count is unknown.
+    const entries = Array.from({ length: 12 }, (_x, i) => entry({ agent_id: `aid-${i}` }));
+    const text = catalog(entries, { truncated: true, total: 900 }) ?? "";
+    expect(text).toContain("more than");
+  });
+
+  it("states that agent_id is required and forbids guessing one", () => {
+    const text = catalog([entry({ agent_id: "aid-1" })]) ?? "";
+    expect(text).toContain("required");
+    // Picking the closest-looking service returns unrelated evidence, which is
+    // worse for the user than an honest "no such knowledge base".
+    expect(text).toMatch(/say so plainly/i);
+  });
+
+  it("labels an unnamed service instead of rendering a bare dash", () => {
+    const text = catalog([entry({ agent_id: "aid-1", agent_name: "" })]) ?? "";
+    expect(text).toContain("(unnamed)");
+  });
+
+  it("renders a description when one arrives, truncated to its budget", () => {
+    // Forward compatibility: the backend has not shipped this field yet.
+    const long = "x".repeat(250);
+    const text = catalog([entry({ agent_id: "aid-1", description: long })]) ?? "";
+    expect(text).toContain("x".repeat(199));
+    expect(text).not.toContain("x".repeat(201));
+    expect(text).toContain("…");
+  });
+
+  it("explains how to get bl only where it recommends running it", () => {
+    // The plugin never shells out, so a fully configured deployment can have no
+    // bl on PATH. Naming the command without the install line is a dead end.
+    const complete = catalog([entry({ agent_id: "aid-1" })]) ?? "";
+    expect(complete).not.toContain("bl knowledge service list");
+    expect(complete).not.toContain("npm install -g bailian-cli");
+
+    const capped =
+      catalog(Array.from({ length: 12 }, (_x, index) => entry({ agent_id: `aid-${index}` }))) ?? "";
+    expect(capped).toContain("bl knowledge service list");
+    expect(capped).toContain("npm install -g bailian-cli");
+
+    // Same rule on the collapsed-to-default branch, which also names the command.
+    const collapsed =
+      catalog([entry({ agent_id: "aid-1" }), entry({ agent_id: "aid-2" })], {
+        defaultRetrieveAgentId: "aid-1",
+      }) ?? "";
+    expect(collapsed).toContain("bl knowledge service list");
+    expect(collapsed).toContain("npm install -g bailian-cli");
+  });
+});
+
+describe("buildNoServiceNotice", () => {
+  it("names the way out instead of leaving the model to invent an agent_id", () => {
+    const text = buildNoServiceNotice();
+    // agent_id is required, so silence here means a guessed id or a silently
+    // dropped retrieval — both look like a broken plugin to the user.
+    expect(text).toMatch(/do not invent an id/i);
+    expect(text).toContain("bl knowledge service create");
+    expect(text).toContain("bl knowledge service deploy");
+    // The management skill is a second-order path: a model that never loads it
+    // must still learn how to get bl.
+    expect(text).toContain("npm install -g bailian-cli");
+    expect(text).toContain("https://bailian.console.aliyun.com/");
+  });
+});
+
+describe("buildRefreshedSceneList", () => {
+  it("lists the scene's services for a rejected call", () => {
+    const text = buildRefreshedSceneList("search", [
+      entry({ agent_id: "aid-1", agent_name: "产品文档" }),
+    ]);
+    expect(text).toContain("aid-1 — 产品文档");
+    expect(text).toMatch(/re-read just now/i);
+    expect(text).not.toContain("npm install -g bailian-cli");
+  });
+
+  it("states the shortfall and how to get bl when the list is capped", () => {
+    const entries = Array.from({ length: CATALOG_ENTRY_LIMIT + 3 }, (_x, index) =>
+      entry({ agent_id: `aid-${index}` }),
+    );
+    const text = buildRefreshedSceneList("search", entries);
+    expect(text).toContain("and 3 more");
+    expect(text).toContain("npm install -g bailian-cli");
+  });
+
+  it("tells a rejected call to stop retrying when the scene has no services", () => {
+    // Returning nothing here used to let the bare "invalid agent_id" through,
+    // which reads as an invitation to try a different id.
+    const text = buildRefreshedSceneList("chat", []);
+    expect(text).toMatch(/no deployed chat services/i);
+    expect(text).toMatch(/do not retry with a different id/i);
+    expect(text).toContain("bl knowledge service deploy");
+  });
+});

packages/bailian-kb-dsh/tests/service-context.test.ts

@@ -0,0 +1,211 @@
+import { describe, expect, it, vi } from "vite-plus/test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { KbClient } from "../src/client.js";
+import { ServiceCache, serviceCachePath, writeServiceCache } from "../src/service-cache.js";
+import { installServiceContext } from "../src/service-context.js";
+
+const HOST = "cn-beijing.maas.aliyuncs.com";
+const WS = "llm-a";
+const SOURCE_PLUGIN = "tool-bailian-kb/services";
+
+type Injected = { id: string; source: { plugin?: string }; content: { text?: string }[] };
+type Decision = { kind: string; messages: Injected[] };
+
+interface HarnessOptions {
+  entries?: { agent_id: string; agent_name: string; scene: "search" | "chat"; status: string }[];
+  cacheOverride?: ServiceCache;
+  postJson?: () => Promise<unknown>;
+  /** Skip seeding the cache file, i.e. the very first step of a fresh install. */
+  withoutCacheFile?: boolean;
+}
+
+/** Drives the installed `agent/pre-step` listener against a fake session. */
+function harness(options: HarnessOptions = {}) {
+  const home = mkdtempSync(join(tmpdir(), "bailian-kb-ctx-"));
+  const entries = options.entries ?? [
+    { agent_id: "aid-1", agent_name: "svc-one", scene: "search" as const, status: "deployed" },
+  ];
+  if (options.withoutCacheFile !== true) {
+    writeServiceCache(serviceCachePath(WS, home), {
+      version: 1,
+      fetchedAt: Date.now(),
+      workspaceId: WS,
+      endpointHost: HOST,
+      entries,
+      total: entries.length,
+      truncated: false,
+    });
+  }
+  const postJson = vi.fn(
+    options.postJson ?? (async () => ({ code: "Success", data: { total_count: 0, rows: [] } })),
+  );
+  const cache =
+    options.cacheOverride ??
+    new ServiceCache({
+      client: { postJson } as unknown as KbClient,
+      resolveWorkspaceId: async () => WS,
+      endpointHost: HOST,
+      warn: () => {},
+      home,
+    });
+
+  let listener!: (payload: unknown, next: () => Promise<unknown>) => Promise<unknown>;
+  const warn = vi.fn();
+  const ctx = {
+    on: (_event: string, handler: typeof listener) => {
+      listener = handler;
+    },
+  };
+  installServiceContext(ctx as never, {
+    cache,
+    resolveWorkspaceId: async () => WS,
+    resolveDefaultRetrieveAgentId: async () => undefined,
+    resolveDefaultChatAgentId: async () => undefined,
+    warn,
+  });
+
+  const events: { type: string; seq: number; data: unknown }[] = [];
+  const agent = {
+    session: {
+      events,
+      surface: { nodes: [] as number[] },
+      header: { cwd: "/tmp" },
+    },
+  };
+
+  const run = async (proposed: Injected[], downstream: "enter" | "reject"): Promise<Decision> =>
+    (await listener({ agent, signal: { aborted: false, throwIfAborted: () => {} } }, async () =>
+      downstream === "reject" ? { kind: "reject" } : { kind: "enter", messages: proposed },
+    )) as Decision;
+
+  return {
+    cache,
+    warn,
+    postJson,
+    /** One step whose downstream decision enters with `proposed`. */
+    step: async (proposed: Injected[] = []) => await run(proposed, "enter"),
+    /** One step whose downstream decision rejects. */
+    stepRejecting: async () => await run([], "reject"),
+    /** Record an entered message into the durable log and make it visible. */
+    commit: (message: Injected) => {
+      events.push({ type: "user/message", seq: events.length + 1, data: message });
+      agent.session.surface.nodes = events.map((event) => event.seq);
+    },
+    /** Simulate compaction: the events remain, the surface shrinks. */
+    setSurface: (seqs: number[]) => {
+      agent.session.surface.nodes = seqs;
+    },
+    /** This module's own messages within a decision. */
+    injected: (decision: Decision) =>
+      decision.messages.filter((m) => m.source.plugin === SOURCE_PLUGIN),
+  };
+}
+
+describe("installServiceContext", () => {
+  it("injects the catalog as a sourced message on the first step", async () => {
+    const h = harness();
+    const decision = await h.step();
+    expect(decision.kind).toBe("enter");
+    const own = h.injected(decision);
+    expect(own).toHaveLength(1);
+    expect(own[0]?.content[0]?.text).toContain("aid-1");
+  });
+
+  it("does not re-inject on later steps of the same turn", async () => {
+    // pre-step fires once per model request, so a turn with five tool calls
+    // fires it six times. Re-injecting each time would insert six copies and
+    // void the KV cache from the first insertion onward — this is a correctness
+    // guard, not an optimization.
+    const h = harness();
+    const first = await h.step();
+    const own = h.injected(first);
+    expect(own).toHaveLength(1);
+    h.commit(own[0]!);
+
+    for (let toolRoundTrip = 0; toolRoundTrip < 5; toolRoundTrip += 1) {
+      expect(h.injected(await h.step())).toHaveLength(0);
+    }
+  });
+
+  it("re-injects once compaction drops the catalog from the visible surface", async () => {
+    const h = harness();
+    const first = await h.step();
+    h.commit(h.injected(first)[0]!);
+    expect(h.injected(await h.step())).toHaveLength(0);
+
+    // The event stays in the durable log but leaves the surface. Comparing only
+    // "did we ever publish this" would suppress every future injection and the
+    // model would finish the session with no service list at all.
+    h.setSurface([]);
+    expect(h.injected(await h.step())).toHaveLength(1);
+  });
+
+  it("replaces its own pending message instead of adding a second one", async () => {
+    const h = harness();
+    const pending = h.injected(await h.step())[0]!;
+    const second = await h.step([pending]);
+    expect(h.injected(second)).toHaveLength(1);
+  });
+
+  it("injects the no-service notice when the cache holds no services", async () => {
+    // A cached empty list is authoritative, not a missing fetch: staying silent
+    // would leave the model to invent the required agent_id.
+    const h = harness({ entries: [] });
+    const own = h.injected(await h.step());
+    expect(own).toHaveLength(1);
+    expect(own[0]?.content[0]?.text).toMatch(/no\s+deployed knowledge service/i);
+  });
+
+  it("injects nothing while no cache document exists yet", async () => {
+    // Nothing has been fetched, so any claim about the workspace would be a
+    // guess; the background refresh corrects this on a later step.
+    const h = harness({ withoutCacheFile: true });
+    expect(h.injected(await h.step())).toHaveLength(0);
+  });
+
+  it("never awaits the network refresh", async () => {
+    // A slow list request must not delay the user's request.
+    let settle: ((value: unknown) => void) | undefined;
+    const h = harness({
+      postJson: async () =>
+        await new Promise((resolve) => {
+          settle = resolve;
+        }),
+    });
+    // Force staleness so this step schedules a refresh.
+    h.cache.invalidate();
+    const raced = await Promise.race([
+      h.step().then(() => "stepped"),
+      new Promise((resolve) => {
+        setTimeout(() => resolve("timed out"), 200);
+      }),
+    ]);
+    expect(raced).toBe("stepped");
+    settle?.({ data: { rows: [] } });
+  });
+
+  it("degrades to no injection when anything throws, never failing the step", async () => {
+    // A throwing pre-step listener fails the proposed step, i.e. stalls the
+    // user's turn. A missing catalog is far cheaper than that.
+    const exploding = {
+      isStale: () => {
+        throw new Error("corrupt cache");
+      },
+      peek: () => undefined,
+      refresh: async () => {},
+      invalidate: () => {},
+    } as unknown as ServiceCache;
+    const h = harness({ cacheOverride: exploding });
+    const decision = await h.step();
+    expect(decision.kind).toBe("enter");
+    expect(h.injected(decision)).toHaveLength(0);
+    expect(h.warn).toHaveBeenCalled();
+  });
+
+  it("passes a rejected downstream decision straight through", async () => {
+    const h = harness();
+    expect((await h.stepRejecting()).kind).toBe("reject");
+  });
+});

packages/bailian-kb-dsh/tests/services.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it, vi } from "vite-plus/test";
+import type { ServiceListResponse } from "../src/api-types.js";
+import type { KbClient } from "../src/client.js";
+import { listServices } from "../src/services.js";
+
+/** A page of `count` rows, all deployed unless overridden. */
+function page(
+  count: number,
+  total: number,
+  overrides: Record<string, unknown> = {},
+): ServiceListResponse {
+  return {
+    code: "Success",
+    data: {
+      total_count: total,
+      rows: Array.from({ length: count }, (_row, index) => ({
+        agent_id: `aid-${index}`,
+        agent_name: `service-${index}`,
+        agent_status: "deployed",
+        modify_time: "2026-08-20T10:00:00",
+        ...overrides,
+      })),
+    },
+  };
+}
+
+/** A client whose postJson is driven by a queue of per-call responses or errors. */
+function clientReturning(...outcomes: (ServiceListResponse | Error)[]): {
+  client: KbClient;
+  postJson: ReturnType<typeof vi.fn>;
+} {
+  const postJson = vi.fn(async () => {
+    const next = outcomes.shift();
+    if (next === undefined) throw new Error("unexpected extra request");
+    if (next instanceof Error) throw next;
+    return next;
+  });
+  return { client: { postJson } as unknown as KbClient, postJson };
+}
+
+describe("listServices", () => {
+  it("queries both scenes for deployed services only and tags each entry with its scene", async () => {
+    const { client, postJson } = clientReturning(page(1, 1), page(1, 1));
+    const result = await listServices(client);
+
+    expect(postJson.mock.calls[0]?.[1]).toMatchObject({
+      agent_scene: "search",
+      // Verified server-side: this filter is honored and excludes drafts.
+      agent_status: "deployed",
+      page_number: 1,
+      page_size: 100,
+    });
+    expect(postJson.mock.calls[1]?.[1]).toMatchObject({ agent_scene: "chat" });
+    expect(result.entries.map((e) => e.scene)).toEqual(["search", "chat"]);
+    expect(result.total).toBe(2);
+    expect(result.truncated).toBe(false);
+    expect(result.failedScenes).toEqual([]);
+  });
+
+  it("stops at a short page without asking for another", async () => {
+    // 3 rows on a 100-row page is the last page; a second request would be waste.
+    const { client, postJson } = clientReturning(page(3, 3), page(0, 0));
+    const result = await listServices(client);
+    expect(postJson).toHaveBeenCalledTimes(2); // one per scene, not one per page
+    expect(result.entries).toHaveLength(3);
+  });
+
+  it("caps at two pages per scene and reports the shortfall as truncated", async () => {
+    // A workspace claiming 500 rows: fetch 200, flag the rest as unfetched.
+    const { client, postJson } = clientReturning(page(100, 500), page(100, 500), page(0, 0));
+    const result = await listServices(client);
+    // 2 pages for search + 1 short page for chat: the cap holds.
+    expect(postJson).toHaveBeenCalledTimes(3);
+    expect(result.entries).toHaveLength(200);
+    expect(result.truncated).toBe(true);
+  });
+
+  it("keeps one scene when the other fails instead of losing the whole list", async () => {
+    const { client } = clientReturning(page(2, 2), new Error("chat scene exploded"));
+    const result = await listServices(client);
+    expect(result.entries).toHaveLength(2);
+    expect(result.entries.every((e) => e.scene === "search")).toBe(true);
+    expect(result.failedScenes).toEqual(["chat"]);
+  });
+
+  it("reports both scenes as failed without throwing", async () => {
+    const { client } = clientReturning(new Error("down"), new Error("down"));
+    const result = await listServices(client);
+    expect(result.entries).toEqual([]);
+    expect(result.failedScenes).toEqual(["search", "chat"]);
+  });
+
+  it("drops rows without an agent_id and never reads pipeline_list", async () => {
+    // pipeline_list is unreliable in production (missing names, sometimes empty),
+    // so entries must not carry any knowledge-base label derived from it.
+    const { client } = clientReturning(
+      {
+        code: "Success",
+        data: {
+          total_count: 2,
+          rows: [
+            { agent_name: "no id", agent_status: "deployed" },
+            {
+              agent_id: "aid-1",
+              agent_name: "ok",
+              agent_status: "deployed",
+              pipeline_list: [{ pipeline_id: "p1" }],
+            },
+          ],
+        },
+      },
+      page(0, 0),
+    );
+    const result = await listServices(client);
+    expect(result.entries).toHaveLength(1);
+    expect(result.entries[0]).toEqual({
+      agent_id: "aid-1",
+      agent_name: "ok",
+      scene: "search",
+      status: "deployed",
+    });
+    expect(JSON.stringify(result.entries)).not.toContain("p1");
+  });
+});

packages/bailian-kb-dsh/tests/skill.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vite-plus/test";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { parseSkillFile } from "../src/skill.js";
+
+const SKILL_PATH = fileURLToPath(new URL("../skills/bailian-kb/SKILL.md", import.meta.url));
+
+describe("parseSkillFile", () => {
+  it("takes name and description from frontmatter and strips the block from the body", () => {
+    const parsed = parseSkillFile(
+      [
+        "---",
+        "name: demo-skill",
+        "description: >-",
+        "  First line of the folded description,",
+        "  continued on the next source line.",
+        "---",
+        "",
+        "# Heading",
+        "",
+        "Body text.",
+        "",
+      ].join("\n"),
+    );
+    expect(parsed?.name).toBe("demo-skill");
+    // A folded scalar joins its lines with spaces; the value must arrive unfolded.
+    expect(parsed?.description).toBe(
+      "First line of the folded description, continued on the next source line.",
+    );
+    // The registry performs no parsing of its own, so the YAML must already be gone.
+    expect(parsed?.content).toBe("\n# Heading\n\nBody text.\n");
+    expect(parsed?.content).not.toContain("---");
+    expect(parsed?.content).not.toContain("description:");
+  });
+
+  it("carries optional whenToUse and metadata, omitting them when absent or blank", () => {
+    const withExtras = parseSkillFile(
+      [
+        "---",
+        "name: demo-skill",
+        "description: Routing text.",
+        "whenToUse: Extra guidance.",
+        "metadata:",
+        "  owner: platform",
+        "---",
+        "Body.",
+      ].join("\n"),
+    );
+    expect(withExtras?.whenToUse).toBe("Extra guidance.");
+    expect(withExtras?.metadata).toEqual({ owner: "platform" });
+
+    const bare = parseSkillFile("---\nname: demo-skill\ndescription: Routing text.\n---\nBody.");
+    expect(bare).not.toHaveProperty("whenToUse");
+    expect(bare).not.toHaveProperty("metadata");
+  });
+
+  it("rejects a file without usable frontmatter instead of throwing", () => {
+    // No fence at all: a plain markdown file.
+    expect(parseSkillFile("# Just markdown\n")).toBeUndefined();
+    // Opening fence never closes.
+    expect(parseSkillFile("---\nname: demo-skill\n")).toBeUndefined();
+    // Unparsable YAML inside the fence.
+    expect(parseSkillFile("---\nname: [unclosed\n---\nBody.")).toBeUndefined();
+    // Scalar and sequence roots are not frontmatter records.
+    expect(parseSkillFile("---\njust a string\n---\nBody.")).toBeUndefined();
+    expect(parseSkillFile("---\n- one\n- two\n---\nBody.")).toBeUndefined();
+    // name or description missing, blank, or the wrong type.
+    expect(parseSkillFile("---\ndescription: Routing text.\n---\nBody.")).toBeUndefined();
+    expect(parseSkillFile("---\nname: demo-skill\n---\nBody.")).toBeUndefined();
+    expect(parseSkillFile('---\nname: demo-skill\ndescription: "   "\n---\nBody.')).toBeUndefined();
+    expect(parseSkillFile("---\nname: 42\ndescription: Routing text.\n---\nBody.")).toBeUndefined();
+  });
+});
+
+describe("the packaged bailian-kb SKILL.md", () => {
+  const parsed = parseSkillFile(readFileSync(SKILL_PATH, "utf8"));
+
+  it("parses, and is the single source of the registered name and description", () => {
+    expect(parsed?.name).toBe("bailian-kb");
+    expect(parsed?.description).toContain("bl");
+    // The frontmatter must state where credentials come from: that sentence used
+    // to live in skill.ts and would otherwise be lost with the duplicate.
+    expect(parsed?.description).toContain("DASHSCOPE_API_KEY");
+  });
+
+  it("keeps its description within the catalog truncation budget", () => {
+    // tool-skill publishes catalog entries through catalogDescription(), which
+    // whitespace-normalizes and hard-truncates at 500 characters.
+    const normalized = (parsed?.description ?? "").replaceAll(/\s+/g, " ").trim();
+    expect(normalized.length).toBeLessThanOrEqual(500);
+  });
+
+  it("registers a body with no frontmatter residue", () => {
+    expect(parsed?.content.startsWith("---")).toBe(false);
+    expect(parsed?.content).not.toContain("description: >-");
+    // The real body still begins with the document heading.
+    expect(parsed?.content.trimStart().startsWith("#")).toBe(true);
+  });
+});

packages/bailian-kb-dsh/tests/sse.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vite-plus/test";
+import { parseSseStream } from "../src/sse.js";
+
+function streamOf(text: string): ReadableStream<Uint8Array> {
+  return new Response(text).body as ReadableStream<Uint8Array>;
+}
+
+async function collect(text: string) {
+  const events: { event?: string; data: string }[] = [];
+  for await (const e of parseSseStream(streamOf(text))) events.push(e);
+  return events;
+}
+
+describe("parseSseStream", () => {
+  it("yields data events split on blank lines", async () => {
+    const events = await collect('data: {"a":1}\n\ndata: [DONE]\n\n');
+    expect(events).toEqual([
+      { event: undefined, data: '{"a":1}' },
+      { event: undefined, data: "[DONE]" },
+    ]);
+  });
+
+  it("carries the event field and parses CRLF lines", async () => {
+    const events = await collect('event: error\r\ndata: {"message":"boom"}\r\n\r\n');
+    expect(events[0]).toEqual({ event: "error", data: '{"message":"boom"}' });
+  });
+
+  it("flushes a final event not terminated by a blank line", async () => {
+    const events = await collect("data: tail\n");
+    expect(events).toEqual([{ event: undefined, data: "tail" }]);
+  });
+});

packages/bailian-kb-dsh/tests/tools.test.ts

@@ -0,0 +1,205 @@
+import { describe, expect, it, vi } from "vite-plus/test";
+import { KbApiError, KbClient } from "../src/client.js";
+import { createKbTools } from "../src/tools.js";
+
+const EXEC = {} as never;
+
+function toolsWith(
+  postJson: unknown,
+  postSse?: unknown,
+  resolveDefaultRetrieveAgentId?: () => Promise<string | undefined>,
+  resolveDefaultChatAgentId?: () => Promise<string | undefined>,
+  describeServicesAfterRefresh?: (scene: "search" | "chat") => Promise<string | undefined>,
+) {
+  const client = { postJson, postSse, agentVersion: undefined } as unknown as KbClient;
+  const list = createKbTools({
+    client,
+    ...(resolveDefaultRetrieveAgentId ? { resolveDefaultRetrieveAgentId } : {}),
+    ...(resolveDefaultChatAgentId ? { resolveDefaultChatAgentId } : {}),
+    ...(describeServicesAfterRefresh ? { describeServicesAfterRefresh } : {}),
+    chatTimeoutMs: 1000,
+  });
+  const byName = Object.fromEntries(list.map((t) => [t.name, t]));
+  return { byName, list };
+}
+
+const searchResponse = {
+  request_id: "r1",
+  data: {
+    total: 3,
+    nodes: [
+      { score: 0.9, text: "A", metadata: { doc_name: "d1" } },
+      { score: 0.8, text: "B", metadata: {} },
+      { score: 0.7, text: "C", metadata: {} },
+    ],
+  },
+};
+
+describe("createKbTools", () => {
+  it("registers kb_search and kb_chat", () => {
+    const { list } = toolsWith(vi.fn());
+    expect(list.map((t) => t.name).sort()).toEqual(["kb_chat", "kb_search"]);
+  });
+
+  it("keeps both descriptions free of service ids so the schemas stay prefix-stable", () => {
+    // The live service list rides an `agent/pre-step` context message precisely
+    // because re-registering a tool to refresh its description would void the
+    // prompt prefix cache. Any id leaking in here means that decision regressed.
+    const { byName } = toolsWith(vi.fn());
+    for (const tool of [byName.kb_search!, byName.kb_chat!]) {
+      const text = `${tool.description} ${JSON.stringify(tool.parameters)}`;
+      expect(text).not.toMatch(/aid-[0-9a-f]/);
+    }
+  });
+
+  it("kb_search truncates nodes client-side to top_k and never sends top_k to the server", async () => {
+    const postJson = vi.fn(async (_path: string, _body: unknown) => searchResponse);
+    const { byName } = toolsWith(postJson);
+    const out = (await byName.kb_search!.execute(
+      { query: "q", agent_id: "aid-1", top_k: 2 },
+      EXEC,
+    )) as { chunks: unknown[] };
+    expect(out.chunks).toHaveLength(2);
+    const body = postJson.mock.calls[0]![1] as Record<string, unknown>;
+    expect(body).not.toHaveProperty("top_k");
+    expect(body.agent_id).toBe("aid-1");
+  });
+
+  it("agent_id is required in the schema for both tools", () => {
+    const { byName } = toolsWith(vi.fn());
+    // defineTool compiles the spec into JSON Schema: requiredness lives in the top-level `required` array.
+    const requiredList = (tool: { parameters: Record<string, unknown> }) =>
+      (tool.parameters.required ?? []) as string[];
+    expect(requiredList(byName.kb_search!)).toContain("agent_id");
+    expect(requiredList(byName.kb_chat!)).toContain("agent_id");
+  });
+
+  it("a missing agent_id is rejected by schema validation before execute (even with a default resolver)", async () => {
+    const postJson = vi.fn(async (_path: string, _body: unknown) => searchResponse);
+    const resolveDefaultRetrieveAgentId = vi.fn(async () => "aid-fixed");
+    const { byName } = toolsWith(postJson, undefined, resolveDefaultRetrieveAgentId);
+    // defineTool validates args against the compiled schema before execute runs,
+    // so with agent_id required the per-call default fallback is never consulted
+    // through this entry point; it stays as defense-in-depth only.
+    const err = await byName.kb_search!.execute({ query: "q" }, EXEC).catch((e: unknown) => e);
+    expect((err as Error).message).toContain("agent_id");
+    expect(resolveDefaultRetrieveAgentId).not.toHaveBeenCalled();
+    expect(postJson).not.toHaveBeenCalled();
+  });
+
+  it("a missing agent_id without any default is also a schema rejection, not the runtime guidance error", async () => {
+    const { byName } = toolsWith(vi.fn());
+    const err = await byName.kb_search!.execute({ query: "q" }, EXEC).catch((e: unknown) => e);
+    expect((err as Error).message).toContain("missing required property");
+  });
+
+  it("a supplied agent_id bypasses the default resolver entirely", async () => {
+    const postJson = vi.fn(async (_path: string, _body: unknown) => searchResponse);
+    const resolveDefaultRetrieveAgentId = vi.fn(async () => "aid-default");
+    const { byName } = toolsWith(postJson, undefined, resolveDefaultRetrieveAgentId);
+    await byName.kb_search!.execute({ query: "q", agent_id: "aid-explicit" }, EXEC);
+    expect(resolveDefaultRetrieveAgentId).not.toHaveBeenCalled();
+    expect((postJson.mock.calls[0]![1] as Record<string, unknown>).agent_id).toBe("aid-explicit");
+  });
+
+  it("a 4xx failure passes the original error through unchanged when no refresh hook is wired", async () => {
+    const postJson = vi.fn(async (_path: string) => {
+      throw new KbApiError("agent not found", 400);
+    });
+    const { byName } = toolsWith(postJson);
+    const err = await byName
+      .kb_search!.execute({ query: "q", agent_id: "bad" }, EXEC)
+      .catch((e: unknown) => e);
+    expect((err as Error).message).toBe("agent not found");
+  });
+
+  it("a 4xx failure appends the refreshed service list for the calling scene", async () => {
+    // agent_id is the only caller-supplied identifier on these endpoints, so a
+    // rejected request most often means the cached id is gone. The recovery the
+    // model needs is the current list, and an error message carries it without
+    // disturbing the request prefix.
+    const postJson = vi.fn(async (_path: string) => {
+      throw new KbApiError("agent not found", 400);
+    });
+    const describe = vi.fn(async (scene: "search" | "chat") => `services for ${scene}: aid-new`);
+    const { byName } = toolsWith(postJson, undefined, undefined, undefined, describe);
+    const err = await byName
+      .kb_search!.execute({ query: "q", agent_id: "stale" }, EXEC)
+      .catch((e: unknown) => e);
+    expect(describe).toHaveBeenCalledWith("search");
+    expect((err as Error).message).toContain("agent not found");
+    expect((err as Error).message).toContain("services for search: aid-new");
+  });
+
+  it("leaves a 5xx failure and a failing refresh alone", async () => {
+    // A server-side fault is not an id problem, and a refresh that itself fails
+    // must not replace the real error with its own.
+    const serverError = vi.fn(async (_path: string) => {
+      throw new KbApiError("upstream exploded", 502);
+    });
+    const describe = vi.fn(async () => "never used");
+    const { byName } = toolsWith(serverError, undefined, undefined, undefined, describe);
+    const err = await byName
+      .kb_search!.execute({ query: "q", agent_id: "aid-1" }, EXEC)
+      .catch((e: unknown) => e);
+    expect(describe).not.toHaveBeenCalled();
+    expect((err as Error).message).toBe("upstream exploded");
+
+    const badRequest = vi.fn(async (_path: string) => {
+      throw new KbApiError("agent not found", 400);
+    });
+    const failing = vi.fn(async () => {
+      throw new Error("refresh also down");
+    });
+    const { byName: byName2 } = toolsWith(badRequest, undefined, undefined, undefined, failing);
+    const err2 = await byName2
+      .kb_search!.execute({ query: "q", agent_id: "bad" }, EXEC)
+      .catch((e: unknown) => e);
+    expect((err2 as Error).message).toBe("agent not found");
+  });
+
+  it("kb_chat buffers the SSE stream into one answer", async () => {
+    const sse =
+      'data: {"output":{"choices":[{"message":{"content":"hi"},"finish_reason":"stop"}]},"request_id":"r2"}\n\ndata: [DONE]\n\n';
+    const postSse = vi.fn(async () => new Response(sse, { status: 200 }));
+    const { byName } = toolsWith(vi.fn(), postSse);
+    const out = (await byName.kb_chat!.execute({ message: "q", agent_id: "aid-1" }, EXEC)) as {
+      answer: string;
+    };
+    expect(out.answer).toBe("hi");
+  });
+
+  it("kb_chat translates a timeout into retry-or-search guidance", async () => {
+    const timeout = Object.assign(new Error("operation timed out"), { name: "TimeoutError" });
+    const postSse = vi.fn(async () => {
+      throw timeout;
+    });
+    const { byName } = toolsWith(vi.fn(), postSse);
+    const err = await byName
+      .kb_chat!.execute({ message: "q", agent_id: "aid-1" }, EXEC)
+      .catch((e: unknown) => e);
+    expect((err as Error).message).toMatch(/timed out.*kb_search/s);
+  });
+
+  it("kb_chat reads chatTimeoutMs off deps per call (live-settings getter stays live)", async () => {
+    const timeout = Object.assign(new Error("operation timed out"), { name: "TimeoutError" });
+    const postSse = vi.fn(async () => {
+      throw timeout;
+    });
+    const client = { postJson: vi.fn(), postSse, agentVersion: undefined } as unknown as KbClient;
+    // Mirrors the host apply: a getter over the mutable settings source.
+    let timeoutMs = 1000;
+    const list = createKbTools({
+      client,
+      get chatTimeoutMs() {
+        return timeoutMs;
+      },
+    });
+    const chat = list.find((t) => t.name === "kb_chat")!;
+    timeoutMs = 2222;
+    const err = await chat
+      .execute({ message: "q", agent_id: "aid-1" }, EXEC)
+      .catch((e: unknown) => e);
+    expect((err as Error).message).toContain("2222ms");
+  });
+});

packages/bailian-kb-dsh/tsconfig.build.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "types": ["node"],
+    "strict": true,
+    "declaration": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "exclude": ["src/web"]
+}

packages/bailian-kb-dsh/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "types": ["node"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": ["src", "tests"]
+}

packages/bailian-kb-dsh/tsconfig.web.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "allowImportingTsExtensions": true,
+    "types": []
+  },
+  "include": ["src/web"]
+}

packages/bailian-kb-dsh/tsdown.config.ts

@@ -0,0 +1,133 @@
+/**
+ * Browser bundle for the plugin's client half, mirroring the host's tsdown
+ * client preset (packages/client/tsdown.client.ts — spelled out here because
+ * an out-of-tree package cannot import it): a closure-factory artifact that
+ * calls window.__ModuleLoader__.load({id, factory}) and resolves externals
+ * through the injected require. CSS Modules are compiled by lightningcss
+ * inside the bundle: importing `x.module.css` yields the hashed class map and
+ * auto-injects a <style data-plugin> tag at factory execution.
+ */
+import { readFile } from "node:fs/promises";
+import { basename, dirname, resolve as resolvePath } from "node:path";
+import { defineConfig } from "tsdown";
+import { transform } from "lightningcss";
+
+/** Plugin id stamped into the __ModuleLoader__.load handoff and style tags. */
+const PLUGIN_ID = "bailian-kb-dsh";
+
+/** The module specifiers the shell shares into the frozen module table. */
+const PLATFORM_MODULES = [
+  "react",
+  "react/jsx-runtime",
+  "react-dom",
+  "react-dom/client",
+  "@deepseek-ai/cordis",
+  "@deepseek-ai/dsh-client-ui-slots",
+  "@deepseek-ai/dsh-client-web-react",
+  "@deepseek-ai/dsh-client-ui-primitives",
+  "@deepseek-ai/dsh-client-ui-attachment",
+  "@deepseek-ai/dsh-client-schema-form",
+];
+
+/**
+ * Documented host exemption (not a platform module): the snapshot-store
+ * engine lives in runtime pending its rehoming; at runtime the lazy CJS table
+ * answers the require natively.
+ */
+const RUNTIME_STORE_EXEMPTION = "@deepseek-ai/dsh-client-runtime/client";
+
+/** Externals resolved from the loader module table. */
+const CLIENT_EXTERNALS: readonly string[] = [...PLATFORM_MODULES, RUNTIME_STORE_EXEMPTION];
+
+/** Virtual-id wrapper keeping module CSS away from tsdown's own css pipeline. */
+const CSS_VIRTUAL_PREFIX = "\0dsh-css:";
+const CSS_VIRTUAL_SUFFIX = ".mjs";
+
+export default defineConfig({
+  name: `${PLUGIN_ID}/client`,
+  entry: { client: "src/web/index.ts" },
+  // Browser bundle lands in its own dist/web subdir: the tsc node half owns
+  // dist/ directly, and a shared outDir would clobber dist/client.js (the KbClient
+  // module) with this artifact. The entryFileNames pin keeps it exactly
+  // dist/web/client.js; the host serves it at /plugins/<id>/client.js via
+  // exports["./client"]. clean must stay off — a default clean would wipe the
+  // tsc-emitted node half.
+  outDir: "dist/web",
+  format: "cjs",
+  platform: "browser",
+  dts: false,
+  sourcemap: true,
+  clean: false,
+  external: [...CLIENT_EXTERNALS],
+  // tsdown auto-externalizes package dependencies; anything NOT in the loader
+  // module table must inline instead. A require() the table cannot answer is a
+  // guaranteed runtime throw, so the rule is the table list itself.
+  noExternal: (id: string) => (CLIENT_EXTERNALS.includes(id) ? undefined : true),
+  define: {
+    "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV ?? "production"),
+    "import.meta.env.MODE": JSON.stringify(process.env.NODE_ENV ?? "production"),
+    "import.meta.env": JSON.stringify({ MODE: process.env.NODE_ENV ?? "production" }),
+  },
+  plugins: [
+    {
+      // Bundle purity gate (build-time mirror of the module-edge rules):
+      // platform seed entries stay external; every other @deepseek-ai value
+      // import is a build error — a cross-plugin value import either inlines a
+      // duplicate runtime instance or requires a specifier the frozen module
+      // table cannot answer. Cross-plugin collaboration goes through cordis
+      // services instead (type-only imports are erased and never reach this gate).
+      name: "dsh-client-bundle-purity",
+      resolveId(source: string) {
+        if (!source.startsWith("@deepseek-ai/")) return null;
+        if (CLIENT_EXTERNALS.includes(source)) return null; // platform module: external wins
+        throw new Error(
+          `client bundle purity: "${source}" is not a platform module (CLIENT_EXTERNALS) — ` +
+            "cross-plugin value imports are forbidden; collaborate through cordis services " +
+            "(type-only imports are erased and never reach this gate)",
+        );
+      },
+    },
+    {
+      name: "dsh-css-modules-inline",
+      resolveId(source: string, importer: string | undefined) {
+        if (!source.endsWith(".module.css")) return null;
+        const abs = importer !== undefined ? resolvePath(dirname(importer), source) : source;
+        return CSS_VIRTUAL_PREFIX + abs + CSS_VIRTUAL_SUFFIX;
+      },
+      async load(virtualId: string) {
+        if (!virtualId.startsWith(CSS_VIRTUAL_PREFIX)) return null;
+        const fileId = virtualId.slice(CSS_VIRTUAL_PREFIX.length, -CSS_VIRTUAL_SUFFIX.length);
+        // The virtual id otherwise hides the physical stylesheet from the watch graph.
+        this.addWatchFile(fileId);
+        const source = await readFile(fileId);
+        const { code, exports: cssExports } = transform({
+          filename: fileId,
+          code: source,
+          cssModules: { pattern: "[hash]_[local]" },
+          minify: true,
+        });
+        const classMap: Record<string, string> = {};
+        for (const [local, exp] of Object.entries(cssExports ?? {})) classMap[local] = exp.name;
+        // One <style data-plugin> per module file; idempotent under re-evaluation.
+        return [
+          `const css = ${JSON.stringify(code.toString())};`,
+          `const tagId = ${JSON.stringify(`${PLUGIN_ID}/${basename(fileId)}`)};`,
+          "if (typeof document !== 'undefined' && document.querySelector('style[data-plugin-css=' + JSON.stringify(tagId) + ']') === null) {",
+          "  const tag = document.createElement('style');",
+          `  tag.dataset.plugin = ${JSON.stringify(PLUGIN_ID)};`,
+          "  tag.dataset.pluginCss = tagId;",
+          "  tag.textContent = css;",
+          "  document.head.appendChild(tag);",
+          "}",
+          `export default ${JSON.stringify(classMap)};`,
+        ].join("\n");
+      },
+    },
+  ],
+  outputOptions: {
+    entryFileNames: "client.js",
+    banner: `window.__ModuleLoader__.load({ id: ${JSON.stringify(PLUGIN_ID)}, factory: (require) => {`,
+    footer: "return module.exports; } });",
+    intro: "var module = { exports: {} }; var exports = module.exports;",
+  },
+});

packages/bailian-kb-dsh/vite.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from "vite-plus";
+
+// 本包不用 `vp pack`：产物是 tsc 出的 node 半（dist/）+ tsdown 出的浏览器 bundle
+// （dist/web/client.js，带 __ModuleLoader__ banner 与 lightningcss CSS Modules 内联），
+// 由包内 `build` script 负责。这里只接管 lint / fmt / test。
+export default defineConfig({
+  lint: {
+    options: {
+      typeAware: true,
+      typeCheck: true,
+    },
+  },
+  fmt: {},
+});

packages/cli/.gitignore

@@ -2,4 +2,7 @@ node_modules
 dist
 *.log
 .DS_Store
-outputs/
+outputs/
+# agents
+agents.state.json
+.env

packages/cli/README.md

@@ -5,7 +5,7 @@
 **The official command-line interface for Aliyun Model Studio (DashScope) AI Platform**
 
 [![npm version](https://img.shields.io/npm/v/bailian-cli?color=0969da&label=npm)](https://www.npmjs.com/package/bailian-cli)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D22.12-brightgreen)](https://nodejs.org)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.17-brightgreen)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)](https://www.typescriptlang.org)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
 
@@ -13,8 +13,9 @@
 
 ---
 
-_Chat with Qwen, generate images & videos, understand images, call agents,_
-_manage memory, search the web — all from your terminal._
+_Chat with Qwen, generate and edit images and videos, understand images, synthesize_
+_and recognize speech, call apps, manage memory, retrieve knowledge, search the web —_
+_every AI capability, one command away._
 
 _Built for AI Agents. Every command works as a structured tool call._
 
@@ -22,27 +23,16 @@ _Built for AI Agents. Every command works as a structured tool call._
 
 ## Features
 
-Equip your AI Agent out-of-the-box with these capabilities, composable across complex tasks:
+- **Model generation** — Full-modality generation across text, image, video, and speech, with editing and reference-based generation
+- **Asset understanding** — Parse and ask questions about images, documents, audio, and long videos
+- **App orchestration** — Call Managed Agents, agents, and workflows published on Aliyun Model Studio, wired to knowledge bases, memory, web search, and MCP tools
+- **Training & deployment** — Validate and upload datasets, fine-tune models, deploy dedicated models as endpoints
+- **Account operations** — Login, UI-based configuration, model marketplace, usage and quota, rate-limit increases, team seat management
+- **Plan onboarding** — Connect subscription plans such as Token Plan to the CLI and common coding agents in one step
 
-- **Text chat** — Qwen3.7-max: major gains in agentic coding, frontend coding, and vibe coding
-- **Multimodal (Omni)** — Full omni-modal support across text + image + audio + video
-- **Image generation & editing** — Qwen-Image 2.0: pro text rendering, photorealism, strong semantic adherence, multi-image composition
-- **Video generation & editing** — happyhorse-1.1 series: text-/image-/reference-to-video and natural-language video editing (up to 9-image reference)
-- **Speech synthesis & recognition** — CosyVoice streaming TTS, voice cloning from 5–20s samples; FunAudio-ASR covers 30 languages including 7 Chinese dialects and 20+ Mandarin accents
-- **Image & video understanding** — Qwen-VL: long-form video analysis, chart/document parsing, visual reasoning, multilingual OCR
+> **Note:** App orchestration, training & deployment, account operations, and plan onboarding are currently available only to China site (aliyun.com) account holders and are not yet supported for international / global site accounts.
 
-> **Note:** The features below are currently available only to China site (aliyun.com) account holders and are not yet supported for international / global site accounts.
-
-- **Knowledge base & memory** — Multimodal RAG retrieval and cross-session memory for personalized, coherent dialogue
-- **App calls** — Invoke agents and workflows already published on Aliyun Model Studio
-- **MCP integration** — Orchestrate Bailian MCP servers: list services, inspect tools, and invoke any tool directly from the terminal
-- **Web search** — Real-time internet retrieval for up-to-date, accurate answers
-- **Model recommendation** — Describe your scenario and get best-fit model suggestions; supports scoped search, model comparison, and alternative discovery
-- **Fine-tuning & deployment** — Upload datasets, create text/audio/image fine-tune jobs (`finetune text|audio|image create`; text covers SFT/LoRA/DPO/CPT), probe job status non-blockingly (`finetune watch`), query per-model training capability (`finetune capability`), and deploy trained models as endpoints (`deploy text|audio|image create`)
-- **Console capabilities** — Browse the model marketplace (`model list`) and Bailian apps (`app list`), review a unified usage view (`usage summary`), check free-tier quota (`usage free`), view model usage statistics (`usage stats`), manage workspaces (`workspace list`), and manage rate limits (`quota list/request/check/history`)
-- **Local file auto-upload** — Every URL parameter accepts a local path; uploaded to free temp storage with 48-hour validity
-
-## Showcase: One-Sentence Cinematic Video
+## Showcase 1: A Cinematic Short Film from One Sentence
 
 <p align="center">
   <a href="https://cloud.video.taobao.com/vod/dS2F4huqbw5Nfe5L3wwb3grz2q2DNYD3retq8dU-iHo.mp4">
@@ -55,132 +45,114 @@ Equip your AI Agent out-of-the-box with these capabilities, composable across co
 A complete **2-minute, 16:9 cinematic short film** — produced end-to-end from a single natural-language sentence, with **zero manual editing**. This showcase demonstrates how an AI Agent can compose a multi-step creative pipeline by orchestrating three primitives:
 
 - **[Qwen Code](https://github.com/QwenLM/qwen-code)** — the agentic coding model that interprets the user's intent and drives the workflow
-- **[Aliyun Model Studio CLI](https://bailian.console.aliyun.com/cli?source_channel=cli_github&)** — invokes **HappyHorse 1.1**, Aliyun Model Studio's text-/image-/reference-to-video generation model
+- **[Aliyun Model Studio CLI](https://github.com/modelstudioai/cli/)** — invokes **HappyHorse 1.1**, Aliyun Model Studio's text-/image-/reference-to-video generation model
 - **[spark-video Skill](https://github.com/JohnKeating1997/spark-video)** — handles scene decomposition, storyboarding, shot continuity, and final stitching
 
 ### The single prompt
 
 > _"Generate a roughly 2-minute video in Japanese cinematic style — a sweet, innocent first-love story about a high-school girl. The plot should be heart-fluttering enough to make viewers want to fall in love. Aspect ratio: 16:9."_
->
-> _(Original: "帮我生成一段日系影视风格，高中女生的青涩初恋故事，剧情高甜，让人看了想谈恋爱，2分钟左右的视频，尺寸是16:9")_
 
-### How it works
+## Showcase 2: A Short-Film Director Managed Agent from One Sentence
 
-1. **Qwen Code** parses the request, plans the narrative beats, and decides which tools to call.
-2. The **spark-video Skill** breaks the story into shots, writes per-shot prompts, and enforces visual continuity (characters, lighting, palette, lens language).
-3. **`bl video generate`** dispatches each shot to **HappyHorse 1.1** in parallel.
-4. The skill stitches all clips back together into a single 16:9 / ~2-min deliverable.
+<p align="center">
+  <a href="https://cloud.video.taobao.com/vod/2v0GYLbJSQb2saj4iopTJDW3iRIHsintYlK-wTKbhqE.mp4">
+    <img src="https://img.alicdn.com/imgextra/i4/6000000001674/O1CN01xhzixhxltbH3LxWu_!!6000000001674-0-tbvideo.jpg" alt="Click to play the demo video" width="720" />
+  </a>
+</p>
 
-No timeline scrubbing. No frame-by-frame editing. Just one sentence → one video.
+<p align="center"><i>👆 Click the cover to play the full demo</i></p>
+
+One sentence builds a reusable cloud-side short-film director for storyboarding, storyboard image generation, and video creation:
+
+- **[Qwen Code](https://github.com/QwenLM/qwen-code)** — understands the requirement and generates the agent configuration
+- **[Aliyun Model Studio CLI](https://github.com/modelstudioai/cli/)** — validates the configuration, previews the changes, and completes the deployment
+- **[Managed Agent](https://bailian.console.aliyun.com/cn-beijing/?tab=managed-agents#/managed-agents/quick-start)** — runs the director role along with its skills and tools in the cloud
+
+### The single prompt
+
+> _"Build me a Managed Agent app that can produce short films — a director expert that generates videos and can also design the matching storyboards."_
 
 ## Installation
 
-```bash
-npm install -g bailian-cli
-npx skills add modelstudioai/cli --all -g
+**Agent install (recommended)**
+
+Send the following to your Agent — it will detect your environment, then install and verify the CLI for you:
+
+```text
+Please read https://bailian.aliyun.com/cli/install.md and install the Aliyun Model Studio CLI for me
 ```
 
-> Requires Node.js >= 22.12.
+**Install with NPM**
+
+```bash
+npm install -g bailian-cli
+bl skill init
+```
+
+> Requires Node.js >= 18.17.
+
+**Install on macOS/Linux**
+
+```bash
+curl -fsSL https://bailian.aliyun.com/cli/install.sh | bash
+```
+
+> No Node.js required. The installer automatically installs Bailian Skills.
+
+**Install on Windows**
+
+```powershell
+irm https://bailian.aliyun.com/cli/install.ps1 | iex
+```
+
+> No Node.js required. The installer automatically installs Bailian Skills.
 
 ## Quick Start
 
-```bash
-# Authenticate, recommended
-bl auth login --console
+Once installed, just describe your task to your AI Agent — no need to assemble commands by hand.
 
-# Or authenticate with an API key
-bl auth login --api-key sk-xxxxx
-
-# Chat with Qwen
-bl text chat --message "What is DashScope?"
-
-# Multimodal chat (text + image + audio + video)
-bl omni --message "Describe this image" --image ./photo.jpg
-
-# Generate an image
-bl image generate --prompt "A cat in a spacesuit" --out-dir ./images/
-
-# Generate a video from local image
-bl video generate --image ./cat.png --prompt "Make the cat move" --download cat.mp4
-
-# Model recommendation — find the best model for your use case
-bl advisor recommend --message "I need a visual-understanding chatbot"
-
-# Compare specific models
-bl advisor recommend --message "qwen-max vs deepseek-v3 for code generation"
-
-# Browser login (required for console capability commands)
-bl auth login --console
-
-# Fine-tune & deploy — a one-shot train-to-serve workflow
-bl dataset upload --file ./train.jsonl                 # Upload a .jsonl dataset (validated first)
-bl finetune text create --model qwen3-8b --datasets ./train.jsonl --training-type sft-lora  # Local paths auto-upload
-bl finetune watch --job-id ft-xxx --output json       # Non-blocking probe (running/succeeded return 0; failed/canceled report an error)
-bl finetune capability --model qwen3-8b               # Which training types a model supports
-bl deploy text create --model qwen3-8b --name my-svc --plan mu  # Deploy the trained model as an endpoint
-
-# Browse models / apps / free-tier quota / usage statistics / workspaces
-bl model list                                        # Browse model families and pricing
-bl app list
-bl usage summary                                     # Unified view: free-tier quota + recent usage overview
-bl usage free                                         # Free-tier quota across models (add --model/--expiring/--sort)
-bl usage stats --workspace-id <id>                    # Model usage statistics (add --model for per-model)
-bl workspace list                                     # List all workspaces
-
-# Rate limit management (list / check / request / history)
-bl quota list                                         # View RPM/TPM limits (add --model to filter)
-bl quota check                                        # Current usage vs rate limits (add --model/--period)
-bl quota request --model qwen3.6-plus --tpm 6000000   # Request a temporary TPM increase
-bl quota history                                      # View quota-change history
-
-# Token Plan team management (requires AK/SK, see auth below)
-bl token-plan list-seats                                # View subscription seat details
-bl token-plan add-member --account-name dev --org-id org_xxx
-bl token-plan assign-seats --workspace-id ws_xxx --seat-type standard --account-id acc_xxx
-bl token-plan create-key --account-id acc_xxx --workspace-id ws_xxx
-```
+| Scenario                 | What to say to your Agent                                                         |
+| ------------------------ | --------------------------------------------------------------------------------- |
+| Managed Agent            | "Create a Managed Agent that can generate short-film storyboards and videos."     |
+| Image & video generation | "Generate an image of a cat in a spacesuit on Mars, then turn it into a video."   |
+| Usage & quota            | "Show my recent model usage, free-tier quota, and rate limits."                   |
+| Model selection          | "Recommend a model for image understanding and customer support."                 |
+| About Bailian CLI        | "Tell me what Bailian CLI can do for me, and suggest how to use it for my needs." |
 
 > More examples and scenarios: [Aliyun Model Studio CLI Site](https://bailian.console.aliyun.com/cli?source_channel=cli_github&)
 
 ## Authentication
 
-### DashScope API Key
+### API Key
 
 Required for most commands. Get your key from the [DashScope Console](https://bailian.console.aliyun.com/cn-beijing/?source_channel=key_github&tab=app#/api-key).
 
 ```bash
-# Option 1: Environment variable
-export DASHSCOPE_API_KEY=sk-xxxxx
-
-# Option 2: Login command (persisted to ~/.bailian/config.json)
 bl auth login --api-key sk-xxxxx
+```
 
-# Option 3: Per-command flag
-bl text chat --api-key sk-xxxxx --message "Hello"
+Get or copy your Token Plan API key from the [Token Plan subscription overview](https://bailian.console.aliyun.com/cn-beijing?tab=plan#/efm/subscription/overview).
+
+```bash
+bl auth login --config token-plan --api-key sk-sp-xxxxx
 ```
 
 ### Console Login (OAuth)
 
-Required for console capability commands (`model list`, `app list`, `usage summary/free/stats`, `workspace list`, `quota list/request/check/history`). Opens the Bailian console in your browser to sign in.
+Required for console capability commands (model list, app list, MCP list, workspace, usage queries, rate-limit increases, direct console calls). Opens the Bailian console in your browser to sign in.
 
 ```bash
 bl auth login --console
 ```
 
-### Alibaba Cloud OpenAPI AK/SK (Token Plan only)
+### Alibaba Cloud OpenAPI AK/SK
 
-Required for the `token-plan` command group. Get your AccessKey from [RAM Console](https://ram.console.aliyun.com/manage/ak).
+Token Plan seat and member management requires an Alibaba Cloud AccessKey. Get yours from the [RAM Console](https://ram.console.aliyun.com/manage/ak).
 
 > Recommended: create a RAM sub-account with minimum privileges instead of using the root account's AK/SK.
 
 ```bash
-# Option 1: Login command (persisted to ~/.bailian/config.json)
 bl auth login --open-api --access-key-id LTAI5t... --access-key-secret ...
-
-# Option 2: Environment variables
-export ALIBABA_CLOUD_ACCESS_KEY_ID=LTAI5t...
-export ALIBABA_CLOUD_ACCESS_KEY_SECRET=...
-export BAILIAN_WORKSPACE_ID=ws-...
 ```
 
 ## Configuration
@@ -189,17 +161,34 @@ export BAILIAN_WORKSPACE_ID=ws-...
 # View current config
 bl config show
 
-# Set defaults
-bl config set --key base_url --value https://dashscope-us.aliyuncs.com
-bl config set --key default_text_model --value qwen-turbo
-bl config set --key timeout --value 600
+# List all config profiles
+bl config list
 
-# Self-update to latest version
-bl update
+# Switch config profile
+bl config use --name token-plan
+
+# Switch the CLI interface to Chinese
+bl config set --key language --value zh-CN
 ```
 
 Config file location: `~/.bailian/config.json`
 
+## Update
+
+```bash
+bl update
+```
+
+Upgrades the CLI to the latest version and refreshes the installed Agent Skills. Release notes for every version live in [CHANGELOG.md](https://github.com/modelstudioai/cli/blob/main/CHANGELOG.md).
+
+## Contributing
+
+Bug reports, feature requests, and PRs are welcome. See [CONTRIBUTING.md](https://github.com/modelstudioai/cli/blob/main/CONTRIBUTING.md) for developer setup, repo layout, and the workflow for adding or changing commands.
+
+Scan the QR code to join the Aliyun Model Studio CLI DingTalk user group for usage help, troubleshooting, bug reports, and tips from other users.
+
+<img src="https://img.alicdn.com/imgextra/i3/O1CN015uuhYGb6j0L12xJZ_!!6000000006304-2-tps-516-485.png" alt="Aliyun Model Studio CLI DingTalk user group" width="240" />
+
 ## Links
 
 | Resource                     | URL                                                                                       |
@@ -209,12 +198,5 @@ Config file location: `~/.bailian/config.json`
 | Qwen Model List              | https://help.aliyun.com/zh/model-studio/getting-started/models                            |
 | Aliyun Model Studio Console  | https://bailian.console.aliyun.com/?source_channel=cli_github                             |
 | Get API Key                  | https://bailian.console.aliyun.com/cn-beijing/?source_channel=key_github&tab=app#/api-key |
+| Get Token Plan API Key       | https://bailian.console.aliyun.com/cn-beijing?tab=plan#/efm/subscription/overview         |
 | Get AccessKey                | https://ram.console.aliyun.com/manage/ak                                                  |
-
-## Changelog
-
-Release notes for every version live in [CHANGELOG.md](https://github.com/modelstudioai/cli/blob/main/CHANGELOG.md).
-
-## Contributing
-
-Bug reports, feature requests, and PRs are welcome. See [CONTRIBUTING.md](https://github.com/modelstudioai/cli/blob/main/CONTRIBUTING.md) for developer setup, repo layout, and the workflow for adding or changing commands.

packages/cli/README.zh.md

@@ -5,7 +5,7 @@
 **阿里云百炼 (DashScope) AI 平台命令行工具**
 
 [![npm version](https://img.shields.io/npm/v/bailian-cli?color=0969da&label=npm)](https://www.npmjs.com/package/bailian-cli)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D22.12-brightgreen)](https://nodejs.org)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.17-brightgreen)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)](https://www.typescriptlang.org)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
 
@@ -22,27 +22,16 @@ _专为 AI Agent 打造，每个命令均可作为结构化工具调用。_
 
 ## 功能特性
 
-让您的 AI Agent 开箱即具备以下能力，并可在复杂任务中自动组合调用：
+- **模型生成** — 文本、图像、视频、语音全模态生成，支持编辑与参考生成
+- **素材理解** — 图像、文档、音频、长视频的解析与问答
+- **应用编排** — 调用百炼已发布的 Managed Agent、智能体和工作流，接入知识库、记忆库、联网搜索与 MCP 工具
+- **模型训推** — 数据集校验上传、模型精调、专属模型部署上线
+- **账号运维** — 授权登录、界面化配置、模型市场、用量与额度、限流提额、团队席位管理
+- **套餐接入** — 支持 Token Plan 等订阅计划一键接到 CLI 和常见 Coding Agent
 
-- **文本对话** — Qwen3.7-max：Agentic coding、前端编程、Vibe coding 等能力显著增强
-- **全模态对话** — 文本 + 图像 + 音频 + 视频全模态支持
-- **图像生成与编辑** — Qwen-Image 2.0：专业文字渲染、真实质感、强语义遵循、多图合成
-- **视频生成与编辑** — happyhorse-1.1 系列，支持文生 / 图生 / 参考生（最多 9 张图参考）/ 自然语言视频编辑
-- **语音合成与识别** — CosyVoice 实时流式合成，5-20s 样本即可克隆；FunAudio-ASR 覆盖 30 种语种，含汉语七大方言与 20+ 口音官话
-- **图像与视频理解** — Qwen-VL：长视频解析、复杂图表与文档识别、视觉推理、多语种 OCR
+> **注意：** 应用编排、模型训推、账号运维和套餐接入目前仅支持中国站（aliyun.com）账号，暂不支持国际站 / 全球站账号。
 
-> **注意：** 以下功能目前仅对中国站（aliyun.com）账号开放，国际站 / 全球站账号暂不支持。
-
-- **知识库与记忆库** — 多模态 RAG 检索 + 跨会话记忆，提供个性化连贯对话体验
-- **应用调用** — 调用已发布在阿里云百炼平台上的智能体与工作流应用
-- **MCP 集成** — 统一调度百炼 MCP 服务：列出服务、查看工具、直接在终端调用任意工具
-- **联网搜索** — 实时互联网信息检索，提升回答准确性及时效性
-- **模型推荐** — 描述你的场景，智能推荐最适合的模型；支持限定范围搜索、模型对比和替代发现
-- **微调与部署** — 上传数据集、创建文本/音频/图像调优任务（`finetune text|audio|image create`；文本涵盖 SFT/LoRA/DPO/CPT）、非阻塞探测任务状态（`finetune watch`）、按模型查训练能力（`finetune capability`），并把训练好的模型部署为推理服务（`deploy text|audio|image create`）
-- **控制台能力** — 浏览模型市场（`model list`）和百炼应用（`app list`），查看统一用量视图（`usage summary`），查询模型免费额度（`usage free`），查看模型用量统计（`usage stats`），管理业务空间（`workspace list`），管理限流与提额（`quota list/request/check/history`）
-- **本地文件自动上传** — 所有 URL 参数同时支持本地路径，免费临时存储 48 小时
-
-## 示例:一句话生成一部电影短片
+## 示例 1：一句话生成一部电影短片
 
 <p align="center">
   <a href="https://cloud.video.taobao.com/vod/dS2F4huqbw5Nfe5L3wwb3grz2q2DNYD3retq8dU-iHo.mp4">
@@ -52,133 +41,117 @@ _专为 AI Agent 打造，每个命令均可作为结构化工具调用。_
 
 <p align="center"><i>👆 点击封面播放完整 2 分钟演示</i></p>
 
-一部完整的 **2 分钟、16:9 电影感短片** —— 由一句自然语言端到端生成,**全程零手动剪辑**。这个示例展示了 AI Agent 如何把三个基础能力编排成一条多步创作流水线:
+一部完整的 **2 分钟、16:9 电影感短片** —— 由一句自然语言端到端生成，**全程零手动剪辑**。这个示例展示了 AI Agent 如何把三个基础能力编排成一条多步创作流水线：
 
-- **[Qwen Code](https://github.com/QwenLM/qwen-code)** —— Agentic coding 模型,解析用户意图、驱动整个工作流
-- **[阿里云百炼 CLI](https://github.com/modelstudioai/cli/)** —— 调用 **HappyHorse 1.1**,百炼的文生/图生/参考生视频模型
+- **[Qwen Code](https://github.com/QwenLM/qwen-code)** —— Agentic coding 模型，解析用户意图、驱动整个工作流
+- **[阿里云百炼 CLI](https://github.com/modelstudioai/cli/)** —— 调用 **HappyHorse 1.1**，百炼的文生/图生/参考生视频模型
 - **[spark-video Skill](https://github.com/JohnKeating1997/spark-video)** —— 负责场景拆分、分镜设计、镜头连贯性和最终拼接
 
 ### 唯一的提示词
 
-> _"帮我生成一段日系影视风格,高中女生的青涩初恋故事,剧情高甜,让人看了想谈恋爱,2 分钟左右的视频,尺寸是 16:9"_
+> _“帮我生成一段日系影视风格，高中女生的青涩初恋故事，剧情高甜，让人看了想谈恋爱，2 分钟左右的视频，尺寸是 16:9。”_
 
-### 工作流程
+## 示例 2：一句话构建短片导演 Managed Agent
 
-1. **Qwen Code** 解析需求、规划叙事节奏,决定要调用哪些工具。
-2. **spark-video Skill** 把故事拆成镜头、为每个镜头写提示词,并保证视觉连贯性(角色、光线、色调、镜头语言)。
-3. **`bl video generate`** 把每个镜头并行下发给 **HappyHorse 1.1**。
-4. Skill 把所有片段拼成最终的 16:9 / 约 2 分钟成片。
+<p align="center">
+  <a href="https://cloud.video.taobao.com/vod/2v0GYLbJSQb2saj4iopTJDW3iRIHsintYlK-wTKbhqE.mp4">
+    <img src="https://img.alicdn.com/imgextra/i4/6000000001674/O1CN01xhzixhxltbH3LxWu_!!6000000001674-0-tbvideo.jpg" alt="点击播放演示视频" width="720" />
+  </a>
+</p>
 
-没有时间线拖拽,没有逐帧剪辑。一句话 → 一部短片。
+<p align="center"><i>👆 点击封面播放完整演示</i></p>
+
+一句话构建一个可复用的云端短片导演，用于分镜设计、分镜图生成和视频创作：
+
+- **[Qwen Code](https://github.com/QwenLM/qwen-code)** —— 理解需求并生成 Agent 配置
+- **[阿里云百炼 CLI](https://github.com/modelstudioai/cli/)** —— 校验配置、预览变更并完成部署
+- **[Managed Agent](https://bailian.console.aliyun.com/cn-beijing/?tab=managed-agents#/managed-agents/quick-start)** —— 在云端运行导演角色及其 Skill 和工具
+
+### 唯一的提示词
+
+> _“帮我构建一个 managedagent 应用，能够实现短片拍摄，导演专家生成视频，然后也能进行设计对应的分镜图。”_
 
 ## 安装
 
-```bash
-npm install -g bailian-cli
-npx skills add modelstudioai/cli --all -g
+**Agent 安装（推荐）**
+
+把下面这句话发给你的 Agent，它会自行判断环境并完成安装与校验：
+
+```text
+请阅读：https://bailian.aliyun.com/cli/install.md 并按照说明为我安装阿里云百炼 CLI
 ```
 
-> 需要预先安装 Node.js >= 22.12。
+**NPM 安装**
+
+```bash
+npm install -g bailian-cli
+bl skill init
+```
+
+> 需要预先安装 Node.js >= 18.17。
+
+**macOS/Linux 安装**
+
+```bash
+curl -fsSL https://bailian.aliyun.com/cli/install.sh | bash
+```
+
+> 无需预先安装 Node.js，安装脚本会自动安装 Bailian Skills。
+
+**Windows 安装**
+
+```powershell
+irm https://bailian.aliyun.com/cli/install.ps1 | iex
+```
+
+> 无需预先安装 Node.js，安装脚本会自动安装 Bailian Skills。
 
 ## 快速开始
 
-```bash
-# 认证（推荐浏览器登录）
-bl auth login --console
+安装完成后，直接在 AI Agent 中描述你的任务，无需手动拼接命令。
 
-# 或使用 API key 认证
-bl auth login --api-key sk-xxxxx
-
-# 和通义千问对话
-bl text chat --message "你好，介绍一下阿里云百炼平台"
-
-# 多模态对话（文本 + 图片 + 音频 + 视频）
-bl omni --message "描述这张图片" --image ./photo.jpg
-
-# 生成图片
-bl image generate --prompt "一只穿太空服的猫在火星上" --out-dir ./images/
-
-# 图生视频（本地文件自动上传）
-bl video generate --image ./cat.png --prompt "让画面中的猫动起来" --download cat.mp4
-
-# 模型推荐 — 根据场景推荐最适合的模型
-bl advisor recommend --message "我要做一个能理解图片的客服机器人"
-
-# 对比特定模型
-bl advisor recommend --message "qwen-max 和 deepseek-v3 哪个更适合做代码生成"
-
-# 浏览器登录（控制台能力相关命令需要）
-bl auth login --console
-
-# 微调与部署 — 从训练到服务的一站式流程
-bl dataset upload --file ./train.jsonl                 # 上传 .jsonl 数据集（先校验）
-bl finetune text create --model qwen3-8b --datasets ./train.jsonl --training-type sft-lora  # 本地路径自动上传
-bl finetune watch --job-id ft-xxx --output json       # 非阻塞探测（运行中/成功返回 0；失败/取消报错）
-bl finetune capability --model qwen3-8b               # 查询模型支持哪些训练方式
-bl deploy text create --model qwen3-8b --name my-svc --plan mu  # 把训练好的模型部署为推理服务
-
-# 浏览模型 / 应用 / 免费额度 / 用量统计 / 业务空间
-bl model list                                        # 浏览模型系列与价格信息
-bl app list
-bl usage summary                                     # 统一视图：免费额度 + 近期用量概览
-bl usage free                                         # 各模型免费额度（可加 --model/--expiring/--sort）
-bl usage stats --workspace-id <id>                    # 模型用量统计（加 --model 查单模型）
-bl workspace list                                     # 列出所有业务空间
-
-# 限流管理与提额（list / check / request / history）
-bl quota list                                         # 查看 RPM/TPM 限额（加 --model 过滤）
-bl quota check                                        # 当前用量 vs 限流阈值（加 --model/--period）
-bl quota request --model qwen3.6-plus --tpm 6000000   # 申请临时 TPM 提额
-bl quota history                                      # 查看提额历史记录
-
-# Token Plan 团队版管理（需 AK/SK，见下方认证说明）
-bl token-plan list-seats                                # 查看订阅席位明细
-bl token-plan add-member --account-name dev --org-id org_xxx
-bl token-plan assign-seats --workspace-id ws_xxx --seat-type standard --account-id acc_xxx
-bl token-plan create-key --account-id acc_xxx --workspace-id ws_xxx
-```
+| 场景             | 可以这样对 Agent 说                                                     |
+| ---------------- | ----------------------------------------------------------------------- |
+| Managed Agent    | “帮我创建一个能够生成短片分镜和视频的 Managed Agent。”                  |
+| 图片和视频生成   | “生成一张穿着太空服的猫站在火星上的图片，再把它制作成一段视频。”        |
+| 用量与额度       | “查看最近的模型用量、免费额度和限流情况。”                              |
+| 模型选型         | “推荐一个适合图片理解和智能客服的模型。”                                |
+| 了解 Bailian CLI | “介绍一下 Bailian CLI 能帮我完成哪些任务，并根据我的需求推荐使用方式。” |
 
 > 更多案例与使用场景：[阿里云百炼 CLI 官方主页](https://bailian.console.aliyun.com/cli?source_channel=cli_github&)
 
 ## 认证方式
 
-### DashScope API Key
+### API Key
 
 大部分命令均需要 API Key。前往 [DashScope 控制台](https://bailian.console.aliyun.com/cn-beijing/?source_channel=key_github&tab=app#/api-key) 获取。
 
 ```bash
-# 方式一：环境变量
-export DASHSCOPE_API_KEY=sk-xxxxx
-
-# 方式二：登录命令（持久化到 ~/.bailian/config.json）
 bl auth login --api-key sk-xxxxx
+```
 
-# 方式三：命令行参数
-bl text chat --api-key sk-xxxxx --message "你好"
+Token Plan 的 API Key 前往 [Token Plan 订阅详情](https://bailian.console.aliyun.com/cn-beijing?tab=plan#/efm/subscription/overview) 获取或复制。
+
+```bash
+bl auth login --config token-plan --api-key sk-sp-xxxxx
 ```
 
 ### 控制台登录（OAuth）
 
-控制台能力命令（`model list`、`app list`、`usage summary/free/stats`、`workspace list`、`quota list/request/check/history`）需要使用此登录方式。打开浏览器跳转百炼控制台完成登录。
+控制台能力命令（模型列表、应用列表、MCP 列表、工作空间、用量查询、限流提额、控制台直调）需要使用此登录方式。打开浏览器跳转百炼控制台完成登录。
 
 ```bash
 bl auth login --console
 ```
 
-### 阿里云 OpenAPI AK/SK（仅 Token Plan）
+### 阿里云 OpenAPI AK/SK
 
-`token-plan` 命令组需要阿里云 AccessKey。前往 [RAM 控制台](https://ram.console.aliyun.com/manage/ak) 获取。
+Token Plan 的席位与成员管理需要阿里云 AccessKey。前往 [RAM 控制台](https://ram.console.aliyun.com/manage/ak) 获取。
 
 > 建议：创建 RAM 子账号并授予最小权限，避免使用主账号 AK/SK。
 
 ```bash
-# 方式一：登录命令（持久化到 ~/.bailian/config.json）
 bl auth login --open-api --access-key-id LTAI5t... --access-key-secret ...
-
-# 方式二：环境变量
-export ALIBABA_CLOUD_ACCESS_KEY_ID=LTAI5t...
-export ALIBABA_CLOUD_ACCESS_KEY_SECRET=...
-export BAILIAN_WORKSPACE_ID=ws-...
 ```
 
 ## 配置
@@ -187,17 +160,34 @@ export BAILIAN_WORKSPACE_ID=ws-...
 # 查看当前配置
 bl config show
 
-# 设置默认值
-bl config set --key base_url --value https://dashscope-us.aliyuncs.com
-bl config set --key default_text_model --value qwen-turbo
-bl config set --key timeout --value 600
+# 查看全部配置档
+bl config list
 
-# 自更新到最新版本
-bl update
+# 切换配置档
+bl config use --name token-plan
+
+# 将 CLI 界面切换为中文
+bl config set --key language --value zh-CN
 ```
 
 配置文件位置：`~/.bailian/config.json`
 
+## 更新
+
+```bash
+bl update
+```
+
+升级 CLI 至最新版本，并同步更新已安装的 Agent Skills。每个版本的变更详情记录在 [CHANGELOG.zh.md](https://github.com/modelstudioai/cli/blob/main/CHANGELOG.zh.md)。
+
+## 参与贡献
+
+欢迎提 Issue、Feature Request 和 PR。开发环境搭建、仓库结构、新增/修改命令的工作流请见 [CONTRIBUTING.zh.md](https://github.com/modelstudioai/cli/blob/main/CONTRIBUTING.zh.md)。
+
+欢迎扫码加入阿里云百炼 CLI 钉钉用户交流群，获取使用答疑、问题排查、Bug 反馈和使用经验交流支持。
+
+<img src="https://img.alicdn.com/imgextra/i3/O1CN015uuhYGb6j0L12xJZ_!!6000000006304-2-tps-516-485.png" alt="阿里云百炼 CLI 钉钉用户交流群" width="240" />
+
 ## 相关链接
 
 | 资源                    | 地址                                                                                      |
@@ -207,12 +197,5 @@ bl update
 | 通义千问模型列表        | https://help.aliyun.com/zh/model-studio/getting-started/models                            |
 | 阿里云百炼控制台        | https://bailian.console.aliyun.com/?source_channel=cli_github                             |
 | 获取 API Key            | https://bailian.console.aliyun.com/cn-beijing/?source_channel=key_github&tab=app#/api-key |
+| 获取 Token Plan API Key | https://bailian.console.aliyun.com/cn-beijing?tab=plan#/efm/subscription/overview         |
 | 获取 AccessKey          | https://ram.console.aliyun.com/manage/ak                                                  |
-
-## 更新日志
-
-每个版本的变更详情记录在 [CHANGELOG.zh.md](https://github.com/modelstudioai/cli/blob/main/CHANGELOG.zh.md)。
-
-## 参与贡献
-
-欢迎提 Issue、Feature Request 和 PR。开发环境搭建、仓库结构、新增/修改命令的工作流请见 [CONTRIBUTING.zh.md](https://github.com/modelstudioai/cli/blob/main/CONTRIBUTING.zh.md)。

packages/cli/doc-commands.md

@@ -0,0 +1,160 @@
+# 迭代一设计 · doc 组命令
+
+> 命令：`doc upload` / `doc list` / `doc status` / `doc delete` / `doc tag` / `doc import-oss`
+> 公共约定见 [README.md](README.md)。
+
+## doc upload — 上传本地文件入库（编排命令）
+
+**说明**：本迭代最复杂命令。把"本地文件 → 数据中心 →（可选）导入知识库"封装为一条命令，替代构建期最高频的控制台操作（S2.2 痛点:高）。对标竞品 add-file。
+
+**编排四步**：
+
+| 步                                 | API                                                | 输入                                                                          | 输出                                   |
+| ---------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------- |
+| 1 申请租约                         | `POST /api/v1/connector/dash/applyFileUploadLease` | `category`(类目ID) + `fileName` + `sizeBytes`(字符串!) + `contentMd5`(Base64) | `leaseId` + `param.url/method/headers` |
+| 2 OSS 上传                         | `PUT {param.url}`                                  | 文件二进制 + `param.headers`（含 `x-bailian-extra`、`Content-Type`）          | HTTP 200                               |
+| 3 注册文件                         | `POST /api/v1/connector/dash/addFile`              | `leaseId` + `category` + `parser: "AUTO_SELECT"` + `tags?`                    | `fileId`                               |
+| 4 导入（可选，传 `--index-id` 时） | `POST /api/v1/indices/rag/index/job/create`        | `indexId` + `dataSource: { sourceType: "DATA_CENTER_FILE", fileIds }`         | `ingestionId`                          |
+
+坑位（实现注释必须标注）：
+
+- `sizeBytes` 必须字符串；`contentMd5` = `crypto.createHash("md5").update(buf).digest("base64")`
+- 租约/注册的类目参数名是 `category`，不是 `categoryId`
+- 第 4 步 body 是嵌套 `dataSource: { sourceType, fileIds }`（实测；公开文档的平铺 `documentIds` 会报 `Index.InvalidParameter`）
+- **第 4 步必须显式传 `sourceType`，不传会导入整个数据中心（API 文档明示的默认行为）**
+- 步骤 2 走 OSS 域名不走 DashScope 网关，用原生 fetch 而非 ctx.client（无 Bearer 头）；失败归类 NETWORK
+
+**Flags**：
+
+| flag                                               | 类型   | 必填 | 说明                                                                                                                  |
+| -------------------------------------------------- | ------ | ---- | --------------------------------------------------------------------------------------------------------------------- |
+| `--file <path>`                                    | array  | 是   | 本地文件路径，可重复；扩展名与大小按产品支持范围预校验（见下方格式白名单）                                            |
+| `--index-id <id>`                                  | string | 否   | 注册后立即导入该知识库（触发第 4 步，多文件合并为一个 job）                                                           |
+| `--category-id <id>`                               | string | 否   | 目标类目；缺省自动解析默认类目（listCategory 取 `isDefault: true`），解析失败报 GENERAL + hint 显式传 `--category-id` |
+| `--tag <text>`                                     | array  | 否   | addFile tags，可重复                                                                                                  |
+| `--wait` / `--poll-interval <s>` / `--timeout <s>` | —      | 否   | 与 `--index-id` 联用，轮询 job status 至终态                                                                          |
+
+**validate**：`--wait` 无 `--index-id` → USAGE；文件不存在/不可读 → GENERAL + errno hint（沿用错误边界规范）。
+
+**格式白名单与大小预校验**（依据 data/documents.md「支持的格式」，读文件前拦截，避免白传 OSS）：
+
+| 类型   | 扩展名                     | 硬限（超限 USAGE）                                    |
+| ------ | -------------------------- | ----------------------------------------------------- |
+| 文档   | .doc .docx .ppt .pptx .pdf | 150 MB                                                |
+| 表格   | .xls .xlsx                 | 10 MB（产品为“建议值”，超限降级为 stderr 警告不拦截） |
+| 图片   | .png .jpg .jpeg .bmp .gif  | 20 MB（尺寸约束不做客户端校验，留服务端）             |
+| 纯文本 | .md .txt .html             | 10 MB（同表格，警告不拦截）                           |
+
+- 扩展名不在白名单 → USAGE，错误信息列出支持格式；白名单常量独立导出便于后续随产品更新
+- 开放问题：create-kb.md 提及 .csv 但 documents.md 格式表未列——文档口径不一致，实现前向产品确认；确认前 .csv 暂入白名单（服务端拒绝会透传）
+
+**输出**：
+
+- text：每文件一行 `<fileName>  <fileId>  registered`；有导入时追加 `job: <ingestionId>`；--wait 结束追加终态
+- json：`{ files: [{path, fileId}], index_id?, ingestion_id?, final_status? }`（编排命令无单一响应可透传，输出自定义稳定结构）
+- quiet：仅 fileId 每行一个
+
+**实现方案**：
+
+- 文件 `doc-upload.ts`；多文件串行执行 1-3 步（首版不并发，避免 OSS 限流复杂化），全部注册成功后合并执行第 4 步
+- 部分失败语义：任一文件步骤 1-3 失败即中止并报错，已成功的 fileId 列入错误 hint（幂等重传代价低）
+- 默认类目解析结果进程内缓存（多文件只查一次）
+- dry-run：不读文件内容（size/md5 以占位符表示），输出四步编排计划 `{ steps: [{step, endpoint, request}] }`
+
+**测试方案**：
+
+- help / 缺 `--file` exitCode 2 / `--wait` 无 `--index-id` exitCode 2
+- 文件不存在 → 非零退出 + ENOENT hint；`.zip` 扩展名 → USAGE 列出支持格式
+- dry-run：断言 steps 长度（带/不带 --index-id 为 4/3）、lease 请求 `sizeBytes` 为字符串类型、job 请求含 `sourceType: "DATA_CENTER_FILE"`
+- live：上传 1KB 临时 md 文件 → 断言 fileId 前缀 `file_` → afterAll doc delete + 数据中心 deleteFile 清理
+
+## doc list — 查询知识库文档列表
+
+**说明**：列出库内文档及解析/索引状态，含 FAILED 发现（S2.3 / S5.2）。
+
+**API**：`GET /api/v1/indices/rag/index/files`，query string：`index_id` + `page_num`（注意本接口是 page_num）+ `page_size`（默认 10，最大 100）。
+
+**Flags**：`--index-id` 必填；`--page-number` / `--page-size`。
+
+**输出**：
+
+- text：每行 `doc_id  status  doc_name  doc_type  size`；status=FAILED 行红色高亮（TTY）；尾行 `total: N`
+- json 透传；quiet 仅 doc_id
+
+**实现/测试**：单 API 直映射（`doc-list.ts`）；dry-run 断言 query 参数名为 `page_num`；live 断言 rows 结构与 doc_id 前缀。
+
+## doc status — 查询导入任务状态
+
+**说明**：查导入任务进度，`--wait` 阻塞至终态供脚本串行（S2.3 痛点:高，L3 验收：FAILED 时非零 exit code）。
+
+**API**：`GET /api/v1/indices/rag/index_job/status`，query string：`index_id` + `job_id`（**双必填，仅传其一服务端返回 SystemError，客户端前置双校验拦截**）+ 分页参数。
+
+**Flags**：
+
+| flag                                                                 | 必填 | 说明                                                                                    |
+| -------------------------------------------------------------------- | ---- | --------------------------------------------------------------------------------------- |
+| `--index-id <id>`                                                    | 是   | 知识库 ID                                                                               |
+| `--job-id <id>`                                                      | 是   | 导入任务 ID（kb create / doc upload 返回的 ingestionId；也见 doc list 的 ingestion_id） |
+| `--page-number` / `--page-size`                                      | 否   | 任务含大量文档时分页                                                                    |
+| `--wait` / `--poll-interval <s>`(默认 5) / `--timeout <s>`(默认 600) | 否   | 轮询至终态                                                                              |
+
+**行为**：
+
+- 终态 FINISH → exit 0；FAILED → `BailianError(GENERAL)` 透传服务端 message（含文档级失败明细摘要），exit 1
+- `--wait` 超时 → TIMEOUT(5)
+- 已知行为：库无进行中任务时接口可能返回 SystemError——hint 引导 "check ingestion_id via doc list"
+
+**输出**：text 顶部任务总状态 + 文档级状态列表（FAILED 高亮）；json 透传。
+
+**测试方案**：help / 缺任一必填（两条用例）/ dry-run 断言 query 含两个 id / live：配合 upload 用例拿真实 job 轮询到 FINISH；`--wait --timeout 1` 对慢任务断言 exitCode 5（若不稳定则仅静态覆盖超时路径，live 标记 skip 原因）。
+
+## doc delete — 删除文档【危险操作】
+
+**说明**：从知识库删除文档及其全部切片（S5.1 内容更新循环）。
+
+**API**：`POST /api/v1/indices/rag/index/delete_file`，body `{ index_id, doc_ids }`（snake_case）。响应 `data.deleted[]` 为实际删除列表。
+
+**Flags**：`--index-id` 必填；`--doc-id` array 必填（可重复）；`--yes`。
+
+**实现方案**：`doc-delete.ts`；命令在 `risk` 对象中同时声明 `level: "high"` 和双语 `message`，由 runtime 在 `run()` 前统一确认；输出以 `data.deleted` 为准（与入参数量不一致时 text 模式警告差异）。
+
+**测试方案**：help / 缺参×2 / dry-run 断言 `doc_ids` 数组 / 无 `--yes` 返回 exitCode 7 + `requires_confirmation` / live 配合 upload 清理链。
+
+## doc tag — 批量更新文档标签
+
+**说明**：批量打标，支撑标签过滤检索（S2.4）。
+
+**API**：`POST /api/v1/connector/dash/batchUpdateFileTag`。`fileInfos`（1-20 项，每项 `fileId` + `tags`，单标签 ≤32 字符、单文件 ≤100 个、总长 ≤700）+ `updateMode`（OVERWRITE/APPEND）。
+
+**Flags**：
+
+| flag            | 必填 | 说明                                                                      |
+| --------------- | ---- | ------------------------------------------------------------------------- |
+| `--doc-id <id>` | 是   | 可重复，1-20 个（客户端预校验），映射 fileInfos[].fileId                  |
+| `--tag <text>`  | 是   | 可重复，应用到所有 `--doc-id`（首版同一组标签批量打；异构标签用多次调用） |
+| `--mode <m>`    | 否   | choices: `overwrite`/`append`，默认 `append`（追加比覆盖安全，作为缺省）  |
+
+**实现/测试**：`doc-tag.ts` 单 API 直映射；客户端预校验标签长度约束（USAGE 前置拦截）；dry-run 断言 `updateMode: "APPEND"` 大写映射与 fileInfos 结构；live 打标后 listFile/describeFile 验证回读。
+
+## doc import-oss — 从授权 OSS 批量导入
+
+**说明**：从已 SLR 授权的 OSS Bucket 批量导入数据中心（大客户批量场景）。
+
+**API**：`POST /api/v1/connector/dash/addFilesFromAuthorizedOss`。必填 `categoryId/categoryType/ossBucket/ossRegionId/fileDetails`（1-10 项，每项 `fileName+ossKey`）。返回 `data.fileIds`。
+
+**Flags**：
+
+| flag                 | 必填 | 说明                                         |
+| -------------------- | ---- | -------------------------------------------- |
+| `--bucket <name>`    | 是   | 映射 ossBucket                               |
+| `--region <id>`      | 是   | 映射 ossRegionId（如 cn-beijing）            |
+| `--oss-key <key>`    | 是   | 可重复，1-10 个；fileName 取 key 的 basename |
+| `--category-id <id>` | 否   | 缺省走默认类目解析（复用 upload 的解析函数） |
+| `--tag <text>`       | 否   | 可重复，≤10                                  |
+| `--overwrite`        | 否   | switch，映射 overWriteFileByOssKey           |
+
+固定值：`categoryType: "UNSTRUCTURED"`；`parser` 不暴露（默认 AUTO_SELECT，审慎原则——DASH_QWEN_VL_PARSER 等需配 parserConfig，使用方式未验证）。
+
+**错误边界**：SLR 未授权的服务端权限错误原样透传，hint 附 RAM 控制台确认 `AliyunServiceRoleForBailian` 的指引（该指引来自 API 文档 Note，属可权威解释范围）。
+
+**实现/测试**：`doc-import-oss.ts` 单 API 直映射；dry-run 断言 fileDetails 结构与 fileName 派生逻辑；live 依赖 OSS 授权环境，gating 追加 `BAILIAN_E2E_OSS_BUCKET` 环境变量，无则 skip。

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bailian-cli",
-  "version": "1.9.0",
+  "version": "1.22.0",
   "description": "CLI for Aliyun Model Studio (DashScope) AI Platform.",
   "keywords": [
     "agent",
@@ -25,7 +25,8 @@
   },
   "files": [
     "dist",
-    "README.zh.md"
+    "README.zh.md",
+    "postinstall.js"
   ],
   "type": "module",
   "exports": {
@@ -40,17 +41,19 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "generate:reference": "tsx ../../tools/generate-reference.ts && sh -c 'cd ../.. && vp check --fix skills/bailian-cli/reference'",
+    "generate:reference": "tsx ../../tools/generate-reference.ts && sh -c 'cd ../.. && vp check --fix skills/bailian-cli/reference skills/bailian-gen/reference skills/bailian-finetune/reference skills/bailian-managed-agent/reference'",
     "sync:skill-version": "tsx ../../tools/sync-skill-metadata.ts",
     "build": "vp pack",
     "dev": "tsx src/main.ts",
     "test": "vp test",
-    "check": "vp check"
+    "check": "vp check",
+    "postinstall": "node postinstall.js"
   },
   "dependencies": {
     "bailian-cli-commands": "workspace:*",
     "bailian-cli-core": "workspace:*",
-    "bailian-cli-runtime": "workspace:*"
+    "bailian-cli-runtime": "workspace:*",
+    "tar-stream": "catalog:"
   },
   "devDependencies": {
     "@clack/prompts": "^0.7.0",
@@ -66,6 +69,6 @@
     "yaml": "catalog:"
   },
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=18.17.0"
   }
 }