maoda-commander-tt 0.0.47 → 0.0.49

package/README.md

@@ -1,36 +1,71 @@
-# template-commander
+# template-commander (`tt`)
 
-一个基于 [commander](https://github.com/tj/commander.js) 的通用 CLI 模板项目，采用面向对象架构设计，支持快速扩展子命令。
+一个 AI-native 的通用 CLI：默认调用方是 AI agent。每个命令在 stdout 只输出一行
+JSON envelope，诊断与进度走 stderr，失败退出码为 1，`--help` 自带面向 agent 的调用契约。
+基于 [commander](https://github.com/tj/commander.js) 与 [rockbed](https://www.npmjs.com/package/rockbed)
+（`Result` / `Disposable` / `Emitter`）。
 
 ## 特性
 
-- **面向对象架构** — 所有命令继承 `BaseCommand<TOptions>`，统一生命周期管理
-- **Disposable 体系** — 继承自 rockbed `Disposable` 基类，自动管理资源释放
-- **事件系统** — 基于 rockbed `Emitter` 提供 `onBeforeExecute` / `onAfterExecute` 等生命周期钩子
-- **结构化错误处理** — 使用 `Result<T>` 代替 throw/reject，错误码可追溯
-- **TypeScript 严格模式** — 全量 strict，类型安全
-- **开发热调试** — 基于 tsx 直接运行 TS，支持 `--inspect` 调试
+- **Agent 输出契约（tt.agent.v1）** — stdout 一行 JSON、stderr 结构化进度、退出码语义稳定，
+  Commander 的输入错误也以同样的 envelope 输出
+- **命令只返回 `Result<TData>`** — `ok(data)` / `fail(code, msg, { stage, nextCommand, ... })`，
+  基类负责输出与退出码；`passthrough` 模式用于透传 git、开发服务器等面向人的场景
+- **清晰分层** — `core`（框架）→ `commands`（表现）→ `modules`（领域）→ `bedrock`（基础设施）
+- **可发现性** — `tt --help` 列公开命令，`tt -hh` 含隐藏命令；每个命令 `--help` 含示例与契约
+- **Disposable / 事件** — 命令与服务继承 `Disposable`，提供 `onBeforeExecute` / `onAfterExecute`
+- **TypeScript strict + node:test** — 全量 strict，测试与源文件同目录
+
+## Agent 调用契约
+
+```bash
+$ tt hello greet
+{"code":0,"msg":"success","data":{"message":"Hello, World!"}}
+
+$ tt deploy --bogus ; echo "exit=$?"
+{"code":1,"msg":"unknown option '--bogus'","error":{"stage":"input"}}
+exit=1
+
+$ tt ai video wait --task-id bad ; echo "exit=$?"
+{"code":18017,"msg":"...","error":{"stage":"wait","taskId":"bad","recoverable":true,"nextCommand":"tt ai video wait --task-id bad"}}
+exit=1
+```
+
+- 成功：`{"code":0,"msg":"success","data":...}`；失败：`{"code":非0,"msg":...,"error"?:{...},"data"?:...}`。
+  `error.stage` 说明失败阶段，`error.nextCommand` 是可直接执行的后续命令，
+  `data` 是失败时仍成立的部分结果（如“已发布但校验失败”）。
+- stderr 上的 `{"protocol":"tt.agent.v1","type":"progress",...,"final":false}` 只是进度，
+  必须等待进程退出后再读取 stdout。
+- 个别命令允许成功退出但业务码非 0（如 `tool get-config` 未配置返回 `16003`），
+  会在该命令 `--help` 的“Agent 调用契约”里写明。
 
 ## 目录结构
 
 ```
 template-commander/
 ├── src/
-│   ├── main.ts                    # 入口文件
-│   ├── core/
-│   │   ├── cli-app.ts             # CliApp 主应用类
-│   │   ├── base-command.ts        # BaseCommand 抽象基类
-│   │   └── command-types.ts       # 命令元信息类型
-│   ├── commands/
-│   │   ├── hello/                 # 示例命令组
-│   │   ├── pippit/                # pippit 命令组
-│   │   └── git/                   # 新增 git 命令组
-│   └── bedrock/                   # 本地补充基础设施
-│       ├── config/                # 本地配置读写
-│       ├── pkg/                   # package.json 查找
-│       └── uuid/                  # UUID 工具
-├── package.json
-└── tsconfig.json
+│   ├── main.ts                 # 可执行入口：注册 createRootCommands() 并运行 CliApp
+│   ├── index.ts                # 库入口：导出 core 与内置命令
+│   ├── core/                   # 命令框架（唯一依赖 commander 的层）
+│   │   ├── cli-app.ts          # 根命令、-hh、根级输入错误 envelope、退出码
+│   │   ├── abstract-command.ts # Command 懒构建、生命周期、按输出模式输出
+│   │   ├── base-command.ts     # 叶子命令（默认 json）
+│   │   ├── base-command-group.ts # 命令组（默认 passthrough，打印帮助）
+│   │   ├── agent-protocol.ts   # envelope 类型、fail()/failFrom()
+│   │   ├── agent-progress.ts   # stderr 进度心跳
+│   │   └── command-meta.ts     # ICommandMeta: name/description/aliases/hidden/output
+│   ├── commands/               # CLI 表现层，每个命令组一个目录
+│   │   ├── index.ts            # 顶层注册表 createRootCommands()
+│   │   ├── ai/  deploy/  git/  hello/  pippit/  shortcut/  tool/
+│   ├── modules/                # 领域逻辑：不依赖 commander，返回 Result<T>
+│   │   ├── ark/  git/  pippit/  static-deploy/  video-generation/  xyq/  xyq-tasks/
+│   ├── bedrock/                # 与业务无关的基础设施
+│   │   ├── config/  cross-app-settings/  download/  pkg/  process/  uuid/
+│   └── constants/              # 兼容性常量（已弃用的内置回退值）
+├── scripts/release.mjs         # 发布脚本
+├── ops/static-deploy/          # 服务器侧部署说明
+├── AGENTS.md                   # agent 工作 harness（契约、分层、发布）
+└── package.json
 ```
 
 ## 快速开始
@@ -41,21 +76,20 @@ template-commander/
 # 安装依赖
 pnpm install
 
-# 开发运行
-pnpm dev -- --help
-pnpm dev -- hello Alice
-pnpm dev -- hello Alice -u
-pnpm dev -- git mm "update docs"
-pnpm dev -- git pp -n
+# 开发运行（pnpm 会把额外参数直接传给 tsx，不要再写 `--`，否则 commander 会把它当作选项结束符）
+pnpm dev --help
+pnpm dev -hh                         # 含隐藏命令的完整列表
+pnpm dev hello greet Alice -u
+pnpm dev git mm "update docs"
+pnpm dev ai video --help
 
 # 调试模式 (支持 Chrome DevTools / VS Code 断点)
-pnpm dev:debug -- hello Alice
-
-# 构建
-pnpm build
+pnpm dev:debug hello greet Alice
 
-# 运行编译产物
-pnpm start -- --help
+# 类型检查、测试、构建、产物冒烟
+pnpm exec tsc --noEmit -p .
+pnpm test
+pnpm build && pnpm test:dist
 ```
 
 ## 发布到 npm
@@ -135,6 +169,141 @@ pnpm pub
 
 参见 [npm Trusted Publishing 文档](https://docs.npmjs.com/trusted-publishers/)。
 
+## 静态文件部署
+
+`tt deploy` 通过 HTTPS API 将现成的文件或目录部署到 nginx 静态目录，不执行构建。
+命令面向 AI 调用：stdout 只输出一个最终 JSON，诊断信息写入 stderr；失败时退出码为 1。
+`tt --help` 可发现该命令，`tt deploy --help` 查看完整说明。
+
+```bash
+# 将 dist 的内容直接部署为 demo 项目
+tt deploy ./dist --name demo
+
+# 单文件默认保持文件名，也可以用 --name 指定目标文件名
+tt deploy ./report.pdf
+tt deploy ./report.pdf --name latest-report.pdf
+
+# 查看部署根下的直接子目录及访问链接
+tt deploy --list
+
+# 不可恢复地删除根下一级文件或整个项目目录
+tt deploy --delete report.pdf
+tt deploy --delete demo
+```
+
+**独立项目直接部署在 tt 根目录下，无需刻意嵌套。** 当前服务器目标为
+`/root/repos/tt`：`tt deploy ./dist --name demo` 将目录内容直接放入
+`/root/repos/tt/demo/`，对应 `https://www.imaoda.com/tt/demo/`，不会额外套一层 `dist/`。
+目标名称只能是根下一级的名称，不能传 `group/demo`；`__catalog` 是保留名称。
+省略 `--name` 时使用源文件或目录的名称。
+
+**HTML 的静态资源使用相对于 HTML 的路径**，例如 `./assets/app.js`、`./style.css`
+和 `./images/cover.png`。避免 `/assets/app.js` 这类从域名根目录开始的路径，否则
+浏览器会请求项目目录之外的位置。部署前先产出适合子路径访问的静态文件。
+
+每次部署完整替换同名目标，包括移除旧版本中存在、本次已删除的文件。命令先上传到
+临时位置，上传成功后再发布。空目录会在上传前报错；目录里的符号链接和敏感文件
+（如 `.git`、`.env`、私钥）会导致整次部署拒绝，请只提供准备公开的静态产物。
+点开头的路径不会通过 nginx 公开；如果目录里只有这类文件，也会因没有可验证的
+公开内容而拒绝部署。
+
+### 本机配置与接口鉴权
+
+在 `~/.config/maoda-commander-tt/maoda-commander-tt.json` 的已有配置中增加
+`staticDeploy` 字段，保留其他字段。将示例 token 替换为已配置到服务器的固定 token：
+
+```json
+{
+  "staticDeploy": {
+    "apiUrl": "https://www.imaoda.com/api/tt",
+    "token": "<你的固定部署 token>"
+  }
+}
+```
+
+`apiUrl` 指向部署 API，命令自动为请求添加 `Authorization: Bearer <token>`。
+固定 token 只保存在本机配置中，不打包到 npm，也不放进命令行参数、公开目录或
+返回结果。部署不需要本机 SSH 权限；换电脑时配置同一 API 地址及 token 即可。
+本机需要 Node.js 22.13.0 或更高版本和 `tar`。API 只接受 HTTPS（本机测试的
+loopback HTTP 除外），客户端不跟随重定向，以免将 token 发送到其他地址。
+
+服务器使用 `TT_DEPLOY_TOKEN` 验证部署、删除和目录查询请求；`TT_DEPLOY_ROOT` 和
+`TT_DEPLOY_BASE_URL` 决定落盘根目录和公开 URL，不由调用端任意指定。
+当前限制为每次归档 50 MiB、最多 2 个并发操作。收到 token 的人可以部署、覆盖或删除
+这个根目录下的项目；需要更换时同时更新服务器和本机配置。
+
+服务器需要预先配置 API 和 nginx 路由，参见 [部署运维说明](ops/static-deploy/README.md)。
+当前服务器在静态入口上
+保留既有跨域响应头、OPTIONS 预检及 HSTS，并设置 `Cache-Control: no-cache`：
+允许浏览器缓存，但再次使用前向服务器确认内容是否更新。
+
+### 目录页与 AI 返回值
+
+浏览器目录入口为 `https://www.imaoda.com/tt/__catalog/`，JSON 清单入口为
+`https://www.imaoda.com/tt/__catalog/index.json`。目录页只列 `/root/repos/tt`
+下的直接子目录及链接，不列其他仓库、根下单文件或子目录里的文件；`/tt/` 本身
+不开放目录浏览。入口采用固定名称，知道链接的人都能看，不提供身份认证。
+每次部署、删除和 `--list` 都会更新清单，AI 可直接使用 `tt deploy --list` 获取同一范围。
+
+有首页的目录部署成功后，返回示例：
+
+```json
+{
+  "code": 0,
+  "msg": "success",
+  "data": {
+    "name": "demo",
+    "type": "directory",
+    "state": "ready",
+    "url": "https://www.imaoda.com/tt/demo/",
+    "baseUrl": "https://www.imaoda.com/tt/demo/",
+    "remotePath": "/root/repos/tt/demo",
+    "verification": {
+      "state": "passed",
+      "checkedUrl": "https://www.imaoda.com/tt/demo/",
+      "httpStatus": 200
+    }
+  }
+}
+```
+
+只有服务器通过公开 URL 与文件 SHA-256 验收才报告 `ready`；这表示已检查文件
+可访问且内容一致，不能替代浏览器
+渲染和全站资源检查。目录优先使用 `index.html` 或 `index.htm` 作为首页；没有首页
+但含有文件时，`url` 为 `null`，`baseUrl` 保留目录地址，`verification.checkedUrl`
+指向实际检查的文件，AI 不应把目录地址当作已可访问的页面。
+
+文件已经发布但访问检查失败时，返回 `code: 1`、`error.stage`，同时保留
+`data.state: "published"`、URL、远端路径和检查结果，退出码为 1。AI 可以据此继续
+排查访问问题；参数、配置或上传等发布前错误不附带虚构的发布成功数据。
+
+`tt deploy --list` 的 `data` 包含 `catalogUrl` 和
+`directories: [{ "name": "demo", "url": ".../demo/", "hasIndex": true }]`。
+`hasIndex: false` 表示该目录没有首页，链接不保证返回页面。
+
+### 删除文件或项目目录
+
+`tt deploy --delete <name>` 删除 tt 根目录下的一个直接子项，可以是单文件，也可以
+是包含多层内容的整个目录。删除不可恢复，无需交互确认；其他顶层项目保留。
+名称必须是一级名称，不支持 `demo/style.css` 这样的内部路径，不能与本地 source、
+`--name` 或 `--list` 同时使用，且不能删除保留名称 `__catalog`。
+
+删除后刷新目录清单。成功时返回 `code: 0`，`data` 示例：
+
+```json
+{
+  "name": "demo",
+  "type": "directory",
+  "state": "deleted",
+  "remotePath": "/root/repos/tt/demo",
+  "catalogUrl": "https://www.imaoda.com/tt/__catalog/"
+}
+```
+
+目标已不存在时同样成功，返回 `state: "absent"`、`type: null`，便于重复调用。
+若公开目标已删除，但目录清单刷新或私有暂存清理失败，命令返回错误和非零退出码，
+同时保留 `data.state: "deleted"`；AI 应据此排查后续步骤，不能把它理解为目标仍在。
+
 ## Shell 快捷方式
 
 ```bash
@@ -144,124 +313,221 @@ tt sc w2
 
 命令日志直接输出到当前终端，gateway 在前台运行。
 
+## AI 图片生成
+
+图片、音频与视频统一采用异步提交：默认返回 `taskId`，`status` 单次查询，
+`wait` 等待已有任务，`--output` 隐含 `--wait`。生成是否成功以 `data.state` 为准，
+不能只看查询命令的 `code=0`；超时返回 `data.timedOut=true`，不会取消生成。
+
+`ai image` 保存本机任务并启动独立后台进程，确认接管后返回
+`taskId`、当前 `state` 和 `nextCommand`。图片 ID 格式为 `local-image:<uuid>`；
+`submitted` 表示本地任务已受理，`working` 表示后台进程正在执行。
+
+```bash
+# 默认仅提交；后台继续生成
+tt ai image '画一片绿色树叶'
+
+# 一次调用等待并保存；也可仅用 --wait 返回归档图片路径
+tt ai image --output ./result.png '画一片绿色树叶'
+
+# 查询、等待同一个任务，不会重新生成
+tt ai image status --task-id 'local-image:<uuid>'
+tt ai image wait --task-id 'local-image:<uuid>' --timeout-seconds 600 --output ./result.png
+
+# 没收到提交输出或丢失 ID 时，查看本机持久记录
+tt ai image list
+```
+
+等待默认 360 秒，上限 600 秒。完成时 `outputs[].localPath` 为绝对路径；再次
+`wait --output` 只复制已有产物。参考图继续通过提示词中的绝对路径提供。
+`--quiet` 关闭提交进度；stdout 始终只有一个最终 JSON envelope。
+
+任务记录默认位于 `~/.tt/ai/image-tasks`，可用 `TT_AI_IMAGE_TASKS_DIR` 指定持久目录。
+每个任务独立保存请求、内部 Codex 会话 ID 和产物；`list` 返回任务状态，
+不会暴露提示词和会话内容。图片经完整 PNG 校验后原子归档，查询仅认已归档产物。
+这些记录不会随 `ai video cache clear` 清理。
+
+后台任务可以在提交命令退出后继续执行；机器重启或 worker 失联后，若无完整归档
+图片，会报告 `state=unknown`，不会隐式 `codex exec resume` 或重新生成。
+仅存在临时文件不代表完成。新命令不是跨机器任务服务，也不保证生图工具中断后
+能接回同一次远端生成。Codex 会话会保留，便于后续诊断。
+
+迁移旧调用：`tt ai image '...'` 若需要直接拿文件，改为
+`tt ai image --wait '...'`，读取 `data.outputs[0].localPath`，不再读取旧 `imagePath`。
+外部 `generate` 技能中依赖同步行为的命令也需在升级 tt 时加 `--wait`。
+
 ## AI 音频生成
 
-`ai audio` 接受一段自然语言提示词并等待 XYQ 返回 MP3。参考音频可选；提供时，
+`ai audio` 接受一段自然语言提示词，完成远端提交后返回 `taskId`、
+`state=submitted` 和 `nextCommand`。参考音频可选；提供时，
 提示词需自行用 `@音频1` 引用它，命令不会改写提示词。
 
 ```bash
-# 纯文本生成音频
+# 提交纯文本生成音频任务
 tt ai audio '萝莉音说：“我今天不回来了”'
 
 # 参考一段本地音频的音色
 tt ai audio --audio ./reference.mp3 \
   '@音频1 参考它的音色，说：“我生气了，哼”'
 
-# 等待生成并下载到本地；省略 --output 时返回远端地址
+# 等待生成并下载到本地（--output 隐含 --wait）
 tt ai audio --audio ./reference.mp3 --output ./result.mp3 \
   '@音频1 参考它的音色，说：“我生气了，哼”'
 ```
 
-命令固定使用 `seedaudio_1.0`、MP3 和 44.1 kHz，最多等待 60 秒。参考音频直接
-上传，不进入持久素材缓存。
+继续查询或等待既有任务：
+
+```bash
+tt ai audio --wait '用温柔的声音说：“晚安”'
+tt ai audio status --task-id 'xyq:<threadId>'
+tt ai audio wait --task-id 'xyq:<threadId>' --timeout-seconds 600 --output ./result.mp3
+```
+
+命令固定使用 `seedaudio_1.0`、MP3 和 44.1 kHz；等待默认 60 秒，可通过
+`--timeout-seconds` 设为 1–600 秒。参考音频直接上传，不进入持久素材缓存。
+云端产物字段统一为 `outputs[].downloadUrl`，本地产物为 `outputs[].localPath`；
+旧同步调用需增加 `--wait`，旧 `remoteUrl` 读取需迁移到 `downloadUrl`。
+超时保留 `taskId` 与 `nextCommand`，下载异常的恢复命令还保留绝对输出路径。
+音频和视频尚无本机任务列表，调用方须保存提交返回的 ID；查询仍需对应账号权限。
+
+## AI 视频生成
+
+`ai video` 同步完成会话初始化、素材上传与远端任务创建后返回 `taskId`，生成本身
+异步进行（通常约 5 分钟）。提交期间 stderr 每 10 秒输出一次 `progress` 事件。
+
+```bash
+# 提交并立即返回 taskId 与 nextCommand
+tt ai video --duration-seconds 8 --images ./ref.png '图1 中的角色转身微笑'
+
+# 一次调用等到结束并下载最高画质产物（隐含 --wait）
+tt ai video --duration-seconds 8 --output ./result.mp4 '海边日出，慢镜头'
+
+# 用 taskId 查询/等待既有任务
+tt ai video status --task-id xyq:<threadId>
+tt ai video wait --task-id xyq:<threadId> --timeout-seconds 600 --output ./result.mp4
+```
+
+等待超时不是失败：`wait` 返回 `timedOut: true` 与当前 `state`，可用同一 `taskId`
+继续等待；`ai video --wait` 和 `--output` 同样在 `data` 中返回当前状态与 `timedOut`。
+查询或下载异常时，`error` 中保留 `taskId`、`recoverable` 和恢复命令。
+
+## 联网搜索
+
+`ai websearch` 通过火山方舟 Responses API 的 `web_search` 工具搜索，`data.text`
+是回答正文，`data.content` 是含引用标注的原始数组。API Key 按
+`ARK_API_KEY` 环境变量 → 跨应用设置 `ark.apiKey` → 内置回退值 的顺序解析。
 
 ## 如何扩展新命令
 
-1. 在 `src/commands/` 下新建文件，创建继承 `BaseCommand<TOptions>` 的类：
+1. 在 `src/commands/<group>/` 下新建 `xxx-command.ts`，继承 `BaseCommand<TOptions, TData>`：
 
 ```typescript
-import type { Command } from 'commander';
-import { BaseCommand } from '../core/base-command.js';
-import type { ICommandActionContext } from '../core/base-command.js';
-import type { ICommandMeta } from '../core/command-types.js';
-import type { Result } from 'rockbed/error';
+import type { Command } from "commander";
+import { ok, type Result } from "rockbed/error";
+import { BaseCommand, fail } from "../../core";
+import type { ICommandActionContext, ICommandMeta } from "../../core";
+import { doSomething } from "../../modules/my-domain";
 
 interface IMyOptions {
-  verbose: boolean;
+  readonly verbose: boolean;
 }
 
-export class MyCommand extends BaseCommand<IMyOptions> {
+interface IMyOutput {
+  readonly target: string;
+  readonly result: string;
+}
+
+export class MyCommand extends BaseCommand<IMyOptions, IMyOutput> {
   protected _meta(): ICommandMeta {
-    return {
-      name: 'my-cmd',
-      description: '这是我的自定义命令',
-      aliases: ['mc'],
-    };
+    return { name: "my-cmd", description: "这是我的自定义命令", aliases: ["mc"] };
+    // hidden: true 隐藏；output: "passthrough" 透传子进程输出
   }
 
   protected _configureArguments(cmd: Command): void {
-    cmd.argument('<target>', '操作目标');
+    cmd.argument("<target>", "操作目标");
   }
 
   protected _configureOptions(cmd: Command): void {
-    cmd.option('--verbose', '详细输出', false);
+    cmd.option("--verbose", "输出更多诊断到 stderr", false);
   }
 
-  protected async _execute(ctx: ICommandActionContext<IMyOptions>): Promise<Result<void>> {
-    const target = ctx.args[0] as string;
+  protected _agentContract(): readonly string[] {
+    return ["data.result 为处理结果；target 不存在时 error.stage=input。"];
+  }
 
+  protected async _execute(
+    ctx: ICommandActionContext<IMyOptions>,
+  ): Promise<Result<IMyOutput>> {
+    const target = String(ctx.args[0] ?? "").trim();
+    if (!target) {
+      return fail(1, "请指定 target", { stage: "input" });
+    }
     if (ctx.options.verbose) {
-      console.log(`[verbose] target = ${target}`);
+      this._debug(`target = ${target}`); // 写 stderr，不污染 stdout
     }
-
-    // 业务逻辑...
-
-    return this._makeOk();
-    // 或错误: return this._makeError(1001, '发生了某种错误');
+    const result = await doSomething(target); // Result<string>
+    if (!result.ok) {
+      return fail(result.code, result.msg, { stage: "process", target });
+    }
+    return ok({ target, result: result.value });
   }
 }
 ```
 
-2. 在 `src/main.ts` 中注册：
+2. 注册：顶层命令加入 `src/commands/index.ts` 的 `createRootCommands()`；
+   子命令在所属命令组的 `_registerSubcommands()` 中 `this._addSubcommand(new MyCommand())`。
+3. 在同目录添加 `my-command.test.ts`：mock `process.stdout.write`，
+   调用 `new MyCommand().command.parseAsync([...], { from: "user" })`，断言 envelope 与 `process.exitCode`。
 
-```typescript
-import { MyCommand } from './commands/my-command.js';
-
-app.registerCommand(new MyCommand());
-```
-
-完成！新命令会自动出现在 `--help` 输出和 `help [command]` 中。
+新命令会自动出现在 `--help`、`help [command]` 中，并自动获得“执行案例”和“Agent 调用契约”页脚。
 
 ## 架构说明
 
-### BaseCommand
+### 分层与依赖方向
+
+`core`（框架，唯一依赖 commander）← `commands`（参数定义、把领域 `Result` 整形为 `data`）
+→ `modules`（领域逻辑，返回 `Result<T>`，不写 stdout）→ `bedrock`（进程、下载、配置等基础设施）。
+依赖只能向下，`modules`/`bedrock` 不得引用 `commands`/`core`。
 
-每个子命令需要实现：
+### 命令基类
 
-| 方法 | 说明 |
+| 成员 | 说明 |
 |---|---|
-| `_meta()` | 返回命令名、描述、别名 |
-| `_execute(ctx)` | 命令核心逻辑，返回 `Result<void>` |
-| `_configureOptions(cmd)` | (可选) 配置 commander 选项 |
-| `_configureArguments(cmd)` | (可选) 配置 commander 参数 |
-| `getExample()` | 根据已注册的参数和选项自动生成命令执行示例 |
+| `_meta()` | 名称、描述、别名、`hidden`、`output` |
+| `_execute(ctx)` | 核心逻辑，返回 `Result<TData>`；json 模式下由基类输出 envelope |
+| `_configureOptions(cmd)` / `_configureArguments(cmd)` | 配置 commander 选项/参数 |
+| `_agentContract()` | 该命令特有的契约行，追加到 `--help` |
+| `_toSuccessEnvelope(data)` | 覆盖成功 envelope（如成功退出但业务码非 0） |
+| `_debug(text)` | 写 stderr 诊断 |
+| `_output(text)` | 仅 passthrough 模式：写 stdout |
+| `BaseCommandGroup._registerSubcommands()` | 命令组挂接子命令 |
 
-### 生命周期事件
+commander `Command` 在首次访问 `.command` 时才构建，因此上述钩子可以使用构造函数注入的服务。
+
+### 错误处理
 
 ```typescript
-const cmd = new HelloCommand();
-cmd.onBeforeExecute(() => console.log('即将执行'));
-cmd.onAfterExecute((result) => {
-  if (result.ok) console.log('执行成功');
-  else console.log(`执行失败: [${result.code}] ${result.msg}`);
-});
+import { err, ok } from "rockbed/error";
+import { fail, failFrom } from "../../core";
+
+return ok(data);                                        // {"code":0,"msg":"success","data":...}
+return fail(1001, "文件不存在", { stage: "read" });      // {"code":1001,"msg":"...","error":{"stage":"read"}}
+return fail(1, "已发布但校验失败", { stage: "verify" }, { state: "published" }); // 附带部分结果 data
+return failFrom(domainResult, { stage: "upload", taskId }); // 保留领域错误码/消息，补充 agent 细节
+return err(1, "plain");                                 // {"code":1,"msg":"plain"}
 ```
 
-### 错误处理
+长耗时命令使用 `createAgentProgressReporter({ enabled, command, phase, message })`
+向 stderr 输出 `tt.agent.v1` 进度事件，`dispose()` 后停止。
 
-使用 `Result<T>` 而非 throw：
+### 生命周期事件
 
 ```typescript
-// 成功
-return this._makeOk();
-
-// 失败 (错误码 + 消息)
-return this._makeError(1001, '文件不存在');
-
-// 也可定义可复用错误
-import { defineError } from 'rockbed/error';
-const missingNameError = defineError(1002, '参数 name 不能为空');
-return missingNameError();
+const cmd = new HelloGreetCommand();
+cmd.onBeforeExecute((ctx) => console.error("即将执行", ctx.args));
+cmd.onAfterExecute((result) => {
+  if (!result.ok) console.error(`执行失败: [${result.code}] ${result.msg}`);
+});
 ```
 
 ## Scripts
@@ -270,7 +536,9 @@ return missingNameError();
 |---|---|
 | `pnpm dev` | 使用 tsx 直接运行（开发用） |
 | `pnpm dev:debug` | 启动 Node inspect 调试 |
-| `pnpm build` | TypeScript 编译 |
+| `pnpm test` | 运行全部 `*.test.ts`（node:test） |
+| `pnpm build` | tsup 构建 `dist/main.js`（CLI）与 `dist/index.js`（库） |
+| `pnpm test:dist` | 构建产物冒烟（`--help`） |
 | `pnpm start` | 运行编译后产物 |
 | `pnpm clean` | 清理 dist 目录 |
 | `pnpm test:release` | 在临时 Git 仓库中验证发布脚本 |
@@ -282,5 +550,5 @@ return missingNameError();
 
 - TypeScript 5.x (strict mode)
 - commander 13.x
-- chalk 5.x
-- tsx (开发热运行)
+- rockbed (`Result` / `Disposable` / `Emitter`)
+- tsx (开发热运行)、tsup (构建)、node:test (测试)