通用业务技能模板 CLI 标准

将 {baseDir} 替换为技能根目录（含 SKILL.md、scripts/ 的目录）。

解释器（必读）

必须使用宿主共享 Python runtime（{JIANGCHANG_DATA_ROOT}/python-runtime/.venv，已在 PATH / VIRTUAL_ENV）。一条命令直接跑，不要先探系统 Python。

python {baseDir}/scripts/main.py <command> …

场景	写法
推荐（Agent）	`python {baseDir}/scripts/main.py <command> …`
手工排查（环境未注入时）	`{JIANGCHANG_DATA_ROOT}/python-runtime/.venv/Scripts/python.exe`（Windows）或 `…/.venv/bin/python3`（Unix）

禁止对技能脚本使用 uv run python …（会创建临时环境，加载不到 jiangchang-platform-kit / jiangchang_skill_core）。
禁止 Agent 自行 pip install / uv pip install 往临时环境塞依赖。

Agent 分流（业务技能复制后必改）

用本表列出本技能哪些子命令可走短 CLI，哪些必须走 Skill Action。默认：短查询/只读写本地可用短 CLI；长耗时 / RPA / 需进度取消进黑名单。有 async/RPA 的技能：黑名单不得为空，且黑名单命令须映射到 actions.json 中的 async Action。

类型	本技能命令（自填）	Agent
短 CLI 白名单	（例）`health` / `version` / `render-html` / `<your-read-or-prep>`	可用 bash/exec + 共享 `python`
Action 强制黑名单	（例）`<your-long-or-rpa-command>`	禁止 bash + `process poll`；必须 `run_skill_action`

细节与 Action 清单见 ACTIONS.md。快照「重新生成」须有 Action id render-html；壳子页与页面调用 jiangchang.call 见 ACTIONS.md「HTML 页面报告」。

最小命令

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。
policy（可选）：仅当 actions.json 顶层启用 Data Policy 时需要；向 stdout 输出 Snapshot JSON（见 references/POLICY.md）。模板默认不实现；多数技能保持 L0 即可。
run / RPA / 长任务：CLI 仍是同一内核；Agent 禁止用 bash 干等长任务结束。须走宿主 Skill Action（run_skill_action），且该 Action 一般为 executionProfile: "async" → 任务中心。长时间无 stdout 不代表卡死；进度看任务中心 / Run Journal。
排查顺序（由快到慢）：
1. 任务中心 / Run Journal {JIANGCHANG_DATA_ROOT}/.jiangchang/runs/{job_id}.jsonl
2. 统一日志文件 {JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/logs/jiangchang.log（含 trace_id、task_failed 等）
3. 业务表（宿主数据管理；有才建）
4. 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），且 finish() 含 video 字段。

config-path（配置路径）

{
  "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 解释器路径（应落在共享 python-runtime）
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 与仓库模板路径

通用业务命令骨架

python {baseDir}/scripts/main.py run
python {baseDir}/scripts/main.py run -t <target> -i <input_id>

命令	用途	Agent 注意
`run`	执行一次任务（常为长任务 / RPA）	走 `run_skill_action`，不要 bash poll

5.1 KiB Raw Blame History Unescape Escape