test(e2e): move contract e2e to commands

AGENTS.md

@@ -4,28 +4,30 @@
 
 ## 项目地图
 
-monorepo 双包结构:
+monorepo 多包结构:
 
-- `packages/cli` — `bailian-cli` 包,CLI 命令、UI、入口
-- `packages/core` — `bailian-cli-core` 包,鉴权 / HTTP / 类型,纯逻辑层
+- `packages/core` — `bailian-cli-core`,鉴权 / HTTP / 类型,纯逻辑层
+- `packages/runtime` — `bailian-cli-runtime`,`createCli` / registry / args / output
+- `packages/commands` — `bailian-cli-commands`,命令实现 + **契约 e2e** + e2e 公共基建(`tests/e2e/core`)
+- `packages/cli` — `bailian-cli`,`bl` 产品入口 + smoke e2e
+- `packages/rag` — `bailian-cli-rag`,`rag` 产品入口 + smoke e2e
+
+### E2E 测试分布
+
+- 契约 e2e(help / dry-run / 真实集成): `packages/commands/tests/e2e/`
+- e2e 基建(`createCliRunner` 等): `packages/commands/tests/e2e/core/`（cli/rag 以相对路径引用）
+- 产品 smoke: `packages/cli/tests/e2e/smoke.e2e.test.ts`、`packages/rag/tests/e2e/smoke.e2e.test.ts`
+- 一次跑全量 e2e: 根目录 `pnpm test:e2e`
 
 ### `packages/cli` 目录要点
 
 ```
 packages/cli/
-├── src/
-│   ├── main.ts              # 入口、鉴权分支、调用 registry
-│   ├── registry.ts          # 命令树解析、动态 help(读 catalog)
-│   ├── commands/
-│   │   ├── catalog.ts       # 命令总表(登记处,构建脚本也读它)
-│   │   ├── index.ts         # re-export commands
-│   │   └── <group>/...ts    # 各命令 defineCommand 实现
-│   ├── output/              # CLI 输出、prompt、progress
-│   └── urls.ts              # 控制台/文档 URL(仅 cli)
-└── tests/e2e/
+├── src/main.ts              # bl 入口(createCli + commands)
+└── tests/e2e/smoke.e2e.test.ts
 ```
 
-Skill / 命令手册随 `skills/bailian-cli/` 经 `npx skills add modelstudioai/cli` 安装。`tools/generate-reference.ts` 从 `catalog.ts` 生成命令手册到 `skills/bailian-cli/reference/`(纳入 git);与 `tools/sync-skill-metadata.ts` 一起在 **pre-commit**（`.vite-hooks/pre-commit`）及根脚本 `pnpm run sync:skill-assets` 中执行。
+命令实现见 `packages/commands/src/commands/`;登记在 **`groups.ts`**。`bl --help` 与 `tools/generate-reference.ts` 生成的命令手册同源,见 [command-add-remove.md](docs/agents/command-add-remove.md)。
 
 非代码资产:
 
@@ -37,9 +39,11 @@ Skill / 命令手册随 `skills/bailian-cli/` 经 `npx skills add modelstudioai/
 约定:
 
 - core 是纯库,不依赖 cli(详见下方通用约定)
-- 文件路径与命令路径一一对应:`commands/text/chat.ts` ↔ `bl text chat`
+- 文件路径与命令路径一一对应:`packages/commands/src/commands/text/chat.ts` ↔ `bl text chat`
 - 单级命令:`commands/<name>.ts`(如 `update.ts`);两级:`commands/<group>/<action>.ts`
-- 命令登记在 **`catalog.ts`**;`bl --help` 与 `tools/generate-reference.ts` 生成的命令手册同源,见 [command-add-remove.md](docs/agents/command-add-remove.md)
+- 命令登记在 **`packages/commands/src/commands/groups.ts`**
+
+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` 中执行。
 
 ## 业务场景索引
 

docs/agents/cli-e2e-tests.md

@@ -1,19 +1,48 @@
 # CLI E2E 测试规范
 
+## 架构（composable-cli）
+
+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`                               |
+
+> `commands/tests/e2e/core` 是 e2e 测试基建，与 `packages/core`（`bailian-cli-core`）无关。
+
 ## 触发条件
 
-- 新增/修改 `packages/cli/src` 下的 command（`commands/catalog.ts` 登记、`defineCommand` 实现、options/usage）
-- 新建或扩展 `packages/cli/tests/e2e/*.e2e.test.ts` 用例
+- 新增/修改 `packages/commands/src/commands/` 下的 command（`groups.ts` 登记、`defineCommand` 实现、options/usage）
+- 新建或扩展 `packages/commands/tests/e2e/<topic>.e2e.test.ts` 用例
+- 新增/变更产品命令面（bl / rag）时同步维护对应 smoke 用例
 - 为命令补 help / 缺参 / dry-run / 真实集成测试
 
-以上情况必须同步维护 `packages/cli/tests/e2e/<topic>.e2e.test.ts`。跑测与环境变量见 `.cursor/skills/bailian-cli-e2e/SKILL.md`。
-
 ## 文件与工具
 
-- 路径：`packages/cli/tests/e2e/<kebab-topic>.e2e.test.ts`
-- 框架：`vite-plus/test`；子进程跑 CLI：`runCli` from `./helpers.ts`
-- 解析 JSON stdout：`parseStdoutJson`；输出目录：`makeE2eOutputDir(e2eLabelFromMetaUrl(import.meta.url))`
-- 长任务：`cliTimeoutPrefix()`；视频用例加 `test(..., 3_600_000)` 等显式超时
+- **契约 e2e 路径**：`packages/commands/tests/e2e/<kebab-topic>.e2e.test.ts`
+- **框架**：`vite-plus/test`；契约测试 `runCli` from `./setup.ts`；cli/rag smoke 通过相对路径引用 `packages/commands/tests/e2e/core/`
+- **解析 JSON stdout**：`parseStdoutJson`；输出目录：`makeE2eOutputDir(e2eLabelFromMetaUrl(import.meta.url))`
+- **长任务**：`cliTimeoutPrefix()`；视频用例加 `test(..., 3_600_000)` 等显式超时
+
+## 跑测命令
+
+```sh
+# 一次跑全部 e2e（契约 + bl/rag smoke）
+pnpm test:e2e
+
+# 仅命令契约（含真实集成，需 BAILIAN_E2E=1 等）
+pnpm --filter bailian-cli-commands test
+
+# 单文件（在 bailian-cli-commands 包目录下运行，路径相对于 packages/commands）
+pnpm --filter bailian-cli-commands test tests/e2e/text-chat.e2e.test.ts
+
+# 全 monorepo（unit + e2e）
+vp run -r test
+```
+
+环境变量与 skip 条件见 `.cursor/skills/bailian-cli-e2e/SKILL.md`（若存在）或下文 skip 表。
 
 ## 双层 describe（固定结构）
 
@@ -32,7 +61,7 @@ describe.skipIf(<ready>)("e2e: <topic>（DashScope …）", () => {
 });
 ```
 
-## skip 条件（helpers.ts）
+## skip 条件（`tests/e2e/core/skip.ts`）
 
 | 场景                | 条件                                                  |
 | ------------------- | ----------------------------------------------------- |
@@ -59,12 +88,13 @@ describe.skipIf(<ready>)("e2e: <topic>（DashScope …）", () => {
 
 ## 新增 command 检查清单
 
-- [ ] `commands/catalog.ts` 登记 + `tests/e2e/<topic>.e2e.test.ts`（新建或扩展）
+- [ ] `packages/commands/src/commands/groups.ts` 登记 + `packages/commands/tests/e2e/<topic>.e2e.test.ts`（新建或扩展）
 - [ ] 若改了 `usage` / `options` / `examples`,跑 `pnpm --filter bailian-cli run generate:reference` 更新 `skills/bailian-cli/reference/` 并提交
 - [ ] 顶层：分组 help + 子命令 `--help`（多子命令则各一条 help）
 - [ ] skip 块：每个 required flag 缺参；可 dry-run 则加一条
 - [ ] 至少一条真实集成（或说明为何仅 smoke）；不破坏已有集成用例顺序
-- [ ] `pnpm test packages/cli/tests/e2e/<file>` 通过
+- [ ] 若 bl/rag 命令面变更，更新对应 smoke 用例
+- [ ] `pnpm --filter bailian-cli-commands test tests/e2e/<file>` 通过
 
 ## 示例片段
 
@@ -97,4 +127,4 @@ test("foo bar --dry-run 仅输出计划", async () => {
 - **E2E**：单条/少量调用、断言固定、可进 `vp test`（见上文 skip 条件）
 - **批量压测**：`packages/cli/tests/stress/run.mjs` + `targets/*.mjs`，并发 + 报告，**仅手动** `pnpm run test:stress -- <target>`
 
-勿把压测并入 E2E 或默认 CI。详见 [stress-batch-tests.md](stress-batch-tests.md)。
+勿把压测并入 E2E 或默认 CI。详见 [stress-batch-tests.md](stress-batch-tests.md).

package.json

@@ -16,7 +16,7 @@
     "ready": "vp check && vp run -r test && vp run -r build",
     "prepare": "vp config",
     "check": "vp check",
-    "sync:skill-assets": "pnpm --filter bailian-cli-core run build && pnpm --filter bailian-cli run generate:reference && pnpm --filter bailian-cli run sync:skill-version",
+    "sync:skill-assets": "pnpm --filter bailian-cli-core run build && pnpm --filter bailian-cli-runtime run build && pnpm --filter bailian-cli-commands run build && pnpm --filter bailian-cli run generate:reference && pnpm --filter bailian-cli run sync:skill-version",
     "dev": "pnpm -F bailian-cli-core dev",
     "bl": "pnpm -F bailian-cli dev",
     "rag": "pnpm -F bailian-cli-rag dev",

packages/cli/src/commands.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "bailian-cli-core";
+export declare const commands: Record<string, Command>;

packages/cli/src/main.ts

@@ -2,7 +2,7 @@ import { createCli } from "bailian-cli-runtime";
 import { commands } from "./commands.ts";
 import pkg from "../package.json" with { type: "json" };
 
-createCli(commands, {
+void createCli(commands, {
   binName: "bl",
   version: pkg.version,
   clientName: "bailian-cli",