# 通用业务技能模板 CLI 标准

将 `{baseDir}` 替换为技能根目录（含 `SKILL.md`、`scripts/` 的目录）。所有命令通过 `python {baseDir}/scripts/main.py` 调用。

## 最小命令

```bash
python {baseDir}/scripts/main.py health
python {baseDir}/scripts/main.py config-path
python {baseDir}/scripts/main.py version
python {baseDir}/scripts/main.py init-db
```

## 标准行为

- **任意 CLI 启动前**执行 `bootstrap_skill_config()`（`main.py` 与 `cli.app.main()` 均触发）。
- **`health`**：只读 runtime 诊断，**不下载、不修复 media-assets，不执行业务动作**；不输出敏感值。
- **`config-path`**：输出 JSON，包含 `skill`、`env_path`、`example_path`。
- **`version`**：输出 JSON（`version`、`skill`）。
- **`init-db`**：幂等创建/迁移本地 SQLite（含 `_jiangchang_*` 展示元数据）。成功输出一行 JSON（`ok` / `skill` / `db_path`），退出码 `0`。宿主可在技能安装或更新成功后静默调用；不要并入 `health`。
- **`run`**：长时间无 stdout **不代表卡死**；RPA / 外部调用期间应通过 Activity 或 Run Journal 看进度。
- **排查顺序**（由快到慢）：
  1. `python {baseDir}/scripts/main.py logs`
  2. `python {baseDir}/scripts/main.py log-get <log_id>`
  3. 统一日志文件 `{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/logs/jiangchang.log`（含 `trace_id`、`task_failed` 等）
  4. Run Journal `{JIANGCHANG_DATA_ROOT}/.jiangchang/runs/{job_id}.jsonl`
  5. RPA artifacts / `video_log` / 失败截图（见 `development/RPA.md`）；未开启录屏时可能只有截图或日志
- **录屏默认关闭**：模板 `.env.example` 为 `OPENCLAW_RECORD_VIDEO=0`；若未开启录屏，任务**可能不会**打印录屏路径。
- 需要录屏时在用户 `.env` 或进程环境变量中设置 **`OPENCLAW_RECORD_VIDEO=1`**；开启后任务完成时 CLI 应打印录屏路径、录屏日志、视频/音频诊断（见 `task_run_support._print_video_summary`），且 `result_summary` 含 video 字段。

## config-path（配置路径）

```json
{
  "skill": "your-skill-slug",
  "env_path": "{DATA_ROOT}/{USER_ID}/your-skill-slug/.env",
  "example_path": "{skill_root}/.env.example"
}
```

## health 标准输出（runtime diagnostics）

`health` 委托 `jiangchang_skill_core.collect_runtime_diagnostics`，典型字段：

- `python_executable` — 当前 Python 解释器路径
- `platform_kit_version` / `platform_kit_min_version` / `platform_kit_version_ok`
- `jiangchang_skill_core_file` — 公共库加载来源（若来自技能目录副本会报 warning）
- `media_assets_root`、`ffmpeg_path`、`ffmpeg_available`、`background_music_mp3_count`
- `runtime_issue[warning|error]` — 非致命/致命问题列表
- `env_path` / `env_exists` / `example_path` — 用户 `.env` 与仓库模板路径

## 通用业务命令骨架

```bash
python {baseDir}/scripts/main.py run
python {baseDir}/scripts/main.py run -t <target> -i <input_id>
python {baseDir}/scripts/main.py logs
python {baseDir}/scripts/main.py logs --task-type demo --status failed
python {baseDir}/scripts/main.py log-get <log_id>
```

| 命令 | 用途 |
|------|------|
| `run` | 执行一次任务 |
| `logs` | 列出最近 N 条任务日志 |
| `log-get` | 按 log_id 查看单条任务日志（JSON） |

## 查询/导出类（可选）

复制后按需增加，例如：`contacts`、`contact-get`、`export` 或业务等价命令。

## 若你的技能依赖兄弟技能

使用 `service.sibling_bridge.call_sibling_json(skill_slug, args)`，不要硬编码兄弟技能名到 `sibling_bridge.py` 自身；并在 `SKILL.md` 声明 `dependencies.required`。

## 手工排查命令（推荐）

**建议使用宿主共享 python-runtime**，避免技能目录内临时 venv 加载不到公共库：

```text
Windows:
  {JIANGCHANG_DATA_ROOT}\python-runtime\.venv\Scripts\python.exe {baseDir}\scripts\main.py health

通用:
  <shared-python> {baseDir}/scripts/main.py health
```

`<shared-python>` 通常位于 `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。

**不建议**在生产/测试机使用技能目录内 `uv run python`，以免加载不到共享 runtime 中的 `jiangchang-platform-kit` / `playwright`。

## 模板约定

- 最小模板至少保留 `health` / `config-path` / `version`
- 通用业务技能建议使用 `run` / `logs` / `log-get`
- 不要再用旧模板的 `publish` / `--account-id` / `--article-id` 命名