gsb-cli 0.1.2

package/skills/gsb-eval/SKILL.md

@@ -0,0 +1,301 @@
+---
+name: gsb-eval
+description: Use this skill when the user asks for GSB evaluation, A/B human evaluation, response/rubric comparison, creating or publishing GSB tasks, uploading datasets, collecting human labels, analyzing GSB results, generating decision reports, or doing good/bad case analysis. Operate the ChatBuy GSB platform through gsb-cli and reuse the GSB analysis/reporting methodology.
+version: 0.1.2
+---
+
+# GSB Eval Platform
+
+## 核心定位
+
+`gsb-eval` 现在是 **ChatBuy GSB 平台的 Agent 操作手册 + 评估分析方法论**，不是旧版“复制一套 HTML/Python 框架到任务目录”的脚手架。
+
+默认工作方式：
+
+- 使用 `gsb-cli` 调用远端 GSB 平台真实 HTTP API，完成数据集上传、任务创建、任务配置、发布、结果导出和 report 归档。
+- 本仓库是 CLI + skill 分发包，不包含平台后端；不要尝试复制 `server.py` / `index.html` 搭建临时评估页面。
+- CLI 命令尽量加 `--json`，按结构化返回里的 `issues[].next_step` 和 `continue_after_fix` 修复问题后继续。
+- 如果修改了平台能力或 HTTP API，同一轮改动里必须同步更新 `gsb-cli` 和本 skill，保证 Agent 命令与平台能力一致。
+
+平台默认地址是 `GSB_BASE_URL` 或 `http://localhost:8888`。远端平台地址由用户或环境提供：
+
+```bash
+export GSB_BASE_URL="https://<gsb-platform-url>"
+gsb-cli doctor
+```
+
+## Skill 安装与更新
+
+通过 npm 安装 `gsb-cli` 时，包内会自带本 skill，并在 `postinstall` 阶段自动执行 copy 模式安装。可用 `GSB_CLI_SKILL_TARGET=codex|cursor|all` 控制目标，或用 `GSB_CLI_SKIP_SKILL_INSTALL=1` 跳过自动安装。
+
+如果是 clone 仓库开发 CLI，在仓库根目录安装 skill：
+
+```bash
+gsb-cli skill install --target codex --mode symlink
+gsb-cli skill install --target cursor --mode symlink
+gsb-cli skill status --target all
+```
+
+推荐 `symlink` 模式：`~/.codex/skills/gsb-eval` 或 `~/.cursor/skills/gsb-eval` 会指向当前仓库，之后在仓库中执行 `git pull` 就会同时更新 CLI 和 skill。安装或更新后需要重启 Codex/Cursor，或重新打开一个 Agent 对话。
+
+如果是发布包或不希望依赖仓库路径，可用 copy 模式：
+
+```bash
+gsb-cli skill install --target codex --mode copy --force
+```
+
+copy 模式更新时需要重新运行同一条 install 命令；通过 npm 更新时会在 `postinstall` 阶段自动刷新。
+
+CLI 会定期检查最新版本并提示；手动检查：
+
+```bash
+gsb-cli version --check
+```
+
+检查结果默认缓存 24 小时。设置 `GSB_CLI_NO_UPDATE_CHECK=1` 可关闭提醒。
+
+## 多任务平台工作流
+
+### 认证
+
+优先使用已有账号登录，不要默认替用户注册新账号：
+
+```bash
+gsb-cli auth login --base-url <platform-url> --username <user> --password <password> --json
+gsb-cli auth whoami --json
+```
+
+只有用户明确表示没有账号或要求创建账号时，才注册：
+
+```bash
+gsb-cli auth register --base-url <platform-url> --username <user> --password <password> --json
+```
+
+### 端到端命令顺序
+
+```bash
+gsb-cli dataset check --a ./baseline --b ./candidate --json
+gsb-cli dataset upload --a ./baseline --b ./candidate --name-a baseline --name-b candidate --json
+gsb-cli task create --name "candidate vs baseline" --purpose "评估 candidate 相比 baseline 的回答质量和上线风险" --mode gsb --json
+gsb-cli task bind <task-id> --a <dataset-a-id> --b <dataset-b-id> --json
+gsb-cli task setup <task-id> --name "candidate vs baseline" --min-per-person 0 --description-file ./task_description.md --json
+gsb-cli task config <task-id> --transparent-mode admin_only --stats admin_only --show-trace true --require-comments false --json
+gsb-cli task preflight <task-id> --json
+gsb-cli task publish <task-id> --json
+```
+
+每一步都优先读取 `next_commands`，但如果任务需要评论必填、透明模式或统计权限，一定要在 `task setup` 后运行 `task config`。
+
+## 触发后的快速决策
+
+- 用户要“创建/发布 GSB 任务”：走 `gsb-cli` 任务工作流。
+- 用户给了 CSV/XLSX/JSONL：先转换成平台数据目录格式，再上传；CLI 不直接转换这些格式。
+- 用户要“分析结果/生成报告/上线建议”：先回收结果，再按本 skill 的分析框架生成报告，最后上传 report 归档。
+- 用户要“bad case/good case 分析”：优先做问题簇/能力簇归纳，不要只罗列 case。
+
+## 登录与通用参数
+
+```bash
+gsb-cli auth login --base-url http://localhost:8888 --username <user> --password <password> --json
+gsb-cli auth whoami --json
+```
+
+Session 会保存在 `~/.chatbuy_gsb_eval_cli/sessions.json`。如果平台重启后出现 401，重新登录。也可以用 `GSB_BASE_URL`、`GSB_USERNAME`、`GSB_PASSWORD` 或 `--base-url` 指定环境。
+
+## 数据格式与上传
+
+平台标准输入是两个版本目录：
+
+```text
+data/
+├── baseline/
+│   ├── Q_0001.json
+│   └── Q_0002.json
+└── candidate/
+    ├── Q_0001.json
+    └── Q_0002.json
+```
+
+约束：
+
+- 每个 `.json` 文件代表一条 case，JSON 顶层必须是 object。
+- A/B 两个目录用同名文件对齐 query id；只有共同文件会进入评估。
+- 非 JSON、嵌套 JSON 会被忽略。
+- 默认 renderer 主要识别 `query`、`response`、`product_cards` 等字段；自定义结构需要上传 renderer。
+
+常用命令：
+
+```bash
+gsb-cli dataset check --a ./data/baseline --b ./data/candidate --json
+gsb-cli dataset upload --a ./data/baseline --b ./data/candidate --name-a baseline --name-b candidate --json
+gsb-cli dataset list --json
+gsb-cli dataset guide --json
+```
+
+Agent 应先跑 `dataset check`。如果返回 `ZERO_COMMON_ITEMS`、`NO_JSON_FILES`、`JSON_PARSE_ERROR` 等问题，先按 `next_step` 修数据，不要跳过检查直接建任务。
+
+## 创建、配置和发布任务
+
+推荐顺序：
+
+```bash
+gsb-cli task create --name "candidate vs baseline" --purpose "评估 candidate 相比 baseline 的回答质量和上线风险" --mode gsb --json
+gsb-cli task bind <task-id> --a <dataset-a-id-or-name> --b <dataset-b-id-or-name> --json
+gsb-cli task setup <task-id> --name "candidate vs baseline" --min-per-person 0 --description-file ./task_description.md --json
+gsb-cli task config <task-id> --transparent-mode admin_only --stats admin_only --show-trace true --require-comments false --json
+gsb-cli task preflight <task-id> --json
+gsb-cli task publish <task-id> --json
+```
+
+说明：
+
+| 配置项 | 命令 | 含义 |
+| --- | --- | --- |
+| `--min-per-person` | `task setup` | 每位评估者最少评估题数；`0` 表示全量 |
+| `--anchor-count` | `task setup` | 指定锚点题数量；不传时平台按固定规则自动抽样 |
+| `--description-file` / `--description` | `task setup` | 给评估者看的任务说明 |
+| `--transparent-mode` | `task config` | 版本名可见性，常用 `admin_only` |
+| `--stats` | `task config` | 统计面板可见性，常用 `admin_only` |
+| `--show-trace` | `task config` | 是否展示 trace 信息 |
+| `--require-comments` | `task config` | 是否强制评估者填写评论 |
+
+`task setup` 会保存分配策略，返回的 `setup_effects` 会说明题数、锚点数量、额外评估维度和评估者顺序数量。若看到 `SETUP_EVAL_DIMENSIONS_PRESENT`，需要确认平台推断出的额外评估维度是否适合当前任务。
+
+- `task create --purpose` 是给创建者和管理员看的任务目的或备注；`task setup --description-file` 是给评估者看的评估说明，两者不要混用。
+- `task create` 通常只需要填写 `--name` 和 `--purpose`；除非用户明确要求固定存储目录，否则不要手写 `--task-id`，让平台根据任务名生成。
+- `--min-per-person 0` 表示每人评估全部题目；如用户指定抽样量，再改成对应数字。
+- `task config` 按用户需求设置透明模式、统计权限、trace 展示和评论必填。
+- `task publish` 会自动先跑 preflight。若 preflight 失败，按返回的 failures 修复后再发布。
+- 发布成功后 CLI 会返回评估 URL，直接交给用户或评估者。
+
+## Workspace 映射
+
+这些路径是平台侧调试信息，Agent 不应直接手改，除非用户明确要求维护平台仓库：
+
+| CLI 操作 | 平台 workspace 结果 |
+| --- | --- |
+| `dataset upload` | 复制 JSON 到 `workspace/uploads/<username>/<dataset-name>/`，并写入 `workspace/uploads/_meta.json` |
+| `task create` | 在 `workspace/tasks/<task-id>/` 创建任务目录，并更新任务注册表 |
+| `task bind` | 将数据快照写入 `workspace/tasks/<task-id>/data_a/` 和 `data_b/`，同时记录版本映射 |
+| `task setup` | 写入 `workspace/tasks/<task-id>/_config.json`，包含 `min_per_person`、`anchor_items`、`eval_dimensions`、`visibility` 等 |
+| `task renderer upload` | 写入 `workspace/tasks/<task-id>/renderer.js` |
+| `results export` | 在 `workspace/tasks/<task-id>/exports/` 生成导出任务和下载文件 |
+| `report upload` | 写入 `workspace/tasks/<task-id>/report/` |
+| 评估者提交 | 写入 `workspace/tasks/<task-id>/rating_result/eval_<user>.json` |
+
+## 自定义 Renderer
+
+当默认 renderer 可能展示为空、字段结构复杂、需要商品卡/trace/多轮对话特殊展示时，生成任务级 `renderer.js` 并上传：
+
+```bash
+gsb-cli task renderer status <task-id> --json
+gsb-cli task renderer upload <task-id> ./renderer.js --json
+gsb-cli task renderer clear <task-id> --json
+```
+
+`renderer.js` 应定义全局 `renderPanel(data, ...)`。上传后重新跑 `task preflight`。
+
+## 回收结果
+
+```bash
+gsb-cli results summary <task-id> --all --json
+gsb-cli results export <task-id> --format json --output ./exports --json
+gsb-cli results export <task-id> --format csv --output ./exports/results.csv --json
+gsb-cli results export <task-id> --format zip --output ./exports --json
+```
+
+如果启用了管理员审核，分析时优先使用已接受结果；不要把 rejected/pending 混入主结论。
+
+## 生成并归档 Report
+
+用户要求“分析评估结果”“生成报告”“给上线建议”时，默认生成 **GSB Decision Report v1**，而不是只给统计大盘。
+
+如果你在平台仓库或能访问平台 `workspace/tasks/<task-id>` 目录，可使用平台侧报告脚本：
+
+```bash
+python3 scripts/build_gsb_decision_report.py \
+  --task <task-id> \
+  --task-name "<display-name>" \
+  --focus-version <candidate-version> \
+  --baseline-version <baseline-version> \
+  --focus-alias <candidate-alias> \
+  --baseline-alias <baseline-alias>
+```
+
+平台脚本默认输出：
+
+- `<platform-workspace>/tasks/<task-id>/report/decision_report.html`
+- `<platform-workspace>/tasks/<task-id>/report/decision_summary.json`
+
+生成后用 CLI 上传到任务归档：
+
+```bash
+gsb-cli report upload <task-id> \
+  <path-to>/decision_report.html \
+  <path-to>/decision_summary.json \
+  --json
+
+gsb-cli report status <task-id> --json
+```
+
+上传接口只接受 `.html` 和 `.json`。成功返回的 `urls.report` 是平台内可访问的最新报告地址。
+
+## 分析框架
+
+分析应从“数据是否可信”到“是否值得上线”逐层推进：
+
+| 层次 | 内容 | 核心问题 |
+| --- | --- | --- |
+| L0 数据质量 | 锚点题、快答、位置偏好、样本量分层、审核状态 | 数据可信吗？噪声是否影响结论？ |
+| L1 总体胜负 | `winner`、`magnitude`、`quality_rating` 统计 | 候选版本整体赢了吗？赢多少？ |
+| L2 显著性 | 二项检验、Bootstrap CI、敏感性分析 | 提升是否稳健，还是随机波动？ |
+| L3 细粒度拆分 | 题型、评估者、query/case、结构指标 | 哪些场景提升，哪些场景退步？ |
+| L4 根因归纳 | 评论分类、双版本回复对照、问题簇/能力簇 | 为什么赢/输，下一步怎么改？ |
+
+关键原则：
+
+- v2 结果里 `winner` 已是实际版本名或 `"similar"`，不要再做 left/right 映射。
+- `magnitude` 表示显著/略好/相似；`quality_rating` 表示绝对质量，所有场次都要看。
+- `similar + below` 是两版共同低质，不等于 baseline 胜出。
+- 主结论建议按题目聚合，而不是只按评次聚合；可用 `much_better=2`、`slightly_better=1`、`similar=0` 做方向分数。
+- 显著好比略好更能支撑上线判断；高共识的候选失利题是重点 bad case。
+- 评论按版本名读取，例如 `comments["candidate"].pros`，不要按左右面板读取。
+- 结构指标只能解释回答形态，不能单独证明质量好坏，必须结合 case 和评论。
+- 样本少的评估者不自动视为低质；只有快答、锚点不一致、极端位置偏好等多信号叠加时才降权或标注风险。
+- 锚点题只用于评估者一致性和分群诊断，不作为候选版本胜负的直接证据。
+
+推荐报告结构：
+
+```text
+1. 一句话结论与上线建议
+2. 数据清洗与样本范围
+3. 核心结果 + 题型拆分
+4. 胜负原因总览
+5. 候选版本高共识胜出 case
+6. 候选版本高共识失利 case
+7. 两版都不好 / 低于预期 case
+8. 结构指标拆分
+9. 锚点题一致性检查（如有）
+10. 评估者画像
+```
+
+## Case 分析写法
+
+当用户要求 good/bad case 分析时：
+
+- 先归并问题簇或能力簇，再展开代表性 case。
+- 每个 case 至少包含评审 comment、候选版本片段、baseline 片段、具体问题定位和改进动作。
+- 不只看输赢，也看是否能 drive 优化；两版都不好、表达结构问题、高风险场景要保留。
+- 多个题型指向同一根因时合并讲，不要机械拆成重复章节。
+- good case 要分析可迁移能力和 positive regression；bad case 要给可执行修复建议和 regression 覆盖建议。
+
+## 参考文件
+
+按需读取这些文件，不要一次性加载全部：
+
+- `references/agent-cli.md`：`gsb-cli` 完整命令说明。
+- `references/analysis.md`：L0-L4 统计分析方法论。
+- `references/decision-report-v1.md`：默认决策报告协议。
+- `references/case-analysis-report.md`：good/bad case 专项报告写作规范。
+- `references/data-format.md`：输入数据格式和目录约束。
+- `references/anchor-design.md`：锚点题设计与一致性诊断。

package/skills/gsb-eval/references/agent-cli.md

@@ -0,0 +1,346 @@
+# gsb-cli 命令参考手册
+
+本手册面向 Agent，覆盖 `gsb-cli` 所有命令的完整签名字段、JSON 输出约定和错误恢复模式。
+
+## 全局约定
+
+### 通用参数
+
+| 参数 | 说明 |
+|------|------|
+| `--base-url <url>` | GSB 平台地址，默认 `GSB_BASE_URL` 或 `http://localhost:8888` |
+| `--profile <name>` | Session 配置文件，默认 `default` |
+| `--username <user>` | 自动登录用户名（自动化场景） |
+| `--password <pass>` | 自动登录密码，优先用 `GSB_PASSWORD` 环境变量 |
+| `--json` | 输出机器可读 JSON，**Agent 场景必须加** |
+| `--help` | 显示帮助 |
+| `--version` | 显示版本 |
+
+### JSON 输出格式
+
+所有 `--json` 输出均为顶层 object，包含：
+
+```json
+{
+  "ok": true,
+  "message": "操作结果简述",
+  "issues": [
+    {
+      "code": "ERROR_CODE",
+      "severity": "error | warning | info",
+      "status": "fail | warn | info",
+      "problem": "问题简述",
+      "evidence": {},
+      "why": "为什么发生",
+      "next_step": "如何修复",
+      "continue_after_fix": {
+        "command": "修复后继续执行的命令",
+        "intent": "此命令的目的",
+        "precondition": "执行此命令前需满足的条件"
+      }
+    }
+  ]
+}
+```
+
+**关键原则**：
+- `ok: false` 时必含 `issues[]`，按 `next_step` 修复后用 `continue_after_fix.command` 继续。
+- 不要跳过 `issues[]` 直接重试，先读问题、再修复、再继续。
+- `severity: "error"` 是阻塞性的，必须修复；`severity: "warning"` 可以判断后继续。
+
+### Session 管理
+
+Session 保存在 `~/.chatbuy_gsb_eval_cli/sessions.json`。平台重启后 token 失效会返回 401，重新 `auth login` 即可。
+
+环境变量方式（CI/自动化）：
+```bash
+export GSB_BASE_URL="https://<platform-url>"
+export GSB_USERNAME="<user>"
+export GSB_PASSWORD="<password>"
+```
+
+---
+
+## 命令详解
+
+### 1. 诊断与版本
+
+```bash
+gsb-cli doctor --json
+```
+检查平台可达性和当前 session 状态。返回 `reachable`、`auth` 状态和当前用户信息。
+
+```bash
+gsb-cli version --check --json
+```
+检查 CLI 是否有新版本。返回 `update.available` 和 `update.update_command`。
+
+---
+
+### 2. 认证
+
+```bash
+gsb-cli auth login --username <user> --password <pass> --json
+gsb-cli auth register --username <user> --password <pass> --json
+gsb-cli auth whoami --json
+gsb-cli auth logout --json
+```
+
+优先使用 `auth login`。只有用户明确表示没有账号或要求创建账号时，才运行 `auth register`；不要在登录失败后自动注册新账号。
+
+`whoami` 返回当前登录用户信息，可用于验证 session 有效性。常见错误码：`AUTH_CREDENTIALS_REQUIRED_OR_INVALID`、`AUTH_REGISTER_FAILED`、`PASSWORD_CHANGE_REQUIRED`。
+
+---
+
+### 3. 数据集
+
+#### 检查数据
+
+```bash
+# 方式1：单目录（需包含两个版本子目录）
+gsb-cli dataset check <dir> --json
+
+# 方式2：分别指定 A/B 目录
+gsb-cli dataset check --a ./data/baseline --b ./data/candidate --json
+
+# 方式3：指定根目录和子目录名
+gsb-cli dataset check --root ./data --version-a baseline --version-b candidate --json
+```
+
+返回每侧的 `json_files`、`valid_json_files` 数量和 pair 的 `common_count`。
+
+常见错误码：
+- `DATASET_DIR_NOT_FOUND` — 目录不存在
+- `NO_JSON_FILES` — 目录中没有 JSON 文件
+- `JSON_PARSE_ERROR` — JSON 解析失败
+- `JSON_ROOT_NOT_OBJECT` — JSON 顶层不是 object
+- `ZERO_COMMON_ITEMS` — A/B 两侧没有同名文件
+
+#### 上传数据集
+
+```bash
+# 单版本上传
+gsb-cli dataset upload ./data/baseline --name baseline --json
+
+# 双版本上传
+gsb-cli dataset upload --a ./data/baseline --b ./data/candidate --name-a baseline --name-b candidate --json
+```
+
+返回 `uploaded[]` 数组，每个元素含 `id`、`name`、`json_count`。
+
+#### 列出数据集
+
+```bash
+gsb-cli dataset list --json
+```
+返回 `datasets.my`（本人上传）和 `datasets.others`（他人上传）。
+
+#### 格式指引
+
+```bash
+gsb-cli dataset guide --json
+```
+返回 `format_guidance`，说明平台期望的 JSON 数据结构。
+
+---
+
+### 4. 任务管理
+
+#### 创建任务
+
+```bash
+gsb-cli task create --name "candidate vs baseline" --purpose "评估 candidate 相比 baseline 的质量和上线风险" --mode gsb --json
+```
+
+- `--name`：任务名称（给管理员看）
+- `--purpose`：任务目的或备注（给创建者和管理员看，不是给评估者看的任务说明）
+- `--mode`：固定为 `gsb`
+- 返回 `task.id`，后续命令均需此 ID
+
+#### 绑定数据源
+
+```bash
+gsb-cli task bind <task-id> --a <dataset-a-id-or-name> --b <dataset-b-id-or-name> --json
+```
+
+可用数据集 ID 或名称引用。常见错误：`DATASET_REF_NOT_FOUND`、`ZERO_COMMON_ITEMS_AFTER_BIND`。
+
+#### 配置任务
+
+```bash
+gsb-cli task setup <task-id> \
+  --name "candidate vs baseline" \
+  --min-per-person 0 \
+  --description-file ./task_description.md \
+  --json
+```
+
+- `--name`：给评估者看的任务名称
+- `--min-per-person 0` 表示每人评估全部题目
+- `--description-file`：评估说明 markdown 文件
+
+`task setup` 会生成并保存分配策略，JSON 返回中的 `setup_effects` 会说明 `total_items`、`min_per_person`、`anchor_items_count`、`eval_dimensions` 和 `evaluator_order_count`。未传 `--anchor-count` 时，锚点题由平台按固定规则抽样。
+
+```bash
+gsb-cli task config <task-id> \
+  --transparent-mode admin_only \
+  --stats admin_only \
+  --show-trace true \
+  --require-comments false \
+  --json
+```
+
+配置项说明：
+- `--transparent-mode`：版本名可见性，常用 `admin_only`
+- `--stats`：统计面板权限
+- `--show-trace`：是否展示 trace 信息
+- `--require-comments`：是否强制要求评论
+
+`require_comments` 不在 `task setup` 中设置；如果任务要求评论必填，必须额外运行 `task config --require-comments true`。
+
+### 4.1 Workspace 映射
+
+这些是平台侧结果位置，仅用于调试和排障。Agent 不应绕过 CLI 直接修改。
+
+| CLI 操作 | 平台 workspace 结果 |
+| --- | --- |
+| `dataset upload` | `workspace/uploads/<username>/<dataset-name>/` + `workspace/uploads/_meta.json` |
+| `task create` | `workspace/tasks/<task-id>/` + 任务注册表 |
+| `task bind` | `workspace/tasks/<task-id>/data_a/`、`data_b/` 和版本映射 |
+| `task setup` | `workspace/tasks/<task-id>/_config.json` |
+| `task renderer upload` | `workspace/tasks/<task-id>/renderer.js` |
+| `results export` | `workspace/tasks/<task-id>/exports/` |
+| `report upload` | `workspace/tasks/<task-id>/report/` |
+| 评估者提交 | `workspace/tasks/<task-id>/rating_result/eval_<user>.json` |
+
+#### 发布前检查
+
+```bash
+gsb-cli task preflight <task-id> --json
+```
+
+返回 `preflight.checks[]` 和 `preflight.failures[]`。阻塞性 failure 必须先修复再发布。
+
+#### 发布任务
+
+```bash
+gsb-cli task publish <task-id> --json
+```
+
+自动先跑 preflight。发布成功后返回 `urls.eval`（评估页面地址），直接发给评估者。
+
+#### 归档任务
+
+```bash
+gsb-cli task archive <task-id> --json
+```
+
+#### 查看任务
+
+```bash
+gsb-cli task get <task-id> --json
+```
+
+---
+
+### 5. Renderer 管理
+
+```bash
+gsb-cli task renderer status <task-id> --json
+gsb-cli task renderer upload <task-id> ./renderer.js --json
+gsb-cli task renderer clear <task-id> --json
+```
+
+当默认 renderer 展示为空或需要自定义渲染时使用。`renderer.js` 应定义 `renderPanel(data, ...)` 函数。
+
+常见错误：`DEFAULT_RENDERER_IN_USE`（提示可能需要自定义 renderer）、`CUSTOM_RENDERER_LIKELY_REQUIRED`。
+
+---
+
+### 6. 结果回收
+
+```bash
+# 查看评估进度和汇总
+gsb-cli results summary <task-id> --all --json
+
+# 导出结果
+gsb-cli results export <task-id> --format json --output ./exports --json
+gsb-cli results export <task-id> --format csv --output ./exports/results.csv --json
+gsb-cli results export <task-id> --format zip --output ./exports --json
+```
+
+---
+
+### 7. 报告管理
+
+```bash
+# 查看报告状态
+gsb-cli report status <task-id> --json
+
+# 获取报告 URL
+gsb-cli report url <task-id> --json
+
+# 上传报告（必须成对传入 .html 和 .json）
+gsb-cli report upload <task-id> ./decision_report.html ./decision_summary.json --json
+
+# 下载报告
+gsb-cli report download <task-id> --type html --output ./report.html --json
+```
+
+---
+
+## 标准工作流
+
+### 完整 GSB 评估流程
+
+```bash
+# 1. 检查环境
+gsb-cli doctor --json
+gsb-cli auth whoami --json
+
+# 2. 检查并上传数据
+gsb-cli dataset check --a ./data/baseline --b ./data/candidate --json
+gsb-cli dataset upload --a ./data/baseline --b ./data/candidate --name-a baseline --name-b candidate --json
+
+# 3. 创建并配置任务
+gsb-cli task create --name "candidate vs baseline" --purpose "..." --mode gsb --json
+gsb-cli task bind <task-id> --a baseline --b candidate --json
+gsb-cli task setup <task-id> --name "candidate vs baseline" --min-per-person 0 --description-file ./task_description.md --json
+gsb-cli task config <task-id> --transparent-mode admin_only --stats admin_only --show-trace true --require-comments false --json
+
+# 4. 发布
+gsb-cli task publish <task-id> --json
+# → 将返回的 urls.eval 发给评估者
+
+# 5. 等待评估完成后回收结果
+gsb-cli results export <task-id> --format json --output ./exports --json
+
+# 6. 分析并生成报告（使用 analysis.md 方法论）
+# → 生成 decision_report.html + decision_summary.json
+
+# 7. 归档报告
+gsb-cli report upload <task-id> ./decision_report.html ./decision_summary.json --json
+```
+
+---
+
+## 常见错误码速查
+
+| 错误码 | 含义 | 修复方向 |
+|--------|------|---------|
+| `AUTH_INVALID_CREDENTIALS` | 用户名或密码错误 | 核对凭据后重新 `auth login` |
+| `PASSWORD_CHANGE_REQUIRED` | 需要修改密码 | 通过平台 Web 页面修改密码 |
+| `PLATFORM_UNREACHABLE` | 平台不可达 | 检查网络和 `--base-url` |
+| `PLATFORM_API_INCOMPATIBLE` | API 不兼容 | 检查平台版本和 CLI 版本是否匹配 |
+| `DATASET_DIR_NOT_FOUND` | 数据目录不存在 | 确认路径正确 |
+| `NO_JSON_FILES` | 目录中没有 JSON 文件 | 检查数据格式 |
+| `JSON_PARSE_ERROR` | JSON 解析失败 | 修复 JSON 语法错误 |
+| `JSON_ROOT_NOT_OBJECT` | JSON 顶层不是 object | 确保每个 JSON 文件的顶层是 `{}` |
+| `ZERO_COMMON_ITEMS` | A/B 两侧没有同名文件 | 检查文件名是否对齐 |
+| `UNMATCHED_JSON_IGNORED` | 部分文件只在单侧存在 | 确认是否需要补充缺失文件 |
+| `DATA_SOURCE_NOT_BOUND` | 任务未绑定数据源 | 执行 `task bind` |
+| `SETUP_MISSING` | 任务未完成配置 | 执行 `task setup` |
+| `DEFAULT_RENDERER_IN_USE` | 使用默认 renderer | 如展示为空，上传自定义 renderer |
+| `EXPORT_TIMEOUT` | 导出超时 | 检查数据量，重试或分批导出 |
+
+所有错误的修复命令均从 `continue_after_fix.command` 字段获取，不需要推测。