153 lines
9.7 KiB
Markdown
153 lines
9.7 KiB
Markdown
---
|
||
name: 技能开发模板（通用业务版）
|
||
description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。"
|
||
version: 1.0.45
|
||
author: 深圳匠厂科技有限公司
|
||
metadata:
|
||
openclaw:
|
||
slug: your-skill-slug
|
||
platform_kit_min_version: "1.2.0"
|
||
emoji: "📦"
|
||
category: "通用"
|
||
developer_ids:
|
||
- 10032
|
||
- 12428
|
||
allowed-tools:
|
||
- bash
|
||
---
|
||
|
||
# 技能开发模板（skill-template）
|
||
|
||
这是一个**用于复制的新技能模板**，不是业务 skill 本身。复制后请替换占位内容，实现你的真实业务逻辑。
|
||
|
||
## Agent / 宿主编排（复制为业务技能后必改）
|
||
|
||
### 架构铁律（先读）
|
||
|
||
- **单业务内核、多入口**：数据管理 / 定时任务 / Agent / 技能详情 / 直接 CLI 必须复用同一 domain service；禁止按入口复制业务逻辑，禁止按 `source` 分叉业务行为。
|
||
- **`placements`**：只决定 Action **出现在哪里**（toolbar / cron / agent / skill-detail）。
|
||
- **`bind.tables`**：只决定数据管理出现在哪些表；含 `toolbar` 时**必须**显式非空绑定。
|
||
- **`executionProfile`**：只决定执行方式——`sync` 当场返回结果，`async` 进**任务中心**。与 placements / 入口**无关**；每个 Action **必须**显式写 `sync` 或 `async`。
|
||
- **同步数据**写技能本地库、不生成导出文件；**导出当前表**由宿主数据管理负责；特殊业务报告才另做 `export-*`。
|
||
- **准备 vs 执行（适用则拆）**：若技能存在「先写入/准备本地数据」与「再对外产生副作用」两段，Agent 必须能分开触发；禁止默认绑成不可拆的一步。一键无准备态的技能可跳过本条。
|
||
|
||
### 如何触发（能力类型）
|
||
|
||
| 你要做什么 | 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/` | — |
|
||
|
||
### 用户意图路由表（业务技能复制后必改）
|
||
|
||
复制为业务技能后，**必须**用本技能真实意图改写下表（保留三列结构）。格子写清：短 CLI 子命令，或 `run_skill_action` → **具体 action id**（及主要 `input`）。勿留模板占位语上线。
|
||
|
||
| 用户意图（本技能自填） | Agent 怎么做 | 进任务中心？ |
|
||
|------------------------|--------------|--------------|
|
||
| （例）查询 / 统计 / 列表 | 短 CLI：`<your-read-commands>` | 否 |
|
||
| （例）写入 / 导入 / 改本地状态 | 短 CLI：`<your-prep-commands>` | 否 |
|
||
| （例）长副作用 / RPA / 需进度 | `run_skill_action` → `<your-async-action-id>`，`input.…` | 是（因该 Action 为 async） |
|
||
|
||
有长任务 / RPA 时：上表至少一行指向真实的 async action id，且该 id 须出现在 `assets/actions.json`；细节分流见 `references/CLI.md`。
|
||
|
||
**硬规则：**
|
||
|
||
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。
|
||
6. 是否进任务中心**只**看该 Action 的 `executionProfile`，与数据管理 / 定时 / Agent 入口无关。
|
||
|
||
Agent 执行契约细节：`references/CLI.md`、`references/ACTIONS.md`、`references/SCHEMA.md`（不要把 `development/` 当 Agent 主读路径）。
|
||
|
||
## 共享 Python（必读）
|
||
|
||
宿主共享 runtime 在 `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`，并已前置到 PATH（同时设 `VIRTUAL_ENV`）。短 CLI 一条命令直接跑：
|
||
|
||
```bash
|
||
python {baseDir}/scripts/main.py health
|
||
python {baseDir}/scripts/main.py version
|
||
python {baseDir}/scripts/main.py config-path
|
||
python {baseDir}/scripts/main.py init-db
|
||
```
|
||
|
||
- 公共库来自共享 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 规则）
|
||
|
||
- 本文（`SKILL.md`）是 LLM / OpenClaw 平台读取的技能入口，**不是**用户市场说明。
|
||
- 根目录 `README.md` 是面向普通用户的说明。
|
||
|
||
当用户询问以下问题时，**必须优先读取**根目录 `README.md`，并用用户能理解的业务语言回答：
|
||
|
||
- 这个技能是做什么的
|
||
- 这个技能怎么用
|
||
- 适合什么场景
|
||
- 使用前要准备什么
|
||
- 执行后会得到什么
|
||
- 能不能帮我完成某个业务任务
|
||
|
||
**回答「怎么用 / 能做什么」时的要求：**
|
||
|
||
1. 以 `README.md` 的「能帮你做什么」「你可以这样告诉 Agent」「常见问题」等章节为主组织回答。
|
||
2. **禁止**在回答中粘贴 `python …/scripts/main.py …` 或其它命令行（除非用户明确索要命令，或自称技术人员/开发者）。
|
||
3. **禁止**为答用法而去 `dir` / `ls` / 列技能目录，或默认打开 `references/`、`development/`；仅当用户明确问命令、参数、集成或排错时再读 `references/`。
|
||
4. **不要**向普通用户暴露 Playwright、DOM、Python、RPA、库表名、`error_code` 等实现细节，除非用户明确询问技术实现。
|
||
|
||
**文档读取边界：**
|
||
|
||
- **不要**把 `SKILL.md`、`references/`、`development/` 中的技术细节直接作为用户回答。
|
||
- **只有当**用户明确询问命令、参数、输出结构、开发、调试、集成或排错时，才读取 `references/`；`development/` 主要给开发者 / 编码助手，对话 Agent **不必**默认打开。
|
||
- 若 `README.md` 与 `SKILL.md` / `references` 表述冲突：对用户展示与市场说明以 `README.md` 为准；对执行契约以 `SKILL.md` / `references` 为准。
|
||
- 用户未问技术实现时，**不要**讨论 slug 命名规则；开发者问命名或 slug 时，读取 `development/NAMING.md`。
|
||
|
||
## 文档分工
|
||
|
||
| 文档 | 读者 | 用途 |
|
||
|------|------|------|
|
||
| 根目录 `README.md` | 普通用户 | 技能市场详情页说明（`metadata.readme_md` 主来源） |
|
||
| `SKILL.md`（本文） | LLM / OpenClaw 平台 | 技能入口、触发与运行契约摘要 |
|
||
| `references/` | Agent 编排 / 调用 | CLI、Action、schema 契约（Agent 主读） |
|
||
| `development/` | 开发者 / AI 编程代理 | 需求、开发教程、测试、深度技术规范 |
|
||
|
||
## 目录约定
|
||
|
||
复制后建议保留：
|
||
|
||
- `assets/`、`development/`、`evals/`、`references/`、`scripts/`、`tests/`
|
||
- CLI 入口固定为 `scripts/main.py`
|
||
- 业务逻辑按 `cli / db / service / util` 分层
|
||
|
||
## 定制入口
|
||
|
||
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`。
|
||
6. 同步修改 `scripts/util/constants.py` 中的 `SKILL_SLUG` / `SKILL_VERSION`。
|
||
7. 本地 SQLite 的中文表名/字段名、标准时间字段与字段顺序规范见 `references/SCHEMA.md`。
|
||
|
||
## 技能命名与 slug
|
||
|
||
- 标准格式：`{verb}-{noun-phrase}-{platform}`（详见 `development/NAMING.md`）。
|
||
- slug / repo / 目录 / `SKILL_SLUG` / DB 文件名：**英文** kebab-case；`name`、`description`、根 `README.md`：**中文**。
|
||
- 复制为新业务技能前**必须**阅读 `development/NAMING.md`。
|
||
- `name`（frontmatter）：**用户可见的中文业务名称**；`description` 是说明，不是名称。
|
||
- `metadata.openclaw.slug`：**英文 kebab-case** 机器标识；目录名、默认 `{slug}.db` 使用 slug，不使用中文。
|
||
- 复制后全局替换 `your-skill-slug` 与 `your_skill_slug`（脚手架会自动处理）；正式技能不得保留英文占位 `name` 或 slug。
|
||
|
||
## 平台元数据
|
||
|
||
- `metadata.openclaw.developer_ids`：技能发布后的默认开发者可见用户 ID 列表。
|
||
- 当 `access_scope = 0`（不公开）时，平台会把 `developer_ids` 中的用户自动补写到 `skill_user_access`。
|
||
- `developer_ids` 建议写为正整数数组；第一个 ID 会作为主开发者同步到 `skills.developer_id`。
|