refactor(cli): unify output contracts for agent-facing commands

.github/workflows/ci.yml

@@ -9,9 +9,13 @@ concurrency:
   group: ci-${{ github.ref }}
   cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
+permissions:
+  contents: read
+  actions: read
+
 jobs:
-  check:
-    name: lint + typecheck + test
+  quality:
+    name: lint + typecheck + build
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
@@ -23,7 +27,32 @@ jobs:
           node-version: "22"
           cache: pnpm
 
-      # Keep native-fetch and compiled Binary tests on the release Bun version.
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm run sync:skill-assets
+
+      - run: pnpm -r --filter "./packages/*" build
+
+      - run: pnpm run check
+
+  test:
+    name: test shard ${{ matrix.shard }}/4
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3, 4]
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: pnpm/action-setup@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+          cache: pnpm
+
+      # Every shard keeps the real Node/Bun/compiled-binary coverage.
       - uses: oven-sh/setup-bun@v2
         with:
           bun-version: "1.3.14"
@@ -34,6 +63,74 @@ jobs:
 
       - run: pnpm -r --filter "./packages/*" build
 
-      - run: pnpm run check
+      - name: Run test shard
+        run: >-
+          pnpm exec vp test --shard=${{ matrix.shard }}/4
+          --reporter=default --reporter=blob --reporter=json
+          --outputFile.blob=.ci-test-results/blob/shard-${{ matrix.shard }}.json
+          --outputFile.json=.ci-test-results/json/shard-${{ matrix.shard }}.json
 
-      - run: pnpm test
+      - name: Upload shard reports
+        if: ${{ always() }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: test-shard-${{ matrix.shard }}
+          path: .ci-test-results/
+          include-hidden-files: true
+          if-no-files-found: error
+          retention-days: 3
+
+  # Keep the existing required-check identity. Upstream failure/skip/cancellation
+  # must produce a failing check, rather than silently skipping the gate.
+  check:
+    name: lint + typecheck + test
+    if: ${{ always() }}
+    needs: [quality, test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: pnpm/action-setup@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - name: Download shard reports
+        id: download
+        uses: actions/download-artifact@v8
+        with:
+          pattern: test-shard-*
+          path: .ci-test-results
+          merge-multiple: true
+
+      # list --filesOnly discovers the full inventory, independently of sharding.
+      - name: Discover complete test inventory
+        run: pnpm exec vp test list --filesOnly --json=.ci-test-inventory.json
+
+      - name: Verify complete shard coverage
+        if: ${{ always() }}
+        env:
+          QUALITY_RESULT: ${{ needs.quality.result }}
+          TEST_RESULT: ${{ needs.test.result }}
+        run: >-
+          node tools/ci/verify-shard-reports.mjs
+          --reports .ci-test-results --inventory .ci-test-inventory.json --shards 4
+
+      - name: Merge test reports
+        if: ${{ always() && steps.download.outcome == 'success' }}
+        run: >-
+          pnpm exec vp test --mergeReports=.ci-test-results/blob
+          --reporter=default --reporter=json --outputFile.json=.ci-test-summary.json
+
+      - name: Upload merged report
+        if: ${{ always() }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: test-summary
+          path: .ci-test-summary.json
+          include-hidden-files: true
+          retention-days: 3

.gitignore

@@ -46,6 +46,9 @@ tools/generated
 
 # Test & scene outputs
 /test/
+/.ci-test-results/
+/.ci-test-inventory.json
+/.ci-test-summary.json
 packages/cli/scene/**/outputs/
 
 # Environment variables (sensitive data)

AGENTS.md

@@ -61,8 +61,9 @@ Skill / 命令手册随 `skills/bailian-*/` 经 `bl skill init` 安装（装齐
 | 场景              | 何时进入                                                              | 详见                                                                         |
 | ----------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
 | 命令增删改        | 增加 / 删除 / 重命名 `bl xxx` 或入口命令路径                          | [docs/agents/command-add-remove.md](docs/agents/command-add-remove.md)       |
-| E2E 测试维护      | 新增/改命令或 e2e 用例、补 help/缺参/dry-run                          | [docs/agents/cli-e2e-tests.md](docs/agents/cli-e2e-tests.md)                 |
+| 测试维护与性能    | 新增/修改任意单测、输出契约测试或 E2E；选择 runner、fixture、计时方式 | [docs/agents/cli-e2e-tests.md](docs/agents/cli-e2e-tests.md)                 |
 | 测试隔离          | 单测/E2E 受本地 HOME、语言、系统目录干扰；统一隔离基建                | [docs/agents/test-isolation.md](docs/agents/test-isolation.md)               |
+| 输出契约          | 新增输出、quiet/verbose、JSON 错误或流式输出                          | [docs/agents/output-contract.md](docs/agents/output-contract.md)             |
 | 批量压测          | 改/跑多能力并发压测、`test:stress`、fixtures                          | [docs/agents/stress-batch-tests.md](docs/agents/stress-batch-tests.md)       |
 | 选项变更          | 给已有命令加 `--flag` 或改默认值                                      | [docs/agents/command-flag-change.md](docs/agents/command-flag-change.md)     |
 | 模型上下架        | 增加新模型 / 改默认模型 / 废弃旧模型                                  | [docs/agents/model-add-remove.md](docs/agents/model-add-remove.md)           |
@@ -136,6 +137,8 @@ CLI 只为「自己能权威解释的错误」发出语义化信号,服务端的
 
 ## 完成改动后的快速验证
 
+新增或修改任何 `**/tests/**` 用例（含 `tests/output`）前，必须读取[测试维护规范](docs/agents/cli-e2e-tests.md)。测试通过之外，还必须检查执行成本：按测试目标选择执行层，说明必要的子进程覆盖，并对新增/扩展套件提供耗时记录；性能优化必须提供同条件前后对比，不能靠删除必要覆盖或增加跳过项提速。具体执行方式、隔离与验收清单统一在该文档维护。
+
 ```sh
 vp check    # format + lint + type check
 vp test     # unit + e2e (真实集成需 API key / console token)

README.md

@@ -141,7 +141,7 @@ Keep the returned IDs and recovery record. Closing the CLI or a later failure do
 
 ### RAG audio and video
 
-`bl knowledge doc import --index-id <id> --doc-id <fileId>` imports an existing file into a knowledge base; `doc list --details` shows per-file processing settings. Media support includes parser options, streaming uploads, and media references in search/chunk output. Chat JSON separates the final answer from phases, tools, docs, usage, and raw events; quiet mode emits only the final answer. See the [command guide](docs/knowledge/knowledge-cli-guide.md).
+`bl knowledge doc import --index-id <id> --doc-id <fileId>` imports an existing file into a knowledge base; `doc list --details` shows per-file processing settings. Media support includes parser options, streaming uploads, and media references in search/chunk output. Chat JSON separates the final answer from phases, tools, docs, usage, and raw events; quiet mode hides progress and informational messages while preserving the final result, including every JSON field. See the [command guide](docs/knowledge/knowledge-cli-guide.md).
 
 ## ParseX
 

README.zh.md

@@ -140,7 +140,7 @@ bl knowledge init --workspace-id <workspace-id> --dry-run
 
 ### RAG 音视频接入
 
-`bl knowledge doc import --index-id <id> --doc-id <fileId>` 将历史文件导入已有库；`doc list --details` 查看文件级处理参数。支持音视频 parser、流式上传，以及检索/切片中的媒体来源展示。问答 JSON 将最终 answer 与 phases/tools/docs/usage/events 分开保存，quiet 仅输出最终回答。参阅 [命令指南](docs/knowledge/knowledge-cli-guide.md)。
+`bl knowledge doc import --index-id <id> --doc-id <fileId>` 将历史文件导入已有库；`doc list --details` 查看文件级处理参数。支持音视频 parser、流式上传，以及检索/切片中的媒体来源展示。问答 JSON 将最终 answer 与 phases/tools/docs/usage/events 分开保存，quiet 只隐藏进度和过程提示，保留最终结果及完整 JSON 字段。参阅 [命令指南](docs/knowledge/knowledge-cli-guide.md)。
 
 ## ParseX