Merge pull request #128 from modelstudioai/feat/config-agent-fix

feat(config-agent): align agent writers, add --key/--region, prepare 1.12.0

.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
 

.vite-hooks/pre-commit

@@ -1,7 +1,7 @@
 #!/usr/bin/env sh
 set -eu
 
-# Regenerate skill reference + SKILL metadata (needs bailian-cli-core dist).
+# Regenerate skill reference + SKILL metadata from source (no package build).
 pnpm run sync:skill-assets
 
 # Stage generator output so it is included in this commit.

AGENTS.md

@@ -7,7 +7,7 @@
 monorepo 现在按"纯逻辑 → 运行时框架 → 命令库 → 产品入口"分层:
 
 - `packages/core` — `bailian-cli-core`,纯逻辑层:鉴权、配置、HTTP client、错误、类型、文件工具
-- `packages/runtime` — `bailian-cli-runtime`,通用 CLI 运行时:`createCli`、参数解析、registry/help、middleware、error handler、输出、pipeline
+- `packages/runtime` — `bailian-cli-runtime`,通用 CLI 运行时:`createCli`、参数解析、registry/help、middleware、error handler、输出、pipeline、Command Pack host
 - `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` 路径
@@ -17,14 +17,16 @@ monorepo 现在按"纯逻辑 → 运行时框架 → 命令库 → 产品入口"
 ```
 packages/cli/src/main.ts          # bl 入口,注入 binName/version/clientName/npmPackage
 packages/cli/src/commands.ts      # bl 产品命令 map,tools/generate-reference.ts 也读它
+packages/cli/src/command-pack-policy.ts # bl 的 Command Pack policy
 packages/kscli/src/main.ts        # kscli 入口和命令 map
 
 packages/commands/src/index.ts    # re-export 单个命令实现
 packages/commands/src/commands/   # defineCommand({ auth, flags, usageArgs, exampleArgs, run })
 
-packages/runtime/src/create-cli.ts # createCli(commands, identity)
+packages/runtime/src/create-cli.ts # createCli(commands, options)
 packages/runtime/src/registry.ts   # 命令树解析 + 动态 help
 packages/runtime/src/middleware.ts # auth / telemetry / update / run command
+packages/runtime/src/command-packs/ # 通用 Command Pack 加载、校验、隔离安装目录和管理命令
 packages/runtime/src/urls.ts       # 用户面控制台 URL
 
 packages/core/src/types/command.ts # Command / flags / auth 类型
@@ -54,20 +56,23 @@ Skill / 命令手册随 `skills/bailian-cli/` 经 `npx skills add modelstudioai/
 
 按当前任务从下表挑一条进入对应文档:
 
-| 场景           | 何时进入                                     | 详见                                                                     |
-| -------------- | -------------------------------------------- | ------------------------------------------------------------------------ |
-| 命令增删改     | 增加 / 删除 / 重命名 `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)                   |
-| 发布           | 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)           |
+| 场景           | 何时进入                                     | 详见                                                                         |
+| -------------- | -------------------------------------------- | ---------------------------------------------------------------------------- |
+| 命令增删改     | 增加 / 删除 / 重命名 `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) |
+| 安装文档       | 改安装、鉴权、验证流程或线上 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)                   |
 
 如果当前任务无法对应任何场景,先按经验完成,然后**回来评估这是不是一类新场景** —— 是就新增 `docs/agents/<scenario>.md`,把清单沉淀下来。
 
@@ -104,6 +109,17 @@ CLI 只为「自己能权威解释的错误」发出语义化信号,服务端的
 
 如果命令调用 Console Gateway,`defineCommand` 必须设置 `auth: "console"`。runtime 会基于 `CONSOLE_AUTH_FLAGS` 自动在 help 中展示 `--console-region`、`--console-site`、`--console-switch-agent`、`--workspace-id`,并由 `authStage` 解析/注入 console credential。命令不要重复声明这些凭证域 flag,也不要手动从 env/config 解析 token。
 
+### 5. 禁止单字母变量命名
+
+所有变量、参数、回调形参必须使用有语义的命名,不允许单字母(如 `i`、`m`、`p`、`t`、`e`、`s`)。具体表现:
+
+- 回调参数: `.map((m) => ...)` → `.map((model) => ...)`, `.find((t) => ...)` → `.find((template) => ...)`
+- catch 变量: `catch (e)` → `catch (error)`
+- for-of 循环: `for (const i of items)` → `for (const item of items)`
+- 临时变量: `const s = ...` → `const strategy = ...`
+
+例外: 仅当作用域极小(≤3 行)且语义从上下文完全明确时,可使用 `k`/`v`(Object.entries 的 key/value)。
+
 ## 完成改动后的快速验证
 
 ```sh

CHANGELOG.md

@@ -6,6 +6,153 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 [中文版](CHANGELOG.zh.md) · [README](README.md) · [Contributing](CONTRIBUTING.md)
 
+## [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
+
+- **Token Plan support** — log in and call supported models directly without manually configuring the endpoint.
+- **Named Config Profiles** — create, switch, and manage isolated configurations; logging in to a named Profile activates it automatically.
+- **Console Access Token automation** — generate and automatically refresh Console Access Tokens.
+- **`bl workspace init`** — initialize a Bailian workspace and activate the required services in one workflow.
+
+### Fixed
+
+- Improved configuration safety and consistency, including secret masking and preservation of custom configuration fields.
+
+## [1.8.3] - 2026-07-16
+
+### Fixed
+
+- Fixed `bl text chat --messages-file -` failing on Windows by treating standard input as a `/dev/stdin` file path; piped JSON messages are now read from standard input correctly. (#103)
+
+## [1.8.2] - 2026-07-15
+
+### Changed
+
+- `bl model list` now defaults to JSON output; pass `--output text` for the table view.
+
+### Fixed
+
+- `bl model list --enrich` now returns each model's input parameter schema (predictConfig); it was previously always empty because the console gateway response envelope was not unwrapped.
+
+## [1.8.1] - 2026-07-14
+
+### Changed
+
+- Expanded the Command Pack allowlist to accept an additional internal command extension.
+
+## [1.8.0] - 2026-07-13
+
+### Added
+
+- **`bl model list`** — browse the Bailian model marketplace: list model families or show full details for a single family (`--model`), with filters for provider, capability, feature, and context-window, pagination (`--page` / `--page-size`), pricing, and `--enrich` for richer metadata.
+- **`bl usage summary`** — a unified usage view combining free-tier quota and a recent usage overview; `--days` sets the overview window (default 7).
+- **Command Pack host support** — added support for allowlisted internal command extensions.
+- **Audio & image fine-tuning** — `bl finetune audio create` (CosyVoice TTS) and `bl finetune image create` (Wan image generation) join the existing text flow. `bl finetune image create` supports `--generation-type t2i|i2i` to select text-to-image or image-to-image training.
+- **Audio & image deployment** — `bl deploy audio create` and `bl deploy image create` deploy fine-tuned TTS and image models as endpoints.
+- **Multimodal dataset validation** — `bl dataset upload` and `bl dataset validate` now accept `.zip` archives with `tts` and `image` schemas, validate referenced media files, and allow image archives up to 1 GB.
+
+### Changed
+
+- **Fine-tune and deploy commands are now split by modality (BREAKING)**: `bl finetune create` → `bl finetune text create`, and `bl deploy create` → `bl deploy text create`. Update any scripts that use the old paths.
+- **Deployment option renamed (BREAKING)**: `--template-id` → `--deploy-spec` on deployment creation commands.
+- **Fine-tune status exit behavior changed (BREAKING)**: `bl finetune watch` no longer reserves exit code 3 for running jobs. Running and succeeded jobs return 0; failed and canceled jobs use normal CLI errors.
+- `bl deploy audio create` now defaults to `--plan mu` (model-unit billing, per the CosyVoice deployment contract); text and image continue to default to `lora`.
+- `bl finetune audio create` now validates CosyVoice training data: audio files must be `.wav`, each `wav_fn` must start with `train/`, and exactly one training file is accepted.
+- `bl quota list` and `bl quota check` now report real RPM/TPM usage against limits, adding `RPM Left` / `TPM Left` columns with remaining-quota progress bars sourced from monitoring data.
+- `bl usage free` output now shares its rendering with `bl usage summary` for consistent free-tier tables.
+- `bl advisor recommend` no longer depends on a dedicated intent-detection model to analyze your request.
+
+### Removed
+
+- **Removed the `tongyi-intent-detect-v3` integration (BREAKING)** used by `bl advisor recommend`, along with the `intent_detect_base_url` config field and the `DASHSCOPE_INTENT_DETECT_BASE_URL` environment variable.
+
+### Fixed
+
+- Skill command-reference generation now reads product command maps directly from source and produces stable formatting during release checks.
+
 ## [1.7.0] - 2026-07-09
 
 ### Added

CHANGELOG.zh.md

@@ -6,6 +6,153 @@
 
 [English](CHANGELOG.md) · [README](README.zh.md) · [参与贡献](CONTRIBUTING.zh.md)
 
+## [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
+
+### 新增
+
+- **支持 Token Plan** —— 登录后即可直接调用支持的模型，无需手动配置接入地址。
+- **命名 Config Profile** —— 支持创建、切换和管理相互隔离的配置，登录后会自动激活当前 Profile。
+- **Console Access Token 自动化** —— 支持生成并自动刷新 Console Access Token。
+- **`bl workspace init`** —— 一站式完成百炼工作空间初始化和所需服务开通。
+
+### 修复
+
+- 提升配置安全性与一致性，包括密钥脱敏和自定义配置字段保留。
+
+## [1.8.3] - 2026-07-16
+
+### 修复
+
+- 修复 Windows 上 `bl text chat --messages-file -` 将标准输入当作 `/dev/stdin` 文件路径读取的问题；通过管道传入的 JSON 消息现在可以从标准输入正常读取。（#103）
+
+## [1.8.2] - 2026-07-15
+
+### 变更
+
+- `bl model list` 现在默认以 JSON 输出；需要表格视图请传 `--output text`。
+
+### 修复
+
+- `bl model list --enrich` 现在能正确返回每个模型的输入参数 schema（predictConfig）；此前因未解包控制台网关响应信封而始终为空。
+
+## [1.8.1] - 2026-07-14
+
+### 变更
+
+- 扩展 Command Pack 白名单，允许加载额外的内部命令扩展。
+
+## [1.8.0] - 2026-07-13
+
+### 新增
+
+- **`bl model list`** —— 浏览百炼模型市场：列出模型家族，或用 `--model` 查看单个家族的完整详情；支持按 provider、能力、特性、上下文窗口过滤，分页（`--page` / `--page-size`）、价格展示，以及 `--enrich` 获取更丰富的元数据。
+- **`bl usage summary`** —— 统一用量视图，一屏合并免费额度与近期用量概览；`--days` 设置概览时间窗口（默认 7 天）。
+- **Command Pack 宿主支持** —— 新增面向白名单内部命令扩展包的加载能力。
+- **音频与图像精调** —— 在原有文本流程之外新增 `bl finetune audio create`（CosyVoice 语音合成）与 `bl finetune image create`（万相图像生成）。`bl finetune image create` 支持 `--generation-type t2i|i2i` 显式选择文生图或图生图训练。
+- **音频与图像部署** —— `bl deploy audio create` 与 `bl deploy image create` 可将精调后的语音合成与图像模型部署为推理接入点。
+- **多模态数据集校验** —— `bl dataset upload` 与 `bl dataset validate` 现在支持使用 `tts`、`image` schema 的 `.zip` 压缩包，可校验包内引用的媒体文件，图像数据压缩包上限提升至 1 GB。
+
+### 变更
+
+- **精调与部署命令按模态拆分（BREAKING）**：`bl finetune create` → `bl finetune text create`，`bl deploy create` → `bl deploy text create`。请更新使用旧路径的脚本。
+- **部署参数重命名（BREAKING）**：部署创建命令的 `--template-id` 更名为 `--deploy-spec`。
+- **精调状态退出行为变更（BREAKING）**：`bl finetune watch` 不再使用退出码 3 表示任务运行中；运行中与成功均返回 0，失败与取消使用 CLI 的常规错误流程。
+- `bl deploy audio create` 默认使用 `--plan mu`（按模型单元计费，符合 CosyVoice 部署契约）；文本与图像仍默认 `lora`。
+- `bl finetune audio create` 现在会校验 CosyVoice 训练数据：音频必须为 `.wav`，每条 `wav_fn` 必须以 `train/` 开头，且只接受一个训练文件。
+- `bl quota list` 与 `bl quota check` 现在会基于监控数据展示真实的 RPM/TPM 用量与限额，新增 `RPM Left` / `TPM Left` 列及剩余额度进度条。
+- `bl usage free` 的输出现在与 `bl usage summary` 共用渲染逻辑，免费额度表格更一致。
+- `bl advisor recommend` 不再依赖独立的意图识别模型来分析你的需求。
+
+### 已移除
+
+- **移除 `bl advisor recommend` 使用的 `tongyi-intent-detect-v3` 集成（BREAKING）**，同时移除 `intent_detect_base_url` 配置字段与 `DASHSCOPE_INTENT_DETECT_BASE_URL` 环境变量。
+
+### 修复
+
+- Skill 命令参考文档生成现在直接读取产品命令源码，并在发布检查中保持稳定格式。
+
 ## [1.7.0] - 2026-07-09
 
 ### 新增

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
 

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
 
 ## 仓库结构

INSTALL.md

@@ -7,7 +7,7 @@
 **原则**：先执行检查；若 **Node / 包管理器 / 网络** 任一不满足下文要求，Agent 应 **在本机终端内主动完成安装或配置**（例如升级 Node、切换镜像、配置 `npm` 代理等），再继续 `bailian-cli` 安装。仅在无权限或环境无法自动化时，再向用户说明原因并请其配合。
 
 1. **Node.js**
-   - 要求 **≥ 22.12.0**，执行 `node -v` 确认。
+   - 要求 **≥ 18.17.0**，执行 `node -v` 确认。
    - 未安装或版本不足：由 Agent 自行安装或升级 Node。
 
 2. **npm**（**唯一**允许的包管理器）
@@ -69,7 +69,7 @@ npx skills add modelstudioai/cli --all -g
 
 > 此方式同时打通 `app list`、`usage free` 等控制台能力，并自动配置 API Key 调用所需的鉴权信息。
 
-### 备选：由 Agent 引导用户输入 API Key 后登录
+### 备选一：由 Agent 引导用户输入普通 API Key 后登录
 
 适用于无法拉起浏览器的对话式安装（远程 SSH、CI 调试、纯终端环境等）：
 
@@ -80,6 +80,15 @@ npx skills add modelstudioai/cli --all -g
 3. 用户提供了 Key 之后，在**用户本机终端**执行（Agent 用终端工具跑，勿把 Key 写进回复正文）：`bl auth login --api-key <用户提供的_Key>`
 4. 登录成功后执行 `bl auth status --output json` 确认；汇报时只使用 masked 字段，**禁止**回显完整 Key。
 
+### 备选二：使用 Token Plan API Key
+
+- 获取入口：[Token Plan 订阅详情](https://bailian.console.aliyun.com/cn-beijing?tab=plan#/efm/subscription/overview)
+
+1. 请用户从订阅详情页获取或复制 Token Plan API Key，勿要求用户发到公开渠道。
+2. 在用户本机终端执行：`bl auth login --config token-plan --api-key <用户提供的_Key>`。
+3. `token-plan` Profile 已内置默认 Base URL；登录命令会先测试 Key，通过后才保存并激活该 Profile，无需另行配置或重复测试。
+4. 执行 `bl auth status --config token-plan --output json` 确认；汇报时只使用 masked 字段。
+
 ### 其他方式
 
 - **环境变量**（不落盘到配置文件）：在 shell 中配置 API Key 环境变量；变量名见 `bl auth status --help`，勿在对话中向用户解释底层命名。
@@ -89,20 +98,19 @@ npx skills add modelstudioai/cli --all -g
 ### Agent 安全约束
 
 - **禁止**把真实 API Key 写入仓库、日志、Skill、聊天记录的可公开部分。
-- CI / 非交互环境：使用 `bl ... --non-interactive`；通过密钥管理或环境变量注入，勿在脚本中硬编码 Key。
+- CI / 非交互环境：显式传入必填参数并使用 `--output json` 获取机器可读结果；如需纯文本输出，设置 `NO_COLOR=1`。通过密钥管理或环境变量注入，勿在脚本中硬编码 Key。
 
 ---
 
-## 4. 最小功能验证
+## 4. 配置验证
 
-在鉴权配置完成后执行：
+API Key 登录命令本身已经完成可用性测试，通过后只需确认配置状态：
 
 ```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`。
+无需再执行重复的模型调用测试。若登录失败，根据 stderr / JSON 中的 `hint` 或 `message` 排查（网络、Key 无效、`base_url` 等）。DashScope 端点：使用 `--base-url` / `bl config set --key base_url` / `DASHSCOPE_BASE_URL`，默认中国大陆 `https://dashscope.aliyuncs.com`。
 
 ---
 
@@ -111,7 +119,7 @@ bl text chat --message "ping" --non-interactive --output json
 | 现象                    | 可能原因             | 建议动作                                                        |
 | ----------------------- | -------------------- | --------------------------------------------------------------- |
 | `bl: command not found` | 全局 bin 不在 PATH   | 检查 `npm prefix -g` 与 PATH                                    |
-| 安装报错 engines        | Node 版本过低        | 升级到 ≥ 22.12                                                  |
-| 401 / 鉴权失败          | 未 login 或 Key 无效 | 引导用户更新 Key 并 `bl auth login --api-key`                   |
+| 安装报错 engines        | Node 版本过低        | 升级到 ≥ 18.17                                                  |
+| 401 / 鉴权失败          | 未 login 或 Key 无效 | 按 Key 类型重新执行普通或 Token Plan 登录命令                   |
 | 企业网络无法访问 npm    | 代理 / 镜像          | 配置 registry 或代理后再装                                      |
 | 本机只有 pnpm、没有 npm | Agent 误用 pnpm 安装 | 先装/修好 **npm**，再用 `npm install -g bailian-cli`；勿用 pnpm |

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)
 
@@ -30,6 +30,7 @@ Equip your AI Agent out-of-the-box with these capabilities, composable across co
 - **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
+- **Coding agent setup** — Configure Claude Code, Qwen Code, OpenCode, OpenClaw, Hermes Agent, or Codex to use DashScope with `bl config agent`
 
 > **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.
 
@@ -38,8 +39,8 @@ Equip your AI Agent out-of-the-box with these capabilities, composable across co
 - **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 SFT/LoRA/DPO/CPT jobs (`finetune create`), probe job status non-blockingly (`finetune watch`), query per-model training capability (`finetune capability`), and deploy trained models as endpoints (`deploy create`)
-- **Console capabilities** — Browse Bailian apps (`app list`), 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`)
+- **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
@@ -80,7 +81,7 @@ npm install -g bailian-cli
 npx skills add modelstudioai/cli --all -g
 ```
 
-> Requires Node.js >= 22.12.
+> Requires Node.js >= 18.17.
 
 ## Quick Start
 
@@ -91,6 +92,12 @@ bl auth login --console
 # Or authenticate with an API key
 bl auth login --api-key sk-xxxxx
 
+# Or use Token Plan (Base URL built in; the key is tested during login)
+bl auth login --config token-plan --api-key sk-sp-xxxxx
+
+# Configure a coding agent to use DashScope
+bl config agent --agent codex --base-url https://dashscope.aliyuncs.com/compatible-mode/v1 --api-key sk-xxxxx --model qwen3-coder-plus
+
 # Chat with Qwen
 bl text chat --message "What is DashScope?"
 
@@ -114,13 +121,15 @@ 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 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 status probe (exit 0/1/3 = done/failed/running)
+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 create --model qwen3-8b --name my-svc --plan mu  # Deploy the trained model as an endpoint
+bl deploy text create --model qwen3-8b --name my-svc --plan mu  # Deploy the trained model as an endpoint
 
-# Browse apps / free-tier quota / usage statistics / workspaces
+# 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
@@ -157,9 +166,18 @@ bl auth login --api-key sk-xxxxx
 bl text chat --api-key sk-xxxxx --message "Hello"
 ```
 
+### Token Plan API Key
+
+Get or copy the API key from the [Token Plan subscription overview](https://bailian.console.aliyun.com/cn-beijing?tab=plan#/efm/subscription/overview).
+The CLI has the default Token Plan Base URL built in. Login tests the key first, then saves and activates the `token-plan` config only when validation succeeds.
+
+```bash
+bl auth login --config token-plan --api-key sk-sp-xxxxx
+```
+
 ### Console Login (OAuth)
 
-Required for console capability commands (`app list`, `usage free`, `usage 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`, `usage summary/free/stats`, `workspace list`, `quota list/request/check/history`). Opens the Bailian console in your browser to sign in.
 
 ```bash
 bl auth login --console
@@ -207,6 +225,7 @@ 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

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)
 
@@ -30,6 +30,7 @@ _专为 AI Agent 打造，每个命令均可作为结构化工具调用。_
 - **视频生成与编辑** — happyhorse-1.1 系列，支持文生 / 图生 / 参考生（最多 9 张图参考）/ 自然语言视频编辑
 - **语音合成与识别** — CosyVoice 实时流式合成，5-20s 样本即可克隆；FunAudio-ASR 覆盖 30 种语种，含汉语七大方言与 20+ 口音官话
 - **图像与视频理解** — Qwen-VL：长视频解析、复杂图表与文档识别、视觉推理、多语种 OCR
+- **Coding Agent 配置** — 使用 `bl config agent` 将 Claude Code、Qwen Code、OpenCode、OpenClaw、Hermes Agent 或 Codex 配置为使用 DashScope
 
 > **注意：** 以下功能目前仅对中国站（aliyun.com）账号开放，国际站 / 全球站账号暂不支持。
 
@@ -38,8 +39,8 @@ _专为 AI Agent 打造，每个命令均可作为结构化工具调用。_
 - **MCP 集成** — 统一调度百炼 MCP 服务：列出服务、查看工具、直接在终端调用任意工具
 - **联网搜索** — 实时互联网信息检索，提升回答准确性及时效性
 - **模型推荐** — 描述你的场景，智能推荐最适合的模型；支持限定范围搜索、模型对比和替代发现
-- **微调与部署** — 上传数据集、创建 SFT/LoRA/DPO/CPT 调优任务（`finetune create`）、非阻塞探测任务状态（`finetune watch`）、按模型查训练能力（`finetune capability`），并把训练好的模型部署为推理服务（`deploy create`）
-- **控制台能力** — 浏览百炼应用（`app list`），查询模型免费额度（`usage free`），查看模型用量统计（`usage stats`），管理业务空间（`workspace list`），管理限流与提额（`quota list/request/check/history`）
+- **微调与部署** — 上传数据集、创建文本/音频/图像调优任务（`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 小时
 
 ## 示例:一句话生成一部电影短片
@@ -78,7 +79,7 @@ npm install -g bailian-cli
 npx skills add modelstudioai/cli --all -g
 ```
 
-> 需要预先安装 Node.js >= 22.12。
+> 需要预先安装 Node.js >= 18.17。
 
 ## 快速开始
 
@@ -89,6 +90,12 @@ bl auth login --console
 # 或使用 API key 认证
 bl auth login --api-key sk-xxxxx
 
+# 或使用 Token Plan（已内置 Base URL，登录时自动测试 Key）
+bl auth login --config token-plan --api-key sk-sp-xxxxx
+
+# 配置 Coding Agent 使用 DashScope
+bl config agent --agent codex --base-url https://dashscope.aliyuncs.com/compatible-mode/v1 --api-key sk-xxxxx --model qwen3-coder-plus
+
 # 和通义千问对话
 bl text chat --message "你好，介绍一下阿里云百炼平台"
 
@@ -112,13 +119,15 @@ bl auth login --console
 
 # 微调与部署 — 从训练到服务的一站式流程
 bl dataset upload --file ./train.jsonl                 # 上传 .jsonl 数据集（先校验）
-bl finetune create --model qwen3-8b --datasets ./train.jsonl --training-type sft-lora  # 本地路径自动上传
-bl finetune watch --job-id ft-xxx --output json       # 非阻塞状态探测（退出码 0/1/3 = 成功/失败/进行中）
+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 create --model qwen3-8b --name my-svc --plan mu  # 把训练好的模型部署为推理服务
+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                                     # 列出所有业务空间
@@ -155,9 +164,18 @@ 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) 获取或复制 API Key。
+CLI 已内置 Token Plan 的默认 Base URL；登录命令会先测试 Key，通过后才保存并激活 `token-plan` 配置。
+
+```bash
+bl auth login --config token-plan --api-key sk-sp-xxxxx
+```
+
 ### 控制台登录（OAuth）
 
-控制台能力命令（`app list`、`usage free`、`usage stats`、`workspace list`、`quota list/request/check/history`）需要使用此登录方式。打开浏览器跳转百炼控制台完成登录。
+控制台能力命令（`model list`、`app list`、`usage summary/free/stats`、`workspace list`、`quota list/request/check/history`）需要使用此登录方式。打开浏览器跳转百炼控制台完成登录。
 
 ```bash
 bl auth login --console
@@ -205,6 +223,7 @@ 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                                                  |
 
 ## 更新日志

docs/agents/auth-change.md

@@ -37,18 +37,38 @@ defineCommand({ auth }) → runtime/authStage → ctx.client → command.run(ctx
 - `bl auth login --console` 只更新 `access_token` 以及回调携带的 console 作用域字段
 - `bl auth login --open-api ...` 只更新 `access_key_id` / `access_key_secret`
 - `bl auth logout --console` 只清 `access_token`
-- `bl auth logout --open-api` 只清 `access_key_id` / `access_key_secret`
-- `bl auth logout` 清 `api_key` + `access_token` + `access_key_*`
+- `bl auth logout --open-api` 只清 `access_key_id` / `access_key_secret` / `security_token`
+- `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`
+- `resolveModelBaseUrl()` — model base URL;优先级 `--base-url` > `DASHSCOPE_BASE_URL` > config `base_url` > `REGIONS.cn`，返回前统一归一化为 URL origin（仅保留协议、host 和显式端口，去除 path、query、fragment）
+- `--config` 只选择 config 文件 block，不提升该 block 的字段优先级；内置套餐 Profile（当前为 `token-plan`）的预设仅在登录时物化写入，运行时继续走统一的 flag > env > selected config file > 默认值
+- 显式 `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_*`,新写入只写短字段
 - `describeAuthState()` — `auth status` / banner / telemetry 使用的只读快照
 
-命令不要直接解析 token、env 或 config。业务请求统一走 `ctx.client`;登录/配置命令通过 `ctx.authStore()` / `ctx.configStore()` 的窄接口操作落盘。
+命令不要直接解析 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"` 硬门禁 —— 无论目标 provider 是谁，authStage 都经 `resolveApiKey(sources)` 解析 bailian 凭证(flag > env > active profile config)，缺失报统一 AUTH;引擎层 `assertProviderCredentials` 再对 agents.yaml 里**全部已声明 provider** 的空 key 拦截并给 provider 专属 hint。例外:`plan --no-refresh` / `plan --dry-run` 传 `credentials: "none"` 并强制 `refresh: false`（不联网、不回写 state，不查 provider key），其中 `--dry-run` 连登录也不要求（authStage 的 dry-run 豁免），`--no-refresh` 仍需登录。
+
+凭证不以真实值写入 `process.env`，而是经 `packages/commands/src/commands/managed-agent/_engine/` 的**内存注入管道**(`resolveAgentProjectConfig`)注入 SDK，管道五步:
+
+1. `prepareProviderEnv()` — 先 `bootstrapRuntimeCredentialsSync()`(SDK 把 `.env` / `~/.agents/config.json` 灌进 env，服务 claude/ark/qoder 等非 bailian provider)，再把全部凭证类 env(`CREDENTIAL_ENV_KEYS`，含别名)中仍为 undefined 的占位为 `""`，使 agents.yaml 插值不因缺变量抛错
+2. `resolveProjectConfig` — 插值发生:bailian 插值拿到占位空串，claude/ark 拿到真实 env 值;随后 `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. `assertProviderCredentials(providers)` — 任一已声明 provider 的 `api_key` 为空 → CLI 权威 `AUTH` 错误 + provider 专属 hint(取代 SDK 原始插值/zod 报错);离线命令传 `credentials: "none"` 整体跳过
+
+`bl auth login` 仅管理 bailian(DashScope)凭证;claude/ark/qoder 的 key 从 env(shell / `.env` / `~/.agents/config.json`)经插值进入 config 对象，同样被清扫。禁止命令层直接 `readConfigFile` 裸读凭证;bailian 字段以 CLI 鉴权链为唯一信源。
 
 ## 必查清单
 
@@ -87,7 +107,7 @@ defineCommand({ auth }) → runtime/authStage → ctx.client → command.run(ctx
 
 - [ ] `packages/commands/src/commands/auth/login.ts`:
   - 新增/调整登录 flag 与流程
-  - 持久化只走 `ctx.authStore().login(...)`
+  - 持久化只走 `ctx.authStore.login(...)`
 - [ ] `packages/commands/src/commands/auth/status.ts`:
   - 分别显示 model / console / openapi 鉴权状态,并 mask token
 - [ ] `packages/commands/src/commands/auth/logout.ts`:

docs/agents/cli-e2e-tests.md

@@ -1,31 +1,58 @@
 # CLI E2E 测试规范
 
+## 架构分层
+
+| 层级            | 路径                                                  | 测什么                                                                                   |
+| --------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| **共享基建**    | `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 拒绝                                                      |
+
+**依赖边界**：`e2e` → `core`；`commands/tests` → `e2e` + `commands/src`；产品 tests → `e2e` + 各自 `src`。**禁止**产品 import `commands/tests/**`（子进程 spawn harness 路径除外）。
+
 ## 触发条件
 
 - 新增/修改 `packages/commands/src/commands` 下的 command 实现
 - 新增/修改 `packages/cli/src/commands.ts` 的 `bl` 命令路径 map
-- 新建或扩展 `packages/cli/tests/e2e/*.e2e.test.ts` 用例
-- 为命令补 help / 缺参 / dry-run / 真实集成测试
+- 新建或扩展 `packages/commands/tests/e2e/<topic>.e2e.test.ts`
+- 新增 bl 产品 path → `registry.smoke` 自动覆盖 leaf path；commands topic 测试在 `topic-routes.ts` 补最小路由
 
-以上情况必须同步维护 `packages/cli/tests/e2e/<topic>.e2e.test.ts`。跑测与环境变量见 `.cursor/skills/bailian-cli-e2e/SKILL.md`。
+跑测与环境变量见 `.cursor/skills/bailian-cli-e2e/SKILL.md`。
+
+> **规则**：共享 command 行为在 `commands/tests/e2e`；产品 map、identity、CLI-only 命令留在对应产品 `tests/e2e`。
 
 ## 文件与工具
 
-- 路径：`packages/cli/tests/e2e/<kebab-topic>.e2e.test.ts`
-- 框架：`vite-plus/test`；子进程跑 CLI：`runCli` from `./helpers.ts`
+### 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 映射）
+- fixtures：`packages/commands/tests/e2e/fixtures/`
+- 路由常量：`topic-routes.ts`（按 topic 维护，**非**全量产品 map）
+
+### 产品 smoke
+
+- bl：`runCli` from `packages/cli/tests/e2e/helpers.ts`
+- kscli：`runKscli` from `packages/kscli/tests/e2e/helpers.ts`
+
+### 共享
+
+- gating / output / runner：`e2e/gating`、`e2e/output`、`e2e/runner`
+- globalSetup：根 `vite.config.ts` → `packages/e2e/src/global-setup.ts`
 - 解析 JSON stdout：`parseStdoutJson`；输出目录：`makeE2eOutputDir(e2eLabelFromMetaUrl(import.meta.url))`
 - 长任务：`cliTimeoutPrefix()`；视频用例加 `test(..., 3_600_000)` 等显式超时
 
 ## 双层 describe（固定结构）
 
 ```ts
-// 1) 不 skip：分组 + --help，无密钥、无真实 API
+// 1) 不 skip：--help，无密钥、无真实 API（分组 help 由 bl registry.smoke 覆盖）
 describe("e2e: <topic>", () => {
-  test("<group> 分组展示子命令帮助且成功退出", ...);
   test("<subcommand> --help 正常退出", ...);
 });
 
-// 2) skipIf：缺参 / dry-run / 真实集成；原有集成用例放最后、勿改逻辑
+// 2) skipIf：缺参 / dry-run / 真实集成
 describe.skipIf(<ready>)("e2e: <topic>（DashScope …）", () => {
   test("缺少 --<flag> 时退出为用法错误 (2)", ...);
   test("<cmd> --dry-run ...", ...); // 若适用
@@ -33,51 +60,69 @@ describe.skipIf(<ready>)("e2e: <topic>（DashScope …）", () => {
 });
 ```
 
-## skip 条件（helpers.ts）
+## skip 条件（`e2e/gating`，commands helpers re-export）
 
-| 场景                | 条件                                                  |
-| ------------------- | ----------------------------------------------------- |
-| 文本/搜索/记忆/配置 | `isDashScopeE2EReady()`                               |
-| 图像/语音           | `isBailianE2EMediaEnabled() && isDashScopeE2EReady()` |
-| 视频                | `isBailianE2EVideoEnabled() && isDashScopeE2EReady()` |
-| 知识库              | `isKnowledgeE2EReady()`                               |
-| 视频 download/task  | 另需 `BAILIAN_E2E_VIDEO_TASK_ID`                      |
+| 场景                    | 条件                                                                                                       |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------- |
+| 文本/搜索/记忆/配置     | `isDashScopeE2EReady()`                                                                                    |
+| 图像/语音               | `isBailianE2EMediaEnabled() && isDashScopeE2EReady()`                                                      |
+| 视频                    | `isBailianE2EVideoEnabled() && isDashScopeE2EReady()`                                                      |
+| OpenAPI AK/SK           | `isOpenApiE2EReady()`（`.env` 中必须同时提供完整 AK/SK）                                                   |
+| 视频 download/task      | 另需 `BAILIAN_E2E_VIDEO_TASK_ID`                                                                           |
+| 知识库 chat/search live | `isChatE2EReady()` / `isSearchE2EReady()`（`knowledge chat/search`，需 `BAILIAN_WORKSPACE_ID` + agent ID） |
 
 ## 用例类型
 
-1. **分组 help**：`runCli(["image"])` → `exitCode === 0`，stdout+stderr 含子命令名
-2. **--help**：`runCli([..., "--help"])` → stderr 含主要 flags
-3. **缺参**：带一个无害全局 flag（如 `--quiet`）且不传 required flag → `exitCode === 2`，stderr 匹配 `--flag|Missing required argument`
-4. **--dry-run**：仅当实现在联网/上传/写盘**之前**返回；断言 stdout JSON/文本，不入网
-5. **真实集成**：保留既有用例名称与断言；放在 skip 块**末尾**
+1. **--help**：`runCommandE2e(ROUTES, [..., "--help"])` → stderr 含主要 flags
+2. **缺参**：带无害全局 flag（如 `--quiet`）且不传 required flag → `exitCode === 2`
+3. **--dry-run**：实现在联网/上传/写盘**之前**返回；断言 stdout JSON/文本
+4. **真实集成**：放在 skip 块**末尾**
+
+## 增删命令同步
+
+- **commands export** + **topic 路由**（`topic-routes.ts` 或测试文件内 `ROUTES`）+ **产品 map**（`cli/commands.ts` / `kscli/commands.ts`）
+- 分组 help 由产品 `registry.smoke` 负责，无需在 commands 重复
 
 ## 安全与例外
 
-- **禁止真实破坏性操作**：`auth logout` 只用 `--dry-run`；`config set` 只用 `--dry-run`
+- **禁止破坏真实用户配置**：`auth logout` 默认只用 `--dry-run`；需要验证实际落盘时，必须通过
+  `BAILIAN_CONFIG_DIR` 指向隔离 fixture；`config set` 只用 `--dry-run`
 - **不加 dry-run**：`dryRun` 在 `resolveFileUrl` / `resolveCredential` / 上传**之后**的命令（如 `image edit`、`speech recognize` 带 `--url`）
 - **`--list-voices` 等旁路**：先于 `--text` 校验的 flag，缺参用例勿带该 flag
 - 新增 required option → 至少一条缺参用例；改 dry-run 输出 → 更新对应断言
 
 ## 新增 command 检查清单
 
-- [ ] `packages/commands/src/index.ts` 导出 + `packages/cli/src/commands.ts` 暴露路径 + `tests/e2e/<topic>.e2e.test.ts`（新建或扩展）
+- [ ] `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`（多子命令则各一条 help）
+- [ ] 子命令 `--help`（分组 help 由 bl `registry.smoke` 覆盖）
 - [ ] skip 块：每个 required flag 缺参；可 dry-run 则加一条
 - [ ] 至少一条真实集成（或说明为何仅 smoke）；不破坏已有集成用例顺序
-- [ ] `pnpm test packages/cli/tests/e2e/<file>` 通过
+- [ ] `vp test packages/commands/tests/e2e/<file>` 通过
+
+## 调试命令
+
+```sh
+pnpm --filter bailian-cli-commands exec vp test packages/commands/tests/e2e/text-chat.e2e.test.ts
+pnpm --filter bailian-cli exec vp test packages/cli/tests/e2e/registry.smoke.e2e.test.ts
+pnpm --filter knowledge-studio-cli exec vp test packages/kscli/tests/e2e/registry.smoke.e2e.test.ts
+pnpm --filter bailian-cli-runtime exec vp test packages/runtime/tests/proxy.e2e.test.ts
+```
 
 ## 示例片段
 
 ```ts
+import { FOO_ROUTES } from "./topic-routes.ts";
+
 test("foo bar 缺少 --prompt 时退出为用法错误 (2)", async () => {
-  const { stderr, exitCode } = await runCli(["foo", "bar", "--quiet"]);
+  const { stderr, exitCode } = await runCommandE2e(FOO_ROUTES, ["foo", "bar", "--quiet"]);
   expect(exitCode).toBe(2);
   expect(stderr).toMatch(/--prompt|Missing required argument/i);
 });
 
 test("foo bar --dry-run 仅输出计划", async () => {
-  const { stdout, stderr, exitCode } = await runCli([
+  const { stdout, stderr, exitCode } = await runCommandE2e(FOO_ROUTES, [
     "foo",
     "bar",
     "--dry-run",
@@ -97,4 +142,4 @@ test("foo bar --dry-run 仅输出计划", async () => {
 - **E2E**：单条/少量调用、断言固定、可进 `vp test`（见上文 skip 条件）
 - **批量压测**：`packages/cli/tests/stress/run.mjs` + `targets/*.mjs`，并发 + 报告，**仅手动** `pnpm run test:stress -- <target>`
 
-勿把压测并入 E2E 或默认 CI。详见 [stress-batch-tests.md](stress-batch-tests.md)。
+勿把压测并入 E2E 或默认 CI。详见 [stress-batch-tests.md](stress-batch-tests.md).

docs/agents/command-add-remove.md

@@ -72,7 +72,8 @@ packages/commands/src/index.ts
   - `exampleArgs`(不含 bin/path 前缀)
   - `validate`(跨 flag 校验)
   - 普通业务命令的 `run(ctx)` 只读 `ctx.flags` / `ctx.settings` / `ctx.client`
-  - `commands/auth/**` 可用 `ctx.authStore()`,`commands/config/**` 可用 `ctx.configStore()`;不要把这些 store accessor 扩散到普通业务命令
+  - `commands/auth/**` 可用 `ctx.authStore`,`commands/config/**` 可用 `ctx.configStore`;不要把这些持久化能力扩散到普通业务命令
+  - `commands/plugin/**` 可用 `ctx.commandPacks`;产品 policy 由 runtime 绑定,命令不要自行 import 产品入口
 - [ ] `packages/commands/src/index.ts`:新增或移除对应 export
 - [ ] 如果命令调用 Console Gateway,设置 `auth: "console"`;不要重复声明 console 凭证域 flags
 - [ ] 如果命令不需要网络或自己管理配置/登录,设置 `auth: "none"`;不要绕过 runtime auth stage
@@ -92,15 +93,17 @@ packages/commands/src/index.ts
 
 ### D. 测试层
 
-- [ ] 按 [cli-e2e-tests.md](cli-e2e-tests.md) 新建或更新 `packages/cli/tests/e2e/<topic>.e2e.test.ts`
-- [ ] 删除命令时一并删对应 e2e / README 示例 / reference 生成结果
-- [ ] 如果 shared command 在不同入口路径下复用,至少确保 `bl` 入口 e2e 覆盖;`kscli` 入口改动需补对应入口测试或手工 smoke
+- [ ] 按 [cli-e2e-tests.md](cli-e2e-tests.md) 新建或更新 `packages/commands/tests/e2e/<topic>.e2e.test.ts`
+- [ ] 同步 `packages/commands/tests/e2e/topic-routes.ts`（该 topic 的最小 path → export 映射）
+- [ ] bl 产品 path 变更由 `registry.smoke` 自动覆盖；kscli 变更同步 `kscli/src/commands.ts` 与 `registry.smoke`
+- [ ] 删除命令时一并删对应 commands e2e / README 示例 / reference / topic 路由条目
+- [ ] 如果 shared command 在不同入口路径下复用,至少确保 commands e2e 覆盖 `bl` path；`kscli` 入口改动需补对应 smoke 或说明不测 flat path live
 
 ### E. 重命名特殊处理
 
 - [ ] 全仓 grep **旧命令名字符串**,确保以下位置全部更新:
   - `packages/cli/src/commands.ts` map key
-  - `packages/kscli/src/main.ts` map key(如适用)
+  - `packages/kscli/src/commands.ts` map key(如适用)
   - 用户可见 hint / README / tests
   - `skills/bailian-cli/reference/`(重建后检查并提交)
 - [ ] 检查 `usageArgs` / `exampleArgs` 没有硬编码旧的 `bl <path>` 前缀
@@ -111,7 +114,7 @@ packages/commands/src/index.ts
 pnpm run sync:skill-assets
 pnpm -F bailian-cli exec tsx src/main.ts <new-command> --help
 pnpm -F bailian-cli exec tsx src/main.ts
-vp test packages/cli/tests/e2e/<topic>.e2e.test.ts
+vp test packages/commands/tests/e2e/<topic>.e2e.test.ts
 ```
 
 如改了 `kscli` 入口:

docs/agents/command-pack.md

@@ -0,0 +1,56 @@
+# Command Pack 维护
+
+## 触发条件
+
+- 新增或移除 Command Pack 包
+- 调整包白名单、允许的命令前缀或协议字段
+- 修改 `plugin install/link/list/remove`
+- 修改 Command Pack 加载、隔离、兼容性或独立安装目录
+
+## 分层边界
+
+- `packages/core/src/types/command-pack.ts`：稳定的协议元数据和导出类型，不知道具体产品或白名单。
+- `packages/runtime/src/command-packs/`：所有 CLI 共用的加载、校验、API 适配、产品隔离安装目录和 manager 实现。
+- `packages/runtime/src/create-cli.ts`：始终接收静态 command map，按 `CliOptions.commandPacks` 统一合并 pack，并把已绑定产品 identity/policy 的 manager 注入 `ctx.commandPacks`。
+- `packages/commands/src/commands/plugin/`：普通共享管理命令，只依赖 `ctx.commandPacks`，不 import 任何产品 policy。
+- `packages/cli/src/command-pack-policy.ts`：`bl` 支持的包、命令前缀和凭据授权。
+- `kscli` 当前不传 `commandPacks`，使用 runtime 的默认空 policy。
+- 当前只有 `bl` 从 `bailian-cli-commands` 导入并登记 `plugin *`；使用默认空 policy 的产品不提前暴露管理命令。
+
+不要把产品白名单写进 core/runtime，也不要通过扫描全局 `node_modules` 自动发现包。通用机制放 runtime，产品差异只由 policy 表达。
+
+## 安全与兼容性清单
+
+- [ ] 包名必须精确命中当前产品 policy 的 `supported`，命令路径必须位于该包允许的前缀。
+- [ ] 正式安装只接受包名加 version/tag；本地目录只走 `plugin link`。
+- [ ] npm 使用独立安装目录和 `--ignore-scripts`，不污染 CLI 自身依赖树。
+- [ ] npm 子进程只继承明确允许的 registry/config/cache/proxy/TLS 配置，不通配透传 pnpm 注入的 `npm_config_*`。
+- [ ] 安装目录按 `identity.npmPackage` 隔离，不能让一个产品安装/删除另一个产品的 pack。
+- [ ] 安装目录只隔离依赖位置，不隔离执行权限；Command Pack 必须视为 CLI 进程内的完全可信代码。
+- [ ] 入口 realpath 不能逃逸包根目录。
+- [ ] 加载前检查 `type`、`apiVersion`、`minCliVersion`；报告状态只使用 `loaded/failed`，具体原因写入 `error`。
+- [ ] Command Pack 不能覆盖内置命令、其他 pack 命令或重声明保留 flag。
+- [ ] 普通网络请求走 `ctx.client`；基础 Context 提供 `identity/settings/flags/client/output/errors`，不提供原始凭据。
+- [ ] `ctx.credentials.apiKey()` 仅限 policy 显式声明 `credentialAccess: ["apiKey"]`，且命令自身为 `auth: "apiKey"`。
+- [ ] 不向 Command Pack 暴露原始 Console Token、OpenAPI AK/SK、`authStore` 或 `configStore`。
+- [ ] 不向 Command Pack 暴露宿主的 `commandPacks` manager，避免 pack 安装或删除其他 pack。
+- [ ] 单包失败必须 fail-open：保留内置命令和其他合法 pack。
+- [ ] 破坏协议前优先在适配层兼容；确实无法兼容时才提升 `apiVersion`。
+
+## 测试与文档
+
+- [ ] `packages/runtime/tests/command-packs.test.ts` 覆盖产品 policy、安装目录隔离、协议版本、前缀和导出契约。
+- [ ] `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` 等正式对外发布时再补。
+
+验证：
+
+```sh
+vp test packages/runtime/tests/command-packs.test.ts
+vp test packages/cli/tests/e2e/command-packs.e2e.test.ts
+vp test packages/kscli/tests/e2e/command-packs.e2e.test.ts
+pnpm run sync:skill-assets
+vp check
+```

docs/agents/config-profile-change.md

@@ -0,0 +1,75 @@
+# Config Profile 与激活状态变更清单
+
+适用于新增 Profile 预设、修改命名 Profile 选择规则、调整 `active_config`，或新增/修改 `bl config list/use/show/ui` 等 Profile 管理能力。
+
+## 1. 保持存储边界
+
+- Profile 业务字段继续由 `ConfigFile` / `CONFIG_FILE_KEYS` 管理。
+- `active_config` 是 `config.json` 顶层元数据，不得进入命名 Profile block，也不得被 `config set` 当作普通字段写入。
+- 识别命名 Profile 时必须排除业务字段和顶层元数据。
+- 旧配置缺少 `active_config` 时继续等价于激活 `default`。
+
+## 2. 保持选择语义
+
+```text
+显式 --config <name> > active_config > default
+```
+
+- 解析阶段用局部变量保留“是否显式传入 `--config`”的信息；完成 Config 选择后不进入 `Settings`。
+- `--config default` 必须显式选择顶层配置并绕过命名激活项。
+- 普通命令的显式 `--config` 只覆盖本次选择，不修改持久化激活状态；例外是
+  `auth login --config ...`，凭证验证并落盘成功后自动激活该 Profile。
+- 激活状态只选择配置 block，不改变字段优先级；字段仍为 flag > env > selected config > 默认值。
+- Pipeline 等进程内调用链也要复用统一的 `buildSources()`，避免绕过激活状态。
+- Console access token 自动刷新等后台读写必须携带 `settings.configName`，不得直接读写顶层 default。
+
+## 3. 保持读写命令交互一致
+
+- `auth login`、`config set` 等写命令未传 `--config` 时修改当前激活项。
+- `auth login --config <name>` 显式指定不存在的 Profile 时，仅在凭证验证成功并实际落盘时
+  创建和激活；`config set --config <name>` 可创建但不自动激活。
+- `config show`、`auth status` 和业务消费等读命令不得因为显式指定不存在的名称而创建 Profile。
+- `auth logout` 默认只清理当前激活项；显式 `--config` 只清理指定项。
+- 按凭证域退出时必须清理该域的完整字段集合，例如 OpenAPI 同时清理 AK、SK 和 STS `security_token`。
+- 所有生产代码读取“当前配置”时优先经过 `buildSources()` 或携带解析后的 `configName`；直接调用无名称的 `readConfigFile()` / `writeConfigFile()` 只适用于明确操作顶层 default 的底层能力。
+
+## 4. 保持状态一致性
+
+- `config use` 只能激活已经存在的命名 Profile；`default` 始终有效。
+- 配置文件中的 `active_config` 指向不存在的 Profile 时返回 usage error，不静默回退。
+- 删除当前激活的命名 Profile 时，同一次落盘切回 `default`，不得留下悬空引用。
+- 配置写入继续使用临时文件 + rename，避免中断后留下半写文件。
+
+## 5. 命令与展示联动
+
+- 新增/重命名命令时同步 `packages/commands/src/index.ts` 和产品入口 `packages/cli/src/commands.ts`。
+- `config list` 标识所有 Profile 与当前激活项。
+- `config show`、`auth status` 只输出本次最终选择的 `config` 和 `config_file`，不重复携带激活状态。
+- `config ui` 从持久化元数据读取激活项，提供显式激活操作，并在删除激活项后刷新为 `default`。
+- `config ui` 保存时只替换 UI 管理的字段；Profile 中未展示但仍属于 `ConfigFile` 的合法字段必须保留，不能因打开并保存 UI 而丢失。
+- 同步 E2E topic routes、Skill setup 和自动生成 reference。
+
+## 6. 最小测试矩阵
+
+- 旧配置无 `active_config` -> `default`。
+- 激活命名 Profile 后，无 `--config` 的命令选择该 Profile。
+- 显式命名 `--config` 和 `--config default` 均覆盖激活项且不修改磁盘状态。
+- 激活不存在的 Profile 失败且不写盘。
+- 悬空 `active_config` 明确失败。
+- 删除激活 Profile 后切回 `default`。
+- 登录、退出、`config set` 分别覆盖“当前激活项”和“显式不存在名称成功后创建”。
+- 显式 `auth login --config <name>` 成功后激活该 Profile，失败或 dry-run 不创建、不切换；
+  `--config default` 成功后切回 `default`。
+- Console token 自动刷新不从其他 Profile 借用 AK/SK，也不把新 token 写入其他 Profile。
+- `config list/show/use/ui`、`auth status` 和依赖默认模型的消费命令覆盖对应 E2E。
+- `config ui` 覆盖保存时保留未管理字段，并继续允许空值清除 UI 管理字段。
+
+## 7. 完成检查
+
+```sh
+pnpm run sync:skill-assets
+vp check
+vp test
+```
+
+命令 E2E 会启动本地子进程，Config UI 测试还会监听 `127.0.0.1` 临时端口；受限沙箱内出现 `EPERM` 时，需要在允许本地进程和端口的环境中复跑。

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 设置一致
 
@@ -42,7 +42,7 @@
 
 - [ ] `.vite-hooks/pre-commit` 改动后,`pnpm install` 重新软链(走 `prepare: vp config`)
 - [ ] 增加 hook 时,确认在干净 clone 后能自动激活
-- [ ] pre-commit 会跑 `pnpm run sync:skill-assets`(先 build core,再 `generate:reference` + `sync:skill-version`)并 `git add` skill 资产,最后 `vp staged`
+- [ ] pre-commit 会跑 `pnpm run sync:skill-assets`(`generate:reference` 含格式化 + `sync:skill-version`,直接读源码、无需先 build)并 `git add` skill 资产,最后 `vp staged`
 
 ### F. CI / 发版工具
 

docs/agents/publish.md

@@ -29,8 +29,9 @@
 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 自动：自检 → 构建 → 发布到 latest → 打 git tag
-5. 对应脚本：`tools/release/publish-stable.mjs`
+4. CI 自动：自检 → 构建 → 检查 npm 已发布版本 → 发布到 latest → 打 git tag
+5. 如果所选发布集合的当前版本已全部存在于 npm，stable 发布会失败并提示先升级版本号；如果只有部分包已发布，CI 会继续补发缺失包
+6. 对应脚本：`tools/release/publish-stable.mjs`
 
 ## 自检（`tools/release/check.mjs`）
 
@@ -92,14 +93,15 @@ 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                                      |
+| 漏点                                                                | 后果                                                                               |
+| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| 只升部分包,漏升 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 明确报错并要求先升级版本号                  |

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

package.json

@@ -16,7 +16,7 @@
     "ready": "vp check && vp run -r test && vp run -r build",
     "prepare": "vp config",
     "check": "vp check",
-    "sync:skill-assets": "pnpm --filter \"bailian-cli^...\" run build && pnpm --filter bailian-cli run generate:reference && pnpm --filter bailian-cli run sync:skill-version",
+    "sync:skill-assets": "pnpm --filter bailian-cli run generate:reference && pnpm --filter bailian-cli run sync:skill-version",
     "dev": "pnpm -F bailian-cli-core dev",
     "bl": "pnpm -F bailian-cli dev",
     "kscli": "pnpm -F knowledge-studio-cli dev",

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)
 
@@ -30,6 +30,7 @@ Equip your AI Agent out-of-the-box with these capabilities, composable across co
 - **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
+- **Coding agent setup** — Configure Claude Code, Qwen Code, OpenCode, OpenClaw, Hermes Agent, or Codex to use DashScope with `bl config agent`
 
 > **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.
 
@@ -38,8 +39,8 @@ Equip your AI Agent out-of-the-box with these capabilities, composable across co
 - **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 SFT/LoRA/DPO/CPT jobs (`finetune create`), probe job status non-blockingly (`finetune watch`), query per-model training capability (`finetune capability`), and deploy trained models as endpoints (`deploy create`)
-- **Console capabilities** — Browse Bailian apps (`app list`), 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`)
+- **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
@@ -80,7 +81,7 @@ npm install -g bailian-cli
 npx skills add modelstudioai/cli --all -g
 ```
 
-> Requires Node.js >= 22.12.
+> Requires Node.js >= 18.17.
 
 ## Quick Start
 
@@ -91,6 +92,12 @@ bl auth login --console
 # Or authenticate with an API key
 bl auth login --api-key sk-xxxxx
 
+# Or use Token Plan (Base URL built in; the key is tested during login)
+bl auth login --config token-plan --api-key sk-sp-xxxxx
+
+# Configure a coding agent to use DashScope
+bl config agent --agent codex --base-url https://dashscope.aliyuncs.com/compatible-mode/v1 --api-key sk-xxxxx --model qwen3-coder-plus
+
 # Chat with Qwen
 bl text chat --message "What is DashScope?"
 
@@ -114,13 +121,15 @@ 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 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 status probe (exit 0/1/3 = done/failed/running)
+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 create --model qwen3-8b --name my-svc --plan mu  # Deploy the trained model as an endpoint
+bl deploy text create --model qwen3-8b --name my-svc --plan mu  # Deploy the trained model as an endpoint
 
-# Browse apps / free-tier quota / usage statistics / workspaces
+# 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
@@ -157,9 +166,18 @@ bl auth login --api-key sk-xxxxx
 bl text chat --api-key sk-xxxxx --message "Hello"
 ```
 
+### Token Plan API Key
+
+Get or copy the API key from the [Token Plan subscription overview](https://bailian.console.aliyun.com/cn-beijing?tab=plan#/efm/subscription/overview).
+The CLI has the default Token Plan Base URL built in. Login tests the key first, then saves and activates the `token-plan` config only when validation succeeds.
+
+```bash
+bl auth login --config token-plan --api-key sk-sp-xxxxx
+```
+
 ### Console Login (OAuth)
 
-Required for console capability commands (`app list`, `usage free`, `usage 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`, `usage summary/free/stats`, `workspace list`, `quota list/request/check/history`). Opens the Bailian console in your browser to sign in.
 
 ```bash
 bl auth login --console
@@ -207,6 +225,7 @@ 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

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)
 
@@ -30,6 +30,7 @@ _专为 AI Agent 打造，每个命令均可作为结构化工具调用。_
 - **视频生成与编辑** — happyhorse-1.1 系列，支持文生 / 图生 / 参考生（最多 9 张图参考）/ 自然语言视频编辑
 - **语音合成与识别** — CosyVoice 实时流式合成，5-20s 样本即可克隆；FunAudio-ASR 覆盖 30 种语种，含汉语七大方言与 20+ 口音官话
 - **图像与视频理解** — Qwen-VL：长视频解析、复杂图表与文档识别、视觉推理、多语种 OCR
+- **Coding Agent 配置** — 使用 `bl config agent` 将 Claude Code、Qwen Code、OpenCode、OpenClaw、Hermes Agent 或 Codex 配置为使用 DashScope
 
 > **注意：** 以下功能目前仅对中国站（aliyun.com）账号开放，国际站 / 全球站账号暂不支持。
 
@@ -38,8 +39,8 @@ _专为 AI Agent 打造，每个命令均可作为结构化工具调用。_
 - **MCP 集成** — 统一调度百炼 MCP 服务：列出服务、查看工具、直接在终端调用任意工具
 - **联网搜索** — 实时互联网信息检索，提升回答准确性及时效性
 - **模型推荐** — 描述你的场景，智能推荐最适合的模型；支持限定范围搜索、模型对比和替代发现
-- **微调与部署** — 上传数据集、创建 SFT/LoRA/DPO/CPT 调优任务（`finetune create`）、非阻塞探测任务状态（`finetune watch`）、按模型查训练能力（`finetune capability`），并把训练好的模型部署为推理服务（`deploy create`）
-- **控制台能力** — 浏览百炼应用（`app list`），查询模型免费额度（`usage free`），查看模型用量统计（`usage stats`），管理业务空间（`workspace list`），管理限流与提额（`quota list/request/check/history`）
+- **微调与部署** — 上传数据集、创建文本/音频/图像调优任务（`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 小时
 
 ## 示例:一句话生成一部电影短片
@@ -78,7 +79,7 @@ npm install -g bailian-cli
 npx skills add modelstudioai/cli --all -g
 ```
 
-> 需要预先安装 Node.js >= 22.12。
+> 需要预先安装 Node.js >= 18.17。
 
 ## 快速开始
 
@@ -89,6 +90,12 @@ bl auth login --console
 # 或使用 API key 认证
 bl auth login --api-key sk-xxxxx
 
+# 或使用 Token Plan（已内置 Base URL，登录时自动测试 Key）
+bl auth login --config token-plan --api-key sk-sp-xxxxx
+
+# 配置 Coding Agent 使用 DashScope
+bl config agent --agent codex --base-url https://dashscope.aliyuncs.com/compatible-mode/v1 --api-key sk-xxxxx --model qwen3-coder-plus
+
 # 和通义千问对话
 bl text chat --message "你好，介绍一下阿里云百炼平台"
 
@@ -112,13 +119,15 @@ bl auth login --console
 
 # 微调与部署 — 从训练到服务的一站式流程
 bl dataset upload --file ./train.jsonl                 # 上传 .jsonl 数据集（先校验）
-bl finetune create --model qwen3-8b --datasets ./train.jsonl --training-type sft-lora  # 本地路径自动上传
-bl finetune watch --job-id ft-xxx --output json       # 非阻塞状态探测（退出码 0/1/3 = 成功/失败/进行中）
+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 create --model qwen3-8b --name my-svc --plan mu  # 把训练好的模型部署为推理服务
+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                                     # 列出所有业务空间
@@ -155,9 +164,18 @@ 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) 获取或复制 API Key。
+CLI 已内置 Token Plan 的默认 Base URL；登录命令会先测试 Key，通过后才保存并激活 `token-plan` 配置。
+
+```bash
+bl auth login --config token-plan --api-key sk-sp-xxxxx
+```
+
 ### 控制台登录（OAuth）
 
-控制台能力命令（`app list`、`usage free`、`usage stats`、`workspace list`、`quota list/request/check/history`）需要使用此登录方式。打开浏览器跳转百炼控制台完成登录。
+控制台能力命令（`model list`、`app list`、`usage summary/free/stats`、`workspace list`、`quota list/request/check/history`）需要使用此登录方式。打开浏览器跳转百炼控制台完成登录。
 
 ```bash
 bl auth login --console
@@ -205,6 +223,7 @@ 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                                                  |
 
 ## 更新日志

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bailian-cli",
-  "version": "1.7.0",
+  "version": "1.12.0",
   "description": "CLI for Aliyun Model Studio (DashScope) AI Platform.",
   "keywords": [
     "agent",
@@ -59,12 +59,13 @@
     "ajv": "catalog:",
     "boxen": "catalog:",
     "chalk": "catalog:",
+    "e2e": "workspace:*",
     "typescript": "^6.0.2",
     "undici": "catalog:",
     "vite-plus": "0.1.22",
     "yaml": "catalog:"
   },
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=18.17.0"
   }
 }

packages/cli/src/command-pack-policy.ts

@@ -0,0 +1,14 @@
+import type { CommandPackPolicy } from "bailian-cli-runtime";
+
+/** Command Packs accepted by the bl product. */
+export const commandPackPolicy = {
+  supported: {
+    "@ali/bailian-plugin-agent": {
+      commandPrefixes: ["agent"],
+      credentialAccess: ["apiKey"],
+    },
+    "@ali/bailian-plugin-inner-console-call": {
+      commandPrefixes: ["inner-console"],
+    },
+  },
+} as const satisfies CommandPackPolicy;

packages/cli/src/commands.ts

@@ -3,6 +3,7 @@ import {
   authLogin,
   authStatus,
   authLogout,
+  authGenerateAccessToken,
   textChat,
   textOmni,
   imageGenerate,
@@ -15,6 +16,10 @@ import {
   visionDescribe,
   configShow,
   configSet,
+  configList,
+  configUse,
+  configUi,
+  configAgent,
   update,
   appCall,
   appList,
@@ -39,9 +44,11 @@ import {
   usageFree,
   usageFreetier,
   usageStats,
+  usageSummary,
   pipelineRun,
   pipelineValidate,
   advisorRecommend,
+  modelList,
   workspaceList,
   quotaList,
   quotaRequest,
@@ -52,7 +59,9 @@ import {
   datasetGet,
   datasetDelete,
   datasetValidate,
-  finetuneCreate,
+  finetuneTextCreate,
+  finetuneAudioCreate,
+  finetuneImageCreate,
   finetuneList,
   finetuneGet,
   finetuneCancel,
@@ -62,7 +71,9 @@ import {
   finetuneExport,
   finetuneWatch,
   finetuneCapability,
-  deployCreate,
+  deployTextCreate,
+  deployAudioCreate,
+  deployImageCreate,
   deployList,
   deployGet,
   deployModels,
@@ -73,6 +84,28 @@ import {
   tokenPlanCreateKey,
   tokenPlanAssignSeats,
   tokenPlanAddMember,
+  workspaceInit,
+  pluginInstall,
+  pluginLink,
+  pluginList,
+  pluginRemove,
+  managedAgentInit,
+  managedAgentValidate,
+  managedAgentPlan,
+  managedAgentApply,
+  managedAgentDestroy,
+  managedAgentStateList,
+  managedAgentStateShow,
+  managedAgentStateRm,
+  managedAgentStateImport,
+  managedAgentSessionCreate,
+  managedAgentSessionList,
+  managedAgentSessionGet,
+  managedAgentSessionDelete,
+  managedAgentSessionRun,
+  managedAgentSessionSend,
+  managedAgentSessionEvents,
+  managedAgentSkillList,
 } from "bailian-cli-commands";
 
 // Full bailian-cli product: every command, exposed under the `bl` binary.
@@ -84,6 +117,7 @@ export const commands: Record<string, AnyCommand> = {
   "auth login": authLogin,
   "auth status": authStatus,
   "auth logout": authLogout,
+  "auth generate-access-token": authGenerateAccessToken,
   "text chat": textChat,
   omni: textOmni,
   "image generate": imageGenerate,
@@ -96,6 +130,10 @@ export const commands: Record<string, AnyCommand> = {
   "vision describe": visionDescribe,
   "config show": configShow,
   "config set": configSet,
+  "config list": configList,
+  "config use": configUse,
+  "config ui": configUi,
+  "config agent": configAgent,
   update,
   "app call": appCall,
   "app list": appList,
@@ -120,9 +158,11 @@ export const commands: Record<string, AnyCommand> = {
   "usage free": usageFree,
   "usage freetier": usageFreetier,
   "usage stats": usageStats,
+  "usage summary": usageSummary,
   "pipeline run": pipelineRun,
   "pipeline validate": pipelineValidate,
   "advisor recommend": advisorRecommend,
+  "model list": modelList,
   "workspace list": workspaceList,
   "quota list": quotaList,
   "quota request": quotaRequest,
@@ -133,7 +173,9 @@ export const commands: Record<string, AnyCommand> = {
   "dataset get": datasetGet,
   "dataset delete": datasetDelete,
   "dataset validate": datasetValidate,
-  "finetune create": finetuneCreate,
+  "finetune text create": finetuneTextCreate,
+  "finetune audio create": finetuneAudioCreate,
+  "finetune image create": finetuneImageCreate,
   "finetune list": finetuneList,
   "finetune get": finetuneGet,
   "finetune cancel": finetuneCancel,
@@ -143,7 +185,9 @@ export const commands: Record<string, AnyCommand> = {
   "finetune export": finetuneExport,
   "finetune watch": finetuneWatch,
   "finetune capability": finetuneCapability,
-  "deploy create": deployCreate,
+  "deploy text create": deployTextCreate,
+  "deploy audio create": deployAudioCreate,
+  "deploy image create": deployImageCreate,
   "deploy list": deployList,
   "deploy get": deployGet,
   "deploy models": deployModels,
@@ -154,4 +198,26 @@ export const commands: Record<string, AnyCommand> = {
   "token-plan create-key": tokenPlanCreateKey,
   "token-plan assign-seats": tokenPlanAssignSeats,
   "token-plan add-member": tokenPlanAddMember,
+  "workspace init": workspaceInit,
+  "plugin install": pluginInstall,
+  "plugin link": pluginLink,
+  "plugin list": pluginList,
+  "plugin remove": pluginRemove,
+  "managed-agent init": managedAgentInit,
+  "managed-agent validate": managedAgentValidate,
+  "managed-agent plan": managedAgentPlan,
+  "managed-agent apply": managedAgentApply,
+  "managed-agent destroy": managedAgentDestroy,
+  "managed-agent state list": managedAgentStateList,
+  "managed-agent state show": managedAgentStateShow,
+  "managed-agent state rm": managedAgentStateRm,
+  "managed-agent state import": managedAgentStateImport,
+  "managed-agent session create": managedAgentSessionCreate,
+  "managed-agent session list": managedAgentSessionList,
+  "managed-agent session get": managedAgentSessionGet,
+  "managed-agent session delete": managedAgentSessionDelete,
+  "managed-agent session run": managedAgentSessionRun,
+  "managed-agent session send": managedAgentSessionSend,
+  "managed-agent session events": managedAgentSessionEvents,
+  "managed-agent skill-list": managedAgentSkillList,
 };

packages/cli/src/main.ts

@@ -1,5 +1,6 @@
 import { createCli } from "bailian-cli-runtime";
 import { commands } from "./commands.ts";
+import { commandPackPolicy } from "./command-pack-policy.ts";
 import pkg from "../package.json" with { type: "json" };
 
 const quickStartTasks = [
@@ -15,4 +16,5 @@ void createCli(commands, {
   clientName: "bailian-cli",
   npmPackage: "bailian-cli",
   quickStartTasks,
+  commandPacks: commandPackPolicy,
 }).run();

packages/cli/tests/e2e/auth.e2e.test.ts

@@ -1,268 +0,0 @@
-import { readFileSync } from "fs";
-import { join } from "path";
-import { describe, expect, test } from "vite-plus/test";
-import { isDashScopeE2EReady, makeE2eOutputDir, parseStdoutJson, runCli } from "./helpers.ts";
-
-/**
- * Auth 相关 E2E：只验证 CLI 进程能正常解析参数并退出。
- */
-
-describe("e2e: auth", () => {
-  test("auth 分组展示子命令帮助且退出码为 0", async () => {
-    const { stdout, stderr, exitCode } = await runCli(["auth"]);
-    expect(exitCode, stderr).toBe(0);
-    const out = `${stdout}\n${stderr}`;
-    expect(out).toMatch(/auth|Authentication|login|logout|status/i);
-  });
-
-  test("auth login --help 正常退出", async () => {
-    const { stderr, exitCode } = await runCli(["auth", "login", "--help"]);
-    expect(exitCode, stderr).toBe(0);
-    expect(stderr).toMatch(/login|api-key/i);
-    expect(stderr).toMatch(/--console-site/);
-    expect(stderr).toMatch(/--open-api/);
-  });
-
-  test("auth logout --help 正常退出", async () => {
-    const { stderr, exitCode } = await runCli(["auth", "logout", "--help"]);
-    expect(exitCode, stderr).toBe(0);
-    expect(stderr).toMatch(/logout|dry-run|yes/i);
-  });
-
-  test("auth status --help 正常退出", async () => {
-    const { stderr, exitCode } = await runCli(["auth", "status", "--help"]);
-    expect(exitCode, stderr).toBe(0);
-    expect(stderr).toMatch(/status|output/i);
-  });
-
-  test("auth login 缺少 --api-key 时报用法错误并退出 (2)", async () => {
-    const { stderr, exitCode } = await runCli(["auth", "login", "--quiet"]);
-    expect(exitCode, stderr).toBe(2);
-    expect(stderr).toMatch(/Choose exactly one login mode/);
-  });
-
-  test("auth login 一次只能选择一种登录模式", async () => {
-    const { stderr, exitCode } = await runCli([
-      "auth",
-      "login",
-      "--console",
-      "--api-key",
-      "sk-e2e-placeholder",
-    ]);
-    expect(exitCode).toBe(2);
-    expect(stderr).toMatch(/Choose exactly one login mode/);
-  });
-
-  test("auth login 模式专属参数不能脱离对应模式", async () => {
-    const openApiFlagOnly = await runCli(["auth", "login", "--access-key-id", "LTAI-e2e"]);
-    expect(openApiFlagOnly.exitCode).toBe(2);
-    expect(openApiFlagOnly.stderr).toMatch(/Use --open-api with --access-key-id/);
-
-    const baseUrlWithoutApiKey = await runCli([
-      "auth",
-      "login",
-      "--console",
-      "--base-url",
-      "https://dashscope.aliyuncs.com",
-    ]);
-    expect(baseUrlWithoutApiKey.exitCode).toBe(2);
-    expect(baseUrlWithoutApiKey.stderr).toMatch(/Use --base-url only with --api-key/);
-
-    const consoleSiteWithoutConsole = await runCli([
-      "auth",
-      "login",
-      "--api-key",
-      "sk-e2e-placeholder",
-      "--console-site",
-      "international",
-    ]);
-    expect(consoleSiteWithoutConsole.exitCode).toBe(2);
-    expect(consoleSiteWithoutConsole.stderr).toMatch(/Use --console-site only with --console/);
-  });
-
-  test("auth login --open-api 要求 AK/SK 成对输入", async () => {
-    const { stderr, exitCode } = await runCli([
-      "auth",
-      "login",
-      "--open-api",
-      "--access-key-id",
-      "LTAI-e2e",
-    ]);
-    expect(exitCode).toBe(2);
-    expect(stderr).toMatch(/Provide --access-key-id and --access-key-secret with --open-api/);
-  });
-
-  test("auth login --dry-run --api-key 不发起校验与落盘", async () => {
-    const { stdout, stderr, exitCode } = await runCli([
-      "auth",
-      "login",
-      "--dry-run",
-      "--api-key",
-      "sk-e2e-dry-run-placeholder",
-    ]);
-    expect(exitCode, stderr).toBe(0);
-    expect(stdout).toContain("Would validate and save API key.");
-  });
-
-  test("auth login --dry-run 覆盖全局参数 --output json --timeout", async () => {
-    const { stdout, stderr, exitCode } = await runCli([
-      "auth",
-      "login",
-      "--dry-run",
-      "--api-key",
-      "sk-e2e-dry-run-placeholder",
-      "--output",
-      "json",
-      "--timeout",
-      "120",
-    ]);
-    expect(exitCode, stderr).toBe(0);
-    expect(stdout).toContain("Would validate and save API key.");
-  });
-
-  test("auth login 缺少密钥且 --output json 时报用法错误并退出 (2)", async () => {
-    const { stderr, exitCode } = await runCli(["auth", "login", "--output", "json"]);
-    expect(exitCode).toBe(2);
-    const err = JSON.parse(stderr.trim()) as { error?: { code?: number; message?: string } };
-    expect(err.error?.code).toBe(2);
-    expect(err.error?.message).toMatch(/Choose exactly one login mode/);
-  });
-
-  test("auth logout --dry-run 不写入配置", async () => {
-    const { stdout, stderr, exitCode } = await runCli(["auth", "logout", "--dry-run"]);
-    expect(exitCode, stderr).toBe(0);
-    expect(stdout).toContain("No changes made.");
-    expect(stderr).not.toContain("Cleared api_key");
-  });
-
-  test("auth logout --dry-run --quiet", async () => {
-    const { stdout, stderr, exitCode } = await runCli(["auth", "logout", "--dry-run", "--quiet"]);
-    expect(exitCode, stderr).toBe(0);
-    expect(stdout).toContain("No changes made.");
-  });
-
-  test("auth logout --dry-run --output json（不清除密钥）", async () => {
-    const { stdout, stderr, exitCode } = await runCli([
-      "auth",
-      "logout",
-      "--dry-run",
-      "--output",
-      "json",
-    ]);
-    expect(exitCode, stderr).toBe(0);
-    expect(stdout).toContain("No changes made.");
-    expect(stderr).not.toContain("Cleared api_key");
-  });
-
-  test.skipIf(!isDashScopeE2EReady())("auth status 文本输出", async () => {
-    const { stdout, stderr, exitCode } = await runCli(["auth", "status", "--output", "text"]);
-    expect(exitCode, stderr).toBe(0);
-    expect(stdout).toMatch(
-      /Authentication Status|API key:|Console token:|DashScope API:|Console gateway:/,
-    );
-  });
-
-  test.skipIf(!isDashScopeE2EReady())("auth status --output json", async () => {
-    const { stdout, stderr, exitCode } = await runCli(["auth", "status", "--output", "json"]);
-    expect(exitCode, stderr).toBe(0);
-    const data = parseStdoutJson<{
-      authenticated?: boolean;
-      api_key?: { source?: string; masked?: string; base_url?: string };
-    }>(stdout);
-    expect(data.authenticated).toBe(true);
-    expect(data.api_key?.source).toBeDefined();
-  });
-
-  test.skipIf(!isDashScopeE2EReady())(
-    "auth status --output json --quiet(base_url 经 env 指定;凭证域 flag 对 status 不可见)",
-    async () => {
-      const { stdout, stderr, exitCode } = await runCli(
-        ["auth", "status", "--output", "json", "--quiet"],
-        { DASHSCOPE_BASE_URL: "https://dashscope.aliyuncs.com" },
-      );
-      expect(exitCode, stderr).toBe(0);
-      const data = parseStdoutJson<{ authenticated?: boolean; api_key?: unknown }>(stdout);
-      expect(data.authenticated).toBe(true);
-      expect(data.api_key).toBeDefined();
-    },
-  );
-
-  test("auth status 不接受凭证域覆盖 flag(--base-url 报 Unknown flag)", async () => {
-    const { stderr, exitCode } = await runCli(["auth", "status", "--base-url", "https://x.test"]);
-    expect(exitCode).not.toBe(0);
-    expect(stderr).toMatch(/Unknown flag.*--base-url/);
-  });
-
-  test("auth status 展示 env OpenAPI AK/SK 且不接受 OpenAPI flag 覆盖", async () => {
-    const { stdout, stderr, exitCode } = await runCli(["auth", "status", "--output", "json"], {
-      ALIBABA_CLOUD_ACCESS_KEY_ID: "LTAI-e2e-placeholder",
-      ALIBABA_CLOUD_ACCESS_KEY_SECRET: "secret-e2e-placeholder",
-    });
-    expect(exitCode, stderr).toBe(0);
-    const data = parseStdoutJson<{
-      authenticated?: boolean;
-      openapi?: { source?: string; access_key_id?: string; access_key_secret?: string };
-    }>(stdout);
-    expect(data.authenticated).toBe(true);
-    expect(data.openapi?.source).toBe("env");
-    expect(data.openapi?.access_key_id).not.toBe("LTAI-e2e-placeholder");
-    expect(data.openapi?.access_key_secret).not.toBe("secret-e2e-placeholder");
-
-    const denied = await runCli(["auth", "status", "--access-key-id", "ak"]);
-    expect(denied.exitCode).not.toBe(0);
-    expect(denied.stderr).toMatch(/Unknown flag.*--access-key-id/);
-  });
-
-  test("auth login --open-api 持久化 OpenAPI AK/SK 并支持单独 logout", async () => {
-    const configDir = makeE2eOutputDir("auth-openapi-login");
-    const env = {
-      BAILIAN_CONFIG_DIR: configDir,
-      ALIBABA_CLOUD_ACCESS_KEY_ID: "",
-      ALIBABA_CLOUD_ACCESS_KEY_SECRET: "",
-    };
-
-    const login = await runCli(
-      [
-        "auth",
-        "login",
-        "--open-api",
-        "--access-key-id",
-        "LTAI-e2e-login-placeholder",
-        "--access-key-secret",
-        "secret-e2e-login-placeholder",
-      ],
-      env,
-    );
-    expect(login.exitCode, login.stderr).toBe(0);
-    expect(login.stderr).toMatch(/OpenAPI credentials saved/);
-
-    const config = JSON.parse(readFileSync(join(configDir, "config.json"), "utf8")) as Record<
-      string,
-      unknown
-    >;
-    expect(config.access_key_id).toBe("LTAI-e2e-login-placeholder");
-    expect(config.access_key_secret).toBe("secret-e2e-login-placeholder");
-    expect(config.openapi_access_key_id).toBeUndefined();
-    expect(config.openapi_access_key_secret).toBeUndefined();
-
-    const status = await runCli(["auth", "status", "--output", "json"], env);
-    expect(status.exitCode, status.stderr).toBe(0);
-    const data = parseStdoutJson<{
-      authenticated?: boolean;
-      openapi?: { source?: string; access_key_id?: string; access_key_secret?: string };
-    }>(status.stdout);
-    expect(data.authenticated).toBe(true);
-    expect(data.openapi?.source).toBe("config");
-    expect(data.openapi?.access_key_id).not.toBe("LTAI-e2e-login-placeholder");
-    expect(data.openapi?.access_key_secret).not.toBe("secret-e2e-login-placeholder");
-
-    const logout = await runCli(["auth", "logout", "--open-api"], env);
-    expect(logout.exitCode, logout.stderr).toBe(0);
-    expect(logout.stderr).toMatch(/Cleared access_key_id/);
-
-    const after = await runCli(["auth", "status", "--output", "json"], env);
-    expect(after.exitCode, after.stderr).toBe(0);
-    const afterData = parseStdoutJson<{ authenticated?: boolean; openapi?: unknown }>(after.stdout);
-    expect(afterData.openapi).toBeUndefined();
-  });
-});

packages/cli/tests/e2e/command-packs.e2e.test.ts

@@ -0,0 +1,134 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterAll, beforeAll, describe, expect, test } from "vite-plus/test";
+import { parseStdoutJson, runCli } from "./helpers.ts";
+
+const fixtureRoot = join(fileURLToPath(import.meta.url), "..", "..", "fixtures", "command-pack");
+let configDir: string;
+
+function env(): NodeJS.ProcessEnv {
+  return { BAILIAN_CONFIG_DIR: configDir, DO_NOT_TRACK: "1" };
+}
+
+describe("e2e: Command Pack", () => {
+  beforeAll(async () => {
+    configDir = await mkdtemp(join(tmpdir(), "bl-command-pack-e2e-"));
+  });
+
+  afterAll(async () => {
+    await rm(configDir, { recursive: true, force: true });
+  });
+
+  test("plugin 分组和管理命令 help 正常", async () => {
+    const group = await runCli(["plugin"], env());
+    expect(group.exitCode, group.stderr).toBe(0);
+    expect(group.stderr).toContain("plugin install");
+    expect(group.stderr).toContain("plugin link");
+    expect(group.stderr).toContain("plugin list");
+    expect(group.stderr).toContain("plugin remove");
+
+    const install = await runCli(["plugin", "install", "--help"], env());
+    expect(install.exitCode, install.stderr).toBe(0);
+    expect(install.stderr).toContain("--package");
+  });
+
+  test("未 link 时插件命令不存在", async () => {
+    const result = await runCli(["agent", "ping", "--message", "before"], env());
+    expect(result.exitCode).not.toBe(0);
+    expect(result.stderr).toMatch(/Unknown command/i);
+  });
+
+  test("link 后命令进入原生 registry/help/执行链路", async () => {
+    const linked = await runCli(
+      ["plugin", "link", "--path", fixtureRoot, "--output", "json"],
+      env(),
+    );
+    expect(linked.exitCode, linked.stderr).toBe(0);
+    const linkedJson = parseStdoutJson<{ linked: { name: string; commands: string[] } }>(
+      linked.stdout,
+    );
+    expect(linkedJson.linked.name).toBe("@ali/bailian-plugin-agent");
+    expect(linkedJson.linked.commands).toEqual([
+      "agent credential",
+      "agent credential-denied",
+      "agent fail",
+      "agent output",
+      "agent ping",
+    ]);
+
+    const rootHelp = await runCli(["--help"], env());
+    expect(rootHelp.exitCode, rootHelp.stderr).toBe(0);
+    expect(rootHelp.stderr).toContain("agent ping");
+
+    const commandHelp = await runCli(["agent", "ping", "--help"], env());
+    expect(commandHelp.exitCode, commandHelp.stderr).toBe(0);
+    expect(commandHelp.stderr).toContain("Ping the Command Pack fixture");
+    expect(commandHelp.stderr).toContain("--message");
+
+    const executed = await runCli(["agent", "ping", "--message", "hello"], env());
+    expect(executed.exitCode, executed.stderr).toBe(0);
+    expect(executed.stdout).toContain("command-pack:hello");
+
+    const credential = await runCli(["agent", "credential", "--api-key", "fixture-key"], env());
+    expect(credential.exitCode, credential.stderr).toBe(0);
+    expect(credential.stdout).toContain("credential-source:flag");
+
+    const denied = await runCli(["agent", "credential-denied"], {
+      ...env(),
+      DASHSCOPE_API_KEY: "fixture-key",
+    });
+    expect(denied.exitCode).toBe(1);
+    expect(denied.stderr).toContain('must declare auth="apiKey"');
+
+    const outputText = await runCli(["agent", "output"], env());
+    expect(outputText.exitCode, outputText.stderr).toBe(0);
+    expect(outputText.stdout).toBe("command-pack-output\n");
+
+    const outputJson = await runCli(["agent", "output", "--output", "json"], env());
+    expect(outputJson.exitCode, outputJson.stderr).toBe(0);
+    expect(parseStdoutJson(outputJson.stdout)).toEqual({ source: "command-pack", ok: true });
+
+    const failed = await runCli(["agent", "fail", "--output", "text"], env());
+    expect(failed.exitCode).toBe(2);
+    expect(failed.stderr).toContain("Command Pack fixture usage error.");
+    expect(failed.stderr).toContain("Use agent fail only in tests.");
+  });
+
+  test("plugin list 输出加载状态", async () => {
+    const result = await runCli(["plugin", "list", "--output", "json"], env());
+    expect(result.exitCode, result.stderr).toBe(0);
+    const json = parseStdoutJson<{
+      command_packs: Array<{ name: string; status: string; commands: string[] }>;
+    }>(result.stdout);
+    expect(json.command_packs).toEqual([
+      expect.objectContaining({
+        name: "@ali/bailian-plugin-agent",
+        status: "loaded",
+        commands: [
+          "agent credential",
+          "agent credential-denied",
+          "agent fail",
+          "agent output",
+          "agent ping",
+        ],
+      }),
+    ]);
+  });
+
+  test("remove 后命令从下一进程消失", async () => {
+    const removed = await runCli(
+      ["plugin", "remove", "--name", "@ali/bailian-plugin-agent", "--output", "json"],
+      env(),
+    );
+    expect(removed.exitCode, removed.stderr).toBe(0);
+    expect(parseStdoutJson<{ removed: string }>(removed.stdout).removed).toBe(
+      "@ali/bailian-plugin-agent",
+    );
+
+    const result = await runCli(["agent", "ping", "--message", "after"], env());
+    expect(result.exitCode).not.toBe(0);
+    expect(result.stderr).toMatch(/Unknown command/i);
+  });
+});

packages/cli/tests/e2e/config-profile.e2e.test.ts

@@ -0,0 +1,164 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { describe, expect, test } from "vite-plus/test";
+import { parseStdoutJson, runCli } from "./helpers.ts";
+
+function withTempConfigDir<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+  const dir = mkdtempSync(join(tmpdir(), "bl-config-profile-"));
+  return fn(dir).finally(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+}
+
+function writeConfig(dir: string, data: Record<string, unknown>): void {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "config.json"), JSON.stringify(data, null, 2) + "\n");
+}
+
+describe("e2e: named config", () => {
+  test("根帮助展示 --config 全局标志", async () => {
+    const { stderr, exitCode } = await runCli(["--help"]);
+    expect(exitCode, stderr).toBe(0);
+    expect(stderr).toMatch(/--config <name>/);
+  });
+
+  test("config set --config 写入命名 block 且不影响默认配置", async () => {
+    await withTempConfigDir(async (dir) => {
+      writeConfig(dir, { output: "text", api_key: "sk-default" });
+
+      const setResult = await runCli(
+        [
+          "config",
+          "set",
+          "--config",
+          "dev",
+          "--key",
+          "output",
+          "--value",
+          "json",
+          "--output",
+          "json",
+        ],
+        { BAILIAN_CONFIG_DIR: dir },
+      );
+      expect(setResult.exitCode, setResult.stderr).toBe(0);
+      const setData = parseStdoutJson<{
+        output?: string;
+        config?: string;
+        config_file?: string;
+      }>(setResult.stdout);
+      expect(setData.output).toBe("json");
+      expect(setData.config).toBe("dev");
+      expect(setData.config_file).toBe(join(dir, "config.json"));
+
+      const raw = JSON.parse(readFileSync(join(dir, "config.json"), "utf8")) as Record<
+        string,
+        unknown
+      >;
+      expect(raw.output).toBe("text");
+      expect((raw.dev as Record<string, unknown>).output).toBe("json");
+    });
+  });
+
+  test("config show --config 只展示命名 block", async () => {
+    await withTempConfigDir(async (dir) => {
+      writeConfig(dir, {
+        output: "text",
+        api_key: "sk-default",
+        dev: { output: "json", access_token: "tok-dev" },
+      });
+
+      const { stdout, stderr, exitCode } = await runCli(
+        ["config", "show", "--config", "dev", "--output", "json"],
+        { BAILIAN_CONFIG_DIR: dir },
+      );
+      expect(exitCode, stderr).toBe(0);
+      const data = parseStdoutJson<Record<string, unknown>>(stdout);
+      expect(data.config).toBe("dev");
+      expect(data.config_file).toBe(join(dir, "config.json"));
+      expect(data.output).toBe("json");
+      expect(data.access_token).toBeDefined();
+      expect(data.api_key).toBeUndefined();
+    });
+  });
+
+  test("auth status --config 不继承默认凭证", async () => {
+    await withTempConfigDir(async (dir) => {
+      writeConfig(dir, { api_key: "sk-default", dev: { output: "json" } });
+
+      const devStatus = await runCli(["auth", "status", "--config", "dev", "--output", "json"], {
+        BAILIAN_CONFIG_DIR: dir,
+        DASHSCOPE_API_KEY: "",
+        ALIBABA_CLOUD_ACCESS_KEY_ID: "",
+        ALIBABA_CLOUD_ACCESS_KEY_SECRET: "",
+      });
+      expect(devStatus.exitCode, devStatus.stderr).toBe(0);
+      const devData = parseStdoutJson<Record<string, unknown>>(devStatus.stdout);
+      expect(devData.authenticated).toBe(false);
+      expect(devData.config).toBe("dev");
+
+      const defaultStatus = await runCli(["auth", "status", "--output", "json"], {
+        BAILIAN_CONFIG_DIR: dir,
+        DASHSCOPE_API_KEY: "",
+        ALIBABA_CLOUD_ACCESS_KEY_ID: "",
+        ALIBABA_CLOUD_ACCESS_KEY_SECRET: "",
+      });
+      expect(defaultStatus.exitCode, defaultStatus.stderr).toBe(0);
+      const defaultData = parseStdoutJson<Record<string, unknown>>(defaultStatus.stdout);
+      expect(defaultData.authenticated).toBe(true);
+      expect(defaultData.config).toBe("default");
+    });
+  });
+
+  test("--config default 等价默认配置", async () => {
+    await withTempConfigDir(async (dir) => {
+      writeConfig(dir, {
+        active_config: "token-plan",
+        output: "json",
+        api_key: "sk-default",
+        "token-plan": { output: "text", api_key: "sk-token" },
+      });
+      const { stdout, stderr, exitCode } = await runCli(
+        ["config", "show", "--config", "default", "--output", "json"],
+        { BAILIAN_CONFIG_DIR: dir },
+      );
+      expect(exitCode, stderr).toBe(0);
+      const data = parseStdoutJson<Record<string, unknown>>(stdout);
+      expect(data.config).toBe("default");
+      expect(data.active).toBeUndefined();
+      expect(data.api_key).toBeDefined();
+      const raw = JSON.parse(readFileSync(join(dir, "config.json"), "utf8")) as Record<
+        string,
+        unknown
+      >;
+      expect(raw.active_config).toBe("token-plan");
+    });
+  });
+
+  test("非法 --config 名称报 usage error", async () => {
+    const { stderr, exitCode } = await runCli(["auth", "status", "--config", "../evil"]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/Invalid config name/);
+  });
+
+  test("auth status 文本输出分行展示选中 Config 和配置文件", async () => {
+    await withTempConfigDir(async (dir) => {
+      writeConfig(dir, {
+        active_config: "token-plan",
+        "token-plan": { api_key: "sk-token" },
+      });
+
+      const result = await runCli(["auth", "status", "--output", "text"], {
+        BAILIAN_CONFIG_DIR: dir,
+        DASHSCOPE_API_KEY: "",
+        ALIBABA_CLOUD_ACCESS_KEY_ID: "",
+        ALIBABA_CLOUD_ACCESS_KEY_SECRET: "",
+      });
+      expect(result.exitCode, result.stderr).toBe(0);
+      expect(result.stdout).toContain("Config: token-plan\n");
+      expect(result.stdout).toContain(`Config file: ${join(dir, "config.json")}\n`);
+      expect(result.stdout).not.toContain("Active config:");
+    });
+  });
+});

packages/cli/tests/e2e/config.e2e.test.ts

@@ -1,155 +0,0 @@
-import { describe, expect, test } from "vite-plus/test";
-import { parseStdoutJson, runCli } from "./helpers.ts";
-
-/**
- * Config 相关 E2E
- */
-
-describe("e2e: config", () => {
-  test("config 分组展示子命令帮助且成功退出", async () => {
-    const { stdout, stderr, exitCode } = await runCli(["config"]);
-    expect(exitCode, stderr).toBe(0);
-    const out = `${stdout}\n${stderr}`;
-    expect(out).toMatch(/config|show|set/i);
-  });
-
-  test("config show --help 正常退出", async () => {
-    const { stderr, exitCode } = await runCli(["config", "show", "--help"]);
-    expect(exitCode, stderr).toBe(0);
-    expect(stderr).toMatch(/show|config/i);
-  });
-
-  test("config set --help 正常退出", async () => {
-    const { stderr, exitCode } = await runCli(["config", "set", "--help"]);
-    expect(exitCode, stderr).toBe(0);
-    expect(stderr).toMatch(/set|--key|--value/i);
-  });
-
-  test("config show --output json", async () => {
-    const { stdout, stderr, exitCode } = await runCli(["config", "show", "--output", "json"]);
-    expect(exitCode, stderr).toBe(0);
-    const data = parseStdoutJson<{
-      config_file?: string;
-      base_url?: string;
-      timeout?: number;
-    }>(stdout);
-    expect(data.config_file).toBeDefined();
-    expect(data.base_url).toBeDefined();
-    expect(data.timeout).toBeDefined();
-  });
-
-  test("config show --output text", async () => {
-    const { stdout, stderr, exitCode } = await runCli(["config", "show", "--output", "text"]);
-    expect(exitCode, stderr).toBe(0);
-    expect(stdout).toMatch(/config_file|timeout|base_url/i);
-  });
-
-  test("config set 缺少 --key / --value 时报用法错误并退出 (2)", async () => {
-    const { stderr, exitCode } = await runCli(["config", "set", "--quiet"]);
-    expect(exitCode, stderr).toBe(2);
-    expect(stderr).toMatch(/--key|--value|Usage:/i);
-  });
-
-  test("config set 非法 key 时退出为用法错误", async () => {
-    const { stderr, exitCode } = await runCli([
-      "config",
-      "set",
-      "--key",
-      "not-a-real-key",
-      "--value",
-      "x",
-    ]);
-    expect(exitCode).toBe(2);
-    expect(stderr).toMatch(/Invalid config key|not-a-real-key/i);
-  });
-
-  test("config set 非法 output", async () => {
-    const { stderr, exitCode } = await runCli([
-      "config",
-      "set",
-      "--key",
-      "output",
-      "--value",
-      "yaml",
-    ]);
-    expect(exitCode).toBe(2);
-    expect(stderr).toMatch(/Invalid output|text, json/i);
-  });
-
-  test("config set 非法 timeout", async () => {
-    const { stderr, exitCode } = await runCli([
-      "config",
-      "set",
-      "--key",
-      "timeout",
-      "--value",
-      "0",
-    ]);
-    expect(exitCode).toBe(2);
-    expect(stderr).toMatch(/Invalid timeout|positive/i);
-  });
-
-  test("config set --dry-run 不落盘（仅输出 would_set）", async () => {
-    const { stdout, stderr, exitCode } = await runCli([
-      "config",
-      "set",
-      "--dry-run",
-      "--key",
-      "output",
-      "--value",
-      "json",
-      "--output",
-      "json",
-    ]);
-    expect(exitCode, stderr).toBe(0);
-    const data = parseStdoutJson<{ would_set?: { output?: string } }>(stdout);
-    expect(data.would_set?.output).toBe("json");
-  });
-
-  test("config set --dry-run 支持连字符别名 key", async () => {
-    const { stdout, stderr, exitCode } = await runCli([
-      "config",
-      "set",
-      "--dry-run",
-      "--key",
-      "default-text-model",
-      "--value",
-      "qwen3.7-max",
-      "--output",
-      "json",
-    ]);
-    expect(exitCode, stderr).toBe(0);
-    const data = parseStdoutJson<{ would_set?: { default_text_model?: string } }>(stdout);
-    expect(data.would_set?.default_text_model).toBe("qwen3.7-max");
-  });
-
-  test("config set --dry-run 支持 AccessKey 短字段别名", async () => {
-    const { stdout, stderr, exitCode } = await runCli([
-      "config",
-      "set",
-      "--dry-run",
-      "--key",
-      "access-key-id",
-      "--value",
-      "LTAI-config-placeholder",
-      "--output",
-      "json",
-    ]);
-    expect(exitCode, stderr).toBe(0);
-    const data = parseStdoutJson<{ would_set?: { access_key_id?: string } }>(stdout);
-    expect(data.would_set?.access_key_id).toBe("LTAI-config-placeholder");
-  });
-
-  test("config set 不接受旧 OpenAPI AccessKey 字段名", async () => {
-    const { stderr, exitCode } = await runCli([
-      "config",
-      "set",
-      "--key",
-      "openapi_access_key_id",
-      "--value",
-      "LTAI-config-placeholder",
-    ]);
-    expect(exitCode).toBe(2);
-    expect(stderr).toMatch(/Invalid config key|openapi_access_key_id/);
-  });
-});

packages/cli/tests/e2e/helpers.ts

@@ -1,215 +1,52 @@
-import { execFile } from "child_process";
-import { mkdirSync, readFileSync } from "fs";
-import { promisify } from "util";
-import { basename, dirname, join } from "path";
+import { dirname, join } from "path";
 import { fileURLToPath } from "url";
-import { readConfigFile } from "bailian-cli-core";
+import {
+  cliTimeoutPrefix,
+  cliTimeoutSeconds,
+  e2eLabelFromMetaUrl,
+  isConsoleAuthFailure,
+  makeE2eOutputDir,
+  parseStdoutJson,
+} from "e2e/output";
+import { runNodeMain, type RunCliResult } from "e2e/runner";
+import {
+  isBailianE2EEnabled,
+  isBailianE2EMediaEnabled,
+  isBailianE2EVideoEnabled,
+  isChatE2EReady,
+  isConsoleE2EReady,
+  isDashScopeE2EReady,
+  isSearchE2EReady,
+} from "e2e/gating";
+import { monorepoRoot } from "e2e/monorepo-root";
 
-const execFileAsync = promisify(execFile);
+export {
+  cliTimeoutPrefix,
+  cliTimeoutSeconds,
+  e2eLabelFromMetaUrl,
+  isBailianE2EEnabled,
+  isBailianE2EMediaEnabled,
+  isBailianE2EVideoEnabled,
+  isChatE2EReady,
+  isConsoleAuthFailure,
+  isConsoleE2EReady,
+  isDashScopeE2EReady,
+  isSearchE2EReady,
+  makeE2eOutputDir,
+  monorepoRoot,
+  parseStdoutJson,
+};
+export type { RunCliResult };
 
-/**
- * Vitest `global-setup.ts` 写入 `test/output/` 下本文件名，供各 worker 进程读取同一会话 id。
- * （仅模块内变量无法跨 Vitest 多进程 worker 共享。）
- */
-export const E2E_RUN_SESSION_FILENAME = ".e2e-run-session";
-
-/**
- * 单次 `vp test` / Vitest 运行共用的 E2E 输出会话目录名（惰性缓存于当前进程）。
- */
-let e2eOutputSessionId: string | undefined;
-
-/** `packages/cli` 根目录（含 `src/main.ts`） */
+/** `packages/cli` 根目录 */
 export const cliPackageRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 
 const mainTs = join(cliPackageRoot, "src", "main.ts");
 
-/** Monorepo 根（含根 `package.json`） */
-export function monorepoRoot(): string {
-  return join(cliPackageRoot, "..", "..");
-}
-
-export function localBin(name: string): string {
-  return join(
-    monorepoRoot(),
-    "node_modules",
-    ".bin",
-    process.platform === "win32" ? `${name}.cmd` : name,
-  );
-}
-
-function readE2eRunSessionFromOutputDir(): string | undefined {
-  try {
-    const p = join(monorepoRoot(), "test", "output", E2E_RUN_SESSION_FILENAME);
-    const t = readFileSync(p, "utf8").trim();
-    return t.length > 0 ? t : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-function getE2eOutputSessionId(): string {
-  if (!e2eOutputSessionId) {
-    const fromEnv = process.env.BAILIAN_E2E_RUN_ID?.trim();
-    if (fromEnv) {
-      e2eOutputSessionId = fromEnv.replace(/[^a-zA-Z0-9._-]+/g, "-");
-    } else {
-      const fromFile = readE2eRunSessionFromOutputDir();
-      if (fromFile) {
-        e2eOutputSessionId = fromFile.replace(/[^a-zA-Z0-9._-]+/g, "-");
-      } else {
-        e2eOutputSessionId = `e2e-run-${Date.now()}-${process.pid}`;
-      }
-    }
-  }
-  return e2eOutputSessionId;
-}
-
-/**
- * 在 `test/output/<会话>/` 下创建用例子目录。
- * 会话 id 优先 `BAILIAN_E2E_RUN_ID`，否则读 Vitest globalSetup 写入的 `test/output/.e2e-run-session`，
- * 再否则回退为单进程 id（非 Vitest 直接跑用例时）。
- * 若已设 `BAILIAN_E2E_OUT` 则直接使用（不再套会话目录）。
- */
-export function makeE2eOutputDir(label: string): string {
-  const fromEnv = process.env.BAILIAN_E2E_OUT?.trim();
-  if (fromEnv) {
-    mkdirSync(fromEnv, { recursive: true });
-    return fromEnv;
-  }
-  const safe = label.replace(/[^a-zA-Z0-9._-]+/g, "-");
-  const sessionDir = join(monorepoRoot(), "test", "output", getE2eOutputSessionId());
-  mkdirSync(sessionDir, { recursive: true });
-  const dir = join(sessionDir, `e2e-vp-${safe}-${Date.now()}`);
-  mkdirSync(dir, { recursive: true });
-  return dir;
-}
-
-/** 全局 `--timeout` 秒数（视频等长任务） */
-export function cliTimeoutSeconds(): string {
-  return process.env.BAILIAN_E2E_TIMEOUT_SEC?.trim() || "3600";
-}
-
-export function cliTimeoutPrefix(): string[] {
-  return ["--timeout", cliTimeoutSeconds()];
-}
-
-/** 显式开启后才跑真实网络 E2E，避免默认 `vp test` 依赖密钥或打外网 */
-export function isBailianE2EEnabled(): boolean {
-  return process.env.BAILIAN_E2E === "1";
-}
-
-/** 可调 DashScope 的 API Key：环境变量优先，否则读 ~/.bailian/config.json */
-export function isDashScopeE2EReady(): boolean {
-  if (!isBailianE2EEnabled()) return false;
-  if (process.env.DASHSCOPE_API_KEY?.trim()) return true;
-  try {
-    const f = readConfigFile();
-    return typeof f.api_key === "string" && f.api_key.length > 0;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Console-gateway 命令（quota / usage free / usage stats）的 E2E 就绪检查：
- * 需 `BAILIAN_E2E=1` 且存在 console access_token（`~/.bailian/config.json` 的
- * `access_token`；凭证解析已集中到 authStage，不再读环境变量）。
- *
- * 仅检查 token 是否存在——无法本地判断是否过期。token 过期时 gated 用例仍会执行，
- * 但用 `isConsoleAuthFailure` 把“session 未登录/已过期”的优雅报错视为通过，保持
- * 与 deploy/dataset “无 key / 有效 key / 失效 key 均绿”的一致策略。
- */
-export function isConsoleE2EReady(): boolean {
-  if (!isBailianE2EEnabled()) return false;
-  try {
-    const config = readConfigFile();
-    return typeof config.access_token === "string" && config.access_token.length > 0;
-  } catch {
-    return false;
-  }
-}
-
-/** 语音与图像（可设 `BAILIAN_E2E_MEDIA=0` 在仅跑文本/记忆/知识库时跳过） */
-export function isBailianE2EMediaEnabled(): boolean {
-  if (process.env.BAILIAN_E2E_MEDIA === "0") return false;
-  return isBailianE2EEnabled();
-}
-
-/** 文生视频 / 图生视频 / 参考视频 / 视频编辑（耗时长，默认关闭） */
-export function isBailianE2EVideoEnabled(): boolean {
-  return isBailianE2EEnabled() && process.env.BAILIAN_E2E_VIDEO === "1";
-}
-
-/** 从 `import.meta.url` 生成 OUT 子目录标签，避免并行用例目录冲突 */
-export function e2eLabelFromMetaUrl(metaUrl: string): string {
-  return basename(fileURLToPath(metaUrl), ".ts").replace(/\.e2e\.test$/, "");
-}
-
-/** 知识库用例：须显式索引 ID + API-KEY */
-export function isKnowledgeE2EReady(): boolean {
-  if (!isBailianE2EEnabled()) return false;
-  if (!process.env.BAILIAN_E2E_INDEX_ID) return false;
-  return isDashScopeE2EReady();
-}
-
-export interface RunCliResult {
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-}
-
-/**
- * 子进程执行 CLI（等价于在 `packages/cli` 下 `tsx src/main.ts ...`）。
- * request_id 等诊断信息在 stderr；`--output json` 时 JSON 在 stdout。
- */
+/** 子进程执行 bl CLI */
 export async function runCli(
   args: string[],
   envOverrides: NodeJS.ProcessEnv = {},
 ): Promise<RunCliResult> {
-  try {
-    const { stdout, stderr } = await execFileAsync(localBin("tsx"), [mainTs, ...args], {
-      cwd: cliPackageRoot,
-      encoding: "utf8",
-      maxBuffer: 32 * 1024 * 1024,
-      env: {
-        ...process.env,
-        NODE_NO_WARNINGS: "1",
-        DO_NOT_TRACK: "1",
-        ...envOverrides,
-      },
-    });
-    return { stdout: stdout ?? "", stderr: stderr ?? "", exitCode: 0 };
-  } catch (err: unknown) {
-    const e = err as {
-      stdout?: string;
-      stderr?: string;
-      code?: number;
-    };
-    return {
-      stdout: e.stdout ?? "",
-      stderr: e.stderr ?? "",
-      exitCode: typeof e.code === "number" ? e.code : 1,
-    };
-  }
-}
-
-export function parseStdoutJson<T = unknown>(stdout: string): T {
-  const t = stdout.trim();
-  // Extract JSON object — stdout may contain [perf] console.time lines before JSON
-  const jsonMatch = t.match(/\{[\s\S]*\}/);
-  if (!jsonMatch) throw new Error(`No JSON object found in stdout: ${t.slice(0, 200)}`);
-  return JSON.parse(jsonMatch[0]) as T;
-}
-
-/**
- * 判断一次 CLI 运行是否因 console session 未登录/已过期而失败。
- *
- * Console E2E 用例的 readiness 闸（`isConsoleE2EReady`）只能判断 token 是否存在，
- * 无法判断是否过期；token 失效时 gated 用例仍会执行并拿到鉴权错误。本函数让用例
- * 参考 deploy/dataset 的做法：只要 CLI 把鉴权错误优雅上抛（非零退出 + stderr 说明
- * session 失效），即视为通过，而不是强求 exit 0 的成功输出。
- */
-export function isConsoleAuthFailure(result: RunCliResult): boolean {
-  if (result.exitCode === 0) return false;
-  return /not logged in|has expired|NotLogined|Run `bl auth login/i.test(result.stderr);
+  return runNodeMain(mainTs, args, { cwd: cliPackageRoot, env: envOverrides });
 }

packages/cli/tests/e2e/image-edit.e2e.test.ts

@@ -1,115 +0,0 @@
-import { describe, expect, test } from "vite-plus/test";
-import { dirname, join } from "path";
-import { fileURLToPath } from "url";
-import {
-  e2eLabelFromMetaUrl,
-  isBailianE2EMediaEnabled,
-  isDashScopeE2EReady,
-  makeE2eOutputDir,
-  parseStdoutJson,
-  runCli,
-} from "./helpers.ts";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-/**
- * Image edit E2E
- */
-
-describe("e2e: image edit", () => {
-  test("image 分组展示子命令帮助且成功退出", async () => {
-    const { stdout, stderr, exitCode } = await runCli(["image"]);
-    expect(exitCode, stderr).toBe(0);
-    const out = `${stdout}\n${stderr}`;
-    expect(out).toMatch(/image|generate|edit/i);
-  });
-
-  test("image edit --help 正常退出", async () => {
-    const { stderr, exitCode } = await runCli(["image", "edit", "--help"]);
-    expect(exitCode, stderr).toBe(0);
-    expect(stderr).toMatch(/edit|--image|--prompt|--async|--concurrent/i);
-  });
-
-  test("image edit --dry-run 接受 async 模型的 --async 与 --concurrent", async () => {
-    const { stdout, stderr, exitCode } = await runCli([
-      "image",
-      "edit",
-      "--dry-run",
-      "--model",
-      "wan2.6-t2i",
-      "--image",
-      "https://example.com/source.png",
-      "--prompt",
-      "Change the background to blue",
-      "--async",
-      "--concurrent",
-      "2",
-      "--output",
-      "json",
-    ]);
-    expect(exitCode, stderr).toBe(0);
-    const data = parseStdoutJson<{ mode?: string; request?: { input?: { messages?: unknown[] } } }>(
-      stdout,
-    );
-    expect(data.mode).toBe("async");
-    expect(data.request?.input?.messages?.length).toBeGreaterThan(0);
-  });
-});
-
-describe.skipIf(!isBailianE2EMediaEnabled() || !isDashScopeE2EReady())("e2e: image edit", () => {
-  test("image edit 缺少 --image 时报用法错误并退出 (2)", async () => {
-    const { stderr, exitCode } = await runCli(["image", "edit", "--prompt", "仅提示词"]);
-    expect(exitCode).toBe(2);
-    expect(stderr).toMatch(/--image|Usage:/i);
-  });
-
-  test("image edit 缺少 --prompt 时报用法错误并退出 (2)", async () => {
-    const testPng = join(__dirname, ".smoke-32.png");
-    const { stderr, exitCode } = await runCli(["image", "edit", "--image", testPng]);
-    expect(exitCode).toBe(2);
-    expect(stderr).toMatch(/--prompt|Usage:/i);
-  });
-
-  test("【qwen-image-2.0】图片编辑", async () => {
-    const outDir = makeE2eOutputDir(e2eLabelFromMetaUrl(import.meta.url));
-    const gen = await runCli([
-      "image",
-      "generate",
-      "--model",
-      "qwen-image-2.0",
-      "--prompt",
-      "一只简笔画小猫，白底",
-      "--out-dir",
-      outDir,
-      "--out-prefix",
-      "e2e-gen",
-      "--output",
-      "json",
-    ]);
-    expect(gen.exitCode, gen.stderr).toBe(0);
-    const genData = parseStdoutJson<{ urls?: string[] }>(gen.stdout);
-    const imagePath = genData.urls?.[0];
-
-    expect(imagePath).toBeTruthy();
-
-    const ed = await runCli([
-      "image",
-      "edit",
-      "--model",
-      "qwen-image-2.0",
-      "--image",
-      imagePath!,
-      "--prompt",
-      "把背景改成浅蓝色",
-      "--out-dir",
-      outDir,
-      "--out-prefix",
-      "e2e-edit",
-      "--output",
-      "json",
-    ]);
-    expect(ed.exitCode, ed.stderr).toBe(0);
-    const edData = parseStdoutJson<{ saved?: string[] }>(ed.stdout);
-    expect(edData.saved?.length ?? 0).toBeGreaterThan(0);
-  }, 600_000);
-});

packages/cli/tests/e2e/image-generate.e2e.test.ts

@@ -1,63 +0,0 @@
-import { describe, expect, test } from "vite-plus/test";
-import {
-  e2eLabelFromMetaUrl,
-  isBailianE2EMediaEnabled,
-  isDashScopeE2EReady,
-  makeE2eOutputDir,
-  parseStdoutJson,
-  runCli,
-} from "./helpers.ts";
-
-/**
- * Image generate：先做 help / 分组等常规检测（不依赖密钥、不调生成接口）。
- * 需 DashScope + 媒体 E2E 的缺参、dry-run 与真实生成放在 skip 块内；
- * 真实生成用例保持原逻辑与顺序，放在块内最后。
- */
-
-describe("e2e: image generate", () => {
-  test("image 分组展示子命令帮助且成功退出", async () => {
-    const { stdout, stderr, exitCode } = await runCli(["image"]);
-    expect(exitCode, stderr).toBe(0);
-    const out = `${stdout}\n${stderr}`;
-    expect(out).toMatch(/image|generate|edit/i);
-  });
-
-  test("image generate --help 正常退出", async () => {
-    const { stderr, exitCode } = await runCli(["image", "generate", "--help"]);
-    expect(exitCode, stderr).toBe(0);
-    expect(stderr).toMatch(/generate|--prompt|--model/i);
-  });
-});
-
-describe.skipIf(!isBailianE2EMediaEnabled() || !isDashScopeE2EReady())(
-  "e2e: image generate",
-  () => {
-    test("image generate 缺少 --prompt 时报用法错误并退出 (2)", async () => {
-      const { stderr, exitCode } = await runCli(["image", "generate", "--model", "qwen-image-2.0"]);
-      expect(exitCode).toBe(2);
-      expect(stderr).toMatch(/--prompt|Usage:/i);
-    });
-
-    test("【qwen-image-2.0】图片生成", async () => {
-      const outDir = makeE2eOutputDir(e2eLabelFromMetaUrl(import.meta.url));
-      const { stdout, stderr, exitCode } = await runCli([
-        "image",
-        "generate",
-        "--model",
-        "qwen-image-2.0",
-        "--prompt",
-        "一只简笔画小猫，白底",
-        "--out-dir",
-        outDir,
-        "--out-prefix",
-        "e2e-gen",
-        "--output",
-        "json",
-      ]);
-      expect(exitCode, stderr).toBe(0);
-      const data = parseStdoutJson<{ saved?: string[] }>(stdout);
-      expect(data.saved?.length ?? 0).toBeGreaterThan(0);
-      expect(data.saved?.[0]).toContain("e2e-gen");
-    }, 300_000);
-  },
-);

packages/cli/tests/e2e/knowledge-search.e2e.test.ts

@@ -1,149 +0,0 @@
-import { describe, expect, test } from "vite-plus/test";
-import { parseStdoutJson, runCli } from "./helpers.ts";
-
-interface DryRunBody {
-  endpoint?: string;
-  request?: {
-    query?: string;
-    agent_id?: string;
-    images?: string[];
-    query_history?: Array<{ role: string; content: string }>;
-  };
-}
-
-describe("e2e: knowledge search", () => {
-  test("knowledge search --help 正常退出", async () => {
-    const { stderr, exitCode } = await runCli(["knowledge", "search", "--help"]);
-    expect(exitCode, stderr).toBe(0);
-    expect(stderr).toMatch(/--query/i);
-    expect(stderr).toMatch(/--agent-id/i);
-    expect(stderr).toMatch(/--workspace-id/i);
-    expect(stderr).toMatch(/--image/i);
-    expect(stderr).toMatch(/--query-history/i);
-  });
-
-  test("缺少 --query 时报用法错误并退出 (2)", async () => {
-    const { stderr, exitCode } = await runCli(["knowledge", "search", "--agent-id", "aid_test"]);
-    expect(exitCode).toBe(2);
-    expect(stderr).toMatch(/--query|Usage:/i);
-  });
-
-  test("缺少 --agent-id 时报用法错误并退出 (2)", async () => {
-    const { stderr, exitCode } = await runCli(["knowledge", "search", "--query", "test"]);
-    expect(exitCode).toBe(2);
-    expect(stderr).toMatch(/--agent-id|Usage:/i);
-  });
-
-  test("缺少 --workspace-id 时非零退出并提示", async () => {
-    const { stderr, exitCode } = await runCli(
-      // 假 key + 隔离配置目录:避免本机 config 的 workspace_id/api_key 漏入
-      [
-        "knowledge",
-        "search",
-        "--query",
-        "test",
-        "--agent-id",
-        "aid_test",
-        "--api-key",
-        "sk-fake",
-        "--output",
-        "json",
-      ],
-      { BAILIAN_WORKSPACE_ID: "", BAILIAN_CONFIG_DIR: "/tmp" },
-    );
-    expect(exitCode).not.toBe(0);
-    expect(stderr).toMatch(/workspace.*required/i);
-  });
-
-  test("--dry-run 输出 endpoint 和 request body", async () => {
-    const { stdout, stderr, exitCode } = await runCli([
-      "knowledge",
-      "search",
-      "--dry-run",
-      "--query",
-      "什么是RAG",
-      "--agent-id",
-      "aid_test",
-      "--workspace-id",
-      "ws_test",
-      "--output",
-      "json",
-    ]);
-    expect(exitCode, stderr).toBe(0);
-    const data = parseStdoutJson<DryRunBody>(stdout);
-    expect(data.endpoint).toMatch(/ws_test\.cn-beijing\.maas\.aliyuncs\.com/);
-    expect(data.endpoint).toMatch(/api\/v1\/indices\/knowledge\/search/);
-    expect(data.request?.query).toBe("什么是RAG");
-    expect(data.request?.agent_id).toBe("aid_test");
-  });
-
-  test("--dry-run + --image 输出 images", async () => {
-    const { stdout, stderr, exitCode } = await runCli([
-      "knowledge",
-      "search",
-      "--dry-run",
-      "--query",
-      "test",
-      "--agent-id",
-      "aid_test",
-      "--workspace-id",
-      "ws_test",
-      "--image",
-      "https://example.com/a.jpg",
-      "--image",
-      "https://example.com/b.jpg",
-      "--output",
-      "json",
-    ]);
-    expect(exitCode, stderr).toBe(0);
-    const data = parseStdoutJson<DryRunBody>(stdout);
-    expect(data.request?.images).toEqual([
-      "https://example.com/a.jpg",
-      "https://example.com/b.jpg",
-    ]);
-  });
-
-  test("--dry-run + --query-history 输出用户对话历史", async () => {
-    const { stdout, stderr, exitCode } = await runCli([
-      "knowledge",
-      "search",
-      "--dry-run",
-      "--query",
-      "它怎么工作",
-      "--agent-id",
-      "aid_test",
-      "--workspace-id",
-      "ws_test",
-      "--query-history",
-      '[{"role":"user","content":"什么是RAG"},{"role":"assistant","content":"RAG是检索增强生成"}]',
-      "--output",
-      "json",
-    ]);
-    expect(exitCode, stderr).toBe(0);
-    const data = parseStdoutJson<DryRunBody>(stdout);
-    expect(data.request?.query_history).toEqual([
-      { role: "user", content: "什么是RAG" },
-      { role: "assistant", content: "RAG是检索增强生成" },
-    ]);
-  });
-
-  test("--dry-run + --query-history 无效 JSON 非零退出", async () => {
-    const { stderr, exitCode } = await runCli([
-      "knowledge",
-      "search",
-      "--dry-run",
-      "--query",
-      "test",
-      "--agent-id",
-      "aid_test",
-      "--workspace-id",
-      "ws_test",
-      "--query-history",
-      "not-valid-json",
-      "--output",
-      "json",
-    ]);
-    expect(exitCode).not.toBe(0);
-    expect(stderr).toMatch(/query-history.*valid JSON/i);
-  });
-});

packages/cli/tests/e2e/registry.smoke.e2e.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, test } from "vite-plus/test";
+import { deriveGroupPaths } from "e2e/registry-smoke";
+import { commands } from "../../src/commands.ts";
+import { runCli } from "./helpers.ts";
+
+const commandPaths = Object.keys(commands).sort();
+const groupPaths = deriveGroupPaths(commandPaths);
+
+describe("e2e: bl registry smoke", () => {
+  test("根帮助展示 bl 与全局 flag", async () => {
+    const { stderr, exitCode } = await runCli(["--help"]);
+    expect(exitCode, stderr).toBe(0);
+    expect(stderr).toMatch(/\bbl\b/i);
+    expect(stderr).toMatch(/--base-url/);
+    expect(stderr).toMatch(/--console-region/);
+    expect(stderr).toMatch(/--console-site/);
+    expect(stderr).toMatch(/--console-switch-agent/);
+    expect(stderr).not.toMatch(/^\s*--region\s/m);
+  });
+
+  test("quota check --help:Flags 含 console 域鉴权 flag,Global Flags 全量列出", async () => {
+    const { stderr, exitCode } = await runCli(["quota", "check", "--help"]);
+    expect(exitCode, stderr).toBe(0);
+    expect(stderr).toMatch(/Global Flags:/);
+    expect(stderr).toMatch(/--console-region <region>/);
+    expect(stderr).toMatch(/--model <model>/);
+    expect(stderr).toMatch(/--period <minutes>/);
+    expect(stderr).toMatch(/--output <format>/);
+    expect(stderr).not.toMatch(/API region \(default: cn-beijing\)/);
+  });
+
+  test.each(commandPaths)("已注册命令 %s --help 成功", async (path) => {
+    const { stderr, exitCode } = await runCli([...path.split(" "), "--help"]);
+    expect(exitCode, stderr).toBe(0);
+  });
+
+  test.each(groupPaths)("命令分组 %s --help 成功", async (path) => {
+    const { stderr, exitCode } = await runCli([...path.split(" "), "--help"]);
+    expect(exitCode, stderr).toBe(0);
+  });
+});

packages/cli/tests/e2e/usage-summary.e2e.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "vite-plus/test";
+import { isConsoleE2EReady, isConsoleAuthFailure, parseStdoutJson, runCli } from "./helpers.ts";
+
+describe("e2e: usage summary", () => {
+  test("usage summary --help 正常退出", async () => {
+    const { stderr, exitCode } = await runCli(["usage", "summary", "--help"]);
+    expect(exitCode, stderr).toBe(0);
+    expect(stderr).toMatch(/--days|summary|usage/i);
+  });
+
+  test("usage summary --help 包含所有示例", async () => {
+    const { stderr, exitCode } = await runCli(["usage", "summary", "--help"]);
+    expect(exitCode, stderr).toBe(0);
+    expect(stderr).toContain("bl usage summary");
+    expect(stderr).toContain("bl usage summary --days 30");
+  });
+});
+
+describe.skipIf(!isConsoleE2EReady())("e2e: usage summary（Console）", () => {
+  test("usage summary --dry-run 输出 free-tier 计划请求", async () => {
+    const { stdout, stderr, exitCode } = await runCli([
+      "usage",
+      "summary",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ freeTier?: { api?: string }; usage?: unknown }>(stdout);
+    expect(data.freeTier?.api).toContain("queryFreeTierQuota");
+  });
+
+  test("usage summary --dry-run --workspace-id 附带用量概览计划请求", async () => {
+    const { stdout, stderr, exitCode } = await runCli([
+      "usage",
+      "summary",
+      "--dry-run",
+      "--workspace-id",
+      "ws-e2e-dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{
+      usage?: { api?: string; data?: { reqDTO?: { filterWorkspaceId?: string } } };
+    }>(stdout);
+    expect(data.usage?.api).toContain("getModelUsageStatistic");
+    expect(data.usage?.data?.reqDTO?.filterWorkspaceId).toBe("ws-e2e-dry-run");
+  });
+
+  test("usage summary 文本输出正常返回", async () => {
+    const result = await runCli(["usage", "summary", "--output", "text"]);
+    if (isConsoleAuthFailure(result)) return;
+    expect(result.exitCode, result.stderr).toBe(0);
+  });
+
+  test("usage summary JSON 输出包含 freeTier 字段", async () => {
+    const result = await runCli(["usage", "summary", "--output", "json"]);
+    if (isConsoleAuthFailure(result)) return;
+    expect(result.exitCode, result.stderr).toBe(0);
+    const data = parseStdoutJson<{ freeTier?: unknown; period?: unknown }>(result.stdout);
+    expect(data.period).toBeTypeOf("object");
+    expect(Array.isArray(data.freeTier)).toBe(true);
+  });
+});

packages/cli/tests/e2e/video-generate-i2v.e2e.test.ts

@@ -1,111 +0,0 @@
-import { join } from "node:path";
-import { describe, expect, test } from "vite-plus/test";
-import {
-  cliTimeoutPrefix,
-  e2eLabelFromMetaUrl,
-  isBailianE2EVideoEnabled,
-  isDashScopeE2EReady,
-  makeE2eOutputDir,
-  parseStdoutJson,
-  runCli,
-} from "./helpers.ts";
-
-/**
- * Video generate (i2v)：help / 分组不依赖密钥；长任务需视频 E2E + DashScope。
- */
-
-describe("e2e: video generate (i2v)", () => {
-  test("video 分组展示子命令帮助且成功退出", async () => {
-    const { stdout, stderr, exitCode } = await runCli(["video"]);
-    expect(exitCode, stderr).toBe(0);
-    expect(`${stdout}\n${stderr}`).toMatch(/video|generate|edit|ref|task|download/i);
-  });
-
-  test("video generate --help 正常退出", async () => {
-    const { stderr, exitCode } = await runCli(["video", "generate", "--help"]);
-    expect(exitCode, stderr).toBe(0);
-    expect(stderr).toMatch(/generate|--prompt|--image|model/i);
-  });
-});
-
-describe.skipIf(!isBailianE2EVideoEnabled() || !isDashScopeE2EReady())(
-  "e2e: video generate (i2v)（DashScope 视频）",
-  () => {
-    test("video generate 缺少 --prompt 时报用法错误并退出 (2)", async () => {
-      const { stderr, exitCode } = await runCli([
-        "video",
-        "generate",
-        ...cliTimeoutPrefix(),
-        "--model",
-        "happyhorse-1.1-i2v",
-        "--image",
-        "https://example.com/placeholder.png",
-      ]);
-      expect(exitCode).toBe(2);
-      expect(stderr).toMatch(/--prompt|Usage:/i);
-    });
-
-    test("video generate --dry-run（无 --image）仅输出 request（t2v 路径不调上传）", async () => {
-      const { stdout, stderr, exitCode } = await runCli([
-        "video",
-        "generate",
-        ...cliTimeoutPrefix(),
-        "--dry-run",
-        "--model",
-        "happyhorse-1.1-t2v",
-        "--prompt",
-        "干跑无图",
-        "--output",
-        "json",
-      ]);
-      expect(exitCode, stderr).toBe(0);
-      const data = parseStdoutJson<{ request?: { input?: { prompt?: string; media?: unknown } } }>(
-        stdout,
-      );
-      expect(data.request?.input?.prompt).toBe("干跑无图");
-      expect(data.request?.input?.media).toBeUndefined();
-    });
-
-    test("【happyhorse-1.1-i2v】图片生成视频", async () => {
-      const outDir = makeE2eOutputDir(e2eLabelFromMetaUrl(import.meta.url));
-      const png = join(outDir, "e2e-gen.png");
-      const gen = await runCli([
-        "image",
-        "generate",
-        "--model",
-        "qwen-image-2.0",
-        "--prompt",
-        "一只简笔画小猫，白底",
-        "--out-dir",
-        outDir,
-        "--out-prefix",
-        "e2e-gen",
-        "--output",
-        "json",
-      ]);
-      expect(gen.exitCode, gen.stderr).toBe(0);
-      const genData = parseStdoutJson<{ saved?: string[] }>(gen.stdout);
-      const imagePath = genData.saved?.[0] ?? png;
-
-      const { stdout, stderr, exitCode } = await runCli([
-        "video",
-        "generate",
-        ...cliTimeoutPrefix(),
-        "--model",
-        "happyhorse-1.1-i2v",
-        "--image",
-        imagePath,
-        "--prompt",
-        "镜头缓慢推进，小猫微微动一下",
-        "--download",
-        join(outDir, "e2e-video-i2v.mp4"),
-        "--output",
-        "json",
-      ]);
-      expect(exitCode, stderr).toBe(0);
-      const data = parseStdoutJson<{ status?: string; video_url?: string; saved?: string }>(stdout);
-      expect(data.status).toBe("SUCCEEDED");
-      expect(data.video_url?.startsWith("https://")).toBe(true);
-    }, 3_600_000);
-  },
-);

packages/cli/tests/fixtures/command-pack/commands.mjs

@@ -0,0 +1,58 @@
+const ping = {
+  description: "Ping the Command Pack fixture",
+  auth: "none",
+  flags: {
+    message: {
+      type: "string",
+      valueHint: "<text>",
+      required: true,
+      description: "Message returned by the fixture",
+    },
+  },
+  usageArgs: "--message <text>",
+  exampleArgs: ['--message "hello"'],
+  async run(ctx) {
+    process.stdout.write(`command-pack:${ctx.flags.message}\n`);
+  },
+};
+
+const credential = {
+  description: "Read an API key through the Command Pack host adapter",
+  auth: "apiKey",
+  async run(ctx) {
+    const apiKey = ctx.credentials.apiKey();
+    process.stdout.write(`credential-source:${apiKey.source}\n`);
+  },
+};
+
+const credentialDenied = {
+  description: "Verify credential access also requires command auth",
+  auth: "none",
+  async run(ctx) {
+    ctx.credentials.apiKey();
+  },
+};
+
+const output = {
+  description: "Exercise the Command Pack output helper",
+  auth: "none",
+  async run(ctx) {
+    ctx.output.result({ source: "command-pack", ok: true }, { text: "command-pack-output" });
+  },
+};
+
+const fail = {
+  description: "Exercise the Command Pack semantic error helper",
+  auth: "none",
+  async run(ctx) {
+    throw ctx.errors.usage("Command Pack fixture usage error.", "Use agent fail only in tests.");
+  },
+};
+
+export default {
+  "agent credential": credential,
+  "agent credential-denied": credentialDenied,
+  "agent fail": fail,
+  "agent output": output,
+  "agent ping": ping,
+};

packages/cli/tests/fixtures/command-pack/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@ali/bailian-plugin-agent",
+  "version": "0.0.0-test",
+  "private": true,
+  "type": "module",
+  "bailianCli": {
+    "type": "command-pack",
+    "apiVersion": 1,
+    "entry": "./commands.mjs",
+    "minCliVersion": "1.7.0"
+  }
+}

packages/cli/tests/install-doc.test.ts

@@ -0,0 +1,73 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { credentialFlagDefs, GLOBAL_FLAGS, type AnyCommand } from "bailian-cli-core";
+import { monorepoRoot } from "e2e/monorepo-root";
+import { describe, expect, test } from "vite-plus/test";
+import { commands } from "../src/commands.ts";
+
+const repositoryRoot = monorepoRoot();
+const installGuide = readFileSync(join(repositoryRoot, "INSTALL.md"), "utf8");
+const cliPackage = JSON.parse(
+  readFileSync(join(repositoryRoot, "packages/cli/package.json"), "utf8"),
+) as {
+  engines?: { node?: string };
+};
+
+function toFlagName(key: string): string {
+  return `--${key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}`;
+}
+
+function findDocumentedCommand(snippet: string): {
+  commandPath?: string;
+  command?: AnyCommand;
+} {
+  const argumentText = snippet.slice("bl ".length).trim();
+  const commandPath = Object.keys(commands)
+    .sort((leftPath, rightPath) => rightPath.length - leftPath.length)
+    .find((candidatePath) => {
+      return argumentText === candidatePath || argumentText.startsWith(`${candidatePath} `);
+    });
+
+  return commandPath ? { commandPath, command: commands[commandPath] } : {};
+}
+
+function documentedCommandSnippets(): string[] {
+  const fencedCommands = installGuide
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith("bl "));
+  const inlineCommands = Array.from(installGuide.matchAll(/`(bl [^`\n]+)`/g), (match) => match[1]);
+  return [...new Set([...fencedCommands, ...inlineCommands])];
+}
+
+describe("INSTALL.md", () => {
+  test("发布包 Node.js 要求与安装文档一致", () => {
+    const nodeEngine = cliPackage.engines?.node;
+    expect(nodeEngine).toMatch(/^>=\d+\.\d+\.\d+$/);
+    expect(installGuide).toContain(`要求 **≥ ${nodeEngine?.slice(2)}**`);
+  });
+
+  test("示例只使用当前命令支持的 flags", () => {
+    for (const snippet of documentedCommandSnippets()) {
+      const { commandPath, command } = findDocumentedCommand(snippet);
+      const argumentText = snippet.slice("bl ".length).trim();
+
+      if (!commandPath || !command) {
+        expect(argumentText, `INSTALL.md 中存在未知命令：${snippet}`).toMatch(/^--/);
+      }
+
+      const supportedFlags = {
+        ...GLOBAL_FLAGS,
+        ...(command ? credentialFlagDefs(command) : {}),
+        ...command?.flags,
+      };
+      const supportedFlagNames = new Set(Object.keys(supportedFlags).map(toFlagName));
+      const usedFlagNames = Array.from(snippet.matchAll(/--[a-z0-9-]+/g), (match) => match[0]);
+      const unsupportedFlagNames = usedFlagNames.filter(
+        (flagName) => !supportedFlagNames.has(flagName),
+      );
+
+      expect(unsupportedFlagNames, `INSTALL.md 命令使用了未声明的 flag：${snippet}`).toEqual([]);
+    }
+  });
+});

packages/cli/vite.config.ts

@@ -2,7 +2,7 @@ import { defineConfig } from "vite-plus";
 
 export default defineConfig({
   test: {
-    globalSetup: "./tests/e2e/global-setup.ts",
+    globalSetup: "../e2e/src/global-setup.ts",
     testTimeout: 60_000,
     hookTimeout: 60_000,
   },

packages/commands/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bailian-cli-commands",
-  "version": "1.7.0",
+  "version": "1.12.0",
   "description": "Command library for bailian-cli products (knowledge, memory, media, …). See https://www.npmjs.com/package/bailian-cli for usage.",
   "homepage": "https://bailian.console.aliyun.com/cli",
   "bugs": {
@@ -40,19 +40,22 @@
     "check": "vp check"
   },
   "dependencies": {
+    "@openagentpack/sdk": "0.3.1",
     "bailian-cli-core": "workspace:*",
     "bailian-cli-runtime": "workspace:*",
     "boxen": "catalog:",
     "chalk": "catalog:",
+    "smol-toml": "catalog:",
     "yaml": "catalog:"
   },
   "devDependencies": {
     "@types/node": "catalog:",
     "@typescript/native-preview": "7.0.0-dev.20260328.1",
+    "e2e": "workspace:*",
     "typescript": "^6.0.2",
     "vite-plus": "0.1.22"
   },
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=18.17.0"
   }
 }

packages/commands/src/commands/advisor/recommend.ts

@@ -272,9 +272,7 @@ export default defineCommand({
       return result;
     });
 
-    const analyzeIntentPromise = analyzeIntent(ctx.client, userInput, {
-      intentDetectBaseUrl: settings.intentDetectBaseUrl,
-    }).then((result) => {
+    const analyzeIntentPromise = analyzeIntent(ctx.client, userInput).then((result) => {
       intentReady = true;
       if (!modelsReady) {
         spinner.update("Agent: Intent analyzed, loading model data...");

packages/commands/src/commands/auth/generate-access-token.ts

@@ -0,0 +1,50 @@
+import {
+  defineCommand,
+  detectOutputFormat,
+  generateCLIAccessToken,
+  type FlagsDef,
+} from "bailian-cli-core";
+import { emitResult } from "bailian-cli-runtime";
+
+const FLAGS = {
+  accessKeyId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Alibaba Cloud Access Key ID",
+    required: true,
+  },
+  accessKeySecret: {
+    type: "string",
+    valueHint: "<secret>",
+    description: "Alibaba Cloud Access Key Secret",
+    required: true,
+  },
+  securityToken: {
+    type: "string",
+    valueHint: "<token>",
+    description: "Alibaba Cloud STS Security Token to store (optional)",
+  },
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Generate a CLI access token using OpenAPI AK/SK",
+  auth: "none",
+  usageArgs: "--access-key-id <id> --access-key-secret <secret> --security-token <token>",
+  flags: FLAGS,
+  exampleArgs: ["--access-key-id LTAIxxxxx --access-key-secret xxxxx --security-token <token>"],
+  async run(ctx) {
+    const { identity, settings, flags } = ctx;
+    const format = detectOutputFormat(settings.output);
+
+    const resp = await generateCLIAccessToken({
+      identity,
+      settings,
+      baseUrl: ctx.client.baseUrl,
+      accessKeyId: flags.accessKeyId,
+      accessKeySecret: flags.accessKeySecret,
+      securityToken: flags.securityToken || undefined,
+    });
+
+    emitResult(resp, format);
+  },
+});

packages/commands/src/commands/auth/login-api-key.ts

@@ -0,0 +1,99 @@
+import {
+  BailianError,
+  ExitCode,
+  chatPath,
+  requestJson,
+  normalizeModelBaseUrl,
+  type AuthPersistPatch,
+  type AuthStore,
+  type Identity,
+  type Settings,
+} from "bailian-cli-core";
+
+interface ApiKeyLoginDeps {
+  identity: Identity;
+  settings: Settings;
+  authStore: AuthStore;
+}
+
+interface ApiKeyLoginProfile {
+  baseUrl: string;
+  persistBaseUrl?: string;
+  defaultTextModel?: string;
+  defaultVideoModel?: string;
+  defaultImageToVideoModel?: string;
+  defaultReferenceToVideoModel?: string;
+  defaultImageModel?: string;
+  persistPatch?: AuthPersistPatch;
+}
+
+const RETRY_DELAY_BASE_MS = 500;
+
+function canRetry(error: unknown): boolean {
+  if (error instanceof BailianError) {
+    if (error.exitCode === ExitCode.NETWORK || error.exitCode === ExitCode.TIMEOUT) return true;
+    const status = error.api?.httpStatus;
+    return status === 401 || (status !== undefined && status >= 500);
+  }
+  if (error instanceof Error) {
+    return (
+      error.name === "AbortError" ||
+      error.name === "TimeoutError" ||
+      error.message.includes("timed out") ||
+      error.message === "fetch failed"
+    );
+  }
+  return false;
+}
+
+export async function validateAndPersistApiKey(
+  deps: ApiKeyLoginDeps,
+  key: string,
+  profile: ApiKeyLoginProfile,
+): Promise<void> {
+  process.stderr.write("Testing key... ");
+  const httpDeps = { identity: deps.identity, settings: deps.settings };
+  const baseUrl = normalizeModelBaseUrl(profile.baseUrl);
+  const persistBaseUrl = profile.persistBaseUrl
+    ? normalizeModelBaseUrl(profile.persistBaseUrl)
+    : undefined;
+  const validationModel = "qwen3.7-max";
+  const requestOpts = {
+    url: baseUrl + chatPath(),
+    method: "POST",
+    headers: { Authorization: `Bearer ${key}` },
+    timeout: Math.min(deps.settings.timeout, 30),
+    body: {
+      model: validationModel,
+      messages: [{ role: "user", content: "hi" }],
+      max_tokens: 1,
+      stream: false,
+    },
+  };
+
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    try {
+      await requestJson<unknown>(httpDeps, requestOpts);
+      break;
+    } catch (error) {
+      if (attempt >= 3 || !canRetry(error)) {
+        process.stderr.write("Failed\n");
+        throw error;
+      }
+      const delayMs = RETRY_DELAY_BASE_MS * 2 ** (attempt - 1);
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+
+  process.stderr.write("Valid\n");
+  await deps.authStore.login({
+    ...profile.persistPatch,
+    api_key: key,
+    base_url: persistBaseUrl,
+    default_text_model: profile.defaultTextModel,
+    default_video_model: profile.defaultVideoModel,
+    default_image_to_video_model: profile.defaultImageToVideoModel,
+    default_reference_to_video_model: profile.defaultReferenceToVideoModel,
+    default_image_model: profile.defaultImageModel,
+  });
+}

packages/commands/src/commands/auth/login-console.ts

@@ -1,18 +1,17 @@
-import { execFile } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import http from "node:http";
 
 import {
   BailianError,
   ExitCode,
-  chatPath,
-  getConfigPath,
-  requestJson,
+  type AuthPersistPatch,
   type AuthStore,
   type ConfigFile,
   type Identity,
   type Settings,
 } from "bailian-cli-core";
+import { listenLocalServer, openInBrowser } from "../shared/local-server.ts";
+import { validateAndPersistApiKey } from "./login-api-key.ts";
 
 /** 登录流程的能力面:身份(UA)、有效配置(timeout 等)、auth 域落盘。 */
 export interface LoginDeps {
@@ -23,6 +22,9 @@ export interface LoginDeps {
 
 const CONSOLE_LOGIN_TIMEOUT_MS = 15 * 60 * 1000;
 const MAX_AUTH_CALLBACK_BODY = 65536;
+// Regex for double newline (\r\n\r\n or \n\n); built via RegExp to avoid
+// literal multi-line splitting in source.
+const REGEX_DOUBLE_NEWLINE = new RegExp("\r\n\r\n|\n\n");
 
 const CONSOLE_ORIGINS: Record<string, string> = {
   domestic: "https://bailian.console.aliyun.com",
@@ -76,7 +78,7 @@ function parseAccessTokenFromMultipart(raw: string, boundaryValue: string): stri
   for (let i = 1; i < segments.length; i++) {
     const part = segments[i]!;
     if (!/name\s*=\s*["'](?:access_token|accessToken)["']/i.test(part)) continue;
-    const sep = part.match(/\r\n\r\n|\n\n/);
+    const sep = part.match(REGEX_DOUBLE_NEWLINE);
     if (!sep || sep.index === undefined) continue;
     let value = part.slice(sep.index + sep[0].length);
     value = value
@@ -359,90 +361,7 @@ async function extractCredentialsFromRequest(
 }
 
 function listenServerOnFreeLocalPort(server: http.Server): Promise<number> {
-  return new Promise((resolve, reject) => {
-    const onErr = (e: Error) => reject(e);
-    server.once("error", onErr);
-    server.listen({ port: 0, host: "127.0.0.1", exclusive: true }, () => {
-      server.off("error", onErr);
-      const addr = server.address();
-      if (!addr || typeof addr === "string") {
-        reject(new Error("Expected TCP socket address"));
-        return;
-      }
-      resolve(addr.port);
-    });
-  });
-}
-
-function openInBrowser(url: string): Promise<void> {
-  const platform = process.platform;
-  const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
-  const args = platform === "win32" ? ["/c", "start", "", url] : [url];
-
-  return new Promise((resolve, reject) => {
-    execFile(cmd, args, { windowsHide: true }, (err) => {
-      if (err) reject(err);
-      else resolve();
-    });
-  });
-}
-
-const RETRY_DELAY_BASE_MS = 500;
-
-function canRetry(err: unknown): boolean {
-  if (err instanceof BailianError) {
-    if (err.exitCode === ExitCode.NETWORK || err.exitCode === ExitCode.TIMEOUT) return true;
-    const status = err.api?.httpStatus;
-    return status === 401 || (status !== undefined && status >= 500);
-  }
-  if (err instanceof Error) {
-    return (
-      err.name === "AbortError" ||
-      err.name === "TimeoutError" ||
-      err.message.includes("timed out") ||
-      err.message === "fetch failed"
-    );
-  }
-  return false;
-}
-
-export async function validateAndPersistApiKey(
-  deps: LoginDeps,
-  key: string,
-  baseUrl: string,
-): Promise<void> {
-  process.stderr.write("Testing key... ");
-  const httpDeps = { identity: deps.identity, settings: deps.settings };
-  const requestOpts = {
-    url: baseUrl + chatPath(),
-    method: "POST",
-    headers: { Authorization: `Bearer ${key}` },
-    timeout: Math.min(deps.settings.timeout, 30),
-    body: {
-      model: "qwen3.7-max",
-      messages: [{ role: "user", content: "hi" }],
-      max_tokens: 1,
-    },
-  };
-
-  for (let attempt = 1; attempt <= 3; attempt++) {
-    try {
-      await requestJson<unknown>(httpDeps, requestOpts);
-      break;
-    } catch (err) {
-      if (attempt >= 3 || !canRetry(err)) {
-        process.stderr.write("Failed\n");
-        throw new BailianError("API key validation failed", ExitCode.AUTH, "Invalid API key.", {
-          cause: err,
-        });
-      }
-      const delayMs = RETRY_DELAY_BASE_MS * 2 ** (attempt - 1);
-      await new Promise((resolve) => setTimeout(resolve, delayMs));
-    }
-  }
-
-  process.stderr.write("Valid\n");
-  await deps.authStore.login({ api_key: key });
+  return listenLocalServer(server);
 }
 
 export async function runConsoleLogin(
@@ -486,20 +405,27 @@ export async function runConsoleLogin(
 
       if (hasConfig || apiKey) {
         try {
-          if (hasConfig) {
-            await deps.authStore.login({
-              access_token: accessToken || undefined,
-              base_url: baseUrl || undefined,
-              console_site: (consoleSite || undefined) as ConfigFile["console_site"],
-              console_region: consoleRegion || undefined,
-              console_switch_agent: consoleSwitchAgent ? Number(consoleSwitchAgent) : undefined,
-              workspace_id: workspaceId || undefined,
-            });
-            process.stderr.write(`Config saved to ${getConfigPath()}\n`);
-          }
+          const callbackPatch: AuthPersistPatch = {
+            access_token: accessToken || undefined,
+            console_site: (consoleSite || undefined) as ConfigFile["console_site"],
+            console_region: consoleRegion || undefined,
+            console_switch_agent: consoleSwitchAgent ? Number(consoleSwitchAgent) : undefined,
+            workspace_id: workspaceId || undefined,
+          };
           if (apiKey) {
             const testBaseUrl = baseUrl || deps.authStore.resolveBaseUrl();
-            await validateAndPersistApiKey(deps, apiKey, testBaseUrl);
+            await validateAndPersistApiKey(deps, apiKey, {
+              baseUrl: testBaseUrl,
+              persistBaseUrl: baseUrl || undefined,
+              persistPatch: callbackPatch,
+            });
+            process.stderr.write(`Config saved to ${deps.authStore.path}\n`);
+          } else if (hasConfig) {
+            await deps.authStore.login({
+              ...callbackPatch,
+              base_url: baseUrl || undefined,
+            });
+            process.stderr.write(`Config saved to ${deps.authStore.path}\n`);
           }
         } catch (err: unknown) {
           callbackError = err;

packages/commands/src/commands/auth/login.ts

@@ -1,10 +1,12 @@
-import { defineCommand, getConfigPath } from "bailian-cli-core";
-import { emitBare } from "bailian-cli-runtime";
 import {
-  resolveConsoleOrigin,
-  runConsoleLogin,
-  validateAndPersistApiKey,
-} from "./login-console.ts";
+  defineCommand,
+  generateCLIAccessToken,
+  getModelProfilePreset,
+  normalizeModelBaseUrl,
+} from "bailian-cli-core";
+import { emitBare } from "bailian-cli-runtime";
+import { validateAndPersistApiKey } from "./login-api-key.ts";
+import { resolveConsoleOrigin, runConsoleLogin } from "./login-console.ts";
 
 const LOGIN_MODE_HINT = "Choose exactly one login mode: --api-key, --console, or --open-api";
 
@@ -19,11 +21,15 @@ export default defineCommand({
   usageArgs:
     "--api-key <key> | --console | --open-api --access-key-id <id> --access-key-secret <secret>",
   flags: {
-    apiKey: { type: "string", valueHint: "<key>", description: "DashScope API key to store" },
+    apiKey: {
+      type: "string",
+      valueHint: "<key>",
+      description: "Model API key to store",
+    },
     baseUrl: {
       type: "string",
       valueHint: "<url>",
-      description: "DashScope API base URL (used with --api-key for validation)",
+      description: "Model API base URL (used with --api-key for validation)",
     },
     console: {
       type: "switch",
@@ -52,6 +58,7 @@ export default defineCommand({
   },
   exampleArgs: [
     "--api-key sk-xxxxx",
+    "--config token-plan --api-key sk-sp-xxxxx",
     "--console",
     "--open-api --access-key-id LTAIxxxxx --access-key-secret xxxxx",
   ],
@@ -87,10 +94,10 @@ export default defineCommand({
   },
   async run(ctx) {
     const { identity, settings, flags } = ctx;
-    const store = ctx.authStore();
+    const store = ctx.authStore;
     const deps = { identity, settings, authStore: store };
     const key = flags.apiKey;
-    const baseUrl = flags.baseUrl || undefined;
+    const baseUrl = flags.baseUrl ? normalizeModelBaseUrl(flags.baseUrl) : undefined;
 
     if (flags.console) {
       if (settings.dryRun) {
@@ -110,14 +117,25 @@ export default defineCommand({
 
     if (flags.openApi) {
       if (settings.dryRun) {
-        emitBare("Would save OpenAPI AK/SK credentials.");
+        emitBare("Would save OpenAPI AK/SK credentials and generate CLI access token.");
         return;
       }
+      const resolvedBaseUrl = store.resolveBaseUrl();
+      process.stderr.write("Generating CLI access token... ");
+      const resp = await generateCLIAccessToken({
+        identity,
+        settings,
+        baseUrl: resolvedBaseUrl,
+        accessKeyId: flags.accessKeyId!,
+        accessKeySecret: flags.accessKeySecret!,
+      });
+      const accessToken = resp.cliAccessToken;
       await store.login({
         access_key_id: flags.accessKeyId,
         access_key_secret: flags.accessKeySecret,
+        access_token: accessToken,
       });
-      process.stderr.write(`OpenAPI credentials saved to ${getConfigPath()}\n`);
+      process.stderr.write(`OpenAPI credentials saved to ${store.path}\n`);
       return;
     }
 
@@ -128,9 +146,18 @@ export default defineCommand({
       emitBare("Would validate and save API key.");
       return;
     }
-    if (baseUrl) {
-      await store.login({ base_url: baseUrl });
-    }
-    await validateAndPersistApiKey(deps, key, baseUrl || store.resolveBaseUrl());
+    const profilePreset = getModelProfilePreset(settings.configName);
+    const storedBaseUrl = store.stored().baseUrl;
+    const resolvedBaseUrl = baseUrl || store.resolveBaseUrl(profilePreset?.baseUrl);
+    const persistBaseUrl = baseUrl || (!storedBaseUrl ? profilePreset?.baseUrl : undefined);
+    await validateAndPersistApiKey(deps, key, {
+      baseUrl: resolvedBaseUrl,
+      persistBaseUrl,
+      defaultTextModel: profilePreset?.defaultTextModel,
+      defaultVideoModel: profilePreset?.defaultVideoModel,
+      defaultImageToVideoModel: profilePreset?.defaultImageToVideoModel,
+      defaultReferenceToVideoModel: profilePreset?.defaultReferenceToVideoModel,
+      defaultImageModel: profilePreset?.defaultImageModel,
+    });
   },
 });

packages/commands/src/commands/auth/logout.ts

@@ -1,8 +1,8 @@
-import { defineCommand, getConfigPath } from "bailian-cli-core";
+import { defineCommand } from "bailian-cli-core";
 import { emitBare } from "bailian-cli-runtime";
 
 export default defineCommand({
-  description: "Clear stored credentials",
+  description: "Clear stored credentials; full logout also clears the model Base URL",
   auth: "none",
   usageArgs: "[--console | --open-api] [--dry-run]",
   flags: {
@@ -12,7 +12,7 @@ export default defineCommand({
     },
     openApi: {
       type: "switch",
-      description: "Only clear OpenAPI AK/SK credentials, keep other credentials intact",
+      description: "Only clear OpenAPI AK/SK/STS credentials, keep other credentials intact",
     },
   },
   exampleArgs: ["", "--console", "--open-api", "--dry-run"],
@@ -20,18 +20,18 @@ export default defineCommand({
     f.console && f.openApi ? "Use only one scope: --console or --open-api" : undefined,
   async run(ctx) {
     const { settings, flags } = ctx;
-    const store = ctx.authStore();
+    const store = ctx.authStore;
     const stored = store.stored();
 
     if (flags.console) {
       if (settings.dryRun) {
-        if (stored.console) emitBare("Would clear access_token from ~/.bailian/config.json");
+        if (stored.console) emitBare(`Would clear access_token from ${store.path}`);
         else emitBare("No console access_token to clear.");
         emitBare("No changes made.");
         return;
       }
       if (await store.logout("console")) {
-        process.stderr.write(`Cleared access_token from ${getConfigPath()}\n`);
+        process.stderr.write(`Cleared access_token from ${store.path}\n`);
         if (stored.apiKey) {
           process.stderr.write(
             "api_key is still configured and will be used for authentication.\n",
@@ -46,13 +46,17 @@ export default defineCommand({
     if (flags.openApi) {
       if (settings.dryRun) {
         if (stored.openapi)
-          emitBare("Would clear access_key_id / access_key_secret from ~/.bailian/config.json");
+          emitBare(
+            `Would clear access_key_id / access_key_secret / security_token from ${store.path}`,
+          );
         else emitBare("No OpenAPI AK/SK credentials to clear.");
         emitBare("No changes made.");
         return;
       }
       if (await store.logout("openapi")) {
-        process.stderr.write(`Cleared access_key_id / access_key_secret from ${getConfigPath()}\n`);
+        process.stderr.write(
+          `Cleared access_key_id / access_key_secret / security_token from ${store.path}\n`,
+        );
         if (stored.apiKey || stored.console) {
           process.stderr.write(
             "Other credentials are still configured and will be used for authentication.\n",
@@ -64,24 +68,24 @@ export default defineCommand({
       return;
     }
 
-    const hasKey = stored.apiKey || stored.console || stored.openapi;
+    const hasStoredAuth = stored.apiKey || stored.console || stored.openapi || !!stored.baseUrl;
 
     if (settings.dryRun) {
-      if (hasKey)
+      if (hasStoredAuth)
         emitBare(
-          "Would clear api_key / access_token / access_key_id / access_key_secret from ~/.bailian/config.json",
+          `Would clear api_key / base_url / access_token / access_key_id / access_key_secret / security_token from ${store.path}`,
         );
-      else emitBare("No credentials to clear.");
+      else emitBare("No credentials or model Base URL to clear.");
       emitBare("No changes made.");
       return;
     }
 
     if (await store.logout("all")) {
       process.stderr.write(
-        "Cleared api_key / access_token / access_key_id / access_key_secret from ~/.bailian/config.json\n",
+        `Cleared api_key / base_url / access_token / access_key_id / access_key_secret / security_token from ${store.path}\n`,
       );
     } else {
-      process.stderr.write("No credentials to clear.\n");
+      process.stderr.write("No credentials or model Base URL to clear.\n");
     }
   },
 });

packages/commands/src/commands/auth/status.ts

@@ -9,7 +9,7 @@ export default defineCommand({
   async run(ctx) {
     const { identity, settings } = ctx;
     const format = detectOutputFormat(settings.output);
-    const auth = ctx.authStore().describe();
+    const auth = ctx.authStore.describe();
 
     const apiKey = auth.apiKey
       ? {
@@ -35,11 +35,15 @@ export default defineCommand({
       : undefined;
 
     const authenticated = !!(apiKey || consoleCred || openapi);
+    const configName = settings.configName ?? "default";
+    const configFile = ctx.authStore.path;
 
     if (!authenticated) {
       emitResult(
         {
           authenticated: false,
+          config: configName,
+          config_file: configFile,
           message: "Not authenticated.",
           hint: [
             `API key (model):   ${identity.binName} auth login --api-key <key> or DASHSCOPE_API_KEY`,
@@ -54,10 +58,22 @@ export default defineCommand({
     }
 
     if (format !== "text") {
-      emitResult({ authenticated: true, api_key: apiKey, console: consoleCred, openapi }, format);
+      emitResult(
+        {
+          authenticated: true,
+          config: configName,
+          config_file: configFile,
+          api_key: apiKey,
+          console: consoleCred,
+          openapi,
+        },
+        format,
+      );
       return;
     }
 
+    emitBare(`Config: ${configName}`);
+    emitBare(`Config file: ${configFile}`);
     emitBare("Authentication Status:");
     if (apiKey) {
       emitBare(`  API key (model):  ${apiKey.source}  ${apiKey.masked}`);

packages/commands/src/commands/config/agent/decode-key.ts

@@ -0,0 +1,153 @@
+import { BailianError, ExitCode } from "bailian-cli-core";
+
+/**
+ * Decoder for the obfuscated API key ("o1_…") produced by the Model Studio web
+ * console. Ported verbatim from the frontend `encodeTokenPlanKey` counterpart:
+ * token = "o1_" + salt(6) + feistel-obfuscated payload + crc32 checksum(6),
+ * all over a 65-character alphabet. Pure logic, no dependencies; the CLI only
+ * ever needs the decode direction.
+ */
+
+const TOKEN_PREFIX = "o1_";
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_.";
+const ALPHABET_SIZE = ALPHABET.length;
+const ALPHABET_INDEX = new Map(ALPHABET.split("").map((character, index) => [character, index]));
+const KEY_PATTERN = /^[A-Za-z0-9._-]+$/;
+const SALT_LENGTH = 6;
+const CHECKSUM_LENGTH = 6;
+const FEISTEL_ROUNDS = 8;
+
+function invalidCredential(): BailianError {
+  return new BailianError(
+    "Invalid obfuscated API key.",
+    ExitCode.USAGE,
+    '--key expects the obfuscated key copied from the web console (starts with "o1_").',
+  );
+}
+
+function toDigits(value: string): number[] {
+  const digits: number[] = [];
+  for (const character of value) {
+    const digit = ALPHABET_INDEX.get(character);
+    if (digit === undefined) throw invalidCredential();
+    digits.push(digit);
+  }
+  return digits;
+}
+
+function fromDigits(digits: number[]): string {
+  return digits.map((digit) => ALPHABET[digit]).join("");
+}
+
+function mixState(state: number, value: number): number {
+  return Math.imul((state ^ value) >>> 0, 0x01000193) >>> 0;
+}
+
+function nextState(state: number): number {
+  let next = state >>> 0;
+  next ^= next << 13;
+  next ^= next >>> 17;
+  next ^= next << 5;
+  return next >>> 0;
+}
+
+function createRoundMask(right: number[], salt: string, round: number, length: number): number[] {
+  let state = (0x811c9dc5 ^ Math.imul(round + 1, 0x9e3779b1)) >>> 0;
+
+  state = mixState(state, right.length);
+  state = mixState(state, length);
+  for (const character of salt) {
+    state = mixState(state, (ALPHABET_INDEX.get(character) ?? -1) + 1);
+  }
+  for (const digit of right) {
+    state = mixState(state, digit + 1);
+  }
+
+  state ^= state >>> 16;
+  state = Math.imul(state, 0x85ebca6b) >>> 0;
+  state ^= state >>> 13;
+  state = Math.imul(state, 0xc2b2ae35) >>> 0;
+  state ^= state >>> 16;
+  state = state >>> 0 || 0x6d2b79f5;
+
+  const mask: number[] = [];
+  for (let index = 0; index < length; index += 1) {
+    state = (state + Math.imul(index + 1, 0x9e3779b1)) >>> 0;
+    state = nextState(state);
+    mask.push(state % ALPHABET_SIZE);
+  }
+  return mask;
+}
+
+function deobfuscatePayload(payload: string, salt: string): string {
+  const digits = toDigits(payload);
+  const midpoint = Math.floor(digits.length / 2);
+  let left = digits.slice(0, midpoint);
+  let right = digits.slice(midpoint);
+
+  for (let round = FEISTEL_ROUNDS - 1; round >= 0; round -= 1) {
+    const previousRight = left;
+    const mask = createRoundMask(previousRight, salt, round, right.length);
+    const previousLeft = right.map(
+      (digit, index) => (digit - mask[index] + ALPHABET_SIZE) % ALPHABET_SIZE,
+    );
+    left = previousLeft;
+    right = previousRight;
+  }
+
+  return fromDigits([...left, ...right]);
+}
+
+function crc32(value: string): number {
+  let checksum = 0xffffffff;
+  for (let index = 0; index < value.length; index += 1) {
+    checksum ^= value.charCodeAt(index);
+    for (let bit = 0; bit < 8; bit += 1) {
+      const mask = -(checksum & 1);
+      checksum = (checksum >>> 1) ^ (0xedb88320 & mask);
+    }
+  }
+  return (checksum ^ 0xffffffff) >>> 0;
+}
+
+function encodeBase65Number(value: number, length: number): string {
+  let remaining = value >>> 0;
+  const encoded = Array<string>(length).fill(ALPHABET[0]);
+
+  for (let index = length - 1; index >= 0; index -= 1) {
+    encoded[index] = ALPHABET[remaining % ALPHABET_SIZE];
+    remaining = Math.floor(remaining / ALPHABET_SIZE);
+  }
+  if (remaining !== 0) throw invalidCredential();
+  return encoded.join("");
+}
+
+function validateSalt(salt: string): void {
+  if (salt.length !== SALT_LENGTH || !KEY_PATTERN.test(salt)) {
+    throw invalidCredential();
+  }
+}
+
+/** Decode an "o1_…" obfuscated token back into the plain API key. */
+export function decodeTokenPlanKey(token: string): string {
+  const minimumLength = TOKEN_PREFIX.length + SALT_LENGTH + CHECKSUM_LENGTH + 1;
+  if (token.length < minimumLength || !token.startsWith(TOKEN_PREFIX)) {
+    throw invalidCredential();
+  }
+
+  const body = token.slice(TOKEN_PREFIX.length);
+  if (!KEY_PATTERN.test(body)) throw invalidCredential();
+
+  const salt = body.slice(0, SALT_LENGTH);
+  const payload = body.slice(SALT_LENGTH, -CHECKSUM_LENGTH);
+  const checksum = body.slice(-CHECKSUM_LENGTH);
+  validateSalt(salt);
+  if (!payload) throw invalidCredential();
+
+  const apiKey = deobfuscatePayload(payload, salt);
+  if (!KEY_PATTERN.test(apiKey)) throw invalidCredential();
+
+  const expectedChecksum = encodeBase65Number(crc32(apiKey), CHECKSUM_LENGTH);
+  if (checksum !== expectedChecksum) throw invalidCredential();
+  return apiKey;
+}

packages/commands/src/commands/config/agent/index.ts

@@ -0,0 +1,128 @@
+import { platform } from "os";
+import { defineCommand, detectOutputFormat, maskToken, type FlagsDef } from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import { AGENTS, VALID_AGENT_NAMES, type WriteParams } from "./writers.ts";
+import { decodeTokenPlanKey } from "./decode-key.ts";
+import { resolveRegionBaseUrl } from "./writers/utils.ts";
+
+const FLAGS = {
+  agent: {
+    type: "string",
+    valueHint: "<name>",
+    description: `Target agent: ${VALID_AGENT_NAMES.join(", ")}`,
+    required: true,
+    choices: VALID_AGENT_NAMES,
+  },
+  baseUrl: {
+    type: "string",
+    valueHint: "<url>",
+    description: "API base URL",
+  },
+  region: {
+    type: "string",
+    valueHint: "<region>",
+    description:
+      "Model Studio region (e.g. cn-beijing, ap-southeast-1); converted into --base-url. Token Plan only",
+  },
+  apiKey: {
+    type: "string",
+    valueHint: "<key>",
+    description: "API key",
+  },
+  key: {
+    type: "string",
+    valueHint: "<encoded>",
+    description:
+      'Obfuscated API key from the web console (starts with "o1_"); decoded into --api-key',
+  },
+  model: {
+    type: "string",
+    valueHint: "<model>",
+    description: "Default model name",
+    required: true,
+  },
+  contextWindow: {
+    type: "number",
+    valueHint: "<tokens>",
+    description: "OpenClaw only: model context window in tokens (default: 256000)",
+  },
+  wireApi: {
+    type: "string",
+    valueHint: "<api>",
+    description:
+      'Codex only: wire protocol (default: responses). "chat" only works with legacy Codex <= 0.80.0',
+    choices: ["chat", "responses"],
+  },
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Configure a coding agent to use DashScope API",
+  auth: "none",
+  usageArgs:
+    "--agent <name> (--base-url <url> | --region <region>) (--api-key <key> | --key <encoded>) --model <model>",
+  flags: FLAGS,
+  exampleArgs: [
+    "--agent claude-code --base-url https://dashscope.aliyuncs.com/apps/anthropic --api-key sk-xxxxx --model qwen3-max",
+    "--agent qwen-code --base-url https://dashscope.aliyuncs.com/compatible-mode/v1 --api-key sk-xxxxx --model qwen3-coder-plus",
+    "--agent codex --base-url https://dashscope.aliyuncs.com/compatible-mode/v1 --api-key sk-xxxxx --model qwen3-coder-plus",
+  ],
+  validate(flags) {
+    if (!flags.baseUrl && !flags.region) return "one of --base-url or --region is required";
+    if (flags.baseUrl && flags.region) return "--base-url and --region are mutually exclusive";
+    if (!flags.apiKey && !flags.key) return "one of --api-key or --key is required";
+    if (flags.apiKey && flags.key) return "--api-key and --key are mutually exclusive";
+    return undefined;
+  },
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const agentName = flags.agent;
+    const { model, contextWindow, wireApi } = flags;
+    // --region is a Token Plan convenience: convert it into a base URL and use
+    // it exactly as --base-url would be.
+    const baseUrl = flags.region ? resolveRegionBaseUrl(flags.region) : flags.baseUrl!;
+    // --key carries the web console's obfuscated form; decode it up front so
+    // even --dry-run validates the token.
+    const apiKey = flags.key ? decodeTokenPlanKey(flags.key) : flags.apiKey!;
+    const agentDef = AGENTS[agentName];
+    const format = detectOutputFormat(settings.output);
+
+    // Hermes has no native Windows support.
+    if (agentName === "hermes" && platform() === "win32") {
+      process.stderr.write(
+        "Warning: Hermes Agent does not support native Windows. Please use WSL2.\n",
+      );
+    }
+
+    if (settings.dryRun) {
+      emitResult(
+        {
+          agent: agentName,
+          label: agentDef.label,
+          base_url: baseUrl,
+          api_key: maskToken(apiKey),
+          model,
+        },
+        format,
+      );
+      return;
+    }
+
+    const params: WriteParams = {
+      baseUrl,
+      apiKey,
+      model,
+      contextWindow,
+      wireApi,
+    };
+    const summary = agentDef.write(params);
+
+    if (!settings.quiet) {
+      emitBare(`${agentDef.label} configured successfully.`);
+      for (const path of summary.paths) emitBare(`  Written: ${path}`);
+      emitBare(`  ${summary.nextStep}`);
+      for (const warning of summary.warnings ?? []) {
+        process.stderr.write(`Warning: ${warning}\n`);
+      }
+    }
+  },
+});

packages/commands/src/commands/config/agent/writers.ts

@@ -0,0 +1,20 @@
+export type { WriteParams, WriteSummary, AgentDef } from "./writers/utils.ts";
+
+import type { AgentDef } from "./writers/utils.ts";
+import claudeCode from "./writers/claude-code.ts";
+import qwenCode from "./writers/qwen-code.ts";
+import opencode from "./writers/opencode.ts";
+import openclaw from "./writers/openclaw.ts";
+import hermes from "./writers/hermes.ts";
+import codex from "./writers/codex.ts";
+
+export const AGENTS: Record<string, AgentDef> = {
+  "claude-code": claudeCode,
+  "qwen-code": qwenCode,
+  opencode,
+  openclaw,
+  hermes,
+  codex,
+};
+
+export const VALID_AGENT_NAMES = Object.keys(AGENTS) as [string, ...string[]];

packages/commands/src/commands/config/agent/writers/claude-code.ts

@@ -0,0 +1,68 @@
+import { homedir } from "os";
+import { join } from "path";
+import {
+  backup,
+  readJson,
+  writeJsonAtomic,
+  resolveClaudeCodeBaseUrl,
+  type AgentDef,
+} from "./utils.ts";
+
+/** Fill a tier/default model env only when the user has not set it yet. */
+function setModelEnvIfAbsent(env: Record<string, string>, key: string, model: string): void {
+  const current = env[key];
+  if (current === undefined || current.trim() === "") {
+    env[key] = model;
+  }
+}
+
+export default {
+  label: "Claude Code",
+  write({ baseUrl, apiKey, model }) {
+    // Claude Code honors CLAUDE_CONFIG_DIR for its settings location.
+    const configDir = process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+    const settingsPath = join(configDir, "settings.json");
+    const onboardingPath = join(homedir(), ".claude.json");
+    const warnings: string[] = [];
+
+    const resolved = resolveClaudeCodeBaseUrl(baseUrl);
+    if (resolved.rewrittenFrom) {
+      warnings.push(
+        `Rewrote base URL for Claude Code: "${resolved.rewrittenFrom}" → "${resolved.url}" ` +
+          `(Claude Code needs /apps/anthropic, not OpenAI compatible-mode).`,
+      );
+    }
+
+    // settings.json — merge env. Base URL + auth token connect Claude Code to
+    // the Anthropic-compatible endpoint; primary model always updates, while
+    // tier/subagent defaults are filled only when absent so existing setups
+    // (e.g. Token Plan Haiku/Subagent splits) are not wiped.
+    backup(settingsPath);
+    const settings = readJson(settingsPath);
+    const env = (settings.env ?? {}) as Record<string, string>;
+    env.ANTHROPIC_BASE_URL = resolved.url;
+    env.ANTHROPIC_AUTH_TOKEN = apiKey;
+    // AUTH_TOKEN and API_KEY are mutually exclusive credential fields — drop a
+    // stale ANTHROPIC_API_KEY so it cannot shadow the token we just wrote.
+    delete env.ANTHROPIC_API_KEY;
+    env.ANTHROPIC_MODEL = model;
+    setModelEnvIfAbsent(env, "ANTHROPIC_DEFAULT_HAIKU_MODEL", model);
+    setModelEnvIfAbsent(env, "ANTHROPIC_DEFAULT_SONNET_MODEL", model);
+    setModelEnvIfAbsent(env, "ANTHROPIC_DEFAULT_OPUS_MODEL", model);
+    setModelEnvIfAbsent(env, "CLAUDE_CODE_SUBAGENT_MODEL", model);
+    settings.env = env;
+    writeJsonAtomic(settingsPath, settings);
+
+    // .claude.json — skip the onboarding prompt on first launch.
+    backup(onboardingPath);
+    const onboarding = readJson(onboardingPath);
+    onboarding.hasCompletedOnboarding = true;
+    writeJsonAtomic(onboardingPath, onboarding);
+
+    return {
+      paths: [settingsPath, onboardingPath],
+      nextStep: "Run `claude` to start using Claude Code with DashScope.",
+      warnings: warnings.length > 0 ? warnings : undefined,
+    };
+  },
+} satisfies AgentDef;

packages/commands/src/commands/config/agent/writers/codex.ts

@@ -0,0 +1,72 @@
+import { homedir } from "os";
+import { join } from "path";
+import { existsSync, readFileSync } from "fs";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+import { backup, readJson, writeJsonAtomic, writeTextAtomic, type AgentDef } from "./utils.ts";
+
+const PROVIDER_KEY = "bailian-cli";
+
+export default {
+  label: "Codex",
+  write({ baseUrl, apiKey, model, wireApi: wireApiParam }) {
+    const configPath = join(homedir(), ".codex", "config.toml");
+    const warnings: string[] = [];
+
+    // config.toml — merge into existing config so unrelated settings
+    // (mcp_servers, approval_policy, other providers, ...) are preserved.
+    backup(configPath);
+    let config: Record<string, unknown> = {};
+    if (existsSync(configPath)) {
+      try {
+        config = parseToml(readFileSync(configPath, "utf-8")) as Record<string, unknown>;
+      } catch {
+        config = {};
+      }
+    }
+
+    config.model_provider = PROVIDER_KEY;
+    config.model = model;
+
+    // wire_api — current Codex releases only load `wire_api = "responses"`
+    // ("chat" is rejected at config load, see openai/codex discussion #7782).
+    // "chat" remains an explicit opt-in for users pinned to legacy Codex
+    // <= 0.80.0 (the Model Studio path for models without Responses support).
+    const wireApi = wireApiParam === "chat" ? "chat" : "responses";
+    if (wireApi === "chat") {
+      warnings.push(
+        'Current Codex releases refuse to load `wire_api = "chat"`; ' +
+          "only use --wire-api chat with legacy Codex <= 0.80.0 " +
+          "(e.g. `npm install -g @openai/codex@0.80.0`).",
+      );
+    }
+
+    const providers = (config.model_providers ?? {}) as Record<string, unknown>;
+    const existing = (providers[PROVIDER_KEY] ?? {}) as Record<string, unknown>;
+    providers[PROVIDER_KEY] = {
+      ...existing,
+      name: PROVIDER_KEY,
+      base_url: baseUrl,
+      // env_key is the official-doc credential mechanism: Codex resolves the
+      // key from the OPENAI_API_KEY env var, falling back to auth.json below.
+      env_key: "OPENAI_API_KEY",
+      wire_api: wireApi,
+      requires_openai_auth: true,
+    };
+    config.model_providers = providers;
+
+    writeTextAtomic(configPath, stringifyToml(config) + "\n");
+
+    // auth.json — Codex reads OPENAI_API_KEY from here when the env var is unset.
+    const authPath = join(homedir(), ".codex", "auth.json");
+    backup(authPath);
+    const auth = readJson(authPath);
+    auth.OPENAI_API_KEY = apiKey;
+    writeJsonAtomic(authPath, auth);
+
+    return {
+      paths: [configPath, authPath],
+      nextStep: "Run `codex` to start using Codex with DashScope.",
+      warnings: warnings.length > 0 ? warnings : undefined,
+    };
+  },
+} satisfies AgentDef;

packages/commands/src/commands/config/agent/writers/hermes.ts

@@ -0,0 +1,43 @@
+import { homedir } from "os";
+import { join } from "path";
+import { existsSync, readFileSync } from "fs";
+import yaml from "yaml";
+import { backup, writeTextAtomic, isAnthropicEndpoint, type AgentDef } from "./utils.ts";
+
+export default {
+  label: "Hermes Agent",
+  write({ baseUrl, apiKey, model }) {
+    const configPath = join(homedir(), ".hermes", "config.yaml");
+
+    backup(configPath);
+
+    let config: Record<string, unknown> = {};
+    if (existsSync(configPath)) {
+      try {
+        config = (yaml.parse(readFileSync(configPath, "utf-8")) ?? {}) as Record<string, unknown>;
+      } catch {
+        config = {};
+      }
+    }
+
+    // Official Model Studio doc shape: a single flat `model` block holding the
+    // active endpoint + credentials. `api_mode: anthropic_messages` is required
+    // for /apps/anthropic endpoints; for the OpenAI-compatible endpoint the
+    // doc says to omit api_mode entirely (chat completions is the default).
+    const block: Record<string, unknown> = {
+      default: model,
+      provider: "custom",
+      base_url: baseUrl,
+      api_key: apiKey,
+    };
+    if (isAnthropicEndpoint(baseUrl)) block.api_mode = "anthropic_messages";
+    config.model = block;
+
+    writeTextAtomic(configPath, yaml.stringify(config));
+
+    return {
+      paths: [configPath],
+      nextStep: 'Run `hermes chat -q "hello"` to verify.',
+    };
+  },
+} satisfies AgentDef;

packages/commands/src/commands/config/agent/writers/openclaw.ts

@@ -0,0 +1,83 @@
+import { homedir } from "os";
+import { join } from "path";
+import { backup, readJson, writeJsonAtomic, isAnthropicEndpoint, type AgentDef } from "./utils.ts";
+
+// Safe default when --context-window is not given: most Model Studio models
+// offer ≥256K context; users can raise it per model via the flag.
+const DEFAULT_CONTEXT_WINDOW = 256000;
+
+const PROVIDER_ID = "bailian-cli";
+
+function readPrimary(defaults: Record<string, unknown>): string | undefined {
+  const model = defaults.model;
+  if (!model || typeof model !== "object") return undefined;
+  const primary = (model as Record<string, unknown>).primary;
+  return typeof primary === "string" && primary.trim() !== "" ? primary.trim() : undefined;
+}
+
+export default {
+  label: "OpenClaw",
+  write({ baseUrl, apiKey, model, contextWindow }) {
+    const configPath = join(homedir(), ".openclaw", "openclaw.json");
+    const warnings: string[] = [];
+    const modelRef = `${PROVIDER_ID}/${model}`;
+
+    backup(configPath);
+    const config = readJson(configPath);
+
+    // models.providers["bailian-cli"] — upsert without removing other providers
+    // (e.g. an existing working bailian-token-plan setup).
+    const models = (config.models ?? {}) as Record<string, unknown>;
+    models.mode = "merge";
+    const providers = (models.providers ?? {}) as Record<string, unknown>;
+    const api = isAnthropicEndpoint(baseUrl) ? "anthropic-messages" : "openai-completions";
+    providers[PROVIDER_ID] = {
+      baseUrl,
+      apiKey,
+      api,
+      models: [
+        {
+          id: model,
+          name: model,
+          contextWindow: contextWindow ?? DEFAULT_CONTEXT_WINDOW,
+          cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        },
+      ],
+    };
+    models.providers = providers;
+    config.models = models;
+
+    // agents.defaults — register the model in the allow-list. Only set primary
+    // when unset, or when primary already points at bailian-cli (reconfigure).
+    // Never steal primary away from another provider such as bailian-token-plan.
+    const agents = (config.agents ?? {}) as Record<string, unknown>;
+    const defaults = (agents.defaults ?? {}) as Record<string, unknown>;
+    const allowedModels = (defaults.models ?? {}) as Record<string, unknown>;
+    allowedModels[modelRef] = allowedModels[modelRef] ?? {};
+    defaults.models = allowedModels;
+
+    const existingPrimary = readPrimary(defaults);
+    if (!existingPrimary) {
+      defaults.model = { primary: modelRef };
+    } else if (existingPrimary.startsWith(`${PROVIDER_ID}/`)) {
+      defaults.model = { primary: modelRef };
+    } else {
+      warnings.push(
+        `Left existing primary model unchanged ("${existingPrimary}"). ` +
+          `Added provider "${PROVIDER_ID}" — switch to "${modelRef}" in OpenClaw if you want to use it.`,
+      );
+    }
+
+    agents.defaults = defaults;
+    config.agents = agents;
+
+    writeJsonAtomic(configPath, config);
+
+    return {
+      paths: [configPath],
+      nextStep:
+        "Run `openclaw gateway restart`, then `openclaw` to start using OpenClaw with DashScope.",
+      warnings: warnings.length > 0 ? warnings : undefined,
+    };
+  },
+} satisfies AgentDef;

packages/commands/src/commands/config/agent/writers/opencode.ts

@@ -0,0 +1,33 @@
+import { homedir } from "os";
+import { join } from "path";
+import { backup, readJsonc, writeJsonAtomic, isAnthropicEndpoint, type AgentDef } from "./utils.ts";
+
+export default {
+  label: "OpenCode",
+  write({ baseUrl, apiKey, model }) {
+    const configPath = join(homedir(), ".config", "opencode", "opencode.json");
+
+    // opencode.json is JSONC — tolerate comments and trailing commas on read.
+    backup(configPath);
+    const config = readJsonc(configPath);
+
+    if (!config.$schema) config.$schema = "https://opencode.ai/config.json";
+
+    const provider = (config.provider ?? {}) as Record<string, unknown>;
+    const npm = isAnthropicEndpoint(baseUrl) ? "@ai-sdk/anthropic" : "@ai-sdk/openai-compatible";
+    provider["bailian-cli"] = {
+      npm,
+      name: "Alibaba Cloud Model Studio",
+      options: { baseURL: baseUrl, apiKey, setCacheKey: true },
+      models: { [model]: { name: model } },
+    };
+    config.provider = provider;
+
+    writeJsonAtomic(configPath, config);
+
+    return {
+      paths: [configPath],
+      nextStep: "Run `opencode` then type `/models` to select your model.",
+    };
+  },
+} satisfies AgentDef;

packages/commands/src/commands/config/agent/writers/qwen-code.ts

@@ -0,0 +1,119 @@
+import { homedir } from "os";
+import { join } from "path";
+import { backup, readJson, writeJsonAtomic, isAnthropicEndpoint, type AgentDef } from "./utils.ts";
+
+const ENV_KEY = "DASHSCOPE_API_KEY";
+
+function displayName(model: string): string {
+  return `[Bailian] ${model}`;
+}
+
+/** Entries we previously wrote, or still own via envKey / display brand. */
+function isBailianCliEntry(entry: Record<string, unknown>): boolean {
+  if (entry.envKey === ENV_KEY) return true;
+  const name = typeof entry.name === "string" ? entry.name : "";
+  return name === "bailian-cli" || name.startsWith("[Bailian]");
+}
+
+/**
+ * Qwen Code keys `modelProviders` and `security.auth.selectedType` by the SDK
+ * protocol (an AuthType string), not by a free-form provider id — the runtime
+ * resolver indexes credentials/defaults by protocol. The `bailian-cli` brand
+ * therefore lives in the env var name (`BAILIAN_CLI_API_KEY`) and the display
+ * label (`[Bailian] …`); Qwen Code keys models by id (+ baseUrl), never by name.
+ *
+ * Qwen Code does not support duplicate model `id`s (only the first loads), so
+ * we must never overwrite a pre-existing Token Plan / third-party entry that
+ * shares the same id.
+ *
+ * Credentials are written to BOTH `env` (via the entry's `envKey`) and
+ * `security.auth` — the resolver reads `security.auth.apiKey/baseUrl` as a
+ * lower-priority layer, which stops a stray system `OPENAI_API_KEY` from being
+ * picked up when the provider→envKey path does not resolve first. The active
+ * `model` also carries its `baseUrl`, as Qwen Code requires to disambiguate
+ * same-id providers.
+ */
+export default {
+  label: "Qwen Code",
+  write({ baseUrl, apiKey, model }) {
+    const settingsPath = join(homedir(), ".qwen", "settings.json");
+    const protocol = isAnthropicEndpoint(baseUrl) ? "anthropic" : "openai";
+    const warnings: string[] = [];
+
+    backup(settingsPath);
+    const settings = readJson(settingsPath);
+
+    // $version — Qwen Code v3 settings schema (official Model Studio doc shape).
+    settings.$version = 3;
+
+    // env — API key read by the provider entry's envKey.
+    // Qwen Code treats settings.json `env` as lowest priority; a process/shell
+    // value for the same key wins and can make the first launch fail.
+    const env = (settings.env ?? {}) as Record<string, string>;
+    env[ENV_KEY] = apiKey;
+    settings.env = env;
+
+    const processEnvValue = process.env[ENV_KEY];
+    if (processEnvValue !== undefined && processEnvValue !== apiKey) {
+      warnings.push(
+        `Shell/environment ${ENV_KEY} is set and overrides settings.json. ` +
+          `Unset it (e.g. \`unset ${ENV_KEY}\`) so the key written here takes effect.`,
+      );
+    }
+
+    // modelProviders[<protocol>] — upsert only bailian-cli-owned entries.
+    const providers = (settings.modelProviders ?? {}) as Record<
+      string,
+      Array<Record<string, unknown>>
+    >;
+    const entries = (providers[protocol] ?? []) as Array<Record<string, unknown>>;
+    const owned = entries.find((entry) => isBailianCliEntry(entry) && entry.id === model);
+    const conflicting = entries.find((entry) => !isBailianCliEntry(entry) && entry.id === model);
+
+    if (owned) {
+      owned.baseUrl = baseUrl;
+      owned.envKey = ENV_KEY;
+      const currentName = typeof owned.name === "string" ? owned.name.trim() : "";
+      if (!currentName || currentName === "bailian-cli") owned.name = displayName(model);
+    } else if (conflicting) {
+      const existingName =
+        typeof conflicting.name === "string" && conflicting.name.length > 0
+          ? conflicting.name
+          : String(conflicting.id);
+      warnings.push(
+        `Model id "${model}" already exists as "${existingName}"; left unchanged ` +
+          `(Qwen Code loads only the first entry per id). Remove or rename that ` +
+          `entry if you want bailian-cli to own this model.`,
+      );
+    } else {
+      entries.push({
+        id: model,
+        name: displayName(model),
+        baseUrl,
+        envKey: ENV_KEY,
+      });
+    }
+    providers[protocol] = entries;
+    settings.modelProviders = providers;
+
+    // security.auth — select the protocol AND keep credentials as a fallback
+    // layer (see the file-level note): without this, a stray system
+    // OPENAI_API_KEY can win when the provider→envKey lookup does not resolve.
+    const security = (settings.security ?? {}) as Record<string, unknown>;
+    security.auth = { selectedType: protocol, apiKey, baseUrl };
+    settings.security = security;
+
+    // model — active model. baseUrl MUST be written alongside name; Qwen Code
+    // uses it to disambiguate same-id providers, and omitting it can misroute
+    // to a different entry (and thus a different credential).
+    settings.model = { name: model, baseUrl };
+
+    writeJsonAtomic(settingsPath, settings);
+
+    return {
+      paths: [settingsPath],
+      nextStep: "Run `qwen` to start using Qwen Code with DashScope.",
+      warnings: warnings.length > 0 ? warnings : undefined,
+    };
+  },
+} satisfies AgentDef;

packages/commands/src/commands/config/agent/writers/utils.ts

@@ -0,0 +1,215 @@
+import { dirname } from "path";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, copyFileSync } from "fs";
+import { BailianError, ExitCode } from "bailian-cli-core";
+
+/** Parameters shared by every agent writer. */
+export interface WriteParams {
+  baseUrl: string;
+  apiKey: string;
+  model: string;
+  /** OpenClaw model entry context window (tokens). */
+  contextWindow?: number;
+  /** Codex provider wire protocol: "responses" or "chat". */
+  wireApi?: string;
+}
+
+/** What a writer reports back after configuring an agent. */
+export interface WriteSummary {
+  paths: string[];
+  nextStep: string;
+  /** Non-fatal issues the command should surface to the user. */
+  warnings?: string[];
+}
+
+/** An agent configuration writer: a human label plus a `write` that applies it. */
+export interface AgentDef {
+  label: string;
+  write(params: WriteParams): WriteSummary;
+}
+
+/**
+ * Strip JSONC syntax (line / block comments and trailing commas) so the result
+ * parses with `JSON.parse`. String contents are preserved verbatim.
+ */
+export function stripJsonc(text: string): string {
+  // Pass 1 — drop comments (string contents preserved verbatim).
+  let uncommented = "";
+  let index = 0;
+  let inString = false;
+  while (index < text.length) {
+    const char = text[index];
+    const next = text[index + 1];
+    if (inString) {
+      uncommented += char;
+      if (char === "\\") {
+        uncommented += next ?? "";
+        index += 2;
+        continue;
+      }
+      if (char === '"') inString = false;
+      index += 1;
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      uncommented += char;
+      index += 1;
+      continue;
+    }
+    if (char === "/" && next === "/") {
+      while (index < text.length && text[index] !== "\n") index += 1;
+      continue;
+    }
+    if (char === "/" && next === "*") {
+      index += 2;
+      while (index < text.length && !(text[index] === "*" && text[index + 1] === "/")) index += 1;
+      index += 2;
+      continue;
+    }
+    uncommented += char;
+    index += 1;
+  }
+
+  // Pass 2 — drop trailing commas (a comma whose next non-whitespace char
+  // closes an object/array). Runs after comment removal so a trailing comment
+  // cannot hide the closing bracket.
+  let output = "";
+  index = 0;
+  inString = false;
+  while (index < uncommented.length) {
+    const char = uncommented[index];
+    if (inString) {
+      output += char;
+      if (char === "\\") {
+        output += uncommented[index + 1] ?? "";
+        index += 2;
+        continue;
+      }
+      if (char === '"') inString = false;
+      index += 1;
+      continue;
+    }
+    if (char === '"') inString = true;
+    if (char === ",") {
+      let lookahead = index + 1;
+      while (lookahead < uncommented.length && /\s/.test(uncommented[lookahead])) lookahead += 1;
+      if (uncommented[lookahead] === "}" || uncommented[lookahead] === "]") {
+        index += 1;
+        continue;
+      }
+    }
+    output += char;
+    index += 1;
+  }
+  return output;
+}
+
+/** Read a JSON object file, returning `{}` when missing or unparseable. */
+export function readJson(path: string): Record<string, unknown> {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+/** Like {@link readJson}, but tolerates JSONC (comments / trailing commas). */
+export function readJsonc(path: string): Record<string, unknown> {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(stripJsonc(readFileSync(path, "utf-8"))) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+/** Atomically write `data` as pretty JSON with owner-only permissions. */
+export function writeJsonAtomic(path: string, data: unknown): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = path + ".tmp";
+  writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
+  renameSync(tmp, path);
+}
+
+/** Atomically write raw text with owner-only permissions. */
+export function writeTextAtomic(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = path + ".tmp";
+  writeFileSync(tmp, content, { mode: 0o600 });
+  renameSync(tmp, path);
+}
+
+/** Copy an existing file to a timestamped `.bak.<epoch>` sibling. No-op if absent. */
+export function backup(path: string): void {
+  if (!existsSync(path)) return;
+  const timestamp = Math.floor(Date.now() / 1000);
+  copyFileSync(path, `${path}.bak.${timestamp}`);
+}
+
+/** Whether a base URL targets the Anthropic-messages compatible endpoint. */
+export function isAnthropicEndpoint(baseUrl: string): boolean {
+  return baseUrl.includes("/apps/anthropic");
+}
+
+/**
+ * Claude Code speaks Anthropic Messages only. Users often paste the OpenAI
+ * compatible-mode URL; rewrite that to `/apps/anthropic` when possible, otherwise
+ * fail with a clear USAGE error before writing a broken config.
+ */
+export function resolveClaudeCodeBaseUrl(baseUrl: string): {
+  url: string;
+  rewrittenFrom?: string;
+} {
+  const trimmed = baseUrl.trim().replace(/\/+$/, "");
+
+  if (isAnthropicEndpoint(trimmed)) {
+    return { url: trimmed };
+  }
+
+  if (trimmed.includes("/compatible-mode")) {
+    const rewritten = trimmed.replace(/\/compatible-mode(?:\/v\d+)?/, "/apps/anthropic");
+    return { url: rewritten, rewrittenFrom: baseUrl.trim() };
+  }
+
+  try {
+    const parsed = new URL(trimmed);
+    const host = parsed.hostname;
+    const isDashScopeHost =
+      host.includes("dashscope") ||
+      host.includes("maas.aliyuncs.com") ||
+      host.includes("token-plan");
+    if (isDashScopeHost && (parsed.pathname === "/" || parsed.pathname === "")) {
+      return {
+        url: `${parsed.origin}/apps/anthropic`,
+        rewrittenFrom: baseUrl.trim(),
+      };
+    }
+  } catch {
+    // Fall through to the USAGE error below.
+  }
+
+  throw new BailianError(
+    `Claude Code requires an Anthropic-compatible base URL, got "${baseUrl}".`,
+    ExitCode.USAGE,
+    "Use a URL ending in /apps/anthropic (not /compatible-mode/v1). Example: https://dashscope.aliyuncs.com/apps/anthropic",
+  );
+}
+
+/**
+ * Convert a Model Studio region id into a Token Plan base URL, used in place of
+ * --base-url. Produces the OpenAI-compatible endpoint; the claude-code writer
+ * rewrites it to /apps/anthropic on its own, and the other writers consume the
+ * compatible-mode URL directly.
+ */
+export function resolveRegionBaseUrl(region: string): string {
+  const normalized = region.trim();
+  if (!/^[a-z0-9-]+$/.test(normalized)) {
+    throw new BailianError(
+      `Invalid --region "${region}".`,
+      ExitCode.USAGE,
+      "Use a Model Studio region id, e.g. cn-beijing or ap-southeast-1.",
+    );
+  }
+  return `https://token-plan.${normalized}.maas.aliyuncs.com/compatible-mode/v1`;
+}

packages/commands/src/commands/config/list.ts

@@ -0,0 +1,31 @@
+import { defineCommand, detectOutputFormat } from "bailian-cli-core";
+import { emitBare, emitResult } from "bailian-cli-runtime";
+
+export default defineCommand({
+  description: "List config profiles and show the active profile",
+  auth: "none",
+  exampleArgs: ["", "--output json"],
+  async run(ctx) {
+    const profiles = ctx.configStore.profiles();
+    const names = ["default", ...Object.keys(profiles.named).sort()];
+    const format = detectOutputFormat(ctx.settings.output);
+
+    if (format === "json") {
+      emitResult(
+        {
+          active_config: profiles.active,
+          profiles: names,
+          config_file: ctx.configStore.path,
+        },
+        format,
+      );
+      return;
+    }
+
+    const nameWidth = Math.max("NAME".length, ...names.map((name) => name.length));
+    emitBare(`${"NAME".padEnd(nameWidth)}  ACTIVE`);
+    for (const name of names) {
+      emitBare(`${name.padEnd(nameWidth)}  ${name === profiles.active ? "*" : ""}`);
+    }
+  },
+});

packages/commands/src/commands/config/set.ts

@@ -1,50 +1,6 @@
-import {
-  defineCommand,
-  detectOutputFormat,
-  maskToken,
-  BailianError,
-  ExitCode,
-  type ConfigFile,
-} from "bailian-cli-core";
+import { defineCommand, detectOutputFormat, maskToken, type ConfigFile } from "bailian-cli-core";
 import { emitResult } from "bailian-cli-runtime";
-
-const VALID_KEYS = [
-  "base_url",
-  "output",
-  "output_dir",
-  "timeout",
-  "api_key",
-  "access_token",
-  "access_key_id",
-  "access_key_secret",
-  "default_text_model",
-  "default_video_model",
-  "default_image_model",
-  "default_speech_model",
-  "default_omni_model",
-  "workspace_id",
-];
-
-// Keys whose values are secrets. Their stored value must never be echoed back in
-// cleartext (CI logs, pipes, shared terminals); show a masked form instead — the
-// same policy `config show` and `auth status` already follow.
-const SECRET_KEYS = new Set(["api_key", "access_token", "access_key_id", "access_key_secret"]);
-
-// Allow hyphen-style keys (e.g. default-text-model → default_text_model)
-const KEY_ALIASES: Record<string, string> = {
-  "base-url": "base_url",
-  "output-dir": "output_dir",
-  "api-key": "api_key",
-  "access-token": "access_token",
-  "access-key-id": "access_key_id",
-  "access-key-secret": "access_key_secret",
-  "default-text-model": "default_text_model",
-  "default-video-model": "default_video_model",
-  "default-image-model": "default_image_model",
-  "default-speech-model": "default_speech_model",
-  "default-omni-model": "default_omni_model",
-  "workspace-id": "workspace_id",
-};
+import { SECRET_KEYS, resolveKey, validateAndCoerce } from "./shared.ts";
 
 export default defineCommand({
   description: "Set a config value",
@@ -55,10 +11,15 @@ export default defineCommand({
       type: "string",
       valueHint: "<key>",
       description:
-        "Config key (base_url, output, output_dir, timeout, api_key, access_token, access_key_id, access_key_secret, default_*_model, workspace_id)",
+        "Config key (base_url, output, output_dir, timeout, api_key, access_token, access_key_id, access_key_secret, security_token, default_*_model, workspace_id)",
+      required: true,
+    },
+    value: {
+      type: "string",
+      valueHint: "<value>",
+      description: "Value to set",
       required: true,
     },
-    value: { type: "string", valueHint: "<value>", description: "Value to set", required: true },
   },
   exampleArgs: [
     "--key output --value json",
@@ -70,47 +31,38 @@ export default defineCommand({
     const key = flags.key;
     const value = flags.value;
 
-    // Resolve hyphen aliases to underscore keys
-    const resolvedKey: string = KEY_ALIASES[key] || key;
-
-    if (!VALID_KEYS.includes(resolvedKey)) {
-      throw new BailianError(
-        `Invalid config key "${key}". Valid keys: ${VALID_KEYS.join(", ")}`,
-        ExitCode.USAGE,
-      );
-    }
-
-    // Validate specific values
-    if (resolvedKey === "output" && !["text", "json"].includes(value)) {
-      throw new BailianError(
-        `Invalid output format "${value}". Valid values: text, json`,
-        ExitCode.USAGE,
-      );
-    }
-
-    if (resolvedKey === "timeout") {
-      const num = Number(value);
-      if (isNaN(num) || num <= 0) {
-        throw new BailianError(
-          `Invalid timeout "${value}". Must be a positive number.`,
-          ExitCode.USAGE,
-        );
-      }
-    }
+    // Resolve hyphen aliases to underscore keys and validate/coerce the value.
+    const resolvedKey: string = resolveKey(key);
+    const coerced = validateAndCoerce(key, value);
 
     const format = detectOutputFormat(settings.output);
 
     if (settings.dryRun) {
-      emitResult({ would_set: { [resolvedKey]: value } }, format);
+      emitResult(
+        {
+          would_set: { [resolvedKey]: coerced },
+          config: settings.configName ?? "default",
+          config_file: ctx.configStore.path,
+        },
+        format,
+      );
       return;
     }
 
-    const coerced = resolvedKey === "timeout" ? Number(value) : value;
-    await ctx.configStore().write({ [resolvedKey]: coerced } as Partial<ConfigFile>);
+    await ctx.configStore.write({
+      [resolvedKey]: coerced,
+    } as Partial<ConfigFile>);
 
     if (!settings.quiet) {
       const shown = SECRET_KEYS.has(resolvedKey) ? maskToken(String(coerced)) : coerced;
-      emitResult({ [resolvedKey]: shown }, format);
+      emitResult(
+        {
+          [resolvedKey]: shown,
+          config: settings.configName ?? "default",
+          config_file: ctx.configStore.path,
+        },
+        format,
+      );
     }
   },
 });

packages/commands/src/commands/config/shared.ts

@@ -0,0 +1,94 @@
+import { BailianError, ExitCode, normalizeModelBaseUrl } from "bailian-cli-core";
+
+/** Config keys that `config set` / `config ui` accept for read/write. */
+export const VALID_KEYS = [
+  "base_url",
+  "output",
+  "output_dir",
+  "timeout",
+  "api_key",
+  "access_token",
+  "access_key_id",
+  "access_key_secret",
+  "security_token",
+  "default_text_model",
+  "default_video_model",
+  "default_image_to_video_model",
+  "default_reference_to_video_model",
+  "default_image_model",
+  "default_speech_model",
+  "default_omni_model",
+  "workspace_id",
+] as const;
+
+// Keys whose values are secrets. `config set` / `config show` mask these; the
+// web UI renders them as password fields (values are still sent in cleartext
+// over the token-gated localhost socket).
+export const SECRET_KEYS = new Set<string>([
+  "api_key",
+  "access_token",
+  "access_key_id",
+  "access_key_secret",
+  "security_token",
+]);
+
+// Allow hyphen-style keys (e.g. default-text-model → default_text_model).
+export const KEY_ALIASES: Record<string, string> = {
+  "base-url": "base_url",
+  "output-dir": "output_dir",
+  "api-key": "api_key",
+  "access-token": "access_token",
+  "access-key-id": "access_key_id",
+  "access-key-secret": "access_key_secret",
+  "security-token": "security_token",
+  "default-text-model": "default_text_model",
+  "default-video-model": "default_video_model",
+  "default-image-to-video-model": "default_image_to_video_model",
+  "default-reference-to-video-model": "default_reference_to_video_model",
+  "default-image-model": "default_image_model",
+  "default-speech-model": "default_speech_model",
+  "default-omni-model": "default_omni_model",
+  "workspace-id": "workspace_id",
+};
+
+/** Resolve a hyphen alias to its underscore config key. */
+export function resolveKey(key: string): string {
+  return KEY_ALIASES[key] || key;
+}
+
+/**
+ * Validate a single config entry and coerce its value to the stored type.
+ * Throws BailianError(USAGE) for unknown keys or invalid values.
+ */
+export function validateAndCoerce(key: string, value: string): string | number {
+  const resolvedKey = resolveKey(key);
+
+  if (!(VALID_KEYS as readonly string[]).includes(resolvedKey)) {
+    throw new BailianError(
+      `Invalid config key "${key}". Valid keys: ${VALID_KEYS.join(", ")}`,
+      ExitCode.USAGE,
+    );
+  }
+
+  if (resolvedKey === "output" && !["text", "json"].includes(value)) {
+    throw new BailianError(
+      `Invalid output format "${value}". Valid values: text, json`,
+      ExitCode.USAGE,
+    );
+  }
+
+  if (resolvedKey === "timeout") {
+    const num = Number(value);
+    if (isNaN(num) || num <= 0) {
+      throw new BailianError(
+        `Invalid timeout "${value}". Must be a positive number.`,
+        ExitCode.USAGE,
+      );
+    }
+    return num;
+  }
+
+  if (resolvedKey === "base_url") return normalizeModelBaseUrl(value);
+
+  return value;
+}

packages/commands/src/commands/config/show.ts

@@ -1,5 +1,6 @@
 import { defineCommand, detectOutputFormat, maskToken } from "bailian-cli-core";
 import { emitResult } from "bailian-cli-runtime";
+import { SECRET_KEYS } from "./shared.ts";
 
 export default defineCommand({
   description: "Display current configuration",
@@ -7,7 +8,7 @@ export default defineCommand({
   exampleArgs: ["", "--output json"],
   async run(ctx) {
     const { settings, client } = ctx;
-    const store = ctx.configStore();
+    const store = ctx.configStore;
     const file = store.read();
     const format = detectOutputFormat(settings.output);
 
@@ -16,16 +17,13 @@ export default defineCommand({
       base_url: client.baseUrl,
       output: settings.output,
       timeout: settings.timeout,
+      config: settings.configName ?? "default",
       config_file: store.path,
     };
 
-    if (typeof result.api_key === "string") result.api_key = maskToken(result.api_key);
-    if (typeof result.access_token === "string")
-      result.access_token = maskToken(result.access_token);
-    if (typeof result.access_key_id === "string")
-      result.access_key_id = maskToken(result.access_key_id);
-    if (typeof result.access_key_secret === "string")
-      result.access_key_secret = maskToken(result.access_key_secret);
+    for (const key of SECRET_KEYS) {
+      if (typeof result[key] === "string") result[key] = maskToken(result[key]);
+    }
 
     emitResult(result, format);
   },

packages/commands/src/commands/config/ui-html.ts

@@ -0,0 +1,266 @@
+// Self-contained single-page web UI for managing config profiles. Served as a
+// string by `config ui`; no build step, no client dependencies. All fetches
+// carry the session token from the page URL.
+export const PAGE_HTML = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>bailian-cli config</title>
+<style>
+  * { box-sizing: border-box; }
+  body { margin: 0; font: 14px/1.5 -apple-system, Segoe UI, Roboto, sans-serif; color: #1f2328; background: #f6f8fa; }
+  #app { display: flex; min-height: 100vh; }
+  #sidebar { width: 240px; background: #fff; border-right: 1px solid #d0d7de; padding: 16px; }
+  #sidebar h1 { font-size: 15px; margin: 0 0 12px; }
+  #profileList { list-style: none; margin: 0 0 12px; padding: 0; }
+  #profileList li { padding: 8px 10px; border-radius: 6px; cursor: pointer; word-break: break-all; }
+  #profileList li:hover { background: #f0f3f6; }
+  #profileList li.selected { background: #0969da; color: #fff; }
+  main { flex: 1; padding: 24px 32px; max-width: 720px; }
+  #editorHead { display: flex; align-items: center; justify-content: space-between; }
+  h2 { font-size: 18px; margin: 0 0 4px; }
+  .row { display: flex; flex-direction: column; margin: 12px 0; }
+  .row label { font-weight: 600; margin-bottom: 4px; }
+  .inputwrap { display: flex; gap: 6px; }
+  input { flex: 1; padding: 7px 9px; border: 1px solid #d0d7de; border-radius: 6px; font: inherit; width: 100%; }
+  button { padding: 7px 12px; border: 1px solid #d0d7de; border-radius: 6px; background: #f6f8fa; cursor: pointer; font: inherit; }
+  button:hover { background: #eef1f4; }
+  #saveBtn { background: #1f883d; color: #fff; border-color: #1f883d; }
+  #saveBtn:hover { background: #1a7f37; }
+  .danger { color: #cf222e; }
+  .toggle { flex: none; }
+  .actions { margin-top: 20px; display: flex; align-items: center; gap: 12px; }
+  .muted { color: #656d76; font-size: 12px; word-break: break-all; }
+  .err { color: #cf222e; font-size: 12px; }
+</style>
+</head>
+<body>
+<div id="app">
+  <aside id="sidebar">
+    <h1>Config Profiles</h1>
+    <ul id="profileList"></ul>
+    <button id="newBtn">+ New profile</button>
+    <p id="cfgFile" class="muted"></p>
+  </aside>
+  <main id="editor">
+    <div id="editorHead">
+      <h2 id="currentName"></h2>
+      <button id="deleteBtn" class="danger">Delete</button>
+    </div>
+    <form id="form" onsubmit="return false"></form>
+    <div class="actions">
+      <button id="saveBtn">Save</button>
+      <button id="useBtn">Save &amp; Activate</button>
+      <span id="status" class="muted"></span>
+    </div>
+  </main>
+</div>
+<script>
+  var token = new URLSearchParams(location.search).get('token') || '';
+  var KEYS = [], SECRETS = [], DATA = { default: {}, named: {} }, CURRENT = '', ACTIVE = 'default';
+
+  function api(path, opts) {
+    var sep = path.indexOf('?') >= 0 ? '&' : '?';
+    return fetch(path + sep + 'token=' + encodeURIComponent(token), opts || {});
+  }
+
+  function setStatus(msg, isErr) {
+    var el = document.getElementById('status');
+    el.textContent = msg || '';
+    el.className = isErr ? 'err' : 'muted';
+  }
+
+  function profileData(name) {
+    return name === '' ? DATA.default : (DATA.named[name] || {});
+  }
+
+  function load() {
+    api('/api/config').then(function (r) { return r.json(); }).then(function (j) {
+      KEYS = j.keys || [];
+      SECRETS = j.secretKeys || [];
+      DATA = { default: j.default || {}, named: j.named || {} };
+      ACTIVE = j.activeProfile || 'default';
+      document.getElementById('cfgFile').textContent = j.configFile || '';
+      CURRENT = ACTIVE === 'default' ? '' : ACTIVE;
+      renderProfiles();
+      renderForm();
+    }).catch(function (e) { setStatus('Load failed: ' + e, true); });
+  }
+
+  function renderProfiles() {
+    var ul = document.getElementById('profileList');
+    ul.innerHTML = '';
+    var names = [''].concat(Object.keys(DATA.named));
+    names.forEach(function (name) {
+      var li = document.createElement('li');
+      var displayName = name === '' ? 'default' : name;
+      li.textContent = displayName + (displayName === ACTIVE ? '  *' : '');
+      if (name === CURRENT) li.className = 'selected';
+      li.onclick = function () { CURRENT = name; renderProfiles(); renderForm(); setStatus(''); };
+      ul.appendChild(li);
+    });
+  }
+
+  function renderForm() {
+    var form = document.getElementById('form');
+    form.innerHTML = '';
+    document.getElementById('currentName').textContent = CURRENT === '' ? 'default (top-level)' : CURRENT;
+    document.getElementById('deleteBtn').style.display = CURRENT === '' ? 'none' : '';
+    var selectedName = CURRENT === '' ? 'default' : CURRENT;
+    var useBtn = document.getElementById('useBtn');
+    useBtn.disabled = selectedName === ACTIVE;
+    useBtn.textContent = selectedName === ACTIVE ? 'Active' : 'Save & Activate';
+    var data = profileData(CURRENT);
+    KEYS.forEach(function (key) {
+      var row = document.createElement('div');
+      row.className = 'row';
+      var label = document.createElement('label');
+      label.textContent = key;
+      label.htmlFor = 'f_' + key;
+      var input = document.createElement('input');
+      input.id = 'f_' + key;
+      input.name = key;
+      var val = data[key];
+      input.value = (val === undefined || val === null) ? '' : String(val);
+      if (SECRETS.indexOf(key) >= 0) {
+        input.type = 'password';
+        var toggle = document.createElement('button');
+        toggle.type = 'button';
+        toggle.className = 'toggle';
+        toggle.textContent = 'show';
+        toggle.onclick = function () {
+          if (input.type === 'password') { input.type = 'text'; toggle.textContent = 'hide'; }
+          else { input.type = 'password'; toggle.textContent = 'show'; }
+        };
+        var wrap = document.createElement('div');
+        wrap.className = 'inputwrap';
+        wrap.appendChild(input);
+        wrap.appendChild(toggle);
+        row.appendChild(label);
+        row.appendChild(wrap);
+      } else {
+        input.type = 'text';
+        row.appendChild(label);
+        row.appendChild(input);
+      }
+      form.appendChild(row);
+    });
+  }
+
+  function collect() {
+    var data = {};
+    KEYS.forEach(function (key) {
+      var el = document.getElementById('f_' + key);
+      data[key] = el ? el.value : '';
+    });
+    return data;
+  }
+
+  function saveProfile(name, data) {
+    var profileData = data === undefined ? collect() : data;
+    var body = JSON.stringify({ name: name, data: profileData });
+    return api('/api/profile', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: body
+    })
+      .then(function (response) {
+        return response.json().then(function (json) { return { ok: response.ok, json: json }; });
+      })
+      .then(function (result) {
+        if (!result.ok) {
+          throw new Error((result.json && result.json.error) || 'error');
+        }
+        var saved = result.json.saved || {};
+        if (name === '') DATA.default = saved; else DATA.named[name] = saved;
+        return saved;
+      });
+  }
+
+  function save() {
+    var name = CURRENT;
+    saveProfile(name)
+      .then(function () {
+        renderForm();
+        setStatus('Saved.');
+      })
+      .catch(function (error) { setStatus('Save failed: ' + error.message, true); });
+  }
+
+  function newProfile() {
+    var name = prompt('New profile name (letters, numbers, - or _):');
+    if (!name) return;
+    if (DATA.named[name] !== undefined) {
+      CURRENT = name;
+      renderProfiles();
+      renderForm();
+      setStatus('Profile already exists.');
+      return;
+    }
+    setStatus('Creating profile...');
+    saveProfile(name, {})
+      .then(function () {
+        CURRENT = name;
+        renderProfiles();
+        renderForm();
+        setStatus('Profile created and saved.');
+      })
+      .catch(function (error) { setStatus('Create failed: ' + error.message, true); });
+  }
+
+  function saveAndActivateProfile() {
+    var name = CURRENT === '' ? 'default' : CURRENT;
+    var profileName = CURRENT;
+    setStatus('Saving...');
+    saveProfile(profileName)
+      .then(function () {
+        return api('/api/active', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ name: name })
+        });
+      })
+      .then(function (response) {
+        return response.json().then(function (json) { return { ok: response.ok, json: json }; });
+      })
+      .then(function (result) {
+        if (!result.ok) {
+          throw new Error('Saved, but activation failed: ' + ((result.json && result.json.error) || 'error'));
+        }
+        ACTIVE = result.json.activeProfile || 'default';
+        renderProfiles();
+        renderForm();
+        setStatus('Saved and activated.');
+      })
+      .catch(function (error) { setStatus(error.message || String(error), true); });
+  }
+
+  function deleteProfile() {
+    if (CURRENT === '') return;
+    if (!confirm('Delete profile "' + CURRENT + '"?')) return;
+    api('/api/profile?name=' + encodeURIComponent(CURRENT), { method: 'DELETE' })
+      .then(function (r) {
+        if (!r.ok) return r.json().then(function (j) { throw new Error(j.error || 'error'); });
+        return r.json();
+      })
+      .then(function (result) {
+        delete DATA.named[CURRENT];
+        ACTIVE = result.activeProfile || 'default';
+        CURRENT = '';
+        renderProfiles();
+        renderForm();
+        setStatus('Deleted.');
+      })
+      .catch(function (e) { setStatus('Delete failed: ' + e, true); });
+  }
+
+  document.getElementById('saveBtn').onclick = save;
+  document.getElementById('newBtn').onclick = newProfile;
+  document.getElementById('useBtn').onclick = saveAndActivateProfile;
+  document.getElementById('deleteBtn').onclick = deleteProfile;
+  load();
+</script>
+</body>
+</html>
+`;

packages/commands/src/commands/config/ui.ts

@@ -0,0 +1,264 @@
+import http from "node:http";
+import { randomBytes } from "node:crypto";
+
+import {
+  defineCommand,
+  detectOutputFormat,
+  BailianError,
+  ExitCode,
+  normalizeConfigName,
+  readConfigFile,
+  writeConfigFile,
+  deleteConfigProfile,
+  type ConfigStore,
+  type FlagsDef,
+} from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import { listenLocalServer, openInBrowser } from "../shared/local-server.ts";
+import { PAGE_HTML } from "./ui-html.ts";
+import { VALID_KEYS, SECRET_KEYS, resolveKey, validateAndCoerce } from "./shared.ts";
+
+const FLAGS = {
+  port: {
+    type: "number",
+    valueHint: "<port>",
+    description: "Port to listen on (default: random free port)",
+  },
+  noOpen: { type: "switch", description: "Do not open the browser automatically" },
+} satisfies FlagsDef;
+
+const MAX_BODY = 1 << 20; // 1 MiB
+
+function errMessage(err: unknown): string {
+  return err instanceof BailianError
+    ? err.message
+    : err instanceof Error
+      ? err.message
+      : String(err);
+}
+
+function sendJson(res: http.ServerResponse, status: number, obj: unknown): void {
+  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+  res.end(JSON.stringify(obj));
+}
+
+function readBody(req: http.IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > MAX_BODY) {
+        reject(new Error("payload too large"));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+  });
+}
+
+/** Build the request cleaned/validated config block from a posted `data` map. */
+function buildProfilePatch(data: Record<string, unknown>): Record<string, string | number> {
+  const cleaned: Record<string, string | number> = {};
+  for (const [k, v] of Object.entries(data)) {
+    let value = "";
+    if (typeof v === "string") value = v;
+    else if (typeof v === "number" || typeof v === "boolean") value = String(v);
+    // null/undefined/objects fall through as "" and clear the key
+    if (value === "") continue;
+    cleaned[resolveKey(k)] = validateAndCoerce(k, value);
+  }
+  return cleaned;
+}
+
+/** Preserve valid Config fields that the UI does not expose or manage. */
+function mergeUnmanagedProfileFields(
+  existing: Record<string, unknown>,
+  managedPatch: Record<string, string | number>,
+): Record<string, unknown> {
+  const managedKeys = new Set<string>(VALID_KEYS);
+  const merged: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(existing)) {
+    if (!managedKeys.has(key)) merged[key] = value;
+  }
+  return { ...merged, ...managedPatch };
+}
+
+/**
+ * Build the config-UI http server. Exported for tests. The handler enforces:
+ * - Host header must be a loopback name (anti DNS-rebinding).
+ * - every request must carry `?token=` matching the session token.
+ */
+export function createConfigUiServer(token: string, configStore: ConfigStore): http.Server {
+  return http.createServer(async (req, res) => {
+    try {
+      const host = (req.headers.host || "").split(":")[0];
+      if (host !== "127.0.0.1" && host !== "localhost") {
+        res.writeHead(403, { "Content-Type": "text/plain; charset=utf-8" });
+        res.end("forbidden host\n");
+        return;
+      }
+
+      const u = new URL(req.url ?? "/", "http://127.0.0.1");
+      if (u.searchParams.get("token") !== token) {
+        res.writeHead(401, { "Content-Type": "text/plain; charset=utf-8" });
+        res.end("unauthorized\n");
+        return;
+      }
+
+      const method = req.method ?? "GET";
+      const path = u.pathname;
+
+      if (path === "/" && method === "GET") {
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(PAGE_HTML);
+        return;
+      }
+
+      if (path === "/api/config" && method === "GET") {
+        const profiles = configStore.profiles();
+        sendJson(res, 200, {
+          configFile: configStore.path,
+          keys: VALID_KEYS,
+          secretKeys: [...SECRET_KEYS],
+          activeProfile: profiles.active,
+          default: profiles.default,
+          named: profiles.named,
+        });
+        return;
+      }
+
+      if (path === "/api/active" && method === "POST") {
+        const raw = await readBody(req);
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(raw);
+        } catch {
+          sendJson(res, 400, { error: "invalid JSON body" });
+          return;
+        }
+        const body = parsed as { name?: unknown };
+        try {
+          const activeProfile = await configStore.activate(body.name);
+          sendJson(res, 200, { activeProfile });
+        } catch (err) {
+          sendJson(res, 400, { error: errMessage(err) });
+        }
+        return;
+      }
+
+      if (path === "/api/profile" && method === "POST") {
+        const raw = await readBody(req);
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(raw);
+        } catch {
+          sendJson(res, 400, { error: "invalid JSON body" });
+          return;
+        }
+        const body = parsed as { name?: unknown; data?: unknown };
+        if (!body.data || typeof body.data !== "object" || Array.isArray(body.data)) {
+          sendJson(res, 400, { error: "missing or invalid 'data'" });
+          return;
+        }
+        let normalized: string | undefined;
+        let cleaned: Record<string, string | number>;
+        try {
+          normalized = normalizeConfigName(body.name);
+          cleaned = buildProfilePatch(body.data as Record<string, unknown>);
+        } catch (err) {
+          sendJson(res, 400, { error: errMessage(err) });
+          return;
+        }
+        const existing = readConfigFile(normalized) as Record<string, unknown>;
+        const saved = mergeUnmanagedProfileFields(existing, cleaned);
+        await writeConfigFile(saved, normalized);
+        sendJson(res, 200, { saved });
+        return;
+      }
+
+      if (path === "/api/profile" && method === "DELETE") {
+        try {
+          const deleted = await deleteConfigProfile(u.searchParams.get("name") ?? undefined);
+          sendJson(res, 200, { deleted, activeProfile: configStore.profiles().active });
+        } catch (err) {
+          sendJson(res, 400, { error: errMessage(err) });
+        }
+        return;
+      }
+
+      res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end("not found\n");
+    } catch {
+      if (!res.headersSent) res.writeHead(500);
+      res.end();
+    }
+  });
+}
+
+export default defineCommand({
+  description: "Open a local web UI to manage config profiles",
+  auth: "none",
+  usageArgs: "[--port <port>] [--no-open]",
+  flags: FLAGS,
+  exampleArgs: ["", "--port 8787", "--no-open"],
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const format = detectOutputFormat(settings.output);
+
+    if (settings.dryRun) {
+      emitResult(
+        {
+          host: "127.0.0.1",
+          port: flags.port ?? "random free port",
+          config_file: ctx.configStore.path,
+          routes: [
+            "GET /              -> web UI",
+            "GET /api/config    -> read all profiles",
+            "POST /api/profile  -> save a profile",
+            "POST /api/active   -> activate a profile",
+            "DELETE /api/profile -> delete a named profile",
+          ],
+        },
+        format,
+      );
+      return;
+    }
+
+    const token = randomBytes(16).toString("hex");
+    const server = createConfigUiServer(token, ctx.configStore);
+
+    let port: number;
+    try {
+      port = await listenLocalServer(server, flags.port ?? 0);
+    } catch (err) {
+      throw new BailianError(
+        `Could not bind to 127.0.0.1 (no free port or permission denied): ${errMessage(err)}`,
+        ExitCode.USAGE,
+      );
+    }
+
+    const url = `http://127.0.0.1:${port}/?token=${token}`;
+
+    if (!flags.noOpen) {
+      try {
+        await openInBrowser(url);
+        emitBare("Opened the config UI in your default browser.");
+      } catch {
+        emitBare("Could not open the browser automatically. Open the URL below manually.");
+      }
+    }
+    emitBare(`Config UI running at ${url}`);
+    emitBare("Note: credentials are shown in cleartext in the browser (localhost only).");
+    emitBare("Press Ctrl+C to stop.");
+
+    await new Promise<void>((resolve) => {
+      const shutdown = () => server.close(() => resolve());
+      process.once("SIGINT", shutdown);
+      process.once("SIGTERM", shutdown);
+      server.once("close", () => resolve());
+    });
+  },
+});

packages/commands/src/commands/config/use.ts

@@ -0,0 +1,42 @@
+import { defineCommand, detectOutputFormat } from "bailian-cli-core";
+import { emitResult } from "bailian-cli-runtime";
+
+export default defineCommand({
+  description: "Set the active config profile",
+  auth: "none",
+  usageArgs: "--name <name>",
+  flags: {
+    name: {
+      type: "string",
+      valueHint: "<name>",
+      description: "Existing profile name, or default",
+      required: true,
+    },
+  },
+  exampleArgs: ["--name token-plan", "--name default"],
+  async run(ctx) {
+    const format = detectOutputFormat(ctx.settings.output);
+    if (ctx.settings.dryRun) {
+      const activeConfig = ctx.configStore.validateActivation(ctx.flags.name);
+      emitResult(
+        {
+          would_activate: activeConfig,
+          config_file: ctx.configStore.path,
+        },
+        format,
+      );
+      return;
+    }
+
+    const activeConfig = await ctx.configStore.activate(ctx.flags.name);
+    if (!ctx.settings.quiet) {
+      emitResult(
+        {
+          active_config: activeConfig,
+          config_file: ctx.configStore.path,
+        },
+        format,
+      );
+    }
+  },
+});

packages/commands/src/commands/dataset/upload.ts

@@ -6,6 +6,7 @@ import {
   parseDatasetSchemaFlag,
   formatIssue,
   MAX_DATASET_BYTES,
+  MAX_MEDIA_ZIP_BYTES,
   BailianError,
   ExitCode,
   type DatasetFile,
@@ -17,7 +18,7 @@ const UPLOAD_FLAGS = {
   file: {
     type: "string",
     valueHint: "<path>",
-    description: "Local .jsonl dataset file (≤300MB)",
+    description: "Local dataset file (.jsonl or .zip; ≤300MB text, ≤1GB image)",
     required: true,
   },
   purpose: {
@@ -29,7 +30,7 @@ const UPLOAD_FLAGS = {
     type: "string",
     valueHint: "<s>",
     description:
-      'Record schema: "chatml" (SFT), "dpo" (chosen/rejected), or "cpt" (raw text). Default auto-detects per record.',
+      'Record schema: "chatml" (SFT), "dpo" (chosen/rejected), "cpt" (raw text), "tts" (audio), or "image" (image generation). Default auto-detects per record.',
   },
   noValidate: {
     type: "switch",
@@ -42,42 +43,55 @@ const UPLOAD_FLAGS = {
 } satisfies FlagsDef;
 
 export default defineCommand({
-  description: "Upload a dataset file (.jsonl) to Bailian",
+  description: "Upload a dataset file (.jsonl or .zip) to Bailian",
   auth: "apiKey",
   usageArgs:
-    "--file <path> [--purpose <name>] [--schema <chatml|dpo|cpt>] [--no-validate] [--full-validate]",
+    "--file <path> [--purpose <name>] [--schema <chatml|dpo|cpt|tts|image>] [--no-validate] [--full-validate]",
   flags: UPLOAD_FLAGS,
   exampleArgs: [
     "--file train.jsonl",
     "--file dpo.jsonl --schema dpo",
     "--file cpt.jsonl --schema cpt",
+    "--file audio.zip --schema tts",
     "--file eval.jsonl --purpose evaluation",
     "--file train.jsonl --full-validate",
     "--file train.jsonl --no-validate",
   ],
   notes: [
-    "Only .jsonl is supported in this release. Three record schemas are",
-    "recognized: chatml = {messages:[...]} (SFT); dpo = {messages:[...],",
-    "chosen, rejected} where chosen/rejected are single assistant messages;",
-    'cpt = {text:"..."} (continual pre-training, raw text). With no --schema,',
-    "a record carrying chosen/rejected is validated as DPO, one with text (and",
-    "no messages) as CPT, otherwise as ChatML. Pass --schema dpo / cpt to",
-    "require that shape on every record, or --schema chatml to ignore the",
-    "preference / text fields. Other purposes may carry a different schema in",
-    "the future and would be served by a purpose-specific validator.",
-    "The dataset upload cap is 300MB per file.",
-    "Upload uses the OpenAI-compatible /compatible-mode/v1/files endpoint so",
-    "the purpose tag is persisted (the DashScope-native /api/v1/files drops it).",
+    "Supports .jsonl (text) and .zip (audio/image archives with a data.jsonl",
+    "manifest). Five record schemas are recognized: chatml = {messages:[...]}",
+    '(SFT); dpo = {messages:[...], chosen, rejected}; cpt = {text:"..."}',
+    '(continual pre-training, raw text); tts = {wav_fn:"train/xxx.wav",',
+    'text:"..."} (audio fine-tuning); image = {img_path:"..."} (image',
+    "generation). With no --schema, a record carrying wav_fn is validated as",
+    "TTS, img_path as image, chosen/rejected as DPO, text (no messages) as CPT,",
+    "otherwise ChatML. Upload cap: 300MB text, 1GB image. Upload uses the",
+    "OpenAI-compatible /compatible-mode/v1/files endpoint so the purpose tag is",
+    "persisted (the DashScope-native /api/v1/files drops it).",
   ],
   async run(ctx) {
     const { identity, settings, flags } = ctx;
     const filePath = flags.file;
     const purpose = flags.purpose || "fine-tune";
     const schema = parseDatasetSchemaFlag(flags.schema);
+    if (schema === "video") {
+      throw new BailianError(
+        `--schema video is not supported.`,
+        ExitCode.USAGE,
+        `Supported schemas: chatml, dpo, cpt, tts, image.`,
+      );
+    }
     const format = detectOutputFormat(settings.output);
+    // Image schema allows larger ZIPs (1 GB vs 300 MB for text).
+    const isMediaSchema = schema === "image";
 
     if (!flags.noValidate) {
-      const result = await validateDataset(filePath, { fullValidate: flags.fullValidate, schema });
+      const maxBytes = isMediaSchema ? MAX_MEDIA_ZIP_BYTES : MAX_DATASET_BYTES;
+      const result = await validateDataset(filePath, {
+        fullValidate: flags.fullValidate,
+        schema,
+        maxBytes,
+      });
       if (!result.valid) {
         const lines = [
           `Dataset validation failed for ${filePath}`,
@@ -112,7 +126,7 @@ export default defineCommand({
           action: "dataset.upload",
           file: filePath,
           purpose,
-          max_bytes: MAX_DATASET_BYTES,
+          max_bytes: isMediaSchema ? MAX_MEDIA_ZIP_BYTES : MAX_DATASET_BYTES,
           validate: !flags.noValidate,
           schema: schema ?? "auto",
         },

packages/commands/src/commands/dataset/validate.ts

@@ -25,7 +25,7 @@ const VALIDATE_FLAGS = {
   file: {
     type: "string",
     valueHint: "<path>",
-    description: "Local .jsonl dataset file",
+    description: "Local dataset file (.jsonl or .zip)",
     required: true,
   },
   fullValidate: {
@@ -36,20 +36,21 @@ const VALIDATE_FLAGS = {
     type: "string",
     valueHint: "<s>",
     description:
-      'Record schema: "chatml" (SFT), "dpo" (chosen/rejected), or "cpt" (raw text). Default auto-detects per record.',
+      'Record schema: "chatml" (SFT), "dpo" (chosen/rejected), "cpt" (raw text), "tts" (audio), or "image" (image generation). Default auto-detects per record.',
   },
 } satisfies FlagsDef;
 
 export default defineCommand({
-  description: "Locally validate a dataset file (.jsonl) without uploading",
+  description: "Locally validate a dataset file (.jsonl or .zip) without uploading",
   // 纯本地校验，不触网、不需 API key（与 `pipeline validate` 一致）。
   auth: "none",
-  usageArgs: "--file <path> [--full-validate] [--schema <chatml|dpo|cpt>]",
+  usageArgs: "--file <path> [--full-validate] [--schema <chatml|dpo|cpt|tts|image>]",
   flags: VALIDATE_FLAGS,
   exampleArgs: [
     "--file train.jsonl",
     "--file dpo.jsonl --schema dpo",
     "--file cpt.jsonl --schema cpt",
+    "--file audio.zip --schema tts",
     "--file eval.jsonl --full-validate",
     "--file train.jsonl --output json",
   ],
@@ -57,17 +58,27 @@ export default defineCommand({
     "Default scan: every line gets a structural check, then ~160 lines (front 50,",
     "evenly spaced 100, last 10) are JSON.parsed against the active schema.",
     "Schemas: chatml = {messages:[...]} (SFT); dpo = {messages:[...], chosen,",
-    "rejected} where chosen/rejected are single assistant messages; cpt =",
-    '{text:"..."} (continual pre-training, raw text). With no --schema, a',
-    "record carrying chosen/rejected is validated as DPO, one with text (and no",
-    "messages) as CPT, otherwise as ChatML. Pass --schema dpo / cpt to require",
-    "that shape on every record (strict), or --schema chatml to ignore the",
-    "preference / text fields. Use --full-validate to JSON.parse every line.",
+    'rejected}; cpt = {text:"..."} (continual pre-training, raw text);',
+    'tts = {wav_fn:"train/xxx.wav", text:"..."} (audio fine-tuning);',
+    'image = {img_path:"..."} (image generation). With no --schema, a record',
+    "carrying wav_fn is validated as TTS, img_path as image, chosen/rejected",
+    "as DPO, text (no messages) as CPT, otherwise ChatML. Pass --schema to",
+    "require a specific shape on every record. ZIP archives (.zip) are",
+    "validated structurally (data.jsonl present, media references resolve) in",
+    "addition to per-record content checks. Use --full-validate to JSON.parse",
+    "every line.",
   ],
   async run(ctx) {
     const { settings, flags } = ctx;
     const filePath = flags.file;
     const schema = parseDatasetSchemaFlag(flags.schema);
+    if (schema === "video") {
+      throw new BailianError(
+        `--schema video is not supported.`,
+        ExitCode.USAGE,
+        `Supported schemas: chatml, dpo, cpt, tts, image.`,
+      );
+    }
     const format = detectOutputFormat(settings.output);
 
     if (settings.dryRun) {

packages/commands/src/commands/deploy/create.ts

@@ -2,11 +2,16 @@ import {
   defineCommand,
   detectOutputFormat,
   createDeployment,
+  pickPlanStrategy,
+  STRATEGIES,
+  defaultDeployPlan,
+  type DeployModality,
   type CreateDeploymentRequest,
+  type CreatePlanFlags,
+  type CommandContext,
   type FlagsDef,
 } from "bailian-cli-core";
 import { emitResult, emitBare } from "bailian-cli-runtime";
-import { pickPlanStrategy, STRATEGIES } from "./plans.ts";
 
 const CREATE_FLAGS = {
   model: {
@@ -26,10 +31,10 @@ const CREATE_FLAGS = {
     valueHint: "<plan>",
     description: "Billing plan: lora (default, Token-billed) | ptu (Token-billed) | mu",
   },
-  templateId: {
+  deploySpec: {
     type: "string",
     valueHint: "<id>",
-    description: "Template id (only used by plan=mu; auto-picked if omitted)",
+    description: "Deploy spec (only used by plan=mu; auto-picked if omitted)",
   },
   capacity: {
     type: "number",
@@ -58,104 +63,156 @@ const CREATE_FLAGS = {
   },
 } satisfies FlagsDef;
 
+const CREATE_USAGE =
+  "--model <model_name> --name <display_name> [--plan <plan>] [--deploy-spec <id>] [--capacity <n>] [--billing-method <m>] [--input-tpm <n>] [--output-tpm <n>] [--thinking-output-tpm <n>]";
+
+const CREATE_NOTES = [
+  "Plan defaults to `lora` (Token-billed) for text/image and `mu` (model-unit-",
+  "billed) for audio (CosyVoice TTS). Pass --plan to override.",
+  "For plan=ptu (Token-billed, provisioned throughput), --input-tpm and",
+  "--output-tpm are required (the platform rejects creation without an",
+  "explicit ptu_capacity despite the doc listing defaults).",
+  "For plan=mu, `capacity`, `billing_method` and `deploy_spec` are required.",
+  "billing_method defaults to POST_PAY (only supported value); deploy_spec",
+  "and capacity are auto-picked from GET /deployments/models when omitted.",
+  "Use `bl deploy models --source base` to inspect available templates.",
+  "After creation, status starts at PENDING and transitions to RUNNING.",
+  "Invoke the deployed model with: bl text chat --model <deployed_model>",
+  "WARNING: --model is overloaded across commands and refers to DIFFERENT",
+  "values. `bl deploy <modality> create --model` takes the exported model_name",
+  "(e.g. `qwen3-8b-ft-...`), but the create response also returns a",
+  "`deployed_model` field (the deployment instance id, e.g.",
+  "`qwen3-8b-5ecb5f068d79`). The inference call `bl text chat --model` must use",
+  "the `deployed_model` from the create response — NOT the `model_name` you",
+  "passed to `deploy <modality> create`. Do not reuse the value across the two",
+  "commands.",
+];
+
 /**
- * `bl deploy create` — create a model deployment.
- *
- * Plan-specific behaviour (required flags / body assembly / auto-pick) lives
- * in `plans.ts` (`PlanStrategy` + `STRATEGIES`). This file only handles the
- * shared envelope: flag validation, dispatch, dry-run, and result
- * formatting. Adding a new plan = one entry in the strategy table;
- * nothing here changes.
- *
- * `--model` (model identifier) and `--name` (console display name) are required.
+ * Shared `deploy <modality> create` flag validation. Plan support is
+ * server-catalog-driven, so validation is identical for every modality: resolve
+ * the effective plan (modality-specific default when --plan is omitted), reject
+ * an unknown --plan, then defer to the plan strategy's required-flag check.
  */
-export default defineCommand({
-  description: "Create a model deployment",
+function validateCreate(modality: DeployModality, flags: CreatePlanFlags): string | undefined {
+  const plan = flags.plan || defaultDeployPlan(modality);
+  const strategy = STRATEGIES[plan];
+  if (!strategy) {
+    return `Unsupported plan "${plan}". Supported plans: ${Object.keys(STRATEGIES).join(", ")}.`;
+  }
+  return strategy.validateFlags(flags);
+}
+
+/**
+ * Shared `deploy <modality> create` implementation. deploy create takes a model
+ * by name and a billing plan — it does NOT inspect data modality for the request
+ * body, so the run logic is identical across text / audio / image. The modality
+ * only fixes the default plan (audio → mu, text/image → lora) and the command
+ * path / description / examples.
+ *
+ * Plan-specific behaviour (required flags / body assembly / auto-pick) lives in
+ * core `plans.ts` (`PlanStrategy` + `STRATEGIES`). This file only handles the
+ * shared envelope: dispatch, dry-run, and result formatting.
+ */
+async function runCreate(
+  modality: DeployModality,
+  ctx: CommandContext<typeof CREATE_FLAGS>,
+): Promise<void> {
+  const { identity, settings, flags } = ctx;
+  const model = flags.model as string;
+  const name = flags.name as string;
+  const plan = (flags.plan as string | undefined) || defaultDeployPlan(modality);
+  const format = detectOutputFormat(settings.output);
+
+  // Plan-specific behaviour is owned by core `plans.ts`. The strategy resolves
+  // the plan-specific body fragment (mu may auto-pick a template from the
+  // deployable-models catalog). Anything outside the strategy table was
+  // already rejected by `validate` above.
+  const strategy = pickPlanStrategy(plan);
+
+  const resolved = await strategy.resolve({
+    client: ctx.client,
+    dryRun: settings.dryRun,
+    binName: identity.binName,
+    flags: flags as CreatePlanFlags,
+    model,
+    name,
+  });
+  const body: Record<string, unknown> = {
+    model_name: model,
+    name,
+    plan,
+    ...resolved.body,
+  };
+
+  if (settings.dryRun) {
+    emitResult({ action: "deploy.create", body }, format);
+    return;
+  }
+
+  const response = await createDeployment(ctx.client, body as CreateDeploymentRequest);
+  const deployment = response.output ?? response.data;
+
+  if (settings.quiet) {
+    emitBare(deployment?.deployed_model ?? "");
+  } else if (format === "text") {
+    emitBare(`Created deployment.`);
+    if (deployment?.deployed_model) emitBare(`  deployed_model:  ${deployment.deployed_model}`);
+    if (deployment?.status) emitBare(`  status:          ${deployment.status}`);
+    if (deployment?.plan) emitBare(`  plan:            ${deployment.plan}`);
+    emitBare(
+      `\nNext: track readiness with: ${identity.binName} deploy get --deployed-model ${deployment?.deployed_model ?? "<id>"}`,
+    );
+  } else {
+    emitResult(response, format);
+  }
+}
+
+/** `bl deploy text create` — deploy a text model. */
+export const deployTextCreate = defineCommand({
+  description: "Create a text model deployment",
   auth: "apiKey",
-  usageArgs:
-    "--model <model_name> --name <display_name> [--plan <plan>] [--template-id <id>] [--capacity <n>] [--billing-method <m>] [--input-tpm <n>] [--output-tpm <n>] [--thinking-output-tpm <n>]",
+  usageArgs: CREATE_USAGE,
   flags: CREATE_FLAGS,
   exampleArgs: [
     "--model my-qwen-sft --name my-sft-test",
     "--model qwen3.6-flash-2026-04-16 --name my-flash --plan ptu --input-tpm 10000 --output-tpm 1000",
     "--model qwen3-8b --name my-qwen3-mu --plan mu",
-    "--model qwen3-8b --name my-qwen3 --plan mu --template-id MU1 --capacity 2",
+    "--model qwen3-8b --name my-qwen3 --plan mu --deploy-spec MU1 --capacity 2",
   ],
-  notes: [
-    "Plan defaults to `lora` (Token-billed). Pass --plan to override.",
-    "For plan=ptu (Token-billed, provisioned throughput), --input-tpm and",
-    "--output-tpm are required (the platform rejects creation without an",
-    "explicit ptu_capacity despite the doc listing defaults).",
-    "For plan=mu, `capacity`, `billing_method` and `template_id` are required.",
-    "billing_method defaults to POST_PAY (only supported value); template_id",
-    "and capacity are auto-picked from GET /deployments/models when omitted.",
-    "Use `bl deploy models --source base` to inspect available templates.",
-    "After creation, status starts at PENDING and transitions to RUNNING.",
-    "Invoke the deployed model with: bl text chat --model <deployed_model>",
-    "WARNING: --model is overloaded across commands and refers to DIFFERENT",
-    "values. `bl deploy create --model` takes the exported model_name (e.g.",
-    "`qwen3-8b-ft-...`), but the create response also returns a `deployed_model`",
-    "field (the deployment instance id, e.g. `qwen3-8b-5ecb5f068d79`). The",
-    "inference call `bl text chat --model` must use the `deployed_model` from",
-    "the create response — NOT the `model_name` you passed to `deploy create`.",
-    "Do not reuse the value across the two commands.",
-  ],
-  validate: (flags) => {
-    const plan = flags.plan || "lora";
-    const strategy = STRATEGIES[plan];
-    if (!strategy) {
-      return `Unsupported plan "${plan}". Supported plans: ${Object.keys(STRATEGIES).join(", ")}.`;
-    }
-    return strategy.validateFlags(flags);
-  },
-  async run(ctx) {
-    const { identity, settings, flags } = ctx;
-    const model = flags.model;
-    const name = flags.name;
-    const plan = flags.plan || "lora";
-    const format = detectOutputFormat(settings.output);
-
-    // Plan-specific behaviour is owned by `plans.ts`. The strategy resolves
-    // the plan-specific body fragment (mu may auto-pick a template from the
-    // deployable-models catalog). Anything outside the strategy table was
-    // already rejected by `validate` above.
-    const strategy = pickPlanStrategy(plan);
-
-    const resolved = await strategy.resolve({
-      client: ctx.client,
-      dryRun: settings.dryRun,
-      binName: identity.binName,
-      flags,
-      model,
-      name,
-    });
-    const body: Record<string, unknown> = {
-      model_name: model,
-      name,
-      plan,
-      ...resolved.body,
-    };
-
-    if (settings.dryRun) {
-      emitResult({ action: "deploy.create", body }, format);
-      return;
-    }
-
-    const response = await createDeployment(ctx.client, body as CreateDeploymentRequest);
-    const deployment = response.output ?? response.data;
-
-    if (settings.quiet) {
-      emitBare(deployment?.deployed_model ?? "");
-    } else if (format === "text") {
-      emitBare(`Created deployment.`);
-      if (deployment?.deployed_model) emitBare(`  deployed_model:  ${deployment.deployed_model}`);
-      if (deployment?.status) emitBare(`  status:          ${deployment.status}`);
-      if (deployment?.plan) emitBare(`  plan:            ${deployment.plan}`);
-      emitBare(
-        `\nNext: track readiness with: ${identity.binName} deploy get --deployed-model ${deployment?.deployed_model ?? "<id>"}`,
-      );
-    } else {
-      emitResult(response, format);
-    }
-  },
+  notes: CREATE_NOTES,
+  validate: (flags) => validateCreate("text", flags),
+  run: (ctx) => runCreate("text", ctx),
+});
+
+/** `bl deploy audio create` — deploy an audio (TTS) model. Defaults to plan=mu. */
+export const deployAudioCreate = defineCommand({
+  description: "Create an audio (TTS) model deployment",
+  auth: "apiKey",
+  usageArgs: CREATE_USAGE,
+  flags: CREATE_FLAGS,
+  exampleArgs: [
+    "--model my-cosyvoice-ft --name my-tts",
+    "--model my-cosyvoice-ft --name my-tts --deploy-spec dps-xxxx --capacity 1",
+    "--model my-cosyvoice-ft --name my-tts --dry-run",
+  ],
+  notes: CREATE_NOTES,
+  validate: (flags) => validateCreate("audio", flags),
+  run: (ctx) => runCreate("audio", ctx),
+});
+
+/** `bl deploy image create` — deploy an image generation model. */
+export const deployImageCreate = defineCommand({
+  description: "Create an image generation model deployment",
+  auth: "apiKey",
+  usageArgs: CREATE_USAGE,
+  flags: CREATE_FLAGS,
+  exampleArgs: [
+    "--model my-wan-ft --name my-wan",
+    "--model my-wan-ft --name my-wan-mu --plan mu",
+    "--model my-wan-ft --name my-wan --dry-run",
+  ],
+  notes: CREATE_NOTES,
+  validate: (flags) => validateCreate("image", flags),
+  run: (ctx) => runCreate("image", ctx),
 });

packages/commands/src/commands/deploy/delete.ts

@@ -59,8 +59,8 @@ export default defineCommand({
             ExitCode.USAGE,
           );
         }
-      } catch (e) {
-        if (e instanceof BailianError) throw e;
+      } catch (error) {
+        if (error instanceof BailianError) throw error;
         // If the get itself failed (e.g. not found), let the DELETE call surface the real error.
       }
     }

packages/commands/src/commands/deploy/list.ts

@@ -68,13 +68,13 @@ export default defineCommand({
       return;
     }
     const headers = ["DEPLOYED_MODEL", "MODEL_NAME", "STATUS", "PLAN", "CAPACITY", "CREATED_AT"];
-    const rows = items.map((i) => [
-      i.deployed_model,
-      i.model_name,
-      i.status,
-      i.plan,
-      i.capacity,
-      i.created_at,
+    const rows = items.map((item) => [
+      item.deployed_model,
+      item.model_name,
+      item.status,
+      item.plan,
+      item.capacity,
+      item.created_at,
     ]);
     for (const line of formatTable(headers, rows)) emitBare(line);
     if (total !== undefined) emitBare(`\nTotal: ${total}`);

packages/commands/src/commands/deploy/models.ts

@@ -73,47 +73,47 @@ export default defineCommand({
     //   - custom (fine-tuned): top-level supported_plans: string[]
     //   - base (catalog):      plans: [{plan, templates?, cu_specs?}]
     // For json: surface the deployment-relevant fields preserved as a tree, so
-    // downstream tooling can drive `bl deploy create --template-id <…>` without
-    // a second round-trip. For text: keep the compact one-line summary.
+    // downstream tooling can drive `bl deploy <modality> create --deploy-spec <…>`
+    // without a second round-trip. For text: keep the compact one-line summary.
     if (format === "json") {
-      const items = models.map((m) => {
+      const items = models.map((model) => {
         const out: Record<string, unknown> = {
-          model_name: m.model_name ?? "",
+          model_name: model.model_name ?? "",
         };
-        if (m.base_model) out.base_model = m.base_model;
-        if (m.model_source) out.model_source = m.model_source;
-        if (m.supported_plans && m.supported_plans.length > 0) {
-          out.supported_plans = m.supported_plans;
+        if (model.base_model) out.base_model = model.base_model;
+        if (model.model_source) out.model_source = model.model_source;
+        if (model.supported_plans && model.supported_plans.length > 0) {
+          out.supported_plans = model.supported_plans;
         }
-        if (m.plans && m.plans.length > 0) {
-          out.plans = m.plans.map((p) => {
-            const planEntry: Record<string, unknown> = { plan: p.plan ?? "" };
-            if (p.cu_specs && p.cu_specs.length > 0) {
-              planEntry.cu_specs = p.cu_specs;
+        if (model.plans && model.plans.length > 0) {
+          out.plans = model.plans.map((plan) => {
+            const planEntry: Record<string, unknown> = { plan: plan.plan ?? "" };
+            if (plan.cu_specs && plan.cu_specs.length > 0) {
+              planEntry.cu_specs = plan.cu_specs;
             }
-            if (p.templates && p.templates.length > 0) {
-              // Pull the top 6 fields most useful for `bl deploy create`.
+            if (plan.templates && plan.templates.length > 0) {
+              // Pull the top 6 fields most useful for `bl deploy <modality> create`.
               // Drop noisy/redundant: template_source, template_type,
               // template_version, deploy_spec (typically == template_id).
-              planEntry.templates = p.templates.map((t) => {
+              planEntry.templates = plan.templates.map((template) => {
                 const tpl: Record<string, unknown> = {};
-                if (t.template_id) tpl.template_id = t.template_id;
-                if (t.template_name) tpl.template_name = t.template_name;
-                if (t.charge_type) tpl.charge_type = t.charge_type;
+                if (template.template_id) tpl.template_id = template.template_id;
+                if (template.template_name) tpl.template_name = template.template_name;
+                if (template.charge_type) tpl.charge_type = template.charge_type;
                 // Flatten roles.unified for the common COUPLED case.
-                const unified = t.roles?.unified;
+                const unified = template.roles?.unified;
                 if (unified?.model_unit_spec) tpl.model_unit_spec = unified.model_unit_spec;
                 if (unified?.capacity_unit_per_instance !== undefined)
                   tpl.capacity_unit_per_instance = unified.capacity_unit_per_instance;
                 // Preserve split-role configs (SEPERATED) as-is so callers
                 // can still drive prefill/decode sizing.
-                if (t.roles?.prefill || t.roles?.decode) {
+                if (template.roles?.prefill || template.roles?.decode) {
                   tpl.roles = {
-                    prefill: t.roles?.prefill,
-                    decode: t.roles?.decode,
+                    prefill: template.roles?.prefill,
+                    decode: template.roles?.decode,
                   };
                 }
-                if (t.template_desc) tpl.template_desc = t.template_desc;
+                if (template.template_desc) tpl.template_desc = template.template_desc;
                 return tpl;
               });
             }
@@ -127,19 +127,19 @@ export default defineCommand({
     }
 
     // text / quiet — keep the compact single-line summary table.
-    const textItems = models.map((m) => {
+    const textItems = models.map((model) => {
       let plansSummary = "";
-      if (m.supported_plans && m.supported_plans.length > 0) {
-        plansSummary = m.supported_plans.join(",");
-      } else if (m.plans && m.plans.length > 0) {
-        plansSummary = m.plans
-          .map((p) => {
-            const planName = p.plan ?? "?";
-            if (p.templates && p.templates.length > 0) {
-              return `${planName}(${p.templates.length}t)`;
+      if (model.supported_plans && model.supported_plans.length > 0) {
+        plansSummary = model.supported_plans.join(",");
+      } else if (model.plans && model.plans.length > 0) {
+        plansSummary = model.plans
+          .map((plan) => {
+            const planName = plan.plan ?? "?";
+            if (plan.templates && plan.templates.length > 0) {
+              return `${planName}(${plan.templates.length}t)`;
             }
-            if (p.cu_specs && p.cu_specs.length > 0) {
-              return `${planName}(${p.cu_specs.join("/")})`;
+            if (plan.cu_specs && plan.cu_specs.length > 0) {
+              return `${planName}(${plan.cu_specs.join("/")})`;
             }
             return planName;
           })
@@ -148,9 +148,9 @@ export default defineCommand({
         plansSummary = "-";
       }
       return {
-        model_name: m.model_name ?? "",
-        base_model: m.base_model ?? "",
-        source: m.model_source ?? "",
+        model_name: model.model_name ?? "",
+        base_model: model.base_model ?? "",
+        source: model.model_source ?? "",
         plans: plansSummary,
       };
     });
@@ -160,7 +160,12 @@ export default defineCommand({
       return;
     }
     const headers = ["MODEL_NAME", "BASE_MODEL", "SOURCE", "PLANS"];
-    const rows = textItems.map((i) => [i.model_name, i.base_model, i.source, i.plans]);
+    const rows = textItems.map((item) => [
+      item.model_name,
+      item.base_model,
+      item.source,
+      item.plans,
+    ]);
     for (const line of formatTable(headers, rows)) emitBare(line);
     if (total !== undefined) emitBare(`\nTotal: ${total}`);
   },

packages/commands/src/commands/finetune/create.ts

@@ -4,12 +4,12 @@ import {
   createFineTune,
   getDataset,
   uploadDataset,
-  validateDataset,
+  detectModality,
+  getProfile,
   fetchModelCapability,
   listSupportedTrainingTypes,
   preflightBatchSizeGate,
   isTrainingTypeCli,
-  toServerTrainingType,
   TRAINING_TYPES_CLI,
   DEFAULT_TRAINING_TYPE,
   formatIssue,
@@ -17,10 +17,12 @@ import {
   ExitCode,
   type Client,
   type Settings,
+  type CommandContext,
   type CreateFineTuneRequest,
   type FineTuneHyperParameters,
   type DatasetFile,
-  type DatasetSchema,
+  type TrainingProfile,
+  type DataModality,
   type FlagsDef,
 } from "bailian-cli-core";
 import { existsSync, statSync } from "fs";
@@ -77,7 +79,11 @@ async function analyzeDatasetTokens(
   binName: string,
   raw: string,
   label: string,
-  schema?: DatasetSchema,
+  profile: TrainingProfile,
+  modality: DataModality,
+  model: string,
+  /** Pre-detected modality for a known path (avoids re-opening the file). */
+  knownModality?: { path: string; modality: DataModality },
 ): Promise<ResolvedDataset> {
   const tokens = raw
     .split(",")
@@ -109,11 +115,18 @@ async function analyzeDatasetTokens(
 
     if (settings.dryRun) continue;
 
-    // Local path → validate (same checks as `dataset upload`). Upload is
-    // deferred to `uploadResolvedLocal` so the gate can run first. The schema
-    // (SFT vs DPO) is derived from --training-type so a DPO job validates the
-    // chosen/rejected preference pairs here, not on the platform.
-    const result = await validateDataset(token, { schema });
+    // The command's modality is authoritative; each local file is validated
+    // under that modality's schema. Reuse the caller's pre-detected modality
+    // when available to avoid opening the same file twice (matters for large
+    // ZIPs).
+    const tokenModality =
+      knownModality && knownModality.path === token ? knownModality.modality : modality;
+
+    // Local path → validate through the profile. The profile internally routes
+    // to the correct validator based on modality. Upload is deferred to
+    // `uploadResolvedLocal` so the gate can run first. `model` is forwarded for
+    // schema-agnostic cross-checks.
+    const result = await profile.validate(token, tokenModality, { model });
     if (!result.valid) {
       const lines = [
         `Dataset validation failed for ${token}`,
@@ -194,25 +207,33 @@ async function uploadResolvedLocal(
   return uploaded;
 }
 
-const CREATE_FLAGS = {
+/** The modality a `finetune <modality> create` subcommand is bound to. */
+type CommandModality = "text" | "audio" | "image";
+
+/**
+ * Flags shared by every `finetune <modality> create` subcommand: what to train
+ * (model), what data to train on (datasets / validations), and how to name the
+ * output. Every modality's model consumes these.
+ */
+const COMMON_FLAGS = {
   model: {
     type: "string",
     valueHint: "<model>",
-    description: "Base model to fine-tune (e.g. qwen3-8b, qwen3-14b)",
+    description: "Base model to fine-tune",
     required: true,
   },
   datasets: {
     type: "string",
     valueHint: "<ids|paths>",
     description:
-      "Comma-separated dataset file IDs or local .jsonl paths. Local paths are uploaded (validated) first, then their file-ids are used.",
+      "Comma-separated dataset file IDs or local paths (.jsonl for text, .zip for audio/image). Local paths are uploaded (validated) first, then their file-ids are used.",
     required: true,
   },
   validations: {
     type: "string",
     valueHint: "<ids|paths>",
     description:
-      "Comma-separated validation dataset file IDs or local .jsonl paths (auto-uploaded like --datasets).",
+      "Comma-separated validation dataset file IDs or local paths (auto-uploaded like --datasets).",
   },
   modelName: {
     type: "string",
@@ -224,6 +245,16 @@ const CREATE_FLAGS = {
     valueHint: "<text>",
     description: "Output suffix appended by the platform (finetuned_output_suffix)",
   },
+} satisfies FlagsDef;
+
+/**
+ * Text flags: text models consume the full hyper-parameter surface — training
+ * type selection plus n_epochs / batch_size / learning_rate / max_length (see
+ * resolveTextHyperParameters). Only text exposes --training-type because only
+ * text models support types other than the sft-lora default.
+ */
+const TEXT_FLAGS = {
+  ...COMMON_FLAGS,
   trainingType: {
     type: "string",
     valueHint: "<t>",
@@ -252,12 +283,368 @@ const CREATE_FLAGS = {
   },
 } satisfies FlagsDef;
 
-export default defineCommand({
-  description: "Create a fine-tune job (sft | sft-lora | dpo | dpo-lora | cpt)",
+/**
+ * Audio (CosyVoice TTS) flags: the audio model runs sft-lora with a fully fixed
+ * hyper-parameter set (AUDIO_HYPER_PARAMS). No --training-type or hyper-parameter
+ * flag is honored by resolveHyperParameters, so none are exposed.
+ */
+const AUDIO_FLAGS = {
+  ...COMMON_FLAGS,
+} satisfies FlagsDef;
+
+/**
+ * Image (Wan generation) flags: the image model runs sft-lora with fixed
+ * defaults; resolveHyperParameters only honors learning_rate, so --learning-rate
+ * is the sole extra numeric knob. --generation-type declares T2I vs I2I
+ * explicitly (the platform expects generation_type as a request field); it is
+ * required to reach I2I from a bare file-id or in --dry-run, where the data
+ * cannot be inspected.
+ */
+const IMAGE_FLAGS = {
+  ...COMMON_FLAGS,
+  generationType: {
+    type: "string",
+    choices: ["t2i", "i2i"] as const,
+    valueHint: "<t2i|i2i>",
+    description:
+      "Generation type: t2i (default) | i2i. Sets generation_type/max_pixels. Required to train I2I from a file-id or with --dry-run (local data auto-detects input_img).",
+  },
+  learningRate: {
+    type: "string",
+    valueHint: "<str>",
+    description: 'Learning rate as a string to preserve precision (e.g. "3e-5")',
+  },
+} satisfies FlagsDef;
+
+const TEXT_USAGE =
+  "--model <model> --datasets <id|path,...> [--validations <id|path,...>] [--model-name <name>] [--suffix <text>] [--n-epochs <n>] [--batch-size <n>] [--learning-rate <str>] [--max-length <n>] [--training-type <sft|sft-lora|dpo|dpo-lora|cpt>]";
+
+const AUDIO_USAGE =
+  "--model <model> --datasets <id|path> [--validations <id|path>] [--model-name <name>] [--suffix <text>]";
+
+const IMAGE_USAGE =
+  "--model <model> --datasets <id|path> [--validations <id|path>] [--model-name <name>] [--suffix <text>] [--generation-type <t2i|i2i>] [--learning-rate <str>]";
+
+const COMMON_NOTES = [
+  "Creating a job uploads any local datasets and consumes training quota.",
+  "Use --dry-run to preview the request body without submitting.",
+  "--datasets / --validations accept either file-ids (from `dataset upload`)",
+  "or local paths. Local paths are validated and uploaded first, then their",
+  "file-ids are submitted — a one-step upload-and-train.",
+];
+
+const TEXT_NOTES = [
+  ...COMMON_NOTES,
+  "Training-type values use the `<method>` / `<method>-lora` convention:",
+  "sft (full) | sft-lora (LoRA) | dpo (full) | dpo-lora (LoRA) | cpt. These map",
+  "to the server's training_type at the interface boundary, so the rest of the",
+  "CLI never sees the raw server strings.",
+  "Before submitting (non dry-run) the job, the model's training capability is",
+  "checked via listFoundationModels (no console login required); an unsupported",
+  "training type fails fast with the list the model actually supports.",
+  "n_epochs defaults to 3. Other hyper-parameters are platform defaults unless set.",
+  "Learning rate is forwarded as a string to avoid JSON-number precision loss.",
+  "Pre-submit gate: if the training dataset's sample count is not greater",
+  "than batch_size, the job is rejected before upload or quota consumption",
+  "(the platform would otherwise fail ~10 min in, after data processing).",
+];
+
+const AUDIO_NOTES = [
+  ...COMMON_NOTES,
+  "Audio TTS training runs sft-lora (efficient_sft) with fixed CosyVoice",
+  "hyper-parameter defaults; there are no training-type or hyper-parameter",
+  "knobs to set.",
+];
+
+const IMAGE_NOTES = [
+  ...COMMON_NOTES,
+  "Image generation training runs sft-lora (efficient_sft) with fixed defaults;",
+  "only --learning-rate is overridable. T2I vs I2I is declared with",
+  "--generation-type (default t2i), which sets generation_type/max_pixels. For",
+  "local data the type is auto-detected (records with input_img train I2I);",
+  "pass --generation-type explicitly to train I2I from a file-id or in --dry-run.",
+];
+
+/**
+ * Shared `finetune <modality> create` implementation. The parameter surface and
+ * run logic are identical to the previous single `finetune create`; the ONLY
+ * change is that the data modality is fixed by the subcommand instead of being
+ * detected from data content. This is what lets file-id datasets (which have no
+ * local file to inspect) train the correct model — the old command silently
+ * defaulted a file-id to "text".
+ *
+ * Image is the only modality with a sub-variant (T2I vs I2I). It is upgraded to
+ * `image-i2i` only when a local file's first record carries `input_img`; a bare
+ * file-id defaults to plain "image" (T2I), matching the old detection fallback.
+ */
+async function runCreate<F extends FlagsDef>(
+  commandModality: CommandModality,
+  ctx: CommandContext<F>,
+): Promise<void> {
+  const { identity, settings } = ctx;
+  const flags = ctx.flags as Record<string, unknown>;
+  const model = flags.model as string;
+  const datasetsRaw = flags.datasets as string;
+
+  // CosyVoice audio fine-tuning accepts exactly one training file
+  // (`training_file_ids` supports a single ID per the speech-synthesis
+  // contract). Reject a multi-token --datasets up-front so the job isn't
+  // rejected server-side after an upload.
+  if (commandModality === "audio") {
+    const audioTokens = datasetsRaw
+      .split(",")
+      .map((token) => token.trim())
+      .filter(Boolean);
+    if (audioTokens.length > 1) {
+      throw new BailianError(
+        `Audio (TTS) fine-tuning accepts exactly one training file, got ${audioTokens.length}.`,
+        ExitCode.USAGE,
+        "Merge your recordings into a single .zip (or pass one file-id).",
+      );
+    }
+  }
+
+  // Resolve the training type before analyzing datasets so the validator can
+  // enforce the right record schema (DPO jobs require chosen/rejected on
+  // every record). Whitelist is the single source of truth in core
+  // (TRAINING_TYPES_CLI); any other value is rejected up-front.
+  const trainingType = (flags.trainingType as string | undefined) || DEFAULT_TRAINING_TYPE;
+  if (!isTrainingTypeCli(trainingType)) {
+    throw new BailianError(
+      `--training-type "${trainingType}" is not supported.`,
+      ExitCode.USAGE,
+      `Supported values: ${TRAINING_TYPES_CLI.join(", ")} (default: ${DEFAULT_TRAINING_TYPE}).`,
+    );
+  }
+
+  // Profile: single source of truth for how this training type behaves
+  // (validation rules, hyper-parameters, gates, capability check).
+  const profile = getProfile(trainingType);
+
+  // Modality is fixed by the subcommand (no content-based detection) — this is
+  // the sole behavioural change of the modality split. Image alone has a T2I/I2I
+  // sub-variant: an explicit --generation-type is authoritative (the only way to
+  // reach I2I from a bare file-id or in --dry-run, where data can't be
+  // inspected); otherwise a local file is probed to upgrade T2I → I2I, and a
+  // bare file-id stays "image" (T2I).
+  const firstLocalPath = datasetsRaw
+    .split(",")
+    .map((token) => token.trim())
+    .find((token) => isLocalPath(token));
+  let modality: DataModality = commandModality;
+  if (commandModality === "image") {
+    const generationType = flags.generationType as "t2i" | "i2i" | undefined;
+    if (generationType === "i2i") {
+      modality = "image-i2i";
+    } else if (!generationType && firstLocalPath && !settings.dryRun) {
+      const detected = await detectModality(firstLocalPath);
+      if (detected === "image-i2i") modality = "image-i2i";
+    }
+  }
+
+  const training = await analyzeDatasetTokens(
+    settings,
+    identity.binName,
+    datasetsRaw,
+    "datasets",
+    profile,
+    modality,
+    model,
+    firstLocalPath ? { path: firstLocalPath, modality } : undefined,
+  );
+  const trainingFileIds = training.fileIds;
+
+  const validation = flags.validations
+    ? await analyzeDatasetTokens(
+        settings,
+        identity.binName,
+        flags.validations as string,
+        "validations",
+        profile,
+        modality,
+        model,
+      )
+    : undefined;
+  const validationFileIds = validation?.fileIds;
+
+  const modelName = flags.modelName as string | undefined;
+  const suffix = flags.suffix as string | undefined;
+
+  // Hyper-parameters: the profile resolves modality-specific defaults
+  // (text: n_epochs/batch_size/learning_rate; audio: lm_max_epoch/fm_max_epoch/...).
+  const hp = profile.resolveHyperParameters(
+    modality,
+    flags as Record<string, unknown>,
+  ) as FineTuneHyperParameters;
+
+  // Restore the batch-size clamping warning that was lost when the logic moved
+  // into profiles. The profile silently clamps to [8, 1024]; surface it here
+  // so the user has an audit trail. Skip modalities that bypass the batch_size
+  // gate (image): their batch_size is a fixed model-family default, not a
+  // clamp of the user's value, so the [8, 1024] "clamped" message would be
+  // self-contradictory and misleading.
+  if (
+    flags.batchSize !== undefined &&
+    hp.batch_size !== undefined &&
+    !settings.quiet &&
+    !profile.shouldSkipGate("batch_size", modality)
+  ) {
+    const requested = flags.batchSize as number;
+    if (hp.batch_size !== requested) {
+      process.stderr.write(
+        `warning: --batch-size ${requested} clamped to ${hp.batch_size} ` +
+          `(server range [8, 1024] for the common training types).\n`,
+      );
+    }
+  }
+  // For modalities that skip the batch_size gate, warn the user that their
+  // explicit --batch-size was discarded (model uses a fixed batch_size).
+  if (
+    flags.batchSize !== undefined &&
+    !settings.quiet &&
+    profile.shouldSkipGate("batch_size", modality)
+  ) {
+    const requested = flags.batchSize as number;
+    if (hp.batch_size !== undefined && hp.batch_size !== requested) {
+      process.stderr.write(
+        `warning: --batch-size ${requested} ignored for ${modality} training ` +
+          `(model uses a fixed batch_size of ${hp.batch_size}).\n`,
+      );
+    }
+  }
+
+  // Auto batch_size for small datasets — only for text data. Audio/image
+  // profiles already set their own batch parameters.
+  if (modality === "text" && hp.batch_size === undefined && !settings.dryRun) {
+    let sizeBytes = training.firstSize ?? 0;
+    if (sizeBytes === 0) {
+      try {
+        const fileInfo = await getDataset(ctx.client, trainingFileIds[0]);
+        sizeBytes = fileInfo.data?.size ?? 0;
+      } catch {
+        // If we can't fetch file info, skip auto-adjustment; platform will use default.
+      }
+    }
+    if (sizeBytes > 0 && sizeBytes < 100 * 1024) {
+      hp.batch_size = 8;
+    }
+  }
+
+  // Pre-submit batch-size gate: the platform rejects a job whose number of
+  // training samples is not greater than batch_size, but only surfaces that
+  // ~10 minutes into the run (after data processing). Fail fast here, before
+  // burning quota. `recordCount` is only known when every --datasets token
+  // was a local file we validated; file-id tokens fall through to the
+  // platform rather than risk a false positive from an undercount.
+  if (
+    !settings.dryRun &&
+    training.recordCount !== undefined &&
+    !profile.shouldSkipGate("batch_size", modality)
+  ) {
+    // 16 is the platform default when neither the user nor the small-file
+    // auto-adjust set a batch_size (see the auto-adjust comment above).
+    const effectiveBatchSize = hp.batch_size ?? 16;
+    const gate = preflightBatchSizeGate({
+      recordCount: training.recordCount,
+      batchSize: effectiveBatchSize,
+    });
+    if (!gate.ok && gate.issue) {
+      throw new BailianError(gate.issue.message, ExitCode.GENERAL, gate.hint);
+    }
+  }
+
+  // Pre-flight capability check: confirm the model actually supports the
+  // requested training type BEFORE any upload, so a wrong --model /
+  // --training-type combo doesn't burn storage on datasets that will never
+  // be trained against. listFoundationModels is a public API (no console
+  // login required); on lookup failure (network / 401 / etc.) we fall back
+  // to letting the server decide rather than blocking the submit.
+  if (!settings.dryRun && !profile.shouldSkipCapabilityCheck(modality)) {
+    let capability: Awaited<ReturnType<typeof fetchModelCapability>> | undefined;
+    try {
+      capability = await fetchModelCapability(settings, model);
+    } catch (error) {
+      if (!settings.quiet) {
+        process.stderr.write(
+          `warning: model capability lookup failed (${(error as Error).message}); ` +
+            "proceeding without local pre-flight.\n",
+        );
+      }
+    }
+    if (capability && !listSupportedTrainingTypes(capability).includes(trainingType)) {
+      const supported = listSupportedTrainingTypes(capability);
+      throw new BailianError(
+        `Model "${model}" does not support training type "${trainingType}".`,
+        ExitCode.USAGE,
+        supported.length
+          ? `This model supports: ${supported.join(", ")}.`
+          : "This model reports no supported training types.",
+      );
+    }
+  }
+
+  // Upload local paths now that pre-flight (validation, batch-size gate,
+  // capability check) has cleared them. This swaps the placeholder path
+  // entries in `training.fileIds` / `validation?.fileIds` for real file-ids.
+  if (!settings.dryRun) {
+    await uploadResolvedLocal(ctx.client, settings, training, "fine-tune", "datasets");
+    if (validation) {
+      await uploadResolvedLocal(ctx.client, settings, validation, "fine-tune", "validations");
+    }
+  }
+
+  const body: CreateFineTuneRequest = {
+    model,
+    training_file_ids: trainingFileIds,
+    // Profile maps the CLI training type to the server value at the boundary.
+    training_type: profile.serverTrainingType,
+    hyper_parameters: hp,
+  };
+  if (validationFileIds && validationFileIds.length > 0) {
+    body.validation_file_ids = validationFileIds;
+  }
+  if (modelName) body.model_name = modelName;
+  if (suffix) body.finetuned_output_suffix = suffix;
+
+  const format = detectOutputFormat(settings.output);
+
+  if (settings.dryRun) {
+    const pending = [
+      ...training.localPaths.map((path) => ({ field: "datasets", path })),
+      ...(validation?.localPaths ?? []).map((path) => ({ field: "validations", path })),
+    ];
+    emitResult(
+      pending.length > 0
+        ? { action: "finetune.create", body, pending_uploads: pending }
+        : { action: "finetune.create", body },
+      format,
+    );
+    return;
+  }
+
+  const response = await createFineTune(ctx.client, body);
+  const job = response.output ?? response.data;
+
+  if (settings.quiet) {
+    if (job?.job_id) emitBare(job.job_id);
+  } else if (format === "text") {
+    if (job?.job_id) {
+      emitBare(`Created fine-tune job: ${job.job_id}`);
+      if (job.status) emitBare(`Status: ${job.status}`);
+    } else {
+      emitResult(response, format);
+    }
+  } else {
+    emitResult(response, format);
+  }
+}
+
+/** `bl finetune text create` — fine-tune a text model. Datasets are `.jsonl`. */
+export const finetuneTextCreate = defineCommand({
+  description: "Create a text model fine-tune job (sft | sft-lora | dpo | dpo-lora | cpt)",
   auth: "apiKey",
-  usageArgs:
-    "--model <model> --datasets <id|path,...> [--validations <id|path,...>] [--model-name <name>] [--suffix <text>] [--n-epochs <n>] [--batch-size <n>] [--learning-rate <str>] [--max-length <n>] [--training-type <sft|sft-lora|dpo|dpo-lora|cpt>]",
-  flags: CREATE_FLAGS,
+  usageArgs: TEXT_USAGE,
+  flags: TEXT_FLAGS,
   exampleArgs: [
     "--model qwen3-8b --datasets file-xxx",
     "--model qwen3-8b --datasets ./train.jsonl",
@@ -268,231 +655,41 @@ export default defineCommand({
     "--model qwen3-8b --datasets file-xxx --output json",
     "--model qwen3-8b --datasets file-xxx --dry-run",
   ],
-  notes: [
-    "Creating a job uploads any local datasets and consumes training quota.",
-    "Use --dry-run to preview the request body without submitting.",
-    "Training-type values use the `<method>` / `<method>-lora` convention:",
-    "sft (full) | sft-lora (LoRA) | dpo (full) | dpo-lora (LoRA) | cpt. These map",
-    "to the server's training_type at the interface boundary, so the rest of the",
-    "CLI never sees the raw server strings.",
-    "Before submitting (non dry-run) the job, the model's training capability is",
-    "checked via listFoundationModels (no console login required); an unsupported",
-    "training type fails fast with the list the model actually supports.",
-    "n_epochs defaults to 3. Other hyper-parameters are platform defaults unless set.",
-    "Learning rate is forwarded as a string to avoid JSON-number precision loss.",
-    "--datasets / --validations accept either file-ids (from `dataset upload`)",
-    "or local .jsonl paths. Local paths are validated and uploaded first, then",
-    "their file-ids are submitted — a one-step upload-and-train.",
-    "Dataset record schema is chosen from --training-type: dpo* → {messages,",
-    "chosen, rejected}; cpt → {text} (raw pre-training text); else {messages}.",
-    "Pre-submit gate: if the training dataset's sample count is not greater",
-    "than batch_size, the job is rejected before upload or quota consumption",
-    "(the platform would otherwise fail ~10 min in, after data processing).",
-  ],
-  async run(ctx) {
-    const { identity, settings, flags } = ctx;
-    const model = flags.model;
-    const datasetsRaw = flags.datasets;
-
-    // Resolve the training type before analyzing datasets so the validator can
-    // enforce the right record schema (DPO jobs require chosen/rejected on
-    // every record). Whitelist is the single source of truth in core
-    // (TRAINING_TYPES_CLI); any other value is rejected up-front.
-    const trainingType = flags.trainingType || DEFAULT_TRAINING_TYPE;
-    if (!isTrainingTypeCli(trainingType)) {
-      throw new BailianError(
-        `--training-type "${trainingType}" is not supported.`,
-        ExitCode.USAGE,
-        `Supported values: ${TRAINING_TYPES_CLI.join(", ")} (default: ${DEFAULT_TRAINING_TYPE}).`,
-      );
-    }
-    // dpo / dpo-lora → "dpo" schema (strict chosen/rejected); cpt → "cpt"
-    // (raw {text} records); else ChatML ({messages}).
-    const datasetSchema: DatasetSchema = trainingType.startsWith("dpo")
-      ? "dpo"
-      : trainingType === "cpt"
-        ? "cpt"
-        : "chatml";
-
-    const training = await analyzeDatasetTokens(
-      settings,
-      identity.binName,
-      datasetsRaw,
-      "datasets",
-      datasetSchema,
-    );
-    const trainingFileIds = training.fileIds;
-
-    const validation = flags.validations
-      ? await analyzeDatasetTokens(
-          settings,
-          identity.binName,
-          flags.validations,
-          "validations",
-          datasetSchema,
-        )
-      : undefined;
-    const validationFileIds = validation?.fileIds;
-
-    const modelName = flags.modelName;
-    const suffix = flags.suffix;
-
-    // Hyper-parameters: inject n_epochs=3 default unless overridden.
-    const hp: FineTuneHyperParameters = {};
-    hp.n_epochs = flags.nEpochs ?? 3;
-    if (flags.learningRate !== undefined) hp.learning_rate = flags.learningRate;
-    if (flags.maxLength !== undefined) hp.max_length = flags.maxLength;
-
-    // batch_size: clamp to [8, 1024] (server hard constraint, undocumented).
-    // Surface the clamp on stderr instead of silently rewriting the user's
-    // value — otherwise the submitted body would carry a number the user never
-    // typed, with no audit trail. (Range observed on common SFT / SFT-LoRA
-    // training types; some bases like qwen3.6-flash report a wider range, so
-    // the warning explicitly mentions "server range".)
-    if (flags.batchSize !== undefined) {
-      const requested = flags.batchSize;
-      let batchSize = requested;
-      if (batchSize < 8) batchSize = 8;
-      if (batchSize > 1024) batchSize = 1024;
-      if (batchSize !== requested && !settings.quiet) {
-        process.stderr.write(
-          `warning: --batch-size ${requested} clamped to ${batchSize} ` +
-            `(server range [8, 1024] for the common training types).\n`,
-        );
-      }
-      hp.batch_size = batchSize;
-    }
-
-    // Auto batch_size for small datasets: fetch first training file size.
-    // With default split=0.9, validation_set = 0.1 * rows.
-    // Platform default batch_size=16 needs rows > 160; batch_size=8 needs rows > 80.
-    // Files < 100KB are conservatively estimated to have < 200 rows.
-    // If the first file was just uploaded we already hold its size; otherwise
-    // fall back to getDataset.
-    if (hp.batch_size === undefined && !settings.dryRun) {
-      let sizeBytes = training.firstSize ?? 0;
-      if (sizeBytes === 0) {
-        try {
-          const fileInfo = await getDataset(ctx.client, trainingFileIds[0]);
-          sizeBytes = fileInfo.data?.size ?? 0;
-        } catch {
-          // If we can't fetch file info, skip auto-adjustment; platform will use default.
-        }
-      }
-      if (sizeBytes > 0 && sizeBytes < 100 * 1024) {
-        hp.batch_size = 8;
-      }
-    }
-
-    // Pre-submit batch-size gate: the platform rejects a job whose number of
-    // training samples is not greater than batch_size, but only surfaces that
-    // ~10 minutes into the run (after data processing). Fail fast here, before
-    // burning quota. `recordCount` is only known when every --datasets token
-    // was a local file we validated; file-id tokens fall through to the
-    // platform rather than risk a false positive from an undercount.
-    //
-    // The decision lives in core (`preflightBatchSizeGate`) — a structured,
-    // job-level pre-flight that returns a `ValidationIssue` (same shape / stable
-    // code as `validateDataset`) so the failure surfaces through the same
-    // `BailianError` + issue convention used by `dataset upload`/`validate`.
-    // ExitCode.GENERAL matches the existing validation-failed exit code.
-    if (!settings.dryRun && training.recordCount !== undefined) {
-      // 16 is the platform default when neither the user nor the small-file
-      // auto-adjust set a batch_size (see the auto-adjust comment above).
-      const effectiveBatchSize = hp.batch_size ?? 16;
-      const gate = preflightBatchSizeGate({
-        recordCount: training.recordCount,
-        batchSize: effectiveBatchSize,
-      });
-      if (!gate.ok && gate.issue) {
-        throw new BailianError(gate.issue.message, ExitCode.GENERAL, gate.hint);
-      }
-    }
-
-    // Pre-flight capability check: confirm the model actually supports the
-    // requested training type BEFORE any upload, so a wrong --model /
-    // --training-type combo doesn't burn storage on datasets that will never
-    // be trained against. listFoundationModels is a public API (no console
-    // login required); on lookup failure (network / 401 / etc.) we fall back
-    // to letting the server decide rather than blocking the submit.
-    if (!settings.dryRun) {
-      let capability: Awaited<ReturnType<typeof fetchModelCapability>> | undefined;
-      try {
-        capability = await fetchModelCapability(settings, model);
-      } catch (error) {
-        if (!settings.quiet) {
-          process.stderr.write(
-            `warning: model capability lookup failed (${(error as Error).message}); ` +
-              "proceeding without local pre-flight.\n",
-          );
-        }
-      }
-      if (capability && !listSupportedTrainingTypes(capability).includes(trainingType)) {
-        const supported = listSupportedTrainingTypes(capability);
-        throw new BailianError(
-          `Model "${model}" does not support training type "${trainingType}".`,
-          ExitCode.USAGE,
-          supported.length
-            ? `This model supports: ${supported.join(", ")}.`
-            : "This model reports no supported training types.",
-        );
-      }
-    }
-
-    // Upload local paths now that pre-flight (validation, batch-size gate,
-    // capability check) has cleared them. This swaps the
-    // placeholder path entries in `training.fileIds` / `validation?.fileIds`
-    // for real file-ids, so the body below sees ids.
-    if (!settings.dryRun) {
-      await uploadResolvedLocal(ctx.client, settings, training, "fine-tune", "datasets");
-      if (validation) {
-        await uploadResolvedLocal(ctx.client, settings, validation, "fine-tune", "validations");
-      }
-    }
-
-    const body: CreateFineTuneRequest = {
-      model,
-      training_file_ids: trainingFileIds,
-      // Map the CLI training type to the server value at the interface boundary.
-      training_type: toServerTrainingType(trainingType),
-      hyper_parameters: hp,
-    };
-    if (validationFileIds && validationFileIds.length > 0) {
-      body.validation_file_ids = validationFileIds;
-    }
-    if (modelName) body.model_name = modelName;
-    if (suffix) body.finetuned_output_suffix = suffix;
-
-    const format = detectOutputFormat(settings.output);
-
-    if (settings.dryRun) {
-      const pending = [
-        ...training.localPaths.map((path) => ({ field: "datasets", path })),
-        ...(validation?.localPaths ?? []).map((path) => ({ field: "validations", path })),
-      ];
-      emitResult(
-        pending.length > 0
-          ? { action: "finetune.create", body, pending_uploads: pending }
-          : { action: "finetune.create", body },
-        format,
-      );
-      return;
-    }
-
-    const response = await createFineTune(ctx.client, body);
-    const job = response.output ?? response.data;
-
-    if (settings.quiet) {
-      if (job?.job_id) emitBare(job.job_id);
-    } else if (format === "text") {
-      if (job?.job_id) {
-        emitBare(`Created fine-tune job: ${job.job_id}`);
-        if (job.status) emitBare(`Status: ${job.status}`);
-      } else {
-        emitResult(response, format);
-      }
-    } else {
-      emitResult(response, format);
-    }
-  },
+  notes: TEXT_NOTES,
+  run: (ctx) => runCreate("text", ctx),
+});
+
+/** `bl finetune audio create` — fine-tune an audio TTS model. Datasets are `.zip`. */
+export const finetuneAudioCreate = defineCommand({
+  description: "Create an audio TTS model fine-tune job (sft-lora)",
+  auth: "apiKey",
+  usageArgs: AUDIO_USAGE,
+  flags: AUDIO_FLAGS,
+  exampleArgs: [
+    "--model cosyvoice-v3-flash --datasets ./audio.zip",
+    "--model cosyvoice-v3-flash --datasets file-xxx",
+    "--model cosyvoice-v3-flash --datasets ./audio.zip --model-name my-tts",
+    "--model cosyvoice-v3-flash --datasets file-xxx --output json",
+    "--model cosyvoice-v3-flash --datasets ./audio.zip --dry-run",
+  ],
+  notes: AUDIO_NOTES,
+  run: (ctx) => runCreate("audio", ctx),
+});
+
+/** `bl finetune image create` — fine-tune an image generation model. Datasets are `.zip`. */
+export const finetuneImageCreate = defineCommand({
+  description: "Create an image generation model fine-tune job (sft-lora)",
+  auth: "apiKey",
+  usageArgs: IMAGE_USAGE,
+  flags: IMAGE_FLAGS,
+  exampleArgs: [
+    "--model wan2.7-image-pro --datasets ./images.zip",
+    "--model wan2.7-image-pro --datasets file-xxx",
+    "--model wan2.7-image-pro --datasets file-xxx --generation-type i2i",
+    "--model wan2.7-image-pro --datasets ./images.zip --model-name my-wan",
+    "--model wan2.7-image-pro --datasets file-xxx --output json",
+    "--model wan2.7-image-pro --datasets ./images.zip --dry-run",
+  ],
+  notes: IMAGE_NOTES,
+  run: (ctx) => runCreate("image", ctx),
 });

packages/commands/src/commands/finetune/export.ts

@@ -34,9 +34,9 @@ export default defineCommand({
   flags: EXPORT_FLAGS,
   exampleArgs: ["--job-id ft-xxx --checkpoint ckpt-3 --model-name my-qwen-sft"],
   notes: [
-    "Required before `deploy create` can target a checkpoint. The platform",
-    "may auto-export the best checkpoint when a job reaches SUCCEEDED — explicit",
-    "export is the canonical path for non-best checkpoints.",
+    "Required before `deploy <modality> create` can target a checkpoint. The",
+    "platform may auto-export the best checkpoint when a job reaches SUCCEEDED —",
+    "explicit export is the canonical path for non-best checkpoints.",
   ],
   async run(ctx) {
     const { identity, settings, flags } = ctx;
@@ -66,7 +66,9 @@ export default defineCommand({
       emitBare(exported);
     } else if (format === "text") {
       emitBare(`Exported ${jobId} / ${checkpoint} → model_name=${exported}`);
-      emitBare(`Next: ${identity.binName} deploy create --model ${exported} --name <display-name>`);
+      emitBare(
+        `Next: ${identity.binName} deploy text create --model ${exported} --name <display-name>`,
+      );
     } else {
       emitResult(response, format);
     }

packages/commands/src/commands/finetune/get.ts

@@ -71,7 +71,7 @@ export default defineCommand({
     if (item.hyper_params) emitBare(`hyper_params:     ${item.hyper_params}`);
     if (item.output_model)
       emitBare(
-        `output_model:     ${item.output_model}  (→ ${identity.binName} deploy create --model)`,
+        `output_model:     ${item.output_model}  (→ ${identity.binName} deploy text create --model)`,
       );
     if (item.model_name) emitBare(`model_name:       ${item.model_name}`);
     if (item.created_at) emitBare(`created_at:       ${item.created_at}`);

packages/commands/src/commands/finetune/list.ts

@@ -75,6 +75,8 @@ export default defineCommand({
     ]);
     for (const line of formatTable(headers, rows)) emitBare(line);
     if (total !== undefined) emitBare(`\nTotal: ${total}`);
-    emitBare(`Tip: OUTPUT_MODEL is the input for \`${identity.binName} deploy create --model\``);
+    emitBare(
+      `Tip: OUTPUT_MODEL is the input for \`${identity.binName} deploy text create --model\``,
+    );
   },
 });

packages/commands/src/commands/finetune/watch.ts

@@ -1,15 +1,16 @@
-import { defineCommand, detectOutputFormat, getFineTune, type FlagsDef } from "bailian-cli-core";
+import {
+  defineCommand,
+  detectOutputFormat,
+  getFineTune,
+  BailianError,
+  ExitCode,
+  type FlagsDef,
+} from "bailian-cli-core";
 import { emitResult, emitBare } from "bailian-cli-runtime";
 
 const DEFAULT_INTERVAL_SEC = 10;
 const MIN_INTERVAL_SEC = 1;
 const TERMINAL_STATUSES = new Set(["SUCCEEDED", "FAILED", "CANCELED"]);
-/** SIGINT exit code (128 + signal 2). */
-const EXIT_INTERRUPTED = 130;
-const EXIT_FAILED = 1;
-const EXIT_TIMEOUT = 2;
-/** Non-terminal status: the job is still running. Distinct from failure. */
-const EXIT_RUNNING = 3;
 
 function nowStamp(): string {
   const date = new Date();
@@ -25,18 +26,6 @@ function formatElapsed(milliseconds: number): string {
   return `${minutes}m ${seconds}s`;
 }
 
-/**
- * Exit code for a status value:
- *   SUCCEEDED            -> 0
- *   FAILED / CANCELED    -> 1
- *   anything else        -> 3 (still running)
- */
-function exitCodeForStatus(status: string): number {
-  if (status === "SUCCEEDED") return 0;
-  if (TERMINAL_STATUSES.has(status)) return EXIT_FAILED;
-  return EXIT_RUNNING;
-}
-
 /**
  * Resolve after `milliseconds`, rejecting early if `signal` aborts (Ctrl-C).
  * Cleans up its timer + listener so nothing leaks between polls.
@@ -101,9 +90,9 @@ export default defineCommand({
     "Default (no --follow) is a NON-BLOCKING single status probe: one fetch, then",
     "return immediately. This is the mode meant for agents / scripts — the caller",
     "owns the polling cadence, so the CLI never holds the terminal.",
-    "Exit codes (both modes): 0 SUCCEEDED | 1 FAILED/CANCELED | 2 --poll-timeout",
-    "exceeded (--follow) | 3 still running (non-terminal, default mode) | 130",
-    "interrupted (Ctrl-C).",
+    "A terminal FAILED/CANCELED status raises a normal CLI error (non-zero exit);",
+    "a SUCCEEDED or still-running status returns 0. With --follow, exceeding",
+    "--poll-timeout raises a timeout error.",
     "Use --follow for the blocking, human-terminal-follow experience; use the",
     "default mode when driving the loop yourself (e.g. from an agent).",
     "For per-step training output (not status), use `finetune logs`.",
@@ -130,32 +119,34 @@ export default defineCommand({
       return;
     }
 
-    // Exit codes here are a public probe contract (0 succeeded / 1 failed / 2
-    // timeout / 3 still running / 130 interrupted) — deliberately routed via
-    // process.exit instead of the central error handler.
-
     // ---- Default: non-blocking single status probe -------------------------
+    // A terminal FAILED/CANCELED status is surfaced as a BailianError (the
+    // central handler prints it and exits non-zero); SUCCEEDED and still-running
+    // both return normally. No process.exit / custom exit-code contract.
     if (!follow) {
       const response = await getFineTune(ctx.client, jobId);
       const job = response.output ?? response.data;
       const status = String(job?.status ?? "").toUpperCase();
       const terminal = TERMINAL_STATUSES.has(status);
-      const code = exitCodeForStatus(status);
 
       if (settings.quiet) {
         // Just the status word — ideal for `status=$(... finetune watch ... --quiet)`.
         emitBare(status || "UNKNOWN");
       } else if (format === "text") {
         emitBare(`${nowStamp()}  ${jobId}  ${status || "UNKNOWN"}`);
-        if (terminal) {
-          const mark = status === "SUCCEEDED" ? "✓" : "✗";
-          emitBare(`${mark} ${jobId}  ${status}`);
-        }
+        if (status === "SUCCEEDED") emitBare(`✓ ${jobId}  ${status}`);
       } else {
         // json: a compact, purpose-built status probe.
         emitResult({ job_id: jobId, status: status || "UNKNOWN", terminal }, format);
       }
-      process.exit(code);
+
+      if (terminal && status !== "SUCCEEDED") {
+        throw new BailianError(
+          `Fine-tune job ${jobId} ended in status ${status}.`,
+          ExitCode.GENERAL,
+        );
+      }
+      return;
     }
 
     // ---- --follow: blocking poll loop (legacy behavior) -------------------
@@ -182,28 +173,35 @@ export default defineCommand({
           const elapsed = Date.now() - startedAt;
           if (format !== "text" || settings.quiet) {
             emitResult(response, format);
-          } else {
-            const mark = status === "SUCCEEDED" ? "✓" : "✗";
-            emitBare(`\n${mark} ${jobId}  ${status}  (elapsed ${formatElapsed(elapsed)})`);
+          } else if (status === "SUCCEEDED") {
+            emitBare(`\n✓ ${jobId}  ${status}  (elapsed ${formatElapsed(elapsed)})`);
           }
-          process.exit(exitCodeForStatus(status));
+          if (status !== "SUCCEEDED") {
+            throw new BailianError(
+              `Fine-tune job ${jobId} ended in status ${status} (elapsed ${formatElapsed(elapsed)}).`,
+              ExitCode.GENERAL,
+            );
+          }
+          return;
         }
 
         if (pollTimeoutSec !== undefined && (Date.now() - startedAt) / 1000 >= pollTimeoutSec) {
-          if (format === "text" && !settings.quiet) {
-            emitBare(
-              `\n⏼ ${jobId}  timed out after ${formatElapsed(Date.now() - startedAt)} (last status: ${status || "UNKNOWN"})`,
-            );
-          }
-          process.exit(EXIT_TIMEOUT);
+          throw new BailianError(
+            `Watching fine-tune job ${jobId} timed out after ` +
+              `${formatElapsed(Date.now() - startedAt)} (last status: ${status || "UNKNOWN"}).`,
+            ExitCode.TIMEOUT,
+          );
         }
 
         await sleep(intervalSec * 1000, controller.signal);
       }
     } catch (error) {
+      // Ctrl-C aborts the poll loop: report and return normally (no custom code).
+      // Any other error (including the BailianError thrown above) propagates to
+      // the central handler.
       if (controller.signal.aborted) {
         emitBare("\nInterrupted.");
-        process.exit(EXIT_INTERRUPTED);
+        return;
       }
       throw error;
     } finally {

packages/commands/src/commands/image/edit.ts

@@ -1,7 +1,5 @@
 import {
   defineCommand,
-  imagePath,
-  imageSyncPath,
   taskPath,
   detectOutputFormat,
   resolveOutputDir,
@@ -20,8 +18,10 @@ import {
   BailianError,
   resolveBooleanFlag,
   resolveWatermark,
+  resolveImageEditApi,
   ASYNC_FLAG,
   CONCURRENT_FLAG,
+  redactDataUri,
 } from "bailian-cli-core";
 import { poll } from "bailian-cli-runtime";
 import { downloadFile } from "bailian-cli-runtime";
@@ -31,12 +31,6 @@ import { resolveImageSize } from "bailian-cli-runtime";
 import { join } from "path";
 import { BOOL_FLAG_PROMPT_EXTEND_CLI_TRUE, BOOL_FLAG_WATERMARK } from "bailian-cli-runtime";
 
-const SYNC_MODEL_PREFIXES = ["qwen-image-2.0", "qwen-image-max"];
-
-function isSyncModel(model: string): boolean {
-  return SYNC_MODEL_PREFIXES.some((p) => model.startsWith(p));
-}
-
 const EDIT_FLAGS = {
   image: {
     type: "array",
@@ -71,6 +65,12 @@ const EDIT_FLAGS = {
     valueHint: "<text>",
     description: "Negative prompt to exclude unwanted content",
   },
+  function: {
+    type: "string",
+    valueHint: "<name>",
+    description:
+      "wanx*-imageedit function (default: description_edit). Examples: stylization_all, description_edit",
+  },
   promptExtend: {
     type: "boolean",
     valueHint: "<bool>",
@@ -98,7 +98,7 @@ const EDIT_FLAGS = {
 type EditFlags = ParsedFlags<typeof EDIT_FLAGS>;
 
 export default defineCommand({
-  description: "Edit an existing image with text instructions (Qwen-Image)",
+  description: "Edit an existing image with text instructions (Qwen-Image / Wan 2.7)",
   auth: "apiKey",
   usageArgs: "--image <url> --prompt <text> [flags]",
   flags: EDIT_FLAGS,
@@ -107,6 +107,9 @@ export default defineCommand({
     '--image https://example.com/logo.png --prompt "Change color to blue" --n 3',
     '--image ./a.png --image ./b.png --prompt "Merge two images into one collage"',
     '--image https://example.com/photo.png --prompt "Remove the person" --model qwen-image-2.0-pro',
+    '--image ./photo.png --prompt "Change the style" --model wan2.7-image',
+    '--image ./photo.png --prompt "Place the subject on a table" --model wan2.5-i2i-preview',
+    '--image ./photo.png --prompt "转换成绘本风格" --model wanx2.1-imageedit --function stylization_all',
     '--image ./photo.png --prompt "Replace the background with a beach" --watermark false',
   ],
   async run(ctx) {
@@ -121,70 +124,138 @@ export default defineCommand({
     const prompt = flags.prompt;
 
     const model = flags.model || settings.defaultImageModel || "qwen-image-2.0";
-    const useSync = isSyncModel(model);
+    const route = resolveImageEditApi(model);
 
     // Auto-upload local files (resolve all images in parallel)
     const resolvedImages = await Promise.all(
-      rawImages.map((img) => ctx.client.uploadFile(img, model)),
+      rawImages.map((image) => ctx.client.resolveImageInput(image, model)),
     );
     const n = flags.n ?? 1;
 
     const promptExtend = resolveBooleanFlag(
       flags.promptExtend,
-      useSync ? true : undefined,
+      route.promptExtendDefault,
       "prompt-extend",
     );
 
-    // Build content: all images first, then text prompt
-    const contentItems: Array<{ image?: string; text?: string }> = resolvedImages.map(
-      (u: string) => ({ image: u }),
-    );
-    contentItems.push({ text: prompt });
-
     const watermark = resolveWatermark(flags.watermark);
 
-    const body: DashScopeImageRequest = {
-      model,
-      input: {
-        messages: [
-          {
-            role: "user",
-            content: contentItems,
-          },
-        ],
-      },
-      parameters: {
-        size: resolveImageSize(flags.size, useSync),
-        n,
-        seed: flags.seed,
-        prompt_extend: promptExtend,
-        watermark,
-        negative_prompt: flags.negativePrompt || undefined,
-      },
+    const parameters: NonNullable<DashScopeImageRequest["parameters"]> = {
+      size: resolveImageSize(flags.size, route.sizeProfile),
+      n,
+      seed: flags.seed,
+      prompt_extend: promptExtend,
+      watermark,
     };
 
+    let body: DashScopeImageRequest;
+    if (route.inputStyle === "function-base-image") {
+      const baseImageUrl = resolvedImages[0];
+      if (!baseImageUrl) {
+        throw new BailianError(
+          "wanx*-imageedit requires at least one --image as base_image_url.",
+          ExitCode.USAGE,
+        );
+      }
+      body = {
+        model,
+        input: {
+          function: flags.function || "description_edit",
+          prompt,
+          base_image_url: baseImageUrl,
+        },
+        parameters,
+      };
+    } else if (route.inputStyle === "prompt-images") {
+      body = {
+        model,
+        input: {
+          prompt,
+          images: resolvedImages,
+          negative_prompt: flags.negativePrompt || undefined,
+        },
+        parameters,
+      };
+    } else {
+      const contentItems: Array<{ image?: string; text?: string }> = resolvedImages.map(
+        (imageUrl: string) => ({ image: imageUrl }),
+      );
+      contentItems.push({ text: prompt });
+      body = {
+        model,
+        input: {
+          messages: [
+            {
+              role: "user",
+              content: contentItems,
+            },
+          ],
+        },
+        parameters: {
+          ...parameters,
+          negative_prompt: flags.negativePrompt || undefined,
+        },
+      };
+    }
+
     // Remove undefined parameters
     stripUndefined(body.parameters as Record<string, unknown>);
 
     const format = detectOutputFormat(settings.output);
 
     if (settings.dryRun) {
-      emitResult({ request: body, mode: useSync ? "sync" : "async" }, format);
+      let previewBody: DashScopeImageRequest = body;
+      if ("messages" in body.input) {
+        previewBody = {
+          ...body,
+          input: {
+            messages: body.input.messages.map((message) => ({
+              ...message,
+              content: message.content.map((item) =>
+                item.image ? { ...item, image: redactDataUri(item.image) } : item,
+              ),
+            })),
+          },
+        };
+      } else if ("images" in body.input) {
+        previewBody = {
+          ...body,
+          input: {
+            ...body.input,
+            images: body.input.images?.map((imageUrl) => redactDataUri(imageUrl)),
+          },
+        };
+      } else if ("base_image_url" in body.input) {
+        previewBody = {
+          ...body,
+          input: {
+            ...body.input,
+            base_image_url: redactDataUri(body.input.base_image_url),
+            mask_image_url: body.input.mask_image_url
+              ? redactDataUri(body.input.mask_image_url)
+              : undefined,
+          },
+        };
+      }
+      emitResult(
+        { request: previewBody, mode: route.useSync ? "sync" : "async", path: route.path },
+        format,
+      );
       return;
     }
 
     if (!settings.quiet) {
       process.stderr.write(
-        `[Model: ${model}] [Mode: ${useSync ? "sync" : "async"}] [Images: ${resolvedImages.length}]\n`,
+        `[Model: ${model}] [Mode: ${route.useSync ? "sync" : "async"}] [Images: ${resolvedImages.length}]\n`,
       );
     }
 
     const concurrent = getConcurrency(flags);
 
-    if (useSync) {
-      await handleSyncMode(ctx.client, settings, body, flags, format, concurrent);
+    if (route.useSync) {
+      await handleSyncMode(ctx.client, settings, route.path, body, flags, format, concurrent);
     } else {
-      await handleAsyncMode(ctx.client, settings, body, flags, format, concurrent);
+      await handleAsyncMode(ctx.client, settings, route.path, body, flags, format, concurrent);
     }
   },
 });
@@ -192,6 +263,7 @@ export default defineCommand({
 async function handleSyncMode(
   client: Client,
   settings: Settings,
+  path: string,
   body: DashScopeImageRequest,
   flags: EditFlags,
   format: OutputFormat,
@@ -199,15 +271,15 @@ async function handleSyncMode(
 ): Promise<void> {
   const results = await runConcurrent(concurrent, settings, () =>
     client.requestJson<DashScopeImageSyncResponse>({
-      path: imageSyncPath(),
+      path,
       method: "POST",
       body,
     }),
   );
 
   const imageUrls = results
-    .flatMap((r) => r.output.choices || [])
-    .flatMap((c) => c.message?.content || [])
+    .flatMap((result) => result.output.choices || [])
+    .flatMap((choice) => choice.message?.content || [])
     .map((item) => item.image)
     .filter(Boolean);
 
@@ -221,6 +293,7 @@ async function handleSyncMode(
 async function handleAsyncMode(
   client: Client,
   settings: Settings,
+  path: string,
   body: DashScopeImageRequest,
   flags: EditFlags,
   format: OutputFormat,
@@ -231,14 +304,14 @@ async function handleAsyncMode(
     settings,
     () =>
       client.requestJson<DashScopeAsyncResponse>({
-        path: imagePath(),
+        path,
         method: "POST",
         body,
         async: true,
       }),
     "tasks",
   );
-  const taskIds = responses.map((r) => r.output.task_id);
+  const taskIds = responses.map((response) => response.output.task_id);
 
   if (flags.async) {
     emitResult({ task_ids: taskIds }, format);
@@ -251,12 +324,12 @@ async function handleAsyncMode(
       url: client.url(taskPath(taskId)),
       intervalSec: pollInterval,
       timeoutSec: settings.timeout,
-      isComplete: (d) => (d as DashScopeTaskResponse).output.task_status === "SUCCEEDED",
-      isFailed: (d) => (d as DashScopeTaskResponse).output.task_status === "FAILED",
-      getStatus: (d) => (d as DashScopeTaskResponse).output.task_status,
-      getErrorMessage: (d) => {
-        const o = (d as DashScopeTaskResponse).output;
-        return o.message || o.code || undefined;
+      isComplete: (data) => (data as DashScopeTaskResponse).output.task_status === "SUCCEEDED",
+      isFailed: (data) => (data as DashScopeTaskResponse).output.task_status === "FAILED",
+      getStatus: (data) => (data as DashScopeTaskResponse).output.task_status,
+      getErrorMessage: (data) => {
+        const output = (data as DashScopeTaskResponse).output;
+        return output.message || output.code || undefined;
       },
     }),
   );
@@ -267,13 +340,13 @@ async function handleAsyncMode(
   for (const result of results) {
     if (result.output.choices) {
       const urls = result.output.choices
-        .flatMap((c) => c.message?.content || [])
+        .flatMap((choice) => choice.message?.content || [])
         .map((item) => item.image)
         .filter(Boolean);
       imageUrls.push(...urls);
     }
     if (result.output.results) {
-      const urls = result.output.results.map((r) => r.url).filter(Boolean);
+      const urls = result.output.results.map((item) => item.url).filter(Boolean);
       if (urls.length > 0 && imageUrls.length === 0) {
         imageUrls.push(...urls);
       }
@@ -303,8 +376,8 @@ async function saveImages(
   // Parallel download all images
   const items =
     imageUrls.length > 1
-      ? imageUrls.map((url, i) => {
-          const filename = `${prefix}_${String(i + 1).padStart(3, "0")}.png`;
+      ? imageUrls.map((url, index) => {
+          const filename = `${prefix}_${String(index + 1).padStart(3, "0")}.png`;
           return { url, destPath: join(outDir, filename) };
         })
       : [{ url: imageUrls[0], destPath: join(outDir, `${prefix}.png`) }];

packages/commands/src/commands/image/generate.ts

@@ -1,7 +1,5 @@
 import {
   defineCommand,
-  imagePath,
-  imageSyncPath,
   taskPath,
   detectOutputFormat,
   type Client,
@@ -19,6 +17,7 @@ import {
   generateFilename,
   resolveBooleanFlag,
   resolveWatermark,
+  resolveImageGenerateApi,
   ASYNC_FLAG,
   CONCURRENT_FLAG,
 } from "bailian-cli-core";
@@ -31,13 +30,6 @@ import { BOOL_FLAG_PROMPT_EXTEND_IMAGE_GENERATE, BOOL_FLAG_WATERMARK } from "bai
 
 import { join } from "path";
 
-// qwen-image-2.0 series uses the sync multimodal-generation endpoint
-const SYNC_MODEL_PREFIXES = ["qwen-image-2.0", "qwen-image-max"];
-
-function isSyncModel(model: string): boolean {
-  return SYNC_MODEL_PREFIXES.some((p) => model.startsWith(p));
-}
-
 const GENERATE_FLAGS = {
   prompt: { type: "string", valueHint: "<text>", description: "Image description", required: true },
   model: {
@@ -104,6 +96,8 @@ export default defineCommand({
     '--prompt "Logo" --watermark false',
     '--prompt "An alien in the space" --watermark false',
     '--prompt "sunset" --model wan2.6-t2i --async --quiet',
+    '--prompt "plush doll" --model z-image-turbo --size 1024*1024',
+    '--prompt "sunset" --model wanx2.0-t2i-turbo --size 1024*1024',
     '--prompt "Pro quality" --model qwen-image-2.0-pro',
     '--prompt "Product shots" --n 2 --concurrent 3  # 6 images in parallel',
   ],
@@ -112,73 +106,90 @@ export default defineCommand({
     const prompt = flags.prompt;
 
     const model = flags.model || settings.defaultImageModel || "qwen-image-2.0";
-    const useSync = isSyncModel(model);
-    const defaultSize = useSync ? "1:1" : "1:1";
+    const route = resolveImageGenerateApi(model);
+    const defaultSize = "1:1";
     const sizeInput = flags.size || defaultSize;
-    const size = resolveImageSize(sizeInput, useSync);
+    const size = resolveImageSize(sizeInput, route.sizeProfile);
     const n = flags.n ?? 1;
     const concurrent = getConcurrency(flags);
 
     const promptExtend = resolveBooleanFlag(
       flags.promptExtend,
-      useSync ? true : undefined,
+      route.promptExtendDefault,
       "prompt-extend",
     );
 
     const watermark = resolveWatermark(flags.watermark);
 
-    const body: DashScopeImageRequest = {
-      model,
-      input: {
-        messages: [{ role: "user", content: [{ text: prompt }] }],
-      },
-      parameters: {
-        size,
-        n,
-        seed: flags.seed,
-        prompt_extend: promptExtend,
-        watermark,
-        negative_prompt: flags.negativePrompt || undefined,
-      },
+    const parameters: NonNullable<DashScopeImageRequest["parameters"]> = {
+      size,
+      n,
+      seed: flags.seed,
+      prompt_extend: promptExtend,
+      watermark,
     };
 
+    const body: DashScopeImageRequest =
+      route.inputStyle === "prompt"
+        ? {
+            model,
+            input: {
+              prompt,
+              negative_prompt: flags.negativePrompt || undefined,
+            },
+            parameters,
+          }
+        : {
+            model,
+            input: {
+              messages: [{ role: "user", content: [{ text: prompt }] }],
+            },
+            parameters: {
+              ...parameters,
+              negative_prompt: flags.negativePrompt || undefined,
+            },
+          };
+
     const format = detectOutputFormat(settings.output);
 
     if (settings.dryRun) {
-      emitResult({ request: body, mode: useSync ? "sync" : "async" }, format);
+      emitResult(
+        { request: body, mode: route.useSync ? "sync" : "async", path: route.path },
+        format,
+      );
       return;
     }
 
     if (!settings.quiet) {
-      process.stderr.write(`[Model: ${model}] [Mode: ${useSync ? "sync" : "async"}]\n`);
+      process.stderr.write(`[Model: ${model}] [Mode: ${route.useSync ? "sync" : "async"}]\n`);
     }
 
-    if (useSync) {
-      await handleSyncMode(ctx.client, settings, model, body, flags, format, concurrent);
+    if (route.useSync) {
+      await handleSyncMode(ctx.client, settings, route.path, body, flags, format, concurrent);
     } else {
-      await handleAsyncMode(ctx.client, settings, model, body, flags, format, concurrent);
+      await handleAsyncMode(ctx.client, settings, route.path, body, flags, format, concurrent);
     }
   },
 });
 
-// ---- Sync mode: qwen-image-2.0 series ----
+// ---- Sync mode: qwen-image / wan2.7-image / z-image ----
 
 async function handleSyncMode(
   client: Client,
   settings: Settings,
-  _model: string,
+  path: string,
   body: DashScopeImageRequest,
   flags: GenerateFlags,
   format: string,
   concurrent: number,
 ): Promise<void> {
   const results = await runConcurrent(concurrent, settings, () =>
-    client.requestJson<DashScopeImageSyncResponse>({ path: imageSyncPath(), method: "POST", body }),
+    client.requestJson<DashScopeImageSyncResponse>({ path, method: "POST", body }),
   );
 
   const imageUrls = results
-    .flatMap((r) => r.output.choices || [])
-    .flatMap((c) => c.message?.content || [])
+    .flatMap((result) => result.output.choices || [])
+    .flatMap((choice) => choice.message?.content || [])
     .map((item) => item.image)
     .filter(Boolean);
 
@@ -189,12 +200,12 @@ async function handleSyncMode(
   await saveImages(imageUrls, flags, settings, format);
 }
 
-// ---- Async mode: wan2.x / qwen-image-plus ----
+// ---- Async mode: wan2.6-t2i / wan2.6-image / legacy text2image ----
 
 async function handleAsyncMode(
   client: Client,
   settings: Settings,
-  _model: string,
+  path: string,
   body: DashScopeImageRequest,
   flags: GenerateFlags,
   format: string,
@@ -205,14 +216,14 @@ async function handleAsyncMode(
     settings,
     () =>
       client.requestJson<DashScopeAsyncResponse>({
-        path: imagePath(),
+        path,
         method: "POST",
         body,
         async: true,
       }),
     "tasks",
   );
-  const taskIds = responses.map((r) => r.output.task_id);
+  const taskIds = responses.map((response) => response.output.task_id);
 
   // --async: return all task IDs immediately
   if (flags.async) {
@@ -229,12 +240,12 @@ async function handleAsyncMode(
       url: pollUrl,
       intervalSec: pollInterval,
       timeoutSec: settings.timeout,
-      isComplete: (d) => (d as DashScopeTaskResponse).output.task_status === "SUCCEEDED",
-      isFailed: (d) => (d as DashScopeTaskResponse).output.task_status === "FAILED",
-      getStatus: (d) => (d as DashScopeTaskResponse).output.task_status,
-      getErrorMessage: (d) => {
-        const o = (d as DashScopeTaskResponse).output;
-        return o.message || o.code || undefined;
+      isComplete: (data) => (data as DashScopeTaskResponse).output.task_status === "SUCCEEDED",
+      isFailed: (data) => (data as DashScopeTaskResponse).output.task_status === "FAILED",
+      getStatus: (data) => (data as DashScopeTaskResponse).output.task_status,
+      getErrorMessage: (data) => {
+        const output = (data as DashScopeTaskResponse).output;
+        return output.message || output.code || undefined;
       },
     });
   });
@@ -245,13 +256,13 @@ async function handleAsyncMode(
   for (const result of results) {
     if (result.output.choices) {
       const urls = result.output.choices
-        .flatMap((c) => c.message?.content || [])
+        .flatMap((choice) => choice.message?.content || [])
         .map((item) => item.image)
         .filter(Boolean);
       imageUrls.push(...urls);
     }
     if (result.output.results) {
-      const urls = result.output.results.map((r) => r.url).filter(Boolean);
+      const urls = result.output.results.map((item) => item.url).filter(Boolean);
       if (urls.length > 0 && imageUrls.length === 0) {
         imageUrls.push(...urls);
       }
@@ -293,8 +304,8 @@ async function saveImages(
   // Parallel download all images
   const items =
     imageUrls.length > 1
-      ? imageUrls.map((url, i) => {
-          const filename = `${prefix}_${String(i + 1).padStart(3, "0")}.png`;
+      ? imageUrls.map((url, index) => {
+          const filename = `${prefix}_${String(index + 1).padStart(3, "0")}.png`;
           return { url, destPath: join(outDir, filename) };
         })
       : [{ url: imageUrls[0], destPath: join(outDir, `${prefix}.png`) }];

packages/commands/src/commands/managed-agent/_engine/address-utils.ts

@@ -0,0 +1,11 @@
+import type { ResourceAddress } from "@openagentpack/sdk";
+
+/** Full state address: provider.type.name */
+export function formatResourceAddress(address: ResourceAddress): string {
+  return `${address.provider}.${address.type}.${address.name}`;
+}
+
+/** CLI display short label: type.name (provider) */
+export function formatResourceLabel(address: ResourceAddress): string {
+  return `${address.type}.${address.name} (${address.provider})`;
+}

packages/commands/src/commands/managed-agent/_engine/config-loader.ts

@@ -0,0 +1,105 @@
+import {
+  createProjectRuntime,
+  type LoadedProjectConfig,
+  type ProjectRuntimeContext,
+  resolveProjectConfig,
+  UserError,
+} from "@openagentpack/sdk";
+import {
+  assertProviderCredentials,
+  type CredentialHost,
+  injectProviderCredentials,
+  normalizeInterpolatedProviderBlocks,
+  prepareProviderEnv,
+  scrubCredentialEnv,
+} from "./credentials.ts";
+import { loadFileState } from "./file-state-manager.ts";
+import { type HostContext, installSdkTransport } from "./transport.ts";
+
+export { CREDENTIALS_NOTE, OFFLINE_NOTE } from "./credentials.ts";
+
+/**
+ * Whether this run requires provider keys:
+ *   - "all" (default) — online command: every provider declared in agents.yaml
+ *     must have a non-empty key after injection
+ *   - "none" — offline command (local config/state only), skip the check
+ */
+export type CredentialScope = "all" | "none";
+
+interface AgentConfigOptions {
+  resolveEnv?: boolean;
+  projectName?: string;
+  statePath?: string;
+  credentials?: CredentialScope;
+}
+
+/**
+ * Resolve agents.yaml with credentials injected the bl way and scrubbed from the
+ * environment — the shared credential spine for every SDK-engine command:
+ *   1. prepare env (SDK bootstrap for non-bailian + placeholders so interpolation
+ *      never throws on a value we're about to supply/reject)
+ *   2. resolve + interpolate the config
+ *   3. override the bailian block with the CLI auth chain's credential (in-memory)
+ *   4. scrub all credential vars from process.env (real values now live only in
+ *      the config object → provider adapters, never the environment)
+ *   5. fail with a CLI-authoritative AUTH error if any provider's key is empty
+ *      (offline commands pass `credentials: "none"` to skip the check)
+ */
+export async function resolveAgentProjectConfig(
+  host: CredentialHost,
+  filePath: string,
+  options: AgentConfigOptions = {},
+): Promise<LoadedProjectConfig> {
+  prepareProviderEnv();
+  const resolved = await resolveProjectConfig(filePath, options);
+  normalizeInterpolatedProviderBlocks(resolved.config.providers);
+  injectProviderCredentials(resolved.config.providers, host);
+  scrubCredentialEnv();
+  if ((options.credentials ?? "all") !== "none") {
+    assertProviderCredentials(resolved.config.providers);
+  }
+  return resolved;
+}
+
+/**
+ * Build a full ProjectRuntimeContext from a config file path — the standard
+ * entry point for agent commands that need the SDK engine. Mirrors OpenAgentPack
+ * CLI's buildCliRuntime: resolve config → load local state → assemble runtime.
+ * Takes the host context first so every SDK-engine command wires the
+ * instrumented transport (UA / tracking headers / verbose) and the bl-resolved,
+ * in-memory-injected credential ({@link resolveAgentProjectConfig}) by construction.
+ */
+export async function buildAgentRuntime(
+  host: HostContext & CredentialHost,
+  filePath: string,
+  options: AgentConfigOptions = {},
+): Promise<ProjectRuntimeContext & { configPath: string }> {
+  installSdkTransport(host);
+  const { config, configPath, projectName } = await resolveAgentProjectConfig(
+    host,
+    filePath,
+    options,
+  );
+  const state = await loadFileState(configPath, options.statePath, projectName);
+  const ctx = createProjectRuntime({
+    projectName,
+    config,
+    state,
+    configPath,
+    providers: config.providers,
+  });
+  return { ...ctx, configPath };
+}
+
+/** Ensure a user-supplied --provider value is actually configured in agents.yaml. */
+export function assertProviderConfigured(
+  ctx: ProjectRuntimeContext,
+  provider: string | undefined,
+): void {
+  if (!provider || provider === "all") return;
+  if (ctx.providers.has(provider)) return;
+  const available = Array.from(ctx.providers.keys()).join(", ") || "none";
+  throw new UserError(
+    `Provider '${provider}' is not configured. Available providers: ${available}.`,
+  );
+}

packages/commands/src/commands/managed-agent/_engine/console-capture.ts

@@ -0,0 +1,23 @@
+/**
+ * Redirect `console.log` / `console.info` to stderr while `fn` runs.
+ *
+ * The OpenAgentPack SDK's provider adapters emit progress/debug logging via
+ * `console.log` (e.g. `[skill-upload]`), which would corrupt bl's stdout data
+ * channel in `--output json` mode. Wrapping SDK calls that may log keeps stdout
+ * a clean data channel. Restores the originals on completion.
+ */
+export async function withStdoutProtected<T>(fn: () => Promise<T>): Promise<T> {
+  const originalLog = console.log;
+  const originalInfo = console.info;
+  const toStderr = (...args: unknown[]): void => {
+    process.stderr.write(`${args.map((arg) => String(arg)).join(" ")}\n`);
+  };
+  console.log = toStderr;
+  console.info = toStderr;
+  try {
+    return await fn();
+  } finally {
+    console.log = originalLog;
+    console.info = originalInfo;
+  }
+}

packages/commands/src/commands/managed-agent/_engine/credentials.ts

@@ -0,0 +1,172 @@
+import { AGENTS_PROVIDER_FIELDS, bootstrapRuntimeCredentialsSync } from "@openagentpack/sdk";
+import { BailianError, type Client, ExitCode, type Settings } from "bailian-cli-core";
+
+/**
+ * AgentStudio API path the SDK's BailianClient serves resources under. bl's
+ * `base_url` is the bare model-service origin (e.g. https://dashscope.aliyuncs.com);
+ * the SDK appends resource paths onto the bailian provider's `base_url` verbatim,
+ * so the agent path must carry this suffix. See OpenAgentPack BailianClient.
+ */
+const AGENTSTUDIO_API_PATH = "/api/v1/agentstudio";
+
+/**
+ * Every env var the SDK recognizes as provider credential material (primary keys
+ * from the SDK's own field map) plus bl-side interpolation aliases and bailian's
+ * endpoint var (not part of AGENTS_PROVIDER_FIELDS). These are the only vars the
+ * pipeline placeholders (to keep interpolation from throwing) and scrubs (so no
+ * real credential persists in the environment).
+ */
+const CREDENTIAL_ENV_KEYS = [
+  ...new Set([
+    ...Object.values(AGENTS_PROVIDER_FIELDS).flatMap((fields) => fields.map((field) => field.key)),
+    "BAILIAN_API_KEY",
+    "BAILIAN_BASE_URL",
+    "CLAUDE_API_KEY",
+    "QODER_API_KEY",
+  ]),
+];
+
+/** How to obtain each provider's key, surfaced in the CLI's own AUTH error when it is missing. */
+const CREDENTIAL_HINTS: Record<string, string> = {
+  bailian: "Run `bl auth login --api-key <key>`, pass --api-key, or set DASHSCOPE_API_KEY.",
+  claude: "Set ANTHROPIC_API_KEY (or CLAUDE_API_KEY) in your shell or .env.",
+  ark: "Set ARK_API_KEY in your shell or .env.",
+  qoder: "Set QODER_PAT (or QODER_API_KEY) in your shell or .env.",
+};
+
+/** The slice of CommandContext the credential pipeline needs: authStage-resolved client + settings. */
+export interface CredentialHost {
+  client: Client;
+  settings: Settings;
+}
+
+/**
+ * Shared `--help` note documenting where agent commands get provider
+ * credentials. Bailian goes through bl's own auth chain (commands declare
+ * `auth: "apiKey"`); other providers come from env. Either way the resolved
+ * credential is injected into the SDK in-memory and scrubbed from the
+ * environment. Attach to every command that loads agents.yaml. `bl` prefix is
+ * safe: agent commands ship on `bl` only.
+ */
+export const CREDENTIALS_NOTE = [
+  "Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).",
+  "Other providers read the env vars referenced in agents.yaml (e.g. ${ANTHROPIC_API_KEY}), including .env and ~/.agents/config.json.",
+  "Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.",
+];
+
+/**
+ * Shared `--help` note for commands that never talk to a provider: they load
+ * agents.yaml / local state only, so no login or provider key is required.
+ */
+export const OFFLINE_NOTE = [
+  "Runs fully offline against local files: no login or provider credentials required.",
+];
+
+/**
+ * Load the SDK's env-based credential sources (`.env`, `~/.agents/config.json`)
+ * for non-bailian providers, then placeholder every credential var that is still
+ * unset with "" so agents.yaml `${VAR}` interpolation never throws on a value the
+ * pipeline is about to supply (bailian) or authoritatively reject ({@link
+ * assertProviderCredentials}). Runs every call (no I/O cache) so a scrubbed
+ * environment is repopulated if the same process resolves more than one config.
+ */
+export function prepareProviderEnv(): void {
+  bootstrapRuntimeCredentialsSync();
+  for (const key of CREDENTIAL_ENV_KEYS) {
+    if (process.env[key] === undefined) process.env[key] = "";
+  }
+}
+
+/**
+ * Override the bailian provider block with bl's authStage-resolved credential, so
+ * the bailian API key is authoritatively the CLI auth chain's — never a config
+ * file bare-read or a stale env value. `api_key` is replaced unconditionally
+ * when a credential resolved; `base_url` / `workspace_id` are filled only when
+ * the block references them and the interpolated value is empty (a literal in
+ * agents.yaml is respected).
+ *
+ * `base_url` carries {@link AGENTSTUDIO_API_PATH} because the SDK appends resource
+ * paths onto it verbatim; a value already ending in the suffix is left as-is.
+ * It is filled even without a credential — `client.baseUrl` is readable
+ * credential-less (defaults to the CLI's model-domain base URL) — so offline
+ * commands (which skip the credential assert) still satisfy the SDK's
+ * "workspace_id or base_url" schema. With no credential the `api_key` is left
+ * untouched: online commands reject it via {@link assertProviderCredentials}.
+ */
+export function injectProviderCredentials(
+  providers: Record<string, unknown>,
+  host: CredentialHost,
+): void {
+  const bailian = providers.bailian;
+  if (!bailian || typeof bailian !== "object") return;
+  const block = bailian as Record<string, unknown>;
+
+  const cred = host.client.exportApiCredential();
+  if (cred) block.api_key = cred.token;
+  if ("base_url" in block && !block.base_url) {
+    // Defensive normalization: the auth chain already normalizes base_url to
+    // an origin, but never let a trailing slash produce "//api/v1/agentstudio".
+    const origin = host.client.baseUrl.replace(/\/+$/, "");
+    block.base_url = origin.endsWith(AGENTSTUDIO_API_PATH)
+      ? origin
+      : `${origin}${AGENTSTUDIO_API_PATH}`;
+  }
+  if ("workspace_id" in block && !block.workspace_id && host.settings.workspaceId) {
+    block.workspace_id = host.settings.workspaceId;
+  }
+}
+
+/**
+ * Remove every credential var from `process.env` after interpolation has run and
+ * bailian has been overridden in-memory. From here on the real credentials live
+ * only in the config object (and, after `createProjectRuntime`, in each provider
+ * adapter instance) — nothing persists in the environment for the process
+ * lifetime or any child process.
+ */
+export function scrubCredentialEnv(): void {
+  for (const key of CREDENTIAL_ENV_KEYS) {
+    delete process.env[key];
+  }
+}
+
+/**
+ * The SDK interpolates `${VAR}` into the raw YAML text, so an empty env var
+ * leaves `api_key:` with nothing after it — YAML parses that as null. Normalize
+ * every null provider field back to "" so the pipeline stays uniform: for
+ * online commands an empty api_key is caught by {@link
+ * assertProviderCredentials}; for offline commands (which skip the assert) the
+ * blocks still satisfy the SDK's string schemas instead of failing zod with
+ * "received null" before the run even starts.
+ */
+export function normalizeInterpolatedProviderBlocks(providers: Record<string, unknown>): void {
+  for (const raw of Object.values(providers)) {
+    if (!raw || typeof raw !== "object") continue;
+    const block = raw as Record<string, unknown>;
+    for (const [fieldName, value] of Object.entries(block)) {
+      if (value === null) block[fieldName] = "";
+    }
+  }
+}
+
+/**
+ * After injection, fail with a CLI-authoritative AUTH error if any configured
+ * provider's `api_key` resolved empty (missing env var, or no bl login for
+ * bailian). Replaces the SDK's raw `Environment variable '...' is not set` /
+ * zod config error with a clean message plus a provider-specific hint. Validates
+ * every declared provider, so a project is only runnable once all its providers'
+ * keys are available; offline commands skip the check entirely.
+ */
+export function assertProviderCredentials(providers: Record<string, unknown>): void {
+  for (const [name, raw] of Object.entries(providers)) {
+    if (!raw || typeof raw !== "object") continue;
+    const block = raw as Record<string, unknown>;
+    if (!("api_key" in block)) continue;
+    const apiKey = block.api_key;
+    if (typeof apiKey === "string" && apiKey.trim()) continue;
+    throw new BailianError(
+      `Provider '${name}' is configured but its API key is empty.`,
+      ExitCode.AUTH,
+      CREDENTIAL_HINTS[name] ?? `Provide credentials for provider '${name}'.`,
+    );
+  }
+}

packages/commands/src/commands/managed-agent/_engine/errors.ts

@@ -0,0 +1,86 @@
+import { UserError } from "@openagentpack/sdk";
+import { type ApiErrorBody, BailianError, ExitCode, mapApiError } from "bailian-cli-core";
+
+/**
+ * Structural shape of the SDK's `ApiError` (thrown by provider clients on HTTP
+ * 4xx/5xx). Matched on fields instead of `instanceof` because the installed SDK
+ * version does not export the class yet, and structural matching keeps this
+ * check stable across SDK versions either way.
+ */
+interface SdkApiErrorLike extends Error {
+  statusCode: number;
+  responseBody: string;
+}
+
+function isSdkApiError(error: Error): error is SdkApiErrorLike {
+  const candidate = error as Partial<SdkApiErrorLike>;
+  return typeof candidate.statusCode === "number" && typeof candidate.responseBody === "string";
+}
+
+/**
+ * The SDK embeds the raw response body in its error message; recover the
+ * structured fields (message / code / request_id) when the body is JSON so
+ * `mapApiError` surfaces a clean server message plus api metadata. Non-JSON
+ * bodies pass through verbatim as the message.
+ */
+function parseSdkResponseBody(raw: string): ApiErrorBody {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (parsed && typeof parsed === "object") return parsed as ApiErrorBody;
+  } catch {
+    /* non-JSON body */
+  }
+  return { message: raw.trim() || undefined };
+}
+
+/**
+ * The SDK's session polling deadline surfaces as a plain `UserError` (no
+ * dedicated timeout class as of SDK 0.3.x), so it is recognized by its stable
+ * message shape: "Session did not complete within the timeout (N seconds)."
+ * (session-runtime's assertNotTimedOut — the SDK's only timeout UserError).
+ * It is a client-side wait limit, not a usage mistake → per bl's error
+ * boundary it must exit TIMEOUT, not USAGE.
+ */
+function isSdkPollingTimeout(error: UserError): boolean {
+  return /did not complete within the timeout/i.test(error.message);
+}
+
+/**
+ * Run an SDK-backed operation, translating SDK error types into BailianError so
+ * bl's error handler produces the right exit code and hint formatting.
+ * SDK `UserError` → USAGE — except the polling-deadline UserError, which is a
+ * client-side timeout → TIMEOUT with a wait-longer hint; SDK `ApiError`
+ * (server HTTP error) → GENERAL via `mapApiError` (server message passed
+ * through verbatim, with httpStatus/apiCode/requestId metadata for
+ * --output json); fetch transport failures (`TypeError: fetch failed`) are
+ * rethrown untouched so the runtime error handler maps them to NETWORK with an
+ * errno-specific hint, matching the native client path; any other Error →
+ * GENERAL (message passed through, per bl's "don't translate server errors"
+ * boundary).
+ */
+export async function withAgentErrors<T>(fn: () => Promise<T>): Promise<T> {
+  try {
+    return await fn();
+  } catch (error) {
+    if (error instanceof BailianError) throw error;
+    if (error instanceof UserError) {
+      if (isSdkPollingTimeout(error)) {
+        throw new BailianError(
+          error.message,
+          ExitCode.TIMEOUT,
+          // `bl` prefix is safe: agent commands ship on `bl` only.
+          "The session may still be running — check `bl managed-agent session get --session-id <id>` or `session events`.",
+        );
+      }
+      throw new BailianError(error.message, ExitCode.USAGE);
+    }
+    if (error instanceof Error && isSdkApiError(error)) {
+      throw mapApiError(error.statusCode, parseSdkResponseBody(error.responseBody));
+    }
+    // DNS/TCP/TLS failures from the SDK's fetch: keep the original TypeError so
+    // the runtime error handler classifies it as NETWORK (exit 6) + errno hint.
+    if (error instanceof TypeError && error.message === "fetch failed") throw error;
+    if (error instanceof Error) throw new BailianError(error.message, ExitCode.GENERAL);
+    throw error;
+  }
+}

packages/commands/src/commands/managed-agent/_engine/feedback.ts

@@ -0,0 +1,10 @@
+import type { RuntimeFeedbackEvent } from "@openagentpack/sdk";
+
+/**
+ * Render SDK runtime feedback to stderr, keeping stdout a clean data channel.
+ * Used as the `onFeedback` sink for plan/apply so progress messages don't mix
+ * with structured output.
+ */
+export function renderAgentFeedback(event: RuntimeFeedbackEvent): void {
+  process.stderr.write(`${event.message}\n`);
+}

packages/commands/src/commands/managed-agent/_engine/file-state-manager.ts

@@ -0,0 +1,24 @@
+import { basename, dirname, resolve } from "node:path";
+import {
+  type IStateManager,
+  LocalFileStateBackend,
+  StateManager,
+  type StateScope,
+} from "@openagentpack/sdk";
+
+function createStateScope(configPath: string, projectName?: string): StateScope {
+  const resolved = resolve(configPath);
+  return { projectId: projectName ?? basename(dirname(resolved)) };
+}
+
+/** Load or initialize a file-based StateManager (mirrors OpenAgentPack CLI). */
+export async function loadFileState(
+  configPath: string,
+  statePath?: string,
+  projectName?: string,
+): Promise<IStateManager> {
+  const resolved = resolve(configPath);
+  const backend = new LocalFileStateBackend({ configPath: resolved, statePath });
+  const path = backend.getStatePath(createStateScope(resolved, projectName));
+  return StateManager.load(path);
+}

packages/commands/src/commands/managed-agent/_engine/pagination.ts

@@ -0,0 +1,25 @@
+export interface PagedResult<T> {
+  items: T[];
+  hasMore: boolean;
+  nextPage?: string;
+}
+
+/** Fetch the first page, then follow cursors while `all` is true. */
+export async function fetchAllPages<T>(
+  fetchPage: (page?: string) => Promise<PagedResult<T>>,
+  all?: boolean,
+): Promise<PagedResult<T>> {
+  const first = await fetchPage();
+  const items = [...first.items];
+  let hasMore = first.hasMore;
+  let nextPage = first.nextPage;
+
+  while (all && nextPage) {
+    const next = await fetchPage(nextPage);
+    items.push(...next.items);
+    hasMore = next.hasMore;
+    nextPage = next.nextPage;
+  }
+
+  return { items, hasMore, nextPage };
+}

packages/commands/src/commands/managed-agent/_engine/session-render.ts

@@ -0,0 +1,129 @@
+import {
+  type CollectedSessionEvents,
+  isTerminalSessionStatus,
+  type ProviderSessionEvent,
+} from "@openagentpack/sdk";
+import { sanitizeSessionEvents } from "@openagentpack/sdk/session-events";
+import { BailianError, ExitCode } from "bailian-cli-core";
+
+/** Skip user echo + thinking noise in live rendering (mirrors OpenAgentPack CLI). */
+function shouldRenderLiveEvent(event: ProviderSessionEvent): boolean {
+  return event.type !== "thinking" && !(event.type === "message" && event.role === "user");
+}
+
+function renderTerminalStatus(status: string, json: boolean): void {
+  if (json) return;
+  process.stderr.write(`\n[session ${status}]\n`);
+}
+
+function findLastSessionError(events: readonly ProviderSessionEvent[]): string | undefined {
+  for (let index = events.length - 1; index >= 0; index--) {
+    const event = events[index];
+    if (event?.type === "error" && event.content?.trim()) return event.content;
+  }
+  return undefined;
+}
+
+function throwIfSessionFailed(status: string | undefined, message?: string): void {
+  if (status !== "failed") return;
+  throw new BailianError(message ?? "Session failed.", ExitCode.GENERAL);
+}
+
+/**
+ * Session identity echoed at the head of the `--output json` envelope so
+ * callers can read the (possibly just-created) session id from stdout and
+ * chain `session send/get/events/delete` — without scraping stderr.
+ * Undefined fields are dropped by JSON.stringify.
+ */
+export interface SessionRenderContext {
+  session_id?: string;
+  provider?: string;
+  agent?: string;
+}
+
+/**
+ * Consume an SSE stream. Text mode renders live (assistant text → stdout,
+ * diagnostics → stderr). JSON mode collects every event and emits exactly one
+ * JSON document at the end — `--output json` guarantees a single valid JSON
+ * result on stdout (mirrors `text chat --stream --output json`). `context`
+ * prefixes the envelope with the session identity.
+ */
+export async function streamAndRenderEvents(
+  events: AsyncIterable<ProviderSessionEvent>,
+  json: boolean,
+  context: SessionRenderContext = {},
+): Promise<void> {
+  const collected: ProviderSessionEvent[] = [];
+  let terminalStatus: string | undefined;
+  let errorMessage: string | undefined;
+  for await (const event of events) {
+    if (json) collected.push(event);
+    else renderEvent(event);
+    if (event.type === "error" && event.content?.trim()) errorMessage = event.content;
+    if (event.type === "status" && isTerminalSessionStatus(event.status)) {
+      terminalStatus = event.status;
+      renderTerminalStatus(event.status ?? "", json);
+      break;
+    }
+  }
+  if (json) {
+    process.stdout.write(
+      `${JSON.stringify({ ...context, events: sanitizeSessionEvents(collected) }, null, 2)}\n`,
+    );
+  }
+  throwIfSessionFailed(terminalStatus, errorMessage);
+}
+
+/** Assistant text → stdout (data channel); everything else → stderr (diagnostics). */
+function renderEvent(event: ProviderSessionEvent): void {
+  if (!shouldRenderLiveEvent(event)) return;
+  if (event.type === "message" && event.content) {
+    process.stdout.write(event.content);
+  } else if (event.type === "tool_use") {
+    process.stderr.write(`\n[tool] ${event.tool_name}\n`);
+  } else if (event.type === "tool_result" && event.content) {
+    const preview =
+      event.content.length > 200 ? `${event.content.slice(0, 200)}...` : event.content;
+    process.stderr.write(`${preview}\n`);
+  } else if (event.type === "status") {
+    if (event.status === "running") process.stderr.write("\n[session running]\n");
+  } else if (event.type === "error") {
+    process.stderr.write(`\n[error] ${event.content ?? "unknown error"}\n`);
+  }
+}
+
+/** Render a polled (non-streaming) collected result. `context` prefixes the JSON envelope. */
+export function renderCollectedEvents(
+  result: CollectedSessionEvents,
+  json: boolean,
+  context: SessionRenderContext = {},
+): void {
+  if (json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          ...context,
+          events: sanitizeSessionEvents(result.result.events),
+          has_more: result.result.has_more,
+          next_page: result.result.next_page,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+  } else {
+    for (const event of result.result.events) renderEvent(event);
+    renderTerminalStatus(result.terminalStatus, json);
+  }
+  throwIfSessionFailed(result.terminalStatus, findLastSessionError(result.result.events));
+}
+
+/** Split a comma-separated --memory-stores value. */
+export function parseMemoryStores(value?: string): string[] | undefined {
+  return value
+    ? value
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+    : undefined;
+}

packages/commands/src/commands/managed-agent/_engine/transport.ts

@@ -0,0 +1,29 @@
+import * as sdk from "@openagentpack/sdk";
+import {
+  createInstrumentedFetch,
+  type FetchImplementation,
+  type Identity,
+  type Settings,
+} from "bailian-cli-core";
+
+/** The slice of CommandContext the transport wrapper needs (UA identity + verbose). */
+export interface HostContext {
+  identity: Identity;
+  settings: Settings;
+}
+
+let installed = false;
+
+/**
+ * Route the SDK's provider-client requests through the CLI's instrumented
+ * fetch (UA, host-gated tracking headers, --verbose logging). Feature-detected:
+ * `setDefaultFetch` landed after @openagentpack/sdk 0.1.0 — on older versions
+ * this is a silent no-op and the SDK keeps using the global fetch as before.
+ */
+export function installSdkTransport(host: HostContext): void {
+  if (installed) return;
+  const setDefaultFetch = (sdk as Record<string, unknown>).setDefaultFetch;
+  if (typeof setDefaultFetch !== "function") return;
+  (setDefaultFetch as (fetchImpl: FetchImplementation) => void)(createInstrumentedFetch(host));
+  installed = true;
+}

packages/commands/src/commands/managed-agent/apply.ts

@@ -0,0 +1,148 @@
+import {
+  BailianError,
+  defineCommand,
+  detectOutputFormat,
+  ExitCode,
+  type FlagsDef,
+} from "bailian-cli-core";
+import { emitBare, emitResult } from "bailian-cli-runtime";
+import { executePlannedProject, planProjectContext } from "@openagentpack/sdk";
+import { formatResourceLabel } from "./_engine/address-utils.ts";
+import {
+  assertProviderConfigured,
+  buildAgentRuntime,
+  CREDENTIALS_NOTE,
+} from "./_engine/config-loader.ts";
+import { withStdoutProtected } from "./_engine/console-capture.ts";
+import { withAgentErrors } from "./_engine/errors.ts";
+import { renderAgentFeedback } from "./_engine/feedback.ts";
+
+const APPLY_FLAGS = {
+  file: {
+    type: "string",
+    valueHint: "<path>",
+    description: "Config file path (default: agents.yaml)",
+  },
+  provider: {
+    type: "string",
+    valueHint: "<name>",
+    description: "Target provider (default: all configured)",
+  },
+  yes: {
+    type: "switch",
+    description: "Confirm and apply without an interactive prompt (required to mutate)",
+  },
+  noRefresh: {
+    type: "switch",
+    description: "Skip refreshing state from remote before planning",
+  },
+  concurrency: {
+    type: "number",
+    valueHint: "<n>",
+    description: "Max independent resources to apply in parallel (default 6, max 10)",
+  },
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Apply planned changes to create/update/delete agent resources",
+  auth: "apiKey",
+  usageArgs: "[--file <path>] [--provider <name>] [--yes] [--concurrency <n>]",
+  flags: APPLY_FLAGS,
+  exampleArgs: ["--yes", "--provider bailian --yes"],
+  notes: CREDENTIALS_NOTE,
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const format = detectOutputFormat(settings.output);
+    const file = flags.file ?? "agents.yaml";
+
+    if (settings.dryRun) {
+      emitResult(
+        {
+          would_apply: {
+            provider: flags.provider ?? "all",
+            refresh: !flags.noRefresh,
+            concurrency: flags.concurrency,
+          },
+          config_file: file,
+          hint: "Run `managed-agent plan` to preview the exact resource changes.",
+        },
+        format,
+      );
+      return;
+    }
+
+    const planned = await withAgentErrors(() =>
+      withStdoutProtected(async () => {
+        const runtime = await buildAgentRuntime(ctx, file);
+        assertProviderConfigured(runtime, flags.provider);
+        return planProjectContext(runtime, {
+          provider: flags.provider,
+          refresh: !flags.noRefresh,
+          quiet: true,
+          onFeedback: renderAgentFeedback,
+        });
+      }),
+    );
+
+    const plan = planned.plan;
+    // In --output json, stdout must stay a single-JSON data channel: diagnostics
+    // and the action preview are progress info → stderr; text mode keeps stdout.
+    const emitProgress = (line: string): void => {
+      if (format === "json") process.stderr.write(`${line}\n`);
+      else emitBare(line);
+    };
+    if (plan.diagnostics.some((diag) => diag.severity === "error")) {
+      for (const diag of plan.diagnostics) {
+        if (diag.severity === "error") emitProgress(`[error] ${diag.code}: ${diag.message}`);
+      }
+      throw new BailianError("Cannot apply: resolve the errors above first.", ExitCode.GENERAL);
+    }
+
+    const actionable = plan.actions.filter((action) => action.action !== "no-op");
+    if (actionable.length === 0) {
+      if (format === "json")
+        emitResult({ succeeded: 0, failed: 0, skipped: 0, results: [] }, format);
+      else emitBare("No changes. Infrastructure is up-to-date.");
+      return;
+    }
+
+    const creates = actionable.filter((action) => action.action === "create").length;
+    const updates = actionable.filter((action) => action.action === "update").length;
+    const deletes = planned.destructiveActions;
+
+    for (const action of actionable) {
+      const icon = action.action === "create" ? "+" : action.action === "update" ? "~" : "-";
+      emitProgress(`  ${icon} ${formatResourceLabel(action.address)}`);
+    }
+
+    if (!flags.yes) {
+      throw new BailianError(
+        `Refusing to apply ${actionable.length} change(s) (${creates} create, ${updates} update, ${deletes.length} destroy) without confirmation.`,
+        ExitCode.USAGE,
+        "Review with `bl managed-agent plan`, then re-run with --yes to apply.",
+      );
+    }
+
+    const result = await withAgentErrors(() =>
+      withStdoutProtected(() =>
+        executePlannedProject(planned, {
+          onFeedback: renderAgentFeedback,
+          policy: "force",
+          concurrency: flags.concurrency,
+        }),
+      ),
+    );
+
+    const succeeded = result.results.filter((entry) => entry.status === "success").length;
+    const failed = result.results.filter((entry) => entry.status === "failed").length;
+    const skipped = result.results.filter((entry) => entry.status === "skipped").length;
+
+    if (format === "json") {
+      emitResult({ succeeded, failed, skipped, results: result.results }, format);
+    } else {
+      emitBare(`\nApply finished: ${succeeded} succeeded, ${failed} failed, ${skipped} skipped.`);
+    }
+
+    if (failed > 0) throw new BailianError("Apply failed.", ExitCode.GENERAL);
+  },
+});

packages/commands/src/commands/managed-agent/destroy.ts

@@ -0,0 +1,114 @@
+import {
+  BailianError,
+  defineCommand,
+  detectOutputFormat,
+  ExitCode,
+  type FlagsDef,
+} from "bailian-cli-core";
+import { emitBare, emitResult } from "bailian-cli-runtime";
+import { destroyPlannedProjectResources, planDestroyProjectContext } from "@openagentpack/sdk";
+import { formatResourceLabel } from "./_engine/address-utils.ts";
+import { buildAgentRuntime, CREDENTIALS_NOTE } from "./_engine/config-loader.ts";
+import { withStdoutProtected } from "./_engine/console-capture.ts";
+import { withAgentErrors } from "./_engine/errors.ts";
+
+const DESTROY_FLAGS = {
+  file: {
+    type: "string",
+    valueHint: "<path>",
+    description: "Config file path (default: agents.yaml)",
+  },
+  yes: {
+    type: "switch",
+    description: "Confirm and destroy without an interactive prompt (required)",
+  },
+  cascade: {
+    type: "switch",
+    description: "Auto-delete dependent resources (e.g. sessions referencing an environment)",
+  },
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Destroy all managed agent resources tracked in state",
+  auth: "apiKey",
+  usageArgs: "[--file <path>] [--yes] [--cascade]",
+  flags: DESTROY_FLAGS,
+  exampleArgs: ["--yes", "--yes --cascade"],
+  notes: CREDENTIALS_NOTE,
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const format = detectOutputFormat(settings.output);
+    const file = flags.file ?? "agents.yaml";
+
+    if (settings.dryRun) {
+      emitResult(
+        {
+          would_destroy: { cascade: Boolean(flags.cascade) },
+          config_file: file,
+          hint: "Run `managed-agent state list` to see the resources tracked in state.",
+        },
+        format,
+      );
+      return;
+    }
+
+    const planned = await withAgentErrors(() =>
+      withStdoutProtected(async () => {
+        const runtime = await buildAgentRuntime(ctx, file);
+        return planDestroyProjectContext(runtime);
+      }),
+    );
+
+    const resources = planned.resources;
+    if (resources.length === 0) {
+      if (format === "json") emitResult({ destroyed: 0, total: 0 }, format);
+      else emitBare("No resources in state. Nothing to destroy.");
+      return;
+    }
+
+    // In --output json, stdout must stay a single-JSON data channel: the
+    // resource preview is progress info → stderr; text mode keeps stdout.
+    for (const resource of resources) {
+      const line = `  - ${formatResourceLabel(resource.address)} [${resource.remote_id}]`;
+      if (format === "json") process.stderr.write(`${line}\n`);
+      else emitBare(line);
+    }
+
+    if (!flags.yes) {
+      throw new BailianError(
+        `Refusing to destroy ${resources.length} resource(s) without confirmation.`,
+        ExitCode.USAGE,
+        "Re-run with --yes to destroy (add --cascade to remove dependents).",
+      );
+    }
+
+    const result = await withAgentErrors(() =>
+      withStdoutProtected(() =>
+        destroyPlannedProjectResources(planned, {
+          cascade: flags.cascade,
+          onCascadeRequired: async () => Boolean(flags.cascade),
+          onResourceResult: (item) => {
+            const label = formatResourceLabel(item.resource.address);
+            process.stderr.write(`  ${item.status === "success" ? "✓" : "✗"} ${label}\n`);
+          },
+        }),
+      ),
+    );
+
+    if (format === "json") {
+      emitResult({ destroyed: result.destroyed, total: result.resources.length }, format);
+    } else {
+      const status = result.partial ? "Destroy incomplete" : "Destroy complete";
+      emitBare(`\n${status}. ${result.destroyed}/${result.resources.length} resources removed.`);
+    }
+
+    if (result.partial) {
+      const firstFailure = result.results.find((item) => item.status !== "success");
+      throw new BailianError(
+        firstFailure?.error ||
+          `Destroy incomplete: ${result.destroyed}/${result.resources.length} resources removed.`,
+        ExitCode.GENERAL,
+      );
+    }
+  },
+});

packages/commands/src/commands/managed-agent/init.ts

@@ -0,0 +1,165 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import {
+  BailianError,
+  defineCommand,
+  detectOutputFormat,
+  ExitCode,
+  type FlagsDef,
+} from "bailian-cli-core";
+import { emitBare, emitResult } from "bailian-cli-runtime";
+
+const GITIGNORE_ADDITIONS = `
+# agents
+agents.state.json
+.env
+`;
+
+const PROVIDERS = ["bailian", "claude", "qoder", "ark", "all"] as const;
+
+const PROVIDER_BLOCKS: Record<string, string> = {
+  bailian: `  bailian:\n    # bl auth login --api-key <key> sets DASHSCOPE_API_KEY; --base-url <url> sets BAILIAN_BASE_URL\n    api_key: \${DASHSCOPE_API_KEY}\n    base_url: \${BAILIAN_BASE_URL}`,
+  claude: `  claude:\n    api_key: \${ANTHROPIC_API_KEY}`,
+  qoder: `  qoder:\n    api_key: \${QODER_PAT}\n    gateway: "https://api.qoder.com/api/v1/cloud"`,
+  ark: `  ark:\n    api_key: \${ARK_API_KEY}`,
+};
+
+const SINGLE_MODEL: Record<string, string> = {
+  bailian: `    model: qwen3.7-max`,
+  claude: `    model: claude-sonnet-4-6`,
+  qoder: `    model: ultimate`,
+  ark: `    model: doubao-seed-2-1-pro-260628`,
+};
+
+function buildTemplate(options: { provider: string; agentName: string }): string {
+  const providerBlock =
+    options.provider === "all"
+      ? `${PROVIDER_BLOCKS.bailian}\n${PROVIDER_BLOCKS.claude}\n${PROVIDER_BLOCKS.qoder}\n${PROVIDER_BLOCKS.ark}`
+      : PROVIDER_BLOCKS[options.provider]!;
+
+  const modelBlock =
+    options.provider === "all"
+      ? `    model:\n      bailian: qwen3.7-max\n      claude: claude-sonnet-4-6\n      qoder: ultimate\n      ark: doubao-seed-2-1-pro-260628`
+      : SINGLE_MODEL[options.provider]!;
+
+  const toolBlock =
+    options.provider === "bailian"
+      ? "[bash, read, glob, grep]"
+      : "[read, glob, grep, web_search, web_fetch]";
+
+  return `version: "1"
+
+providers:
+${providerBlock}
+
+defaults:
+  provider: ${options.provider === "all" ? "all" : options.provider}
+
+environments:
+  dev:
+    config:
+      type: cloud
+      networking:
+        type: unrestricted
+
+agents:
+  ${options.agentName}:
+    description: "General-purpose assistant"
+${modelBlock}
+    instructions: |
+      You are a helpful assistant.
+    environment: dev
+    tools:
+      builtin: ${toolBlock}
+`;
+}
+
+const INIT_FLAGS = {
+  provider: {
+    type: "string",
+    valueHint: "<name>",
+    description: "Provider: bailian, claude, qoder, ark, all (default: bailian)",
+    choices: PROVIDERS,
+  },
+  agentName: {
+    type: "string",
+    valueHint: "<name>",
+    description: "Name of the first agent (default: assistant)",
+  },
+  file: {
+    type: "string",
+    valueHint: "<path>",
+    description: "Output config path (default: agents.yaml)",
+  },
+  force: {
+    type: "switch",
+    description: "Overwrite an existing config file",
+  },
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Create a new agents.yaml template",
+  auth: "none",
+  usageArgs: "[--provider <name>] [--agent-name <name>] [--file <path>] [--force]",
+  flags: INIT_FLAGS,
+  exampleArgs: ["", "--provider bailian --agent-name assistant", "--provider all"],
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const format = detectOutputFormat(settings.output);
+    const provider = flags.provider ?? "bailian";
+    const agentName = flags.agentName ?? "assistant";
+    const file = flags.file ?? "agents.yaml";
+
+    if (existsSync(file) && !flags.force) {
+      throw new BailianError(
+        `${file} already exists.`,
+        ExitCode.USAGE,
+        "Pass --force to overwrite.",
+      );
+    }
+
+    const gitignorePath = ".gitignore";
+
+    if (settings.dryRun) {
+      let wouldUpdateGitignore = true;
+      if (existsSync(gitignorePath)) {
+        const content = await readFile(gitignorePath, "utf8");
+        wouldUpdateGitignore = !content.includes("agents.state.json");
+      }
+      emitResult(
+        {
+          would_create: file,
+          provider,
+          agent: agentName,
+          would_update_gitignore: wouldUpdateGitignore,
+        },
+        format,
+      );
+      return;
+    }
+
+    const template = buildTemplate({ provider, agentName });
+    await writeFile(file, template, "utf8");
+
+    if (existsSync(gitignorePath)) {
+      const content = await readFile(gitignorePath, "utf8");
+      if (!content.includes("agents.state.json")) {
+        await writeFile(gitignorePath, content + GITIGNORE_ADDITIONS, "utf8");
+      }
+    } else {
+      await writeFile(gitignorePath, `${GITIGNORE_ADDITIONS.trim()}\n`, "utf8");
+    }
+
+    if (format === "json") {
+      emitResult({ created: file, provider, agent: agentName }, format);
+    } else {
+      emitBare(`Created ${file}`);
+      if (provider === "bailian" || provider === "all") {
+        emitBare(
+          "Credentials: run `bl auth login --api-key <key> --base-url <url>`, or set DASHSCOPE_API_KEY / BAILIAN_BASE_URL.",
+        );
+      }
+      emitBare("Next: edit agents.yaml, then run `bl managed-agent plan`.");
+    }
+  },
+});

packages/commands/src/commands/managed-agent/plan.ts

@@ -0,0 +1,112 @@
+import {
+  BailianError,
+  defineCommand,
+  detectOutputFormat,
+  ExitCode,
+  type FlagsDef,
+} from "bailian-cli-core";
+import { emitBare, emitResult } from "bailian-cli-runtime";
+import { planProjectContext } from "@openagentpack/sdk";
+import { formatResourceLabel } from "./_engine/address-utils.ts";
+import {
+  assertProviderConfigured,
+  buildAgentRuntime,
+  CREDENTIALS_NOTE,
+} from "./_engine/config-loader.ts";
+import { withStdoutProtected } from "./_engine/console-capture.ts";
+import { withAgentErrors } from "./_engine/errors.ts";
+import { renderAgentFeedback } from "./_engine/feedback.ts";
+
+const PLAN_FLAGS = {
+  file: {
+    type: "string",
+    valueHint: "<path>",
+    description: "Config file path (default: agents.yaml)",
+  },
+  provider: {
+    type: "string",
+    valueHint: "<name>",
+    description: "Target provider (default: all configured)",
+  },
+  noRefresh: {
+    type: "switch",
+    description: "Skip refreshing state from remote before planning",
+  },
+  refreshOnly: {
+    type: "switch",
+    description: "Refresh state and show drift without planning remote mutations",
+  },
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Show what changes would be applied to agent infrastructure",
+  auth: "apiKey",
+  usageArgs: "[--file <path>] [--provider <name>] [--no-refresh] [--refresh-only]",
+  flags: PLAN_FLAGS,
+  exampleArgs: ["", "--provider bailian", "--no-refresh"],
+  notes: [
+    ...CREDENTIALS_NOTE,
+    "--no-refresh and --dry-run plan offline from local config and state: no remote requests, no state writes, provider keys are not checked.",
+  ],
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const format = detectOutputFormat(settings.output);
+    const file = flags.file ?? "agents.yaml";
+    // Offline mode never talks to a provider and never saves refreshed state:
+    // --no-refresh by explicit request, --dry-run by contract (read-only run).
+    // Provider keys are skipped then; the bl login gate (auth: "apiKey") still
+    // applies except under --dry-run (authStage's dry-run exemption).
+    const offline = Boolean(flags.noRefresh) || settings.dryRun;
+
+    const planned = await withAgentErrors(() =>
+      withStdoutProtected(async () => {
+        const runtime = await buildAgentRuntime(ctx, file, {
+          credentials: offline ? "none" : "all",
+        });
+        assertProviderConfigured(runtime, flags.provider);
+        return planProjectContext(runtime, {
+          provider: flags.provider,
+          refresh: !offline,
+          quiet: format === "json",
+          onFeedback: format === "json" ? undefined : renderAgentFeedback,
+        });
+      }),
+    );
+
+    const plan = planned.plan;
+    const hasErrors = plan.diagnostics.some((diag) => diag.severity === "error");
+
+    if (format === "json") {
+      emitResult(plan, format);
+      if (hasErrors) throw new BailianError("Plan contains errors.", ExitCode.GENERAL);
+      return;
+    }
+
+    for (const diag of plan.diagnostics) {
+      emitBare(`[${diag.severity}] ${diag.code}: ${diag.message}`);
+    }
+    if (hasErrors) throw new BailianError("Plan contains errors.", ExitCode.GENERAL);
+
+    const creates = plan.actions.filter((action) => action.action === "create");
+    const updates = plan.actions.filter((action) => action.action === "update");
+    const deletes = plan.actions.filter((action) => action.action === "delete");
+
+    if (creates.length + updates.length + deletes.length === 0) {
+      emitBare("No changes. Infrastructure is up-to-date.");
+      if (flags.refreshOnly) emitBare("Refresh-only mode: no remote mutations were performed.");
+      return;
+    }
+
+    emitBare("\nPlanned actions:\n");
+    for (const action of creates) emitBare(`  + ${formatResourceLabel(action.address)}`);
+    for (const action of updates) {
+      emitBare(`  ~ ${formatResourceLabel(action.address)}`);
+      if (action.reason) emitBare(`    ${action.reason}`);
+    }
+    for (const action of deletes) emitBare(`  - ${formatResourceLabel(action.address)}`);
+    emitBare(
+      `\nPlan: ${creates.length} to create, ${updates.length} to update, ${deletes.length} to destroy.`,
+    );
+    if (flags.refreshOnly) emitBare("Refresh-only mode: no remote mutations will be performed.");
+  },
+});

packages/commands/src/commands/managed-agent/session-create.ts

@@ -0,0 +1,101 @@
+import { defineCommand, detectOutputFormat, type FlagsDef } from "bailian-cli-core";
+import { emitBare, emitResult } from "bailian-cli-runtime";
+import { createSessionForAgent } from "@openagentpack/sdk";
+import { buildAgentRuntime, CREDENTIALS_NOTE } from "./_engine/config-loader.ts";
+import { withStdoutProtected } from "./_engine/console-capture.ts";
+import { withAgentErrors } from "./_engine/errors.ts";
+import { parseMemoryStores } from "./_engine/session-render.ts";
+
+const SESSION_CREATE_FLAGS = {
+  file: {
+    type: "string",
+    valueHint: "<path>",
+    description: "Config file path (default: agents.yaml)",
+  },
+  agent: {
+    type: "string",
+    valueHint: "<name>",
+    description: "Agent name (auto-detected when only one agent is configured)",
+  },
+  environment: {
+    type: "string",
+    valueHint: "<name>",
+    description: "Override agent's declared environment",
+  },
+  vault: {
+    type: "string",
+    valueHint: "<name>",
+    description: "Override agent's declared vault",
+  },
+  memoryStores: {
+    type: "string",
+    valueHint: "<names>",
+    description: "Override agent's memory stores (comma-separated)",
+  },
+  title: { type: "string", valueHint: "<title>", description: "Session title" },
+  provider: {
+    type: "string",
+    valueHint: "<name>",
+    description: "Target provider (multi-provider agents)",
+  },
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Create a new session for an agent",
+  auth: "apiKey",
+  usageArgs: "[--agent <name>] [--environment <name>] [--title <title>] [--file <path>]",
+  flags: SESSION_CREATE_FLAGS,
+  exampleArgs: ["", "--agent assistant", "--agent assistant --title 'debug run'"],
+  notes: CREDENTIALS_NOTE,
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const format = detectOutputFormat(settings.output);
+    const file = flags.file ?? "agents.yaml";
+
+    if (settings.dryRun) {
+      emitResult(
+        {
+          would_create_session: {
+            agent: flags.agent ?? "auto",
+            provider: flags.provider ?? "auto",
+            environment: flags.environment,
+            vault: flags.vault,
+            memory_stores: parseMemoryStores(flags.memoryStores),
+            title: flags.title,
+          },
+          config_file: file,
+        },
+        format,
+      );
+      return;
+    }
+
+    const run = await withAgentErrors(() =>
+      withStdoutProtected(async () => {
+        const runtime = await buildAgentRuntime(ctx, file);
+        return createSessionForAgent(runtime, {
+          agent: flags.agent,
+          provider: flags.provider,
+          environment: flags.environment,
+          vault: flags.vault,
+          memoryStores: parseMemoryStores(flags.memoryStores),
+          title: flags.title,
+        });
+      }),
+    );
+
+    const { agentName, session } = run;
+    if (format === "json") {
+      emitResult({ agent: agentName, session }, format);
+      return;
+    }
+    emitBare(`Session created: ${session.id}`);
+    emitBare(`  Agent:       ${agentName}`);
+    emitBare(`  Environment: ${session.environment_id}`);
+    emitBare(`  Status:      ${session.status}`);
+    if (session.vault_ids.length) emitBare(`  Vaults:      ${session.vault_ids.join(", ")}`);
+    if (session.memory_store_ids.length) {
+      emitBare(`  Memory:      ${session.memory_store_ids.join(", ")}`);
+    }
+  },
+});

packages/commands/src/commands/managed-agent/session-delete.ts

@@ -0,0 +1,61 @@
+import { defineCommand, detectOutputFormat, type FlagsDef } from "bailian-cli-core";
+import { emitBare, emitResult } from "bailian-cli-runtime";
+import { deleteSession } from "@openagentpack/sdk";
+import { buildAgentRuntime, CREDENTIALS_NOTE } from "./_engine/config-loader.ts";
+import { withStdoutProtected } from "./_engine/console-capture.ts";
+import { withAgentErrors } from "./_engine/errors.ts";
+
+const SESSION_DELETE_FLAGS = {
+  sessionId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Session ID (required)",
+    required: true,
+  },
+  file: {
+    type: "string",
+    valueHint: "<path>",
+    description: "Config file path (default: agents.yaml)",
+  },
+  provider: {
+    type: "string",
+    valueHint: "<name>",
+    description: "Target provider",
+  },
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Delete a session",
+  auth: "apiKey",
+  usageArgs: "--session-id <id> [--provider <name>] [--file <path>]",
+  flags: SESSION_DELETE_FLAGS,
+  exampleArgs: ["--session-id sess_abc123"],
+  notes: CREDENTIALS_NOTE,
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const format = detectOutputFormat(settings.output);
+    const file = flags.file ?? "agents.yaml";
+
+    if (settings.dryRun) {
+      emitResult(
+        {
+          would_delete_session: flags.sessionId,
+          provider: flags.provider ?? "auto",
+          config_file: file,
+        },
+        format,
+      );
+      return;
+    }
+
+    await withAgentErrors(() =>
+      withStdoutProtected(async () => {
+        const runtime = await buildAgentRuntime(ctx, file);
+        await deleteSession(runtime, flags.sessionId, flags.provider);
+      }),
+    );
+
+    if (format === "json") emitResult({ deleted: flags.sessionId }, format);
+    else emitBare(`Session ${flags.sessionId} deleted.`);
+  },
+});

packages/commands/src/commands/managed-agent/session-events.ts

@@ -0,0 +1,92 @@
+import { defineCommand, detectOutputFormat, type FlagsDef } from "bailian-cli-core";
+import { emitBare, emitResult, formatTable } from "bailian-cli-runtime";
+import { listSessionEvents } from "@openagentpack/sdk";
+import { sanitizeSessionEvents } from "@openagentpack/sdk/session-events";
+import { buildAgentRuntime, CREDENTIALS_NOTE } from "./_engine/config-loader.ts";
+import { withStdoutProtected } from "./_engine/console-capture.ts";
+import { withAgentErrors } from "./_engine/errors.ts";
+import { fetchAllPages } from "./_engine/pagination.ts";
+
+const SESSION_EVENTS_FLAGS = {
+  sessionId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Session ID (required)",
+    required: true,
+  },
+  file: {
+    type: "string",
+    valueHint: "<path>",
+    description: "Config file path (default: agents.yaml)",
+  },
+  provider: {
+    type: "string",
+    valueHint: "<name>",
+    description: "Target provider",
+  },
+  limit: {
+    type: "number",
+    valueHint: "<n>",
+    description: "Maximum number of events to fetch",
+  },
+  all: {
+    type: "switch",
+    description: "Fetch all pages by following the cursor",
+  },
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "List event history for a session",
+  auth: "apiKey",
+  usageArgs: "--session-id <id> [--limit <n>] [--all] [--file <path>]",
+  flags: SESSION_EVENTS_FLAGS,
+  exampleArgs: ["--session-id sess_abc123", "--session-id sess_abc123 --all"],
+  notes: CREDENTIALS_NOTE,
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const format = detectOutputFormat(settings.output);
+    const file = flags.file ?? "agents.yaml";
+
+    const { items: events, hasMore } = await withAgentErrors(() =>
+      withStdoutProtected(async () => {
+        const runtime = await buildAgentRuntime(ctx, file);
+        return fetchAllPages(async (page) => {
+          const result = await listSessionEvents(runtime, flags.sessionId, {
+            provider: flags.provider,
+            limit: flags.limit,
+            page_token: page,
+          });
+          return {
+            items: result.events,
+            hasMore: result.has_more,
+            nextPage: result.next_page,
+          };
+        }, flags.all);
+      }),
+    );
+
+    if (format === "json") {
+      emitResult({ events: sanitizeSessionEvents(events), has_more: hasMore }, format);
+      return;
+    }
+    if (events.length === 0) {
+      emitBare("No events found.");
+      return;
+    }
+
+    const headers = ["#", "TYPE", "CONTENT"];
+    const rows = events.map((event, index) => {
+      let preview = "";
+      if (event.type === "message") preview = (event.content ?? "").slice(0, 60);
+      else if (event.type === "tool_use") preview = event.tool_name ?? "";
+      else if (event.type === "tool_result") preview = (event.content ?? "").slice(0, 60);
+      else if (event.type === "status") preview = event.status ?? "";
+      else if (event.type === "error") preview = (event.content ?? "").slice(0, 60);
+      else preview = event.raw_type;
+      return [String(index + 1), event.type, preview];
+    });
+    for (const line of formatTable(headers, rows)) emitBare(line);
+    emitBare(`\nTotal: ${events.length}`);
+    if (hasMore) emitBare("More events available. Use --all to fetch all.");
+  },
+});

packages/commands/src/commands/managed-agent/session-get.ts

@@ -0,0 +1,58 @@
+import { defineCommand, detectOutputFormat, type FlagsDef } from "bailian-cli-core";
+import { emitBare, emitResult } from "bailian-cli-runtime";
+import { getSession } from "@openagentpack/sdk";
+import { buildAgentRuntime, CREDENTIALS_NOTE } from "./_engine/config-loader.ts";
+import { withStdoutProtected } from "./_engine/console-capture.ts";
+import { withAgentErrors } from "./_engine/errors.ts";
+
+const SESSION_GET_FLAGS = {
+  sessionId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Session ID (required)",
+    required: true,
+  },
+  file: {
+    type: "string",
+    valueHint: "<path>",
+    description: "Config file path (default: agents.yaml)",
+  },
+  provider: {
+    type: "string",
+    valueHint: "<name>",
+    description: "Target provider",
+  },
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Get details of a session",
+  auth: "apiKey",
+  usageArgs: "--session-id <id> [--provider <name>] [--file <path>]",
+  flags: SESSION_GET_FLAGS,
+  exampleArgs: ["--session-id sess_abc123"],
+  notes: CREDENTIALS_NOTE,
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const format = detectOutputFormat(settings.output);
+    const file = flags.file ?? "agents.yaml";
+
+    const session = await withAgentErrors(() =>
+      withStdoutProtected(async () => {
+        const runtime = await buildAgentRuntime(ctx, file);
+        return getSession(runtime, flags.sessionId, flags.provider);
+      }),
+    );
+
+    if (format === "json") {
+      emitResult(session, format);
+      return;
+    }
+    emitBare(`  ID:          ${session.id}`);
+    emitBare(`  Agent:       ${session.agent_id}`);
+    emitBare(`  Environment: ${session.environment_id}`);
+    emitBare(`  Status:      ${session.status}`);
+    if (session.title) emitBare(`  Title:       ${session.title}`);
+    emitBare(`  Created:     ${session.created_at}`);
+    emitBare(`  Updated:     ${session.updated_at}`);
+  },
+});

packages/commands/src/commands/managed-agent/session-list.ts

@@ -0,0 +1,88 @@
+import { defineCommand, detectOutputFormat, type FlagsDef } from "bailian-cli-core";
+import { emitBare, emitResult, formatTable } from "bailian-cli-runtime";
+import { listSessionSummaries } from "@openagentpack/sdk";
+import { buildAgentRuntime, CREDENTIALS_NOTE } from "./_engine/config-loader.ts";
+import { withStdoutProtected } from "./_engine/console-capture.ts";
+import { withAgentErrors } from "./_engine/errors.ts";
+import { fetchAllPages } from "./_engine/pagination.ts";
+
+const SESSION_LIST_FLAGS = {
+  file: {
+    type: "string",
+    valueHint: "<path>",
+    description: "Config file path (default: agents.yaml)",
+  },
+  agent: {
+    type: "string",
+    valueHint: "<name>",
+    description: "Filter by agent name",
+  },
+  all: {
+    type: "switch",
+    description: "Fetch all pages by following the cursor",
+  },
+  provider: {
+    type: "string",
+    valueHint: "<name>",
+    description: "Target provider",
+  },
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "List sessions from the provider",
+  auth: "apiKey",
+  usageArgs: "[--agent <name>] [--all] [--provider <name>] [--file <path>]",
+  flags: SESSION_LIST_FLAGS,
+  exampleArgs: ["", "--agent assistant", "--all"],
+  notes: CREDENTIALS_NOTE,
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const format = detectOutputFormat(settings.output);
+    const file = flags.file ?? "agents.yaml";
+
+    const { items: summaries, hasMore } = await withAgentErrors(() =>
+      withStdoutProtected(async () => {
+        const runtime = await buildAgentRuntime(ctx, file);
+        return fetchAllPages(async (page) => {
+          const result = await listSessionSummaries(runtime, {
+            agent: flags.agent,
+            provider: flags.provider,
+            filter: page ? { page } : undefined,
+          });
+          return {
+            items: result.summaries,
+            hasMore: result.hasMore,
+            nextPage: result.nextPage,
+          };
+        }, flags.all);
+      }),
+    );
+
+    const sessions = summaries.map((summary) => summary.session);
+    if (format === "json") {
+      emitResult({ sessions, has_more: hasMore }, format);
+      return;
+    }
+    if (sessions.length === 0) {
+      emitBare("No sessions found.");
+      return;
+    }
+
+    const agentNames = new Map(
+      summaries
+        .filter((summary) => summary.agentName)
+        .map((summary) => [summary.session.id, summary.agentName!]),
+    );
+    const headers = ["ID", "TITLE", "AGENT", "STATUS", "CREATED"];
+    const rows = sessions.map((session) => [
+      session.id,
+      (session.title ?? "").slice(0, 20),
+      agentNames.get(session.id) ?? session.agent_id.slice(0, 12),
+      session.status,
+      session.created_at,
+    ]);
+    for (const line of formatTable(headers, rows)) emitBare(line);
+    emitBare(`\nTotal: ${sessions.length}`);
+    if (hasMore) emitBare("More sessions available. Use --all to fetch all.");
+  },
+});

packages/commands/src/commands/managed-agent/session-run.ts

@@ -0,0 +1,125 @@
+import { defineCommand, detectOutputFormat, type FlagsDef } from "bailian-cli-core";
+import { emitResult } from "bailian-cli-runtime";
+import { startSessionRun, startSessionRunPolling } from "@openagentpack/sdk";
+import { buildAgentRuntime, CREDENTIALS_NOTE } from "./_engine/config-loader.ts";
+import { withStdoutProtected } from "./_engine/console-capture.ts";
+import { withAgentErrors } from "./_engine/errors.ts";
+import {
+  parseMemoryStores,
+  renderCollectedEvents,
+  streamAndRenderEvents,
+} from "./_engine/session-render.ts";
+
+const SESSION_RUN_FLAGS = {
+  prompt: {
+    type: "string",
+    valueHint: "<text>",
+    description: "Prompt to send (required)",
+    required: true,
+  },
+  file: {
+    type: "string",
+    valueHint: "<path>",
+    description: "Config file path (default: agents.yaml)",
+  },
+  agent: {
+    type: "string",
+    valueHint: "<name>",
+    description: "Agent name (auto-detected when only one agent is configured)",
+  },
+  environment: {
+    type: "string",
+    valueHint: "<name>",
+    description: "Override agent's declared environment",
+  },
+  vault: {
+    type: "string",
+    valueHint: "<name>",
+    description: "Override agent's declared vault",
+  },
+  memoryStores: {
+    type: "string",
+    valueHint: "<names>",
+    description: "Override agent's memory stores (comma-separated)",
+  },
+  title: { type: "string", valueHint: "<title>", description: "Session title" },
+  provider: {
+    type: "string",
+    valueHint: "<name>",
+    description: "Target provider",
+  },
+  noStream: {
+    type: "switch",
+    description: "Use polling instead of SSE streaming",
+  },
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Create a session, send a message, and stream the response",
+  auth: "apiKey",
+  usageArgs: "--prompt <text> [--agent <name>] [--no-stream] [--file <path>]",
+  flags: SESSION_RUN_FLAGS,
+  exampleArgs: ['--prompt "hello"', '--agent assistant --prompt "summarize this repo"'],
+  notes: [
+    ...CREDENTIALS_NOTE,
+    "--output json emits one envelope: { session_id, provider, agent, events } — read session_id to chain `session send/get/events/delete`.",
+  ],
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const format = detectOutputFormat(settings.output);
+    const file = flags.file ?? "agents.yaml";
+    const asJson = format === "json";
+
+    const runOptions = {
+      agent: flags.agent,
+      provider: flags.provider,
+      environment: flags.environment,
+      vault: flags.vault,
+      memoryStores: parseMemoryStores(flags.memoryStores),
+      title: flags.title,
+    };
+
+    if (settings.dryRun) {
+      emitResult(
+        {
+          would_run: {
+            prompt: flags.prompt,
+            agent: flags.agent ?? "auto",
+            provider: flags.provider ?? "auto",
+            environment: flags.environment,
+            vault: flags.vault,
+            memory_stores: runOptions.memoryStores,
+            title: flags.title,
+            mode: flags.noStream ? "polling" : "streaming",
+          },
+          config_file: file,
+        },
+        format,
+      );
+      return;
+    }
+
+    await withAgentErrors(() =>
+      withStdoutProtected(async () => {
+        const runtime = await buildAgentRuntime(ctx, file);
+        if (flags.noStream) {
+          const run = await startSessionRunPolling(runtime, flags.prompt, runOptions);
+          if (!asJson) process.stderr.write(`Session created: ${run.session.id}\n`);
+          renderCollectedEvents(run, asJson, {
+            session_id: run.session.id,
+            provider: run.provider,
+            agent: run.agentName,
+          });
+        } else {
+          const run = await startSessionRun(runtime, flags.prompt, runOptions);
+          if (!asJson) process.stderr.write(`Session created: ${run.session.id}\n`);
+          await streamAndRenderEvents(run.events, asJson, {
+            session_id: run.session.id,
+            provider: run.provider,
+            agent: run.agentName,
+          });
+        }
+      }),
+    );
+  },
+});