通用业务技能模板 CLI 标准

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

解释器（必读）

必须使用宿主共享 Python runtime，不要用系统 Python / 临时 venv。

优先级	写法
推荐（Agent）	`"$JIANGCHANG_PYTHON_EXE" {baseDir}/scripts/main.py <command> …`
Windows cmd	`"%JIANGCHANG_PYTHON_EXE%" {baseDir}/scripts/main.py <command> …`
等价（PATH 已指向共享 venv）	`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 往临时环境塞依赖。

下文示例里的 python 均指上述共享解释器（优先写成 $JIANGCHANG_PYTHON_EXE）。

最小命令

"$JIANGCHANG_PYTHON_EXE" {baseDir}/scripts/main.py health
"$JIANGCHANG_PYTHON_EXE" {baseDir}/scripts/main.py config-path
"$JIANGCHANG_PYTHON_EXE" {baseDir}/scripts/main.py version
"$JIANGCHANG_PYTHON_EXE" {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 / RPA / 长任务：CLI 仍是同一内核；Agent 禁止用 bash 干等长任务结束。须走宿主 Skill Action（run_skill_action），且该 Action 一般为 executionProfile: "async" → 任务中心。长时间无 stdout 不代表卡死；进度看任务中心 / Run Journal。
排查顺序（由快到慢）：
1. "$JIANGCHANG_PYTHON_EXE" {baseDir}/scripts/main.py logs
2. "$JIANGCHANG_PYTHON_EXE" {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（配置路径）

{
  "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 与仓库模板路径

通用业务命令骨架

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

命令	用途	Agent 注意
`run`	执行一次任务（常为长任务 / RPA）	走 `run_skill_action`，不要 bash poll
`logs`	列出最近 N 条任务日志	可用短 CLI
`log-get`	按 log_id 查看单条任务日志（JSON）	可用短 CLI

查询/导出类（可选）

复制后按需增加，例如：contacts、contact-get、export 或业务等价命令。短查询用共享 Python CLI；需挂数据管理/定时/Agent 结构化入口时再写进 assets/actions.json。

若你的技能依赖兄弟技能

使用 service.sibling_bridge.call_sibling_json(skill_slug, args)，不要硬编码兄弟技能名到 sibling_bridge.py 自身；并在 SKILL.md 声明 dependencies.required。兄弟进程继承当前解释器（须已是共享 runtime）。

模板约定

最小模板至少保留 health / config-path / version
通用业务技能建议使用 run / logs / log-get
不要再用旧模板的 publish / --account-id / --article-id 命名
Skill Action 与任务中心契约见 ACTIONS.md

5.5 KiB Raw Blame History Unescape Escape