548 lines
13 KiB
Markdown
548 lines
13 KiB
Markdown
# 技能开发教程
|
||
|
||
这份文档是给**技术人员**看的，目标不是解释概念，而是让你拿到 `skill-template` 后，可以**一步一步开发出一个新的 skill**。
|
||
|
||
本文默认你开发的是当前最常见的一类技能：
|
||
|
||
- 有明确的 `scripts/main.py` CLI 入口
|
||
- 可能需要读写本地 SQLite
|
||
- 可能需要调用兄弟技能
|
||
- 业务逻辑主要放在 `scripts/service/`
|
||
|
||
如果你开发的是发布型 skill，这个模板就是直接可用的起点。
|
||
|
||
## 1. 先理解模板的定位
|
||
|
||
`skill-template` 不是业务 skill，它只是一个**新 skill 仓库模板**。
|
||
|
||
你不应该直接在这个仓库里开发业务，而应该：
|
||
|
||
1. 复制这个目录
|
||
2. 改成新 skill 的目录名
|
||
3. 把占位内容替换掉
|
||
4. 再开始写业务逻辑
|
||
|
||
## 2. 新 skill 的标准目录结构
|
||
|
||
复制模板后，你应该保留下面这套结构：
|
||
|
||
```text
|
||
your-skill/
|
||
├─ .github/
|
||
├─ assets/
|
||
├─ evals/
|
||
├─ references/
|
||
├─ scripts/
|
||
│ ├─ cli/
|
||
│ ├─ db/
|
||
│ ├─ jiangchang_skill_core/
|
||
│ ├─ service/
|
||
│ └─ util/
|
||
├─ tests/
|
||
├─ .gitignore
|
||
├─ README.md
|
||
├─ release.ps1
|
||
└─ SKILL.md
|
||
```
|
||
|
||
各目录职责如下：
|
||
|
||
- `assets/`：放示例输出、schema、静态说明资源
|
||
- `references/`：放研发和编排需要长期维护的文档
|
||
- `scripts/`：放真正的代码
|
||
- `tests/`：放自动化测试
|
||
- `evals/`：放人工验收材料、评估清单、示例场景
|
||
|
||
## 3. `scripts/` 内部如何分层
|
||
|
||
`scripts/` 不是乱放 Python 文件，而是按职责分层：
|
||
|
||
```text
|
||
scripts/
|
||
├─ main.py
|
||
├─ cli/
|
||
├─ db/
|
||
├─ jiangchang_skill_core/
|
||
├─ service/
|
||
└─ util/
|
||
```
|
||
|
||
每层的职责要明确：
|
||
|
||
- `main.py`
|
||
作用：唯一 CLI 入口
|
||
只做启动、编码兼容、引入 `cli.app`
|
||
|
||
- `cli/`
|
||
作用：参数解析、命令分发、用法说明
|
||
不写具体业务逻辑
|
||
|
||
- `db/`
|
||
作用：SQLite 连接、建表、repository
|
||
不写页面操作和业务编排
|
||
|
||
- `service/`
|
||
作用：核心业务逻辑
|
||
比如发布流程、调用兄弟技能、浏览器自动化
|
||
|
||
- `util/`
|
||
作用：常量、日志、路径、时间工具、通用帮助函数
|
||
|
||
- `jiangchang_skill_core/`
|
||
作用：运行时环境与统一日志副本
|
||
一般按现有规范技能复制，不要自己乱改结构
|
||
|
||
## 4. 开发一个新 skill 的标准步骤
|
||
|
||
下面这套顺序建议严格按步骤做，不要一上来就直接写 `service`。
|
||
|
||
### 第一步：复制模板并改目录名
|
||
|
||
例如你要开发 `weibo-publisher`：
|
||
|
||
1. 复制 `skill-template`
|
||
2. 新目录改成 `weibo-publisher`
|
||
3. 初始化为独立 git 仓库
|
||
4. 关联它自己的远端仓库
|
||
|
||
目录名要和 skill slug 对齐，后面很多地方都依赖这个命名。
|
||
|
||
### 第二步：先改 4 个最关键的标识
|
||
|
||
复制后优先改下面这些地方：
|
||
|
||
1. `SKILL.md`
|
||
2. `scripts/util/constants.py`
|
||
3. `references/` 下的文案
|
||
4. `scripts/service/` 下的平台占位文件名
|
||
|
||
最先要统一的是：
|
||
|
||
- 技能中文名
|
||
- `slug`
|
||
- 平台中文名
|
||
- 平台内部键
|
||
- 日志 logger 名
|
||
|
||
## 5. 哪些占位内容必须替换
|
||
|
||
复制后，至少要全局检查并替换下面这些内容：
|
||
|
||
- `your-skill-slug`
|
||
- `your-platform-key`
|
||
- `技能开发模板（复制后请修改）`
|
||
- `你的平台名`
|
||
- `platform_playwright.py`
|
||
- `openclaw.skill.your_skill_slug`
|
||
|
||
如果你是做发布型 skill，通常还要替换：
|
||
|
||
- `publish` 命令中的中文提示
|
||
- `references/CLI.md` 的命令示例
|
||
- `references/README.md` 的用户话术
|
||
- `references/SCHEMA.md` 的数据库文件名
|
||
|
||
## 6. `SKILL.md` 应该怎么写
|
||
|
||
`SKILL.md` 是技能清单，不是设计文档。
|
||
|
||
应该重点写：
|
||
|
||
- 技能名称
|
||
- 技能描述
|
||
- slug
|
||
- category
|
||
- dependencies
|
||
- 何时使用本技能
|
||
- 对用户的引导话术
|
||
- CLI 使用原则
|
||
|
||
不要在 `SKILL.md` 里写大量实现细节。
|
||
实现细节放在：
|
||
|
||
- `references/`
|
||
- 代码注释
|
||
- `service/` 实现里
|
||
|
||
## 7. `references/` 应该放什么
|
||
|
||
`references/` 是当前规范 skill 的文档中心，建议至少有这些：
|
||
|
||
- `README.md`
|
||
面向内部说明和技能作用介绍
|
||
|
||
- `CLI.md`
|
||
写清楚命令、参数、默认值、兄弟技能调用方式
|
||
|
||
- `RUNTIME.md`
|
||
写清楚运行时目录、环境变量、入口约定
|
||
|
||
- `SCHEMA.md`
|
||
写清楚数据库路径、核心表结构、日志表结构
|
||
|
||
- `DEVELOPMENT.md`
|
||
写给技术人员的开发教程，也就是本文档
|
||
|
||
如果后面某个 skill 需要更细的说明，可以再加：
|
||
|
||
- `ERRORS.md`
|
||
- `INTEGRATION.md`
|
||
- `PLATFORMS.md`
|
||
|
||
## 8. `assets/` 应该放什么
|
||
|
||
`assets/` 不放业务代码，只放辅助材料。
|
||
|
||
建议放：
|
||
|
||
- `examples/`
|
||
比如 `version` 输出示例、`log-get` 输出示例
|
||
|
||
- `schemas/`
|
||
比如日志记录、机读 JSON 的 schema
|
||
|
||
不要把正式研发文档放到 `assets/`。
|
||
文档应该进 `references/`。
|
||
|
||
## 9. `cli` 层怎么写
|
||
|
||
建议保持一个原则：
|
||
|
||
- `cli` 只负责解析参数和路由
|
||
- `service` 才负责干活
|
||
|
||
也就是说，`cli/app.py` 的职责是：
|
||
|
||
1. 打印帮助
|
||
2. 定义 `publish / logs / log-get / health / version`
|
||
3. 把参数转交给 `service.publish_service`
|
||
|
||
不要在 `cli/app.py` 里直接写：
|
||
|
||
- 浏览器自动化
|
||
- 子进程调用兄弟技能
|
||
- SQLite 逻辑
|
||
|
||
## 10. `service` 层怎么写
|
||
|
||
`service` 是核心层。
|
||
|
||
通常可以这样拆：
|
||
|
||
- `publish_service.py`
|
||
放命令编排、参数兜底、结果分流
|
||
|
||
- `sibling_bridge.py`
|
||
放兄弟技能调用，例如调 `account-manager`、`content-manager`
|
||
|
||
- `*_playwright.py`
|
||
放浏览器后台自动化
|
||
|
||
- `entitlement_service.py`
|
||
放鉴权逻辑
|
||
|
||
### 一个很重要的原则
|
||
|
||
不要把所有逻辑都堆进一个文件。
|
||
|
||
推荐流向是：
|
||
|
||
`cli.app` -> `service.publish_service` -> `service.sibling_bridge` / `service.xxx_playwright` -> `db`
|
||
|
||
## 11. `db` 层怎么写
|
||
|
||
如果你的 skill 需要记录日志或本地状态，建议：
|
||
|
||
- `db/connection.py`
|
||
只做连接和建表
|
||
|
||
- `db/publish_logs_repository.py`
|
||
只做增删查改
|
||
|
||
不要在 `db` 层里：
|
||
|
||
- 调浏览器
|
||
- 打印用户提示
|
||
- 拼接业务流程
|
||
|
||
## 12. 如何接兄弟技能
|
||
|
||
如果 skill 要依赖兄弟 skill，不要在业务代码里写死绝对路径。
|
||
|
||
统一通过：
|
||
|
||
- `scripts/util/runtime_paths.py`
|
||
- `scripts/service/sibling_bridge.py`
|
||
|
||
来做调用。
|
||
|
||
常见调用对象是：
|
||
|
||
- `account-manager`
|
||
- `content-manager`
|
||
|
||
调用原则：
|
||
|
||
1. 通过 `get_skills_root()` 找到兄弟技能根目录
|
||
2. 再拼出对应 `scripts/main.py`
|
||
3. 用子进程调用
|
||
4. 机器可读输出优先 JSON
|
||
|
||
## 13. 如何开发发布型 skill
|
||
|
||
如果你开发的是 publisher 类 skill，建议按这个顺序做：
|
||
|
||
1. 先把目录结构搭完整
|
||
2. 先让 `health` / `version` 跑通
|
||
3. 再让 `publish_service.py` 的骨架跑通
|
||
4. 再接 `sibling_bridge.py`
|
||
5. 最后再写 `*_playwright.py`
|
||
|
||
不要一开始就直接写页面选择器。
|
||
|
||
推荐先确保这些基础能力正常：
|
||
|
||
- 能取到账号
|
||
- 能取到文章
|
||
- 能写日志
|
||
- CLI 子命令通了
|
||
- 错误返回值格式定好了
|
||
|
||
然后再进浏览器自动化。
|
||
|
||
## 14. 本地开发的最小验证顺序
|
||
|
||
建议每次新 skill 开发时按下面顺序验证：
|
||
|
||
### 1. 验证入口
|
||
|
||
```bash
|
||
python scripts/main.py health
|
||
python scripts/main.py version
|
||
```
|
||
|
||
### 2. 验证 CLI 路由
|
||
|
||
```bash
|
||
python scripts/main.py -h
|
||
python scripts/main.py publish -h
|
||
```
|
||
|
||
### 3. 验证本地日志与数据库
|
||
|
||
如果是发布型 skill，再继续：
|
||
|
||
```bash
|
||
python scripts/main.py logs
|
||
python scripts/main.py log-get 1
|
||
```
|
||
|
||
### 4. 最后再验证真实业务
|
||
|
||
比如：
|
||
|
||
```bash
|
||
python scripts/main.py publish
|
||
```
|
||
|
||
## 15. 发布到正式环境验证
|
||
|
||
当本地开发、自测和联调完成后，还需要把 skill 发布到正式环境做一次完整验证。建议技术人员严格按下面顺序执行，不要跳步。
|
||
|
||
### 第一步：在 skill 根目录执行 `release.ps1`
|
||
|
||
在当前 skill 仓库根目录执行：
|
||
|
||
```powershell
|
||
.\release.ps1
|
||
```
|
||
|
||
这一步会自动完成标准发布动作，包括：
|
||
|
||
1. 检查当前仓库状态
|
||
2. 自动提交尚未提交的改动
|
||
3. 推送最新代码到远程仓库
|
||
4. 自动创建新的语义化版本 tag
|
||
5. 推送 tag，触发后续 CI 流程
|
||
|
||
如果你只是想先预览发布动作，可以先执行：
|
||
|
||
```powershell
|
||
.\release.ps1 -DryRun
|
||
```
|
||
|
||
### 第二步：到 Gitea 仓库查看工作流
|
||
|
||
发布命令执行完成后，远程仓库会自动触发 Gitea 工作流。此时应立即进入对应 skill 的仓库页面，切换到“工作流”页签查看执行状态。
|
||
|
||
重点确认：
|
||
|
||
- 是否已经出现最新一次发布记录
|
||
- 是否由最新提交触发
|
||
- 是否成功执行完 `release_skill.yaml`
|
||
|
||
下面这张图演示了在仓库页进入“工作流”的位置：
|
||
|
||
|
||
|
||
下面这张图演示了工作流成功后的状态页面：
|
||
|
||
|
||
|
||
### 第三步：确认工作流执行成功
|
||
|
||
只有当工作流状态为成功，才说明正式发布产物已经正确构建完成。
|
||
|
||
如果工作流失败，不要继续做平台验证，而应该先回到代码仓库排查，例如：
|
||
|
||
- 发布脚本是否正常推送
|
||
- `SKILL.md`、`scripts/`、`references/` 是否齐全
|
||
- 工作流文件是否存在
|
||
- 发布包结构是否符合模板规范
|
||
|
||
### 第四步：进入匠厂平台下载安装包
|
||
|
||
当工作流成功后，就可以进入匠厂平台验证最终安装效果。
|
||
|
||
匠厂产品下载地址：
|
||
|
||
- [https://jc2009.com/product.html](https://jc2009.com/product.html)
|
||
|
||
打开页面后，下载并安装匠厂客户端。下面这张图演示了下载入口位置：
|
||
|
||
|
||
|
||
匠厂产品页可从这里进入：[产品下载 - 匠厂](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` 下的平台文件名已改对
|
||
- [ ] 没有残留旧平台名
|
||
- [ ] `health` / `version` 可运行
|
||
- [ ] `.gitignore` 生效，没有把 `__pycache__` 提交进去
|
||
- [ ] `release.ps1` 存在
|
||
- [ ] `.github/workflows/release_skill.yaml` 存在
|
||
|
||
## 17. 常见错误
|
||
|
||
### 错误 1：只改了目录名，没改 slug
|
||
|
||
表现：
|
||
|
||
- 数据目录不对
|
||
- 版本输出不对
|
||
- 日志名不对
|
||
|
||
要检查：
|
||
|
||
- `SKILL.md`
|
||
- `scripts/util/constants.py`
|
||
|
||
### 错误 2：平台中文名改了，内部键没改
|
||
|
||
表现：
|
||
|
||
- 兄弟技能筛选账号失败
|
||
- 发布命令走错平台
|
||
|
||
要检查：
|
||
|
||
- `publish_service.py`
|
||
- `sibling_bridge.py`
|
||
- `references/CLI.md`
|
||
|
||
### 错误 3：把业务逻辑写进 CLI
|
||
|
||
表现：
|
||
|
||
- 文件越来越乱
|
||
- 不方便测
|
||
- 参数和业务耦合太重
|
||
|
||
要改回：
|
||
|
||
- `cli` 只做参数解析
|
||
- `service` 才做业务
|
||
|
||
### 错误 4：保留了旧模板结构
|
||
|
||
表现：
|
||
|
||
- 仓库同时存在 `docs/`、`optional/`、`skill_main.py`
|
||
- 技术人员不知道看哪一套
|
||
|
||
现在的新模板原则是：
|
||
|
||
- 不做旧结构兼容
|
||
- 统一走 `references/` + `scripts/main.py`
|
||
|
||
## 18. 推荐开发顺序总结
|
||
|
||
如果让一个新人照着做，我建议他按这个顺序：
|
||
|
||
1. 复制模板并改目录名
|
||
2. 改 `SKILL.md`
|
||
3. 改 `scripts/util/constants.py`
|
||
4. 改 `references/`
|
||
5. 改 `scripts/cli/app.py`
|
||
6. 改 `scripts/service/`
|
||
7. 跑 `health` / `version`
|
||
8. 再做业务联调
|
||
9. 最后 release
|
||
|
||
## 19. 这份模板的底线要求
|
||
|
||
以后新建 skill，至少要满足这几点：
|
||
|
||
- 目录结构统一
|
||
- 入口统一为 `scripts/main.py`
|
||
- 文档统一放 `references/`
|
||
- 业务核心逻辑统一放 `scripts/service/`
|
||
- 不再使用旧模板历史结构
|
||
|
||
如果做不到这些，后面 skill 一多，就会越来越乱。
|