client-commons/skill-template

Fork 0

Files

chendelian b267ca3266

技能自动化发布 / release (push) Successful in 7s

Details

chore: auto release commit (2026-06-15 17:32:47)

2026-06-15 17:32:49 +08:00

28 KiB

Raw Blame History

技能开发教程

这份文档是给技术人员看的，目标不是解释概念，而是让你拿到 skill-template 后，可以一步一步开发出一个新的 skill。

本文默认你开发的是当前最常见的一类业务 skill：

有明确的 scripts/main.py CLI 入口
可能需要读写本地 SQLite（例如任务日志 task_logs）
可能需要调用兄弟技能或外部 HTTP / RPA
业务逻辑主要放在 scripts/service/

发布、对账、代发、报表分析等场景都只是业务特例；模板提供通用骨架，复制后按领域补齐实现即可。

工具	类型	适合场景	官方入口
Cursor	独立 AI IDE	代码编辑、Agent 开发、整仓理解	官网 / 下载
Windsurf	独立 AI IDE	Agent 编程、项目生成、连续开发流	文档 / 下载
GitHub Copilot	IDE 插件 / 编程助手	日常补全、解释代码、生成函数、配合 VS Code 或 JetBrains 使用	官网
Claude Code	终端 / IDE 编程代理	命令行开发、代码库分析、自动改代码、运行命令	官网 / 文档
Codex	终端 / IDE / Web 编程代理	OpenAI 官方编码代理，适合代码生成、理解、调试、评审	官网 / 快速开始
Aider	终端 AI 编程工具	已有代码仓库的增量开发、终端协作、快速提交	官网 / 文档
Cline	VS Code / JetBrains 插件	编辑器内 Agent 开发、命令执行、浏览器联动调试	官网 / 文档 / VS Code 插件

工具	类型	适合场景	官方入口
Trae	独立 AI IDE	AI 辅助写代码、项目搭建、对话式开发	官网 / 下载
通义灵码	独立 IDE / IDE 插件	国内团队日常编码、问答、补全、代码生成	官网 / 下载
CodeGeeX	IDE 插件 / 开源助手	代码补全、生成、注释、跨语言辅助	GitHub / VS Code 插件
腾讯 CodeBuddy	IDE 插件	代码补全、测试生成、智能问答、腾讯云开发体系协作	官网 / 文档 / VS Code 插件
百度文心快码（Baidu Comate）	IDE 插件	国内研发团队辅助编码、解释、测试、优化	官网

1. 先理解模板的定位

skill-template 不是业务 skill，它只是一个新 skill 仓库模板。

你不应该直接在这个仓库里开发业务，而应该：

复制这个目录
改成新 skill 的目录名
把占位内容替换掉
再开始写业务逻辑

2. 新 skill 的标准目录结构

复制模板后，你应该保留下面这套结构：

your-skill/
├─ .github/
├─ assets/
├─ development/
├─ evals/
├─ references/
├─ scripts/
│  ├─ cli/
│  ├─ db/
│  ├─ service/
│  └─ util/
├─ tests/
├─ .gitignore
├─ README.md
├─ requirements.txt
├─ release.ps1
└─ SKILL.md

各目录职责如下：

assets/：放示例输出、schema、静态说明资源
README.md：面向用户的市场详情页说明
SKILL.md：面向 LLM / 平台的技能入口
references/：Agent 运行/编排/调用时渐进加载的补充上下文（如 CLI、SCHEMA）
development/：面向开发者与 AI 编程代理的开发资料、需求、测试与技术规范
scripts/：放真正的代码
tests/：放自动化测试
evals/：放人工验收材料、评估清单、示例场景

3. `scripts/` 内部如何分层

scripts/ 不是乱放 Python 文件，而是按职责分层：

scripts/
├─ main.py
├─ cli/
├─ db/
├─ service/
└─ util/

每层的职责要明确：

main.py 作用：唯一 CLI 入口只做启动、编码兼容、引入 cli.app
cli/ 作用：参数解析、命令分发、用法说明不写具体业务逻辑
db/ 作用：SQLite 连接、建表、repository 不写页面操作和业务编排
service/ 作用：核心业务逻辑比如任务编排、调用兄弟技能、外部 API、可选浏览器自动化
util/ 作用：常量、日志、路径、时间工具、通用帮助函数

公共能力（config、logging、runtime_env、rpa、media_assets、video_session、runtime_diagnostics）从共享 runtime 的 jiangchang-platform-kit>=1.0.14 import，不得在 scripts/ 下保留 jiangchang_skill_core/ 副本。

3.2 开发 RPA 类 skill

若 skill 需要浏览器/桌面/手机自动化，按以下顺序落地：

先读三份标准：RPA.md（三端范式与反反爬）、CONFIG.md（.env 落盘与读取）、ADAPTER.md（四档 adapter）。
从模板复制骨架：
- scripts/service/example_adapter/ → 改名为 scripts/service/<domain>_adapter/（仅 adapter 四档骨架，不等同于真实浏览器 RPA 成功案例）
- 若是 真实浏览器 RPA（真实网站、登录态、验证码、滚动采集），必须先读 examples/real_browser_rpa/README.md，再按需参考：
  - examples/real_browser_rpa/scripts/service/browser_session.py
  - examples/real_browser_rpa/scripts/service/human_verification.py
  - examples/real_browser_rpa/scripts/service/task_rpa.py
  - examples/real_browser_rpa/scripts/service/account_client.py
- 若是 仿真浏览器 RPA（自有 sandbox、表单批量提交、可控 DOM），必须先读 examples/simulator_browser_rpa/README.md，再按需参考：
  - examples/simulator_browser_rpa/scripts/service/browser_session.py
  - examples/simulator_browser_rpa/scripts/service/adapter/
  - examples/simulator_browser_rpa/scripts/service/task_service.py
  - examples/simulator_browser_rpa/sandbox/demo_app.html
只用共享库，不在 skill 里重写反反爬：
```
from jiangchang_skill_core import config
from jiangchang_skill_core.rpa import launch_persistent_browser, anti_detect, wait_for_captcha_pass
```
上述 import 来自宿主共享 runtime 安装的 jiangchang-platform-kit，不是技能目录副本。
mock 档必须离线可跑（OPENCLAW_TEST_TARGET=mock）；sim_rpa / real_* 按需单独测。
桌面/手机：本期标准见 RPA.md 第 2/3 节，复用 jiangchang_desktop_sdk / screencast，不要在新 skill 里重复造包（尚待实战验证）。

3.1 `requirements.txt` 依赖规范

技能根目录的 requirements.txt 是标准文件，用于声明本技能特有 Python 三方依赖。

公共依赖（jiangchang-platform-kit、playwright、config、runtime diagnostics、RPA 公共能力等）由宿主共享 runtime 提供，不要写入技能 requirements.txt。
SKILL.md 的 metadata.openclaw.platform_kit_min_version（当前 1.0.14）是运行契约/兼容性声明，供宿主安装与启用时校验，不是 pip 依赖声明。
匠厂宿主安装/更新技能后，会将技能 requirements.txt 安装到共享 venv：{JIANGCHANG_DATA_ROOT}/python-runtime/.venv。
不要在业务代码中 subprocess / pip install；缺依赖由 health 报错，由宿主负责安装。
版本约束尽量收窄，降低多技能共享 venv 时的冲突风险。推荐范围写法：
- pkg>=1.2.0,<2
对原生扩展 / 高风险依赖（如 chromadb、onnxruntime）建议 pin 或窄范围，避免无上限：
- 不推荐：chromadb>=0.5.0
- 推荐：chromadb>=0.5.23,<0.6
不要把系统组件（VC++ Runtime、浏览器安装包等）写进 requirements.txt；这类前置条件写在 health / preflight 文档与错误提示中。
若技能无额外 Python 依赖，可保留空文件或仅含注释说明；不要为 platform-kit 或 playwright 保留占位行。
独立本地开发环境若缺少公共包，可手动安装；生产/宿主运行由共享 runtime 负责。

3.3 公共能力不要复制

以下模块由 platform-kit 提供，技能内不要重复实现或 vendored 拷贝：

能力	导入方式
config	`from jiangchang_skill_core import config`
logging	`from jiangchang_skill_core.unified_logging import ...` 或 `util.logging_config` 薄封装
runtime_env	`from jiangchang_skill_core.runtime_env import ...` 或 `util.runtime_paths` 薄封装
rpa	`from jiangchang_skill_core.rpa import ...`
media_assets	`from jiangchang_skill_core.media_assets import ...`
video_session	`from jiangchang_skill_core.rpa.video_session import RpaVideoSession`
runtime_diagnostics	`from jiangchang_skill_core import collect_runtime_diagnostics, format_runtime_health_lines`

health 应委托 collect_runtime_diagnostics，不要在 scripts/util/ 自建 runtime_diagnostics.py。

4. 开发一个新 skill 的标准步骤

下面这套顺序建议严格按步骤做，不要一上来就直接写 service。

第一步：复制模板并改目录名

例如你要开发 your-skill-slug（或 disburse-payroll-icbc 一类领域 skill）：

复制 skill-template
新目录改成与 slug 一致的名称（如 your-skill-slug）
初始化为独立 git 仓库
关联它自己的远端仓库

目录名要和 skill slug 对齐，后面很多地方都依赖这个命名。

第二步：先改 4 个最关键的标识

复制后优先改下面这些地方：

SKILL.md
根目录 README.md（用户市场说明）
scripts/util/constants.py
references/ 与 development/ 下的文案
scripts/service/ 下的业务占位实现（优先改 task_service.py）

最先要统一的是：

技能中文名
slug
平台中文名
平台内部键
日志 logger 名

此外，如果该技能发布后默认不公开（access_scope = 0），建议一开始就把 SKILL.md 中的 metadata.openclaw.developer_ids 配好。这样后续发布到平台时，开发者本人仍能在技能市场中看到并验证该技能。

5. 哪些占位内容必须替换

复制后，至少要全局检查并替换下面这些内容：

your-skill-slug
your-platform-key（若 skill 涉及外部平台对接，可能会用到这类占位）
技能开发模板（通用业务版）
你的平台名
openclaw.skill.your_skill_slug

如果你的 skill 对外 CLI 需要自定义文案或别名（例如发布类对外仍叫 publish），通常还要替换：

run 命令中的中文提示与别名策略（见 ../references/CLI.md）
../references/CLI.md 的命令示例
../README.md 的用户话术
../references/SCHEMA.md 的字段映射补充说明

如需浏览器自动化，不要在模板里保留空的 platform_playwright.py；请按业务新建 xxx_playwright.py（命名自定），并在 task_service.py 中按需引用。

6. `SKILL.md` 与根 `README.md` 应该怎么写

`SKILL.md`（LLM / 平台入口）

SKILL.md 是给 LLM 与 OpenClaw 平台看的技能入口，不是用户市场详情页。

应该重点写：

YAML frontmatter：name、description、version、metadata.openclaw（含 slug、platform_kit_min_version、developer_ids 等）
何时触发本技能、CLI 入口摘要、运行契约要点
指向 references/（Agent 调用）与 development/（开发规范）的分工说明

不要在 SKILL.md 里写大量用户市场文案或实现细节。

根 `README.md`（用户市场说明）

根 README.md 是技能市场详情页主来源（metadata.readme_md），面向普通用户。

应包含 YAML frontmatter 的 description（市场列表简介），正文用用户能理解的语言说明：

能做什么、适合什么场景、使用前准备什么
如何自然语言告诉 Agent
执行结果、注意事项、常见问题

不要在根 README.md 里写开发教程、目录规范、release、requirements 等技术细节。

实现细节放在：

development/
references/（CLI / SCHEMA）
代码注释与 service/ 实现

关于 `metadata.openclaw.developer_ids`

这是一个平台发布元数据字段，用于解决下面这个问题：

技能发布后若平台记录中的 access_scope = 0，技能默认不公开
如果不额外授权，连开发者自己也可能在技能市场里看不到这个技能

因此可以在 SKILL.md 中声明：

metadata:
  openclaw:
    slug: your-skill-slug
    category: 通用
    developer_ids:
      - 1032
      - 12428

约定如下：

只允许填写正整数用户 ID
推荐使用数组，即使当前只有 1 个开发者
发布时平台会把这些用户自动补写到 skill_user_access
第一个 ID 会同步到 skills.developer_id
一期只做“补授权”，不会因为你 later 修改数组而自动撤销旧授权

7. 文档目录分工

当前规范 skill 的文档按读者拆分：

根 README.md

用户市场详情页说明（含 frontmatter description）

SKILL.md

LLM / OpenClaw 平台技能入口

references/（Agent 运行/编排/调用时渐进加载）

README.md — Agent 参考索引
CLI.md — 命令、参数、默认值、兄弟技能调用方式
SCHEMA.md — 数据库路径、核心表结构、日志表结构
可按需增加 ERRORS.md、INTEGRATION.md 等编排向补充

development/（开发者 / AI 编程代理）

REQUIREMENTS.md — 需求与验收
DEVELOPMENT.md — 开发教程（本文档）
TESTING.md — 测试分层与隔离（详见 TESTING.md）
ADAPTER.md、RPA.md、CONFIG.md、RUNTIME.md — 技术规范

8. `assets/` 应该放什么

assets/ 不放业务代码，只放辅助材料。

建议放：

examples/ 比如 version 输出示例、log-get 输出示例
schemas/ 比如日志记录、机读 JSON 的 schema

不要把正式研发文档放到 assets/。用户说明进根 README.md；Agent 编排资料进 references/；开发规范进 development/。

9. `cli` 层怎么写

建议保持一个原则：

cli 只负责解析参数和路由
service 才负责干活

也就是说，cli/app.py 的职责是：

打印帮助
定义 run / logs / log-get / health / version
把参数转交给 service.task_service

不要在 cli/app.py 里直接写：

浏览器自动化
子进程调用兄弟技能
SQLite 逻辑

10. `service` 层怎么写

service 是核心层。

通常可以这样拆：

task_service.py 放命令编排、参数兜底、结果分流（例如 cmd_run）
sibling_bridge.py 放通用兄弟技能子进程工具（call_sibling_json）；具体调用哪个 slug 由业务在 task_service.py 决定，不要在本文件硬编码发布类专用 helper
xxx_playwright.py（按需新建）浏览器后台自动化 不在模板默认结构中；若确有需要，按命名约定自建模块并在 task_service.py 引用
entitlement_service.py 放鉴权逻辑

一个很重要的原则

不要把所有逻辑都堆进一个文件。

推荐流向是：

cli.app -> service.task_service -> service.sibling_bridge / （可选）service.xxx_playwright -> db

11. `db` 层怎么写

如果你的 skill 需要记录日志或本地状态，建议：

db/connection.py 只做连接和建表
db/task_logs_repository.py 只做增删查改（模板默认表：task_logs）

不要在 db 层里：

调浏览器
打印用户提示
拼接业务流程

12. 如何接兄弟技能

如果 skill 要依赖兄弟 skill，不要在业务代码里写死绝对路径。

统一通过：

scripts/util/runtime_paths.py
scripts/service/sibling_bridge.py

来做调用。

调用哪些兄弟技能由具体业务决定；请在 task_service.py 中使用 service.sibling_bridge.call_sibling_json(skill_slug, args) 或 get_sibling_main_path(skill_slug)，不要在本模板仓库的 sibling_bridge.py 中堆积特定技能函数。

调用原则：

通过 get_skills_root() 找到兄弟技能根目录
再拼出对应 scripts/main.py
用子进程调用
机器可读输出优先 JSON

13. 如何开发一个新 skill

不管你开发的是发布类、采集类、分析类还是知识库类 skill，建议都先按下面这个顺序推进：

先把目录结构搭完整
先让 health / version 跑通
再把核心 service 骨架跑通
再接兄弟技能桥接、数据库或外部系统
最后再补浏览器自动化、复杂流程编排或高风险集成

不要一开始就直接写页面选择器、复杂接口编排或深层业务逻辑。

推荐先确保这些基础能力正常：

CLI 入口能跑通
基础命令输出稳定
关键依赖能取到
日志或本地状态能落下来
错误返回值格式定好了

如果你的 skill 属于外联型 / RPA 型，可以把上面的“核心 service”具体落成 task_service.py，再按需接 sibling_bridge.py、（可选）*_playwright.py。这只是示例路径组合，不代表模板绑定某一业务领域。

14. 本地开发的最小验证顺序

建议每次新 skill 开发时按下面顺序验证：

1. 验证入口

python scripts/main.py health
python scripts/main.py version

2. 验证 CLI 路由

python scripts/main.py -h
python scripts/main.py <your-command> -h

3. 验证本地日志与数据库

如果你的 skill 需要本地日志或数据库，再继续：

python scripts/main.py <your-log-command>
python scripts/main.py <your-detail-command> <id>

如果你沿用了模板中的通用任务日志骨架，那么这里可以具体对应成：

python scripts/main.py logs
python scripts/main.py log-get 1

4. 最后再验证真实业务

比如：

python scripts/main.py <your-command>

14.5 测试驱动的开发顺序

新 skill 不应该等所有业务做完才补测试。建议在每个开发阶段都先把对应测试跑一遍：

目录搭建后：跑 python tests/run_tests.py -v，确认全部默认测试套件通过。
- 此时 test_skill_metadata.py 会校验 SKILL.md slug 与 constants.SKILL_SLUG 一致；如果你只改了一边，会立刻发现。
改完 constants 后：再跑一次必跑套件，确认未引入回归。
写完 service 业务后：从 tests/samples/test_service_contract.py.sample 复制一份做契约测试。
接外部系统时：写在 tests/integration/，并配合 OPENCLAW_TEST_TARGET 显式开启。

详见 TESTING.md。

15. 发布到正式环境验证

在执行 release.ps1 之前，必须先在本地确认 python tests/run_tests.py -v 通过。测试不通过不得发起正式发布。

当本地开发、自测和联调完成后，还需要把 skill 发布到正式环境做一次完整验证。建议技术人员严格按下面顺序执行，不要跳步。

第一步：在 skill 根目录执行 `release.ps1`

在当前 skill 仓库根目录执行：

.\release.ps1

如果你的技能使用了 metadata.openclaw.developer_ids，那么这一步触发的发布工作流除了同步 skills / skill_versions 外，还会在平台侧自动补开发者可见权限。测试非公开技能时，建议重点验证这部分是否生效。

这一步会自动完成标准发布动作，包括：

检查当前仓库状态
自动提交尚未提交的改动
推送最新代码到远程仓库
自动创建新的语义化版本 tag
推送 tag，触发后续 CI 流程

如果你只是想先预览发布动作，可以先执行：

.\release.ps1 -DryRun

第二步：到 Gitea 仓库查看工作流

发布命令执行完成后，远程仓库会自动触发 Gitea 工作流。此时应立即进入对应 skill 的仓库页面，切换到“工作流”页签查看执行状态。

重点确认：

是否已经出现最新一次发布记录
是否由最新提交触发
是否成功执行完 release_skill.yaml

下面这张图演示了在仓库页进入“工作流”的位置：

下面这张图演示了工作流成功后的状态页面：

第三步：确认工作流执行成功

只有当工作流状态为成功，才说明正式发布产物已经正确构建完成。

如果工作流失败，不要继续做平台验证，而应该先回到代码仓库排查，例如：

发布脚本是否正常推送
SKILL.md、根 README.md、scripts/、references/、development/ 是否齐全
工作流文件是否存在
发布包结构是否符合模板规范

第四步：进入匠厂平台下载安装包

当工作流成功后，就可以进入匠厂平台验证最终安装效果。

匠厂产品下载地址：

https://jc2009.com/product.html

打开页面后，下载并安装匠厂客户端。下面这张图演示了下载入口位置：

匠厂产品页可从这里进入：产品下载 - 匠厂

第五步：安装匠厂后，在技能市场检查最新 skill

安装并启动匠厂后，进入左侧“技能市场”，搜索或查找刚刚发布的 skill，确认以下内容：

技能可以被正常检索到
技能名称、说明、版本信息正确
最新版本已经同步出来
可以正常安装或更新

下面这张图演示了在技能市场中查看已发布 skill 的位置：

第六步：安装并实际启用该 skill

在技能市场中找到目标 skill 后，执行安装或更新操作，确保客户端本地已经拿到最新版本。

这一步建议至少确认：

安装按钮可以正常执行
安装后状态正常
不会出现缺文件、缺入口或安装失败的问题

第七步：在“新建任务”中实际使用该 skill

安装完成后，不要只停留在“已安装”状态，还需要进入“新建任务”页面，真正调用一次该 skill，完成最终验证。

建议至少验证：

新任务中可以正常选择或触发该 skill
skill 能被正确唤起
主要命令或主流程可以运行
返回结果、日志和行为符合预期

下面这张图演示了安装后在任务界面中实际使用 skill 的场景：

16. 发布前检查清单

每个新 skill 发布前，建议技术人员逐条确认：

目录结构符合当前模板
SKILL.md 中 slug、名称、描述都已替换
scripts/util/constants.py 已修改
../references/CLI.md 示例命令已改成真实命令
service 下的核心业务文件（如 task_service.py）已按领域改名并实现
没有残留旧平台名
health / version 可运行
.gitignore 生效，没有把 __pycache__ 提交进去
release.ps1 存在
.github/workflows/release_skill.yaml 存在
python tests/run_tests.py -v 全部通过
没有新增默认必跑测试访问真实网络或浏览器
如有 integration 测试需求，已写在 tests/integration/ 下并保持 .sample 后缀

17. 常见错误

错误 1：只改了目录名，没改 slug

表现：

数据目录不对
版本输出不对
日志名不对

要检查：

SKILL.md
scripts/util/constants.py

错误 2：平台中文名改了，内部键没改

表现：

兄弟技能筛选账号失败
run 命令走错平台或 task_type

要检查：

task_service.py
sibling_bridge.py
../references/CLI.md

错误 3：把业务逻辑写进 CLI

表现：

文件越来越乱
不方便测
参数和业务耦合太重

要改回：

cli 只做参数解析
service 才做业务

错误 4：保留了旧模板结构

表现：

仓库同时存在 docs/、optional/、skill_main.py
技术人员不知道看哪一套

现在的新模板原则是：

不做旧结构兼容
用户说明在根 README.md，Agent 资料在 references/，开发规范在 development/
统一走 scripts/main.py 作为 CLI 入口

18. 推荐开发顺序总结

如果让一个新人照着做，我建议他按这个顺序：

复制模板并改目录名
改 SKILL.md 与根 README.md
改 scripts/util/constants.py
改 references/ 与 development/
改 scripts/cli/app.py
改 scripts/service/
跑 python tests/run_tests.py -v
跑 health / version
再做业务联调
最后 release

19. 这份模板的底线要求

以后新建 skill，至少要满足这几点：

目录结构统一
入口统一为 scripts/main.py
用户说明在根 README.md，Agent 资料在 references/，开发规范在 development/
业务核心逻辑统一放 scripts/service/
不再使用旧模板历史结构

如果做不到这些，后面 skill 一多，就会越来越乱。

28 KiB Raw Blame History Unescape Escape