Release v1.0.113: document default_sort may use hidden columns

CHANGELOG.md

@@ -9,6 +9,16 @@
 - 小节正文写用户能看懂的变化（新能力、修复、注意事项），避免堆砌内部实现细节
 - 打 tag 前**必须**为即将发布的版本新增一节；找不到匹配小节时，本次发布不会更新 changelog 字段
 
+## 1.0.113
+
+- 固化数据管理契约：`visible=0` 只藏界面；`default_sort_json` 仍可引用隐藏的非敏感物理列（含主键）
+- 元数据校验：排序列必须真实存在；引用隐藏列仅提示、不报错
+
+## 1.0.112
+
+- 新技能的名字不必再以平台或 `default` 结尾。没有抖音、小红书、亚马逊这类外部平台时，用动词加名词即可
+- 不要再把 `default` 当作占位平台。已经发布、名字末尾是 `default` 的技能不用改名
+
 ## 1.0.111
 
 - 沉淀数据管理呈现加法：同一 `cellPresentation.enabled` 支持单元格、整行、整列、行列交叉区域（闭集 tone）

SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: 技能开发模板（通用业务版）
 description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。"
-version: 1.0.111
+version: 1.0.113
 author: 深圳匠厂科技有限公司
 metadata:
   openclaw:
@@ -159,7 +159,7 @@ python {baseDir}/scripts/main.py init-db
 
 ## 技能命名与 slug
 
-- 标准格式：`{verb}-{noun-phrase}-{platform}`（详见 `development/NAMING.md`）。
+- 标准格式：`{verb}-{noun-phrase}`，绑定外部平台时才加 `-{platform}`（详见 `development/NAMING.md`）。不要用 `default` 占位。
 - slug / repo / 目录 / `SKILL_SLUG` / DB 文件名：**英文** kebab-case；`name`、`description`、根 `README.md`：**中文**。
 - 复制为新业务技能前**必须**阅读 `development/NAMING.md`。
 - `name`（frontmatter）：**用户可见的中文业务名称**；`description` 是说明，不是名称。

assets/naming/scopes.txt

@@ -1,4 +1,3 @@
 all
 batch
 multi
-default

development/DEVELOPMENT.md

@@ -925,7 +925,7 @@ uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-relea
 每个新 skill 发布前，建议技术人员逐条确认：
 
 - [ ] 目录结构符合当前模板
-- [ ] slug 符合 [`NAMING.md`](NAMING.md)（verb-noun-platform）
+- [ ] slug 符合 [`NAMING.md`](NAMING.md)（动词-名词，平台可选；不要用 `default` 占位）
 - [ ] 目录名、`SKILL.md` slug、`constants.SKILL_SLUG` 三者一致
 - [ ] `SKILL.md` 中 slug、名称、描述都已替换
 - [ ] `SKILL.md` 的 `developer_ids` 已换成**本人**匠厂用户 ID（设置 → 用户信息 → 复制），不是模板示例 ID

development/NAMING.md

@@ -13,23 +13,24 @@
 | ❌ **不修改** | 其他仓库（尤其 `account-manager`）不在本文约束范围内 |
 | ✅ **模板占位** | 模板本体的 `your-skill-slug` 占位必须继续通过全部测试 |
 
-**新技能勿仿**历史 2 段无平台形态（如 `reconcile-finance`）或不符合 verb-noun-platform 的旧 repo 名；校验器对历史 repo **不追溯**，但规范中明确标注为反模式。
+**新技能**使用「动词-名词」，外部平台可选。不要再为了凑段数追加 `default`。校验器不追溯已上线仓库；已经发布、末尾是 `default` 的技能不用改名。
 
 ---
 
 ## 2. 命名格式
 
-标准形态（约 95% 新技能）：
+标准形态：
 
 ```text
-{verb}-{noun-phrase}-{platform}
+{verb}-{noun-phrase}
+{verb}-{noun-phrase}-{platform}    # 仅当技能绑定外部平台时
 ```
 
 | 部分 | 规则 |
 |------|------|
 | **verb** | 1 个词，来自 [动词白名单](#5-动词白名单) |
 | **noun-phrase** | 1～3 个词（按 `-` 分段），描述业务对象 |
-| **platform** | 1 个词，来自 [平台白名单](#6-平台白名单)；可含连字符（如 `single-window`） |
+| **platform** | **可选**。没有抖音、小红书、亚马逊这类外部系统时省略。有平台时 1 个词，来自 [平台白名单](#6-平台白名单)；可含连字符（如 `single-window`） |
 
 **展示层分工不变：**
 
@@ -44,8 +45,8 @@
 
 | 约束 | 值 |
 |------|-----|
-| 格式 | `{verb}-{noun-phrase}-{platform}`（标准型，默认） |
-| 总段数（按 `-` 分割） | **3～5 段**（标准型）；scope 型见 [§4](#4-三类合法形态) |
+| 格式 | `{verb}-{noun-phrase}`；有外部平台时才加 `-{platform}` |
+| 总段数（按 `-` 分割） | **2～5 段** |
 | 总长度 | **≤ 48 字符** |
 | 字符集 | 小写字母、数字、连字符；kebab-case |
 | 禁止 | 中文 slug、下划线、**平台放最前**（如 `amazon-download-xxx`） |
@@ -56,12 +57,26 @@
 
 ## 4. 三类合法形态
 
-### 4.1 标准型（95%）
+### 4.1 无平台（常见）
 
-`verb-noun-platform` 或 `verb-noun-noun-platform`（3～5 段）
+`verb-noun` 或 `verb-noun-noun`（2～4 段）
 
 - 第 1 段 ∈ 动词白名单
-- 最后 1 段（或 hyphenated 平台的最后 2 段）∈ 平台白名单
+- 其余为 noun-phrase（1～3 段）
+- **不要**追加 `default`
+
+示例：
+
+- `generate-monthly-statements`
+- `reconcile-finance`
+- `process-article`
+
+### 4.2 标准型（绑定外部平台）
+
+`verb-noun-platform`（在无平台形态后加平台，总段数仍 ≤ 5）
+
+- 第 1 段 ∈ 动词白名单
+- 最后 1 段（或 hyphenated 平台的最后若干段）∈ 平台白名单
 - 中间为 noun-phrase（1～3 段）
 
 示例：
@@ -71,19 +86,19 @@
 - `enter-sales-receipt-kingdee`
 - `fill-export-declaration-single-window`
 
-### 4.2 scope 型（少见）
+### 4.3 scope 型（少见）
 
 `verb-noun-scope`
 
-- 最后 1 段 ∈ scope 白名单：`all` | `batch` | `multi` | `default`
+- 最后 1 段 ∈ scope 白名单：`all` | `batch` | `multi`
 - 第 1 段 ∈ 动词白名单
-- 总段数 3～5
+- 至少还有一段名词（因此最少 3 段）
 
 示例：`generate-article-all`
 
-> 说明：`geo-generate-article-all` 若作为新技能且不在豁免表、首段 `geo` 不在动词表，应写为 `generate-article-all`。
+> `default` 已从 scope 词表移除。它不是平台，也不表示范围。新技能不要写 `generate-article-default` 这类占位。已发布且末尾为 `default` 的仓库保持原 slug；同步本校验后只会警告，不会因此失败。
 
-### 4.3 历史豁免（不校验语义）
+### 4.4 历史豁免（不校验语义）
 
 以下 slug 跳过 verb/platform 语义校验（见 `LEGACY_EXEMPT_SLUGS`）：
 
@@ -121,7 +136,7 @@
 | lianlian | single-window | export-rebate |
 | etax | | |
 
-scope 词表：[`assets/naming/scopes.txt`](../assets/naming/scopes.txt) — `all`、`batch`、`multi`、`default`
+scope 词表：[`assets/naming/scopes.txt`](../assets/naming/scopes.txt) — `all`、`batch`、`multi`。不含 `default`。
 
 ---
 
@@ -164,7 +179,7 @@ slug **末段 platform** 与 `account-manager` 中的 `platform_key` **语义对
 
 ## 9. 复制新技能流程
 
-1. **先定 slug** — 按本文规范拟定 `{verb}-{noun-phrase}-{platform}`，确认在白名单内且 ≤ 48 字符
+1. **先定 slug** — `{verb}-{noun-phrase}`，仅在绑定外部平台时加 `-{platform}`。确认动词/平台在白名单内且 ≤ 48 字符。不要用 `default` 占位。
 2. **复制目录** — **推荐** [`tools/scaffold_skill.ps1`](../tools/scaffold_skill.ps1)（`-Slug` 与目录名一致）；勿整包复制带走 `.git`
 2.5. **清理 Git（若未用 scaffold）** — 删除 `.git`、`.openclaw-skill-template`、`.pytest_cache`；再 `git init` 与 `git remote add origin`
 3. **全局替换** — `your-skill-slug` → 新 slug；更新 `SKILL.md`、`constants.py`、文档中的占位
@@ -179,10 +194,12 @@ slug **末段 platform** 与 `account-manager` 中的 `platform_key` **语义对
 
 | slug | 说明 |
 |------|------|
-| `download-settlement-report-amazon` | 标准型，4 段 |
-| `add-product-shopee` | 标准型，3 段 |
-| `enter-sales-receipt-kingdee` | 标准型 |
-| `fill-export-declaration-single-window` | 标准型，平台含连字符 |
+| `generate-monthly-statements` | 无平台 |
+| `reconcile-finance` | 无平台，动词 + 一个名词 |
+| `download-settlement-report-amazon` | 有平台 |
+| `add-product-shopee` | 有平台 |
+| `enter-sales-receipt-kingdee` | 有平台 |
+| `fill-export-declaration-single-window` | 有平台，平台含连字符 |
 | `generate-article-all` | scope 型 |
 
 ### ❌ 反例
@@ -191,7 +208,7 @@ slug **末段 platform** 与 `account-manager` 中的 `platform_key` **语义对
 |------|------|
 | `amazon-download-settlement-report` | 平台在最前 |
 | `enter-cross-border-sales-receipt-voucher-kingdee` | 过长、noun 臃肿 |
-| `reconcile-finance` | 新技能禁止 2 段无平台 |
+| `generate-article-default` | `default` 不是平台；应写成 `generate-article` |
 | `download_settlement_amazon` | 非 kebab-case（下划线） |
 
 ---
@@ -201,14 +218,14 @@ slug **末段 platform** 与 `account-manager` 中的 `platform_key` **语义对
 - **平台前置**：`amazon-download-...`、`shopee-add-...`
 - **英文占位 name**：复制后仍保留 `My Skill` 或纯英文 slug 风格名称
 - **只改目录名**：`SKILL.md` slug 与 `constants.SKILL_SLUG` 未同步
-- **noun 堆砌**：中间段过多导致超 48 字符或难以阅读
-- **仿历史 2 段 repo**：`reconcile-finance`、`content-manager` 等
+- **用 default 占位**：`generate-article-default`。没有外部平台就省略末段
+- **名词堆砌**：中间段过多导致超 48 字符或难以阅读
 
 ---
 
 ## 12. 演进说明（当前不启用）
 
-当技能库规模 **> 200** 时，可再评估引入 `{domain}-verb-noun-platform` 前缀形态。**当前不启用**，新技能一律使用本文 verb-noun-platform 标准型或 scope 型。
+当技能库规模 **> 200** 时，可再评估引入 `{domain}-verb-noun-platform` 前缀形态。**当前不启用**。新技能使用动词-名词；只有绑定外部平台时才使用 verb-noun-platform，或使用 scope 型。
 
 ---
 
@@ -218,9 +235,9 @@ slug **末段 platform** 与 `account-manager` 中的 `platform_key` **语义对
 
 | 历史 slug | 说明 |
 |-----------|------|
-| `account-manager` | 跨平台账号管理，非 verb-noun-platform |
-| `reconcile-finance` | 2 段无 platform |
-| `scrape-contacts-lianjia` | 平台名不在当前白名单（链家） |
+| `account-manager` | 跨平台账号管理，非动词-名词 |
+| `reconcile-finance` | 现已是合法的无平台形态；旧文档曾把它标成反例 |
+| `scrape-contacts-lianjia` | 平台名不在当前白名单（链家）；新技能若要表达链家，先把平台加入白名单 |
 | `skill-template` | 模板仓库本身 |
 
 校验器通过 `LEGACY_EXEMPT_SLUGS` 对模板占位与少数豁免 slug 跳过语义检查；**新复制出去的业务 skill 不在豁免表内**，必须满足 §3 硬约束。

development/POLICY_MATRIX.md

@@ -60,7 +60,7 @@
 | 是否满足完整快照语义 / 空结果保护实现 | references/SCHEMA.md | 见 `test_sync_contract.py.sample` |
 | 是否把系统导出与业务同步混淆 | references/ACTIONS.md；SCHEMA.md | 文档 + sample；勿做源码关键词误报扫描 |
 | `db/` 层不得调浏览器或拼业务流程 | development/DEVELOPMENT.md §11 | 需跨文件调用图 |
-| slug 命名语义（verb-noun-platform） | development/NAMING.md | 部分覆盖于 `tests/test_slug_naming.py`，非本矩阵 hard policy |
+| slug 命名语义（动词-名词，平台可选） | development/NAMING.md | 部分覆盖于 `tests/test_slug_naming.py`，非本矩阵 hard policy |
 | 复制模板不得保留 `.git` / template marker | development/DEVELOPMENT.md §4 | 由 `tests/test_scaffold_guard.py` 守护，属脚手架场景 |
 | 共享 runtime 导入来源非技能目录 | development/RUNTIME.md | 运行时依赖已安装包，见 `tests/test_platform_import.py` |
 | RPA 真实轨迹、选择器纪律、状态等待、HITL 超时与有限重试是否正确实现 | development/AI_RPA.md；development/RPA.md §0–§1 | 文档和默认节奏已守护，真实行为与 DOM 质量仍需人工验收 |

development/TESTING.md

@@ -34,7 +34,7 @@
 - **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。
 - **开发规范守护（hard policy）**：[`tests/test_development_policy_guard.py`](../tests/test_development_policy_guard.py) ——规则索引见 [`development/POLICY_MATRIX.md`](POLICY_MATRIX.md)，只执行可机器检测的 hard 规则。
-- **slug 语义**：[`tests/test_slug_naming.py`](../tests/test_slug_naming.py) ——verb-noun-platform 命名规范校验。
+- **slug 语义**：[`tests/test_slug_naming.py`](../tests/test_slug_naming.py) ——动词-名词命名；平台可选，`default` 不再作为占位。
 - **HTML 报告壳**：[`tests/test_html_page_service.py`](../tests/test_html_page_service.py) 守护 `assets/html/example-report.html` 的数据管理 iframe 预览布局基线，并守护 ACTIONS.md 里的壳子页目录 `assets/html/pages` 与 `jiangchang.call`。业务技能若有自定义 `assets/html/*.html` 或 `pages/*.html`，建议在自有仓库加同类静态断言（见 `references/ACTIONS.md`「宿主预览布局」）。不要把 `example-report.html` 放进 `pages/`。
 
 **原则：`tests/test_*.py` 不允许隐形访问外网、不允许拉起真实浏览器、不允许读写开发者机器的真实数据根**。如果需要仿真服务器，也应仅在 integration（并由档位变量放行）。

references/ACTIONS.md

@@ -776,6 +776,7 @@ HINT: <next step>
 - 依赖或宣传表顶栏「更多操作」溢出菜单（宿主已取消该能力）。
 - 把「表格行数据默认排序」与按钮顺序混淆——行排序见 [`SCHEMA.md`](SCHEMA.md) 的 `default_sort_json`。
 - 把「默认展示列」与 `visible=0` 硬隐藏混淆——默认展示列见 [`SCHEMA.md`](SCHEMA.md) 的 `default_visible_columns_json`。
+- 误以为 `visible=0` 的列不能出现在 `default_sort_json`——隐藏只影响展示/筛选/搜索；ORDER BY 仍可用非敏感物理列（含隐藏主键）。
 - 新增 `row-context-menu` 等 placement，或要求技能再维护一份与 `row` 平行的菜单清单。
 
 ### Action 类型 × placements（常见示例，不是限制）

references/SCHEMA.md

@@ -180,11 +180,36 @@ JSON 数组（可多字段，按顺序）：
 
 规则：
 
-- `column` 必须是该表真实列名；敏感列会被宿主忽略
+- `column` 必须是该表**真实物理列名**（存在于 SQLite 表）；不存在则宿主忽略该段或技能校验报错
+- **可以**引用 `visible=0` 的列（含隐藏的主键 `id`）。`visible=0` 只表示界面不展示 / 不进默认 SELECT·筛选·搜索；**不表示不能 ORDER BY**
+- 敏感列（宿主标为 sensitive）不得用于排序；技能侧勿把密钥类字段写进 `default_sort_json`
 - `direction` 仅 `asc` / `desc`（缺省按 `desc`）
 - 用户在 UI 上手动改排序后，以用户选择为准；声明只影响未选择时的默认
 - 通过 `upsert_table_metadata(..., default_sort_json=...)` 写入；旧库由 `init_display_metadata_tables` 幂等 `ALTER` 补列
 
+与 `visible` 的分工（勿再踩坑）：
+
+| 能力 | `visible=0` 是否仍可用 |
+|------|------------------------|
+| 表格列展示 / 「列」面板 | 否（硬隐藏） |
+| 默认 SELECT、列筛选、顶栏搜索 | 否 |
+| **`default_sort_json` / ORDER BY** | **是**（非敏感列） |
+| 行主键定位（`$row.$pk` 等） | 是（主键即使隐藏仍应可排序、可定位；宿主查询层保留） |
+
+示例（编号硬隐藏，但仍按编号排序——合法）：
+
+```python
+upsert_table_metadata(
+    cursor,
+    table_name="period_rule_overrides",
+    display_name="本月默认金额",
+    readonly=1,
+    default_sort_json='[{"column":"period","direction":"desc"},{"column":"id","direction":"asc"}]',
+)
+# id 列元数据可见性：
+# upsert_column_metadata(..., column_name="id", visible=0, ...)
+```
+
 示例（消息时间线）：
 
 ```python
@@ -277,6 +302,8 @@ upsert_column_metadata(
 - 只写英文物理名而不写中文 `display_name`
 - 让元数据引用不存在的表
 - 用 `visible=0` 假装「默认不展示但用户还能勾出来」（那是硬隐藏，勾不回来）
+- 误以为「列 `visible=0` 就不能写进 `default_sort_json`」——排序与展示已拆开；隐藏编号/主键仍可排序（须列真实存在且非敏感）
+- 把不存在的列名写进 `default_sort_json`（技能校验应报错；宿主也会忽略无效段）
 
 ### `_jiangchang_columns` 字段级标准
 

scripts/db/display_metadata.py

@@ -103,6 +103,7 @@ def upsert_table_metadata(
     default_sort_json: 宿主数据管理默认排序，JSON 数组，例如
     '[{"column":"sent_at","direction":"desc"},{"column":"id","direction":"desc"}]'
     为空则宿主回退到 updated_at → created_at → 主键。
+    排序列须为真实物理列；**允许**引用 visible=0 的非敏感列（隐藏≠不能 ORDER BY）。
 
     default_visible_columns_json: 宿主数据管理默认展示列，JSON 字符串数组，例如
     '["stat_type","period","stage"]'

scripts/db/display_metadata_validator.py

@@ -279,6 +279,95 @@ def validate_filter_search_metadata(
     return [], warnings
 
 
+def parse_default_sort_json(raw: object) -> tuple[list[dict[str, str]], list[str]]:
+    """解析 default_sort_json；返回 (specs, errors)。specs 项含 column / direction。"""
+    errors: list[str] = []
+    if raw is None or str(raw).strip() == "":
+        return [], []
+    text = str(raw).strip()
+    try:
+        parsed = json.loads(text)
+    except json.JSONDecodeError:
+        return [], ["default_sort_json 不是合法 JSON"]
+    if not isinstance(parsed, list):
+        return [], ["default_sort_json 必须是 JSON 数组"]
+    out: list[dict[str, str]] = []
+    for index, item in enumerate(parsed):
+        if not isinstance(item, dict):
+            errors.append(f"default_sort_json[{index}] 必须是对象")
+            continue
+        column = str(
+            item.get("column")
+            or item.get("columnName")
+            or item.get("column_name")
+            or ""
+        ).strip()
+        direction_raw = str(item.get("direction") or "desc").strip().lower()
+        if not column:
+            errors.append(f"default_sort_json[{index}] 缺少 column")
+            continue
+        if direction_raw not in {"asc", "desc"}:
+            errors.append(f"default_sort_json[{index}].direction 只能是 asc 或 desc")
+            continue
+        out.append({"column": column, "direction": direction_raw})
+    return out, errors
+
+
+def validate_default_sort_metadata(
+    cursor,
+    table_name: str,
+    *,
+    physical_columns: list[str] | None = None,
+) -> tuple[list[str], list[str]]:
+    """校验表级 default_sort_json：列须真实存在；允许 visible=0；不存在则报错。
+
+    契约：visible=0 只藏界面，ORDER BY 仍可用非敏感物理列（含隐藏主键）。
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+    table_cols = {
+        str(row[1]) for row in cursor.execute("PRAGMA table_info(_jiangchang_tables)").fetchall()
+    }
+    if "default_sort_json" not in table_cols:
+        return [], []
+    cursor.execute(
+        "SELECT default_sort_json FROM _jiangchang_tables WHERE table_name = ?",
+        (table_name,),
+    )
+    row = cursor.fetchone()
+    if not row:
+        return [], []
+    specs, parse_errors = parse_default_sort_json(row[0])
+    for msg in parse_errors:
+        errors.append(f"{table_name}: {msg}")
+    if parse_errors:
+        return errors, warnings
+
+    physical = set(physical_columns or list_physical_column_names(cursor, table_name))
+    for spec in specs:
+        column = spec["column"]
+        if column not in physical:
+            errors.append(
+                f"{table_name}: default_sort_json 引用了不存在的列 {column!r}"
+            )
+            continue
+        # visible=0 合法：不报错。仅提示契约，避免作者误删排序列。
+        cursor.execute(
+            """
+            SELECT visible FROM _jiangchang_columns
+            WHERE table_name = ? AND column_name = ?
+            """,
+            (table_name, column),
+        )
+        meta = cursor.fetchone()
+        if meta is not None and meta[0] is not None and int(meta[0]) == 0:
+            warnings.append(
+                f"{table_name}.{column}: default_sort_json 引用了 visible=0 列"
+                "（合法：隐藏列仍可 ORDER BY；见 references/SCHEMA.md）"
+            )
+    return errors, warnings
+
+
 def validate_column_permissions(
     cursor,
     table_name: str,
@@ -558,6 +647,14 @@ def validate_display_metadata(conn: sqlite3.Connection, *, check_column_order: b
         _, filter_warnings = validate_filter_search_metadata(cur, table_name)
         report.warnings.extend(filter_warnings)
 
+        sort_errors, sort_warnings = validate_default_sort_metadata(
+            cur,
+            table_name,
+            physical_columns=physical_columns,
+        )
+        report.errors.extend(sort_errors)
+        report.warnings.extend(sort_warnings)
+
     cur.execute("SELECT table_name, column_name FROM _jiangchang_columns")
     for table_name, column_name in cur.fetchall():
         if table_name in METADATA_TABLES:

scripts/util/constants.py

@@ -1,6 +1,6 @@
 """技能标识、版本与平台公共库约束（复制后请修改 slug/version/logger）。"""
 
 SKILL_SLUG = "your-skill-slug"
-SKILL_VERSION = "1.0.111"
+SKILL_VERSION = "1.0.113"
 LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug"
 PLATFORM_KIT_MIN_VERSION = "1.2.11"

scripts/util/slug_naming.py

@@ -7,7 +7,7 @@ import re
 
 _KEBAB_SLUG = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
 _MAX_SLUG_LENGTH = 48
-_MIN_SEGMENTS = 3
+_MIN_SEGMENTS = 2
 _MAX_SEGMENTS = 5
 _MAX_NOUN_SEGMENTS = 3
 
@@ -60,7 +60,9 @@ _BUILTIN_PLATFORMS = frozenset(
         "etax",
     }
 )
-_BUILTIN_SCOPES = frozenset({"all", "batch", "multi", "default"})
+_BUILTIN_SCOPES = frozenset({"all", "batch", "multi"})
+# 旧技能用 default 占位末段。不再当成合法 scope；校验只警告，避免同步后挡住已发布仓库。
+_DEPRECATED_PLATFORM_PLACEHOLDER = "default"
 
 LEGACY_EXEMPT_SLUGS: frozenset[str] = frozenset(
     {
@@ -117,11 +119,12 @@ def _match_platform_suffix(
 
 def classify_slug_form(segments: list[str], *, slug: str = "") -> str:
     """
-    返回: 'legacy_exempt' | 'standard' | 'scope' | 'invalid'
+    返回: 'legacy_exempt' | 'standard' | 'scope' | 'plain' | 'invalid'
 
     - legacy_exempt: slug in LEGACY_EXEMPT_SLUGS
-    - standard: 末段匹配 platforms, 首段 in verbs, 3<=len<=5
-    - scope: 末段 in scopes, 首段 in verbs, 3<=len<=5
+    - standard: 末段匹配 platforms，首段 in verbs，2<=len<=5，且动词后至少还有一段名词
+    - scope: 末段 in scopes（all/batch/multi），首段 in verbs，至少 verb-noun-scope
+    - plain: 动词 + 名词，无平台、无 scope
     - invalid: 其他
     """
     if slug in LEGACY_EXEMPT_SLUGS:
@@ -138,12 +141,14 @@ def classify_slug_form(segments: list[str], *, slug: str = "") -> str:
         return "invalid"
 
     if segments[-1] in scopes:
+        if len(segments) < 3:
+            return "invalid"
         return "scope"
 
     if _match_platform_suffix(segments, platforms) is not None:
         return "standard"
 
-    return "invalid"
+    return "plain"
 
 
 def validate_slug_semantics(
@@ -173,8 +178,8 @@ def validate_slug_semantics(
 
     if segment_count < _MIN_SEGMENTS:
         msg = (
-            f"slug 段数应为 {_MIN_SEGMENTS}～{_MAX_SEGMENTS}（verb-noun-platform），"
-            f"当前为 {segment_count} 段：{slug!r}；新技能禁止 2 段无平台形态（如 reconcile-finance）"
+            f"slug 段数应为 {_MIN_SEGMENTS}～{_MAX_SEGMENTS}（动词-名词，平台可选），"
+            f"当前为 {segment_count} 段：{slug!r}"
         )
         (errors if strict else warnings).append(msg)
         return errors, warnings
@@ -197,9 +202,6 @@ def validate_slug_semantics(
 
     form = classify_slug_form(segments, slug=slug)
     if form == "scope":
-        if segments[-1] not in scopes:
-            msg = f"slug 末段应为 scope 白名单中的词：{segments[-1]!r}（slug={slug!r}）"
-            (errors if strict else warnings).append(msg)
         noun_count = segment_count - 2
     elif form == "standard":
         platform_match = _match_platform_suffix(segments, platforms)
@@ -210,13 +212,17 @@ def validate_slug_semantics(
         else:
             _platform_name, platform_part_count = platform_match
             noun_count = segment_count - 1 - platform_part_count
+    elif form == "plain":
+        noun_count = segment_count - 1
+        if segments[-1] == _DEPRECATED_PLATFORM_PLACEHOLDER:
+            warnings.append(
+                "slug 末段 default 已不再作为平台占位；没有外部平台时直接省略。"
+                f"已发布的技能不用改名：{slug!r}"
+            )
     else:
-        if segment_count >= _MIN_SEGMENTS:
-            if segments[-1] not in scopes:
-                platform_match = _match_platform_suffix(segments, platforms)
-                if platform_match is None:
-                    msg = f"slug 末段应匹配平台或 scope 白名单：{slug!r}"
-                    (errors if strict else warnings).append(msg)
+        if segments and segments[-1] in scopes and segment_count < 3:
+            msg = f"scope 型 slug 至少为动词-名词-scope：{slug!r}"
+            (errors if strict else warnings).append(msg)
         noun_count = 0
 
     if noun_count > _MAX_NOUN_SEGMENTS:

tests/test_display_metadata.py

@@ -595,6 +595,53 @@ metadata:
         self.assertIn("readonly = 1", text)
         self.assertIn("seed_column_metadata_batch", text)
         self.assertIn("valid_column_names", text)
+        self.assertIn("可以**引用 `visible=0` 的列", text)
+        self.assertIn("default_sort_json` / ORDER BY", text)
+
+    def test_default_sort_json_allows_hidden_column_and_rejects_missing(self) -> None:
+        conn = sqlite3.connect(":memory:")
+        try:
+            from db.display_metadata import (
+                init_display_metadata_tables,
+                seed_column_metadata_batch,
+                upsert_table_metadata,
+            )
+            from db.display_metadata_validator import validate_default_sort_metadata
+
+            cur = conn.cursor()
+            init_display_metadata_tables(cur)
+            cur.execute(
+                "CREATE TABLE demo_sort (id INTEGER PRIMARY KEY, title TEXT NOT NULL)"
+            )
+            upsert_table_metadata(
+                cur,
+                table_name="demo_sort",
+                display_name="排序示例",
+                default_sort_json='[{"column":"title","direction":"asc"},{"column":"id","direction":"desc"}]',
+            )
+            seed_column_metadata_batch(
+                cur,
+                table_name="demo_sort",
+                columns=(
+                    {"column_name": "id", "display_name": "编号", "visible": 0, "editable": 0},
+                    {"column_name": "title", "display_name": "标题", "visible": 1, "editable": 1},
+                ),
+                valid_column_names=["id", "title"],
+            )
+            errors, warnings = validate_default_sort_metadata(cur, "demo_sort")
+            self.assertEqual(errors, [])
+            self.assertTrue(any("visible=0" in w and "id" in w for w in warnings))
+
+            upsert_table_metadata(
+                cur,
+                table_name="demo_sort",
+                display_name="排序示例",
+                default_sort_json='[{"column":"missing_col","direction":"asc"}]',
+            )
+            errors, _ = validate_default_sort_metadata(cur, "demo_sort")
+            self.assertTrue(any("missing_col" in e for e in errors))
+        finally:
+            conn.close()
 
     def test_default_visible_columns_json_upsert_and_migrate(self) -> None:
         conn = sqlite3.connect(":memory:")

tests/test_slug_naming.py

@@ -44,6 +44,8 @@ class TestSlugNaming(unittest.TestCase):
         for slug in (
             "download-settlement-report-amazon",
             "add-product-shopee",
+            "generate-monthly-statements",
+            "reconcile-finance",
             "generate-article-all",
             "your-skill-slug",
             "account-manager",
@@ -56,8 +58,7 @@ class TestSlugNaming(unittest.TestCase):
         cases = (
             "amazon-download-settlement-report",
             "enter-cross-border-sales-receipt-voucher-kingdee",
-            "reconcile-finance",
-            "download-settlement-report-unknownplat",
+            "generate",
             "foobar-settlement-report-amazon",
         )
         for slug in cases:
@@ -78,6 +79,19 @@ class TestSlugNaming(unittest.TestCase):
         self.assertTrue(errors)
         self.assertTrue(any("48" in err for err in errors))
 
+    def test_plain_slug_without_platform(self) -> None:
+        slug = "generate-monthly-statements"
+        self.assertEqual(classify_slug_form(parse_slug_segments(slug), slug=slug), "plain")
+        errors, warnings = validate_slug_semantics(slug)
+        self.assertEqual(errors, [], msg=f"errors={errors!r} warnings={warnings!r}")
+        self.assertEqual(warnings, [])
+
+    def test_default_suffix_warns_but_does_not_fail(self) -> None:
+        slug = "generate-article-default"
+        errors, warnings = validate_slug_semantics(slug)
+        self.assertEqual(errors, [], msg=f"errors={errors!r}")
+        self.assertTrue(any("default" in item for item in warnings), msg=f"warnings={warnings!r}")
+
     def test_legacy_exempt_set(self) -> None:
         self.assertIn("your-skill-slug", LEGACY_EXEMPT_SLUGS)
         self.assertIn("account-manager", LEGACY_EXEMPT_SLUGS)