feat: 固化 verb-noun-platform slug 命名规范与语义校验

2026-07-03 10:24:05 +08:00
parent e366605299
commit 7136689efe
16 changed files with 674 additions and 12 deletions
--- a/development/DEVELOPMENT.md
+++ b/development/DEVELOPMENT.md
@@ -79,8 +79,9 @@

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

+0. 按 [`NAMING.md`](NAMING.md) 确定 slug（`{verb}-{noun-phrase}-{platform}`）
 1. 复制这个目录
-2. 改成新 skill 的目录名
+2. 改成新 skill 的目录名（与 slug 一致）
 3. 把占位内容替换掉
 4. 再开始写业务逻辑

@@ -682,6 +683,8 @@ uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-relea
 每个新 skill 发布前，建议技术人员逐条确认：

 - [ ] 目录结构符合当前模板
+- [ ] slug 符合 [`NAMING.md`](NAMING.md)（verb-noun-platform）
+- [ ] 目录名、`SKILL.md` slug、`constants.SKILL_SLUG` 三者一致
 - [ ] `SKILL.md` 中 slug、名称、描述都已替换
 - [ ] `scripts/util/constants.py` 已修改
 - [ ] `../references/CLI.md` 示例命令已改成真实命令
@@ -751,11 +754,46 @@ uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-relea
 - 用户说明在根 `README.md`，Agent 资料在 `references/`，开发规范在 `development/`
 - 统一走 `scripts/main.py` 作为 CLI 入口

+### 错误 5：平台放 slug 最前
+
+表现：
+
+- slug 形如 `amazon-download-settlement-report`
+- 语义校验或 `test_slug_naming` 失败
+
+要改：
+
+- 动词放首段，平台放末段，例如 `download-settlement-report-amazon`
+- 见 [`NAMING.md`](NAMING.md)
+
+### 错误 6：noun 段过长导致超 48 字符
+
+表现：
+
+- slug 超过 48 字符
+- 中间名词段堆砌过多
+
+要改：
+
+- 精简 noun-phrase，保留核心业务含义
+- 见 [`NAMING.md`](NAMING.md) §3 硬约束
+
+### 错误 7：只改目录名未改 slug
+
+表现：
+
+- 与「错误 1」相同，但目录已改名而 `SKILL.md` / `constants.py` 仍为占位
+
+要检查：
+
+- `SKILL.md` 的 `metadata.openclaw.slug`
+- `scripts/util/constants.py` 的 `SKILL_SLUG`
+
 ## 18. 推荐开发顺序总结

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

-1. 复制模板并改目录名
+1. 按 [`NAMING.md`](NAMING.md) 确定 slug，复制模板并改目录名
 2. 改 `SKILL.md` 与根 `README.md`
 3. 改 `scripts/util/constants.py`
 4. 改 `references/` 与 `development/`
--- a/development/NAMING.md
+++ b/development/NAMING.md
@@ -0,0 +1,236 @@
+# 技能 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% 新技能）：
+
+```text
+{verb}-{noun-phrase}-{platform}
+```
+
+| 部分 | 规则 |
+|------|------|
+| **verb** | 1 个词，来自 [动词白名单](#5-动词白名单) |
+| **noun-phrase** | 1～3 个词（按 `-` 分段），描述业务对象 |
+| **platform** | 1 个词，来自 [平台白名单](#6-平台白名单)；可含连字符（如 `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](#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-amazon`
+- `add-product-shopee`
+- `enter-sales-receipt-kingdee`
+- `fill-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-manager`
+- `skill-template`
+- `your-skill-slug` / `your_skill_slug`（模板占位）
+
+---
+
+## 5. 动词白名单
+
+词表文件：[`assets/naming/verbs.txt`](../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`](../assets/naming/platforms.txt)
+
+| 平台 | 平台 | 平台 |
+|------|------|------|
+| amazon | shopee | xinghang |
+| alibaba | kingdee | icbc |
+| pingpong | worldfirst | paypal |
+| lianlian | single-window | export-rebate |
+| etax | | |
+
+scope 词表：[`assets/naming/scopes.txt`](../assets/naming/scopes.txt) — `all`、`batch`、`multi`、`default`
+
+---
+
+## 7. slug 与展示字段分工
+
+```yaml
+---
+name: 亚马逊结算报表下载          # 中文，用户可见
+description: "从卖家中心下载结算报表并入库"  # 中文说明
+metadata:
+  openclaw:
+    slug: download-settlement-report-amazon   # 英文机器标识
+---
+```
+
+同步修改：
+
+- 目录名
+- `metadata.openclaw.slug`
+- `scripts/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. 复制新技能流程
+
+1. **先定 slug** — 按本文规范拟定 `{verb}-{noun-phrase}-{platform}`，确认在白名单内且 ≤ 48 字符
+2. **复制目录** — 将 `skill-template` 复制为新目录，**目录名 = slug**
+3. **全局替换** — `your-skill-slug` → 新 slug；更新 `SKILL.md`、`constants.py`、文档中的占位
+4. **填写 REQUIREMENTS** — 完成 [`REQUIREMENTS.md`](REQUIREMENTS.md) §0 技能标识
+5. **开发 & 自检** — `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.md` slug 与 `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`](DEVELOPMENT.md) | 复制模板步骤、发布前检查清单 |
+| [`REQUIREMENTS.md`](REQUIREMENTS.md) | §0 技能标识必填项 |
+| [`../references/SCHEMA.md`](../references/SCHEMA.md) | kebab-case 与数据库路径 |
+| [`../SKILL.md`](../SKILL.md) | frontmatter 命名摘要 |
--- a/development/README.md
+++ b/development/README.md
@@ -3,12 +3,13 @@
 本目录面向**人类开发者**与 **AI 编程代理**。开始定制 skill 前，建议按以下顺序阅读：

 1. [`REQUIREMENTS.md`](REQUIREMENTS.md) — 需求文档模板与验收标准
-2. [`DEVELOPMENT.md`](DEVELOPMENT.md) — 完整开发步骤与目录规范
-3. [`TESTING.md`](TESTING.md) — 测试分层、隔离数据根与档位开关
-4. [`ADAPTER.md`](ADAPTER.md) — 涉及外部系统对接时
-5. [`RPA.md`](RPA.md) — 涉及浏览器 / 桌面 / 手机自动化时
-6. [`CONFIG.md`](CONFIG.md) — `.env` 规范与 bootstrap 机制
-7. [`RUNTIME.md`](RUNTIME.md) — 共享 runtime、数据路径、发布打包与编码约定
+2. [`NAMING.md`](NAMING.md) — slug / 仓库名命名规范（复制模板前必读）
+3. [`DEVELOPMENT.md`](DEVELOPMENT.md) — 完整开发步骤与目录规范
+4. [`TESTING.md`](TESTING.md) — 测试分层、隔离数据根与档位开关
+5. [`ADAPTER.md`](ADAPTER.md) — 涉及外部系统对接时
+6. [`RPA.md`](RPA.md) — 涉及浏览器 / 桌面 / 手机自动化时
+7. [`CONFIG.md`](CONFIG.md) — `.env` 规范与 bootstrap 机制
+8. [`RUNTIME.md`](RUNTIME.md) — 共享 runtime、数据路径、发布打包与编码约定

 Agent 调用契约见 [`../references/CLI.md`](../references/CLI.md)、[`../references/SCHEMA.md`](../references/SCHEMA.md)。  
 用户市场说明见根目录 [`README.md`](../README.md)，不要写进本目录。
--- a/development/REQUIREMENTS.md
+++ b/development/REQUIREMENTS.md
@@ -15,6 +15,14 @@

 # REQUIREMENTS

+## 0. 技能标识（复制 REQUIREMENTS 时必填）
+
+- 拟定 slug（英文，符合 `development/NAMING.md`）：
+- 中文 name：
+- 中文 description（一句话）：
+- account-manager platform_key（如有）：
+- 命名形态：标准型 / scope 型
+
 ## 1. 文档目标

 说明这份需求文档的作用，以及它解决什么问题。
--- a/development/TESTING.md
+++ b/development/TESTING.md
@@ -32,6 +32,7 @@
 - 标准时间字段：`created_at` / `updated_at` 默认值、trigger 维护与 `datetime_unix_seconds` 元数据（见 `test_timestamp_columns.py`）；
 - **adapter profile**：[`tests/test_adapter_profile_policy.py`](../tests/test_adapter_profile_policy.py) + [`adapter_test_utils`](../tests/adapter_test_utils.py) ——验证在未授权情况下绝不误判开启真实网络/RPA。
 - **发布打包守护**：[`tests/test_release_packaging_constraints.py`](../tests/test_release_packaging_constraints.py) ——`scripts/**/*.py` 单文件 < 1000 行、文本文件 UTF-8 without BOM。
+- **slug 语义**：[`tests/test_slug_naming.py`](../tests/test_slug_naming.py) ——verb-noun-platform 命名规范校验。

 **原则：`tests/test_*.py` 不允许隐形访问外网、不允许拉起真实浏览器、不允许读写开发者机器的真实数据根**。如果需要仿真服务器，也应仅在 integration（并由档位变量放行）。