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

2026-07-15 11:13:53 +08:00
parent 6b64aad138
commit 296798a0f3
12 changed files with 178 additions and 111 deletions
--- a/SKILL.md
+++ b/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: 技能开发模板（通用业务版）
 description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。"
-version: 1.0.42
+version: 1.0.43
 author: 深圳匠厂科技有限公司
 metadata:
  openclaw:
@@ -25,20 +25,51 @@ allowed-tools:
 ### 架构铁律（先读）

 - **单业务内核、多入口**：数据管理 / 定时任务 / Agent / 技能详情 / 直接 CLI 必须复用同一 domain service；禁止按入口复制业务逻辑，禁止按 `source` 分叉业务行为。
- **`placements`**：只决定 Action 出现在哪里。
+- **`placements`**：只决定 Action **出现在哪里**（toolbar / cron / agent / skill-detail）。
 - **`bind.tables`**：只决定数据管理出现在哪些表；含 `toolbar` 时**必须**显式非空绑定。
- **`executionProfile`**：只决定 sync 等待还是 async Job；**必须**显式声明 `sync` 或 `async`；与 placements **正交**（任意合法组合均可）。
- **`async`**：宿主建 Job，立即返回 `jobId`，进度见**任务中心** / Skill Run Card。
+- **`executionProfile`**：只决定执行方式——`sync` 当场返回结果，`async` 进**任务中心**。与 placements / 入口**无关**；每个 Action **必须**显式写 `sync` 或 `async`。
 - **同步数据**写技能本地库、不生成导出文件；**导出当前表**由宿主数据管理负责；特殊业务报告才另做 `export-*`。

-### 编排要点
+### 如何触发（决策树）

- **长耗时 / RPA / 浏览器任务**：必须通过宿主 **Skill Action**（`run_skill_action`）调用 `assets/actions.json` 中的 action；建议 `executionProfile: "async"`。
- **禁止**对长任务使用 `exec python …/scripts/main.py run` 或 `process poll` 干等 CLI 返回。
- 只读查询（`health` / `stats` 等）可用 `"sync"`，立即返回结果。
- 批量处理用参数化 `pickCount` / `--pick N` 顺序消费队列，**不要并发**同一 Profile。
- 详细契约：`development/SKILL_ACTION_RUNTIME.md`、`references/ACTIONS.md`、`references/SCHEMA.md`。
- 模板源仓库本身仅示范 `health` / `version` / `config-path` / `init-db`（运维/诊断 CLI）；定制后按业务增加 Action，**一个能力一个 Action + 多 placements**。
+| 你要做什么 | Agent 怎么做 | 进任务中心？ |
+|------------|--------------|--------------|
+| 短查询 / 只读 / 秒级（`health` / `version` / `stats` / `list` / `get` / `logs` 等） | OpenClaw bash/exec + **共享 Python** 跑 CLI（见下方「共享 Python」） | 否（CLI 当场结束） |
+| 已在 `actions.json` 声明且 `executionProfile: "sync"` 的能力 | 可用 `run_skill_action`，或同等效果的短 CLI（同一内核） | 否 |
+| 长耗时 / RPA / 浏览器 / 需要进度或取消；或 `executionProfile: "async"` | **必须** `run_skill_action`（先 `list_skill_actions` / `get_skill_action`） | **是**（仅因为该 Action 是 async） |
+| 用户只问用法 / 能做什么 | 读根目录 `README.md`；技术细节读 `references/` | — |
+
+**硬规则：**
+
+1. **禁止**对长任务使用 `exec`/`bash` 跑 `…/scripts/main.py run`（或等价业务命令）再 `process poll` 干等。
+2. **禁止**用 `uv run python …` 跑技能脚本（会建临时环境，缺 `jiangchang_skill_core`）。
+3. **禁止** Agent 自行 `pip install`。
+4. Action **可选**：无数据管理 / 定时 / Agent 结构化调用需求时可不提供 `actions.json`；有长任务 / RPA 时**必须**提供至少一条 `executionProfile: "async"` 且 `placements` 含 `agent` 的 Action。
+5. **一个业务能力一个 Action**，用多个 `placements` 挂入口；底层仍是同一 `scripts/main.py` CLI。
+
+Agent 执行契约细节：`references/CLI.md`、`references/ACTIONS.md`、`references/SCHEMA.md`（不要把 `development/` 当 Agent 主读路径）。
+
+## 共享 Python（必读）
+
+宿主把共享 runtime 注入进程环境：`JIANGCHANG_PYTHON_EXE`、`VIRTUAL_ENV`，并把 venv 的 `bin`/`Scripts` 前置到 `PATH`。
+
+**推荐调用式（Agent）：**
+
+```bash
+"$JIANGCHANG_PYTHON_EXE" {baseDir}/scripts/main.py health
+"$JIANGCHANG_PYTHON_EXE" {baseDir}/scripts/main.py version
+"$JIANGCHANG_PYTHON_EXE" {baseDir}/scripts/main.py config-path
+"$JIANGCHANG_PYTHON_EXE" {baseDir}/scripts/main.py init-db
+```
+
+Windows cmd 可用 `"%JIANGCHANG_PYTHON_EXE%"`。若环境已注入共享 venv，也可写 `python {baseDir}/scripts/main.py …`（须确认不是系统/临时解释器）。
+
+- 公共库来自共享 venv 的 `jiangchang-platform-kit>=1.2.0`（包名路径 `jiangchang_skill_core`）；**不要 vendor** `scripts/jiangchang_skill_core/`。
+- 根目录 `requirements.txt` **只声明技能特有**依赖；不要写 `jiangchang-platform-kit` / `playwright`。
+- `metadata.openclaw.platform_kit_min_version` 是宿主兼容声明，**不是** pip 依赖。
+- `health` 用 `collect_runtime_diagnostics` 做只读诊断。
+
+配置：仓库 `.env.example` 为模板；用户 `.env` 在 `{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/{slug}/.env`。优先级：进程环境变量 > 用户 `.env` > `.env.example`。

 ## 面向用户问答（LLM 规则）

@@ -55,8 +86,8 @@ allowed-tools:
 - 能不能帮我完成某个业务任务

 - **不要**把 `SKILL.md`、`references/`、`development/` 中的技术细节直接作为用户回答。
- **只有当**用户明确询问命令、参数、输出结构、开发、调试、集成或排错时，才读取 `references/` 或 `development/`。
- 若 `README.md` 与 `SKILL.md` / `references` 表述冲突：对用户展示与市场说明以 `README.md` 为准；对执行契约、CLI、schema、运行约束以 `SKILL.md` / `references` 为准。
+- **只有当**用户明确询问命令、参数、输出结构、开发、调试、集成或排错时，才读取 `references/`；`development/` 主要给开发者 / 编码助手，对话 Agent **不必**默认打开。
+- 若 `README.md` 与 `SKILL.md` / `references` 表述冲突：对用户展示与市场说明以 `README.md` 为准；对执行契约以 `SKILL.md` / `references` 为准。
 - 回答用户时**不要**暴露 Playwright、DOM、Python、RPA 等实现细节，除非用户明确询问技术实现。
 - 用户未问技术实现时，**不要**讨论 slug 命名规则；开发者问命名或 slug 时，读取 `development/NAMING.md`。

@@ -66,8 +97,8 @@ allowed-tools:
 |------|------|------|
 | 根目录 `README.md` | 普通用户 | 技能市场详情页说明（`metadata.readme_md` 主来源） |
 | `SKILL.md`（本文） | LLM / OpenClaw 平台 | 技能入口、触发与运行契约摘要 |
-| `references/` | Agent 编排/调用 | 渐进式加载：CLI 契约、字段 schema 等 |
-| `development/` | 开发者 / AI 编程代理 | 需求、开发教程、测试、技术规范 |
+| `references/` | Agent 编排 / 调用 | CLI、Action、schema 契约（Agent 主读） |
+| `development/` | 开发者 / AI 编程代理 | 需求、开发教程、测试、深度技术规范 |

 ## 目录约定

@@ -77,36 +108,15 @@ allowed-tools:
 - CLI 入口固定为 `scripts/main.py`
 - 业务逻辑按 `cli / db / service / util` 分层

-## 最小命令
-
-```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
-```
-
-配置：仓库 `.env.example` 为模板；用户 `.env` 在 `{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/{slug}/.env`，启动时自动 bootstrap。优先级：进程环境变量 > 用户 `.env` > `.env.example`。
-
-## 运行依赖
-
- Python 运行环境由匠厂宿主注入**共享 runtime**：`{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。
- 公共能力来自共享 runtime 安装的 `jiangchang-platform-kit>=1.2.0`（`jiangchang_skill_core` 包）；**不要 vendor** `scripts/jiangchang_skill_core/`，新技能不得在仓库内保留该目录副本。
- config、logging、runtime_env、rpa、media-assets、video_session、runtime_diagnostics 等均从共享 venv 的 `jiangchang_skill_core` import，而非技能目录副本。
- 根目录 `requirements.txt` **只声明技能特有** Python 三方依赖；`jiangchang-platform-kit`、`playwright` 等公共能力由宿主共享 runtime 提供，**不要**写入技能 requirements。
- `metadata.openclaw.platform_kit_min_version`（当前 `1.2.0`）是运行契约/兼容性声明，供宿主安装与启用时校验，**不是**技能 pip 依赖声明。
- Skill 代码**不要**自行 `pip install`；系统级依赖（如 VC++ Runtime）仅在 `health` / preflight 中提示用户安装。
- `health` 使用 `collect_runtime_diagnostics` 输出统一 runtime 诊断（只读，不下载/修复 media-assets）。
-
 ## 定制入口

 1. 从本模板创建新业务技能时，**不得保留模板 `.git`**；优先使用 [`tools/scaffold_skill.ps1`](tools/scaffold_skill.ps1)（见 [`tools/README.md`](tools/README.md)）。
 2. 业务技能仓库中**不得**存在 `.openclaw-skill-template`（仅 template 源仓库保留）。
 3. 复制目录为你的新 skill 仓库，全局替换 `your-skill-slug` 等占位词。
 4. 按 `development/DEVELOPMENT.md` 完成开发与文档定制。
-5. 用户市场说明写入根 `README.md`；Agent 调用契约见 `references/CLI.md`、`references/SCHEMA.md`、`references/ACTIONS.md`；长任务 / 任务中心见 `development/SKILL_ACTION_RUNTIME.md`。
+5. 用户市场说明写入根 `README.md`；Agent 调用契约见 `references/CLI.md`、`references/SCHEMA.md`、`references/ACTIONS.md`。
 6. 同步修改 `scripts/util/constants.py` 中的 `SKILL_SLUG` / `SKILL_VERSION`。
-7. 本地 SQLite 的中文表名/字段名、标准时间字段与字段顺序规范见 `references/SCHEMA.md`（元数据表 `_jiangchang_*` + `CREATE TABLE` 物理顺序）。
+7. 本地 SQLite 的中文表名/字段名、标准时间字段与字段顺序规范见 `references/SCHEMA.md`。

 ## 技能命名与 slug