tirtc-devtools-cli 0.0.5 → 0.0.7

package/README.md

@@ -6,11 +6,13 @@
 
 关于 `tirtc-devtools-cli` 命令的详细使用方法、参数说明与示例，请参考 [USAGE.md](./USAGE.md)。
 
+如果要先快速确认当前 binary 暴露了哪些命令面，直接运行：`node devtools/cli/bin/tirtc-devtools-cli.js --help`。
+
 ## 负责什么
 
 - **唯一用户产品门面**：提供 `tirtc-devtools-cli` 命令族，覆盖常见的 RTC 测试操作，让内部研发、外部开发者和 AI agent 脚本无需手写底层协议。
 - **配置解析与翻译**：负责解析用户传入的 CLI 参数和 TOML 配置文件，进行本地必填校验、脱敏，并翻译为 App Server 协议的 request。
-- **产品级 Observability**：将底层的运行时事件和状态翻译为结构化输出 (JSON) 或友好的终端日志输出。
+- **产品级 Observability**：将底层的运行时事件和状态翻译为结构化输出 (JSON) 或友好的终端日志输出；对长耗时命令补轻量进度提示。
 - **调试期工具内聚**：承接调试期必要工具（如 token bootstrap、二维码与媒体预处理）的产品化入口，避免把调试流程散落在 runtime 或外部手工步骤中。
 - **本地 token 工具**：提供直接签发 token、打印组合 JSON、单独 token 与本地二维码 PNG 路径的公开 CLI 能力，服务本地联调与体验验证。
 
@@ -49,4 +51,4 @@
 
 - 本地测试配置文件路径：`devtools/cli/tests/.local/runtime-backed.e2e.local.json`（必需，已在 `.gitignore` 忽略）。
 - 示例模板：`devtools/cli/tests/runtime-backed.e2e.config.example.json`。
-- 推荐先运行 `tirtc-devtools-cli media assets prepare --source .refers/simple.mp4 --output-root ./.tmp/tirtc-devtools-cli/assets`，再把 `assetsDir` 指向返回的 `assets_dir`。
+- CLI server-only 正式 E2E 现在直接读取 `mp4Path`，由 `service start` 内部自动 prepare；不再要求先手工 prepare 再维护 `assetsDir`。

package/USAGE.md

@@ -2,435 +2,222 @@
 
 `tirtc-devtools-cli` 是基于 `app-server/host` 的命令行门面，用来控制会话、服务、连接、流、命令通道与调试工具。
 
-## 一、先说清楚关系
+## 一、关系
 
-- Runtime：底层内核能力（transport/audio/video/media/facade）。
-- App Server：把 Runtime 组织成稳定控制面协议（Host 进程）。
-- CLI（`devtools/cli`）：面向用户的命令行门面，通过协议控制 App Server。
+- Runtime：底层 transport/audio/video/media 能力。
+- App Server：把 Runtime 组织成稳定控制面协议。
+- CLI：面向用户的命令行门面，通过协议驱动 App Server。
 
-也就是说：CLI 不是独立重做一套 RTC 能力，而是消费 App Server；App Server 再消费 Runtime。
-
-## 二、如何编译“最新”CLI
-
-你提到的重点是对的：不仅要“安装”，还要能拿到**最新源码构建产物**。
-
-### 1) 开发态构建（最快）
+## 二、开发态构建
 
 ```bash
-npm --prefix app-server ci && \
- npm --prefix devtools/cli ci && \
- npm --prefix app-server run build && \
- npm --prefix devtools/cli run build
+npm --prefix app-server ci
+npm --prefix devtools/cli ci
+npm --prefix app-server run build
+npm --prefix devtools/cli run build
 ```
 
-构建后可直接运行：
+运行入口：
 
 ```bash
 node devtools/cli/bin/tirtc-devtools-cli.js --help
 ```
 
-### 2) 发布态打包（可分发二进制）
+## 三、Help 菜单速览
 
-按统一链路执行（先准备 runtime，再打包产品）：
+安装或构建完成后，先用 help 菜单确认当前 binary 暴露的命令面：
 
 ```bash
-./runtime/script/prepare_product_runtime.sh --platform macos-arm64 --consumer both
-./app-server/script/package.sh
-./devtools/cli/script/package.sh
+node devtools/cli/bin/tirtc-devtools-cli.js --help
 ```
 
-产物位置：
-
-- App Server：`app-server/bin/dist/`
-- CLI：`devtools/cli/bin/dist/`
+当前顶层 help 快照：
+
+```text
+Usage: tirtc-devtools-cli [options] [command]
+
+TiRTC DevTools CLI
+
+Options:
+  --config <path>        配置文件路径（TOML）
+  --json                 以机器可读 JSON 输出（便于脚本集成）
+  --session <sessionId>  指定会话 ID；除 service start/connect 外必须传
+  -h, --help             display help for command
+
+Commands:
+  host        Host 基础能力（状态、停止）
+  init        新手第一步：生成 CLI 配置模板
+  media       媒体素材辅助：prepare local assets
+  service     服务端能力：启动/停止服务，等待远端接入
+  connection  客户端能力：主动连接远端 peer
+  token       Token 工具：签发 token，并输出可直接使用的 JSON 与本地二维码 PNG
+  stream      流控制：发送/接收/消息
+  output      输出挂载：文件等消费者 attach/detach
+  command     命令通道：发送命令与事件跟踪
+  debug       调试工具：连接 bootstrap 二维码
+  events      事件订阅：实时观察 Host 事件
+  logs        日志导出：导出运行日志
+  report      报告查看/导出：验收证据
+  guide       新手入口：按场景给出可执行步骤
+```
 
-### 3) 一键验收（推荐）
+常用子菜单 help：
 
 ```bash
-./script/acceptance_app_server_devtools.sh
+node devtools/cli/bin/tirtc-devtools-cli.js service --help
+node devtools/cli/bin/tirtc-devtools-cli.js stream --help
+node devtools/cli/bin/tirtc-devtools-cli.js command --help
+node devtools/cli/bin/tirtc-devtools-cli.js token issue --help
+```
+
+当前关键子菜单快照：
+
+```text
+$ node ... service --help
+Commands:
+  start  启动 server-only 会话（必须显式提供 --config）
+  stop   停止服务端监听
+
+$ node ... stream --help
+Commands:
+  list                                 查看流快照列表
+  send                                 发送流：绑定 prepared local assets 并发起上行
+  receive                              接收流：声明并接收下行
+  message <send> <streamId> <payload>  发送 UTF-8 字符串型 stream message
+
+$ node ... command --help
+Commands:
+  send <commandId> <kind> <payloadEncoding> <payload>  发送字符串型命令并等待响应
+  tail                                                 持续监听命令相关事件
+
+$ node ... token issue --help
+Options:
+  --access-id <accessId>
+  --secret-key <secretKey>
+  --local-id <localId>
+  --openapi-entry <url>
+  --service-entry <entry>
+  --user-ttl-seconds <seconds>
+  --channel-ttl-seconds <seconds>
+  --qr-error-correction-level <level>
+  --ascii-max-columns <columns>
 ```
 
-## 三、全局参数
+## 四、全局参数
 
 - `--config <path>`：TOML 配置文件路径。
 - `--json`：结构化 JSON 输出。
-- `--session <sessionId>`：指定会话（除 `service start` / `connection connect` 外必须显式传）。
+- `--session <sessionId>`：除 `service start` / `connection connect` 外，其余业务命令必须显式提供。
 
-## 四、会话模型
+## 五、会话模型
 
 一个 session = 一个常驻 Host 进程 + 一个 endpoint runtime 实例。
 
-- `tirtc-devtools-cli host session start`：创建会话，返回 `sessionId`
-- `tirtc-devtools-cli host session list`：查看会话
-- `tirtc-devtools-cli host session stop <sessionId>`：停止会话
-
-设计约束：
-
-- 单机同一时刻只允许一个 `service` 会话；再次 `service start` 会直接失败并提示先停止已有服务会话。
-- `service start`：自动创建一个 session（也可通过 `--session` 绑定已有 session）。
-- `connection connect`：总是创建新的 session（不支持复用已有 session），允许多个 client 会话并行。
-- 除上述两条入口命令外，其他业务命令都必须显式传 `--session <sessionId>`。
-
-## 五、命令总览
-
-### Config
-
-用途：初始化 CLI 配置文件，作为后续 `service/debug/logging` 等命令的参数来源。
-
-- `tirtc-devtools-cli init [outputPath]`：生成配置模板；不传路径时默认写入 `./.tmp/tirtc-devtools-cli/config.toml`。
-
-### Host
-
-用途：管理 Host 进程生命周期与会话健康状态。
-
-- `tirtc-devtools-cli host status`：查看当前 Host/service/connection/artifact 状态。
-- `tirtc-devtools-cli host stop`：停止当前 `--session` 对应的 Host 进程。
-- `tirtc-devtools-cli host stop --all`：停止全部 session 对应 Host，并清理本机 orphan host 进程。
-
-### Service
-
-用途：控制服务端角色（等待远端连接的一侧）。
-
-- `tirtc-devtools-cli service start [serviceEntry] [license]`：启动服务并进入等待连接状态。
-- `tirtc-devtools-cli service stop`：停止服务。
-
-说明：`license` 必填；`serviceEntry` 可省略，省略时走 runtime/core/transport 默认值。
-
-`debug bootstrap qrcode` / `debug bootstrap qrcode-from-config` 默认复用当前唯一活跃 session；多 session 时请显式传 `--session`。
-
-### Connection
-
-用途：控制客户端侧连接动作（主动连接/断开）。
-
-- `tirtc-devtools-cli connection show`：查看当前连接状态。
-- `tirtc-devtools-cli connection connect [serviceEntry] <peerId> [token]`：主动发起连接（不传 token 时自动签发）。
-- `tirtc-devtools-cli connection disconnect`：主动断开连接。
-
-说明：`connect` 每次都会新建一个 session；省略 `serviceEntry` 时，Host 回退到 runtime 配置默认值。
-
-自动签发补充：
+- `host session start`：创建会话。
+- `host session list`：查看会话。
+- `host session stop <sessionId>`：停止会话。
+- `service start`：默认创建 `service` 会话；可通过 `--session` 绑定已有空闲会话。
+- `connection connect`：总是创建新的 `client` 会话，不允许复用 `--session`。
 
-- 若命令行和 `[connection].token` 都为空，且 TOML 提供 `[connection.auto_token]` 的 `access_id/secret_key`，CLI 会传 `tokenMode=auto`，由 App Server 在连接前实时签发新 token。
-- `local_id` 可选；缺省时 App Server 侧回退为本次连接使用的 `peer_id`。
-- 若手动 token 与自动签发配置都缺失，命令会失败。
+## 六、server-only 正式入口
 
-### Token
+### 1. 配置真相
 
-用途：直接签发 token，并把调试所需的核心信息一次性输出到控制台，同时在本地生成二维码 PNG。
+server-only 正式路径只认 `[server] + [logging]`：
 
-- `tirtc-devtools-cli token issue <peerId>`：签发 token；默认从环境变量读取凭据，并使用 `peerId` 作为默认 `localId`。
-
-可选参数：
-
-- `--access-id <accessId>`：显式传 access id；不传时读取 `TIRTC_CONN_ACCESS_ID`。
-- `--secret-key <secretKey>`：显式传 secret key；不传时读取 `TIRTC_CONN_SECRET_KEY`。
-- `--local-id <localId>`：显式传 local id；不传时默认使用 `peerId`。
-- `--openapi-entry <url>`：覆盖默认 openapi entry。
-- `--service-entry <entry>`：附加到组合 payload，便于扫码后直接连到目标服务。
-- `--user-ttl-seconds <seconds>`：覆盖 user token ttl。
-- `--channel-ttl-seconds <seconds>`：覆盖 channel token ttl。
-- `--qr-error-correction-level <level>`：设置二维码纠错级别，可选 `L/M/Q/H`，默认 `M`。
-- `--ascii-max-columns <columns>`：显式限制 ASCII 二维码最大宽度；不传时优先读取当前终端宽度或 `COLUMNS`。
-
-默认输出四部分：
+```toml
+[server]
+service_entry = ""
+license = "runtime-license"
+mp4_path = "/Users/allenfeng/Development/Repositories/tirtc-nexus/tirtc-matrix/.refers/simple.mp4"
+video_stream_id = 11
+audio_stream_id = 10
 
-- `Issued Token Summary`：面向人类阅读的摘要，快速确认 local/peer/entry/ttl。
-- `Token`：单独罗列 token 字符串，便于复制粘贴。
-- `Payload JSON`：组合 JSON，对方或 Agent 可直接复制使用。
-- `QR Code ASCII`：非 `--json` 模式下尽量输出 ASCII 二维码；如果终端宽度不足，会提示改看 PNG。
-- `QR Code PNG`：基于组合 JSON 生成的本地 PNG 文件绝对路径。适合人工打开图片后扫码。
+[logging]
+root_dir = "./.tmp/tirtc-devtools-cli/logging"
+console_mirror = true
+level = "info"
+```
 
 说明：
 
-- 组合 JSON 的 `type` 固定为 `tirtc-connect-token`。
-- PNG 二维码承载的是组合 JSON，不再暴露 `secret_key`。
-- CLI 不会在最终 JSON、控制台输出或二维码内容里打印 `access_id` 和 `secret_key`。
-- `--json` 模式下只输出 `payload`、`payloadJson`、`token` 和 `qrCodePngPath`，不输出 ASCII 二维码。
-- 如果觉得 ASCII 二维码太密，可把纠错级别从默认 `M` 调低到 `L`；如果希望更耐遮挡，可调高到 `Q` 或 `H`，但二维码会更密。
+- `license`、`mp4_path`、`video_stream_id`、`audio_stream_id` 必填。
+- `service_entry` 可留空，回退到底层默认值。
+- 旧 `[service]`、`[stream.request_policy]`、`[streams.send]` 不再属于正式合同。
 
-推荐默认做法：
+### 2. 启动命令
 
 ```bash
-export TIRTC_CONN_ACCESS_ID="<ACCESS_ID>"
-export TIRTC_CONN_SECRET_KEY="<SECRET_KEY>"
-tirtc-devtools-cli --json token issue "<PEER_ID>"
+node devtools/cli/bin/tirtc-devtools-cli.js --config ./server.toml --json service start
 ```
 
-只有在你明确需要覆盖环境变量时，才额外传 `--access-id` 和 `--secret-key`。
-只有在你明确需要不同的本地用户标识时，才额外传 `--local-id`。
-
-### Stream
-
-用途：管理音视频流的发送/接收与远端请求策略。
-
-- `tirtc-devtools-cli stream list`：列出当前流状态。
-- `tirtc-devtools-cli media assets prepare --source <mp4> --output-root <dir>`：把 MP4 prepare 为 local assets。
-- `tirtc-devtools-cli stream send start <streamId> <media> <assets_dir>`：启动发送流并绑定 prepared local assets。
-- `tirtc-devtools-cli stream send stop <streamId>`：停止发送流。
-- `tirtc-devtools-cli stream receive start <streamId> <media>`：启动接收流。
-- `tirtc-devtools-cli stream receive stop <streamId>`：停止接收流。
-- `tirtc-devtools-cli stream request-policy get`：查看远端请求策略。
-- `tirtc-devtools-cli stream request-policy set <manual|auto-if-bound>`：设置远端请求策略。
-
-`request-policy` 行为：
-
-- `manual`：只上报远端请求事件，由上层显式决定是否发流。
-- `auto-if-bound`：如果本地已通过 `stream send start` 绑定 `(streamId, media, assets_dir)`，远端请求到达后自动启动发送。
-
-发送链路说明：
-
-- `stream/sendStart` 走 runtime-backed 真实发送路径。
-- 实际链路：`prepared local assets -> A/V PTS 对齐 -> 真实 uplink (runtime-backed transport)`。
-- 返回字段中的 `source.local_assets.assets_dir` 可用于验收与排障。
-
-### Output
-
-用途：把流内容挂到具体消费端（文件、预览页等）。
-
-- `tirtc-devtools-cli output attach <streamId> <consumer> <mediaView> <format> <delivery> [targetPath] [maxFiles]`：附加输出消费。
-- `tirtc-devtools-cli output detach <outputId>`：移除输出消费。
-
-`output attach` 当前最小稳定组合（CLI 前置校验）：
-
-- `consumer=web_preview`：`delivery` 必须是 `artifact_path`，`format` 推荐 `jpeg`/`pcm`（兼容旧值 `h264`/`g711a`）。
-- `consumer=file_sink`：`delivery` 必须是 `file`，`format` 必须是 `mp4`。
-
-`web_preview` 用法（音视频一起预览）：
-
-- 先在客户端会话中启动接收（必须两路都起）：
-  - `tirtc-devtools-cli stream receive start <videoStreamId> video`
-  - `tirtc-devtools-cli stream receive start <audioStreamId> audio`
-- 再挂接两路输出到同一个预览页：
-  - `tirtc-devtools-cli output attach <videoStreamId> web_preview encoded jpeg artifact_path [videoTargetPath]`
-  - `tirtc-devtools-cli output attach <audioStreamId> web_preview encoded pcm artifact_path [audioTargetPath]`
-- 两次 `output attach` 返回的 `result.preview.url` 应一致；用该 URL 在 Chrome 打开本地预览。
-- 页面打开后会自动触发 `GET /preview/start?token=...`；若浏览器拦截自动播放音频，请手动点击 `Start Stream` 解锁。
-- 可通过 `GET /preview/status?token=...` 查看 audio/video source 启动状态与 frame 计数。
-
-### Command
-
-用途：发送业务命令与实时观察命令事件。
-
-- `tirtc-devtools-cli command send <commandId> <kind> <payloadEncoding> <payload>`：发送命令。
-- `tirtc-devtools-cli command send-json <commandId> <kind> <payloadJson>`：以 JSON-first 形态发送命令。
-- `tirtc-devtools-cli command tail`：持续监听命令相关事件。
+`service start` 固定流程：
 
-`command send-json` 约束：
+1. 读取并校验 `[server]`。
+2. 对 `mp4_path` 执行 prepare。
+3. 调用 `service/start`。
+4. 自动调用两次 `stream/sendStart`：一次音频、一次视频。
+5. 返回 `autoApplied` 摘要：`preparedAssetsDir`、固定 `mediaSendPolicy=AUTO_ON_CONNECTED`、以及音视频 sendStart 结果。
 
-- `payloadJson` 必须是合法 JSON 文本。
-- CLI 固定按 `payloadEncoding=json` 下发给 Host。
+非 `--json` 模式下，CLI 会在 `stderr` 输出轻量进度提示：先显示 MP4 prepare，再显示 service start，避免长时间静默。
 
-### Debug Bootstrap 二维码
+### 3. 自动发送语义
 
-用途：生成客户端扫码连接所需的 bootstrap 二维码（只包含连接信息，不签发 token）。
+- App Server server 角色固定使用 `AUTO_ON_CONNECTED`。
+- CLI 不再暴露 request-policy 配置或命令。
+- 一旦远端请求对应 media，已绑定的发送流会自动转为 `active`。
 
-- `tirtc-devtools-cli debug bootstrap qrcode <accessId> <secretKey> <peerId> [serviceEntry]`：按命令参数生成二维码。
-- `tirtc-devtools-cli debug bootstrap qrcode-from-config`：按 `[debug.connect_bootstrap]` 配置生成二维码。
-
-二维码产物会落到 Host artifact 的 `debug/` 目录。
-
-### 观测与报告
-
-用途：做运行观测与验收证据导出。
-
-- `tirtc-devtools-cli events tail`：实时查看事件流。
-- `tirtc-devtools-cli logs export <outputPath>`：导出日志。
-- `tirtc-devtools-cli report show`：查看报告。
-- `tirtc-devtools-cli report export <outputPath>`：导出报告。
-
-## 六、服务端操作指引（对接安卓扫码）
-
-目标：只操作 CLI 服务端，启动后自动待推流；安卓端扫码拿到 bootstrap 信息，自行签发 token 后连接并观看音视频。
-
-### 1) 启动服务端
+## 七、connection connect
 
 ```bash
-node devtools/cli/bin/tirtc-devtools-cli.js service start "" "runtime-license"
-```
-
-记下返回里的 `sessionId`。
-
-### 2) 让服务端进入“自动按需发流”
-
-```bash
-编辑 `--config` 指向的 TOML：
-[stream.request_policy]
-mode = "auto-if-bound"
-
-[streams.send]
-assets_dir = "./.tmp/tirtc-devtools-cli/assets/<prepared-assets-id>"
-audio_stream_id = 10
-video_stream_id = 11
-
-再执行 service start（CLI 会自动应用 request_policy + send 绑定）。
+node devtools/cli/bin/tirtc-devtools-cli.js --config ./server.toml --json connection connect <serviceEntry> <peerId> [token]
 ```
 
 说明：
-- `auto-if-bound` 表示远端请求到达后，若本地已配置并应用发送绑定，服务端会自动开始对应发送。
-- `[streams.send]` 只配置一次 prepared assets 目录；音视频都从同一个 local assets 输入读取。
-- `audio_stream_id` 与 `video_stream_id` 必须与客户端请求的 stream id 一致。
-
-### 3) 生成给安卓扫码的 bootstrap 二维码
-
-```bash
-node devtools/cli/bin/tirtc-devtools-cli.js --session <SESSION_ID> debug bootstrap qrcode \
-  "<access-id>" "<secret-key>" "<peer-id>" "<service-entry>"
-```
-
-命令会在 Host artifact 的 `debug/` 目录下生成：
-- `*.qr.png`（扫码图）
-
-### 4) 安卓端扫码后的预期流程（安卓实现不在本仓库）
-
-- 安卓扫描二维码，解析出 bootstrap JSON。
-- 使用 `access_id + secret_key` 在客户端侧（或你们外部签发服务）签发连接 token。
-- 使用签发后的 token + `peer_id`（必要时加 `service_entry`）建立连接。
-- 连接成功后请求接收对应流（例如 `10/video`、`11/audio`），即可看到服务端已绑定的媒体内容。
-
-### 4.1) 本地直接签发 token（公开调试入口）
-
-```bash
-node devtools/cli/bin/tirtc-devtools-cli.js token issue \
-  "<access-id>" "<secret-key>" "<local-id>" "<peer-id>" \
-  --service-entry "<service-entry>"
-```
-
-输出包含：
-
-- 一份可直接复制的组合 JSON
-- 单独的 token 字符串
-- 同一份组合 JSON 对应的本地二维码 PNG 路径
-
-二维码内容示例：
-
-```json
-{
-  "version": 1,
-  "type": "tirtc-connect-token",
-  "peer_id": "<peer-id>",
-  "local_id": "<local-id>",
-  "service_entry": "<service-entry>",
-  "token": "<issued-token>",
-  "openapi_entry": "http://api-test-tirtc.tange365.com",
-  "user_ttl_seconds": 86400,
-  "channel_ttl_seconds": 300,
-  "generated_at": "<iso8601>"
-}
-```
-
-### 5) Web Preview 手动控制（建议验收路径）
-
-- 在客户端会话 attach 两路 `web_preview` 后，打开返回的 `preview.url`。
-- 页面默认只建立事件连接，不会自动起流。
-- 点击 `Start Stream`：触发服务端开始推送音视频。
-- 点击 `Stop Stream`：触发服务端停止推送。
-- 关闭页面：会自动触发一次 stop 请求（作为兜底）。
-
-## 六点四、二维码内容协议（安卓对齐）
-
-`debug bootstrap qrcode*` 生成的 payload 是一个 JSON 字符串，字段如下：
-
-```json
-{
-  "version": 1,
-  "type": "tirtc-connect-bootstrap",
-  "access_id": "<access-id>",
-  "secret_key": "<secret-key>",
-  "peer_id": "<peer-id>",
-  "service_entry": "<service-entry>"
-}
-```
-
-字段约束：
-- `version`: 固定 `1`。
-- `type`: 固定 `tirtc-connect-bootstrap`。
-- `access_id`: 客户端签发 token 所需。
-- `secret_key`: 客户端签发 token 所需。
-- `peer_id`: 目标服务端 peer 标识。
-- `service_entry`: 可选；为空或缺失时，客户端按自身默认 entry 策略处理。
-
-注意：
-- 该二维码不包含 token，也不在 App Server 侧签发 token。
-- token 签发职责在客户端或外部系统。
-
-
-## 六点五、日志配置与实时观测
 
-`[logging]` 段默认已在模板里生成：
+- 若未显式传 `token`，CLI 会尝试使用 `[connection.auto_token]` 触发 App Server 自动签发。
+- 若命令行、省略 token、且配置也缺自动签发凭据，则命令失败。
 
-- `root_dir`：会话日志根目录（默认 `./.tmp/tirtc-devtools-cli/logging`）
-- `console_mirror`：是否把 Host 关键日志镜像到当前命令终端
-- `level`：日志级别预留位（当前 Host 以统一关键路径日志为主）
+## 八、stream / output / command
 
-日志目录结构：
-
-- `<root_dir>/<session_id>/host.process.log`（Host 进程 stdio）
-- `<root_dir>/<session_id>/runtime.host.log`（Host 侧结构化运行日志）
-- `<root_dir>/<session_id>/uplink/*.transport-uplink.log`（发送 worker 日志）
-
-实时观察：
-
-- `node devtools/cli/bin/tirtc-devtools-cli.js --session <SESSION_ID> events tail`
-- 输出中包含 `family=logs` / `kind=host.line` 的实时日志事件
-
-## 六点六、配置格式说明
-
-- 推荐使用 TOML（支持注释，便于人工维护）
-- `init` 默认生成 TOML 模板：`.tmp/tirtc-devtools-cli/config.toml`
+### Stream
 
-## 七、本地 E2E 配置（必需）
+- `stream list`
+- `stream send start <streamId> <media> <assets_dir>`
+- `stream send stop <streamId>`
+- `stream message send <streamId> <payload>`
+- `stream receive start <streamId> <media>`
+- `stream receive stop <streamId>`
 
-创建本地测试配置（已被 git ignore）：
+`stream message send` 是字符串型 payload contract；当前 Host/runtime-backed adapter 至少保证连接存在时可接受请求并落事件。
 
-```bash
-mkdir -p devtools/cli/tests/.local
-cp devtools/cli/tests/runtime-backed.e2e.config.example.json devtools/cli/tests/.local/runtime-backed.e2e.local.json
-```
-
-推荐输入（客户端自行签发 token）：
-
-```json
-{
-  "assetsDir": "./.tmp/tirtc-devtools-cli/assets/<prepared-assets-id>",
-  "license": "<license>",
-  "peerId": "<peer-id>",
-  "useFakeToken": false,
-  "accessId": "<access-id>",
-  "secretKey": "<secret-key>",
-  "e2eToken": "<externally-issued-token>"
-}
-```
+### Output
 
-说明：
-- `useFakeToken=true` 时会走本地 fake token（不依赖 token 签发服务）。
-- `useFakeToken=false` 时必须提供外部签发 token（优先 `e2eToken`，否则读取环境变量 `TIRTC_E2E_TOKEN`）。
-- `debug bootstrap qrcode*` 仅生成客户端连接信息二维码（`access_id` / `secret_key` / `peer_id` / 可选 `service_entry`），不负责签发 token。
+- `output attach <streamId> <consumer> <mediaView> <format> <delivery> [targetPath] [maxFiles]`
+- `output detach <outputId>`
 
-## 八、FFmpeg 说明
+CLI 仍会在本地收紧最小组合矩阵：
 
-- FFmpeg 不入库（不纳入 git 版本管理）。
-- 打包时自动准备并放入：
-  - `devtools/cli/bin/tools/<platform>/`
-  - `devtools/cli/bin/dist/tools/<platform>/`
+- `web_preview` 只允许 `delivery=artifact_path`，`format` 允许 `jpeg|pcm|h264|g711a`
+- `file_sink` 只允许 `delivery=file`，`format=mp4`
 
-## 九、新手入口
+### Command
 
-- `node devtools/cli/bin/tirtc-devtools-cli.js guide quickstart`
+- `command send <commandId> <kind> <payloadEncoding> <payload>`
+- `command tail`
 
-会直接打印“服务端启动 -> 绑定自动发流 -> 生成 bootstrap 二维码 -> 客户端扫码签发 token 并连接 -> 打开 Web Preview 后手动 Start/Stop -> 观测报告”的最小闭环步骤。
+`command send` 是统一的主动发送 surface。`send-json` 不再属于正式产品合同；如果要发 JSON，请把 JSON 文本作为 `payload` 传入。
 
-## 十、常用验收命令
+## 九、token / debug / report
 
-- App Server：`./app-server/script/test.sh acceptance`
-- CLI：`./devtools/cli/script/test.sh acceptance`
-- 联合一键：`./script/acceptance_app_server_devtools.sh`
+- `token issue <peerId>`：本地签发 token。
+- `debug bootstrap qrcode ...` / `debug bootstrap qrcode-from-config`：生成联调用二维码。
+- `events tail`：实时查看事件流。
+- `logs export <outputPath>`：导出日志。
+- `report show` / `report export <outputPath>`：查看或导出报告。
 
-## 十一、退出码
+## 十、本地 E2E 配置
 
-- `0`：成功
-- `1`：内部错误
-- `2`：协议版本不匹配
-- `3`：未初始化
-- `4`：请求/参数错误
-- `7`：连接失败
-- `8`：流不存在
+- CLI server/client E2E 本地配置文件：`devtools/cli/tests/.local/runtime-backed.e2e.local.json`
+- 推荐字段：`mp4Path`、`serviceEntry`、`license`、`peerId`、`accessId`、`secretKey`、可选 `e2eToken`
+- CLI server-only E2E 不再要求先手工 `media assets prepare` 再回填 `assetsDir`

package/dist/devtools/cli/src/config.d.ts

@@ -1,7 +1,10 @@
 export type CliConfig = {
-    service?: {
+    server?: {
         service_entry?: string;
         license?: string;
+        mp4_path?: string;
+        video_stream_id?: number;
+        audio_stream_id?: number;
     };
     connection?: {
         service_entry?: string;
@@ -16,18 +19,6 @@ export type CliConfig = {
             channel_ttl_seconds?: number;
         };
     };
-    stream?: {
-        request_policy?: {
-            mode?: 'manual' | 'auto-if-bound';
-        };
-    };
-    streams?: {
-        send?: {
-            assets_dir?: string;
-            audio_stream_id?: number;
-            video_stream_id?: number;
-        };
-    };
     logging?: {
         root_dir?: string;
         console_mirror?: boolean;