173 lines
8.4 KiB
Markdown
173 lines
8.4 KiB
Markdown
|
# Easel SKILL 接口规范 v0.3
|
|||
|
|
|
|||
|
|
> 所有 Easel SKILL 遵循此规范。SKILL 是独立可调的原子能力单元。
|
|||
|
|
|
|||
|
|
## 目录结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
skills/
|
|||
|
|
├── openclaw/ 五层 SKILL（发现/策划/制作/发布/归因），由 OpenClaw 直接执行
|
|||
|
|
└── shared/ 跨 SKILL 共享工具（脚本、配置、依赖）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
每个 SKILL 是一个独立目录：
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
skill-xxx/
|
|||
|
|
├── SKILL.md 必须 — 执行流程（精简，< 200 行）
|
|||
|
|
├── references/ 可选 — 领域知识（按需加载，不常驻 prompt）
|
|||
|
|
│ └── *.md
|
|||
|
|
├── scripts/ 可选 — 可执行脚本（运行时调用，代码不进 prompt）
|
|||
|
|
│ └── *.py / *.sh
|
|||
|
|
└── tests/ 可选 — 测试用例
|
|||
|
|
├── test1.prompt 输入
|
|||
|
|
└── test1.expected 期望输出（关键字匹配）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 三层加载机制
|
|||
|
|
|
|||
|
|
| 层 | 内容 | 加载时机 | token 开销 |
|
|||
|
|
|---|---|---|---|
|
|||
|
|
| Metadata | frontmatter（name, description） | 常驻，用于 SKILL 路由 | 极小 |
|
|||
|
|
| Instructions | SKILL.md 主体 | SKILL 被触发时 | 中等 |
|
|||
|
|
| Resources | references/ + scripts/ | SKILL 执行中按需读取 | 按需 |
|
|||
|
|
|
|||
|
|
**核心原则：SKILL.md 只写"怎么做"，领域知识写在 references/ 里。**
|
|||
|
|
|
|||
|
|
### 共享工具层
|
|||
|
|
|
|||
|
|
`skills/shared/` 存放多个 SKILL 共用的工具脚本和配置（如 ffmpeg 封装、API client、通用模板）。SKILL 通过相对路径引用。
|
|||
|
|
|
|||
|
|
## SKILL.md 格式
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
---
|
|||
|
|
name: skill-xxx
|
|||
|
|
description: >-
|
|||
|
|
用中文说明本 SKILL 做什么、用户在什么场景或用哪些说法时应触发，以及与相邻 SKILL 的边界。
|
|||
|
|
layer: discover / plan / produce / publish / attribute / general
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# SKILL 名称
|
|||
|
|
|
|||
|
|
> 一句话描述
|
|||
|
|
|
|||
|
|
## 输入
|
|||
|
|
|
|||
|
|
描述接受什么输入
|
|||
|
|
|
|||
|
|
## 输出
|
|||
|
|
|
|||
|
|
描述输出格式（字段说明，不写具体值）
|
|||
|
|
|
|||
|
|
## 执行步骤
|
|||
|
|
|
|||
|
|
1. 步骤（引用 references/ 下的文件获取领域知识）
|
|||
|
|
2. ...
|
|||
|
|
|
|||
|
|
## Profile 感知
|
|||
|
|
|
|||
|
|
有 Profile 时怎么用，没有时怎么退
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**frontmatter 规则：**
|
|||
|
|
- 只保留 `name`、`description`、`layer` 三个常规字段，减少常驻路由上下文和无效元数据
|
|||
|
|
- `description` 是 Agent 的主要触发依据，必须用中文同时写清能力、触发场景/用户说法和相邻 SKILL 边界；可使用 YAML 块标量
|
|||
|
|
- `layer` 标明所属层：五个流水线层 `discover / plan / produce / publish / attribute`，外加 `general`（跨切面基础设施，如画像管理、产物管理、模板库——不属于任一流水线阶段）
|
|||
|
|
- 仅在 OpenClaw 需要判断操作系统、二进制、环境变量或安装方式时，允许增加 `metadata.openclaw` 运行时清单
|
|||
|
|
- 禁止 `version`、`profile_aware`、`self_developed`、普通 `metadata.trigger/impl/source`、`allowed-tools`、`tags`；来源信息放 `EASEL-META.md`，执行约束和 Profile 行为写正文
|
|||
|
|
- SKILL.md 主体控制在 200 行以内
|
|||
|
|
|
|||
|
|
全库校验：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
python scripts/validate_skills.py
|
|||
|
|
python scripts/validate_skill_commands.py
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
第一条检查 frontmatter、资源链接、输出和发布安全契约；第二条解析 Skill 中的 Python 命令，对照脚本的 argparse 定义检查路径与参数漂移。
|
|||
|
|
|
|||
|
|
## 调用方式
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
easel skill check-compliance -i "内容"
|
|||
|
|
easel skill check-compliance -i "内容" -p 画像名
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
所有调用统一走 OpenClaw agent，由 OpenClaw 读对应 SKILL、按 AGENTS.md 规则自己执行。
|
|||
|
|
|
|||
|
|
## SKILL 同步
|
|||
|
|
|
|||
|
|
`openclaw/sync.sh` 把 `skills/openclaw/` 与 `skills/shared/` 同步到 `~/.openclaw/workspace-easel/`。
|
|||
|
|
|
|||
|
|
## Profile 注入
|
|||
|
|
|
|||
|
|
- OpenClaw 直接读取 Profile 文件夹，按 AGENTS.md 凝练后用于产出。
|
|||
|
|
- 检测标记：`=== EASEL ACCOUNT PROFILE ===`
|
|||
|
|
|
|||
|
|
## 产物管理
|
|||
|
|
|
|||
|
|
**目录布局规约**（一个内容项目 = `outputs/<主题>/` 一个目录）：
|
|||
|
|
```
|
|||
|
|
outputs/<主题>/
|
|||
|
|
├── note.md / final.mp4 / card_1.png 成品（用户要发/读的最终文件，放项目根）
|
|||
|
|
├── assets/ 中间件：frames/ clips/ 构建脚本 原始素材 草稿 重复文件
|
|||
|
|
└── .easel.json 唯一元数据：展示头 + 层间产物契约（隐藏）
|
|||
|
|
```
|
|||
|
|
- **成品放项目根、中间件进 `assets/`**：前端「内容库」据此把成品与素材分区展示。
|
|||
|
|
- 项目名用人类可读主题（中文可），禁泛名（xhs/test）；测试/临时产物写 `outputs/_scratch/`。
|
|||
|
|
- 任何新脚本在创建产物前必须调用 `skills/shared/scripts/output_paths.py` 的 `validate_output_path()`；系统写入需显式传 `allow_system=True`，且只能使用已注册的 `_` 路径。
|
|||
|
|
- 系统状态一律 `_` 前缀目录（`_login/_publish/_analytics/_profile_build/_scratch`）；
|
|||
|
|
**内容库只展示项目目录**，忽略根目录散文件与系统目录。
|
|||
|
|
|
|||
|
|
### 元数据契约（`.easel.json`）
|
|||
|
|
|
|||
|
|
单一元数据文件（隐藏），由 `skills/shared/scripts/manifest.py` 读写（带 selftest），含两部分：
|
|||
|
|
|
|||
|
|
**① 展示头**（供前端「内容库」富展示：标题/平台/状态/封面/标签 + 成品高亮）。收尾登记：
|
|||
|
|
```bash
|
|||
|
|
python skills/shared/scripts/manifest.py meta --topic <主题> \
|
|||
|
|
--title "<人类可读标题>" --platform 小红书 --kind cards --status draft \
|
|||
|
|
--tags "标签1,标签2" --cover cover.png --deliverables card_1.png,card_2.png
|
|||
|
|
```
|
|||
|
|
`kind` 取 `article/xhs-note/video/cards/poster/audio/other`；`status` 取 `draft/ready/published`。
|
|||
|
|
`meta` 为 upsert：只改传入字段、其余保留；缺省有兜底（title→topic、cover→首张成品媒体）。
|
|||
|
|
|
|||
|
|
**② 层间产物契约 steps[]**：纵向编排跨层时，上游产物路径与关键结论通过 manifest 结构化传递，下游无需重新推导。
|
|||
|
|
```bash
|
|||
|
|
# 上游每步产出后登记（失败也登记 --status failed，供断点续跑）
|
|||
|
|
python skills/shared/scripts/manifest.py record --topic <主题> \
|
|||
|
|
--layer plan --skill video-script --profile <画像> \
|
|||
|
|
--outputs script.md,brief.md --summary "3 幕结构，钩子在前 3s"
|
|||
|
|
|
|||
|
|
# 下游步骤前取上游最近一步作为输入
|
|||
|
|
python skills/shared/scripts/manifest.py latest --topic <主题> [--layer plan]
|
|||
|
|
python skills/shared/scripts/manifest.py read --topic <主题> # 看全链路
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Schema：`{topic, profile, created, updated, title, summary, platform, kind, status, tags[], cover, deliverables[], steps:[{layer, skill, at, status, outputs[], upstream[], summary}]}`。
|
|||
|
|
`layer` 取 `discover/plan/produce/publish/attribute/general`；step `status` 取 `done/failed`（默认 done）。契约稳定、可被任一层消费。
|
|||
|
|
|
|||
|
|
> 存量目录用 `scripts/migrate_outputs.py`（dry-run→apply 回填展示头，`--reorganize` 归整中间件进 assets/）收敛；测试残渣用 `scripts/cleanup_outputs.sh` 清理。
|
|||
|
|
|
|||
|
|
## 出站内容安全闸门（发布/评论类 SKILL 契约）
|
|||
|
|
|
|||
|
|
任何把文本**发到公开平台**的脚本（xhs/douyin/web_publisher/xhs_comment/zhihu_answer 等），在真发（`--exec`）前**必须**过 `skills/shared/scripts/content_guard.py` 的 `guard_or_die(...)`。**分两级**（见 `BLOCK_CATEGORIES`）：**BLOCK 级**=真·敏感信息（API key、内部 URL/域名、代理 IP、内部路径、env 名 + `.env` 真值）→ **fail-closed 退出码 7 阻止发布**；**WARN 级**=AI 措辞（由 AI 生成/OpenClaw/Claude/system prompt/大模型）与模型名（claude-*/gpt-image-2）→ 论文解读、AI 科普里可能是正常内容，**只提醒不拦截**。dry-run 全部只告警。放行硬拦须显式 `--allow-unsafe`。新增发布类脚本照此接入。
|
|||
|
|
|
|||
|
|
**有界编排约定**：manifest 只当**薄索引**（`summary` 一行给编排层路由 + `outputs[]` 指路径），**不复制内容**。跨层要传的东西分两类，都落 `outputs/<主题>/` 成文件，不留在对话里：
|
|||
|
|
- **产物（载荷）**：脚本/图/视频/文案 → 写文件，`--outputs` 指过去，下游按路径读全文。
|
|||
|
|
- **决策/意图**（基调、受众、钩子、do/don't 等不体现在产物里的）→ 写进 `outputs/<主题>/brief.md`（策划层的创作简报），同样列入 `--outputs`。
|
|||
|
|
|
|||
|
|
## 测试
|
|||
|
|
|
|||
|
|
SKILL 可带 `tests/` 目录，用低成本模型验证基本功能：
|
|||
|
|
- `test1.prompt` — 测试输入
|
|||
|
|
- `test1.expected` — 期望输出关键字/pattern
|
|||
|
|
|
|||
|
|
## 设计约束
|
|||
|
|
|
|||
|
|
1. **独立可调** — 不依赖其他 SKILL
|
|||
|
|
2. **无 Profile 也能用** — Profile 是加持不是前提
|
|||
|
|
3. **接口一致** — 输出格式稳定，可被下游消费
|
|||
|
|
4. **SKILL.md 精简** — 执行流程在主文件，领域知识放 references/
|
|||
|
|
5. **泛化** — 定义规则和模式，不给具体 case 示例
|