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

feat(config-agent): align agent writers, add --key/--region, prepare 1.12.0
Merge branch 'main' of github.com:modelstudioai/cli into feat/config-agent-fix
2026-09-14 19:49:23 +08:00 · 2026-07-28 20:39:56 +08:00 · 2026-07-28 20:33:16 +08:00 · 2026-07-28 20:27:28 +08:00 · 2026-07-28 19:37:13 +08:00 · 2026-07-28 19:32:26 +08:00
143 changed files with 9457 additions and 1218 deletions
@@ -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

@@ -68,6 +68,7 @@ Skill / 命令手册随 `skills/bailian-cli/` 经 `npx skills add modelstudioai/
 | 鉴权扩展       | 加 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)               |
@@ -6,6 +6,88 @@ 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
@@ -6,6 +6,88 @@

 [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

 ### 新增
@@ -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

@@ -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

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

@@ -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?"

@@ -159,6 +166,15 @@ 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 (`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.
@@ -209,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
@@ -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）账号开放，国际站 / 全球站账号暂不支持。

@@ -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 "你好，介绍一下阿里云百炼平台"

@@ -157,6 +164,15 @@ 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）

 控制台能力命令（`model list`、`app list`、`usage summary/free/stats`、`workspace list`、`quota list/request/check/history`）需要使用此登录方式。打开浏览器跳转百炼控制台完成登录。
@@ -207,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                                                  |

 ## 更新日志
@@ -38,12 +38,12 @@ defineCommand({ auth }) → runtime/authStage → ctx.client → command.run(ctx
 - `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` / `security_token`
- `bl auth logout` 清 `api_key` + `access_token` + `access_key_*`
+- `bl auth logout` 清 `api_key` + `base_url` + `access_token` + `access_key_*`

 解析分工:

 - `resolveApiKey()` — `auth: "apiKey"` 命令;优先级 `--api-key` > `DASHSCOPE_API_KEY` > config `api_key`
- `resolveModelBaseUrl()` — model base URL;优先级 `--base-url` > `DASHSCOPE_BASE_URL` > config `base_url` > `REGIONS.cn`，返回前统一去除 query、fragment、尾斜杠和已知 SDK/API Base 后缀，同时保留自定义网关前缀
+- `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 不切换
@@ -53,6 +53,23 @@ defineCommand({ auth }) → runtime/authStage → ctx.client → command.run(ctx

 命令不要直接解析 token、env 或 config。业务请求统一走 `ctx.client`;登录/配置命令通过 `ctx.authStore` / `ctx.configStore` 的窄接口操作落盘。

+### 例外:agent 命令的分层鉴权与 SDK 凭证内存注入
+
+`bl managed-agent *` 按调用链分两层:
+
+- **离线命令** — `init`、`validate`、`state list/show/rm`:`auth: "none"`，只读写本地文件，无需登录;引擎侧传 `credentials: "none"` 跳过凭证断言
+- **联网命令** — `plan`、`apply`、`destroy`、`state import`、`skill-list`、全部 `session *`:统一声明 `auth: "apiKey"` 硬门禁 —— 无论目标 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 鉴权链为唯一信源。
+
 ## 必查清单

 ### A. core 层(类型 + 解析)
@@ -85,7 +85,8 @@ describe.skipIf(<ready>)("e2e: <topic>（DashScope …）", () => {

 ## 安全与例外

- **禁止真实破坏性操作**：`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 输出 → 更新对应断言
@@ -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`；只更新其中一侧不会自动证明发布成功
@@ -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 设置一致

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

@@ -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?"

@@ -159,6 +166,15 @@ 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 (`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.
@@ -209,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
@@ -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）账号开放，国际站 / 全球站账号暂不支持。

@@ -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 "你好，介绍一下阿里云百炼平台"

@@ -157,6 +164,15 @@ 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）

 控制台能力命令（`model list`、`app list`、`usage summary/free/stats`、`workspace list`、`quota list/request/check/history`）需要使用此登录方式。打开浏览器跳转百炼控制台完成登录。
@@ -207,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                                                  |

 ## 更新日志
@@ -1,6 +1,6 @@
 {
  "name": "bailian-cli",
-  "version": "1.9.0",
+  "version": "1.12.0",
  "description": "CLI for Aliyun Model Studio (DashScope) AI Platform.",
  "keywords": [
    "agent",
@@ -66,6 +66,6 @@
    "yaml": "catalog:"
  },
  "engines": {
-    "node": ">=22.12.0"
+    "node": ">=18.17.0"
  }
 }
@@ -19,6 +19,7 @@ import {
  configList,
  configUse,
  configUi,
+  configAgent,
  update,
  appCall,
  appList,
@@ -88,6 +89,23 @@ import {
  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.
@@ -115,6 +133,7 @@ export const commands: Record<string, AnyCommand> = {
  "config list": configList,
  "config use": configUse,
  "config ui": configUi,
+  "config agent": configAgent,
  update,
  "app call": appCall,
  "app list": appList,
@@ -184,4 +203,21 @@ export const commands: Record<string, AnyCommand> = {
  "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,
 };
@@ -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([]);
+    }
+  });
+});
@@ -1,6 +1,6 @@
 {
  "name": "bailian-cli-commands",
-  "version": "1.9.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,10 +40,12 @@
    "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": {
@@ -54,6 +56,6 @@
    "vite-plus": "0.1.22"
  },
  "engines": {
-    "node": ">=22.12.0"
+    "node": ">=18.17.0"
  }
 }
@@ -20,6 +20,9 @@ interface ApiKeyLoginProfile {
  baseUrl: string;
  persistBaseUrl?: string;
  defaultTextModel?: string;
+  defaultVideoModel?: string;
+  defaultImageToVideoModel?: string;
+  defaultReferenceToVideoModel?: string;
  defaultImageModel?: string;
  persistPatch?: AuthPersistPatch;
 }
@@ -54,17 +57,17 @@ export async function validateAndPersistApiKey(
  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: profile.defaultTextModel || "qwen3.7-max",
+      model: validationModel,
      messages: [{ role: "user", content: "hi" }],
      max_tokens: 1,
      stream: false,
-      enable_thinking: false,
    },
  };

@@ -88,6 +91,9 @@ export async function validateAndPersistApiKey(
    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,
  });
 }
@@ -21,7 +21,11 @@ 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: "Model API key to store" },
+    apiKey: {
+      type: "string",
+      valueHint: "<key>",
+      description: "Model API key to store",
+    },
    baseUrl: {
      type: "string",
      valueHint: "<url>",
@@ -150,6 +154,9 @@ export default defineCommand({
      baseUrl: resolvedBaseUrl,
      persistBaseUrl,
      defaultTextModel: profilePreset?.defaultTextModel,
+      defaultVideoModel: profilePreset?.defaultVideoModel,
+      defaultImageToVideoModel: profilePreset?.defaultImageToVideoModel,
+      defaultReferenceToVideoModel: profilePreset?.defaultReferenceToVideoModel,
      defaultImageModel: profilePreset?.defaultImageModel,
    });
  },
@@ -2,7 +2,7 @@ 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: {
@@ -68,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 / security_token from ${store.path}`,
+          `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 / security_token from ${store.path}\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");
    }
  },
 });
@@ -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;
+}
@@ -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`);
+      }
+    }
+  },
+});
@@ -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[]];
@@ -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;
@@ -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;
@@ -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;
@@ -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;
@@ -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;
@@ -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;
@@ -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`;
+}
@@ -14,7 +14,12 @@ export default defineCommand({
        "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",
@@ -44,7 +49,9 @@ export default defineCommand({
      return;
    }

-    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;
@@ -13,6 +13,8 @@ export const VALID_KEYS = [
  "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",
@@ -41,6 +43,8 @@ export const KEY_ALIASES: Record<string, string> = {
  "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",
@@ -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`) }];
@@ -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`) }];
@@ -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})`;
+}
@@ -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}.`,
+  );
+}
@@ -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;
+  }
+}
@@ -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}'.`,
+    );
+  }
+}
@@ -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;
+  }
+}
@@ -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`);
+}
@@ -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);
+}
@@ -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 };
+}
@@ -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;
+}
@@ -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;
+}
@@ -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);
+  },
+});
@@ -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,
+      );
+    }
+  },
+});
@@ -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`.");
+    }
+  },
+});
@@ -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.");
+  },
+});
@@ -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(", ")}`);
+    }
+  },
+});
@@ -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.`);
+  },
+});
@@ -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.");
+  },
+});
@@ -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}`);
+  },
+});
@@ -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.");
+  },
+});
@@ -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,
+          });
+        }
+      }),
+    );
+  },
+});
@@ -0,0 +1,93 @@
+import { defineCommand, detectOutputFormat, type FlagsDef } from "bailian-cli-core";
+import { emitResult } from "bailian-cli-runtime";
+import { sendSessionMessagePolling, sendSessionMessageStreaming } 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 { renderCollectedEvents, streamAndRenderEvents } from "./_engine/session-render.ts";
+
+const SESSION_SEND_FLAGS = {
+  sessionId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Session ID (required)",
+    required: true,
+  },
+  message: {
+    type: "string",
+    valueHint: "<text>",
+    description: "Message to send (required)",
+    required: true,
+  },
+  file: {
+    type: "string",
+    valueHint: "<path>",
+    description: "Config file path (default: agents.yaml)",
+  },
+  provider: {
+    type: "string",
+    valueHint: "<name>",
+    description: "Target provider",
+  },
+  noStream: {
+    type: "switch",
+    description: "Use polling instead of SSE streaming",
+  },
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Send a message to an existing session and stream the response",
+  auth: "apiKey",
+  usageArgs: "--session-id <id> --message <text> [--no-stream] [--file <path>]",
+  flags: SESSION_SEND_FLAGS,
+  exampleArgs: ['--session-id sess_abc123 --message "continue"'],
+  notes: CREDENTIALS_NOTE,
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const format = detectOutputFormat(settings.output);
+    const file = flags.file ?? "agents.yaml";
+    const asJson = format === "json";
+
+    if (settings.dryRun) {
+      emitResult(
+        {
+          would_send: {
+            session_id: flags.sessionId,
+            message: flags.message,
+            provider: flags.provider ?? "auto",
+            mode: flags.noStream ? "polling" : "streaming",
+          },
+          config_file: file,
+        },
+        format,
+      );
+      return;
+    }
+
+    await withAgentErrors(() =>
+      withStdoutProtected(async () => {
+        const runtime = await buildAgentRuntime(ctx, file);
+        if (flags.noStream) {
+          const result = await sendSessionMessagePolling(runtime, flags.sessionId, flags.message, {
+            provider: flags.provider,
+          });
+          renderCollectedEvents(result, asJson, {
+            session_id: flags.sessionId,
+          });
+        } else {
+          const events = await sendSessionMessageStreaming(
+            runtime,
+            flags.sessionId,
+            flags.message,
+            {
+              provider: flags.provider,
+            },
+          );
+          await streamAndRenderEvents(events, asJson, {
+            session_id: flags.sessionId,
+          });
+        }
+      }),
+    );
+  },
+});
@@ -0,0 +1,93 @@
+import { defineCommand, detectOutputFormat, type FlagsDef } from "bailian-cli-core";
+import { emitBare, emitResult, formatTable } from "bailian-cli-runtime";
+import { listSkills } 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 SKILL_SOURCES = ["custom", "official", "all"] as const;
+type SkillSource = (typeof SKILL_SOURCES)[number];
+
+const SKILL_LIST_FLAGS = {
+  file: {
+    type: "string",
+    valueHint: "<path>",
+    description: "Config file path (default: agents.yaml)",
+  },
+  source: {
+    type: "string",
+    valueHint: "<source>",
+    description:
+      "Skill catalog: custom (workspace-uploaded, default), official (built-in), or all (both catalogs in one call)",
+  },
+  provider: {
+    type: "string",
+    valueHint: "<name>",
+    description: "Target provider",
+  },
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "List skills from the provider's skill catalog",
+  auth: "apiKey",
+  usageArgs: "[--source custom|official|all] [--provider <name>] [--file <path>]",
+  flags: SKILL_LIST_FLAGS,
+  exampleArgs: [
+    "",
+    "--source official",
+    "--source all --output json",
+    "--source custom --provider bailian",
+  ],
+  notes: [
+    ...CREDENTIALS_NOTE,
+    "Providers without a skill listing API (e.g. ark) return an empty list.",
+    "For agent-driven skill selection, use `--source all --output json`: one call returns both catalogs with per-skill `source` and `description` fields to pick from.",
+    "When generating a task that needs a suitable skill, call this command to match official or custom skills before wiring them into the task.",
+  ],
+  validate: (f) =>
+    f.source && !SKILL_SOURCES.includes(f.source as SkillSource)
+      ? "--source must be one of: custom, official, all."
+      : undefined,
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const format = detectOutputFormat(settings.output);
+    const file = flags.file ?? "agents.yaml";
+    const source = (flags.source as SkillSource | undefined) ?? "custom";
+
+    const skills = await withAgentErrors(() =>
+      withStdoutProtected(async () => {
+        const runtime = await buildAgentRuntime(ctx, file);
+        if (source !== "all") {
+          return listSkills(runtime, { provider: flags.provider, source });
+        }
+        // Both catalogs in one call; each entry carries its own `source` field.
+        const [customSkills, officialSkills] = await Promise.all([
+          listSkills(runtime, { provider: flags.provider, source: "custom" }),
+          listSkills(runtime, { provider: flags.provider, source: "official" }),
+        ]);
+        return [...customSkills, ...officialSkills];
+      }),
+    );
+
+    if (format === "json") {
+      emitResult({ source, skills }, format);
+      return;
+    }
+    if (skills.length === 0) {
+      emitBare(source === "all" ? "No skills found." : `No ${source} skills found.`);
+      return;
+    }
+
+    const headers = ["ID", "NAME", "SOURCE", "STATUS", "VERSION", "CREATED"];
+    const rows = skills.map((skill) => [
+      skill.id,
+      skill.name.slice(0, 32),
+      skill.source,
+      skill.status,
+      skill.latest_version ?? "-",
+      skill.created_at ?? "-",
+    ]);
+    for (const line of formatTable(headers, rows)) emitBare(line);
+    emitBare(`\nTotal: ${skills.length} (${source})`);
+  },
+});
@@ -0,0 +1,82 @@
+import { defineCommand, detectOutputFormat, type FlagsDef } from "bailian-cli-core";
+import { emitBare, emitResult } from "bailian-cli-runtime";
+import { importResource, parseStateAddress } 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 STATE_IMPORT_FLAGS = {
+  address: {
+    type: "string",
+    valueHint: "<provider.type.name>",
+    description: "Resource state address (required)",
+    required: true,
+  },
+  remoteId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Existing remote resource ID to import (required)",
+    required: true,
+  },
+  resourceVersion: {
+    type: "number",
+    valueHint: "<n>",
+    description: "Resource version (for versioned resources like agents)",
+  },
+  file: {
+    type: "string",
+    valueHint: "<path>",
+    description: "Config file path (default: agents.yaml)",
+  },
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Import an existing remote resource into agents state",
+  auth: "apiKey",
+  usageArgs:
+    "--address <provider.type.name> --remote-id <id> [--resource-version <n>] [--file <path>]",
+  flags: STATE_IMPORT_FLAGS,
+  exampleArgs: ["--address bailian.agent.assistant --remote-id agent-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) {
+      // Validate the address shape locally so dry-run still catches usage errors.
+      await withAgentErrors(async () => {
+        parseStateAddress(flags.address, { requireProvider: true });
+      });
+      emitResult(
+        {
+          would_import: flags.address,
+          remote_id: flags.remoteId,
+          resource_version: flags.resourceVersion,
+          config_file: file,
+        },
+        format,
+      );
+      return;
+    }
+
+    await withAgentErrors(() =>
+      withStdoutProtected(async () => {
+        // Parse first so a malformed address fails fast, before any config I/O.
+        const parsed = parseStateAddress(flags.address, {
+          requireProvider: true,
+        });
+        const runtime = await buildAgentRuntime(ctx, file);
+        await importResource(runtime, parsed, flags.remoteId, {
+          resourceVersion: flags.resourceVersion,
+        });
+      }),
+    );
+
+    if (format === "json") {
+      emitResult({ imported: flags.address, remote_id: flags.remoteId }, format);
+    } else {
+      emitBare(`Imported ${flags.address} (remote_id: ${flags.remoteId}) into state.`);
+    }
+  },
+});
@@ -0,0 +1,55 @@
+import { defineCommand, detectOutputFormat, type FlagsDef } from "bailian-cli-core";
+import { emitBare, emitResult, formatTable } from "bailian-cli-runtime";
+import { buildAgentRuntime, OFFLINE_NOTE } from "./_engine/config-loader.ts";
+import { withStdoutProtected } from "./_engine/console-capture.ts";
+import { withAgentErrors } from "./_engine/errors.ts";
+
+const STATE_LIST_FLAGS = {
+  file: {
+    type: "string",
+    valueHint: "<path>",
+    description: "Config file path (default: agents.yaml)",
+  },
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "List resources tracked in agents state",
+  auth: "none",
+  usageArgs: "[--file <path>]",
+  flags: STATE_LIST_FLAGS,
+  exampleArgs: ["", "--file agents.yaml"],
+  notes: OFFLINE_NOTE,
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const format = detectOutputFormat(settings.output);
+    const file = flags.file ?? "agents.yaml";
+
+    const resources = await withAgentErrors(() =>
+      withStdoutProtected(async () => {
+        const runtime = await buildAgentRuntime(ctx, file, {
+          credentials: "none",
+        });
+        return runtime.state.listResources();
+      }),
+    );
+
+    if (format === "json") {
+      emitResult({ resources }, format);
+      return;
+    }
+    if (resources.length === 0) {
+      emitBare("No resources tracked in state.");
+      return;
+    }
+
+    const headers = ["TYPE", "NAME", "PROVIDER", "REMOTE ID"];
+    const rows = resources.map((resource) => [
+      resource.address.type,
+      resource.address.name,
+      resource.address.provider,
+      resource.remote_id ?? "(local)",
+    ]);
+    for (const line of formatTable(headers, rows)) emitBare(line);
+    emitBare(`\nTotal: ${resources.length}`);
+  },
+});
@@ -0,0 +1,70 @@
+import {
+  BailianError,
+  defineCommand,
+  detectOutputFormat,
+  ExitCode,
+  type FlagsDef,
+} from "bailian-cli-core";
+import { emitBare, emitResult } from "bailian-cli-runtime";
+import { parseStateAddress } from "@openagentpack/sdk";
+import { buildAgentRuntime, OFFLINE_NOTE } from "./_engine/config-loader.ts";
+import { withStdoutProtected } from "./_engine/console-capture.ts";
+import { withAgentErrors } from "./_engine/errors.ts";
+
+const STATE_RM_FLAGS = {
+  address: {
+    type: "string",
+    valueHint: "<provider.type.name>",
+    description: "Resource state address (required)",
+    required: true,
+  },
+  file: {
+    type: "string",
+    valueHint: "<path>",
+    description: "Config file path (default: agents.yaml)",
+  },
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Remove a resource from state without destroying it remotely",
+  auth: "none",
+  usageArgs: "--address <provider.type.name> [--file <path>]",
+  flags: STATE_RM_FLAGS,
+  exampleArgs: ["--address bailian.agent.assistant"],
+  notes: OFFLINE_NOTE,
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const format = detectOutputFormat(settings.output);
+    const file = flags.file ?? "agents.yaml";
+
+    if (settings.dryRun) {
+      // Validate the address shape locally so dry-run still catches usage errors.
+      await withAgentErrors(async () => {
+        parseStateAddress(flags.address, { requireProvider: false });
+      });
+      emitResult({ would_remove: flags.address, config_file: file }, format);
+      return;
+    }
+
+    await withAgentErrors(() =>
+      withStdoutProtected(async () => {
+        const runtime = await buildAgentRuntime(ctx, file, {
+          credentials: "none",
+        });
+        const parsed = parseStateAddress(flags.address, {
+          requireProvider: false,
+        });
+        const found = runtime.state.findResource(parsed);
+        if (!found) {
+          throw new BailianError(`Resource not found: ${flags.address}`, ExitCode.GENERAL);
+        }
+        runtime.state.removeResource(found.address);
+        await runtime.state.save();
+      }),
+    );
+
+    const message = `Removed ${flags.address} from state (remote resource not deleted).`;
+    if (format === "json") emitResult({ removed: flags.address }, format);
+    else emitBare(message);
+  },
+});
@@ -0,0 +1,59 @@
+import {
+  BailianError,
+  defineCommand,
+  detectOutputFormat,
+  ExitCode,
+  type FlagsDef,
+} from "bailian-cli-core";
+import { emitBare, emitResult } from "bailian-cli-runtime";
+import { parseStateAddress } from "@openagentpack/sdk";
+import { buildAgentRuntime, OFFLINE_NOTE } from "./_engine/config-loader.ts";
+import { withStdoutProtected } from "./_engine/console-capture.ts";
+import { withAgentErrors } from "./_engine/errors.ts";
+
+const STATE_SHOW_FLAGS = {
+  address: {
+    type: "string",
+    valueHint: "<provider.type.name>",
+    description: "Resource state address (required)",
+    required: true,
+  },
+  file: {
+    type: "string",
+    valueHint: "<path>",
+    description: "Config file path (default: agents.yaml)",
+  },
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Show details of a resource in agents state",
+  auth: "none",
+  usageArgs: "--address <provider.type.name> [--file <path>]",
+  flags: STATE_SHOW_FLAGS,
+  exampleArgs: ["--address bailian.agent.assistant"],
+  notes: OFFLINE_NOTE,
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const format = detectOutputFormat(settings.output);
+    const file = flags.file ?? "agents.yaml";
+
+    const found = await withAgentErrors(() =>
+      withStdoutProtected(async () => {
+        const runtime = await buildAgentRuntime(ctx, file, {
+          credentials: "none",
+        });
+        const parsed = parseStateAddress(flags.address, {
+          requireProvider: false,
+        });
+        return runtime.state.findResource(parsed);
+      }),
+    );
+
+    if (!found) {
+      throw new BailianError(`Resource not found: ${flags.address}`, ExitCode.GENERAL);
+    }
+
+    if (format === "json") emitResult(found, format);
+    else emitBare(JSON.stringify(found, null, 2));
+  },
+});
@@ -0,0 +1,56 @@
+import {
+  BailianError,
+  defineCommand,
+  detectOutputFormat,
+  ExitCode,
+  type FlagsDef,
+} from "bailian-cli-core";
+import { emitBare, emitResult } from "bailian-cli-runtime";
+import { validateProjectConfig } from "@openagentpack/sdk";
+import { OFFLINE_NOTE, resolveAgentProjectConfig } from "./_engine/config-loader.ts";
+import { withAgentErrors } from "./_engine/errors.ts";
+
+const VALIDATE_FLAGS = {
+  file: {
+    type: "string",
+    valueHint: "<path>",
+    description: "Config file path (default: agents.yaml)",
+  },
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Validate an agents.yaml configuration (offline)",
+  auth: "none",
+  usageArgs: "[--file <path>]",
+  flags: VALIDATE_FLAGS,
+  exampleArgs: ["", "--file agents.yaml"],
+  notes: OFFLINE_NOTE,
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const format = detectOutputFormat(settings.output);
+    const file = flags.file ?? "agents.yaml";
+
+    const diagnostics = await withAgentErrors(async () => {
+      const { config } = await resolveAgentProjectConfig(ctx, file, {
+        credentials: "none",
+      });
+      return validateProjectConfig(config);
+    });
+
+    const errorCount = diagnostics.filter((diag) => diag.severity === "error").length;
+
+    if (format === "json") {
+      emitResult({ valid: errorCount === 0, diagnostics }, format);
+    } else {
+      for (const diag of diagnostics) {
+        const where = diag.resource ? ` (${diag.resource.type}.${diag.resource.name})` : "";
+        emitBare(`[${diag.severity}] ${diag.message}${where}`);
+      }
+      if (errorCount === 0) emitBare("Configuration is valid.");
+    }
+
+    if (errorCount > 0) {
+      throw new BailianError(`Validation failed with ${errorCount} error(s).`, ExitCode.GENERAL);
+    }
+  },
+});
@@ -0,0 +1,39 @@
+import { BailianError } from "bailian-cli-core";
+import { mcpMarketplaceDetailPage } from "bailian-cli-runtime";
+
+/** Detect MCP-not-activated / invalid 404 errors (CLI-wrapped server message). */
+export function isMcpNotActivated(error: unknown): boolean {
+  if (!(error instanceof BailianError)) return false;
+  const message = error.message;
+  if (!/MCP request failed:\s*404\b/i.test(message)) return false;
+  return /未开通|MCP不存在|MCP_IS_INVALID/i.test(message);
+}
+
+/** Activation hint; URL from runtime/urls.ts. */
+export function mcpActivateHint(serverCode: string): string {
+  const lines = [
+    `Activate (or re-activate) the ${serverCode} MCP in the Bailian MCP marketplace, then retry.`,
+  ];
+  if (serverCode === "WebSearch") {
+    lines.push(
+      "If it was previously on SSE, cancel and activate again to upgrade to Streamable HTTP.",
+    );
+  }
+  lines.push(`Open: ${mcpMarketplaceDetailPage(serverCode)}`);
+  return lines.join("\n");
+}
+
+/**
+ * For not-activated errors, keep the original message / exitCode and append a hint only.
+ * Do not replace the server error message.
+ */
+export function rethrowWithMcpActivateHint(error: unknown, serverCode: string): never {
+  if (isMcpNotActivated(error) && error instanceof BailianError && !error.hint) {
+    throw new BailianError(error.message, error.exitCode, mcpActivateHint(serverCode), {
+      cause: error,
+      api: error.api,
+      rawResponse: error.rawResponse,
+    });
+  }
+  throw error;
+}
@@ -8,6 +8,7 @@ import {
  type ParsedFlags,
 } from "bailian-cli-core";
 import { emitResult } from "bailian-cli-runtime";
+import { rethrowWithMcpActivateHint } from "./activate-hint.ts";

 const CALL_FLAGS = {
  target: {
@@ -130,14 +131,21 @@ export default defineCommand({
    }

    const client = ctx.client.mcp(url);
-    await client.initialize();
-    const result = await client.callTool(toolName, toolArgs);
+    try {
+      await client.initialize();
+      const result = await client.callTool(toolName, toolArgs);

-    if (result.isError) {
-      const errText = result.content.map((c) => c.text || "").join("\n");
-      throw new BailianError(`Tool error: ${errText}`);
+      if (result.isError) {
+        const errText = result.content.map((c) => c.text || "").join("\n");
+        throw new BailianError(`Tool error: ${errText}`);
+      }
+
+      emitResult(result, format);
+    } catch (error) {
+      if (!flags.url) {
+        rethrowWithMcpActivateHint(error, serverCode);
+      }
+      throw error;
    }
-
-    emitResult(result, format);
  },
 });
@@ -1,5 +1,6 @@
 import { defineCommand, bailianMcpPath, detectOutputFormat } from "bailian-cli-core";
 import { emitResult } from "bailian-cli-runtime";
+import { rethrowWithMcpActivateHint } from "./activate-hint.ts";

 export default defineCommand({
  description: "List tools exposed by an MCP server (tools/list)",
@@ -36,8 +37,15 @@ export default defineCommand({
    }

    const client = ctx.client.mcp(url);
-    await client.initialize();
-    const tools = await client.listTools();
-    emitResult({ server: code, url, tools }, format);
+    try {
+      await client.initialize();
+      const tools = await client.listTools();
+      emitResult({ server: code, url, tools }, format);
+    } catch (error) {
+      if (!flags.url) {
+        rethrowWithMcpActivateHint(error, code);
+      }
+      throw error;
+    }
  },
 });
@@ -0,0 +1,18 @@
+import {
+  isMcpNotActivated,
+  mcpActivateHint,
+  rethrowWithMcpActivateHint,
+} from "../mcp/activate-hint.ts";
+
+/** Detect WebSearch MCP not-activated / invalid 404 errors. */
+export const isWebSearchMcpNotActivated = isMcpNotActivated;
+
+/** WebSearch activation hint. */
+export function webSearchActivateHint(): string {
+  return mcpActivateHint("WebSearch");
+}
+
+/** Keep the original message; append a hint for WebSearch not-activated errors. */
+export function rethrowWithWebSearchActivateHint(error: unknown): never {
+  rethrowWithMcpActivateHint(error, "WebSearch");
+}
@@ -5,8 +5,8 @@ import {
  mcpWebSearchPath,
  type FlagsDef,
 } from "bailian-cli-core";
-import { createSpinner } from "bailian-cli-runtime";
-import { emitResult } from "bailian-cli-runtime";
+import { createSpinner, emitResult } from "bailian-cli-runtime";
+import { rethrowWithWebSearchActivateHint } from "./web-activate-hint.ts";

 const WEB_SEARCH_FLAGS = {
  query: { type: "string", valueHint: "<text>", description: "Search query text" },
@@ -41,11 +41,14 @@ export default defineCommand({
        return;
      }

-      const client = ctx.client.mcp(mcpWebSearchPath());
-      await client.initialize();
-      const tools = await client.listTools();
-
-      emitResult({ tools }, format);
+      try {
+        const client = ctx.client.mcp(mcpWebSearchPath());
+        await client.initialize();
+        const tools = await client.listTools();
+        emitResult({ tools }, format);
+      } catch (error) {
+        rethrowWithWebSearchActivateHint(error);
+      }
      return;
    }

@@ -123,7 +126,7 @@ export default defineCommand({
      }
    } catch (error) {
      spinner.stop("Failed.");
-      throw error;
+      rethrowWithWebSearchActivateHint(error);
    }
  },
 });
@@ -149,11 +149,6 @@ export default defineCommand({
      if (flags.thinkingBudget !== undefined) {
        body.thinking_budget = flags.thinkingBudget;
      }
-    } else if (!shouldStream) {
-      // DashScope qwen3 models default to enable_thinking=true server-side, but
-      // non-streaming calls require it to be explicitly false. Stream calls
-      // support thinking, so leave the field unset there (server handles it).
-      body.enable_thinking = false;
    }

    if (flags.tool) {
@@ -13,6 +13,7 @@ import {
  resolveWatermark,
  ASYNC_FLAG,
  CONCURRENT_FLAG,
+  redactDataUri,
 } from "bailian-cli-core";
 import { poll } from "bailian-cli-runtime";
 import { downloadFile, formatBytes } from "bailian-cli-runtime";
@@ -103,8 +104,9 @@ export default defineCommand({

    const model =
      flags.model ||
-      settings.defaultVideoModel ||
-      (flags.image ? "happyhorse-1.1-i2v" : "happyhorse-1.1-t2v");
+      (flags.image
+        ? settings.defaultImageToVideoModel || "happyhorse-1.1-i2v"
+        : settings.defaultVideoModel || "happyhorse-1.1-t2v");
    const format = detectOutputFormat(settings.output);

    const imageUrl = flags.image;
@@ -112,7 +114,7 @@ export default defineCommand({
    // Auto-upload local image file for i2v
    let resolvedImageUrl: string | undefined;
    if (imageUrl) {
-      resolvedImageUrl = await ctx.client.uploadFile(imageUrl, model);
+      resolvedImageUrl = await ctx.client.resolveImageInput(imageUrl, model);
    }

    const watermark = resolveWatermark(flags.watermark);
@@ -139,7 +141,16 @@ export default defineCommand({
    };

    if (settings.dryRun) {
-      emitResult({ request: body }, format);
+      const previewBody = resolvedImageUrl
+        ? {
+            ...body,
+            input: {
+              ...body.input,
+              media: [{ type: "first_frame" as const, url: redactDataUri(resolvedImageUrl) }],
+            },
+          }
+        : body;
+      emitResult({ request: previewBody }, format);
      return;
    }

@@ -13,6 +13,7 @@ import {
  resolveWatermark,
  ASYNC_FLAG,
  CONCURRENT_FLAG,
+  redactDataUri,
 } from "bailian-cli-core";
 import { poll } from "bailian-cli-runtime";
 import { downloadFile, formatBytes } from "bailian-cli-runtime";
@@ -117,23 +118,23 @@ export default defineCommand({
    const imageVoices = flags.imageVoice || [];
    const videoVoices = flags.videoVoice || [];

-    const model = flags.model || "happyhorse-1.1-r2v";
+    const model = flags.model || settings.defaultReferenceToVideoModel || "happyhorse-1.1-r2v";
    const format = detectOutputFormat(settings.output);

    // --- Resolve file URLs (auto-upload local files) ---
    const media: DashScopeVideoRefRequest["input"]["media"] = [];

    // Add reference images
-    for (let i = 0; i < images.length; i++) {
-      const resolved = await ctx.client.uploadFile(images[i]!, model);
+    for (let imageIndex = 0; imageIndex < images.length; imageIndex++) {
+      const resolved = await ctx.client.resolveImageInput(images[imageIndex]!, model);
      const entry: DashScopeVideoRefRequest["input"]["media"][number] = {
        type: "reference_image",
        url: resolved,
      };

      // Pair voice by position
-      if (imageVoices[i]) {
-        const resolvedVoice = await ctx.client.uploadFile(imageVoices[i]!, model);
+      if (imageVoices[imageIndex]) {
+        const resolvedVoice = await ctx.client.uploadFile(imageVoices[imageIndex]!, model);
        entry.reference_voice = resolvedVoice;
      }

@@ -141,16 +142,16 @@ export default defineCommand({
    }

    // Add reference videos
-    for (let i = 0; i < refVideos.length; i++) {
-      const resolved = await ctx.client.uploadFile(refVideos[i]!, model);
+    for (let videoIndex = 0; videoIndex < refVideos.length; videoIndex++) {
+      const resolved = await ctx.client.uploadFile(refVideos[videoIndex]!, model);
      const entry: DashScopeVideoRefRequest["input"]["media"][number] = {
        type: "reference_video",
        url: resolved,
      };

      // Pair voice by position
-      if (videoVoices[i]) {
-        const resolvedVoice = await ctx.client.uploadFile(videoVoices[i]!, model);
+      if (videoVoices[videoIndex]) {
+        const resolvedVoice = await ctx.client.uploadFile(videoVoices[videoIndex]!, model);
        entry.reference_voice = resolvedVoice;
      }

@@ -178,7 +179,18 @@ export default defineCommand({
    };

    if (settings.dryRun) {
-      emitResult({ request: body }, format);
+      const previewBody = {
+        ...body,
+        input: {
+          ...body.input,
+          media: body.input.media.map((item) => ({
+            ...item,
+            url: redactDataUri(item.url),
+            reference_voice: item.reference_voice ? redactDataUri(item.reference_voice) : undefined,
+          })),
+        },
+      };
+      emitResult({ request: previewBody }, format);
      return;
    }

@@ -233,11 +245,11 @@ export default defineCommand({
    );

    const videos: Array<{ taskId: string; videoUrl: string }> = [];
-    for (let i = 0; i < results.length; i++) {
-      const result = results[i]!;
+    for (let resultIndex = 0; resultIndex < results.length; resultIndex++) {
+      const result = results[resultIndex]!;
      const videoUrl =
        result.output.video_url || (result.output.results && result.output.results[0]?.url);
-      if (videoUrl) videos.push({ taskId: taskIds[i]!, videoUrl });
+      if (videoUrl) videos.push({ taskId: taskIds[resultIndex]!, videoUrl });
    }

    if (videos.length === 0) {
@@ -8,18 +8,13 @@ import {
  BailianError,
  ExitCode,
  isLocalFile,
+  imageFileToDataUri,
+  redactDataUri,
 } from "bailian-cli-core";
 import { emitResult, emitBare } from "bailian-cli-runtime";
-import { readFileSync, existsSync } from "fs";
+import { existsSync, statSync } from "fs";
 import { extname } from "path";

-const IMAGE_MIME_TYPES: Record<string, string> = {
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".png": "image/png",
-  ".webp": "image/webp",
-};
-
 const VIDEO_EXTENSIONS = new Set([".mp4", ".mov", ".avi", ".mkv", ".webm", ".flv", ".wmv"]);

 function isVideoInput(input: string): boolean {
@@ -35,18 +30,7 @@ async function toImageUrl(image: string): Promise<string> {
  if (image.startsWith("data:")) return image;
  if (image.startsWith("http://") || image.startsWith("https://")) return image;
  if (image.startsWith("oss://")) return image;
-
-  // Local file → data URI (for small files < 10MB, fallback)
-  if (!existsSync(image)) throw new BailianError(`File not found: ${image}`, ExitCode.USAGE);
-  const ext = extname(image).toLowerCase();
-  const mime = IMAGE_MIME_TYPES[ext];
-  if (!mime)
-    throw new BailianError(
-      `Unsupported image format "${ext}". Supported: jpg, jpeg, png, webp`,
-      ExitCode.USAGE,
-    );
-  const buf = readFileSync(image);
-  return `data:${mime};base64,${buf.toString("base64")}`;
+  return imageFileToDataUri(image);
 }

 export default defineCommand({
@@ -86,7 +70,10 @@ export default defineCommand({
    const { settings, flags } = ctx;
    let image = flags.image;
    const videoInputs = flags.video ?? [];
-    const model = flags.model || "qwen3-vl-plus";
+    const model =
+      flags.model ||
+      (ctx.client.usesTokenPlanEndpoint() ? settings.defaultTextModel : undefined) ||
+      "qwen3-vl-plus";

    // Auto-detect: if --image was given a video file, treat it as --video
    if (image && isVideoInput(image)) {
@@ -102,7 +89,14 @@ export default defineCommand({

    if (settings.dryRun) {
      emitResult(
-        { request: { prompt, image, video: videoInputs.length ? videoInputs : undefined, model } },
+        {
+          request: {
+            prompt,
+            image: image ? redactDataUri(image) : undefined,
+            video: videoInputs.length ? videoInputs.map(redactDataUri) : undefined,
+            model,
+          },
+        },
        format,
      );
      return;
@@ -132,10 +126,9 @@ export default defineCommand({

      let finalImageUrl = imageUrl;
      if (isLocalFile(image) && imageUrl.startsWith("data:")) {
-        const { statSync } = await import("fs");
        const fileSize = statSync(image).size;
        if (fileSize > 5 * 1024 * 1024) {
-          finalImageUrl = await ctx.client.uploadFile(image, model);
+          finalImageUrl = await ctx.client.resolveImageInput(image, model);
        }
      }

@@ -22,6 +22,7 @@ export { default as configSet } from "./commands/config/set.ts";
 export { default as configList } from "./commands/config/list.ts";
 export { default as configUse } from "./commands/config/use.ts";
 export { default as configUi } from "./commands/config/ui.ts";
+export { default as configAgent } from "./commands/config/agent/index.ts";
 export { default as update } from "./commands/update.ts";
 export { default as appCall } from "./commands/app/call.ts";
 export { default as appList } from "./commands/app/list.ts";
@@ -90,6 +91,23 @@ export { default as tokenPlanListSeats } from "./commands/token-plan/list-seats.
 export { default as tokenPlanCreateKey } from "./commands/token-plan/create-key.ts";
 export { default as tokenPlanAssignSeats } from "./commands/token-plan/assign-seats.ts";
 export { default as tokenPlanAddMember } from "./commands/token-plan/add-member.ts";
+export { default as managedAgentInit } from "./commands/managed-agent/init.ts";
+export { default as managedAgentValidate } from "./commands/managed-agent/validate.ts";
+export { default as managedAgentPlan } from "./commands/managed-agent/plan.ts";
+export { default as managedAgentApply } from "./commands/managed-agent/apply.ts";
+export { default as managedAgentDestroy } from "./commands/managed-agent/destroy.ts";
+export { default as managedAgentStateList } from "./commands/managed-agent/state-list.ts";
+export { default as managedAgentStateShow } from "./commands/managed-agent/state-show.ts";
+export { default as managedAgentStateRm } from "./commands/managed-agent/state-rm.ts";
+export { default as managedAgentStateImport } from "./commands/managed-agent/state-import.ts";
+export { default as managedAgentSessionCreate } from "./commands/managed-agent/session-create.ts";
+export { default as managedAgentSessionList } from "./commands/managed-agent/session-list.ts";
+export { default as managedAgentSessionGet } from "./commands/managed-agent/session-get.ts";
+export { default as managedAgentSessionDelete } from "./commands/managed-agent/session-delete.ts";
+export { default as managedAgentSessionRun } from "./commands/managed-agent/session-run.ts";
+export { default as managedAgentSessionSend } from "./commands/managed-agent/session-send.ts";
+export { default as managedAgentSessionEvents } from "./commands/managed-agent/session-events.ts";
+export { default as managedAgentSkillList } from "./commands/managed-agent/skill-list.ts";
 export { default as workspaceInit } from "./commands/workspace/init.ts";
 export { default as pluginInstall } from "./commands/plugin/install.ts";
 export { default as pluginLink } from "./commands/plugin/link.ts";
@@ -0,0 +1,159 @@
+import { describe, expect, test } from "vite-plus/test";
+import { decodeTokenPlanKey } from "../src/commands/config/agent/decode-key.ts";
+
+/**
+ * decode-key 单元测试:在测试内移植前端 encodeTokenPlanKey 参考实现
+ * (bailian-tokenplan encode-token-plan-key.ts),做 encode → decode round-trip,
+ * 保证 CLI 解码与前端编码逐位互逆。
+ */
+
+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 CHECKSUM_LENGTH = 6;
+const FEISTEL_ROUNDS = 8;
+
+function toDigits(value: string): number[] {
+  return value.split("").map((character) => {
+    const digit = ALPHABET_INDEX.get(character);
+    if (digit === undefined) throw new Error("bad char");
+    return digit;
+  });
+}
+
+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 obfuscatePayload(apiKey: string, salt: string): string {
+  const digits = toDigits(apiKey);
+  const midpoint = Math.floor(digits.length / 2);
+  let left = digits.slice(0, midpoint);
+  let right = digits.slice(midpoint);
+
+  for (let round = 0; round < FEISTEL_ROUNDS; round += 1) {
+    const mask = createRoundMask(right, salt, round, left.length);
+    const nextRight = left.map((digit, index) => (digit + mask[index]) % ALPHABET_SIZE);
+    left = right;
+    right = nextRight;
+  }
+  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);
+  }
+  return encoded.join("");
+}
+
+/** 前端 encodeTokenPlanKey 的测试内移植(固定 salt)。 */
+function encodeTokenPlanKey(apiKey: string, salt: string): string {
+  const payload = obfuscatePayload(apiKey, salt);
+  const checksum = encodeBase65Number(crc32(apiKey), CHECKSUM_LENGTH);
+  return TOKEN_PREFIX + salt + payload + checksum;
+}
+
+describe("config agent decode-key", () => {
+  test("encode → decode round-trip 还原原始 apiKey", () => {
+    const samples = [
+      "sk-1234567890abcdef",
+      "sk-sp-H.PML.Ns85.MEUCIFHbYk4yBBWLGegORHfWZGB5DdSEs6ms3AwyMsuTOk0CAiEAlOwrUO6dz6IYPUlJ4gK7u6kjStkythgxWaVP5B28ly0",
+      "a",
+      "A-b_c.9",
+    ];
+    const salts = ["AbC123", "zzzzzz", "0.-_Zq", "AAAAAA"];
+    for (const apiKey of samples) {
+      for (const salt of salts) {
+        expect(decodeTokenPlanKey(encodeTokenPlanKey(apiKey, salt))).toBe(apiKey);
+      }
+    }
+  });
+
+  test("固定 salt 的确定性:相同输入产出相同 token 且可解码", () => {
+    const tokenA = encodeTokenPlanKey("sk-fixed-key", "S4ltS4");
+    const tokenB = encodeTokenPlanKey("sk-fixed-key", "S4ltS4");
+    expect(tokenA).toBe(tokenB);
+    expect(decodeTokenPlanKey(tokenA)).toBe("sk-fixed-key");
+  });
+
+  test("篡改 checksum 抛错", () => {
+    const token = encodeTokenPlanKey("sk-checksum-test", "AbC123");
+    const flippedTail = token.slice(-1) === "A" ? "B" : "A";
+    const tampered = token.slice(0, -1) + flippedTail;
+    expect(() => decodeTokenPlanKey(tampered)).toThrow(/Invalid obfuscated API key/);
+  });
+
+  test("篡改 salt 抛错(payload 解出与 checksum 不符)", () => {
+    const token = encodeTokenPlanKey("sk-salt-test", "AbC123");
+    const body = token.slice(TOKEN_PREFIX.length);
+    const flippedSaltHead = body[0] === "A" ? "B" : "A";
+    const tampered = TOKEN_PREFIX + flippedSaltHead + body.slice(1);
+    expect(() => decodeTokenPlanKey(tampered)).toThrow(/Invalid obfuscated API key/);
+  });
+
+  test("非法前缀 / 非法字符 / 过短 token 抛错", () => {
+    expect(() => decodeTokenPlanKey("x1_AbC123payloadAAAAAA")).toThrow(
+      /Invalid obfuscated API key/,
+    );
+    expect(() => decodeTokenPlanKey("o1_AbC123pay!oadAAAAAA")).toThrow(
+      /Invalid obfuscated API key/,
+    );
+    expect(() => decodeTokenPlanKey("o1_short")).toThrow(/Invalid obfuscated API key/);
+    expect(() => decodeTokenPlanKey("")).toThrow(/Invalid obfuscated API key/);
+  });
+});
@@ -0,0 +1,582 @@
+import { mkdtempSync, rmSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from "fs";
+import { tmpdir, homedir } from "os";
+import { join } from "path";
+import { afterEach, beforeEach, describe, expect, test } from "vite-plus/test";
+import claudeCode from "../src/commands/config/agent/writers/claude-code.ts";
+import qwenCode from "../src/commands/config/agent/writers/qwen-code.ts";
+import opencode from "../src/commands/config/agent/writers/opencode.ts";
+import openclaw from "../src/commands/config/agent/writers/openclaw.ts";
+import hermes from "../src/commands/config/agent/writers/hermes.ts";
+import codex from "../src/commands/config/agent/writers/codex.ts";
+import { resolveRegionBaseUrl } from "../src/commands/config/agent/writers/utils.ts";
+import yaml from "yaml";
+
+/**
+ * Agent writer 单元测试：直接调用 writer，用临时 HOME 隔离文件系统。
+ * writer 是纯文件 I/O，在进程内测试比 e2e 子进程更快、覆盖更全。
+ */
+
+const OAI_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1";
+const ANTHROPIC_URL = "https://dashscope.aliyuncs.com/apps/anthropic";
+
+let home = "";
+let prevHome: string | undefined;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "bl-agent-writer-"));
+  prevHome = process.env.HOME;
+  process.env.HOME = home;
+  // homedir() 在 POSIX 读 $HOME；断言隔离生效。
+  expect(homedir()).toBe(home);
+});
+
+afterEach(() => {
+  if (prevHome === undefined) delete process.env.HOME;
+  else process.env.HOME = prevHome;
+  rmSync(home, { recursive: true, force: true });
+});
+
+function readJsonAt(...segments: string[]): Record<string, unknown> {
+  return JSON.parse(readFileSync(join(home, ...segments), "utf8"));
+}
+
+describe("config agent writers", () => {
+  test("claude-code 写入 env 与 onboarding，并合并已有 env", () => {
+    // 预置一个无关 env 键与旧的 ANTHROPIC_API_KEY，验证合并保留 / 旧键清理
+    mkdirSync(join(home, ".claude"), { recursive: true });
+    writeFileSync(
+      join(home, ".claude", "settings.json"),
+      JSON.stringify({
+        env: { KEEP_ME: "1", ANTHROPIC_API_KEY: "sk-stale" },
+        other: true,
+      }),
+    );
+
+    const summary = claudeCode.write({
+      baseUrl: ANTHROPIC_URL,
+      apiKey: "sk-a",
+      model: "qwen3-max",
+    });
+    expect(summary.paths).toHaveLength(2);
+
+    const settings = readJsonAt(".claude", "settings.json");
+    const env = settings.env as Record<string, string>;
+    expect(env.KEEP_ME).toBe("1");
+    expect(settings.other).toBe(true);
+    expect(env.ANTHROPIC_BASE_URL).toBe(ANTHROPIC_URL);
+    expect(env.ANTHROPIC_AUTH_TOKEN).toBe("sk-a");
+    expect(env.ANTHROPIC_API_KEY).toBeUndefined();
+    expect(env.ANTHROPIC_MODEL).toBe("qwen3-max");
+    expect(env.ANTHROPIC_DEFAULT_HAIKU_MODEL).toBe("qwen3-max");
+    expect(env.ANTHROPIC_DEFAULT_SONNET_MODEL).toBe("qwen3-max");
+    expect(env.ANTHROPIC_DEFAULT_OPUS_MODEL).toBe("qwen3-max");
+    expect(env.CLAUDE_CODE_SUBAGENT_MODEL).toBe("qwen3-max");
+
+    expect(readJsonAt(".claude.json").hasCompletedOnboarding).toBe(true);
+  });
+
+  test("claude-code 尊重 CLAUDE_CONFIG_DIR", () => {
+    const customDir = join(home, "custom-claude");
+    process.env.CLAUDE_CONFIG_DIR = customDir;
+    try {
+      claudeCode.write({
+        baseUrl: ANTHROPIC_URL,
+        apiKey: "sk-a",
+        model: "qwen3-max",
+      });
+      const settings = JSON.parse(readFileSync(join(customDir, "settings.json"), "utf8"));
+      expect((settings.env as Record<string, string>).ANTHROPIC_AUTH_TOKEN).toBe("sk-a");
+    } finally {
+      delete process.env.CLAUDE_CONFIG_DIR;
+    }
+  });
+
+  test("claude-code 将 compatible-mode URL 改写为 apps/anthropic", () => {
+    const tokenPlanOpenAi = "https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1";
+    const summary = claudeCode.write({
+      baseUrl: tokenPlanOpenAi,
+      apiKey: "sk-a",
+      model: "qwen3.8-max-preview",
+    });
+    const env = readJsonAt(".claude", "settings.json").env as Record<string, string>;
+    expect(env.ANTHROPIC_BASE_URL).toBe(
+      "https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic",
+    );
+    expect(summary.warnings?.some((warning) => warning.includes("Rewrote base URL"))).toBe(true);
+  });
+
+  test("claude-code 保留已有分层模型，不整表覆盖", () => {
+    mkdirSync(join(home, ".claude"), { recursive: true });
+    writeFileSync(
+      join(home, ".claude", "settings.json"),
+      JSON.stringify({
+        env: {
+          ANTHROPIC_DEFAULT_HAIKU_MODEL: "qwen3.6-flash",
+          CLAUDE_CODE_SUBAGENT_MODEL: "qwen3.7-max",
+        },
+      }),
+    );
+
+    claudeCode.write({
+      baseUrl: ANTHROPIC_URL,
+      apiKey: "sk-a",
+      model: "qwen3.8-max-preview",
+    });
+    const env = readJsonAt(".claude", "settings.json").env as Record<string, string>;
+    expect(env.ANTHROPIC_MODEL).toBe("qwen3.8-max-preview");
+    expect(env.ANTHROPIC_DEFAULT_HAIKU_MODEL).toBe("qwen3.6-flash");
+    expect(env.CLAUDE_CODE_SUBAGENT_MODEL).toBe("qwen3.7-max");
+    expect(env.ANTHROPIC_DEFAULT_SONNET_MODEL).toBe("qwen3.8-max-preview");
+  });
+
+  test("claude-code 拒绝无法改写为 Anthropic 的 base URL", () => {
+    expect(() =>
+      claudeCode.write({
+        baseUrl: "https://api.openai.com/v1",
+        apiKey: "sk-a",
+        model: "qwen3-max",
+      }),
+    ).toThrow(/Anthropic-compatible base URL/);
+  });
+
+  test("qwen-code compatible-mode 走 openai 协议（官方 v3 结构）", () => {
+    qwenCode.write({
+      baseUrl: OAI_URL,
+      apiKey: "sk-q",
+      model: "qwen3-coder-plus",
+    });
+    const settings = readJsonAt(".qwen", "settings.json");
+    expect(settings.$version).toBe(3);
+    const security = settings.security as { auth: Record<string, unknown> };
+    // security.auth 携带 selectedType 以及凭证兜底（apiKey/baseUrl），
+    // 避免系统 OPENAI_API_KEY 抢占
+    expect(security.auth).toEqual({
+      selectedType: "openai",
+      apiKey: "sk-q",
+      baseUrl: OAI_URL,
+    });
+    expect((settings.env as Record<string, string>).DASHSCOPE_API_KEY).toBe("sk-q");
+    // model.name 必须与 baseUrl 一同写入（同 id provider 消歧契约）
+    expect(settings.model).toEqual({
+      name: "qwen3-coder-plus",
+      baseUrl: OAI_URL,
+    });
+    const providers = settings.modelProviders as Record<string, Array<Record<string, unknown>>>;
+    // name 是模型显示名（非 provider 品牌常量），品牌只在 envKey 里
+    expect(providers.openai[0]).toMatchObject({
+      id: "qwen3-coder-plus",
+      name: "[Bailian] qwen3-coder-plus",
+      baseUrl: OAI_URL,
+      envKey: "DASHSCOPE_API_KEY",
+    });
+  });
+
+  test("qwen-code upsert 时治愈旧的 bailian-cli name 但保留用户自定义 name", () => {
+    mkdirSync(join(home, ".qwen"), { recursive: true });
+    writeFileSync(
+      join(home, ".qwen", "settings.json"),
+      JSON.stringify({
+        modelProviders: {
+          openai: [
+            {
+              id: "qwen3-coder-plus",
+              name: "bailian-cli",
+              baseUrl: OAI_URL,
+              envKey: "DASHSCOPE_API_KEY",
+            },
+            {
+              id: "my-model",
+              name: "My Custom",
+              baseUrl: OAI_URL,
+              envKey: "DASHSCOPE_API_KEY",
+            },
+          ],
+        },
+      }),
+    );
+
+    // 旧 sentinel 被治愈为显示名
+    qwenCode.write({
+      baseUrl: OAI_URL,
+      apiKey: "sk-q",
+      model: "qwen3-coder-plus",
+    });
+    // 用户自定义 name 不被覆盖
+    qwenCode.write({ baseUrl: OAI_URL, apiKey: "sk-q", model: "my-model" });
+
+    const settings = readJsonAt(".qwen", "settings.json");
+    const entries = (settings.modelProviders as Record<string, Array<Record<string, unknown>>>)
+      .openai;
+    const healed = entries.find((entry) => entry.id === "qwen3-coder-plus")!;
+    expect(healed.name).toBe("[Bailian] qwen3-coder-plus");
+    expect(healed.envKey).toBe("DASHSCOPE_API_KEY");
+    const custom = entries.find((entry) => entry.id === "my-model")!;
+    expect(custom.name).toBe("My Custom");
+  });
+
+  test("qwen-code anthropic 端点走 anthropic 协议", () => {
+    qwenCode.write({
+      baseUrl: ANTHROPIC_URL,
+      apiKey: "sk-q",
+      model: "qwen3-max",
+    });
+    const settings = readJsonAt(".qwen", "settings.json");
+    expect((settings.security as { auth: { selectedType: string } }).auth.selectedType).toBe(
+      "anthropic",
+    );
+    const providers = settings.modelProviders as Record<string, unknown>;
+    expect(Array.isArray(providers.anthropic)).toBe(true);
+    expect(providers.openai).toBeUndefined();
+  });
+
+  test("qwen-code 对自有 provider 项按 id upsert 而非追加", () => {
+    qwenCode.write({
+      baseUrl: OAI_URL,
+      apiKey: "sk-1",
+      model: "qwen3-coder-plus",
+    });
+    qwenCode.write({
+      baseUrl: OAI_URL,
+      apiKey: "sk-2",
+      model: "qwen3-coder-plus",
+    });
+    const settings = readJsonAt(".qwen", "settings.json");
+    const openaiEntries = (settings.modelProviders as Record<string, unknown[]>).openai;
+    expect(openaiEntries).toHaveLength(1);
+    expect((settings.env as Record<string, string>).DASHSCOPE_API_KEY).toBe("sk-2");
+  });
+
+  test("qwen-code 不劫持已有 Token Plan 同 id 条目的 name/envKey", () => {
+    mkdirSync(join(home, ".qwen"), { recursive: true });
+    writeFileSync(
+      join(home, ".qwen", "settings.json"),
+      JSON.stringify({
+        env: { BAILIAN_TOKEN_PLAN_API_KEY: "sk-token-plan" },
+        modelProviders: {
+          openai: [
+            {
+              id: "qwen3.8-max-preview",
+              name: "[Token Plan 个人版] qwen3.8-max-preview",
+              baseUrl: "https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
+              envKey: "BAILIAN_TOKEN_PLAN_API_KEY",
+              generationConfig: { extra_body: { enable_thinking: true } },
+            },
+          ],
+        },
+      }),
+    );
+
+    const tokenPlanUrl = "https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1";
+    const summary = qwenCode.write({
+      baseUrl: tokenPlanUrl,
+      apiKey: "sk-bailian",
+      model: "qwen3.8-max-preview",
+    });
+
+    const settings = readJsonAt(".qwen", "settings.json");
+    const openaiEntries = (
+      settings.modelProviders as Record<string, Array<Record<string, unknown>>>
+    ).openai;
+    expect(openaiEntries).toHaveLength(1);
+    expect(openaiEntries[0]).toMatchObject({
+      id: "qwen3.8-max-preview",
+      name: "[Token Plan 个人版] qwen3.8-max-preview",
+      envKey: "BAILIAN_TOKEN_PLAN_API_KEY",
+      generationConfig: { extra_body: { enable_thinking: true } },
+    });
+    expect((settings.env as Record<string, string>).BAILIAN_TOKEN_PLAN_API_KEY).toBe(
+      "sk-token-plan",
+    );
+    expect((settings.env as Record<string, string>).DASHSCOPE_API_KEY).toBe("sk-bailian");
+    expect(summary.warnings?.some((warning) => warning.includes("already exists"))).toBe(true);
+  });
+
+  test("qwen-code 在进程环境变量覆盖 settings.env 时给出警告", () => {
+    const previous = process.env.DASHSCOPE_API_KEY;
+    process.env.DASHSCOPE_API_KEY = "sk-from-shell";
+    try {
+      const summary = qwenCode.write({
+        baseUrl: OAI_URL,
+        apiKey: "sk-from-settings",
+        model: "qwen3-coder-plus",
+      });
+      expect(summary.warnings?.some((warning) => warning.includes("overrides settings.json"))).toBe(
+        true,
+      );
+    } finally {
+      if (previous === undefined) delete process.env.DASHSCOPE_API_KEY;
+      else process.env.DASHSCOPE_API_KEY = previous;
+    }
+  });
+
+  test("opencode 容忍 JSONC（注释与尾逗号）", () => {
+    mkdirSync(join(home, ".config", "opencode"), { recursive: true });
+    writeFileSync(
+      join(home, ".config", "opencode", "opencode.json"),
+      [
+        "{",
+        "  // user comment",
+        '  "provider": {',
+        '    "other": { "name": "Other" }, // inline comment',
+        "  },",
+        "  /* block */",
+        '  "theme": "dark",',
+        "}",
+      ].join("\n"),
+    );
+
+    opencode.write({ baseUrl: OAI_URL, apiKey: "sk-o", model: "qwen3-max" });
+    const config = readJsonAt(".config", "opencode", "opencode.json");
+    expect(config.theme).toBe("dark");
+    const provider = config.provider as Record<string, unknown>;
+    expect(provider.other).toBeDefined();
+    expect(provider["bailian-cli"]).toBeDefined();
+  });
+
+  test("opencode 按端点选 npm，含 setCacheKey，合并保留其它 provider", () => {
+    mkdirSync(join(home, ".config", "opencode"), { recursive: true });
+    writeFileSync(
+      join(home, ".config", "opencode", "opencode.json"),
+      JSON.stringify({ provider: { other: { name: "Other" } } }),
+    );
+
+    opencode.write({
+      baseUrl: ANTHROPIC_URL,
+      apiKey: "sk-o",
+      model: "qwen3-max",
+    });
+    const config = readJsonAt(".config", "opencode", "opencode.json");
+    const provider = config.provider as Record<string, Record<string, unknown>>;
+    expect(provider.other).toBeDefined();
+    expect(provider["bailian-cli"].npm).toBe("@ai-sdk/anthropic");
+    const options = provider["bailian-cli"].options as Record<string, unknown>;
+    expect(options.baseURL).toBe(ANTHROPIC_URL);
+    expect(options.apiKey).toBe("sk-o");
+    expect(options.setCacheKey).toBe(true);
+    expect((provider["bailian-cli"].models as Record<string, unknown>)["qwen3-max"]).toBeDefined();
+
+    // 非 anthropic 端点用 openai-compatible
+    opencode.write({ baseUrl: OAI_URL, apiKey: "sk-o", model: "qwen3-max" });
+    expect(
+      (
+        readJsonAt(".config", "opencode", "opencode.json").provider as Record<
+          string,
+          { npm: string }
+        >
+      )["bailian-cli"].npm,
+    ).toBe("@ai-sdk/openai-compatible");
+  });
+
+  test("openclaw 写入 provider、api、primary，并登记 defaults.models", () => {
+    openclaw.write({
+      baseUrl: OAI_URL,
+      apiKey: "sk-c",
+      model: "qwen3-coder-plus",
+    });
+    const config = readJsonAt(".openclaw", "openclaw.json");
+    const models = config.models as Record<string, unknown>;
+    expect(models.mode).toBe("merge");
+    const bailian = (models.providers as Record<string, Record<string, unknown>>)["bailian-cli"];
+    expect(bailian.api).toBe("openai-completions");
+    const entry = (bailian.models as Array<Record<string, unknown>>)[0];
+    expect(entry.id).toBe("qwen3-coder-plus");
+    expect(entry.contextWindow).toBe(256000);
+    expect(entry.cost).toEqual({
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+    });
+    const agents = config.agents as {
+      defaults: { model: { primary: string }; models: Record<string, unknown> };
+    };
+    expect(agents.defaults.model.primary).toBe("bailian-cli/qwen3-coder-plus");
+    expect(agents.defaults.models["bailian-cli/qwen3-coder-plus"]).toEqual({});
+
+    // --context-window 覆盖默认值；anthropic 端点用 anthropic-messages
+    openclaw.write({
+      baseUrl: ANTHROPIC_URL,
+      apiKey: "sk-c",
+      model: "qwen3-max",
+      contextWindow: 1000000,
+    });
+    const config2 = readJsonAt(".openclaw", "openclaw.json");
+    const providers2 = (config2.models as Record<string, unknown>).providers as Record<
+      string,
+      { api: string; models: Array<Record<string, unknown>> }
+    >;
+    expect(providers2["bailian-cli"].api).toBe("anthropic-messages");
+    expect(providers2["bailian-cli"].models[0].contextWindow).toBe(1000000);
+    expect(
+      (config2.agents as { defaults: { model: { primary: string } } }).defaults.model.primary,
+    ).toBe("bailian-cli/qwen3-max");
+  });
+
+  test("openclaw 不抢占已有 token-plan primary", () => {
+    mkdirSync(join(home, ".openclaw"), { recursive: true });
+    writeFileSync(
+      join(home, ".openclaw", "openclaw.json"),
+      JSON.stringify({
+        models: {
+          mode: "merge",
+          providers: {
+            "bailian-token-plan": {
+              baseUrl: "https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic",
+              apiKey: "sk-token-plan",
+              api: "anthropic-messages",
+              models: [{ id: "qwen3.8-max-preview", name: "qwen3.8-max-preview" }],
+            },
+          },
+        },
+        agents: {
+          defaults: {
+            model: { primary: "bailian-token-plan/qwen3.8-max-preview" },
+            models: { "bailian-token-plan/qwen3.8-max-preview": {} },
+          },
+        },
+      }),
+    );
+
+    const summary = openclaw.write({
+      baseUrl: "https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
+      apiKey: "sk-bailian",
+      model: "qwen3.8-max-preview",
+    });
+
+    const config = readJsonAt(".openclaw", "openclaw.json");
+    const agents = config.agents as {
+      defaults: { model: { primary: string }; models: Record<string, unknown> };
+    };
+    expect(agents.defaults.model.primary).toBe("bailian-token-plan/qwen3.8-max-preview");
+    expect(agents.defaults.models["bailian-cli/qwen3.8-max-preview"]).toEqual({});
+    expect(
+      (config.models as { providers: Record<string, unknown> }).providers["bailian-token-plan"],
+    ).toBeDefined();
+    expect(
+      (config.models as { providers: Record<string, unknown> }).providers["bailian-cli"],
+    ).toBeDefined();
+    expect(summary.warnings?.some((warning) => warning.includes("Left existing primary"))).toBe(
+      true,
+    );
+  });
+
+  test("hermes 写入官方扁平 model.* 结构，保留其它顶层键", () => {
+    mkdirSync(join(home, ".hermes"), { recursive: true });
+    writeFileSync(
+      join(home, ".hermes", "config.yaml"),
+      yaml.stringify({
+        custom_providers: [{ name: "other", base_url: "https://x" }],
+      }),
+    );
+
+    hermes.write({
+      baseUrl: OAI_URL,
+      apiKey: "sk-h",
+      model: "qwen3-coder-plus",
+    });
+    const config = yaml.parse(readFileSync(join(home, ".hermes", "config.yaml"), "utf8"));
+    // OpenAI 兼容端点：按官方文档省略 api_mode；无关顶层键不受影响
+    expect(config.model).toEqual({
+      default: "qwen3-coder-plus",
+      provider: "custom",
+      base_url: OAI_URL,
+      api_key: "sk-h",
+    });
+    expect(config.custom_providers).toHaveLength(1);
+
+    // anthropic 端点：必须带 api_mode = anthropic_messages
+    hermes.write({
+      baseUrl: ANTHROPIC_URL,
+      apiKey: "sk-h",
+      model: "qwen3-max",
+    });
+    const config2 = yaml.parse(readFileSync(join(home, ".hermes", "config.yaml"), "utf8"));
+    expect(config2.model).toEqual({
+      default: "qwen3-max",
+      provider: "custom",
+      base_url: ANTHROPIC_URL,
+      api_key: "sk-h",
+      api_mode: "anthropic_messages",
+    });
+  });
+
+  test("codex 写入 config.toml 与 auth.json（官方 env_key 结构，合并保留）", () => {
+    // 预置 config.toml 无关顶层键与另一个 provider，验证非破坏性合并
+    mkdirSync(join(home, ".codex"), { recursive: true });
+    writeFileSync(
+      join(home, ".codex", "config.toml"),
+      [
+        'approval_policy = "on-request"',
+        "",
+        "[model_providers.other]",
+        'name = "other"',
+        'base_url = "https://other.example.com/v1"',
+        "",
+      ].join("\n"),
+    );
+    // 预置 auth.json 无关键，验证合并保留
+    writeFileSync(join(home, ".codex", "auth.json"), JSON.stringify({ EXISTING: "keep" }));
+
+    const summary = codex.write({
+      baseUrl: OAI_URL,
+      apiKey: "sk-x",
+      model: "qwen3-coder-plus",
+    });
+    // 默认路径无警告
+    expect(summary.warnings).toBeUndefined();
+    const toml = readFileSync(join(home, ".codex", "config.toml"), "utf8");
+    expect(toml).toContain('model_provider = "bailian-cli"');
+    expect(toml).toContain('model = "qwen3-coder-plus"');
+    expect(toml).toContain("[model_providers.bailian-cli]");
+    expect(toml).toContain(`base_url = "${OAI_URL}"`);
+    expect(toml).toContain('env_key = "OPENAI_API_KEY"');
+    // 未传 --wire-api 时默认 responses（新版 Codex 已不支持 chat）
+    expect(toml).toContain('wire_api = "responses"');
+    expect(toml).toContain("requires_openai_auth = true");
+    // 合并：保留用户已有的无关配置
+    expect(toml).toContain('approval_policy = "on-request"');
+    expect(toml).toContain("[model_providers.other]");
+
+    const auth = readJsonAt(".codex", "auth.json");
+    expect(auth.OPENAI_API_KEY).toBe("sk-x");
+    expect(auth.EXISTING).toBe("keep");
+
+    // --wire-api chat：仅旧版 Codex <= 0.80.0 可用，附带警告
+    const summary2 = codex.write({
+      baseUrl: OAI_URL,
+      apiKey: "sk-x",
+      model: "glm-5",
+      wireApi: "chat",
+    });
+    expect(summary2.warnings?.some((warning) => warning.includes("0.80.0"))).toBe(true);
+    const toml2 = readFileSync(join(home, ".codex", "config.toml"), "utf8");
+    expect(toml2).toContain('wire_api = "chat"');
+    expect(toml2).toContain('model = "glm-5"');
+  });
+
+  test("已存在的配置文件会被备份为 .bak.<epoch>", () => {
+    mkdirSync(join(home, ".openclaw"), { recursive: true });
+    writeFileSync(join(home, ".openclaw", "openclaw.json"), JSON.stringify({ pre: 1 }));
+
+    openclaw.write({ baseUrl: OAI_URL, apiKey: "sk-c", model: "qwen3-max" });
+    const backups = readdirSync(join(home, ".openclaw")).filter((name) =>
+      name.startsWith("openclaw.json.bak."),
+    );
+    expect(backups).toHaveLength(1);
+  });
+
+  test("resolveRegionBaseUrl 将 region 转为 Token Plan compatible-mode URL", () => {
+    expect(resolveRegionBaseUrl("cn-beijing")).toBe(
+      "https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
+    );
+    expect(resolveRegionBaseUrl("ap-southeast-1")).toBe(
+      "https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
+    );
+  });
+
+  test("resolveRegionBaseUrl 拒绝非法 region", () => {
+    expect(() => resolveRegionBaseUrl("cn beijing")).toThrow(/Invalid --region/);
+    expect(() => resolveRegionBaseUrl("CN-Beijing")).toThrow(/Invalid --region/);
+    expect(() => resolveRegionBaseUrl("")).toThrow(/Invalid --region/);
+  });
+});
@@ -81,6 +81,8 @@ test("GET /api/config 返回全部 profile、明文密钥与持久化激活项",
    expect(res.json.default).toMatchObject({ api_key: "sk-default", output: "json" });
    expect(res.json.named.dev).toMatchObject({ api_key: "sk-dev", access_token: "tok-dev" });
    expect(res.json.secretKeys).toContain("api_key");
+    expect(res.json.keys).toContain("default_image_to_video_model");
+    expect(res.json.keys).toContain("default_reference_to_video_model");
  });
 });

@@ -112,10 +114,10 @@ test("POST /api/profile 写命名 profile（timeout 强制为 number），空串
    expect(readConfigFile("stage")).toMatchObject({
      api_key: "sk-stage",
      timeout: 90,
-      base_url: "https://proxy.example.com/team",
+      base_url: "https://proxy.example.com",
    });
    const rawConfig = JSON.parse(readFileSync(getConfigPath(), "utf8"));
-    expect(rawConfig.stage.base_url).toBe("https://proxy.example.com/team");
+    expect(rawConfig.stage.base_url).toBe("https://proxy.example.com");

    // 空串清除 api_key（整块替换）
    const clear = await httpJson(port, "POST", `/api/profile?token=${TOKEN}`, {
@@ -0,0 +1,217 @@
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { afterEach, beforeEach, expect, test } from "vite-plus/test";
+import {
+  type ApiKeyCredential,
+  Client,
+  ExitCode,
+  type Identity,
+  type Settings,
+} from "bailian-cli-core";
+import {
+  assertProviderCredentials,
+  type CredentialHost,
+  injectProviderCredentials,
+  prepareProviderEnv,
+  scrubCredentialEnv,
+} from "../src/commands/managed-agent/_engine/credentials.ts";
+
+/**
+ * 凭证内存注入管道:injectProviderCredentials 把 authStage 解析进 Client 的凭证
+ * 权威覆写 bailian 配置块(不落 env),scrubCredentialEnv 清空所有凭证 env,
+ * assertProviderCredentials 对任一已声明 provider 的空 key 给 CLI 权威 AUTH
+ * 错误(离线命令跳过断言)。用快照隔离凭证 env。
+ */
+const TRACKED_ENV = [
+  "DASHSCOPE_API_KEY",
+  "BAILIAN_API_KEY",
+  "BAILIAN_BASE_URL",
+  "BAILIAN_WORKSPACE_ID",
+  "ANTHROPIC_API_KEY",
+  "CLAUDE_API_KEY",
+  "ARK_API_KEY",
+  "QODER_PAT",
+  "QODER_API_KEY",
+  "AGENTS_CONFIG_PATH",
+  "AGENTS_PROVIDER",
+];
+
+let envSnapshot: Record<string, string | undefined> = {};
+
+beforeEach(() => {
+  envSnapshot = Object.fromEntries(TRACKED_ENV.map((key) => [key, process.env[key]]));
+});
+
+afterEach(() => {
+  for (const key of TRACKED_ENV) {
+    const value = envSnapshot[key];
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+});
+
+const identity: Identity = {
+  binName: "bl",
+  version: "0.0.0-test",
+  npmPackage: "bailian-cli",
+  clientName: "bailian-cli",
+};
+
+function makeHost(options: { apiCred?: ApiKeyCredential; workspaceId?: string }): CredentialHost {
+  const settings = { workspaceId: options.workspaceId } as Settings;
+  return {
+    settings,
+    client: new Client({
+      identity,
+      settings,
+      baseUrl: options.apiCred?.baseUrl ?? "https://dashscope.aliyuncs.com",
+      apiCred: options.apiCred,
+    }),
+  };
+}
+
+function bailianCred(
+  token = "sk-auth-chain",
+  baseUrl = "https://dashscope.aliyuncs.com",
+): ApiKeyCredential {
+  return { token, baseUrl, source: "config" };
+}
+
+test("inject:bailian api_key 无条件覆盖(含 yaml 字面量),base_url 空则拼 agentstudio 后缀", () => {
+  const providers = { bailian: { api_key: "literal-from-yaml", base_url: "" } };
+  injectProviderCredentials(providers, makeHost({ apiCred: bailianCred() }));
+  expect(providers.bailian.api_key).toBe("sk-auth-chain");
+  expect(providers.bailian.base_url).toBe("https://dashscope.aliyuncs.com/api/v1/agentstudio");
+});
+
+test("inject:base_url 已带后缀不重复拼;非空字面量 base_url 保留", () => {
+  const withSuffix = { bailian: { api_key: "", base_url: "" } };
+  injectProviderCredentials(
+    withSuffix,
+    makeHost({
+      apiCred: bailianCred("t", "https://x.maas.aliyuncs.com/api/v1/agentstudio"),
+    }),
+  );
+  expect(withSuffix.bailian.base_url).toBe("https://x.maas.aliyuncs.com/api/v1/agentstudio");
+
+  const literal = {
+    bailian: {
+      api_key: "",
+      base_url: "https://custom.example.com/api/v1/agentstudio",
+    },
+  };
+  injectProviderCredentials(literal, makeHost({ apiCred: bailianCred() }));
+  expect(literal.bailian.base_url).toBe("https://custom.example.com/api/v1/agentstudio");
+});
+
+test("inject:base_url 尾斜杠被规范化,不产生双斜杠", () => {
+  const providers = { bailian: { api_key: "", base_url: "" } };
+  injectProviderCredentials(
+    providers,
+    makeHost({ apiCred: bailianCred("t", "https://dashscope.aliyuncs.com/") }),
+  );
+  expect(providers.bailian.base_url).toBe("https://dashscope.aliyuncs.com/api/v1/agentstudio");
+});
+
+test("inject:已带后缀且尾斜杠的 base_url 去斜杠后原样保留", () => {
+  const providers = { bailian: { api_key: "", base_url: "" } };
+  injectProviderCredentials(
+    providers,
+    makeHost({
+      apiCred: bailianCred("t", "https://x.maas.aliyuncs.com/api/v1/agentstudio/"),
+    }),
+  );
+  expect(providers.bailian.base_url).toBe("https://x.maas.aliyuncs.com/api/v1/agentstudio");
+});
+
+test("inject:workspace_id 引用且为空时用 settings 填充;有字面量则保留", () => {
+  const empty = { bailian: { api_key: "", workspace_id: "" } };
+  injectProviderCredentials(
+    empty,
+    makeHost({ apiCred: bailianCred(), workspaceId: "ws-settings" }),
+  );
+  expect(empty.bailian.workspace_id).toBe("ws-settings");
+
+  const literal = { bailian: { api_key: "", workspace_id: "ws-yaml" } };
+  injectProviderCredentials(
+    literal,
+    makeHost({ apiCred: bailianCred(), workspaceId: "ws-settings" }),
+  );
+  expect(literal.bailian.workspace_id).toBe("ws-yaml");
+});
+
+test("inject:无凭证时 api_key 保持不变,base_url 仍用 client 默认域名补齐(离线/范围外 schema 可用)", () => {
+  const providers = { bailian: { api_key: "", base_url: "" } };
+  injectProviderCredentials(providers, makeHost({}));
+  expect(providers.bailian.api_key).toBe("");
+  expect(providers.bailian.base_url).toBe("https://dashscope.aliyuncs.com/api/v1/agentstudio");
+});
+
+test("inject:非 bailian provider 块不被触碰", () => {
+  const providers = {
+    claude: { api_key: "sk-ant" },
+    ark: { api_key: "ark-key" },
+  };
+  injectProviderCredentials(providers, makeHost({ apiCred: bailianCred() }));
+  expect(providers.claude.api_key).toBe("sk-ant");
+  expect(providers.ark.api_key).toBe("ark-key");
+});
+
+test("assert:所有已声明 provider 的 key 非空时通过", () => {
+  expect(() =>
+    assertProviderCredentials({
+      bailian: { api_key: "x" },
+      claude: { api_key: "y" },
+    }),
+  ).not.toThrow();
+});
+
+test("assert:claude key 为空抛 AUTH 且 hint 指向 ANTHROPIC_API_KEY", () => {
+  let thrown: unknown;
+  try {
+    assertProviderCredentials({ claude: { api_key: "" } });
+  } catch (error) {
+    thrown = error;
+  }
+  const err = thrown as { exitCode?: number; hint?: string; message?: string };
+  expect(err.exitCode).toBe(ExitCode.AUTH);
+  expect(err.hint).toContain("ANTHROPIC_API_KEY");
+  expect(err.message).toContain("claude");
+});
+
+test("assert:bailian key 为空(dry-run/未登录)抛 AUTH 且 hint 指向 bl auth login", () => {
+  let thrown: unknown;
+  try {
+    assertProviderCredentials({ bailian: { api_key: "" } });
+  } catch (error) {
+    thrown = error;
+  }
+  const err = thrown as { exitCode?: number; hint?: string };
+  expect(err.exitCode).toBe(ExitCode.AUTH);
+  expect(err.hint).toContain("bl auth login");
+});
+
+test("scrub:所有凭证 env 变量被删除", () => {
+  process.env.DASHSCOPE_API_KEY = "x";
+  process.env.ANTHROPIC_API_KEY = "y";
+  process.env.ARK_API_KEY = "z";
+  process.env.BAILIAN_BASE_URL = "u";
+  process.env.QODER_PAT = "q";
+  scrubCredentialEnv();
+  expect(process.env.DASHSCOPE_API_KEY).toBeUndefined();
+  expect(process.env.ANTHROPIC_API_KEY).toBeUndefined();
+  expect(process.env.ARK_API_KEY).toBeUndefined();
+  expect(process.env.BAILIAN_BASE_URL).toBeUndefined();
+  expect(process.env.QODER_PAT).toBeUndefined();
+});
+
+test("prepare:调用后凭证变量均已定义,避免 yaml 插值抛错", () => {
+  // 指向不存在的 agents 配置,隔离宿主 ~/.agents/config.json 干扰
+  process.env.AGENTS_CONFIG_PATH = join(tmpdir(), "no-such-agents-config.json");
+  delete process.env.ARK_API_KEY;
+  delete process.env.QODER_API_KEY;
+  prepareProviderEnv();
+  // 契约:每个凭证变量都被占位或填充,插值不会因 undefined 抛错
+  expect(process.env.ARK_API_KEY).toBeDefined();
+  expect(process.env.QODER_API_KEY).toBeDefined();
+});
@@ -0,0 +1,92 @@
+import { BailianError, ExitCode } from "bailian-cli-core";
+import { afterEach, beforeEach, expect, test, vi } from "vite-plus/test";
+
+const sdkMocks = vi.hoisted(() => ({
+  destroyPlannedProjectResources: vi.fn(),
+  planDestroyProjectContext: vi.fn(),
+}));
+
+const configLoaderMocks = vi.hoisted(() => ({
+  buildAgentRuntime: vi.fn(),
+}));
+
+vi.mock("@openagentpack/sdk", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@openagentpack/sdk")>();
+  return { ...actual, ...sdkMocks };
+});
+
+vi.mock("../src/commands/managed-agent/_engine/config-loader.ts", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("../src/commands/managed-agent/_engine/config-loader.ts")>();
+  return { ...actual, ...configLoaderMocks };
+});
+
+import destroyCommand from "../src/commands/managed-agent/destroy.ts";
+
+const resources = [
+  {
+    address: { provider: "bailian", type: "agent", name: "assistant" },
+    remote_id: "agent-ok",
+  },
+  {
+    address: { provider: "bailian", type: "environment", name: "dev" },
+    remote_id: "env-failed",
+  },
+];
+
+let stdoutChunks: string[] = [];
+let originalStdoutWrite: typeof process.stdout.write;
+let originalStderrWrite: typeof process.stderr.write;
+
+beforeEach(() => {
+  stdoutChunks = [];
+  originalStdoutWrite = process.stdout.write.bind(process.stdout);
+  originalStderrWrite = process.stderr.write.bind(process.stderr);
+  process.stdout.write = ((chunk: string | Uint8Array) => {
+    stdoutChunks.push(String(chunk));
+    return true;
+  }) as typeof process.stdout.write;
+  process.stderr.write = (() => true) as typeof process.stderr.write;
+
+  const planned = { resources, executionContext: {} };
+  configLoaderMocks.buildAgentRuntime.mockResolvedValue({});
+  sdkMocks.planDestroyProjectContext.mockReturnValue(planned);
+  sdkMocks.destroyPlannedProjectResources.mockResolvedValue({
+    ...planned,
+    results: [
+      { resource: resources[0], status: "success", reason: "destroyed" },
+      {
+        resource: resources[1],
+        status: "failed",
+        reason: "failed",
+        error: "provider refused deletion",
+      },
+    ],
+    destroyed: 1,
+    partial: true,
+  });
+});
+
+afterEach(() => {
+  process.stdout.write = originalStdoutWrite;
+  process.stderr.write = originalStderrWrite;
+  vi.clearAllMocks();
+});
+
+test("destroy 部分失败时输出汇总并以首个原始错误抛 GENERAL", async () => {
+  let thrown: unknown;
+  try {
+    await destroyCommand.run({
+      settings: { output: "json", dryRun: false },
+      flags: { yes: true },
+    } as never);
+  } catch (error) {
+    thrown = error;
+  }
+
+  expect(thrown).toBeInstanceOf(BailianError);
+  const mapped = thrown as BailianError;
+  expect(mapped.exitCode).toBe(ExitCode.GENERAL);
+  expect(mapped.message).toBe("provider refused deletion");
+  expect(JSON.parse(stdoutChunks.join(""))).toEqual({ destroyed: 1, total: 2 });
+});
@@ -219,7 +219,6 @@ describe("e2e: auth", () => {
        body: {
          model: "qwen3.7-max",
          stream: false,
-          enable_thinking: false,
        },
      });

@@ -267,8 +266,11 @@ describe("e2e: auth", () => {
      expect(config["token-plan"]).toMatchObject({
        api_key: "sk-sp-e2e-placeholder",
        base_url: validationServer.baseUrl,
-        default_text_model: "qwen3.7-max",
-        default_image_model: "qwen-image-2.0",
+        default_text_model: "qwen3.8-max-preview",
+        default_video_model: "happyhorse-1.1-t2v",
+        default_image_to_video_model: "happyhorse-1.1-i2v",
+        default_reference_to_video_model: "happyhorse-1.1-r2v",
+        default_image_model: "wan2.7-image",
      });
    } finally {
      await validationServer.close();
@@ -284,6 +286,9 @@ describe("e2e: auth", () => {
        {
          "token-plan": {
            default_text_model: "custom-text-model",
+            default_video_model: "custom-video-model",
+            default_image_to_video_model: "custom-image-to-video-model",
+            default_reference_to_video_model: "custom-reference-to-video-model",
            default_image_model: "custom-image-model",
          },
        },
@@ -311,7 +316,6 @@ describe("e2e: auth", () => {
        body: {
          model: "qwen3.7-max",
          stream: false,
-          enable_thinking: false,
        },
      });

@@ -324,8 +328,11 @@ describe("e2e: auth", () => {
      expect(config["token-plan"]).toMatchObject({
        api_key: "sk-sp-e2e-placeholder",
        base_url: "https://token-plan.cn-beijing.maas.aliyuncs.com",
-        default_text_model: "qwen3.7-max",
-        default_image_model: "qwen-image-2.0",
+        default_text_model: "qwen3.8-max-preview",
+        default_video_model: "happyhorse-1.1-t2v",
+        default_image_to_video_model: "happyhorse-1.1-i2v",
+        default_reference_to_video_model: "happyhorse-1.1-r2v",
+        default_image_model: "wan2.7-image",
      });
      expect((config["token-plan"] as Record<string, unknown>).base_url).not.toBe(
        validationServer.baseUrl,
@@ -478,6 +485,38 @@ describe("e2e: auth", () => {
    expect(stderr).not.toContain("Cleared api_key");
  });

+  test("auth logout 清除当前 Config 的全部凭证和 Base URL，保留普通配置", async () => {
+    const configDir = makeE2eOutputDir("auth-logout-all");
+    writeFileSync(
+      join(configDir, "config.json"),
+      JSON.stringify(
+        {
+          api_key: "sk-e2e-placeholder",
+          base_url: "https://model.example.com",
+          access_token: "console-token-placeholder",
+          access_key_id: "LTAI-e2e-placeholder",
+          access_key_secret: "secret-e2e-placeholder",
+          security_token: "sts-e2e-placeholder",
+          output: "json",
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+
+    const { stderr, exitCode } = await runCommandE2e(AUTH_ROUTES, ["auth", "logout"], {
+      BAILIAN_CONFIG_DIR: configDir,
+    });
+    expect(exitCode, stderr).toBe(0);
+    expect(stderr).toContain("api_key / base_url / access_token");
+
+    const config = JSON.parse(readFileSync(join(configDir, "config.json"), "utf8")) as Record<
+      string,
+      unknown
+    >;
+    expect(config).toEqual({ output: "json" });
+  });
+
  test.skipIf(!isDashScopeE2EReady())("auth status 文本输出", async () => {
    const { stdout, stderr, exitCode } = await runCommandE2e(AUTH_ROUTES, [
      "auth",
@@ -1,4 +1,4 @@
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync, existsSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
 import { describe, expect, test } from "vite-plus/test";
@@ -247,10 +247,10 @@ describe("e2e: config", () => {
      );
      expect(setResult.exitCode, setResult.stderr).toBe(0);
      expect(parseStdoutJson<{ base_url?: string }>(setResult.stdout).base_url).toBe(
-        "https://proxy.example.com/bailian",
+        "https://proxy.example.com",
      );
      expect(JSON.parse(readFileSync(join(configDir, "config.json"), "utf8")).base_url).toBe(
-        "https://proxy.example.com/bailian",
+        "https://proxy.example.com",
      );

      const invalidResult = await runCommandE2e(
@@ -295,10 +295,50 @@ describe("e2e: config", () => {
      "json",
    ]);
    expect(exitCode, stderr).toBe(0);
-    const data = parseStdoutJson<{ would_set?: { default_text_model?: string } }>(stdout);
+    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 支持图生视频默认模型别名", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(CONFIG_ROUTES, [
+      "config",
+      "set",
+      "--dry-run",
+      "--key",
+      "default-image-to-video-model",
+      "--value",
+      "happyhorse-1.1-i2v",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{
+      would_set?: { default_image_to_video_model?: string };
+    }>(stdout);
+    expect(data.would_set?.default_image_to_video_model).toBe("happyhorse-1.1-i2v");
+  });
+
+  test("config set --dry-run 支持参考生视频默认模型别名", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(CONFIG_ROUTES, [
+      "config",
+      "set",
+      "--dry-run",
+      "--key",
+      "default-reference-to-video-model",
+      "--value",
+      "happyhorse-1.1-r2v",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{
+      would_set?: { default_reference_to_video_model?: string };
+    }>(stdout);
+    expect(data.would_set?.default_reference_to_video_model).toBe("happyhorse-1.1-r2v");
+  });
+
  test("config set --dry-run 展示归一化后的 Base URL", async () => {
    const { stdout, stderr, exitCode } = await runCommandE2e(CONFIG_ROUTES, [
      "config",
@@ -345,4 +385,285 @@ describe("e2e: config", () => {
    expect(exitCode).toBe(2);
    expect(stderr).toMatch(/Invalid config key|openapi_access_key_id/);
  });
+
+  test("config agent --help 正常退出", async () => {
+    const { stderr, exitCode } = await runCommandE2e(CONFIG_ROUTES, ["config", "agent", "--help"]);
+    expect(exitCode, stderr).toBe(0);
+    expect(stderr).toMatch(/agent|--base-url|--model/i);
+  });
+
+  test("config agent 缺少 --api-key/--key 时报用法错误并退出 (2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(CONFIG_ROUTES, [
+      "config",
+      "agent",
+      "--agent",
+      "claude-code",
+      "--base-url",
+      "https://dashscope.aliyuncs.com/apps/anthropic",
+      "--model",
+      "qwen3-max",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/--api-key|--key|Usage:/i);
+  });
+
+  test("config agent --api-key 与 --key 同传时报用法错误 (2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(CONFIG_ROUTES, [
+      "config",
+      "agent",
+      "--agent",
+      "claude-code",
+      "--base-url",
+      "https://dashscope.aliyuncs.com/apps/anthropic",
+      "--api-key",
+      "sk-placeholder",
+      "--key",
+      "o1_AbC123kaQ9JHCXF2GepMW4oJTD7ODPw_Hx",
+      "--model",
+      "qwen3-max",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/mutually exclusive|--api-key/i);
+  });
+
+  test("config agent --key 非法值时报用法错误 (2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(CONFIG_ROUTES, [
+      "config",
+      "agent",
+      "--agent",
+      "claude-code",
+      "--base-url",
+      "https://dashscope.aliyuncs.com/apps/anthropic",
+      "--key",
+      "not-an-encoded-key",
+      "--model",
+      "qwen3-max",
+      "--dry-run",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/Invalid obfuscated API key|o1_/i);
+  });
+
+  test("config agent --key 合法值 --dry-run 解码成功且输出脱敏", async () => {
+    const home = mkdtempSync(join(tmpdir(), "bl-config-agent-key-"));
+    try {
+      const { stdout, stderr, exitCode } = await runCommandE2e(
+        CONFIG_ROUTES,
+        [
+          "config",
+          "agent",
+          "--agent",
+          "claude-code",
+          "--base-url",
+          "https://dashscope.aliyuncs.com/apps/anthropic",
+          "--key",
+          // encode("sk-e2e-key-placeholder", salt "AbC123") 的固定产物
+          "o1_AbC123kaQ9JHCXF2GepMW4oJTD7ODPw_Hx",
+          "--model",
+          "qwen3-max",
+          "--dry-run",
+          "--output",
+          "json",
+        ],
+        { HOME: home },
+      );
+      expect(exitCode, stderr).toBe(0);
+      const data = parseStdoutJson<{ agent?: string; api_key?: string }>(stdout);
+      expect(data.agent).toBe("claude-code");
+      // 解码后的真实 key 不得明文出现，且脱敏值非空
+      expect(stdout).not.toContain("sk-e2e-key-placeholder");
+      expect(data.api_key).toBeTruthy();
+      expect(existsSync(join(home, ".claude", "settings.json"))).toBe(false);
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+
+  test("config agent --region 转为 base URL，--dry-run 成功", async () => {
+    const home = mkdtempSync(join(tmpdir(), "bl-config-agent-region-"));
+    try {
+      const { stdout, stderr, exitCode } = await runCommandE2e(
+        CONFIG_ROUTES,
+        [
+          "config",
+          "agent",
+          "--agent",
+          "qwen-code",
+          "--region",
+          "cn-beijing",
+          "--api-key",
+          "sk-region-placeholder",
+          "--model",
+          "qwen3.8-max-preview",
+          "--dry-run",
+          "--output",
+          "json",
+        ],
+        { HOME: home },
+      );
+      expect(exitCode, stderr).toBe(0);
+      const data = parseStdoutJson<{ agent?: string; base_url?: string }>(stdout);
+      expect(data.agent).toBe("qwen-code");
+      expect(data.base_url).toBe(
+        "https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
+      );
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+
+  test("config agent --base-url 与 --region 同传时报用法错误 (2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(CONFIG_ROUTES, [
+      "config",
+      "agent",
+      "--agent",
+      "qwen-code",
+      "--base-url",
+      "https://dashscope.aliyuncs.com/compatible-mode/v1",
+      "--region",
+      "cn-beijing",
+      "--api-key",
+      "sk-placeholder",
+      "--model",
+      "qwen3-coder-plus",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/mutually exclusive|--base-url|--region/i);
+  });
+
+  test("config agent 既缺 --base-url 又缺 --region 时报用法错误 (2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(CONFIG_ROUTES, [
+      "config",
+      "agent",
+      "--agent",
+      "qwen-code",
+      "--api-key",
+      "sk-placeholder",
+      "--model",
+      "qwen3-coder-plus",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/--base-url|--region|Usage:/i);
+  });
+
+  test("config agent 非法 --agent 时退出为用法错误 (2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(CONFIG_ROUTES, [
+      "config",
+      "agent",
+      "--agent",
+      "not-an-agent",
+      "--base-url",
+      "https://dashscope.aliyuncs.com/compatible-mode/v1",
+      "--api-key",
+      "sk-placeholder",
+      "--model",
+      "qwen3-max",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/not-an-agent|claude-code|agent/i);
+  });
+
+  test("config agent --dry-run 输出脱敏信息且不写盘", async () => {
+    const home = mkdtempSync(join(tmpdir(), "bl-config-agent-dry-"));
+    try {
+      const { stdout, stderr, exitCode } = await runCommandE2e(
+        CONFIG_ROUTES,
+        [
+          "config",
+          "agent",
+          "--agent",
+          "claude-code",
+          "--base-url",
+          "https://dashscope.aliyuncs.com/apps/anthropic",
+          "--api-key",
+          "sk-secret-placeholder",
+          "--model",
+          "qwen3-max",
+          "--dry-run",
+          "--output",
+          "json",
+        ],
+        { HOME: home },
+      );
+      expect(exitCode, stderr).toBe(0);
+      const data = parseStdoutJson<{
+        agent?: string;
+        base_url?: string;
+        model?: string;
+        api_key?: string;
+      }>(stdout);
+      expect(data.agent).toBe("claude-code");
+      expect(data.base_url).toBe("https://dashscope.aliyuncs.com/apps/anthropic");
+      expect(data.model).toBe("qwen3-max");
+      expect(stdout).not.toContain("sk-secret-placeholder");
+      expect(existsSync(join(home, ".claude", "settings.json"))).toBe(false);
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+
+  test("config agent codex 写入 config.toml 与 auth.json（官方 env_key 结构）", async () => {
+    const home = mkdtempSync(join(tmpdir(), "bl-config-agent-codex-"));
+    try {
+      const { stderr, exitCode } = await runCommandE2e(
+        CONFIG_ROUTES,
+        [
+          "config",
+          "agent",
+          "--agent",
+          "codex",
+          "--base-url",
+          "https://dashscope.aliyuncs.com/compatible-mode/v1",
+          "--api-key",
+          "sk-codex-placeholder",
+          "--model",
+          "qwen3-coder-plus",
+        ],
+        { HOME: home },
+      );
+      expect(exitCode, stderr).toBe(0);
+      const toml = readFileSync(join(home, ".codex", "config.toml"), "utf8");
+      expect(toml).toContain('model_provider = "bailian-cli"');
+      expect(toml).toContain('env_key = "OPENAI_API_KEY"');
+      expect(toml).toContain("requires_openai_auth = true");
+      // 默认即 responses（新版 Codex 已不支持 chat）
+      expect(toml).toContain('wire_api = "responses"');
+      const auth = JSON.parse(readFileSync(join(home, ".codex", "auth.json"), "utf8"));
+      expect(auth.OPENAI_API_KEY).toBe("sk-codex-placeholder");
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+
+  test("config agent hermes 写入官方扁平 model.* 结构", async () => {
+    const home = mkdtempSync(join(tmpdir(), "bl-config-agent-hermes-"));
+    try {
+      const { stderr, exitCode } = await runCommandE2e(
+        CONFIG_ROUTES,
+        [
+          "config",
+          "agent",
+          "--agent",
+          "hermes",
+          "--base-url",
+          "https://dashscope.aliyuncs.com/compatible-mode/v1",
+          "--api-key",
+          "sk-hermes-placeholder",
+          "--model",
+          "qwen3-coder-plus",
+        ],
+        { HOME: home },
+      );
+      expect(exitCode, stderr).toBe(0);
+      const yamlText = readFileSync(join(home, ".hermes", "config.yaml"), "utf8");
+      expect(yamlText).toContain("default: qwen3-coder-plus");
+      expect(yamlText).toContain("provider: custom");
+      expect(yamlText).toContain("base_url: https://dashscope.aliyuncs.com/compatible-mode/v1");
+      expect(yamlText).toContain("api_key: sk-hermes-placeholder");
+      // OpenAI 兼容端点不写 api_mode
+      expect(yamlText).not.toContain("api_mode");
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
 });
@@ -0,0 +1,7 @@
+version: "1"
+
+providers:
+  bailian:
+    api_key: ${DASHSCOPE_API_KEY}
+
+agents: "not-a-map"
@@ -0,0 +1,28 @@
+version: "1"
+
+providers:
+  bailian:
+    api_key: ${DASHSCOPE_API_KEY}
+    base_url: ${BAILIAN_BASE_URL}
+  claude:
+    api_key: ${ANTHROPIC_API_KEY}
+
+defaults:
+  provider: all
+
+environments:
+  dev:
+    config:
+      type: cloud
+      networking:
+        type: unrestricted
+
+agents:
+  assistant:
+    description: "E2E multi-provider fixture"
+    model:
+      bailian: qwen3.7-max
+      claude: claude-sonnet-4-6
+    instructions: |
+      You are a helpful assistant.
+    environment: dev
@@ -0,0 +1,24 @@
+version: "1"
+
+providers:
+  bailian:
+    api_key: ${DASHSCOPE_API_KEY}
+    base_url: ${BAILIAN_BASE_URL}
+
+defaults:
+  provider: bailian
+
+environments:
+  dev:
+    config:
+      type: cloud
+      networking:
+        type: unrestricted
+
+agents:
+  assistant:
+    description: "E2E auth-chain fixture"
+    model: qwen3.7-max
+    instructions: |
+      You are a helpful assistant.
+    environment: dev
@@ -1,5 +1,6 @@
 import { describe, expect, test } from "vite-plus/test";
-import { join } from "path";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
 import {
  e2eFixturesDir,
  e2eLabelFromMetaUrl,
@@ -46,6 +47,127 @@ describe("e2e: image edit", () => {
    expect(data.mode).toBe("async");
    expect(data.request?.input?.messages?.length).toBeGreaterThan(0);
  });
+
+  test("Token Plan 使用 Base64 传入 wan2.7-image 本地图片", async () => {
+    const configDir = makeE2eOutputDir("image-edit-token-plan-local-image");
+    writeFileSync(
+      join(configDir, "config.json"),
+      JSON.stringify({
+        "token-plan": {
+          api_key: "sk-sp-e2e-placeholder",
+          base_url: "https://token-plan.cn-beijing.maas.aliyuncs.com",
+          default_image_model: "wan2.7-image",
+        },
+      }),
+    );
+
+    const { stdout, stderr, exitCode } = await runCommandE2e(
+      IMAGE_ROUTES,
+      [
+        "image",
+        "edit",
+        "--config",
+        "token-plan",
+        "--image",
+        join(e2eFixturesDir, ".smoke-32.png"),
+        "--prompt",
+        "改成蓝色",
+        "--dry-run",
+        "--output",
+        "json",
+      ],
+      {
+        BAILIAN_CONFIG_DIR: configDir,
+        DASHSCOPE_API_KEY: "",
+        DASHSCOPE_BASE_URL: "",
+      },
+    );
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{
+      mode?: string;
+      request?: {
+        model?: string;
+        input?: { messages?: Array<{ content?: Array<{ image?: string }> }> };
+      };
+    }>(stdout);
+    expect(data.mode).toBe("sync");
+    expect(data.request?.model).toBe("wan2.7-image");
+    expect(data.request?.input?.messages?.[0]?.content?.[0]?.image).toBe(
+      "data:image/png;base64,<omitted>",
+    );
+  });
+
+  test("wan2.5-i2i-preview dry-run 走 prompt+images", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(IMAGE_ROUTES, [
+      "image",
+      "edit",
+      "--model",
+      "wan2.5-i2i-preview",
+      "--image",
+      "https://example.com/source.png",
+      "--prompt",
+      "Place on a table",
+      "--size",
+      "1:1",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{
+      mode?: string;
+      path?: string;
+      request?: {
+        input?: { prompt?: string; images?: string[]; messages?: unknown };
+        parameters?: { size?: string };
+      };
+    }>(stdout);
+    expect(data.mode).toBe("async");
+    expect(data.path).toBe("/api/v1/services/aigc/image2image/image-synthesis");
+    expect(data.request?.input?.prompt).toBe("Place on a table");
+    expect(data.request?.input?.images).toEqual(["https://example.com/source.png"]);
+    expect(data.request?.input?.messages).toBeUndefined();
+    expect(data.request?.parameters?.size).toBe("1280*1280");
+  });
+
+  test("wanx2.1-imageedit dry-run 走 function + base_image_url", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(IMAGE_ROUTES, [
+      "image",
+      "edit",
+      "--model",
+      "wanx2.1-imageedit",
+      "--image",
+      "https://example.com/source.png",
+      "--prompt",
+      "转换成绘本风格",
+      "--function",
+      "stylization_all",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{
+      mode?: string;
+      path?: string;
+      request?: {
+        input?: {
+          function?: string;
+          prompt?: string;
+          base_image_url?: string;
+          images?: unknown;
+          messages?: unknown;
+        };
+      };
+    }>(stdout);
+    expect(data.mode).toBe("async");
+    expect(data.path).toBe("/api/v1/services/aigc/image2image/image-synthesis");
+    expect(data.request?.input?.function).toBe("stylization_all");
+    expect(data.request?.input?.prompt).toBe("转换成绘本风格");
+    expect(data.request?.input?.base_image_url).toBe("https://example.com/source.png");
+    expect(data.request?.input?.images).toBeUndefined();
+    expect(data.request?.input?.messages).toBeUndefined();
+  });
 });

 describe.skipIf(!isBailianE2EMediaEnabled() || !isDashScopeE2EReady())("e2e: image edit", () => {
@@ -1,4 +1,6 @@
 import { describe, expect, test } from "vite-plus/test";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
 import {
  e2eLabelFromMetaUrl,
  isBailianE2EMediaEnabled,
@@ -21,6 +23,175 @@ describe("e2e: image generate", () => {
    expect(exitCode, stderr).toBe(0);
    expect(stderr).toMatch(/generate|--prompt|--model/i);
  });
+
+  test("Token Plan 默认使用 wan2.7-image 同步接口", async () => {
+    const configDir = makeE2eOutputDir("image-generate-token-plan-default");
+    writeFileSync(
+      join(configDir, "config.json"),
+      JSON.stringify({
+        "token-plan": {
+          api_key: "sk-sp-e2e-placeholder",
+          base_url: "https://token-plan.cn-beijing.maas.aliyuncs.com",
+          default_image_model: "wan2.7-image",
+        },
+      }),
+    );
+
+    const { stdout, stderr, exitCode } = await runCommandE2e(
+      IMAGE_ROUTES,
+      [
+        "image",
+        "generate",
+        "--config",
+        "token-plan",
+        "--prompt",
+        "一只猫",
+        "--dry-run",
+        "--output",
+        "json",
+      ],
+      {
+        BAILIAN_CONFIG_DIR: configDir,
+        DASHSCOPE_API_KEY: "",
+        DASHSCOPE_BASE_URL: "",
+      },
+    );
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ mode?: string; request?: { model?: string } }>(stdout);
+    expect(data.mode).toBe("sync");
+    expect(data.request?.model).toBe("wan2.7-image");
+  });
+
+  test("z-image-turbo dry-run 走 sync multimodal", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(IMAGE_ROUTES, [
+      "image",
+      "generate",
+      "--model",
+      "z-image-turbo",
+      "--prompt",
+      "一只猫",
+      "--size",
+      "1024*1024",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ mode?: string; request?: { model?: string } }>(stdout);
+    expect(data.mode).toBe("sync");
+    expect(data.request?.model).toBe("z-image-turbo");
+  });
+
+  test("qwen-image-plus dry-run 走 sync multimodal", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(IMAGE_ROUTES, [
+      "image",
+      "generate",
+      "--model",
+      "qwen-image-plus",
+      "--prompt",
+      "一只猫",
+      "--size",
+      "1328*1328",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{
+      mode?: string;
+      path?: string;
+      request?: { model?: string };
+    }>(stdout);
+    expect(data.mode).toBe("sync");
+    expect(data.path).toBe("/api/v1/services/aigc/multimodal-generation/generation");
+    expect(data.request?.model).toBe("qwen-image-plus");
+  });
+
+  test("qwen-image-plus 默认 1:1 映射为 1328*1328", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(IMAGE_ROUTES, [
+      "image",
+      "generate",
+      "--model",
+      "qwen-image-plus",
+      "--prompt",
+      "一只猫",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{
+      request?: { parameters?: { size?: string; prompt_extend?: boolean } };
+    }>(stdout);
+    expect(data.request?.parameters?.size).toBe("1328*1328");
+  });
+
+  test("z-image-turbo 默认 prompt_extend 为 false", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(IMAGE_ROUTES, [
+      "image",
+      "generate",
+      "--model",
+      "z-image-turbo",
+      "--prompt",
+      "一只猫",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{
+      request?: { parameters?: { size?: string; prompt_extend?: boolean } };
+    }>(stdout);
+    expect(data.request?.parameters?.prompt_extend).toBe(false);
+    expect(data.request?.parameters?.size).toBe("1024*1024");
+  });
+
+  test("wanx-v1 默认 1:1 映射为 1024*1024", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(IMAGE_ROUTES, [
+      "image",
+      "generate",
+      "--model",
+      "wanx-v1",
+      "--prompt",
+      "一只猫",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{
+      request?: { parameters?: { size?: string }; input?: { prompt?: string } };
+    }>(stdout);
+    expect(data.request?.parameters?.size).toBe("1024*1024");
+    expect(data.request?.input?.prompt).toBe("一只猫");
+  });
+
+  test("wanx2.0-t2i-turbo dry-run 走 text2image prompt 路径", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(IMAGE_ROUTES, [
+      "image",
+      "generate",
+      "--model",
+      "wanx2.0-t2i-turbo",
+      "--prompt",
+      "一只猫",
+      "--size",
+      "1024*1024",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{
+      mode?: string;
+      path?: string;
+      request?: { model?: string; input?: { prompt?: string; messages?: unknown } };
+    }>(stdout);
+    expect(data.mode).toBe("async");
+    expect(data.path).toBe("/api/v1/services/aigc/text2image/image-synthesis");
+    expect(data.request?.model).toBe("wanx2.0-t2i-turbo");
+    expect(data.request?.input?.prompt).toBe("一只猫");
+    expect(data.request?.input?.messages).toBeUndefined();
+  });
 });

 describe.skipIf(!isBailianE2EMediaEnabled() || !isDashScopeE2EReady())(
@@ -0,0 +1,298 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, test } from "vite-plus/test";
+import { e2eFixturesDir, parseStdoutJson, runCommandE2e } from "./helpers.ts";
+import { MANAGED_AGENT_ROUTES } from "./topic-routes.ts";
+
+/**
+ * managed-agent 凭证链 e2e：验证 bl 自有配置体系（config 写入 / 命名 Profile /
+ * logout）与错误映射如何流入 SDK 引擎。全部离线：凭证门禁用 `managed-agent plan`
+ * 验证（空 state 不发网络请求，但 auth: "apiKey" 硬门禁 + 引擎全量 provider key
+ * 断言照常生效）；`validate` / `state list` 属离线命令，无凭证也必须可用。
+ * 配置一律通过 BAILIAN_CONFIG_DIR 指向临时目录，绝不触碰真实用户配置。
+ */
+
+const ROUTES = {
+  ...MANAGED_AGENT_ROUTES,
+  "auth logout": "authLogout",
+};
+
+const AGENTS_YAML = join(e2eFixturesDir, "managed-agent", "agents.yaml");
+const AGENTS_YAML_INVALID = join(e2eFixturesDir, "managed-agent", "agents-invalid.yaml");
+const AGENTS_YAML_MULTI = join(e2eFixturesDir, "managed-agent", "agents-multi.yaml");
+
+const tempDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+/** 新建隔离配置目录并写入 config.json；返回子进程 env 覆盖（清空外部凭证 env）。 */
+function makeConfigEnv(config: Record<string, unknown>): NodeJS.ProcessEnv {
+  const configDir = mkdtempSync(join(tmpdir(), "bl-managed-agent-auth-"));
+  tempDirs.push(configDir);
+  writeFileSync(join(configDir, "config.json"), `${JSON.stringify(config, null, 2)}\n`);
+  return {
+    BAILIAN_CONFIG_DIR: configDir,
+    DASHSCOPE_API_KEY: "",
+    DASHSCOPE_BASE_URL: "",
+    BAILIAN_BASE_URL: "",
+    BAILIAN_WORKSPACE_ID: "",
+  };
+}
+
+function validateArgs(file: string): string[] {
+  return ["managed-agent", "validate", "--file", file, "--quiet"];
+}
+
+/** plan 是凭证门禁命令：空 state 下不发网络，但 authStage + 引擎断言照常生效。 */
+function planArgs(file: string): string[] {
+  return ["managed-agent", "plan", "--file", file, "--quiet"];
+}
+
+/** 隔离宿主机的 ~/.agents/config.json，避免它强制覆盖 provider 凭证 env。 */
+function isolatedAgentsConfigEnv(): NodeJS.ProcessEnv {
+  return { AGENTS_CONFIG_PATH: join(tmpdir(), "bl-e2e-no-agents-config.json") };
+}
+
+/**
+ * 在临时目录里搭一套非空 state 的项目：agents.yaml 复用单 provider fixture，
+ * agents.state.json 预置一条已追踪资源 —— 非空 state 是触发 plan 默认 refresh
+ * 路径的前提，用于验证 --dry-run 强制离线。目录纳入 tempDirs 自动清理。
+ */
+function makeStatefulProject(): { configPath: string; statePath: string } {
+  const dir = mkdtempSync(join(tmpdir(), "bl-managed-agent-dry-run-"));
+  tempDirs.push(dir);
+  const configPath = join(dir, "agents.yaml");
+  const statePath = join(dir, "agents.state.json");
+  writeFileSync(configPath, readFileSync(AGENTS_YAML, "utf8"));
+  writeFileSync(
+    statePath,
+    `${JSON.stringify(
+      {
+        resources: [
+          {
+            address: { provider: "bailian", type: "agent", name: "assistant" },
+            remote_id: "agent-e2e-dry-run",
+          },
+        ],
+      },
+      null,
+      2,
+    )}\n`,
+  );
+  return { configPath, statePath };
+}
+
+/** 分配一个刚释放的本地端口，连接必然 ECONNREFUSED，用于网络错误场景。 */
+async function closedPort(): Promise<number> {
+  const server = createServer();
+  try {
+    await new Promise<void>((resolveListen) => server.listen(0, "127.0.0.1", resolveListen));
+    const address = server.address();
+    if (!address || typeof address === "string") {
+      throw new Error("failed to allocate a closed port");
+    }
+    return address.port;
+  } finally {
+    await new Promise<void>((resolveClose) => server.close(() => resolveClose()));
+  }
+}
+
+describe("e2e: managed-agent 凭证链（config 写入 / Profile / logout / 错误映射）", () => {
+  test("config.json 写入的 api_key 流入引擎，plan 离线通过", async () => {
+    const env = makeConfigEnv({ api_key: "sk-e2e-config-write" });
+    const { stderr, exitCode } = await runCommandE2e(ROUTES, planArgs(AGENTS_YAML), env);
+    expect(exitCode, stderr).toBe(0);
+  });
+
+  test("active_config 指向的命名 Profile 提供凭证时通过", async () => {
+    const env = makeConfigEnv({
+      work: { api_key: "sk-e2e-profile-work" },
+      active_config: "work",
+    });
+    const { stderr, exitCode } = await runCommandE2e(ROUTES, planArgs(AGENTS_YAML), env);
+    expect(exitCode, stderr).toBe(0);
+  });
+
+  test("active_config 切到无凭证 Profile 时报统一 AUTH 错误 (3)", async () => {
+    const env = makeConfigEnv({
+      work: { api_key: "sk-e2e-profile-work" },
+      empty: {},
+      active_config: "empty",
+    });
+    const { stderr, exitCode } = await runCommandE2e(ROUTES, planArgs(AGENTS_YAML), env);
+    expect(exitCode).toBe(3);
+    expect(stderr).toMatch(/auth login|API key/i);
+  });
+
+  test("auth logout 清除凭证后 plan 报 AUTH，而非用残留凭证", async () => {
+    const env = makeConfigEnv({ api_key: "sk-e2e-before-logout" });
+
+    const before = await runCommandE2e(ROUTES, planArgs(AGENTS_YAML), env);
+    expect(before.exitCode, before.stderr).toBe(0);
+
+    const logout = await runCommandE2e(ROUTES, ["auth", "logout"], env);
+    expect(logout.exitCode, logout.stderr).toBe(0);
+
+    const after = await runCommandE2e(ROUTES, planArgs(AGENTS_YAML), env);
+    expect(after.exitCode).toBe(3);
+    expect(after.stderr).toMatch(/auth login|API key/i);
+  });
+
+  test("agents.yaml schema 错误映射为 USAGE (2)，不透传原始 zod dump", async () => {
+    const env = makeConfigEnv({});
+    const { stderr, exitCode } = await runCommandE2e(
+      ROUTES,
+      validateArgs(AGENTS_YAML_INVALID),
+      env,
+    );
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/agents/i);
+    expect(stderr).not.toMatch(/"code":\s*"invalid_type"/);
+  });
+
+  test("validate --output json 成功路径 stdout 为单个合法 JSON", async () => {
+    const env = makeConfigEnv({ api_key: "sk-e2e-config-write" });
+    const { stdout, stderr, exitCode } = await runCommandE2e(
+      ROUTES,
+      ["managed-agent", "validate", "--file", AGENTS_YAML, "--output", "json"],
+      env,
+    );
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ valid?: boolean; diagnostics?: unknown[] }>(stdout);
+    expect(data.valid).toBe(true);
+    expect(Array.isArray(data.diagnostics)).toBe(true);
+  });
+
+  test("SDK fetch 连不上时映射为 NETWORK (6) + errno hint，不降级成 GENERAL", async () => {
+    const port = await closedPort();
+    const env = makeConfigEnv({
+      api_key: "sk-e2e-network",
+      base_url: `http://127.0.0.1:${port}`,
+    });
+    const { stderr, exitCode } = await runCommandE2e(
+      ROUTES,
+      ["managed-agent", "session", "get", "--session-id", "sess_net", "--file", AGENTS_YAML],
+      env,
+    );
+    expect(exitCode).toBe(6);
+    expect(stderr).toMatch(/Network request failed/i);
+    expect(stderr).toMatch(/ECONNREFUSED|refused/i);
+  });
+});
+
+describe("e2e: managed-agent 鉴权分层（离线命令免登录 / 联网命令统一 apiKey 门禁）", () => {
+  test("validate 无任何凭证也离线通过 (0)", async () => {
+    const env = makeConfigEnv({});
+    const { stderr, exitCode } = await runCommandE2e(ROUTES, validateArgs(AGENTS_YAML), env);
+    expect(exitCode, stderr).toBe(0);
+  });
+
+  test("state list 无任何凭证也离线通过 (0)，stdout 为合法 JSON", async () => {
+    const env = makeConfigEnv({});
+    const { stdout, stderr, exitCode } = await runCommandE2e(
+      ROUTES,
+      ["managed-agent", "state", "list", "--file", AGENTS_YAML, "--output", "json"],
+      env,
+    );
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ resources?: unknown[] }>(stdout);
+    expect(Array.isArray(data.resources)).toBe(true);
+  });
+
+  test("plan --no-refresh 无登录时仍被 apiKey 硬门禁拦住 (3)", async () => {
+    const env = makeConfigEnv({});
+    const { stderr, exitCode } = await runCommandE2e(
+      ROUTES,
+      [...planArgs(AGENTS_YAML), "--no-refresh"],
+      env,
+    );
+    expect(exitCode).toBe(3);
+    expect(stderr).toMatch(/auth login|API key/i);
+  });
+
+  test("已登录 bailian 时，多 provider 配置下 plan --no-refresh 离线通过，不查其他 provider key (0)", async () => {
+    const env = {
+      ...makeConfigEnv({ api_key: "sk-e2e-no-refresh" }),
+      ...isolatedAgentsConfigEnv(),
+      ANTHROPIC_API_KEY: "",
+      CLAUDE_API_KEY: "",
+    };
+    const { stderr, exitCode } = await runCommandE2e(
+      ROUTES,
+      [...planArgs(AGENTS_YAML_MULTI), "--no-refresh"],
+      env,
+    );
+    expect(exitCode, stderr).toBe(0);
+  });
+
+  test("统一登录门禁：只配 claude key 未登录 bailian 时，plan --provider claude 仍报 AUTH (3)", async () => {
+    const env = {
+      ...makeConfigEnv({}),
+      ...isolatedAgentsConfigEnv(),
+      ANTHROPIC_API_KEY: "sk-ant-e2e-scope",
+      CLAUDE_API_KEY: "",
+    };
+    const { stderr, exitCode } = await runCommandE2e(
+      ROUTES,
+      [...planArgs(AGENTS_YAML_MULTI), "--provider", "claude"],
+      env,
+    );
+    expect(exitCode).toBe(3);
+    expect(stderr).toMatch(/auth login|API key/i);
+  });
+
+  test("已登录但缺 claude key 时，全量断言拦住并给 ANTHROPIC_API_KEY hint (3)", async () => {
+    const env = {
+      ...makeConfigEnv({ api_key: "sk-e2e-bailian-present" }),
+      ...isolatedAgentsConfigEnv(),
+      ANTHROPIC_API_KEY: "",
+      CLAUDE_API_KEY: "",
+    };
+    const { stderr, exitCode } = await runCommandE2e(
+      ROUTES,
+      [...planArgs(AGENTS_YAML_MULTI), "--provider", "claude"],
+      env,
+    );
+    expect(exitCode).toBe(3);
+    expect(stderr).toMatch(/ANTHROPIC_API_KEY/);
+  });
+});
+
+describe("e2e: plan --dry-run 离线契约（不联网 / 不写 state / 免凭证）", () => {
+  test("无任何凭证时 plan --dry-run 不报 AUTH，离线出 plan (0)", async () => {
+    const env = makeConfigEnv({});
+    const { stderr, exitCode } = await runCommandE2e(
+      ROUTES,
+      [...planArgs(AGENTS_YAML), "--dry-run"],
+      env,
+    );
+    expect(exitCode, stderr).toBe(0);
+  });
+
+  test("有凭证且 state 非空时，--dry-run 跳过 refresh：不发请求、state 文件不变；同环境不加 --dry-run 则证明会联网", async () => {
+    const { configPath, statePath } = makeStatefulProject();
+    // base_url 指向必然 ECONNREFUSED 的本地端口：一旦 refresh 真发请求必现形。
+    // refresh 对 API 错误优雅降级(不影响退出码)，因此用 stderr 的
+    // "Failed to refresh" 告警作为「发过请求」的观测信号。
+    const port = await closedPort();
+    const env = makeConfigEnv({
+      api_key: "sk-e2e-dry-run",
+      base_url: `http://127.0.0.1:${port}`,
+    });
+    const stateBefore = readFileSync(statePath, "utf8");
+
+    // 对照组：不加 --dry-run，默认 refresh 路径真实访问远端 → 出现 refresh 失败告警。
+    const withoutDryRun = await runCommandE2e(ROUTES, planArgs(configPath), env);
+    expect(withoutDryRun.stderr).toMatch(/Failed to refresh/i);
+
+    // --dry-run：同环境必须完全离线成功，无任何 refresh 痕迹，且不回写 state 文件。
+    const withDryRun = await runCommandE2e(ROUTES, [...planArgs(configPath), "--dry-run"], env);
+    expect(withDryRun.exitCode, withDryRun.stderr).toBe(0);
+    expect(withDryRun.stderr).not.toMatch(/Failed to refresh/i);
+    expect(readFileSync(statePath, "utf8")).toBe(stateBefore);
+  });
+});
@@ -0,0 +1,247 @@
+import { describe, expect, test } from "vite-plus/test";
+import { parseStdoutJson, runCommandE2e } from "./helpers.ts";
+import { MANAGED_AGENT_ROUTES } from "./topic-routes.ts";
+
+/**
+ * managed-agent：help / 缺参不依赖密钥；所有 mutation 命令的 --dry-run
+ * 必须在构建 SDK runtime（凭证注入 / 联网 / 写盘）之前短路，因此同样不需要密钥。
+ * 鉴权分层：离线命令（init/validate/state list|show|rm）auth: "none"；联网命令
+ * 统一 auth: "apiKey" 硬门禁（见 managed-agent-auth-chain e2e）。
+ * 真实集成（apply/destroy/session 流程）依赖工作区内的 agents.yaml 与远端资源，
+ * 属批量场景，暂仅覆盖 dry-run 契约。
+ */
+
+describe("e2e: managed-agent", () => {
+  test("managed-agent apply --help 正常退出", async () => {
+    const { stderr, exitCode } = await runCommandE2e(MANAGED_AGENT_ROUTES, [
+      "managed-agent",
+      "apply",
+      "--help",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    expect(stderr).toMatch(/--file|--provider|--yes/i);
+  });
+
+  test("managed-agent session delete 缺少 --session-id 时退出为用法错误 (2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(MANAGED_AGENT_ROUTES, [
+      "managed-agent",
+      "session",
+      "delete",
+      "--quiet",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/--session-id|Missing required/i);
+  });
+
+  test("managed-agent session send 缺少 --message 时退出为用法错误 (2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(MANAGED_AGENT_ROUTES, [
+      "managed-agent",
+      "session",
+      "send",
+      "--session-id",
+      "sess_e2e",
+      "--quiet",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/--message|Missing required/i);
+  });
+
+  test("managed-agent skill-list --help 正常退出", async () => {
+    const { stderr, exitCode } = await runCommandE2e(MANAGED_AGENT_ROUTES, [
+      "managed-agent",
+      "skill-list",
+      "--help",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    expect(stderr).toMatch(/--source|--provider|--file/i);
+  });
+
+  test("managed-agent skill-list 非法 --source 时退出为用法错误 (2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(MANAGED_AGENT_ROUTES, [
+      "managed-agent",
+      "skill-list",
+      "--source",
+      "builtin",
+      "--quiet",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/--source must be one of: custom, official/i);
+  });
+
+  test("managed-agent skill-list --source all 通过参数校验（缺配置文件时才失败）", async () => {
+    // auth: "apiKey" 的凭证解析先于 run() 执行；注入假 key 让用例不依赖环境凭证，
+    // 命令仍会在配置加载阶段因文件缺失短路，不产生任何网络请求。
+    const { stderr, exitCode } = await runCommandE2e(
+      MANAGED_AGENT_ROUTES,
+      [
+        "managed-agent",
+        "skill-list",
+        "--source",
+        "all",
+        "--file",
+        "agents.e2e-missing.yaml",
+        "--quiet",
+      ],
+      { DASHSCOPE_API_KEY: "sk-e2e-skill-list" },
+    );
+    // all 是合法值：不应报 --source 用法错误，而是走到配置加载后因文件缺失退出
+    expect(exitCode).toBe(2);
+    expect(stderr).not.toMatch(/--source must be one of/i);
+    expect(stderr).toMatch(/File not found.*agents\.e2e-missing\.yaml/i);
+  });
+});
+
+describe("e2e: managed-agent（--dry-run 短路，不联网不写盘）", () => {
+  test("init --dry-run 仅输出计划，不创建文件", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(MANAGED_AGENT_ROUTES, [
+      "managed-agent",
+      "init",
+      "--dry-run",
+      "--file",
+      "agents.e2e-dry-run.yaml",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ would_create?: string; provider?: string }>(stdout);
+    expect(data.would_create).toBe("agents.e2e-dry-run.yaml");
+    expect(data.provider).toBe("bailian");
+  });
+
+  test("apply --dry-run 仅输出计划", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(MANAGED_AGENT_ROUTES, [
+      "managed-agent",
+      "apply",
+      "--dry-run",
+      "--yes",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ would_apply?: { provider?: string } }>(stdout);
+    expect(data.would_apply?.provider).toBe("all");
+  });
+
+  test("destroy --dry-run 仅输出计划", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(MANAGED_AGENT_ROUTES, [
+      "managed-agent",
+      "destroy",
+      "--dry-run",
+      "--cascade",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ would_destroy?: { cascade?: boolean } }>(stdout);
+    expect(data.would_destroy?.cascade).toBe(true);
+  });
+
+  test("session create --dry-run 仅输出计划", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(MANAGED_AGENT_ROUTES, [
+      "managed-agent",
+      "session",
+      "create",
+      "--dry-run",
+      "--agent",
+      "assistant",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ would_create_session?: { agent?: string } }>(stdout);
+    expect(data.would_create_session?.agent).toBe("assistant");
+  });
+
+  test("session delete --dry-run 仅输出计划", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(MANAGED_AGENT_ROUTES, [
+      "managed-agent",
+      "session",
+      "delete",
+      "--dry-run",
+      "--session-id",
+      "sess_e2e",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ would_delete_session?: string }>(stdout);
+    expect(data.would_delete_session).toBe("sess_e2e");
+  });
+
+  test("session send --dry-run 仅输出计划", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(MANAGED_AGENT_ROUTES, [
+      "managed-agent",
+      "session",
+      "send",
+      "--dry-run",
+      "--session-id",
+      "sess_e2e",
+      "--message",
+      "干跑",
+      "--no-stream",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{
+      would_send?: { session_id?: string; message?: string; mode?: string };
+    }>(stdout);
+    expect(data.would_send?.session_id).toBe("sess_e2e");
+    expect(data.would_send?.message).toBe("干跑");
+    expect(data.would_send?.mode).toBe("polling");
+  });
+
+  test("session run --dry-run 仅输出计划", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(MANAGED_AGENT_ROUTES, [
+      "managed-agent",
+      "session",
+      "run",
+      "--dry-run",
+      "--prompt",
+      "干跑",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{
+      would_run?: { prompt?: string; mode?: string };
+    }>(stdout);
+    expect(data.would_run?.prompt).toBe("干跑");
+    expect(data.would_run?.mode).toBe("streaming");
+  });
+
+  test("state rm --dry-run 仅输出计划", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(MANAGED_AGENT_ROUTES, [
+      "managed-agent",
+      "state",
+      "rm",
+      "--dry-run",
+      "--address",
+      "bailian.agent.assistant",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ would_remove?: string }>(stdout);
+    expect(data.would_remove).toBe("bailian.agent.assistant");
+  });
+
+  test("state import --dry-run 仅输出计划", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(MANAGED_AGENT_ROUTES, [
+      "managed-agent",
+      "state",
+      "import",
+      "--dry-run",
+      "--address",
+      "bailian.agent.assistant",
+      "--remote-id",
+      "agent-e2e",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ would_import?: string; remote_id?: string }>(stdout);
+    expect(data.would_import).toBe("bailian.agent.assistant");
+    expect(data.remote_id).toBe("agent-e2e");
+  });
+});
@@ -18,6 +18,7 @@ export const CONFIG_ROUTES: E2eRouteExports = {
  "config list": "configList",
  "config use": "configUse",
  "config ui": "configUi",
+  "config agent": "configAgent",
 };

 export const MEMORY_ROUTES: E2eRouteExports = {
@@ -58,6 +59,10 @@ export const VIDEO_ROUTES: E2eRouteExports = {
  "video download": "videoDownload",
 };

+export const VISION_ROUTES: E2eRouteExports = {
+  "vision describe": "visionDescribe",
+};
+
 export const SPEECH_ROUTES: E2eRouteExports = {
  "speech synthesize": "speechSynthesize",
  "speech recognize": "speechRecognize",
@@ -81,9 +86,13 @@ export const OMNI_ROUTES: E2eRouteExports = {
  "speech synthesize": "speechSynthesize",
 };

-export const FILE_UPLOAD_ROUTES: E2eRouteExports = { "file upload": "fileUpload" };
+export const FILE_UPLOAD_ROUTES: E2eRouteExports = {
+  "file upload": "fileUpload",
+};

-export const ADVISOR_ROUTES: E2eRouteExports = { "advisor recommend": "advisorRecommend" };
+export const ADVISOR_ROUTES: E2eRouteExports = {
+  "advisor recommend": "advisorRecommend",
+};

 export const QUOTA_ROUTES: E2eRouteExports = {
  "quota list": "quotaList",
@@ -146,3 +155,20 @@ export const TOKEN_PLAN_ROUTES: E2eRouteExports = {
  "token-plan assign-seats": "tokenPlanAssignSeats",
  "token-plan add-member": "tokenPlanAddMember",
 };
+
+export const MANAGED_AGENT_ROUTES: E2eRouteExports = {
+  "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 rm": "managedAgentStateRm",
+  "managed-agent state import": "managedAgentStateImport",
+  "managed-agent session create": "managedAgentSessionCreate",
+  "managed-agent session get": "managedAgentSessionGet",
+  "managed-agent session delete": "managedAgentSessionDelete",
+  "managed-agent session run": "managedAgentSessionRun",
+  "managed-agent session send": "managedAgentSessionSend",
+  "managed-agent skill-list": "managedAgentSkillList",
+};
@@ -1,3 +1,4 @@
+import { writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { describe, expect, test } from "vite-plus/test";
 import {
@@ -21,6 +22,96 @@ describe("e2e: video generate (i2v)", () => {
    expect(exitCode, stderr).toBe(0);
    expect(stderr).toMatch(/generate|--prompt|--image|model/i);
  });
+
+  test("Token Plan 使用独立的图生视频默认模型", async () => {
+    const configDir = makeE2eOutputDir("video-i2v-token-plan-default");
+    writeFileSync(
+      join(configDir, "config.json"),
+      JSON.stringify(
+        {
+          "token-plan": {
+            api_key: "sk-sp-e2e-placeholder",
+            base_url: "https://token-plan.cn-beijing.maas.aliyuncs.com",
+            default_video_model: "happyhorse-1.1-t2v",
+            default_image_to_video_model: "custom-image-to-video-model",
+          },
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+
+    const { stdout, stderr, exitCode } = await runCommandE2e(
+      VIDEO_ROUTES,
+      [
+        "video",
+        "generate",
+        "--config",
+        "token-plan",
+        "--dry-run",
+        "--image",
+        "https://example.com/placeholder.png",
+        "--prompt",
+        "干跑校验",
+        "--output",
+        "json",
+      ],
+      {
+        BAILIAN_CONFIG_DIR: configDir,
+        DASHSCOPE_API_KEY: "",
+        DASHSCOPE_BASE_URL: "",
+      },
+    );
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{
+      request?: { model?: string; input?: { media?: Array<{ type?: string }> } };
+    }>(stdout);
+    expect(data.request?.model).toBe("custom-image-to-video-model");
+    expect(data.request?.input?.media?.[0]?.type).toBe("first_frame");
+  });
+
+  test("Token Plan 图生视频将本地首帧转换为 Base64", async () => {
+    const configDir = makeE2eOutputDir("video-i2v-token-plan-local-image");
+    const imagePath = join(configDir, "first-frame.png");
+    writeFileSync(imagePath, Buffer.from([1, 2, 3]));
+    writeFileSync(
+      join(configDir, "config.json"),
+      JSON.stringify({
+        "token-plan": {
+          api_key: "sk-sp-e2e-placeholder",
+          base_url: "https://token-plan.cn-beijing.maas.aliyuncs.com",
+          default_image_to_video_model: "happyhorse-1.1-i2v",
+        },
+      }),
+    );
+
+    const { stdout, stderr, exitCode } = await runCommandE2e(
+      VIDEO_ROUTES,
+      [
+        "video",
+        "generate",
+        "--config",
+        "token-plan",
+        "--dry-run",
+        "--image",
+        imagePath,
+        "--prompt",
+        "让画面动起来",
+        "--output",
+        "json",
+      ],
+      {
+        BAILIAN_CONFIG_DIR: configDir,
+        DASHSCOPE_API_KEY: "",
+        DASHSCOPE_BASE_URL: "",
+      },
+    );
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{
+      request?: { input?: { media?: Array<{ url?: string }> } };
+    }>(stdout);
+    expect(data.request?.input?.media?.[0]?.url).toBe("data:image/png;base64,<omitted>");
+  });
 });

 describe.skipIf(!isBailianE2EVideoEnabled() || !isDashScopeE2EReady())(
@@ -1,3 +1,4 @@
+import { writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { describe, expect, test } from "vite-plus/test";
 import {
@@ -43,6 +44,92 @@ describe("e2e: video ref (r2v)", () => {
    );
    expect(data.request?.input?.media?.[0]?.url).toBe("https://example.com/person.png");
  });
+
+  test("Token Plan 使用独立的参考生视频默认模型", async () => {
+    const configDir = makeE2eOutputDir("video-r2v-token-plan-default");
+    writeFileSync(
+      join(configDir, "config.json"),
+      JSON.stringify(
+        {
+          "token-plan": {
+            api_key: "sk-sp-e2e-placeholder",
+            base_url: "https://token-plan.cn-beijing.maas.aliyuncs.com",
+            default_reference_to_video_model: "custom-reference-to-video-model",
+          },
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+
+    const { stdout, stderr, exitCode } = await runCommandE2e(
+      VIDEO_ROUTES,
+      [
+        "video",
+        "ref",
+        "--config",
+        "token-plan",
+        "--dry-run",
+        "--prompt",
+        "Image 1 waves",
+        "--image",
+        "https://example.com/person.png",
+        "--output",
+        "json",
+      ],
+      {
+        BAILIAN_CONFIG_DIR: configDir,
+        DASHSCOPE_API_KEY: "",
+        DASHSCOPE_BASE_URL: "",
+      },
+    );
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ request?: { model?: string } }>(stdout);
+    expect(data.request?.model).toBe("custom-reference-to-video-model");
+  });
+
+  test("Token Plan 参考生视频将本地参考图转换为 Base64", async () => {
+    const configDir = makeE2eOutputDir("video-r2v-token-plan-local-image");
+    const imagePath = join(configDir, "reference.png");
+    writeFileSync(imagePath, Buffer.from([1, 2, 3]));
+    writeFileSync(
+      join(configDir, "config.json"),
+      JSON.stringify({
+        "token-plan": {
+          api_key: "sk-sp-e2e-placeholder",
+          base_url: "https://token-plan.cn-beijing.maas.aliyuncs.com",
+          default_reference_to_video_model: "happyhorse-1.1-r2v",
+        },
+      }),
+    );
+
+    const { stdout, stderr, exitCode } = await runCommandE2e(
+      VIDEO_ROUTES,
+      [
+        "video",
+        "ref",
+        "--config",
+        "token-plan",
+        "--dry-run",
+        "--image",
+        imagePath,
+        "--prompt",
+        "Image 1 waves",
+        "--output",
+        "json",
+      ],
+      {
+        BAILIAN_CONFIG_DIR: configDir,
+        DASHSCOPE_API_KEY: "",
+        DASHSCOPE_BASE_URL: "",
+      },
+    );
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{
+      request?: { input?: { media?: Array<{ url?: string }> } };
+    }>(stdout);
+    expect(data.request?.input?.media?.[0]?.url).toBe("data:image/png;base64,<omitted>");
+  });
 });

 describe.skipIf(!isBailianE2EVideoEnabled() || !isDashScopeE2EReady())(
@@ -0,0 +1,45 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vite-plus/test";
+import { makeE2eOutputDir, parseStdoutJson, runCommandE2e } from "./helpers.ts";
+import { VISION_ROUTES } from "./topic-routes.ts";
+
+describe("e2e: vision describe", () => {
+  test("Token Plan 默认使用支持视觉理解的文本模型", async () => {
+    const configDir = makeE2eOutputDir("vision-describe-token-plan-default");
+    writeFileSync(
+      join(configDir, "config.json"),
+      JSON.stringify({
+        "token-plan": {
+          api_key: "sk-sp-e2e-placeholder",
+          base_url: "https://token-plan.cn-beijing.maas.aliyuncs.com",
+          default_text_model: "qwen3.8-max-preview",
+        },
+      }),
+    );
+
+    const { stdout, stderr, exitCode } = await runCommandE2e(
+      VISION_ROUTES,
+      [
+        "vision",
+        "describe",
+        "--config",
+        "token-plan",
+        "--image",
+        "https://example.com/image.png",
+        "--dry-run",
+        "--output",
+        "json",
+      ],
+      {
+        BAILIAN_CONFIG_DIR: configDir,
+        DASHSCOPE_API_KEY: "",
+        DASHSCOPE_BASE_URL: "",
+      },
+    );
+
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ request?: { model?: string } }>(stdout);
+    expect(data.request?.model).toBe("qwen3.8-max-preview");
+  });
+});
@@ -0,0 +1,77 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { expect, test } from "vite-plus/test";
+
+/**
+ * 发布契约：最低 Node 版本。
+ * 1) bl 全部发布包的 engines.node 必须一致（版本 bump 一动多动的另一面）。
+ * 2) 外部运行时依赖 @openagentpack/sdk 的 engines 下限不得高于 bl 的下限，
+ *    否则 Node 18/20 用户安装 bailian-cli 会触发 EBADENGINE / engine-strict 失败。
+ *    历史上出现过冲突版本，用版本号白名单做棘轮：一旦升级依赖版本，本检查自动强制生效。
+ */
+
+const repoRoot = join(import.meta.dirname, "..", "..", "..");
+const BL_PACKAGES = ["core", "runtime", "commands", "cli", "kscli"] as const;
+
+/** 上游 engines 冲突版本白名单；当前依赖版本已对齐，请勿把新版本加进来。 */
+const KNOWN_SDK_ENGINE_CONFLICT_VERSIONS = new Set<string>([]);
+
+interface PackageManifest {
+  name: string;
+  version: string;
+  engines?: { node?: string };
+  dependencies?: Record<string, string>;
+}
+
+function readManifest(path: string): PackageManifest {
+  return JSON.parse(readFileSync(path, "utf8")) as PackageManifest;
+}
+
+/** 解析 ">=X.Y.Z" / ">=X" 形式的 engines 下限为可比较的 [major, minor, patch]。 */
+function parseEngineFloor(range: string): [number, number, number] {
+  const matched = /^>=\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(range.trim());
+  if (!matched) throw new Error(`Unsupported engines range: ${range}`);
+  return [Number(matched[1]), Number(matched[2] ?? 0), Number(matched[3] ?? 0)];
+}
+
+function floorLessOrEqual(
+  left: [number, number, number],
+  right: [number, number, number],
+): boolean {
+  for (let index = 0; index < 3; index++) {
+    if (left[index]! !== right[index]!) return left[index]! < right[index]!;
+  }
+  return true;
+}
+
+test("bl 全部发布包 engines.node 一致", () => {
+  const floors = BL_PACKAGES.map((pkg) => {
+    const manifest = readManifest(join(repoRoot, "packages", pkg, "package.json"));
+    return { name: manifest.name, node: manifest.engines?.node };
+  });
+  const [first, ...rest] = floors;
+  expect(first?.node).toMatch(/^>=\d+\.\d+\.\d+$/);
+  for (const entry of rest) {
+    expect(entry.node, `${entry.name} engines.node 与 ${first?.name} 不一致`).toBe(first?.node);
+  }
+});
+
+test("@openagentpack/sdk engines 下限不高于 bl 的最低 Node 版本", () => {
+  const commandsManifest = readManifest(join(repoRoot, "packages", "commands", "package.json"));
+  const blFloor = parseEngineFloor(commandsManifest.engines?.node ?? "");
+
+  const sdkManifest = readManifest(
+    join(repoRoot, "packages", "commands", "node_modules", "@openagentpack", "sdk", "package.json"),
+  );
+  const sdkRange = sdkManifest.engines?.node;
+  if (!sdkRange) return; // 无 engines 声明即不设限,兼容
+
+  if (KNOWN_SDK_ENGINE_CONFLICT_VERSIONS.has(sdkManifest.version)) return;
+
+  const sdkFloor = parseEngineFloor(sdkRange);
+  expect(
+    floorLessOrEqual(sdkFloor, blFloor),
+    `@openagentpack/sdk@${sdkManifest.version} 要求 Node ${sdkRange}，高于 bl 承诺的 ${commandsManifest.engines?.node}；` +
+      "这会让 Node 18/20 用户安装 bailian-cli 失败（EBADENGINE / engine-strict）。",
+  ).toBe(true);
+});
@@ -0,0 +1,118 @@
+import { UserError } from "@openagentpack/sdk";
+import { BailianError, ExitCode } from "bailian-cli-core";
+import { expect, test } from "vite-plus/test";
+import { withAgentErrors } from "../src/commands/managed-agent/_engine/errors.ts";
+
+/**
+ * Structural stand-in for the SDK's internal `ApiError` (not exported by the
+ * installed SDK version): withAgentErrors matches on statusCode/responseBody
+ * fields, so any Error carrying them must map through mapApiError.
+ */
+class FakeSdkApiError extends Error {
+  constructor(
+    readonly statusCode: number,
+    readonly responseBody: string,
+  ) {
+    super(`Bailian API ${statusCode}: ${responseBody}`);
+  }
+}
+
+async function catchMapped(error: unknown): Promise<BailianError> {
+  try {
+    await withAgentErrors(() => Promise.reject(error));
+  } catch (mapped) {
+    expect(mapped).toBeInstanceOf(BailianError);
+    return mapped as BailianError;
+  }
+  throw new Error("expected withAgentErrors to throw");
+}
+
+test("BailianError passes through untouched", async () => {
+  const original = new BailianError("already mapped", ExitCode.AUTH);
+  const mapped = await catchMapped(original);
+  expect(mapped).toBe(original);
+});
+
+test("SDK UserError maps to USAGE", async () => {
+  const mapped = await catchMapped(new UserError("bad agents.yaml"));
+  expect(mapped.exitCode).toBe(ExitCode.USAGE);
+  expect(mapped.message).toBe("bad agents.yaml");
+});
+
+test("SDK polling-timeout UserError maps to TIMEOUT (5), not USAGE", async () => {
+  // 消息形状来自 SDK session-runtime 的 assertNotTimedOut —— 客户端等待超时，
+  // 按 bl 错误边界必须归 TIMEOUT，不能告诉自动化调用方“参数错误”。
+  const mapped = await catchMapped(
+    new UserError("Session did not complete within the timeout (600 seconds)."),
+  );
+  expect(mapped.exitCode).toBe(ExitCode.TIMEOUT);
+  expect(mapped.message).toBe("Session did not complete within the timeout (600 seconds).");
+  expect(mapped.hint).toMatch(/session get/);
+});
+
+test("提及 timeout 但非轮询超时句式的 UserError 仍归 USAGE", async () => {
+  const mapped = await catchMapped(new UserError("Invalid timeout value in agents.yaml"));
+  expect(mapped.exitCode).toBe(ExitCode.USAGE);
+});
+
+test("SDK ApiError with DashScope-style JSON body surfaces clean message and api metadata", async () => {
+  const body = JSON.stringify({
+    code: "InvalidParameter",
+    message: "agent name already exists",
+    request_id: "req-123",
+  });
+  const mapped = await catchMapped(new FakeSdkApiError(400, body));
+  expect(mapped.exitCode).toBe(ExitCode.GENERAL);
+  expect(mapped.message).toBe("agent name already exists");
+  expect(mapped.api).toEqual({
+    httpStatus: 400,
+    apiCode: "InvalidParameter",
+    requestId: "req-123",
+  });
+});
+
+test("SDK ApiError with OpenAI-style error envelope extracts message and type", async () => {
+  const body = JSON.stringify({
+    error: { message: "model does not exist", type: "invalid_request_error" },
+    request_id: "req-456",
+  });
+  const mapped = await catchMapped(new FakeSdkApiError(404, body));
+  expect(mapped.exitCode).toBe(ExitCode.GENERAL);
+  expect(mapped.message).toBe("model does not exist");
+  expect(mapped.api?.apiCode).toBe("invalid_request_error");
+  expect(mapped.api?.requestId).toBe("req-456");
+});
+
+test("SDK ApiError with non-JSON body passes raw text through as message", async () => {
+  const mapped = await catchMapped(new FakeSdkApiError(502, "Bad Gateway"));
+  expect(mapped.exitCode).toBe(ExitCode.GENERAL);
+  expect(mapped.message).toBe("Bad Gateway");
+  expect(mapped.api?.httpStatus).toBe(502);
+});
+
+test("SDK ApiError with empty body falls back to HTTP status message", async () => {
+  const mapped = await catchMapped(new FakeSdkApiError(503, ""));
+  expect(mapped.message).toBe("HTTP 503");
+  expect(mapped.api?.httpStatus).toBe(503);
+});
+
+test("plain Error maps to GENERAL with message passed through", async () => {
+  const mapped = await catchMapped(new Error("boom"));
+  expect(mapped.exitCode).toBe(ExitCode.GENERAL);
+  expect(mapped.message).toBe("boom");
+  expect(mapped.api).toBeUndefined();
+});
+
+test("fetch transport TypeError is rethrown untouched for the runtime NETWORK mapping", async () => {
+  const transportError = new TypeError("fetch failed", {
+    cause: Object.assign(new Error("connect ECONNREFUSED 127.0.0.1:1"), {
+      code: "ECONNREFUSED",
+    }),
+  });
+  try {
+    await withAgentErrors(() => Promise.reject(transportError));
+    throw new Error("expected withAgentErrors to throw");
+  } catch (error) {
+    expect(error).toBe(transportError);
+  }
+});
@@ -0,0 +1,81 @@
+import { describe, expect, test } from "vite-plus/test";
+import { BailianError, ExitCode } from "bailian-cli-core";
+import { mcpMarketplaceDetailPage } from "bailian-cli-runtime";
+import {
+  isMcpNotActivated,
+  mcpActivateHint,
+  rethrowWithMcpActivateHint,
+} from "../src/commands/mcp/activate-hint.ts";
+
+describe("mcp-activate-hint", () => {
+  test("识别 404 + 未开通 / MCP不存在 / MCP_IS_INVALID", () => {
+    expect(
+      isMcpNotActivated(new BailianError("MCP request failed: 404 Not Found - MCP不存在或未开通")),
+    ).toBe(true);
+    expect(
+      isMcpNotActivated(new BailianError("MCP request failed: 404  - MCP不存在或未开通")),
+    ).toBe(true);
+    expect(
+      isMcpNotActivated(new BailianError("MCP request failed: 404 Not Found - MCP_IS_INVALID")),
+    ).toBe(true);
+  });
+
+  test("裸 404 或非 MCP 错误不加开通判定", () => {
+    expect(isMcpNotActivated(new BailianError("MCP request failed: 404 Not Found"))).toBe(false);
+    expect(isMcpNotActivated(new BailianError("MCP request failed: 405 Method Not Allowed"))).toBe(
+      false,
+    );
+    expect(isMcpNotActivated(new Error("MCP不存在或未开通"))).toBe(false);
+  });
+
+  test("hint 含对应 server 的 MCP 广场深链", () => {
+    const serverCode = "market-cmapi00073529";
+    expect(mcpActivateHint(serverCode)).toContain(mcpMarketplaceDetailPage(serverCode));
+    expect(mcpActivateHint(serverCode)).toMatch(/Activate|re-activate/i);
+  });
+
+  test("WebSearch hint 含 SSE 升级说明", () => {
+    expect(mcpActivateHint("WebSearch")).toMatch(/SSE|Streamable HTTP/i);
+  });
+
+  test("rethrow 保留原 message，补 hint", () => {
+    const serverCode = "market-cmapi00073529";
+    const original = new BailianError(
+      "MCP request failed: 404 Not Found - MCP不存在或未开通",
+      ExitCode.GENERAL,
+    );
+    try {
+      rethrowWithMcpActivateHint(original, serverCode);
+      expect.unreachable("should throw");
+    } catch (error) {
+      expect(error).toBeInstanceOf(BailianError);
+      const wrapped = error as BailianError;
+      expect(wrapped.message).toBe(original.message);
+      expect(wrapped.exitCode).toBe(ExitCode.GENERAL);
+      expect(wrapped.hint).toContain(mcpMarketplaceDetailPage(serverCode));
+      expect(wrapped.cause).toBe(original);
+    }
+  });
+
+  test("已有 hint 或非未开通错误原样抛出", () => {
+    const withHint = new BailianError(
+      "MCP request failed: 404 Not Found - MCP不存在或未开通",
+      ExitCode.GENERAL,
+      "already hinted",
+    );
+    try {
+      rethrowWithMcpActivateHint(withHint, "WebSearch");
+      expect.unreachable("should throw");
+    } catch (error) {
+      expect(error).toBe(withHint);
+    }
+
+    const other = new BailianError("MCP request failed: 401 Unauthorized");
+    try {
+      rethrowWithMcpActivateHint(other, "WebSearch");
+      expect.unreachable("should throw");
+    } catch (error) {
+      expect(error).toBe(other);
+    }
+  });
+});
@@ -0,0 +1,81 @@
+import { describe, expect, test } from "vite-plus/test";
+import { BailianError, ExitCode } from "bailian-cli-core";
+import { MCP_WEBSEARCH_PAGE } from "bailian-cli-runtime";
+import {
+  isWebSearchMcpNotActivated,
+  rethrowWithWebSearchActivateHint,
+  webSearchActivateHint,
+} from "../src/commands/search/web-activate-hint.ts";
+
+describe("web-activate-hint", () => {
+  test("识别 404 + 未开通 / MCP不存在 / MCP_IS_INVALID", () => {
+    expect(
+      isWebSearchMcpNotActivated(
+        new BailianError("MCP request failed: 404 Not Found - MCP不存在或未开通"),
+      ),
+    ).toBe(true);
+    expect(
+      isWebSearchMcpNotActivated(new BailianError("MCP request failed: 404  - MCP不存在或未开通")),
+    ).toBe(true);
+    expect(
+      isWebSearchMcpNotActivated(
+        new BailianError("MCP request failed: 404 Not Found - MCP_IS_INVALID"),
+      ),
+    ).toBe(true);
+  });
+
+  test("裸 404 或非 MCP 错误不加开通判定", () => {
+    expect(isWebSearchMcpNotActivated(new BailianError("MCP request failed: 404 Not Found"))).toBe(
+      false,
+    );
+    expect(
+      isWebSearchMcpNotActivated(new BailianError("MCP request failed: 405 Method Not Allowed")),
+    ).toBe(false);
+    expect(isWebSearchMcpNotActivated(new Error("MCP不存在或未开通"))).toBe(false);
+  });
+
+  test("hint 含 MCP 广场 WebSearch 深链", () => {
+    expect(webSearchActivateHint()).toContain(MCP_WEBSEARCH_PAGE);
+    expect(webSearchActivateHint()).toMatch(/Activate|re-activate/i);
+  });
+
+  test("rethrow 保留原 message，补 Hint", () => {
+    const original = new BailianError(
+      "MCP request failed: 404 Not Found - MCP不存在或未开通",
+      ExitCode.GENERAL,
+    );
+    try {
+      rethrowWithWebSearchActivateHint(original);
+      expect.unreachable("should throw");
+    } catch (error) {
+      expect(error).toBeInstanceOf(BailianError);
+      const wrapped = error as BailianError;
+      expect(wrapped.message).toBe(original.message);
+      expect(wrapped.exitCode).toBe(ExitCode.GENERAL);
+      expect(wrapped.hint).toContain(MCP_WEBSEARCH_PAGE);
+      expect(wrapped.cause).toBe(original);
+    }
+  });
+
+  test("已有 hint 或非未开通错误原样抛出", () => {
+    const withHint = new BailianError(
+      "MCP request failed: 404 Not Found - MCP不存在或未开通",
+      ExitCode.GENERAL,
+      "already hinted",
+    );
+    try {
+      rethrowWithWebSearchActivateHint(withHint);
+      expect.unreachable("should throw");
+    } catch (error) {
+      expect(error).toBe(withHint);
+    }
+
+    const other = new BailianError("MCP request failed: 401 Unauthorized");
+    try {
+      rethrowWithWebSearchActivateHint(other);
+      expect.unreachable("should throw");
+    } catch (error) {
+      expect(error).toBe(other);
+    }
+  });
+});
@@ -0,0 +1,170 @@
+import { afterEach, beforeEach, expect, test } from "vite-plus/test";
+import type { CollectedSessionEvents, ProviderSessionEvent } from "@openagentpack/sdk";
+import { BailianError, ExitCode } from "bailian-cli-core";
+import {
+  renderCollectedEvents,
+  streamAndRenderEvents,
+} from "../src/commands/managed-agent/_engine/session-render.ts";
+
+/**
+ * `--output json` 会话信封契约：stdout 恰好一个合法 JSON，且信封头部携带
+ * session_id / provider / agent —— session run 的调用方必须能从 stdout 拿到
+ * 新建 Session ID 以继续 send/get/events/delete（不靠刮 stderr）。
+ */
+
+let stdoutChunks: string[] = [];
+let originalStdoutWrite: typeof process.stdout.write;
+
+beforeEach(() => {
+  stdoutChunks = [];
+  originalStdoutWrite = process.stdout.write.bind(process.stdout);
+  process.stdout.write = ((chunk: string | Uint8Array) => {
+    stdoutChunks.push(String(chunk));
+    return true;
+  }) as typeof process.stdout.write;
+});
+
+afterEach(() => {
+  process.stdout.write = originalStdoutWrite;
+});
+
+function capturedJson(): Record<string, unknown> {
+  // 契约：整个 stdout 拼起来是单个合法 JSON
+  return JSON.parse(stdoutChunks.join("")) as Record<string, unknown>;
+}
+
+async function* fakeEventStream(): AsyncIterable<ProviderSessionEvent> {
+  yield {
+    type: "message",
+    role: "assistant",
+    content: "hi",
+  } as ProviderSessionEvent;
+  yield { type: "status", status: "completed" } as ProviderSessionEvent;
+}
+
+async function* fakeFailedEventStream(): AsyncIterable<ProviderSessionEvent> {
+  yield {
+    type: "error",
+    content: "provider quota exceeded",
+  } as ProviderSessionEvent;
+  yield { type: "status", status: "failed" } as ProviderSessionEvent;
+}
+
+function fakeCollected(): CollectedSessionEvents {
+  return {
+    terminalStatus: "completed",
+    result: {
+      events: [
+        {
+          type: "message",
+          role: "assistant",
+          content: "hi",
+        } as ProviderSessionEvent,
+      ],
+      has_more: false,
+      next_page: undefined,
+    },
+  } as CollectedSessionEvents;
+}
+
+function fakeFailedCollected(): CollectedSessionEvents {
+  return {
+    terminalStatus: "failed",
+    result: {
+      events: [
+        {
+          type: "error",
+          content: "provider quota exceeded",
+        } as ProviderSessionEvent,
+      ],
+      has_more: false,
+      next_page: undefined,
+    },
+  } as CollectedSessionEvents;
+}
+
+async function catchSessionFailure(run: () => Promise<void> | void): Promise<BailianError> {
+  try {
+    await run();
+  } catch (error) {
+    expect(error).toBeInstanceOf(BailianError);
+    return error as BailianError;
+  }
+  throw new Error("expected failed session to throw");
+}
+
+test("stream json:信封携带 session_id/provider/agent + events", async () => {
+  await streamAndRenderEvents(fakeEventStream(), true, {
+    session_id: "sess_stream",
+    provider: "bailian",
+    agent: "assistant",
+  });
+  const data = capturedJson();
+  expect(data.session_id).toBe("sess_stream");
+  expect(data.provider).toBe("bailian");
+  expect(data.agent).toBe("assistant");
+  expect(Array.isArray(data.events)).toBe(true);
+  expect((data.events as unknown[]).length).toBe(2);
+});
+
+test("streaming failed:保留 JSON 信封并以服务端 error 消息抛 GENERAL", async () => {
+  const error = await catchSessionFailure(() =>
+    streamAndRenderEvents(fakeFailedEventStream(), true, {
+      session_id: "sess_failed_stream",
+      provider: "bailian",
+      agent: "assistant",
+    }),
+  );
+  expect(error.exitCode).toBe(ExitCode.GENERAL);
+  expect(error.message).toBe("provider quota exceeded");
+
+  const data = capturedJson();
+  expect(data.session_id).toBe("sess_failed_stream");
+  expect((data.events as unknown[]).length).toBe(2);
+});
+
+test("polling json:信封携带 session_id/provider/agent，并保留 has_more/next_page", () => {
+  renderCollectedEvents(fakeCollected(), true, {
+    session_id: "sess_poll",
+    provider: "claude",
+    agent: "assistant",
+  });
+  const data = capturedJson();
+  expect(data.session_id).toBe("sess_poll");
+  expect(data.provider).toBe("claude");
+  expect(data.agent).toBe("assistant");
+  expect(data.has_more).toBe(false);
+  expect(Array.isArray(data.events)).toBe(true);
+});
+
+test("polling failed:保留 JSON 信封并以服务端 error 消息抛 GENERAL", async () => {
+  const error = await catchSessionFailure(() =>
+    renderCollectedEvents(fakeFailedCollected(), true, {
+      session_id: "sess_failed_poll",
+      provider: "claude",
+      agent: "assistant",
+    }),
+  );
+  expect(error.exitCode).toBe(ExitCode.GENERAL);
+  expect(error.message).toBe("provider quota exceeded");
+
+  const data = capturedJson();
+  expect(data.session_id).toBe("sess_failed_poll");
+  expect((data.events as unknown[]).length).toBe(1);
+});
+
+test("json:不传 context 时信封形状不变(无 session_id 键)", () => {
+  renderCollectedEvents(fakeCollected(), true);
+  const data = capturedJson();
+  expect("session_id" in data).toBe(false);
+  expect(Array.isArray(data.events)).toBe(true);
+});
+
+test("text 模式:context 不影响 stdout(仍只输出助手文本)", async () => {
+  await streamAndRenderEvents(fakeEventStream(), false, {
+    session_id: "sess_text",
+  });
+  const output = stdoutChunks.join("");
+  expect(output).toBe("hi");
+  expect(output).not.toContain("sess_text");
+});
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
ls	afa43a42b9	Merge pull request #128 from modelstudioai/feat/config-agent-fix feat(config-agent): align agent writers, add --key/--region, prepare 1.12.0	2026-07-28 20:39:56 +08:00
lisheng.lisheng	bbf45a5961	Merge branch 'main' of github.com:modelstudioai/cli into feat/config-agent-fix # Conflicts: # CHANGELOG.md # CHANGELOG.zh.md # packages/cli/package.json # packages/commands/package.json # packages/core/package.json # packages/kscli/package.json # packages/runtime/package.json # skills/bailian-cli/SKILL.md	2026-07-28 20:33:16 +08:00
lisheng.lisheng	3988e701e1	chore(cli): 发布 1.11.0 版本，更新 agent 配置功能 - 新增 `bl config agent --key` / `--region`，支持控制台编码 API Key 本地解码和区域派生 Token Plan 地址 - 新增 `bl config agent --context-window`，设置 OpenClaw 配置的上下文窗口大小，默认 256000 - 新增 `bl config agent --wire-api`，支持选择 Codex 配置的通信协议，兼容旧版 chat 协议并提示警告 - 变更 Codex 默认写入通信协议为 `responses`，适配新版 Codex 不再支持旧 chat 模式 - 变更 Qwen Code 代理配置改用 `DASHSCOPE_API_KEY` 环境变量替代 `BAILIAN_CLI_API_KEY` - 修复各 agent 配置格式不匹配问题，支持 JSONC 格式和官方结构，完善模型白名单与计费元数据 - 修复配置写入逻辑，合并保持用户自定义配置，避免覆盖及重复条目，优化显示名保留 - 更新所有相关包版本号至 1.11.0，包含 bailian-cli、commands、core、kscli、runtime - 更新 bailian-cli 技能元数据版本号至 1.11.0	2026-07-28 20:27:28 +08:00
lisheng.lisheng	96744e3328	feat(config-agent): add --key and --region, default codex wire_api to responses - --key: decode the web console's obfuscated API key (o1_ prefix) into the real key; mutually exclusive with --api-key, exactly one required - --region: convert a Model Studio region into the Token Plan base URL (token-plan.<region>.maas.aliyuncs.com/compatible-mode/v1); mutually exclusive with --base-url, exactly one required - codex: default wire_api to "responses" (current Codex rejects "chat"); --wire-api chat kept for legacy Codex <= 0.80.0 with a warning - regenerate skills reference for the new flags	2026-07-28 19:37:13 +08:00
Gong Shiqi	3b7993e854	Merge pull request #126 from modelstudioai/fix/web-search-and-thinking fix(mcp,text): MCP activation hints and fix error caused by enable_thinking	2026-07-28 19:32:26 +08:00
若麒	be6ddb6126	chore(release): prepare 1.11.2	2026-07-28 19:24:40 +08:00
clh02467605	25ac5c9c84	fix: revert change about defaultTextModel	2026-07-28 18:05:18 +08:00
clh02467605	8ef91fe395	test(core): align token-plan preset expectation with qwen3.7-plus	2026-07-28 17:29:41 +08:00
clh02467605	5d9e22de8f	Merge remote-tracking branch 'refs/remotes/origin/main' into fix/web-search-and-thinking	2026-07-28 17:20:46 +08:00
clh02467605	20e3555b84	fix(text,auth): drop enable_thinking retry and omit the field by default Pass through model constraint errors instead of auto-retrying, switch token-plan default text model to qwen3.7-plus, and align related e2e expectations.	2026-07-28 17:19:05 +08:00
Gong Shiqi	81fa5b567c	Merge pull request #123 from modelstudioai/fix/default-model Fix/default model	2026-07-28 16:19:04 +08:00
若麒	df987ad536	docs(changelog): document image edit function option	2026-07-28 16:13:40 +08:00
若麒	4c4e7afb83	chore(release): prepare 1.11.1	2026-07-28 16:07:29 +08:00
若麒	17c52fb86f	Merge branch 'main' into fix/default-model	2026-07-28 15:46:46 +08:00
Gong Shiqi	634d7045c6	Merge pull request #127 from modelstudioai/release/1.11.0 chore(release): prepare 1.11.0	2026-07-28 14:02:28 +08:00
若麒	eadd92327f	chore(release): prepare 1.11.0	2026-07-28 13:28:11 +08:00
lisheng.lisheng	5a58f56b06	refactor(agent): 修改环境变量名并优化代码格式 - 将环境变量名从 BAILIAN_CLI_API_KEY 改为 DASHSCOPE_API_KEY - 调整导入语句格式，提升代码可读性 - 优化 providers 条目查找的换行和缩进 - 标准化名称判断与赋值逻辑的格式与排列	2026-07-28 09:59:41 +08:00
clh02467605	7ad14a79b9	Merge branch 'main' of github.com:modelstudioai/cli into fix/web-search-and-thinking	2026-07-28 09:25:34 +08:00
clh02467605	8211268bd8	fix(text,mcp): keep thinking_budget on enable_thinking retry and hint MCP activation on 404	2026-07-28 09:25:02 +08:00
Gong Shiqi	7319f6d1ce	Merge pull request #116 from modelstudioai/feat/cma 添加agent studio的cli能力	2026-07-27 22:46:50 +08:00
chenanran555	2dce9fe093	feat(agent): session and destroy failed error	2026-07-27 21:52:52 +08:00
chenanran555	9819eb6ddc	feat(agent): 非bailian provider也走鉴权逻辑	2026-07-27 21:33:36 +08:00
qcq01083097	58252911a8	fix(image): correct wan2.5/2.6 size presets and wanx-v1 dated aliases	2026-07-27 21:09:32 +08:00
chenanran555	a03ee0c72c	fix(agent): timeout error	2026-07-27 20:23:21 +08:00
chenanran555	05860b3bdd	fix(agent): session output json with session_id	2026-07-27 20:10:47 +08:00
chenanran555	63ee5aaec3	fix(agent): plan command dry-run	2026-07-27 20:03:09 +08:00
chenanran555	93c9149e45	feat(agent): 鉴权分离线命令和在线命令，仅对bailian provider鉴权	2026-07-27 19:51:56 +08:00
chenanran555	6f9e006fef	feat(agent): add skills for skill-list command	2026-07-27 18:17:39 +08:00
chenanran555	e22058b0f7	feat: update openagentpack sdk	2026-07-27 18:14:06 +08:00
lisheng.lisheng	0221e35803	fix(config-agent): 优化 Codex 配置写入与兼容性处理 - 调整 Codex 代理默认 wire_api 为 "responses"，兼容新版 Codex - 增加对 legacy Codex <= 0.80.0 使用 wire_api "chat" 的警告提示 - 修正 agent flags 描述，更准确说明 wire_api 默认与兼容范围 - 优化代码格式，统一 import 语句风格 - 增加测试用例覆盖不同 wire_api 配置及环境变量警告 - 修复写入过程中文件备份及合并逻辑，保留用户已有配置 - 修复多个 provider 写入时键名与内容匹配，避免重复添加 - 改善测试代码格式，提高可读性与一致性	2026-07-27 17:10:26 +08:00
clh02467605	36ebd63716	fix(text): omit enable_thinking by default and retry when API requires false Non-streaming chat no longer forces enable_thinking=false, which breaks thinking-only models. Retry once with false only when the server demands it.	2026-07-27 16:51:11 +08:00
clh02467605	dac254af86	feat: add MCP WebSearch page URL and enhance error handling in web search command	2026-07-27 16:51:09 +08:00
chenanran555	8a0fb870f1	feat(agent): update openagentpack sdk version	2026-07-27 16:34:58 +08:00
qcq01083097	ff469ce717	feat(install-docs): enhance installation documentation and validation processes	2026-07-27 11:24:22 +08:00
chenanran555	5f0966ec8d	fix(agent): ci issues	2026-07-27 10:51:09 +08:00
qcq01083097	c4f5bb09c6	fix(image): resolve size and prompt_extend by model profile Stop inferring size/prompt_extend from sync vs async; use per-family sizeProfile. wanx*-imageedit uses function+base_image_url; bare qwen-image uses the fixed resolution table.	2026-07-27 10:17:09 +08:00
qcq01083097	9a13700390	fix(image): route text-to-image and image-edit by model family Fix wanx/wan2.x-t2i, wan2.5-i2i, z-image, and qwen-image-plus hitting the wrong endpoint, and add routing unit tests plus dry-run coverage.	2026-07-27 10:16:25 +08:00
chenanran555	32c497db63	feat(agent): add skill-list command and fix pr issues	2026-07-26 18:52:27 +08:00
chenanran555	247bb82154	test(agent): cover config-write, profile, logout and error-mapping auth-chain scenarios	2026-07-24 18:44:18 +08:00
chenanran555	1e6165d7ff	fix(agent): guarantee single valid JSON on stdout for --output json	2026-07-24 16:25:09 +08:00
chenanran555	1bf4fec9e6	feat(agent): support --dry-run for all local and remote mutations	2026-07-24 16:02:15 +08:00
chenanran555	1d589c5178	Merge remote-tracking branch 'origin/main' into feat/cma	2026-07-24 14:52:21 +08:00
chenanran555	9cad1994e7	feat(agent): validate by client apiKey auth type	2026-07-24 14:50:30 +08:00
Gong Shiqi	fac2b2d18b	Merge pull request #121 from modelstudioai/fix/install-doc-non-interactive docs: fix installation guide flags	2026-07-24 11:19:40 +08:00
若麒	3e249279bc	docs: fix installation guide flags	2026-07-24 11:08:06 +08:00
Gong Shiqi	f9012a6330	Merge pull request #119 from modelstudioai/fix/base-url-origin-only fix(core): normalize model base URL to origin	2026-07-23 19:35:24 +08:00
若麒	92ee845bdd	fix(core): normalize model base URL to origin	2026-07-23 19:31:02 +08:00
lisheng.lisheng	4751145283	fix(config-agent): 修复 Qwen Code 凭证写入与模型名处理 - 凭证同时写入 env 和 security.auth，避免系统 OPENAI_API_KEY 干扰 - modelProviders 中按 id + baseUrl 作为键，保持 name 为模型显示名 - 修复旧的 bailian-cli 名称，防止其覆盖用户自定义显示名 - model 配置中新增 baseUrl 字段，用于消歧同 id 但不同地址的模型 - 调整测试用例验证上述行为，确保配置一致性和兼容性	2026-07-23 19:20:44 +08:00
chenanran555	64335a6201	feat(agent): rename cli command to managed-agent	2026-07-23 16:46:06 +08:00
lisheng.lisheng	26a69a7c99	fix(config-agent): align agent writers with cc-switch and official Model Studio docs - claude-code: honor CLAUDE_CONFIG_DIR; drop stale ANTHROPIC_API_KEY - qwen-code: write $version:3; security.auth carries selectedType only - opencode: tolerate JSONC (comments/trailing commas) via stripJsonc - openclaw: add --context-window flag (default 256000), full cost fields, agents.defaults.models allowlist - hermes: switch to official flat model.* block; api_mode only for anthropic endpoints - codex: official env_key + auth.json fallback; add --wire-api flag (default chat, responses for supported models)	2026-07-23 11:12:34 +08:00
chenanran555	1da3367de8	feat: fix ci	2026-07-22 17:44:50 +08:00
chenanran555	9e59b01326	feat: update openagentpack sdk	2026-07-22 17:01:14 +08:00
chenanran555	7cbd61dd5c	Merge remote-tracking branch 'origin/main' into feat/cma # Conflicts: # packages/commands/src/commands/auth/login.ts # packages/commands/src/commands/config/set.ts # packages/commands/src/index.ts # packages/core/src/client/index.ts # packages/core/src/config/schema.ts # skills/bailian-cli/reference/auth.md # skills/bailian-cli/reference/config.md # skills/bailian-cli/reference/index.md	2026-07-22 16:38:46 +08:00
chenanran555	1c9dac24e9	feat(cma): login时初始化agent相关的baseUrl	2026-07-22 14:20:24 +08:00
chenanran555	d6bd38a46a	feat(agent): agent相关cli命令的client层功能，对齐cli client的基础能力	2026-07-22 13:40:28 +08:00
Gong Shiqi	678f60be75	Merge pull request #115 from modelstudioai/release/1.10.1 chore(release): prepare 1.10.1	2026-07-22 11:35:36 +08:00
若麒	d11b55b956	chore(release): prepare 1.10.1	2026-07-22 11:30:43 +08:00
Gong Shiqi	e4e3f069e1	Merge pull request #112 from modelstudioai/chore/optimize-skill docs: optimize bailian-cli skill routing and consent rules	2026-07-22 10:56:15 +08:00
Gong Shiqi	440cbfe6ae	Merge pull request #114 from modelstudioai/feat/token-plan-default-models feat: update Token Plan defaults and support local image inputs	2026-07-22 10:52:35 +08:00
若麒	1adfe797bd	docs: simplify Bailian skill consent rules	2026-07-22 10:50:25 +08:00
Gong Shiqi	d04012b0a4	Merge pull request #113 from modelstudioai/feat/node-engines-limit Feat/node engines limit	2026-07-22 10:33:07 +08:00
若麒	81539005cc	Merge branch 'main' into feat/token-plan-default-models	2026-07-22 09:55:39 +08:00
若麒	4c566fd60e	feat(token-plan): support local images with base64 data URIs - convert local images to Base64 for Token Plan image and video commands - preserve the existing OSS upload flow for standard API Key profiles - use wan2.7-image as the default image model with the sync endpoint - hide full Base64 image content in dry-run output - add Token Plan compatibility tests and update related docs	2026-07-22 09:54:54 +08:00
rendianmeng	853ce3caae	docs: update README.zh.md	2026-07-21 14:10:49 +08:00
rendianmeng	3b779a708d	feat: node engines limit change	2026-07-21 13:55:38 +08:00
chenanran555	6329427b4d	feat(agent): add agent command group with session and state management	2026-07-21 10:43:22 +08:00
clh02467605	b4a2a1c42d	docs: optimize bailian-cli skill	2026-07-20 18:26:08 +08:00
若麒	4ca3e2de80	feat(config): update token-plan default models - switch the default text model to qwen3.8-max-preview - add dedicated T2V, I2V, and R2V model defaults - persist and consume per-mode video model settings - enable thinking when validating the qwen3.8 preview model	2026-07-20 16:44:53 +08:00
Gong Shiqi	1f91fa42fa	Merge pull request #109 from modelstudioai/feat/cli-access-token chore(release): prepare 1.10.0	2026-07-19 16:55:33 +08:00
若麒	39f12e1a78	chore(release): prepare 1.10.0	2026-07-19 16:47:29 +08:00
若麒	a853319dd0	feat(onboarding): add Token Plan setup guidance - add Token Plan subscription and login entry to CLI, README, INSTALL, and skill - document built-in Base URL and automatic key validation - remove the completed Token Plan integration design document	2026-07-19 16:05:35 +08:00
若麒	bc162f4678	Merge branch 'main' into feat/cli-access-token	2026-07-19 15:32:20 +08:00
Gong Shiqi	12ecac4d96	Merge pull request #107 from modelstudioai/feat/config-agent feat: add `bl config agent` command for one-click coding agent configuration	2026-07-19 11:48:36 +08:00
Gong Shiqi	52f6e267e6	Merge pull request #108 from modelstudioai/fix/bailian-cli-skill fix(skill): refine Bailian provider routing and consent	2026-07-19 11:09:43 +08:00
若麒	c9e5913034	Merge branch 'main' into fix/bailian-cli-skill	2026-07-19 11:03:25 +08:00
lisheng.lisheng	ba062c1a71	feat: add `bl config agent` command for one-click coding agent configuration Add `bl config agent` to configure a coding agent (Claude Code, Qwen Code, OpenCode, OpenClaw, Hermes, Codex) to use a DashScope/ModelStudio endpoint with a single command. Writers non-destructively merge into each agent's local config with a timestamped backup and atomic writes. - Field structures aligned to farion1231/cc-switch; qwen-code aligned to QwenLM/qwen-code source (modelProviders/security.auth keyed by protocol). - provider id unified as `bailian-cli` (qwen-code brands via model entry name + BAILIAN_CLI_API_KEY, since it keys by protocol). - Codex config.toml merged via smol-toml to preserve unrelated settings. - Add writer unit tests + config e2e cases; regenerate skill reference.	2026-07-18 19:29:53 +08:00
若麒	a03ba673be	fix(auth): clear model base URL on full logout	2026-07-17 15:57:23 +08:00
若麒	fc8351f136	fix(skill): refine provider routing and consent - scope bl preference to matched Bailian and multimodal tasks - ask once before provider-neutral remote or billable calls - avoid routing ordinary text, generic search, and ambiguous usage requests to bl	2026-07-13 19:38:04 +08:00