fix(e2e): use commands-local e2e map instead of importing cli

Author: hopelynd

AGENTS.md

@@ -19,31 +19,43 @@ monorepo 多包结构:
 - 产品 smoke: `packages/cli/tests/e2e/smoke.e2e.test.ts`、`packages/rag/tests/e2e/smoke.e2e.test.ts`
 - 一次跑全量 e2e: 根目录 `pnpm test:e2e`
 
+### 命令登记分层
+
+命令**实现**在 `packages/commands/src/commands/`;**路径映射**由各产品 / 测试 fixture 自行维护,库本身不预设:
+
+| 层           | 文件                                               | 作用                                   |
+| ------------ | -------------------------------------------------- | -------------------------------------- |
+| 单命令导出   | `packages/commands/src/index.ts`                   | 从实现文件 re-export,供产品与 e2e 引用 |
+| bl 产品 map  | `packages/cli/src/commands.ts`                     | `bl` 暴露的全量命令路径                |
+| rag 产品 map | `packages/rag/src/main.ts` 内 `commands`           | `rag` 裁剪后的命令路径(如 `retrieve`)  |
+| 契约 e2e map | `packages/commands/tests/fixtures/e2e-commands.ts` | 测试用全量 map,不依赖任何产品包        |
+
+`bl --help` 与 `tools/generate-reference.ts` 读 **`packages/cli/src/commands.ts`**,见 [command-add-remove.md](docs/agents/command-add-remove.md)。
+
 ### `packages/cli` 目录要点
 
 ```
 packages/cli/
 ├── src/main.ts              # bl 入口(createCli + commands)
+├── src/commands.ts          # bl 产品 command map
 └── tests/e2e/smoke.e2e.test.ts
 ```
 
-命令实现见 `packages/commands/src/commands/`;登记在 **`groups.ts`**。`bl --help` 与 `tools/generate-reference.ts` 生成的命令手册同源,见 [command-add-remove.md](docs/agents/command-add-remove.md)。
-
 非代码资产:
 
 - `tools/release/` — 发版自动化（CI 驱动，见 `.github/workflows/publish.yml`）
-- `tools/generate-reference.ts` — 从 `catalog.ts` 生成命令手册到 `skills/bailian-cli/reference/`
+- `tools/generate-reference.ts` — 从 `packages/cli/src/commands.ts` 生成命令手册到 `skills/bailian-cli/reference/`
 - `tools/sync-skill-metadata.ts` — 从 `packages/cli/package.json` 同步 `skills/bailian-cli/SKILL.md` 的 `metadata.version`（与 `generate:reference` 一并由根目录 `pnpm run sync:skill-assets` 及 pre-commit 执行）
 - `README.md` / `README.zh.md` — npm 和 GitHub 主页
 
 约定:
 
 - core 是纯库,不依赖 cli(详见下方通用约定)
-- 文件路径与命令路径一一对应:`packages/commands/src/commands/text/chat.ts` ↔ `bl text chat`
+- 文件路径与命令路径一一对应:`packages/commands/src/commands/text/chat.ts` ↔ `bl text chat`(路径 key 由产品 map 决定,rag 可 remap)
 - 单级命令:`commands/<name>.ts`(如 `update.ts`);两级:`commands/<group>/<action>.ts`
-- 命令登记在 **`packages/commands/src/commands/groups.ts`**
+- 新增命令:实现 + `index.ts` 导出 + `e2e-commands.ts` 登记;bl 暴露则同步 `cli/src/commands.ts`(详见 [command-add-remove.md](docs/agents/command-add-remove.md))
 
-Skill / 命令手册随 `skills/bailian-cli/` 经 `npx skills add modelstudioai/cli` 安装。`tools/generate-reference.ts` 从 catalog 生成命令手册到 `skills/bailian-cli/reference/`(纳入 git);与 `tools/sync-skill-metadata.ts` 一起在 **pre-commit**（`.vite-hooks/pre-commit`）及根脚本 `pnpm run sync:skill-assets` 中执行。
+Skill / 命令手册随 `skills/bailian-cli/` 经 `npx skills add modelstudioai/cli` 安装。`tools/generate-reference.ts` 从 `cli/src/commands.ts` 生成命令手册到 `skills/bailian-cli/reference/`(纳入 git);与 `tools/sync-skill-metadata.ts` 一起在 **pre-commit**（`.vite-hooks/pre-commit`）及根脚本 `pnpm run sync:skill-assets` 中执行。
 
 ## 业务场景索引
 
@@ -79,7 +91,7 @@ core 不应该知道 cli 的存在。具体表现:
 
 - core 不写 stderr,不调 `process.exit`(用 `console.*` 或 `throw`)
 - core 抛的 `BailianError`,hint 字符串不出现 `bl xxx` 命令名
-- core 不写死域名 / region / 追踪参数(URL 集中在 `packages/cli/src/urls.ts`)
+- core 不写死域名 / region / 追踪参数(URL 集中在 `packages/runtime/src/urls.ts`)
 - core 接收 cli 通过 `Config` 注入的 metadata(`clientName` / `clientVersion`)
 
 ### 3. 错误处理边界:CLI 不翻译服务端错误

docs/agents/cli-e2e-tests.md

@@ -4,17 +4,18 @@
 
 E2E 按包分层，与命令实现 / 产品入口解耦：
 
-| 层级             | 路径                                                                                   | 测什么                                                                            |
-| ---------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| **公共基建**     | `packages/commands/tests/e2e/core/`                                                    | `createCliRunner`、skip 判定、输出目录、global-setup                              |
-| **命令契约 e2e** | `packages/commands/tests/e2e/*.e2e.test.ts`                                            | help、缺参、dry-run、**真实集成**；跑 canonical 入口 `tests/fixtures/test-cli.ts` |
-| **产品 smoke**   | `packages/cli/tests/e2e/smoke.e2e.test.ts`、`packages/rag/tests/e2e/smoke.e2e.test.ts` | 版本、root help、命令面裁剪；跑各产品 `src/main.ts`                               |
+| 层级             | 路径                                                                                   | 测什么                                                                                           |
+| ---------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| **公共基建**     | `packages/commands/tests/e2e/core/`                                                    | `createCliRunner`、skip 判定、输出目录、global-setup                                             |
+| **契约 e2e map** | `packages/commands/tests/fixtures/e2e-commands.ts`                                     | 测试用全量 `{ "<path>": command }` map，仅依赖 `bailian-cli-commands` 单命令导出，不绑定任何产品 |
+| **命令契约 e2e** | `packages/commands/tests/e2e/*.e2e.test.ts`                                            | help、缺参、dry-run、**真实集成**；跑 `tests/fixtures/test-cli.ts`（引用上述 fixture map）       |
+| **产品 smoke**   | `packages/cli/tests/e2e/smoke.e2e.test.ts`、`packages/rag/tests/e2e/smoke.e2e.test.ts` | 版本、root help、命令面裁剪；跑各产品 `src/main.ts`                                              |
 
 > `commands/tests/e2e/core` 是 e2e 测试基建，与 `packages/core`（`bailian-cli-core`）无关。
 
 ## 触发条件
 
-- 新增/修改 `packages/commands/src/commands/` 下的 command（`groups.ts` 登记、`defineCommand` 实现、options/usage）
+- 新增/修改 `packages/commands/src/commands/` 下的 command（`src/index.ts` 单命令导出、`defineCommand` 实现、options/usage）
 - 新建或扩展 `packages/commands/tests/e2e/<topic>.e2e.test.ts` 用例
 - 新增/变更产品命令面（bl / rag）时同步维护对应 smoke 用例
 - 为命令补 help / 缺参 / dry-run / 真实集成测试
@@ -88,7 +89,8 @@ describe.skipIf(<ready>)("e2e: <topic>（DashScope …）", () => {
 
 ## 新增 command 检查清单
 
-- [ ] `packages/commands/src/commands/groups.ts` 登记 + `packages/commands/tests/e2e/<topic>.e2e.test.ts`（新建或扩展）
+- [ ] `packages/commands/src/index.ts` 导出 + `tests/fixtures/e2e-commands.ts` 登记路径 + `packages/commands/tests/e2e/<topic>.e2e.test.ts`（新建或扩展）
+- [ ] 若 bl 也暴露该命令，同步 `packages/cli/src/commands.ts` 产品 map
 - [ ] 若改了 `usage` / `options` / `examples`,跑 `pnpm --filter bailian-cli run generate:reference` 更新 `skills/bailian-cli/reference/` 并提交
 - [ ] 顶层：分组 help + 子命令 `--help`（多子命令则各一条 help）
 - [ ] skip 块：每个 required flag 缺参；可 dry-run 则加一条

docs/agents/command-add-remove.md

@@ -20,41 +20,47 @@
                      仅当子组下有 ≥2 个 action 时合理(否则拍平到两级)
 ```
 
-文件路径与命令路径必须 1:1 对齐。
+实现文件路径与命令语义 1:1 对齐;**产品在 map 里决定暴露路径**(rag 可将 `knowledge retrieve` remap 为 `retrieve`)。
 
 ## CLI 命令注册架构(必读)
 
-命令元数据以 **`catalog.ts` 为单一登记处**;`registry.ts` 只负责解析与打印 help,不再内嵌命令表或手写 Resources 列表。
+composable-cli:命令库只 export 单命令,**路径 map 由产品 / 测试各自注入**;`createCli` + `CommandRegistry` 在 `bailian-cli-runtime` 里解析 help。
 
 ```
-commands/<...>.ts   defineCommand({ name, description, usage, options, examples, run })
+packages/commands/src/commands/<...>.ts
+  defineCommand({ name, description, usage, options, examples, run })
         ↓
-commands/catalog.ts   export const commands: Record<string, Command>
+packages/commands/src/index.ts          单命令 re-export(无路径 preset)
         ↓
-   ┌────┴────┬──────────────────────┬─────────────────────┐
-   ↓         ↓                      ↓                     ↓
-registry.ts  main.ts      tools/generate-reference.ts   export-schema.ts
-(解析/help)  (入口)       → skills/bailian-cli/reference/index.md + <group>.md
+   ┌────┴────────────┬─────────────────────────┬──────────────────────────┐
+   ↓                 ↓                         ↓                          ↓
+cli/src/commands.ts  rag/src/main.ts   tests/fixtures/e2e-commands.ts   (其他产品…)
+(bl 全量 map)        (rag 裁剪 map)    (契约 e2e 全量 map)
+        ↓                 ↓                         ↓
+   createCli(commands, opts)  →  runtime/registry.ts(建树、resolve、printHelp)
+        ↓
+tools/generate-reference.ts 读 cli/src/commands.ts → skills/bailian-cli/reference/
 ```
 
-- **`packages/cli/src/commands/catalog.ts`**: `import` 命令模块 + `"<path>": handler` 映射;**不** `import registry.ts`(避免构建时循环依赖)
-- **`packages/cli/src/commands/index.ts`**: `export { commands } from "./catalog.ts"`(给包内 re-export 用)
-- **`packages/cli/src/registry.ts`**: `import { commands } from "./commands/catalog.ts"`,建树、`resolve`、`printHelp`;Commands / Global Flags 从 `Command` 元数据与 `GLOBAL_OPTIONS` **动态生成**
-- **`tools/generate-reference.ts`**: pre-commit / `pnpm run sync:skill-assets` 时读 `catalog.ts`,写 `skills/bailian-cli/reference/index.md`(索引) + `skills/bailian-cli/reference/<一级命令>.md`(详情,勿手改)。该目录**纳入 git**,随 `npx skills add modelstudioai/cli` 分发
+- **`packages/commands/src/index.ts`**: `export { default as textChat } from "./commands/text/chat.ts"` 等;**不**含 `"<path>": handler` 映射
+- **`packages/cli/src/commands.ts`**: bl 产品 map;`main.ts` 传入 `createCli`
+- **`packages/rag/src/main.ts`**: rag 产品 map(内联);路径可不同于 bl
+- **`packages/commands/tests/fixtures/e2e-commands.ts`**: 契约 e2e 全量 map;**不** import `packages/cli`
+- **`packages/runtime/src/registry.ts`**: 从注入的 `Record<string, Command>` 建树;Commands / Global Flags 从 `Command` 元数据与 `GLOBAL_OPTIONS` **动态生成**
+- **`tools/generate-reference.ts`**: pre-commit / `pnpm run sync:skill-assets` 时读 **`packages/cli/src/commands.ts`**,写 `skills/bailian-cli/reference/index.md`(索引) + `skills/bailian-cli/reference/<一级命令>.md`(详情,勿手改)。该目录**纳入 git**,随 `npx skills add modelstudioai/cli` 分发
 
-已删除、勿再引用:`commands/help.ts`、`registry.ts` 内联 `new CommandRegistry({...})`、`printRootHelp` 手写命令行。
+已删除、勿再引用:`packages/cli/src/commands/catalog.ts`、`groups.ts`、`packages/cli/src/registry.ts`、`config/export-schema.ts`。
 
 ## 必查清单
 
 ### A. 代码层
 
-- [ ] **新建/删除/移动**对应的 `packages/cli/src/commands/<...>.ts` 文件
-- [ ] **`packages/cli/src/commands/catalog.ts`**:
-  - 增删 `import xxx from "./.../xxx.ts"`
-  - 在 `export const commands` 里增删 `"<group> <action>": xxx`(key 与 `defineCommand({ name })` 一致)
-- [ ] **不要**在 `registry.ts` 里重复登记命令(已从 catalog 读取)
-- [ ] 如果命令需要跳过入口的默认 DashScope API key 引导(`ensureApiKey`),在对应 `defineCommand` 上设 `skipDefaultApiKeySetup: true`(字段定义见 `packages/core/src/types/command.ts`;`main.ts` 根据已解析的 `command` 读取)
-- [ ] **`config/export-schema.ts`**: 若新命令不适合作为 agent tool,评估是否加入 `SKIP_PREFIXES`;该文件在 `run()` 内 `import("../catalog.ts")`,勿顶层 import catalog 以免循环依赖
+- [ ] **新建/删除/移动**对应的 `packages/commands/src/commands/<...>.ts` 文件
+- [ ] **`packages/commands/src/index.ts`**: 增删 `export { default as xxx } from "./commands/.../xxx.ts"`
+- [ ] **`packages/commands/tests/fixtures/e2e-commands.ts`**: 增删 import 与 `"<path>": xxx`(契约 e2e 命令面)
+- [ ] **`packages/cli/src/commands.ts`**(bl 暴露该命令时): 同步 import 与 map key(key 与 `defineCommand({ name })` 一致)
+- [ ] **`packages/rag/src/main.ts`**(rag 暴露该命令时): 同步 import 与 map key(路径可按 rag 产品约定 remap)
+- [ ] 如果命令需要跳过入口的默认 DashScope API key 引导(`ensureApiKey`),在对应 `defineCommand` 上设 `skipDefaultApiKeySetup: true`(字段定义见 `packages/core/src/types/command.ts`;`createCli` 根据已解析的 `command` 读取)
 
 ### B. 文档层
 
@@ -64,13 +70,14 @@ registry.ts  main.ts      tools/generate-reference.ts   export-schema.ts
 
 ### C. 测试层
 
-- [ ] 按 [cli-e2e-tests.md](cli-e2e-tests.md) 新建或更新 `packages/cli/tests/e2e/<topic>.e2e.test.ts`
+- [ ] 按 [cli-e2e-tests.md](cli-e2e-tests.md) 新建或更新 `packages/commands/tests/e2e/<topic>.e2e.test.ts`
+- [ ] bl / rag 命令面变更时,同步对应 smoke:`packages/cli/tests/e2e/smoke.e2e.test.ts`、`packages/rag/tests/e2e/smoke.e2e.test.ts`
 - [ ] 删除命令时一并删对应 e2e
 
 ### D. 重命名特殊处理
 
 - [ ] 全仓 grep **旧命令名字符串**,确保以下位置全部更新:
-  - `catalog.ts` 的 key
+  - 各产品 / fixture map 的 key(`cli/src/commands.ts`、`e2e-commands.ts`、`rag/src/main.ts` 等)
   - error hints(cli 层)
   - `skills/bailian-cli/reference/`(重建后检查并提交)
   - README 示例
@@ -79,15 +86,17 @@ registry.ts  main.ts      tools/generate-reference.ts   export-schema.ts
 ## 完成后自查
 
 ```sh
-pnpm run sync:skill-assets   # reference/ + SKILL metadata.version 与 catalog / package.json 一致
+pnpm run sync:skill-assets   # reference/ + SKILL metadata.version 与 cli/commands.ts / package.json 一致
 node packages/cli/src/main.ts <new-command> --help
 node packages/cli/src/main.ts                        # 根 help 列表含新命令
-vp test packages/cli/tests/e2e/<topic>.e2e.test.ts   # 相关 e2e
+pnpm --filter bailian-cli-commands test tests/e2e/<topic>.e2e.test.ts
+pnpm --filter bailian-cli test tests/e2e/smoke.e2e.test.ts   # bl 命令面变更时
 ```
 
 ## 常见漏点
 
-- ✗ 只改了命令文件,忘了 **`catalog.ts`** → 命令不存在或 help 里没有
+- ✗ 只改了命令文件,忘了 **`index.ts` 导出** → 产品 / e2e 无法 import
+- ✗ 忘了 **`e2e-commands.ts`** → 契约 e2e 跑不起来或缺命令
+- ✗ bl 要暴露却忘了 **`cli/src/commands.ts`** → `bl --help` 里没有、reference 也不会生成
 - ✗ 手改 **`skills/bailian-cli/reference/*.md`** → 下次 generate 被覆盖;应改 `defineCommand` 后重新 generate 并提交
-- ✗ 在 `export-schema.ts` 顶层 `import catalog` → 可能与 registry 循环依赖
 - ✗ 单 action 的子组是反模式,新增时优先拍平为两级

packages/cli/src/commands.d.ts

@@ -1,5 +1,4 @@
 node_modules
 dist
-tests/**/*.d.ts
 *.log
 .DS_Store

packages/commands/.gitignore

@@ -0,0 +1,98 @@
+import type { Command } from "bailian-cli-core";
+import {
+  authLogin,
+  authStatus,
+  authLogout,
+  textChat,
+  textOmni,
+  imageGenerate,
+  imageEdit,
+  videoGenerate,
+  videoEdit,
+  videoRef,
+  videoTaskGet,
+  videoDownload,
+  visionDescribe,
+  configShow,
+  configSet,
+  update,
+  appCall,
+  appList,
+  memoryAdd,
+  memorySearch,
+  memoryList,
+  memoryUpdate,
+  memoryDelete,
+  memoryProfileCreate,
+  memoryProfileGet,
+  knowledgeRetrieve,
+  mcpCall,
+  mcpList,
+  mcpTools,
+  searchWeb,
+  speechSynthesize,
+  speechRecognize,
+  fileUpload,
+  consoleCall,
+  usageFree,
+  usageFreetier,
+  usageStats,
+  pipelineRun,
+  pipelineValidate,
+  advisorRecommend,
+  workspaceList,
+  quotaList,
+  quotaRequest,
+  quotaHistory,
+  quotaCheck,
+} from "bailian-cli-commands";
+
+// 契约 e2e 全量命令面：测试关注点，不绑定任何产品 preset。
+// 路径映射由测试 fixture 维护；新增命令时需同步更新本 map 与 src/index.ts 导出。
+export const e2eCommands: Record<string, Command> = {
+  "auth login": authLogin,
+  "auth status": authStatus,
+  "auth logout": authLogout,
+  "text chat": textChat,
+  omni: textOmni,
+  "image generate": imageGenerate,
+  "image edit": imageEdit,
+  "video generate": videoGenerate,
+  "video edit": videoEdit,
+  "video ref": videoRef,
+  "video task get": videoTaskGet,
+  "video download": videoDownload,
+  "vision describe": visionDescribe,
+  "config show": configShow,
+  "config set": configSet,
+  update,
+  "app call": appCall,
+  "app list": appList,
+  "memory add": memoryAdd,
+  "memory search": memorySearch,
+  "memory list": memoryList,
+  "memory update": memoryUpdate,
+  "memory delete": memoryDelete,
+  "memory profile create": memoryProfileCreate,
+  "memory profile get": memoryProfileGet,
+  "knowledge retrieve": knowledgeRetrieve,
+  "mcp call": mcpCall,
+  "mcp list": mcpList,
+  "mcp tools": mcpTools,
+  "search web": searchWeb,
+  "speech synthesize": speechSynthesize,
+  "speech recognize": speechRecognize,
+  "file upload": fileUpload,
+  "console call": consoleCall,
+  "usage free": usageFree,
+  "usage freetier": usageFreetier,
+  "usage stats": usageStats,
+  "pipeline run": pipelineRun,
+  "pipeline validate": pipelineValidate,
+  "advisor recommend": advisorRecommend,
+  "workspace list": workspaceList,
+  "quota list": quotaList,
+  "quota request": quotaRequest,
+  "quota history": quotaHistory,
+  "quota check": quotaCheck,
+};

packages/commands/tests/fixtures/e2e-commands.ts

@@ -1,8 +1,8 @@
 import { createCli } from "bailian-cli-runtime";
-import { commands } from "../../../cli/src/commands.ts";
+import { e2eCommands } from "./e2e-commands.ts";
 
-// 契约 e2e 专用 canonical 入口：全量 commands，与 bl 命令面一致。
-void createCli(commands, {
+// 契约 e2e 专用 canonical 入口：全量 commands，独立于 bl/rag 产品。
+void createCli(e2eCommands, {
   binName: "bl",
   version: "0.0.0-test",
   clientName: "bailian-cli",

packages/commands/tests/fixtures/test-cli.ts

@@ -17,6 +17,5 @@
     "isolatedModules": true,
     "verbatimModuleSyntax": true,
     "skipLibCheck": true
-  },
-  "exclude": ["tests/**/*"]
+  }
 }