通用业务技能模板 CLI 标准

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

最小命令

python {baseDir}/scripts/main.py health
python {baseDir}/scripts/main.py config-path
python {baseDir}/scripts/main.py version

标准行为

任意 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）。
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）
任务完成后若有 video artifact，CLI 应打印录屏路径、录屏日志、视频/音频诊断（见 task_run_support._print_video_summary）。

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 解释器路径
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>
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 加载不到公共库：

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 命名

3.8 KiB Raw Blame History Unescape Escape