@fatecannotbealtered-/jira-cli 1.0.6 → 1.1.1

package/.agent/CLI-SPEC_zh.md

@@ -0,0 +1,641 @@
+# 面向 Agent 的 CLI 工具设计规范
+
+
+本文定义本仓库 CLI 在被 AI Agent 调用时必须遵守的机器契约。目标是让 Agent 能稳定调用、可靠解析、可恢复重试，并避免任何非交互场景下的阻塞或误写。
+
+## 1. 核心铁律
+
+1. stdout 是契约：默认输出单个合法 JSON 文档，禁止混入日志、进度、提示、颜色控制符。
+2. stderr 是旁路：进度、警告、调试、错误说明全部写 stderr。
+3. 机器优先：默认 `--format json`；`text` 仅供人读；`raw` 仅用于裸字节、日志、diff 等原样透传。
+4. 非交互安全：写操作不得等待键盘输入，必须使用 `--dry-run` + `--confirm <token>`。
+5. 确定性：相同输入产生相同结构输出；字段名、字段顺序、schema 版本保持稳定。
+6. 最小惊扰：查询不改变状态；写操作在缺少有效 confirm token 时必须失败而不是继续执行。
+7. 可恢复：错误码、exit code、`retryable` 必须足够稳定，让 Agent 能决定是否重试、回退或请求用户介入。
+
+## 2. 全局参数
+
+| 参数                       | 说明                             |
+|--------------------------|--------------------------------|
+| `--format json/text/raw` | 输出格式，默认 `json`                 |
+| `--json`                 | `--format json` 的兼容别名，不推荐新调用使用 |
+| `--fields <a,b,c>`       | 仅返回指定字段，降低 token（查询命令）         |
+| `--compact`              | 紧凑 JSON 输出，去除冗余空白（查询命令）        |
+| `--dry-run`              | 模拟写操作，返回变更预览与 `confirm_token`  |
+| `--confirm <token>`      | 携带 dry-run 返回的 token 真正执行写操作   |
+| `--quiet`                | 抑制 stderr 上的进度/提示，不抑制错误        |
+
+`update` 命令可以按工具增加 `--target-version` 或 `--channel` 等参数，但必须保留统一生命周期参数：`--check`、`--dry-run`、`--confirm <token>`。
+
+格式职责：
+
+- `json`：结构化机器输出，默认格式，也是唯一推荐给 Agent 的格式。
+- `text`：人类可读，可以变化，禁止程序解析。
+- `raw`：未包装 bytes / log / diff，原样透传，不使用 JSON envelope。
+
+## 3. 统一输出 Envelope
+
+成功与失败使用同形结构。Agent 只需要先判断 `ok`。
+
+成功：
+
+```json
+{
+  "ok": true,
+  "schema_version": "1.0",
+  "data": {},
+  "meta": {
+    "duration_ms": 0
+  }
+}
+```
+
+失败：
+
+```json
+{
+  "ok": false,
+  "schema_version": "1.0",
+  "error": {
+    "code": "E_NOT_FOUND",
+    "message": "human readable message",
+    "details": {},
+    "retryable": false
+  },
+  "meta": {
+    "duration_ms": 0
+  }
+}
+```
+
+约定：
+
+- 所有 JSON 响应必须包含 `ok` 与 `schema_version`。
+- `data` 始终是命令的业务载荷；不要把业务字段提升到 envelope 顶层。
+- `error.code` 使用稳定的语义化枚举，统一以 `E_` 开头。
+- `error.message` 给人读，Agent 不应解析。
+- `error.details` 放结构化上下文，必须脱敏。
+- `error.retryable` 决定 Agent 是否可以自动退避重试。
+- `meta.duration_ms` 记录命令执行耗时。
+- 破坏性 schema 变更必须升级 `schema_version` 主版本。
+
+## 4. stdout / stderr 规则
+
+- stdout 在 `json` 模式下只能出现一个 JSON 文档，或在明确流式命令中输出 NDJSON。
+- stderr 可输出进度、警告、诊断。
+- `json` 模式下出错时，失败 envelope 就是 stdout 上那个唯一的 JSON 文档——Agent 永远解析 stdout 并检查 `ok`，不从 stderr 抓取；stderr 可以补充人类可读的错误说明。
+- `--quiet` 只能抑制 stderr 上的非错误信息。
+- 不允许在 JSON stdout 前后打印 banner、提示语、进度条或颜色码。
+- stdout / stderr 一律 **UTF-8 编码，不带 BOM**，换行用 `\n`，确保跨平台（尤其 Windows）Agent 可稳定解析。
+
+## 5. 流式输出（NDJSON）
+
+大输出、日志流、订阅流、批量逐项结果使用 NDJSON。每行必须是独立合法 JSON，便于流式消费、降内存、可中断：
+
+```jsonl
+{"ok":true,"schema_version":"1.0","type":"item","data":{}}
+{"ok":true,"schema_version":"1.0","type":"item","data":{}}
+{"ok":true,"schema_version":"1.0","type":"summary","data":{"count":2}}
+```
+
+约定：
+
+- 普通查询默认使用单 JSON envelope。
+- 只有命令语义明确是 log / stream / subscribe / 批量流式输出时才使用 NDJSON。
+- NDJSON 行必须包含 `ok`、`schema_version`、`type`。
+- 结束行建议使用 `type: "summary"`。
+- 真正的二进制或纯文本透传走 `--format raw`，不要包成巨型单 JSON。
+
+## 6. Exit Code 语义表
+
+| Code | 含义                 | Agent 行为               |
+|------|--------------------|------------------------|
+| 0    | 成功                 | 继续                     |
+| 1    | 通用错误               | 读取 error envelope 判断   |
+| 2    | 参数/用法错误            | 不重试，修正参数               |
+| 3    | 资源不存在              | 不重试                    |
+| 4    | 权限/认证/配置失败         | 不重试，提示凭证或权限            |
+| 5    | 需确认但缺少 token       | 走 dry-run 获取 token 后重试 |
+| 6    | 前置条件冲突或 token 失效   | 重新读取状态后重试              |
+| 7    | 可重试瞬时错误（网络/限流/服务端） | 退避后重试                  |
+| 8    | 超时                 | 退避后重试                  |
+| 9    | 需人工介入（见 §15.3，可选） | 转述给用户，待其完成后跑 `resume`  |
+
+错误码与 exit code 必须一致：
+
+- `E_USAGE` / `E_VALIDATION` -> 2
+- `E_NOT_FOUND` -> 3
+- `E_AUTH` / `E_FORBIDDEN` / `E_CONFIG` -> 4
+- `E_CONFIRMATION_REQUIRED` -> 5
+- `E_CONFLICT` -> 6
+- `E_NETWORK` / `E_RATE_LIMITED` / `E_SERVER` -> 7
+- `E_TIMEOUT` -> 8
+- `E_HUMAN_REQUIRED` -> 9（可选，仅启用 §15.3 时）
+
+## 7. 写操作流程（dry-run -> confirm）
+
+写命令第一步必须支持 `--dry-run`，返回预览与 token：
+
+```json
+{
+  "ok": true,
+  "schema_version": "1.0",
+  "data": {
+    "preview": {
+      "changes": [
+        {
+          "action": "delete",
+          "resource": "mail",
+          "id": "123",
+          "before": {},
+          "after": null
+        }
+      ]
+    },
+    "confirm_token": "ct_9f2a...",
+    "expires_at": "2026-06-05T12:00:00Z"
+  },
+  "meta": {
+    "duration_ms": 0
+  }
+}
+```
+
+第二步携带 token 执行：
+
+```bash
+tool resource delete --id 123 --confirm ct_9f2a...
+```
+
+confirm token 约定：
+
+- token 必须绑定操作内容哈希，包括命令路径、参数、目标资源 ID、调用账号、权限上下文。
+- 哈希必须用机器本地密钥做 HMAC（如 `~/.<tool>/confirm.secret`，首次使用时生成，权限 `0600`），使 token 无法通过重算公开哈希凭空铸造——它只能来自同一台机器上一次真实的 `--dry-run`。
+- 能获取资源版本时，也应绑定资源版本、etag、changekey 或 updated_at，防止状态漂移。
+- token 必须有过期时间，`expires_at` 使用 ISO 8601 UTC。
+- token 过期、操作参数变化、目标状态变化时，执行命令返回 `E_CONFLICT`，exit code 6。
+- 缺少 token 时返回 `E_CONFIRMATION_REQUIRED`，exit code 5。
+- dry-run 不得产生外部副作用，但可以读取状态用于构造 preview。
+
+## 8. 查询、分页与字段选择
+
+查询命令默认支持：
+
+- `--fields <a,b,c>`：只返回指定字段，支持 dotted path 时需在 reference 中声明。
+- `--compact`：压缩 JSON 空白。
+- `--limit`：限制返回条数。
+- `--cursor` 或 `--offset`：分页游标或偏移。
+
+分页返回建议：
+
+```json
+{
+  "items": [],
+  "count": 0,
+  "next_cursor": null,
+  "has_more": false
+}
+```
+
+约定：
+
+- 所有 ID 使用字符串，即使底层是数字。
+- 所有时间使用 ISO 8601 UTC。
+- 列表顺序必须稳定；默认排序规则应在 reference 中声明。
+- 查询命令不得因为缺少可选过滤条件而进入交互询问。
+
+## 9. 幂等性与并发安全
+
+写命令应尽量支持幂等语义：
+
+- 创建类命令建议支持 `--request-id` 或 `--idempotency-key`。
+- 重试同一个 idempotency key 不应重复创建资源。
+- 更新/删除类命令应在 dry-run 中记录目标资源版本。
+- confirm 时发现版本变化必须返回 `E_CONFLICT`。
+- 批量写操作应返回逐项结果，不要因为单项失败隐藏其他项状态。
+
+批量写结果建议：
+
+```json
+{
+  "results": [
+    {
+      "id": "1",
+      "ok": true,
+      "action": "deleted"
+    },
+    {
+      "id": "2",
+      "ok": false,
+      "error": {
+        "code": "E_NOT_FOUND"
+      }
+    }
+  ],
+  "summary": {
+    "ok_count": 1,
+    "error_count": 1
+  }
+}
+```
+
+## 10. 敏感信息与审计
+
+- password、token、secret、authorization header、cookie 不得出现在 stdout、stderr、error.details、audit log。
+- dry-run preview 必须脱敏敏感字段。
+- reference/context/doctor 不得泄露明文凭证。
+- context 可以报告凭证是否存在，但只能用布尔值或脱敏摘要。
+- audit log 应记录命令路径、脱敏参数、调用账号、时间、exit code、duration。
+- `--quiet` 不应关闭审计。
+
+## 11. 自描述命令（reference / context / doctor / changelog）
+
+### reference
+
+声明工具能力、命令、参数、输出 schema、错误码、权限等级，供 Agent 先理解能力。
+
+```json
+{
+  "ok": true,
+  "schema_version": "1.0",
+  "data": {
+    "tool": "tool-name",
+    "version": "1.0.0",
+    "release_readiness": {
+      "level": "beta",
+      "fcc_required": true,
+      "fcc_status": "verified",
+      "mock_upstream_required": true,
+      "mock_upstream_status": "verified",
+      "live_smoke_required_for_stable": true,
+      "live_smoke_status": "missing",
+      "reason": "Stable requires recorded live smoke/E2E evidence.",
+      "required_evidence": [
+        "functional_contract_coverage_100",
+        "mock_upstream_contract_tests",
+        "recorded_live_smoke_for_stable"
+      ]
+    },
+    "commands": [
+      {
+        "path": "resource delete",
+        "type": "write",
+        "description": "Delete a resource",
+        "params": [
+          {
+            "name": "id",
+            "type": "string",
+            "required": true,
+            "multiple": false
+          }
+        ],
+        "output_schema": {}
+      }
+    ],
+    "exit_codes": {}
+  },
+  "meta": {
+    "duration_ms": 0
+  }
+}
+```
+
+`release_readiness` 是机器可读的发布门禁字段。每个 AI 原生 CLI 的
+`reference` 都必须包含：
+
+- `level`：`stable`、`beta` 或 `unpublishable`。
+- `stable`：FCC 达到 100%；mock upstream / contract tests 覆盖外部行为；
+  且该 release candidate 至少有一次可追溯的真实环境 smoke/E2E 记录。
+- `beta`：FCC 达到 100%，mock upstream / contract tests 完整，但缺少真实
+  smoke/E2E 记录，或项目明确声明暂不具备真实 E2E 条件。
+- `unpublishable`：任一公开行为缺少命令级测试，或 mock upstream / contract
+  tests 只覆盖 happy path，未覆盖失败、鉴权、分页、空结果、限流等行为。
+- `fcc_status`、`mock_upstream_status`、`live_smoke_status` 使用
+  `verified`、`missing`、`not_applicable` 或 `unknown`；`stable` 对必需项不得
+  使用 `missing` 或 `unknown`。
+- `required_evidence[]` 列出 Agent 或发布脚本信任该等级前应检查的证据。
+
+### context
+
+报告当前运行环境、配置、目标、凭证状态。
+
+```json
+{
+  "ok": true,
+  "schema_version": "1.0",
+  "data": {
+    "env": "prod",
+    "account": "user@example.com",
+    "config": {},
+    "credentials": {
+      "configured": true
+    }
+  },
+  "meta": {
+    "duration_ms": 0
+  }
+}
+```
+
+### doctor
+
+环境与风险体检，每项给出可执行修复建议。
+
+```json
+{
+  "ok": true,
+  "schema_version": "1.0",
+  "data": {
+    "checks": [
+      {
+        "check": "auth",
+        "status": "pass",
+        "fix": null
+      },
+      {
+        "check": "network",
+        "status": "fail",
+        "fix": "set HTTP_PROXY or check VPN"
+      },
+      {
+        "check": "release_readiness",
+        "status": "warn",
+        "fix": "record live smoke/E2E evidence before declaring stable"
+      }
+    ]
+  },
+  "meta": {
+    "duration_ms": 0
+  }
+}
+```
+
+`doctor` 必须包含 `check: "release_readiness"`，并与 `reference` 报告同一个
+发布等级。`stable` 使用 `pass`，有意声明的 `beta` 使用 `warn`，
+`unpublishable` 或自称 `stable` 但证据缺失时使用 `fail`。非 `pass` 状态应给出
+可执行的 `fix`。
+
+### changelog
+
+报告**版本之间发生了什么变化**，让自更新后的 Agent 能补齐认知，而不是继续用旧套路。这是 `reference`（描述当前能力）在时间维度上的补充。
+
+```bash
+tool changelog                    # 全部版本变更
+tool changelog --since 1.0.3      # 只返回比 1.0.3 新的版本
+```
+
+```json
+{
+  "ok": true,
+  "schema_version": "1.0",
+  "data": {
+    "current_version": "1.1.0",
+    "since": "1.0.3",
+    "entries": [
+      {
+        "version": "1.1.0",
+        "date": "2026-06-07",
+        "changes": {
+          "added": [
+            "..."
+          ],
+          "changed": [
+            "..."
+          ],
+          "fixed": []
+        }
+      }
+    ]
+  },
+  "meta": {
+    "duration_ms": 0
+  }
+}
+```
+
+约定：
+
+- **单一真相源**：`changelog` 输出从 `CHANGELOG.md` 派生（构建时按 `## [version]` 段落嵌入二进制），不另维护数据。与 release-notes 同源。
+- `--since <version>` 只返回严格高于该版本的条目，供「上次见过 X 版本」的 Agent 拉增量。
+- 变更分类沿用 Keep a Changelog：`added` / `changed` / `fixed` / `deprecated` / `removed` / `security`。
+- 自更新成功后，工具应在结果中提示 Agent 运行 `changelog --since <旧版本>`（见 §14）。
+
+## 12. 命令设计约定
+
+1. 用最短命令完成明确任务，减少组合复杂度。
+2. 查询命令默认支持 `--fields` 与 `--compact` 降 token。
+3. 写命令必须支持 `--dry-run` 与 `--confirm`。
+4. 命名采用 `<noun> <verb>` 或 `<verb> <noun>` 风格，并在全局统一。
+5. 不要求 Agent 解析帮助文本；`--help` 给人看，机器能力通过 `reference` 暴露。
+6. 所有时间用 ISO 8601 UTC；所有 ID 用字符串。
+7. 命令失败时优先返回结构化错误，不输出半截成功 payload。
+8. 命令参数应避免二义性；布尔值用 flag，枚举值用有限选项。
+
+## 13. 功能契约覆盖率与发布门禁
+
+功能契约覆盖率（Functional Contract Coverage，FCC）是发布阻断标准：Agent
+能依赖的每一个公开行为，都必须有自动化命令级测试覆盖。代码行覆盖率或分支覆盖率是有用的工程指标，但它是辅助指标，不能替代缺失的功能契约测试。
+
+公开功能契约包括以下位置声明的任何行为：
+
+- `README.md` / `README_zh.md`、`SKILL.md` 或 Skill reference 页面；
+- `tool reference`、`--help`、`context`、`doctor`、`changelog`、`update` 输出；
+- JSON envelope 字段、命令输出 schema、全局参数、错误码、exit code、retryable、stdout/stderr 边界；
+- 已记录的配置/环境变量、凭证处理、写操作安全、自更新校验、Skill 同步和 `_untrusted` 安全承诺。
+
+每个公开命令或契约至少覆盖：
+
+- 成功路径；
+- 缺失/非法参数；
+- 配置缺失、认证缺失或权限失败（适用时）；
+- 上游 API 失败、网络失败、限流或超时（适用时）；
+- JSON envelope 形状、输出 schema、exit code、stdout/stderr 边界；
+- 非交互行为：不提示、不阻塞，写命令使用 `--dry-run` -> `--confirm <token>`；
+- 每个影响可观察行为的 bug fix 都必须带回归测试。
+
+`FCC = 100%` 的含义：
+
+- 公开契约中列出的每个命令、参数、输出、错误行为，都映射到至少一个自动化测试，或明确标注为不适用；
+- 命令级测试验证 CLI 边界，而不仅仅测试内部 helper；
+- 生成代码、版本常量、构建元数据或不可达平台保护分支可以从数字覆盖率中排除，但如果它们是文档化公开行为，就不能从 FCC 中排除；
+- 存在已知 FCC 缺口时，不得打发布 tag。
+- `fcc_status: "verified"` 必须有机器背书——枚举守卫测试：从 `reference` 实时输出枚举全部叶子命令，逐一断言存在命令级测试调用。状态诚实声明为 `missing` 时守卫跳过；不补测试就把声明翻成 `verified` 会让守卫立刻失败（模板自带该守卫）。
+
+CI 应在每个 PR 上运行单测和命令级测试。数字覆盖率门槛可以按仓库逐步抬升，但发布标准是绝对的：公开功能契约必须被覆盖。
+
+### 发布就绪等级
+
+发布就绪比「测试通过」更严格：
+
+- **Stable**：FCC 达到 100%；mock upstream / contract tests 覆盖成功、
+  参数校验、配置/认证/权限失败、上游/网络/限流/超时失败、空结果、分页、输出
+  schema、exit code、stdout/stderr 边界；并且该 release candidate 至少有一次
+  真实环境 smoke/E2E 记录。
+- **Beta**：FCC 达到 100%，mock upstream / contract tests 具备同等行为宽度，
+  但缺少真实环境 smoke/E2E 记录，或项目明确声明暂不具备真实 E2E 条件。
+- **Unpublishable**：任何公开命令、参数、输出或错误行为缺少命令级测试，或
+  mock upstream 测试只覆盖 happy path。
+
+`reference.release_readiness` 和 `doctor.checks[]` 是这道门禁的机器可读出口。
+仓库可以选择不发布 `beta` 产物，但没有上述真实证据时不得自称 `stable`。
+
+## 14. 版本与兼容策略
+
+- `schema_version` 表示输出 schema 版本，不等同于工具版本。
+- 破坏性 schema 变更升级主版本，例如 `1.x` -> `2.0`。
+- 非破坏性新增字段可以保持主版本不变。
+- 废弃字段应先保留兼容期，并在 reference 中标记 deprecated。
+- 兼容别名可以存在，但不应作为新文档推荐用法。
+- Agent 应优先依据 `reference`，而不是 `--help` 或 README。
+
+### 版本协商（工具版本 ↔ Skill 期望）
+
+Skill 是写它那天的能力快照，二进制版本一漂就可能错位：按 v1.1 写的 Skill 碰上 v1.0 二进制，会静默调用不存在的命令。
+
+- 工具必须能报告自身版本：`tool --version` 与 `context.data.version`。
+- Skill 在 frontmatter 声明最低兼容版本（见 SKILL-SPEC `requires.min_version`）。
+- `doctor` 应有一项检查「当前版本是否满足声明的最低版本」，不满足时给出 `fix`（升级命令），状态 `fail`。
+
+### 自更新与 Skill 同步闭环
+
+带 `self-update` 的工具，更新成功后**必须打通两条更新链**：
+
+1. 二进制或包本身是最新；
+2. 内置 Agent Skill 目录也是最新，最终状态等同于运行 `npx skills add <repo> -y -g`。
+
+用户首次安装 Skill 仍使用 `npx skills add ...`；CLI 二进制不能暴露单独的 `install-skill` 命令。但在 update 生命周期中，工具需要负责完整更新：要么同步整个 `skills/<tool>/` 目录，要么在结果中显式返回 `skill_sync_status` 与 `skill_sync_command`，让 Agent 在使用新能力前完成同步。
+
+update 必须遵守的契约：
+
+- `update --check` 只读。返回当前/目标版本、安装方式、是否有二进制/包更新、Skill 同步是否需要或可用、checksum/签名材料是否可用。
+- `update --dry-run` 返回完整变更预览：二进制/包更新、Skill 目录同步、checksum/签名校验，以及 `confirm_token`。
+- `update --confirm <token>` 执行更新。替换本地文件或运行包管理器前，必须先完成 release 完整性校验。
+- 更新成功后，返回 `previous_version`、`current_version`、`skill_sync_status`，以及足够审计的校验元数据。
+- 如果二进制/包更新成功但 Skill 同步失败，必须返回非成功或部分成功状态，并给出 `skill_sync_command`；Agent 在 Skill 同步完成前不得使用新文档能力。
+
+版本通知契约：
+
+- `update --check` 主动检查最新 release，并刷新本地更新通知缓存。
+- `doctor` 可以用较短超时主动检查；网络失败本身不得导致 `doctor` 失败。
+- `context` 和 `--help` 只读取本地缓存，不得访问远程 registry 或 GitHub。
+- 有可用更新时，JSON 命令数据中包含 `notices[]`，字段包括
+  `type: "update_available"`、当前/最新版本、安装方式、
+  `recommended_command`、已知 release URL、检查时间和机器可读的下一步。文本/help 输出可追加一句简短提示。
+
+release 校验基线：
+
+- 按 `checksums.txt` 校验归档/包；checksum 不匹配、缺失 checksum 文件、或缺少当前归档条目，都必须失败关闭。
+- 已签名 release 应由 tagged GitHub Actions release workflow 使用 Sigstore/Cosign keyless 模式签署 `checksums.txt`。验证端应绑定到预期仓库 workflow 身份和 GitHub OIDC issuer。
+- update 结果携带 `signature_status`（一个短字符串说明发布完整性在哪里被验证：如 `verified`、`not_checked`、`handled_by_npm_installer`、`manual_release_verification_required`）与 `signature_verified`（仅当本地 Sigstore 验证真实执行且成功时为 true）。不能把 checksum 校验伪装成签名校验。
+
+- `update --confirm <token>` 成功后，结果 `data` 中返回 `previous_version` 与 `current_version`。
+- 同时在结果中提示：`run "changelog --since <previous_version>" to see what changed`。
+- Agent 约定：自更新后、继续干活前，先读 `changelog --since <旧版本>`（见 SKILL-SPEC 配方）。
+
+## 15. 可选模式（按需启用）
+
+以下三种模式**不是人人必做**：工具用得上就照这里实现，用不上就忽略，零负担。它们让规范随工具复杂度伸缩——简单工具保持轻，复杂工具不必重新发明轮子。每条都标了「何时适用」。
+
+### 15.1 凭证生命周期（令牌会过期时）
+
+**何时适用**：凭证不是静态的，而是会过期 / 需刷新的——OAuth access_token（微信公众号约 2h）、cookie / session（小红书）、临时 STS 凭证等。静态用户名密码的工具跳过本节。
+
+- `context.data.credentials` 除「配没配」外，应报告**有效性与过期信息**（脱敏）：
+
+  ```json
+  {
+    "credentials": {
+      "configured": true,
+      "valid": true,
+      "expires_at": "2026-06-07T12:00:00Z",
+      "refreshable": true
+    }
+  }
+  ```
+
+- 令牌过期且不可自动刷新时，操作返回 `E_AUTH`（exit 4），`details` 指明需重新认证。
+- 可自动刷新的工具应**透明刷新**，不让 Agent 操心；刷新失败再降级为 `E_AUTH`。
+- `doctor` 增一项 `check: "credentials"`，对临近过期给 `warn` + 续期 `fix`。
+- 刷新令牌、secret 一律脱敏，绝不出现在 stdout / stderr / details。
+
+### 15.2 异步任务生命周期（长任务：提交 -> 轮询 -> 取结果）
+
+**何时适用**：操作不能同步返回结果——SQL 异步执行 / 审批（Archery）、批量群发、采集 / 爬取任务、大导出。同步即得结果的命令跳过本节。
+
+- 提交命令立即返回 `job_id` 与状态，不阻塞：
+
+  ```json
+  {
+    "ok": true,
+    "schema_version": "1.0",
+    "data": {
+      "job_id": "job_abc123",
+      "status": "pending",
+      "poll": "tool job status --id job_abc123",
+      "result": "tool job result --id job_abc123"
+    },
+    "meta": { "duration_ms": 12 }
+  }
+  ```
+
+- 状态查询返回稳定枚举：`pending` / `running` / `succeeded` / `failed` / `cancelled`，并带进度（如 `progress`、`eta_seconds`）。
+- 结果与状态分开取：`succeeded` 后用 `result` 命令拉数据（大结果走 NDJSON / `--format raw`）。
+- `failed` 的结果用标准 error envelope，`retryable` 指明能否重试整个任务。
+- 写类长任务的提交仍走 `dry-run → confirm`；confirm 后才落 `job_id`。
+
+### 15.3 人工介入检查点（需要人来扫码 / 验证码 / 审批时）
+
+**何时适用**：流程中途必须由人完成某步——扫码登录 / 验证码（小红书）、审批人放行（Archery）、二次确认等。全自动工具跳过本节。
+
+- 卡在人工步骤时，**不阻塞、不瞎试**，返回专用信号让 Agent 把球踢给用户：
+
+  ```json
+  {
+    "ok": false,
+    "schema_version": "1.0",
+    "error": {
+      "code": "E_HUMAN_REQUIRED",
+      "message": "Scan the QR code to continue",
+      "details": { "action": "scan_qr", "resume": "tool login resume --id sess_1", "qr_path": "/tmp/qr.png" },
+      "retryable": false
+    },
+    "meta": { "duration_ms": 30 }
+  }
+  ```
+
+- `E_HUMAN_REQUIRED` 用 exit code `9`（在既有 0–8 之外新增；不复用 `4`，以区分「凭证错」与「等人动作」）。
+- `details.action` 用稳定枚举说明需要人做什么，`details.resume` 给出人工完成后的续跑命令。
+- Agent 约定：收到 `E_HUMAN_REQUIRED` → 向用户转述 `message` 与所需动作 → 等用户完成 → 跑 `resume`，不自动重试。
+
+## 16. 设计检查清单
+
+> 标 `（可选）` 的仅当对应可选模式启用时才需勾。
+
+- [ ] 默认 `--format json`
+- [ ] stdout 仅含合法 JSON / NDJSON，无污染
+- [ ] 日志与进度全部走 stderr
+- [ ] 成功/失败同形 envelope，含 `ok` 与 `schema_version`
+- [ ] `error` 含语义化 `code`、`details`、`retryable`
+- [ ] exit code 分层且与 `retryable` 一致
+- [ ] 写命令具备 dry-run / confirm-token 闭环
+- [ ] confirm token 绑定操作参数、账号、权限上下文和资源版本
+- [ ] 提供 `reference` / `context` / `doctor`
+- [ ] 提供 `changelog [--since]`，与 CHANGELOG/release-notes 同源
+- [ ] 工具可报告自身版本（`--version` 与 `context.version`）
+- [ ] `reference` 报告 `release_readiness`，`doctor` 检查它
+- [ ] （含 self-update 时）实现 `update --check` / `--dry-run` / `--confirm`
+- [ ] （含 self-update 时）release 完整性被校验，签名状态显式返回
+- [ ] （含 self-update 时）整个 Skill 目录同步纳入 update 结果
+- [ ] （含 self-update 时）更新后回传 previous/current 版本并提示读 changelog
+- [ ] 查询命令支持 `fields` / `compact`
+- [ ] 列表命令支持分页或明确说明无需分页
+- [ ] README / Skill / reference / help / context / doctor / changelog / update 中声明的公开行为达到 100% 功能契约覆盖率
+- [ ] Stable release 有真实环境 smoke/E2E 记录；否则工具声明为 `beta`
+- [ ] 所有时间为 ISO 8601 UTC
+- [ ] 所有 ID 为字符串
+- [ ] 敏感信息全链路脱敏
+- [ ] schema 变更有版本与兼容策略
+- [ ] stdout/stderr 为 UTF-8 无 BOM
+- [ ] （可选·令牌过期）`context`/`doctor` 报告凭证有效性与过期，刷新失败降级 `E_AUTH`
+- [ ] （可选·长任务）提交返回 `job_id` + 状态枚举，状态/结果分离
+- [ ] （可选·需人工）卡人工步骤返回 `E_HUMAN_REQUIRED`（exit 9）+ `resume`，不自动重试