feat(runtime): add unified confirmation gate for high-risk commands

Author: XXPermanentXX

docs/agents/cli-e2e-tests.md

@@ -79,6 +79,13 @@ describe.skipIf(<ready>)("e2e: <topic>（DashScope …）", () => {
 3. **--dry-run**：实现在联网/上传/写盘**之前**返回；断言 stdout JSON/文本
 4. **真实集成**：放在 skip 块**末尾**
 
+高风险命令额外要求：
+
+- `--help` 展示 runtime 注入的 `--yes`
+- 无 `--yes` 返回 exit code 7 和 JSON `type: "requires_confirmation"`
+- `--dry-run` 无需 `--yes`，且必须证明在任何远端请求或本地写入之前返回
+- runtime 的离线 high-risk fixture 必须覆盖带 `--yes` 确实进入 `run()`，并断言 `yes` 不进入 command 自有 flags
+
 ## Journey 层（用户旅程全链路）
 
 - **定位**：命令 E2E 验单命令契约；journey 验“用户带着目标跨命令走通回路”，结构性断言不在 journey 重复

docs/agents/command-add-remove.md

@@ -71,7 +71,9 @@ packages/commands/src/index.ts
   - `usageArgs`(不含 bin/path 前缀)
   - `exampleArgs`(不含 bin/path 前缀)
   - `validate`(跨 flag 校验)
+  - 高风险命令必须声明 `risk: { level: "high", message: <双语文案> }`;`--yes` 由 runtime 注入,命令不得自行声明
   - 普通业务命令的 `run(ctx)` 只读 `ctx.flags` / `ctx.settings` / `ctx.client`
+  - 声明 `risk` 的 `run(ctx)` 必须在任何远端请求或本地写入之前处理 `ctx.settings.dryRun` 并返回预览;runtime 只负责确认闸门,不替命令实现 dry-run
   - `commands/auth/**` 可用 `ctx.authStore`,`commands/config/**` 可用 `ctx.configStore`;不要把这些持久化能力扩散到普通业务命令
   - `commands/plugin/**` 可用 `ctx.commandPacks`;产品 policy 由 runtime 绑定,命令不要自行 import 产品入口
 - [ ] 用户可见 Help 文案在命令文件中就近提供 `en-US` / `zh-CN`:命令 `description`、flag `description`、`notes` 和包含自然语言的 `exampleArgs`;纯命令语法示例可保留为字符串,服务端错误不翻译

docs/agents/telemetry-change.md

@@ -17,11 +17,12 @@
   │    ├─ ~/.bailian/telemetry.jsonl
   │    └─ AEM(pid=bailian-cli-node, event name=命令路径)
   │
-  └─ authStage
-       ├─ apiKey  → DashScope / 模型域
-       ├─ console → Bailian Console Gateway
-       ├─ openapi → 阿里云 OpenAPI
-       └─ none    → 无凭证域；本地命令也仍有 AEM 命令事件
+  └─ confirmationStage
+       └─ versionCheckStage → authStage
+            ├─ apiKey  → DashScope / 模型域
+            ├─ console → Bailian Console Gateway
+            ├─ openapi → 阿里云 OpenAPI
+            └─ none    → 无凭证域；本地命令也仍有 AEM 命令事件
 ```
 
 ### 1. 三套鉴权与埋点标识
@@ -77,7 +78,7 @@ source-config 只用于百炼 / DashScope API 侧消费，不发送到通用网
 
 ### 3. 全命令 AEM 客户端埋点
 
-`packages/runtime/src/middleware.ts` 的 `telemetryStage` 包裹 `authStage` 与命令执行，因此成功、业务失败、网络失败和鉴权失败都会形成一次命令事件。事件名是空格连接的命令路径，例如 `text chat`。
+`packages/runtime/src/middleware.ts` 的 `telemetryStage` 包裹确认闸门、`authStage` 与命令执行，因此成功、确认未通过、业务失败、网络失败和鉴权失败都会形成一次命令事件。事件名是空格连接的命令路径，例如 `text chat`。确认闸门仍位于版本检查、鉴权和业务执行之前，不会因为埋点而放行高风险操作。
 
 以下情况不会形成命令事件，因为没有进入 middleware 的 `run`：
 
@@ -92,7 +93,7 @@ source-config 只用于百炼 / DashScope API 侧消费，不发送到通用网
 - `command`、`timestamp`、`durationMs`、`success`
 - `cliVersion`、`nodeVersion`、`os`
 - `authMethod`
-- 失败时的 `errorMessage`、`httpStatus`、`requestId`
+- 失败时的 `errorMessage`、`exitCode`、`httpStatus`、`requestId`
 - 安全 allowlist 过滤后的 `params`
 
 参数默认不上传，只有 `packages/core/src/telemetry/tracker.ts` 的 `PARAM_ALLOWLIST` 中字段会进入事件。不得加入 prompt、凭证、文件路径、URL、账号/租户/工作空间 ID 或其他用户内容。
@@ -108,16 +109,16 @@ source-config 只用于百炼 / DashScope API 侧消费，不发送到通用网
 
 AEM 映射：
 
-| AEM 字段   | 内容                                      |
-| ---------- | ----------------------------------------- |
-| event name | 命令路径                                  |
-| `et`       | `EXP`                                     |
-| `ext`      | 除 `command`、`params` 外的结构化事件字段 |
-| `c1`       | allowlist 参数                            |
-| `c2`       | `success` / `failure`                     |
-| `c3`       | HTTP status                               |
-| `c4`       | 错误文案，最多 500 字符                   |
-| `c5`       | request ID                                |
+| AEM 字段   | 内容                                                               |
+| ---------- | ------------------------------------------------------------------ |
+| event name | 命令路径                                                           |
+| `et`       | `EXP`                                                              |
+| `ext`      | 除 `command`、`params` 外的结构化事件字段，包含失败时的 `exitCode` |
+| `c1`       | allowlist 参数                                                     |
+| `c2`       | `success` / `failure`                                              |
+| `c3`       | HTTP status                                                        |
+| `c4`       | 错误文案，最多 500 字符                                            |
+| `c5`       | request ID                                                         |
 
 远端发送是 best-effort，不得阻塞命令或改变退出码。正常退出最多等待 1 秒，SIGINT 最多等待 500 ms。
 
@@ -144,6 +145,7 @@ AEM 映射：
 - [ ] 更新 `TrackingEvent`、`createTrackingEvent()` 与 `buildRemoteAemOptions()` 的字段映射
 - [ ] 本地 JSONL 与远端 AEM 必须基于同一结构化事件，不能维护两套字段口径
 - [ ] 成功与失败均覆盖；遥测异常必须静默且不改变业务退出码
+- [ ] runtime 本地语义错误应记录 `exitCode`；新增字段默认随 AEM `ext` 上报，无需占用新的 `c1`—`c5`
 - [ ] 检查 `DO_NOT_TRACK=1` 与 `telemetry: false` 两个关闭入口
 - [ ] 错误字段不得额外拼接 token、请求体、prompt 或本地路径
 

docs/knowledge/doc.md

@@ -190,11 +190,11 @@ bl knowledge doc delete --index-id <id> --doc-id <id> [flags]
 
 **参数**
 
-| 参数              | 类型   | 必填 | 说明              |
-| ----------------- | ------ | ---- | ----------------- |
-| `--index-id <id>` | string | 是   | 知识库 ID         |
-| `--doc-id <id>`   | array  | 是   | 文档 ID（可重复） |
-| `--yes`           | switch | 否   | 跳过确认提示      |
+| 参数              | 类型   | 必填 | 说明               |
+| ----------------- | ------ | ---- | ------------------ |
+| `--index-id <id>` | string | 是   | 知识库 ID          |
+| `--doc-id <id>`   | array  | 是   | 文档 ID（可重复）  |
+| `--yes`           | switch | 否   | 显式确认高风险操作 |
 
 **输出**
 
@@ -223,7 +223,7 @@ json 模式：返回 API 原始响应，`data.deleted[]` 为实际删除的 ID 
 # 删除单个文档
 bl knowledge doc delete --index-id idx-xxx --doc-id doc-xxx --workspace-id ws-xxx
 
-# 批量删除，跳过确认
+# 用户明确确认后批量删除
 bl knowledge doc delete --index-id idx-xxx --doc-id doc-a --doc-id doc-b --yes
 ```
 

docs/kscli/doc.md

@@ -190,11 +190,11 @@ kscli doc delete --index-id <id> --doc-id <id> [flags]
 
 **参数**
 
-| 参数              | 类型   | 必填 | 说明              |
-| ----------------- | ------ | ---- | ----------------- |
-| `--index-id <id>` | string | 是   | 知识库 ID         |
-| `--doc-id <id>`   | array  | 是   | 文档 ID（可重复） |
-| `--yes`           | switch | 否   | 跳过确认提示      |
+| 参数              | 类型   | 必填 | 说明               |
+| ----------------- | ------ | ---- | ------------------ |
+| `--index-id <id>` | string | 是   | 知识库 ID          |
+| `--doc-id <id>`   | array  | 是   | 文档 ID（可重复）  |
+| `--yes`           | switch | 否   | 显式确认高风险操作 |
 
 **输出**
 
@@ -223,7 +223,7 @@ json 模式：返回 API 原始响应，`data.deleted[]` 为实际删除的 ID 
 # 删除单个文档
 kscli doc delete --index-id idx-xxx --doc-id doc-xxx --workspace-id ws-xxx
 
-# 批量删除，跳过确认
+# 用户明确确认后批量删除
 kscli doc delete --index-id idx-xxx --doc-id doc-a --doc-id doc-b --yes
 ```
 

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

@@ -53,6 +53,7 @@ describe("e2e: Command Pack", () => {
     expect(linkedJson.linked.commands).toEqual([
       "agent credential",
       "agent credential-denied",
+      "agent dangerous",
       "agent fail",
       "agent output",
       "agent ping",
@@ -96,6 +97,34 @@ describe("e2e: Command Pack", () => {
     expect(failed.stderr).toContain("Use agent fail only in tests.");
   });
 
+  test("high-risk 命令由 runtime 统一确认并支持安全 dry-run", async () => {
+    const dangerousHelp = await runCli(["agent", "dangerous", "--help"], env());
+    expect(dangerousHelp.exitCode, dangerousHelp.stderr).toBe(0);
+    expect(dangerousHelp.stderr).toContain("--yes");
+
+    const unconfirmed = await runCli(["agent", "dangerous", "--output", "json"], env());
+    expect(unconfirmed.exitCode).toBe(7);
+    expect(JSON.parse(unconfirmed.stderr)).toMatchObject({
+      error: { code: 7, type: "requires_confirmation" },
+    });
+
+    const confirmed = await runCli(["agent", "dangerous", "--yes", "--output", "json"], env());
+    expect(confirmed.exitCode, confirmed.stderr).toBe(0);
+    expect(parseStdoutJson(confirmed.stdout)).toEqual({
+      executed: true,
+      dry_run: false,
+      command_flags: [],
+    });
+
+    const preview = await runCli(["agent", "dangerous", "--dry-run", "--output", "json"], env());
+    expect(preview.exitCode, preview.stderr).toBe(0);
+    expect(parseStdoutJson(preview.stdout)).toEqual({
+      executed: false,
+      dry_run: true,
+      command_flags: [],
+    });
+  });
+
   test("plugin list 输出加载状态", async () => {
     const result = await runCli(["plugin", "list", "--output", "json"], env());
     expect(result.exitCode, result.stderr).toBe(0);
@@ -109,6 +138,7 @@ describe("e2e: Command Pack", () => {
         commands: [
           "agent credential",
           "agent credential-denied",
+          "agent dangerous",
           "agent fail",
           "agent output",
           "agent ping",

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

@@ -19,6 +19,26 @@ const ping = {
   },
 };
 
+const dangerous = {
+  description: "Exercise runtime confirmation for a high-risk Command Pack command",
+  auth: "none",
+  risk: {
+    level: "high",
+    message: {
+      "en-US": "This fixture represents a high-risk operation.",
+      "zh-CN": "该测试命令代表高风险操作。",
+    },
+  },
+  async run(ctx) {
+    const dryRun = ctx.settings.dryRun;
+    ctx.output.result({
+      executed: !dryRun,
+      dry_run: dryRun,
+      command_flags: Object.keys(ctx.flags),
+    });
+  },
+};
+
 const credential = {
   description: "Read an API key through the Command Pack host adapter",
   auth: "apiKey",
@@ -55,6 +75,7 @@ const fail = {
 export default {
   "agent credential": credential,
   "agent credential-denied": credentialDenied,
+  "agent dangerous": dangerous,
   "agent fail": fail,
   "agent output": output,
   "agent ping": ping,

packages/commands/src/commands/knowledge/doc-delete.ts

@@ -6,7 +6,7 @@ import {
   type FlagsDef,
   type RagDeleteFileResponse,
 } from "bailian-cli-core";
-import { emitResult, emitBare, confirmDangerousAction } from "bailian-cli-runtime";
+import { emitResult, emitBare } from "bailian-cli-runtime";
 import { resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
 
 const DOC_DELETE_FLAGS = {
@@ -25,28 +25,22 @@ const DOC_DELETE_FLAGS = {
     },
     required: true,
   },
-  yes: {
-    type: "switch",
-    description: { "en-US": "Skip the confirmation prompt", "zh-CN": "跳过确认提示" },
-  },
   ...WORKSPACE_FLAG,
 } satisfies FlagsDef;
 
-/** Confirmation summary: list all doc_ids up to 5, otherwise show the first 5 + total count */
-function buildDeleteSummary(indexId: string, docIds: string[]): string {
-  const listed =
-    docIds.length <= 5
-      ? docIds.join("\n  ")
-      : `${docIds.slice(0, 5).join("\n  ")}\n  ... (${docIds.length} documents total)`;
-  return `Delete ${docIds.length} document(s) from knowledge base ${indexId}:\n  ${listed}\nDocuments and all their chunks are permanently removed from the index. This cannot be undone.`;
-}
-
 export default defineCommand({
   description: {
     "en-US": "Delete documents and their chunks from a knowledge base",
     "zh-CN": "从知识库中删除文档及其 Chunk",
   },
   auth: "apiKey",
+  risk: {
+    level: "high",
+    message: {
+      "en-US": "This permanently deletes the selected documents and all of their chunks.",
+      "zh-CN": "该操作会永久删除所选文档及其全部 Chunk，且无法撤销。",
+    },
+  },
   usageArgs: "--index-id <id> --doc-id <id> [flags]",
   flags: DOC_DELETE_FLAGS,
   notes: [
@@ -72,7 +66,7 @@ export default defineCommand({
     },
   ],
   exampleArgs: [
-    "--index-id idx-xxx --doc-id file-xxx --workspace-id ws-xxx",
+    "--index-id idx-xxx --doc-id file-xxx --workspace-id ws-xxx --dry-run",
     "--index-id idx-xxx --doc-id file-a --doc-id file-b --yes",
   ],
   async run(ctx) {
@@ -89,11 +83,6 @@ export default defineCommand({
       return;
     }
 
-    await confirmDangerousAction(
-      buildDeleteSummary(flags.indexId, flags.docId),
-      flags.yes ?? false,
-    );
-
     const response = await ctx.client.requestJson<RagDeleteFileResponse>({
       path: endpoint,
       method: "POST",

packages/commands/tests/e2e/knowledge/knowledge-doc-delete.e2e.test.ts

@@ -66,7 +66,7 @@ describe("e2e: knowledge doc delete", () => {
     expect(data.request?.doc_ids).toEqual(["file_a", "file_b"]);
   });
 
-  test("非 TTY 无 --yes 报 USAGE (2)", async () => {
+  test("无 --yes 返回确认请求 (7)", async () => {
     const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_DELETE_ROUTES, [
       "knowledge",
       "doc",
@@ -79,9 +79,18 @@ describe("e2e: knowledge doc delete", () => {
       "sk-fake",
       "--workspace-id",
       "ws_test",
+      "--output",
+      "json",
     ]);
-    expect(exitCode).toBe(2);
-    expect(stderr).toMatch(/--yes/);
+    expect(exitCode).toBe(7);
+    expect(JSON.parse(stderr)).toMatchObject({
+      error: {
+        code: 7,
+        type: "requires_confirmation",
+        hint: expect.stringContaining("--yes"),
+      },
+    });
+    expect(stderr).not.toContain("sk-fake");
   });
 });
 

packages/core/src/errors/codes.ts

@@ -6,6 +6,7 @@ export const ExitCode = {
   QUOTA: 4,
   TIMEOUT: 5,
   NETWORK: 6,
+  CONFIRMATION_REQUIRED: 7,
   CONTENT_FILTER: 10,
 } as const;