7.7 KiB
技能 slug 命名规范（verb-noun-platform）
本文是匠厂新业务 skill 的 slug / Git 仓库名 / 目录名命名权威说明。复制
skill-template出去开发新技能前必读；Agent 在开发者询问命名或 slug 时也应先读本文。
1. 适用范围
| 范围 | 说明 |
|---|---|
| ✅ 适用 | 从 skill-template 复制出去的新技能 |
| ❌ 不追溯 | 已上线历史技能（如 account-manager、reconcile-finance、scrape-contacts-lianjia 等）保持不动 |
| ❌ 不修改 | 其他仓库（尤其 account-manager）不在本文约束范围内 |
| ✅ 模板占位 | 模板本体的 your-skill-slug 占位必须继续通过全部测试 |
新技能勿仿历史 2 段无平台形态（如 reconcile-finance）或不符合 verb-noun-platform 的旧 repo 名；校验器对历史 repo 不追溯，但规范中明确标注为反模式。
2. 命名格式
标准形态（约 95% 新技能）：
{verb}-{noun-phrase}-{platform}
| 部分 | 规则 |
|---|---|
| verb | 1 个词，来自 动词白名单 |
| noun-phrase | 1～3 个词（按 - 分段），描述业务对象 |
| platform | 1 个词，来自 平台白名单；可含连字符（如 single-window） |
展示层分工不变：
| 字段 | 语言 | 示例 |
|---|---|---|
slug / repo / 目录 / SKILL_SLUG / DB 文件名 |
英文 kebab-case | download-settlement-report-amazon |
SKILL.md 的 name、description、根 README.md |
中文 | 亚马逊结算报表下载 |
3. 硬约束（新技能强制校验）
| 约束 | 值 |
|---|---|
| 格式 | {verb}-{noun-phrase}-{platform}（标准型，默认） |
总段数（按 - 分割） |
3～5 段（标准型）；scope 型见 §4 |
| 总长度 | ≤ 48 字符 |
| 字符集 | 小写字母、数字、连字符；kebab-case |
| 禁止 | 中文 slug、下划线、平台放最前（如 amazon-download-xxx） |
实现校验见 scripts/util/slug_naming.py；scripts/db/display_metadata_validator.py 在 SKILL.md frontmatter 自检时调用。
4. 三类合法形态
4.1 标准型（95%）
verb-noun-platform 或 verb-noun-noun-platform（3～5 段）
- 第 1 段 ∈ 动词白名单
- 最后 1 段（或 hyphenated 平台的最后 2 段）∈ 平台白名单
- 中间为 noun-phrase（1～3 段）
示例：
download-settlement-report-amazonadd-product-shopeeenter-sales-receipt-kingdeefill-export-declaration-single-window
4.2 scope 型（少见）
verb-noun-scope
- 最后 1 段 ∈ scope 白名单：
all|batch|multi|default - 第 1 段 ∈ 动词白名单
- 总段数 3～5
示例：generate-article-all
说明：
geo-generate-article-all若作为新技能且不在豁免表、首段geo不在动词表，应写为generate-article-all。
4.3 历史豁免（不校验语义）
以下 slug 跳过 verb/platform 语义校验（见 LEGACY_EXEMPT_SLUGS）：
account-managerskill-templateyour-skill-slug/your_skill_slug（模板占位）
5. 动词白名单
词表文件：assets/naming/verbs.txt（每行一词，便于后续扩展）
| 动词 | 动词 | 动词 | 动词 |
|---|---|---|---|
| scrape | receive | download | export |
| add | fill | enter | bind |
| withdraw | reconcile | verify | submit |
| query | process | reply | generate |
| draft | review | confirm | track |
| upload | match | triage | ship |
| reprice |
6. 平台白名单
词表文件：assets/naming/platforms.txt
| 平台 | 平台 | 平台 |
|---|---|---|
| amazon | shopee | xinghang |
| alibaba | kingdee | icbc |
| pingpong | worldfirst | paypal |
| lianlian | single-window | export-rebate |
| etax |
scope 词表：assets/naming/scopes.txt — all、batch、multi、default
7. slug 与展示字段分工
---
name: 亚马逊结算报表下载 # 中文，用户可见
description: "从卖家中心下载结算报表并入库" # 中文说明
metadata:
openclaw:
slug: download-settlement-report-amazon # 英文机器标识
---
同步修改：
- 目录名
metadata.openclaw.slugscripts/util/constants.py中的SKILL_SLUG- 默认数据库路径
{slug}/{slug}.db
三者必须一致。
8. 与 account-manager 的关系
slug 末段 platform 与 account-manager 中的 platform_key 语义对应，但不要求字符串完全相等。
| slug 末段 (platform) | account-manager platform_key（示例） |
|---|---|
| amazon | amazon_sim / amazon |
| shopee | shopee |
| kingdee | kingdee |
新技能若需账号下发，在 REQUIREMENTS.md §0 填写拟用的 platform_key，并与兄弟技能调用参数对齐。
9. 复制新技能流程
- 先定 slug — 按本文规范拟定
{verb}-{noun-phrase}-{platform}，确认在白名单内且 ≤ 48 字符 - 复制目录 — 将
skill-template复制为新目录，目录名 = slug - 全局替换 —
your-skill-slug→ 新 slug；更新SKILL.md、constants.py、文档中的占位 - 填写 REQUIREMENTS — 完成
REQUIREMENTS.md§0 技能标识 - 开发 & 自检 —
python tests/run_tests.py -v，含 slug 语义测试
10. 正例 / 反例
✅ 正例
| slug | 说明 |
|---|---|
download-settlement-report-amazon |
标准型，4 段 |
add-product-shopee |
标准型，3 段 |
enter-sales-receipt-kingdee |
标准型 |
fill-export-declaration-single-window |
标准型，平台含连字符 |
generate-article-all |
scope 型 |
❌ 反例
| slug | 原因 |
|---|---|
amazon-download-settlement-report |
平台在最前 |
enter-cross-border-sales-receipt-voucher-kingdee |
过长、noun 臃肿 |
reconcile-finance |
新技能禁止 2 段无平台 |
download_settlement_amazon |
非 kebab-case（下划线） |
11. 反模式
- 平台前置：
amazon-download-...、shopee-add-... - 英文占位 name：复制后仍保留
My Skill或纯英文 slug 风格名称 - 只改目录名：
SKILL.mdslug 与constants.SKILL_SLUG未同步 - noun 堆砌：中间段过多导致超 48 字符或难以阅读
- 仿历史 2 段 repo：
reconcile-finance、content-manager等
12. 演进说明（当前不启用）
当技能库规模 > 200 时，可再评估引入 {domain}-verb-noun-platform 前缀形态。当前不启用，新技能一律使用本文 verb-noun-platform 标准型或 scope 型。
13. 历史形态说明
以下为代表性历史 repo，新技能勿仿：
| 历史 slug | 说明 |
|---|---|
account-manager |
跨平台账号管理，非 verb-noun-platform |
reconcile-finance |
2 段无 platform |
scrape-contacts-lianjia |
平台名不在当前白名单（链家） |
skill-template |
模板仓库本身 |
校验器通过 LEGACY_EXEMPT_SLUGS 对模板占位与少数豁免 slug 跳过语义检查；新复制出去的业务 skill 不在豁免表内，必须满足 §3 硬约束。
14. 相关文档
| 文档 | 内容 |
|---|---|
DEVELOPMENT.md |
复制模板步骤、发布前检查清单 |
REQUIREMENTS.md |
§0 技能标识必填项 |
../references/SCHEMA.md |
kebab-case 与数据库路径 |
../SKILL.md |
frontmatter 命名摘要 |