docs: clarify shared Python, CLI vs Action, and Task Center rules

references/ACTIONS.md

@@ -1,10 +1,22 @@
 # Skill Action Manifest（匠厂宿主）
 
-本文件说明 `assets/actions.json` 与 `scripts/main.py` CLI 的对应关系，供 Agent 编排与宿主 **Skill Action Runtime** 使用。
+本文件说明 `assets/actions.json` 与 `scripts/main.py` CLI 的对应关系，供 **Agent 编排**与宿主 **Skill Action Runtime** 使用。这是 Agent 侧关于 Action / 任务中心的**主契约**；实现细节与开发规范见 [`../development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。
 
-**权威运行时契约（sync/async、任务中心、单内核编排）见 [`../development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。**
+**边界：** 用户市场说明见根目录 [`README.md`](../README.md)；CLI 参数见 [`CLI.md`](CLI.md)。
 
-**边界：** 用户市场说明见根目录 [`README.md`](../README.md)；CLI 参数与错误码细节见 [`CLI.md`](CLI.md)。
+## Agent 何时用 Action（与 CLI 的分工）
+
+| 场景 | 做法 |
+|------|------|
+| 短查询 / 只读 / 秒级 | bash + 共享 Python CLI（见 [`CLI.md`](CLI.md)）；**不必**强行走 Action |
+| 数据管理按钮 / 定时任务 / 技能详情按钮 | **必须**在 `actions.json` 声明对应 Action |
+| 长耗时 / RPA / 需要进度与取消 | **必须** `run_skill_action`；对应 Action 一般为 `executionProfile: "async"` |
+| 已声明的 `sync` Action | `run_skill_action` 当场返回结果，**不进**任务中心 |
+| 已声明的 `async` Action | `run_skill_action` 立即返回 `jobId`，**进入**任务中心 |
+
+**进不进任务中心只取决于该 Action 的 `executionProfile`，与从数据管理、定时任务还是 Agent 触发无关。**
+
+禁止对长任务 `exec`/`bash` + `process poll` 干等 CLI。禁止 `uv run python` 跑技能脚本。
 
 ## 模板严格规范 vs 宿主向后兼容
 
@@ -117,10 +129,10 @@ Action 是**可选能力**：
 
 ## 执行模型
 
-宿主将 action 转为 argv，再执行：
+宿主将 action 转为 argv，再用**共享 Python** 执行（与 Agent CLI 同一解释器契约）：
 
 ```text
-python {skill_root}/scripts/main.py <command> <args...>
+{JIANGCHANG_PYTHON_EXE} {skill_root}/scripts/main.py <command> <args...>
 ```
 
 - `entrypoint.type` 当前只支持 `cli`
@@ -132,7 +144,7 @@ python {skill_root}/scripts/main.py <command> <args...>
 
 ### `executionProfile`（仅 sync / async）
 
-模板与新技能**只允许**这两种值；禁止发明 `auto` / `background` / `deferred` 等第三种模式。
+模板与新技能**只允许**这两种值；每个 Action **必须**显式写出；禁止发明 `auto` / `background` / `deferred`；**禁止**依赖宿主「省略字段时的兼容默认」。
 
 | 值 | 宿主行为 | 任务中心 |
 |----|----------|----------|
@@ -141,9 +153,9 @@ python {skill_root}/scripts/main.py <command> <args...>
 
 合法组合（全部允许）：`sync|async` × `toolbar|cron|agent|skill-detail`。
 
-经验建议（**不是** placement 硬限制）：耗时不可预测、需要暂停/停止/进度展示的任务，建议用 `async`。
+经验建议（**不是** placement 硬限制）：耗时不可预测、需要暂停/停止/进度展示的任务，用 `async`。
 
-直接执行 CLI 时，终端自然等待进程结束；宿主通过 Action 调用同一 CLI 时，再按 `executionProfile` 决定同步等待还是建 Job。技能**不得**自行实现第二套任务中心或后台队列。
+直接执行短 CLI 时，终端自然等待进程结束。宿主通过 Action 调用同一 CLI 时，再按 `executionProfile` 决定同步等待还是建 Job。技能**不得**自行实现第二套任务中心或后台队列。
 
 ### CLI 输出契约
 

references/CLI.md

@@ -1,14 +1,30 @@
 # 通用业务技能模板 CLI 标准
 
-将 `{baseDir}` 替换为技能根目录（含 `SKILL.md`、`scripts/` 的目录）。所有命令通过 `python {baseDir}/scripts/main.py` 调用。
+将 `{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`）。
 
 ## 最小命令
 
 ```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
+"$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
 ```
 
 ## 标准行为
@@ -18,13 +34,13 @@ python {baseDir}/scripts/main.py init-db
 - **`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 看进度。
+- **`run` / RPA / 长任务**：CLI 仍是同一内核；**Agent 禁止**用 bash 干等长任务结束。须走宿主 Skill Action（`run_skill_action`），且该 Action 一般为 `executionProfile: "async"` → **任务中心**。长时间无 stdout **不代表卡死**；进度看任务中心 / Run Journal。
 - **排查顺序**（由快到慢）：
-  1. `python {baseDir}/scripts/main.py logs`
-  2. `python {baseDir}/scripts/main.py log-get <log_id>`
+  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`）；未开启录屏时可能只有截图或日志
+  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 字段。
 
@@ -42,7 +58,7 @@ python {baseDir}/scripts/main.py init-db
 
 `health` 委托 `jiangchang_skill_core.collect_runtime_diagnostics`，典型字段：
 
-- `python_executable` — 当前 Python 解释器路径
+- `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`
@@ -52,45 +68,30 @@ python {baseDir}/scripts/main.py init-db
 ## 通用业务命令骨架
 
 ```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>
+"$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>
 ```
 
-| 命令 | 用途 |
-|------|------|
-| `run` | 执行一次任务 |
-| `logs` | 列出最近 N 条任务日志 |
-| `log-get` | 按 log_id 查看单条任务日志（JSON） |
+| 命令 | 用途 | Agent 注意 |
+|------|------|------------|
+| `run` | 执行一次任务（常为长任务 / RPA） | **走 `run_skill_action`**，不要 bash poll |
+| `logs` | 列出最近 N 条任务日志 | 可用短 CLI |
+| `log-get` | 按 log_id 查看单条任务日志（JSON） | 可用短 CLI |
 
 ## 查询/导出类（可选）
 
-复制后按需增加，例如：`contacts`、`contact-get`、`export` 或业务等价命令。
+复制后按需增加，例如：`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`。
-
-## 手工排查命令（推荐）
-
-**建议使用宿主共享 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`。
+使用 `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`](ACTIONS.md)

references/README.md

@@ -6,16 +6,16 @@
 
 - 本文**不得**包含 YAML frontmatter，**不得**包含 `description` 字段。
 - 技能市场详情与普通用户说明**必须**放在根目录 [`README.md`](../README.md)。
-- 本目录只保留运行时引用资料（如 `CLI.md`、`SCHEMA.md`）；开发规范放在 [`../development/`](../development/)。
+- **Agent 主读本目录**（`CLI.md` / `ACTIONS.md` / `SCHEMA.md`）与根 [`SKILL.md`](../SKILL.md)。
+- [`../development/`](../development/) 是开发者 / 编码助手深度规范，**不是**对话 Agent 的默认读盘路径。
 
 | 文档 | 用途 |
 |------|------|
 | 根目录 [`README.md`](../README.md) | 用户市场详情页说明 |
-| [`SKILL.md`](../SKILL.md) | LLM / OpenClaw 平台技能入口 |
-| [`CLI.md`](CLI.md) | 命令行入口、参数与调用契约 |
+| [`SKILL.md`](../SKILL.md) | LLM / OpenClaw 平台技能入口与触发摘要 |
+| [`CLI.md`](CLI.md) | 共享 Python、命令行入口、参数与短操作契约 |
+| [`ACTIONS.md`](ACTIONS.md) | Skill Action、sync/async、任务中心、多入口（可选能力） |
 | [`SCHEMA.md`](SCHEMA.md) | 本地 SQLite 与数据管理展示契约 |
-| [`ACTIONS.md`](ACTIONS.md) | Skill Action manifest（**可选**能力）与宿主入口契约 |
-| [`../development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md) | sync/async、任务中心、Agent 禁令、编排与队列 pick（长任务必读） |
-| [`../development/`](../development/) | 开发、测试、技术规范（给开发者 / AI 编程代理） |
+| [`../development/`](../development/) | 开发、测试、RPA 深度规范（给人 / 编码助手） |
 
-按需阅读：编排任务时优先 `CLI.md`；解析结构化字段时读 `SCHEMA.md`；配置宿主按钮/定时任务/Agent 入口时读 `ACTIONS.md` + `SKILL_ACTION_RUNTIME.md`；运行时环境细节见 `../development/RUNTIME.md`。
+按需阅读：短操作优先 `CLI.md`；Action / 任务中心读 `ACTIONS.md`；结构化字段读 `SCHEMA.md`。