From 707d97760f4c91aa32097d61f6287fc63b4633ec Mon Sep 17 00:00:00 2001 From: chendelian <116870791@qq.com> Date: Wed, 1 Jul 2026 11:39:28 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=8C=A0=E5=8E=82=E6=95=B0=E6=8D=AE?= =?UTF-8?q?=E7=AE=A1=E7=90=86=E5=B1=95=E7=A4=BA=E5=85=83=E6=95=B0=E6=8D=AE?= =?UTF-8?q?=E8=A7=84=E8=8C=83=E2=80=94=E2=80=94=E5=85=83=E6=95=B0=E6=8D=AE?= =?UTF-8?q?=E8=A1=A8=E5=88=9D=E5=A7=8B=E5=8C=96/=E6=A0=A1=E9=AA=8C?= =?UTF-8?q?=E3=80=81display=5Forder=20=E5=A5=91=E7=BA=A6=E3=80=81=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E4=B8=8E=E6=B5=8B=E8=AF=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- SKILL.md | 7 + development/DEVELOPMENT.md | 2 + development/REQUIREMENTS.md | 3 + development/RUNTIME.md | 3 + development/TESTING.md | 1 + references/SCHEMA.md | 187 ++++++++++-- scripts/db/connection.py | 2 + scripts/db/display_metadata.py | 164 +++++++++++ scripts/db/display_metadata_validator.py | 248 ++++++++++++++++ tests/README.md | 1 + tests/test_db_smoke.py | 10 +- tests/test_display_metadata.py | 347 +++++++++++++++++++++++ 12 files changed, 948 insertions(+), 27 deletions(-) create mode 100644 scripts/db/display_metadata.py create mode 100644 scripts/db/display_metadata_validator.py create mode 100644 tests/test_display_metadata.py diff --git a/SKILL.md b/SKILL.md index 60e5a4c..34aaad8 100644 --- a/SKILL.md +++ b/SKILL.md @@ -82,6 +82,13 @@ python {baseDir}/scripts/main.py version 2. 按 `development/DEVELOPMENT.md` 完成开发与文档定制。 3. 用户市场说明写入根 `README.md`；Agent 调用契约见 `references/CLI.md`、`references/SCHEMA.md`。 4. 同步修改 `scripts/util/constants.py` 中的 `SKILL_SLUG` / `SKILL_VERSION`。 +5. 本地 SQLite 的中文表名/字段名与字段顺序规范见 `references/SCHEMA.md`（元数据表 `_jiangchang_*` + `CREATE TABLE` 物理顺序）。 + +## 技能命名与 slug + +- `name`（frontmatter）：**用户可见的中文业务名称**；`description` 是说明，不是名称。 +- `metadata.openclaw.slug`：**英文 kebab-case** 机器标识；目录名、默认 `{slug}.db` 使用 slug，不使用中文。 +- 复制后全局替换 `your-skill-slug`；正式技能不得保留英文占位 `name` 或 slug。 ## 平台元数据 diff --git a/development/DEVELOPMENT.md b/development/DEVELOPMENT.md index bb549c7..253474c 100644 --- a/development/DEVELOPMENT.md +++ b/development/DEVELOPMENT.md @@ -445,6 +445,8 @@ metadata: - `db/task_logs_repository.py` 只做增删查改（模板默认表：`task_logs`） +- `db/display_metadata.py` + 创建 `_jiangchang_tables` / `_jiangchang_columns` 并幂等写入中文展示名（见 `references/SCHEMA.md`） 不要在 `db` 层里： diff --git a/development/REQUIREMENTS.md b/development/REQUIREMENTS.md index d2b29cd..c760d00 100644 --- a/development/REQUIREMENTS.md +++ b/development/REQUIREMENTS.md @@ -150,6 +150,9 @@ - 主命令（如 `run`）在 mock / simulator 档位可重复验证 - `python tests/run_tests.py -v` 必跑测试全部通过 - `task_logs` 写入和查询符合 `references/SCHEMA.md` +- `init_db()` 已写入 `_jiangchang_tables` / `_jiangchang_columns`；用户可见表/字段具备中文 `display_name` +- 字段展示顺序与 `PRAGMA table_info(task_logs)` 的 cid 一致；不依赖 `display_order` +- `tests/test_display_metadata.py` 通过 - 真实联调（如有）放在 `tests/integration/`，且默认套件不包含真实外联 - 发布后 Gitea 工作流成功；匠厂技能市场可见最新版本；安装后可在“新建任务”中调用 diff --git a/development/RUNTIME.md b/development/RUNTIME.md index dd61395..82178ad 100644 --- a/development/RUNTIME.md +++ b/development/RUNTIME.md @@ -89,6 +89,9 @@ RPA 录屏成片（`RpaVideoSession`）、ffmpeg 路径、背景音乐探测均 {...}/{skill_slug}.db ``` +- 业务表使用英文 snake_case；中文表名/字段名写入 `_jiangchang_tables` / `_jiangchang_columns`（见 `references/SCHEMA.md`）。 +- 界面字段顺序由 `CREATE TABLE` 列定义顺序决定，**不要**维护 `display_order` 来调整顺序。 + ## 明确禁止 - **不得** vendored `scripts/jiangchang_skill_core/` diff --git a/development/TESTING.md b/development/TESTING.md index 07a0e6d..327f900 100644 --- a/development/TESTING.md +++ b/development/TESTING.md @@ -28,6 +28,7 @@ - 运行时：`runtime_paths` 与 **`JIANGCHANG_*` 隔离**； - `SKILL.md` YAML slug vs [`constants.SKILL_SLUG`](../scripts/util/constants.py)； - SQLite 骨架：`task_logs` 创建幂等与仓储读写； +- 数据管理元数据：`_jiangchang_*` 幂等初始化、中文展示名、`PRAGMA table_info` 字段顺序（见 `test_display_metadata.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。 diff --git a/references/SCHEMA.md b/references/SCHEMA.md index d3ffe56..f9282d5 100644 --- a/references/SCHEMA.md +++ b/references/SCHEMA.md @@ -1,38 +1,173 @@ -# 数据存储模板 +# 数据存储与数据管理展示规范 -## 数据库路径 +本文是 skill 本地 SQLite 与匠厂宿主「数据管理」页面展示契约的**权威说明**。 +实现上的 DDL 与默认中文元数据种子见 `scripts/db/display_metadata.py`；`scripts/db/connection.py` 的 `init_db()` 会一并初始化。 -`{DATA_ROOT}/{USER_ID}/your-skill-slug/your-skill-slug.db` +## 职责边界 -## 通用任务日志表（task_logs） +| 层级 | 负责内容 | +|------|----------| +| **技能（本仓库）** | `SKILL.md.name` 中文技能名；英文物理表/字段名；`_jiangchang_*` 中文展示元数据；`CREATE TABLE` 字段物理顺序 | +| **宿主（匠厂）** | 读取元数据与 PRAGMA 顺序并展示；不猜测业务语义、不按英文字段名重排 | -模板默认建表： +SQLite **没有**可靠的 `COMMENT ON TABLE/COLUMN`；SQL 文件里的 `-- 注释` 也不会成为可查询结构。 +因此中文展示名称必须写入元数据表；字段顺序必须写在 `CREATE TABLE` 的列定义顺序中（`PRAGMA table_info` 的 `cid`）。 -| 字段 | 类型 | 说明 | +> **禁止**新技能使用宿主的旧版 `_schema_meta` 表。仅 `_jiangchang_tables` / `_jiangchang_columns` 为正式契约。 + +## 技能名称（SKILL.md） + +```yaml +--- +name: 中文业务名称 +description: 中文技能说明 +metadata: + openclaw: + slug: english-kebab-slug +--- +``` + +- `name`：用户可见的中文业务名称（可含品牌，如 `GEO 文章生成`、`1688 联系人采集`）。 +- `description`：能力说明，不是技能名称。 +- `metadata.openclaw.slug`：机器标识，kebab-case 英文；目录名与默认数据库文件名使用 slug。 +- 复制模板后不得将 `your-skill-slug`、`My Skill` 等占位内容作为正式技能发布名称。 + +## 数据库路径与命名 + +```text +{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/{skill-slug}/{skill-slug}.db +``` + +- 数据库文件：英文 slug，例如 `scrape-contacts.db`、`account-manager.db`（默认 `{skill-slug}.db`）。 +- 业务表、字段：**英文 snake_case** 物理名，例如 `task_logs`、`created_at`。 +- **禁止**用中文作为 SQLite 真实表名或字段名。 + +## 元数据表（宿主兼容） + +宿主读取字段（与 `jiangchang` `metadata-resolver.ts` 一致）： + +### `_jiangchang_tables` + +| 字段 | 必填 | 说明 | |------|------|------| -| `id` | INTEGER PK | 自增主键 | -| `task_type` | TEXT NOT NULL | 任务类型（disburse / reconcile / verify ...） | -| `target_id` | TEXT | 任务目标（账号、平台、客户等的 ID） | -| `input_id` | TEXT | 输入对象 ID | -| `input_title` | TEXT | 输入对象标题快照 | -| `status` | TEXT NOT NULL | success / failed / partial / require_login 等 | -| `error_msg` | TEXT | 错误说明 | -| `result_summary` | TEXT | 结果摘要（建议存 JSON 字符串） | -| `created_at` | INTEGER | Unix 时间戳 | -| `updated_at` | INTEGER | Unix 时间戳 | +| `table_name` | 是 | 物理表名 | +| `display_name` | 是 | 中文表名（用户可见） | +| `description` | 否 | 表说明 | +| `sort_order` | 否 | 宿主目录排序；与字段顺序无关 | +| `visible` | 是 | `1` 展示 / `0` 隐藏 | +| `readonly` | 是 | `1` 只读 / `0` 可写（业务语义） | -## 不同业务的字段映射建议 +### `_jiangchang_columns` -| 业务场景 | task_type | target_id 含义 | input_id 含义 | -|---|---|---|---| -| 发布类 | publish | 账号 ID | 文章 ID | -| 工资代发 | disburse | 付款账户 | 工资表批次 ID | -| 对账 | reconcile | 银行 / 平台 | 对账批次 ID | +| 字段 | 必填 | 说明 | +|------|------|------| +| `table_name` | 是 | 物理表名 | +| `column_name` | 是 | 物理字段名 | +| `display_name` | 是 | 中文字段名（用户可见） | +| `description` | 否 | 字段说明 | +| `display_order` | 否 | **遗留兼容字段；模板写入时固定 NULL，重复初始化会清理历史非空值，不得用于调整展示顺序** | +| `visible` | 是 | 是否展示 | +| `searchable` | 是 | 是否可搜索 | +| `editable` | 是 | 是否可编辑（与宿主权限结合） | +| `display_type` | 否 | 如 `text` / `textarea` | +| `options_json` | 否 | 枚举选项 JSON | + +这两张表是**数据字典**，不是业务数据；宿主不会把它们当作普通业务表展示。 + +写入应**幂等**（`INSERT … ON CONFLICT DO UPDATE`），数据库升级时同步维护元数据。 + +## 业务字段物理顺序 + +用户在「数据管理」中看到的列顺序 = `CREATE TABLE` 定义顺序 = `PRAGMA table_info` 的 `cid` 顺序。 +**宿主不会**按英文字段名、`display_order` 或语义规则重排。 + +推荐顺序（可按业务裁剪，但已有字段应遵守相对位置）： + +```text +1. 主键 id +2. 关联标识与核心业务字段 +3. 普通业务字段 +4. 状态、结果、错误等辅助字段 +5. created_at（如有） +6. updated_at（如有） +``` + +### 模板默认：`task_logs` + +物理定义（权威顺序）： + +```sql +CREATE TABLE IF NOT EXISTS task_logs ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + task_type TEXT NOT NULL, + target_id TEXT, + input_id TEXT, + input_title TEXT, + status TEXT NOT NULL, + error_msg TEXT, + result_summary TEXT, + created_at INTEGER NOT NULL, + updated_at INTEGER NOT NULL +); +``` + +对应中文展示（由 `init_db()` 写入元数据表）： + +| 物理字段 | 中文名 | +|----------|--------| +| id | 编号 | +| task_type | 任务类型 | +| target_id | 目标编号 | +| input_id | 输入编号 | +| input_title | 输入标题 | +| status | 状态 | +| error_msg | 错误信息 | +| result_summary | 结果摘要 | +| created_at | 创建时间 | +| updated_at | 更新时间 | + +表中文名：**任务日志**。 + +禁止事项： + +- 不要把 `created_at` 放在第一列； +- 不要把 `id` 随意放在中间； +- 不要指望宿主按英文字段名排序； +- 若需调整历史表字段顺序，应通过规范迁移**重建表**，而不是在宿主侧配置掩盖。 + +复合主键或特殊表结构，请在本文档或技能自有 SCHEMA 补充中说明例外。 + +## 中文命名质量 + +- 使用普通用户能理解的业务用语：`task_logs` → **任务日志**，`error_msg` → **错误信息**。 +- 禁止：`Task Logs`、`input编号`、`errormsg`、直接把物理名当 `display_name`。 +- 不宜向用户暴露的实现细节（如 `payload_json`、`selector`）应设 `visible = 0` 或给出可理解中文名。 + +## 元数据同步规则 + +1. 新增用户可见业务表 → 同步 `_jiangchang_tables`。 +2. 新增用户可见字段 → 同步 `_jiangchang_columns`。 +3. 删除/重命名表或字段 → 同步清理或迁移元数据。 +4. 初始化脚本必须幂等。 +5. 元数据中的表、字段必须在库中真实存在；可见项不得缺少中文 `display_name`。 + +## 不同业务的 `task_logs` 映射 + +| 业务场景 | task_type | target_id | input_id | +|----------|-----------|-----------|----------| +| 发布类 | publish | 账号 ID | 内容 ID | +| 工资代发 | disburse | 付款账户 | 批次 ID | +| 对账 | reconcile | 银行/平台 | 对账批次 ID | | 发票验真 | verify | 税务地区 | 发票批次 ID | -| 报关 | declare | 港口 / 海关 | 报关批次 ID | + +业务特有字段优先放入 `result_summary`（JSON 字符串），避免随意加列；若确需新列，必须同步元数据并保持合理物理顺序。 + +## 开发自检 + +- `init_db()` 后运行 `tests/test_display_metadata.py`。 +- 复制为真实技能后，使用 `scripts/db/display_metadata_validator.py` 中的校验函数检查 SKILL 名称、slug 与元数据完整性。 ## 模板原则 -- 模板不做历史迁移兼容设计 -- 新 skill 直接从当前 schema 起步 -- 业务有特殊字段时，建议放 `result_summary`（JSON 字符串），不要乱加列 +- 模板不做复杂历史迁移框架；新 skill 从当前 schema 起步。 +- 元数据 DDL 与 `task_logs` 中文种子以 `scripts/db/display_metadata.py` 为单一权威来源。 diff --git a/scripts/db/connection.py b/scripts/db/connection.py index ed12294..034115b 100644 --- a/scripts/db/connection.py +++ b/scripts/db/connection.py @@ -4,6 +4,7 @@ from __future__ import annotations import sqlite3 +from db.display_metadata import init_display_metadata from util.runtime_paths import get_db_path @@ -31,6 +32,7 @@ def init_db() -> None: ) """ ) + init_display_metadata(cur) conn.commit() finally: conn.close() diff --git a/scripts/db/display_metadata.py b/scripts/db/display_metadata.py new file mode 100644 index 0000000..622a06c --- /dev/null +++ b/scripts/db/display_metadata.py @@ -0,0 +1,164 @@ +"""匠厂数据管理展示元数据（_jiangchang_tables / _jiangchang_columns）。 + +SQLite 无原生表/字段 COMMENT；中文展示名称通过这两张元数据表提供给宿主「数据管理」页面。 +字段在界面上的顺序由 CREATE TABLE / PRAGMA table_info(cid) 决定，**不**使用 display_order 排序。 +""" + +from __future__ import annotations + +from typing import Iterable + +# 宿主会隐藏这些表，不作为业务表展示（见 jiangchang electron/data-management/types.ts） +INTERNAL_METADATA_TABLES = frozenset({"_jiangchang_tables", "_jiangchang_columns"}) +LEGACY_METADATA_TABLES = frozenset({"_schema_meta"}) +METADATA_TABLES = INTERNAL_METADATA_TABLES | LEGACY_METADATA_TABLES + +TASK_LOGS_TABLE = "task_logs" + +_JIANGCHANG_TABLES_DDL = """ +CREATE TABLE IF NOT EXISTS _jiangchang_tables ( + table_name TEXT PRIMARY KEY, + display_name TEXT NOT NULL, + description TEXT, + sort_order INTEGER, + visible INTEGER NOT NULL DEFAULT 1, + readonly INTEGER NOT NULL DEFAULT 0 +) +""" + +_JIANGCHANG_COLUMNS_DDL = """ +CREATE TABLE IF NOT EXISTS _jiangchang_columns ( + table_name TEXT NOT NULL, + column_name TEXT NOT NULL, + display_name TEXT NOT NULL, + description TEXT, + display_order INTEGER, + visible INTEGER NOT NULL DEFAULT 1, + searchable INTEGER NOT NULL DEFAULT 1, + editable INTEGER NOT NULL DEFAULT 1, + display_type TEXT, + options_json TEXT, + PRIMARY KEY (table_name, column_name) +) +""" + +TASK_LOGS_TABLE_METADATA = { + "table_name": TASK_LOGS_TABLE, + "display_name": "任务日志", + "description": "记录技能任务的执行状态和结果", + "visible": 1, + "readonly": 0, +} + +TASK_LOGS_COLUMN_METADATA: tuple[dict[str, object], ...] = ( + {"column_name": "id", "display_name": "编号", "description": "任务日志唯一编号", "visible": 1, "searchable": 1, "editable": 0}, + {"column_name": "task_type", "display_name": "任务类型", "description": "任务的业务类型", "visible": 1, "searchable": 1, "editable": 1}, + {"column_name": "target_id", "display_name": "目标编号", "description": "任务目标对象编号", "visible": 1, "searchable": 1, "editable": 1}, + {"column_name": "input_id", "display_name": "输入编号", "description": "输入对象编号", "visible": 1, "searchable": 1, "editable": 1}, + {"column_name": "input_title", "display_name": "输入标题", "description": "输入对象标题", "visible": 1, "searchable": 1, "editable": 1}, + {"column_name": "status", "display_name": "状态", "description": "任务当前状态", "visible": 1, "searchable": 1, "editable": 1}, + {"column_name": "error_msg", "display_name": "错误信息", "description": "任务失败时的错误说明", "visible": 1, "searchable": 1, "editable": 1}, + {"column_name": "result_summary", "display_name": "结果摘要", "description": "任务执行结果摘要", "visible": 1, "searchable": 1, "editable": 1}, + {"column_name": "created_at", "display_name": "创建时间", "description": "记录创建时间", "visible": 1, "searchable": 1, "editable": 0}, + {"column_name": "updated_at", "display_name": "更新时间", "description": "记录最后更新时间", "visible": 1, "searchable": 1, "editable": 0}, +) + + +def init_display_metadata_tables(cursor) -> None: + cursor.execute(_JIANGCHANG_TABLES_DDL) + cursor.execute(_JIANGCHANG_COLUMNS_DDL) + + +def upsert_table_metadata(cursor, *, table_name: str, display_name: str, description: str | None = None, visible: int = 1, readonly: int = 0) -> None: + cursor.execute( + """ + INSERT INTO _jiangchang_tables (table_name, display_name, description, visible, readonly) + VALUES (?, ?, ?, ?, ?) + ON CONFLICT(table_name) DO UPDATE SET + display_name = excluded.display_name, + description = excluded.description, + visible = excluded.visible, + readonly = excluded.readonly + """, + (table_name, display_name, description, visible, readonly), + ) + + +def upsert_column_metadata( + cursor, + *, + table_name: str, + column_name: str, + display_name: str, + description: str | None = None, + visible: int = 1, + searchable: int = 1, + editable: int = 1, +) -> None: + # display_order 保留为 NULL：宿主按 PRAGMA table_info cid 展示字段，不读 display_order。 + cursor.execute( + """ + INSERT INTO _jiangchang_columns ( + table_name, column_name, display_name, description, + display_order, visible, searchable, editable + ) + VALUES (?, ?, ?, ?, NULL, ?, ?, ?) + ON CONFLICT(table_name, column_name) DO UPDATE SET + display_name = excluded.display_name, + description = excluded.description, + display_order = NULL, + visible = excluded.visible, + searchable = excluded.searchable, + editable = excluded.editable + """, + (table_name, column_name, display_name, description, visible, searchable, editable), + ) + + +def seed_task_logs_display_metadata(cursor) -> None: + meta = TASK_LOGS_TABLE_METADATA + upsert_table_metadata( + cursor, + table_name=str(meta["table_name"]), + display_name=str(meta["display_name"]), + description=str(meta["description"]) if meta.get("description") else None, + visible=int(meta["visible"]), + readonly=int(meta["readonly"]), + ) + for column in TASK_LOGS_COLUMN_METADATA: + upsert_column_metadata( + cursor, + table_name=TASK_LOGS_TABLE, + column_name=str(column["column_name"]), + display_name=str(column["display_name"]), + description=str(column["description"]) if column.get("description") else None, + visible=int(column["visible"]), + searchable=int(column["searchable"]), + editable=int(column["editable"]), + ) + + +def init_display_metadata(cursor) -> None: + init_display_metadata_tables(cursor) + seed_task_logs_display_metadata(cursor) + + +def iter_user_tables(cursor) -> Iterable[str]: + cursor.execute( + "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name" + ) + for (name,) in cursor.fetchall(): + if name in METADATA_TABLES: + continue + yield str(name) + + +def _quote_identifier(name: str) -> str: + return '"' + name.replace('"', '""') + '"' + + +def list_physical_column_names(cursor, table_name: str) -> list[str]: + cursor.execute(f"PRAGMA table_info({_quote_identifier(table_name)})") + rows = cursor.fetchall() + rows.sort(key=lambda row: int(row[0])) + return [str(row[1]) for row in rows] diff --git a/scripts/db/display_metadata_validator.py b/scripts/db/display_metadata_validator.py new file mode 100644 index 0000000..0a3668d --- /dev/null +++ b/scripts/db/display_metadata_validator.py @@ -0,0 +1,248 @@ +"""数据管理展示元数据校验（模板开发自检，不依赖宿主）。""" + +from __future__ import annotations + +import os +import re +import sqlite3 +from dataclasses import dataclass, field + +from db.display_metadata import ( + METADATA_TABLES, + TASK_LOGS_COLUMN_METADATA, + TASK_LOGS_TABLE, + iter_user_tables, + list_physical_column_names, +) +from util.constants import SKILL_SLUG + +_TEMPLATE_PLACEHOLDER_SLUGS = frozenset({"your-skill-slug", "your_skill_slug"}) +_ENGLISH_PLACEHOLDER_NAME_PATTERNS = ( + re.compile(r"^my\s+skill$", re.I), + re.compile(r"^your[-_\s]?skill", re.I), + re.compile(r"^skill[-_\s]?template$", re.I), + re.compile(r"^[a-z0-9_-]+$"), +) +_KEBAB_SLUG = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$") +_CJK_RE = re.compile(r"[\u4e00-\u9fff]") + + +@dataclass +class ValidationReport: + errors: list[str] = field(default_factory=list) + warnings: list[str] = field(default_factory=list) + + @property + def ok(self) -> bool: + return not self.errors + + +def _has_cjk(text: str) -> bool: + return bool(_CJK_RE.search(text)) + + +def _looks_like_raw_physical_name(display_name: str, physical_name: str) -> bool: + if not display_name.strip(): + return True + if display_name.strip().lower() == physical_name.strip().lower(): + return True + compact = display_name.replace(" ", "").replace("_", "").lower() + if compact == physical_name.replace("_", "").lower(): + return True + return False + + +def _parse_frontmatter_field(text: str, field_name: str) -> str: + parts = text.split("---", 2) + if len(parts) < 2: + return "" + for line in parts[1].splitlines(): + match = re.match(rf"^{re.escape(field_name)}:\s*(.+)\s*$", line.strip()) + if match: + return match.group(1).strip().strip("\"'") + return "" + + +def _parse_openclaw_slug(text: str) -> str: + parts = text.split("---", 2) + if len(parts) < 2: + return "" + lines = parts[1].splitlines() + for index, line in enumerate(lines): + if re.match(r"^\s+openclaw:\s*$", line): + for inner in lines[index + 1 :]: + if inner.strip() and inner[0] not in (" ", "\t"): + break + match = re.match(r"^(\s+)slug:\s*(.+)\s*$", inner) + if match: + return match.group(2).strip().strip("\"'") + return "" + + +def parse_skill_frontmatter(skill_root: str) -> dict[str, str]: + path = os.path.join(skill_root, "SKILL.md") + with open(path, encoding="utf-8") as f: + text = f.read() + return { + "name": _parse_frontmatter_field(text, "name"), + "slug": _parse_openclaw_slug(text), + } + + +def validate_skill_frontmatter(skill_root: str, *, allow_template_placeholders: bool = True) -> ValidationReport: + report = ValidationReport() + data = parse_skill_frontmatter(skill_root) + name = str(data.get("name") or "").strip() + slug = str(data.get("slug") or "").strip() + + if not name: + report.errors.append("SKILL.md frontmatter.name 缺失") + elif not _has_cjk(name): + if allow_template_placeholders and slug in _TEMPLATE_PLACEHOLDER_SLUGS: + report.warnings.append("SKILL.md frontmatter.name 建议使用清晰的中文业务名称（模板占位可暂保留）") + else: + report.errors.append("SKILL.md frontmatter.name 应使用用户可见的中文业务名称") + else: + for pattern in _ENGLISH_PLACEHOLDER_NAME_PATTERNS: + if pattern.fullmatch(name): + if allow_template_placeholders and slug in _TEMPLATE_PLACEHOLDER_SLUGS: + report.warnings.append(f"SKILL.md frontmatter.name 仍为占位风格：{name!r}") + else: + report.errors.append(f"SKILL.md frontmatter.name 不应为英文占位名：{name!r}") + break + + if not slug: + report.errors.append("SKILL.md metadata.openclaw.slug 缺失") + elif not _KEBAB_SLUG.fullmatch(slug): + report.errors.append(f"metadata.openclaw.slug 必须为 kebab-case：{slug!r}") + elif slug in _TEMPLATE_PLACEHOLDER_SLUGS and not allow_template_placeholders: + report.errors.append(f"metadata.openclaw.slug 仍为模板占位：{slug!r}") + + constants_slug = SKILL_SLUG.strip() + if slug and constants_slug and slug != constants_slug: + report.warnings.append( + f"SKILL.md slug ({slug!r}) 与 util.constants.SKILL_SLUG ({constants_slug!r}) 不一致" + ) + + return report + + +def column_order_warnings(table_name: str, ordered_names: list[str]) -> list[str]: + warnings: list[str] = [] + if "id" in ordered_names and ordered_names.index("id") != 0: + warnings.append(f"{table_name}: 字段 id 通常应定义在 CREATE TABLE 的第一列") + if "created_at" in ordered_names: + idx = ordered_names.index("created_at") + trailing = ordered_names[idx + 1 :] + if trailing and trailing != ["updated_at"]: + warnings.append( + f"{table_name}: created_at 之后通常只应跟 updated_at，不应再放置其他业务字段" + ) + if "updated_at" in ordered_names and "created_at" in ordered_names: + if ordered_names.index("updated_at") < ordered_names.index("created_at"): + warnings.append(f"{table_name}: updated_at 不应出现在 created_at 之前") + return warnings + + +def _table_exists(cursor, table_name: str) -> bool: + cursor.execute( + "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ? LIMIT 1", + (table_name,), + ) + return cursor.fetchone() is not None + + +def validate_display_metadata(conn: sqlite3.Connection, *, check_column_order: bool = True) -> ValidationReport: + report = ValidationReport() + cur = conn.cursor() + + has_tables_meta = _table_exists(cur, "_jiangchang_tables") + has_columns_meta = _table_exists(cur, "_jiangchang_columns") + if not has_tables_meta: + report.errors.append("缺少数据管理元数据表 _jiangchang_tables") + if not has_columns_meta: + report.errors.append("缺少数据管理元数据表 _jiangchang_columns") + if not has_tables_meta or not has_columns_meta: + return report + + for table_name in iter_user_tables(cur): + cur.execute( + "SELECT display_name FROM _jiangchang_tables WHERE table_name = ?", + (table_name,), + ) + row = cur.fetchone() + if not row or not str(row[0] or "").strip(): + report.errors.append(f"业务表 {table_name!r} 缺少 _jiangchang_tables.display_name") + elif not _has_cjk(str(row[0])): + report.errors.append(f"业务表 {table_name!r} 的 display_name 应使用中文业务名称") + + physical_columns = list_physical_column_names(cur, table_name) + if check_column_order: + report.warnings.extend(column_order_warnings(table_name, physical_columns)) + + for column_name in physical_columns: + cur.execute( + """ + SELECT display_name, visible + FROM _jiangchang_columns + WHERE table_name = ? AND column_name = ? + """, + (table_name, column_name), + ) + col_row = cur.fetchone() + if not col_row: + report.errors.append( + f"字段 {table_name}.{column_name} 缺少 _jiangchang_columns 元数据" + ) + continue + display_name = str(col_row[0] or "").strip() + visible = col_row[1] is None or int(col_row[1]) != 0 + if visible and not display_name: + report.errors.append(f"字段 {table_name}.{column_name} 的 display_name 为空") + elif visible and _looks_like_raw_physical_name(display_name, column_name): + report.errors.append( + f"字段 {table_name}.{column_name} 的 display_name 不应直接等于英文物理名：{display_name!r}" + ) + elif visible and not _has_cjk(display_name): + report.errors.append( + f"字段 {table_name}.{column_name} 的 display_name 应使用中文：{display_name!r}" + ) + + cur.execute("SELECT table_name, column_name FROM _jiangchang_columns") + for table_name, column_name in cur.fetchall(): + if table_name in METADATA_TABLES: + continue + cur.execute( + "SELECT 1 FROM sqlite_master WHERE type='table' AND name = ?", + (table_name,), + ) + if not cur.fetchone(): + report.errors.append(f"元数据引用了不存在的表：{table_name!r}") + continue + physical = list_physical_column_names(cur, str(table_name)) + if str(column_name) not in physical: + report.errors.append(f"元数据引用了不存在的字段：{table_name}.{column_name}") + + cur.execute("SELECT table_name FROM _jiangchang_tables") + for (table_name,) in cur.fetchall(): + if table_name in METADATA_TABLES: + continue + cur.execute( + "SELECT 1 FROM sqlite_master WHERE type='table' AND name = ?", + (table_name,), + ) + if not cur.fetchone(): + report.errors.append(f"元数据引用了不存在的表：{table_name!r}") + + return report + + +def validate_template_database(conn: sqlite3.Connection) -> ValidationReport: + report = validate_display_metadata(conn) + physical = list_physical_column_names(conn.cursor(), TASK_LOGS_TABLE) + expected = [str(item["column_name"]) for item in TASK_LOGS_COLUMN_METADATA] + if physical != expected: + report.errors.append( + f"task_logs 物理字段顺序应为 {expected}，当前为 {physical}" + ) + return report diff --git a/tests/README.md b/tests/README.md index ca4771e..581ddd2 100644 --- a/tests/README.md +++ b/tests/README.md @@ -73,6 +73,7 @@ python tests/run_tests.py test_cli_smoke | 运行路径与 **JIANGCHANG_*** 隔离 | ``test_runtime_paths.py`` | | ``SKILL.md`` slug 与 ``constants.SKILL_SLUG`` | ``test_skill_metadata.py`` | | DB / ``task_logs`` 骨架冒烟 | ``test_db_smoke.py`` | +| 数据管理元数据 / 字段顺序 | ``test_display_metadata.py`` | | **adapter profile / 外呼授权策略** | ``test_adapter_profile_policy.py`` + ``adapter_test_utils.py``（非 ``test_`` 前缀，不自动当用例收集） | | **无 vendored ``jiangchang_skill_core``** | ``test_platform_import.py`` | | **runtime diagnostics 架构守护** | ``test_runtime_diagnostics_integration.py`` | diff --git a/tests/test_db_smoke.py b/tests/test_db_smoke.py index 5f94911..dbda051 100644 --- a/tests/test_db_smoke.py +++ b/tests/test_db_smoke.py @@ -10,12 +10,20 @@ from _support import IsolatedDataRoot class TestDbSmoke(unittest.TestCase): def test_init_db_idempotent_and_crud_smoke(self) -> None: with IsolatedDataRoot(): - from db.connection import init_db from db import task_logs_repository as tlr + from db.connection import get_conn, init_db init_db() init_db() # 幂等 + conn = get_conn() + try: + cur = conn.cursor() + cur.execute("SELECT display_name FROM _jiangchang_tables WHERE table_name = 'task_logs'") + self.assertEqual(cur.fetchone()[0], "任务日志") + finally: + conn.close() + new_id = tlr.save_task_log( task_type="demo_task", target_id="tgt-1", diff --git a/tests/test_display_metadata.py b/tests/test_display_metadata.py new file mode 100644 index 0000000..76bc61c --- /dev/null +++ b/tests/test_display_metadata.py @@ -0,0 +1,347 @@ +# -*- coding: utf-8 -*- +"""数据管理展示元数据：幂等初始化、中文名称、PRAGMA 字段顺序、校验规则。""" +from __future__ import annotations + +import sqlite3 +import unittest + +from _support import IsolatedDataRoot, get_skill_root + + +class TestDisplayMetadata(unittest.TestCase): + def test_init_db_metadata_idempotent(self) -> None: + with IsolatedDataRoot(): + from db.connection import get_conn, init_db + + init_db() + init_db() + + conn = get_conn() + try: + cur = conn.cursor() + cur.execute("SELECT COUNT(*) FROM _jiangchang_tables WHERE table_name = 'task_logs'") + self.assertEqual(int(cur.fetchone()[0]), 1) + cur.execute("SELECT COUNT(*) FROM _jiangchang_columns WHERE table_name = 'task_logs'") + self.assertEqual(int(cur.fetchone()[0]), 10) + finally: + conn.close() + + def test_task_logs_has_chinese_table_and_column_names(self) -> None: + with IsolatedDataRoot(): + from db.connection import get_conn, init_db + + init_db() + conn = get_conn() + try: + cur = conn.cursor() + cur.execute( + "SELECT display_name FROM _jiangchang_tables WHERE table_name = 'task_logs'" + ) + self.assertEqual(cur.fetchone()[0], "任务日志") + + cur.execute( + """ + SELECT column_name, display_name + FROM _jiangchang_columns + WHERE table_name = 'task_logs' + ORDER BY column_name + """ + ) + by_name = dict(cur.fetchall()) + self.assertEqual(by_name["status"], "状态") + self.assertEqual(by_name["error_msg"], "错误信息") + self.assertEqual(by_name["created_at"], "创建时间") + finally: + conn.close() + + def test_task_logs_physical_order_matches_pragma_cid(self) -> None: + with IsolatedDataRoot(): + from db.connection import init_db + from db.display_metadata import TASK_LOGS_COLUMN_METADATA, list_physical_column_names + from db.connection import get_conn + + init_db() + conn = get_conn() + try: + cur = conn.cursor() + physical = list_physical_column_names(cur, "task_logs") + expected = [str(item["column_name"]) for item in TASK_LOGS_COLUMN_METADATA] + self.assertEqual( + physical, + expected, + ) + cur.execute("PRAGMA table_info('task_logs')") + cid_order = [row[1] for row in sorted(cur.fetchall(), key=lambda row: int(row[0]))] + self.assertEqual(cid_order, expected) + finally: + conn.close() + + def test_init_db_sets_task_logs_display_order_null(self) -> None: + with IsolatedDataRoot(): + from db.connection import get_conn, init_db + + init_db() + conn = get_conn() + try: + cur = conn.cursor() + cur.execute( + """ + SELECT column_name, display_order + FROM _jiangchang_columns + WHERE table_name = 'task_logs' + """ + ) + for column_name, display_order in cur.fetchall(): + self.assertIsNone( + display_order, + msg=f"{column_name} display_order should be NULL", + ) + finally: + conn.close() + + def test_reinit_clears_stale_display_order(self) -> None: + with IsolatedDataRoot(): + from db.connection import get_conn, init_db + + init_db() + conn = get_conn() + try: + conn.execute( + """ + UPDATE _jiangchang_columns + SET display_order = 99 + WHERE table_name = 'task_logs' AND column_name = 'id' + """ + ) + conn.commit() + finally: + conn.close() + + init_db() + conn = get_conn() + try: + cur = conn.cursor() + cur.execute( + """ + SELECT display_order FROM _jiangchang_columns + WHERE table_name = 'task_logs' AND column_name = 'id' + """ + ) + self.assertIsNone(cur.fetchone()[0]) + finally: + conn.close() + + def test_legacy_display_order_does_not_change_pragma_physical_order(self) -> None: + with IsolatedDataRoot(): + from db.connection import get_conn, init_db + from db.display_metadata import list_physical_column_names + + init_db() + conn = get_conn() + try: + cur = conn.cursor() + cur.execute( + """ + UPDATE _jiangchang_columns + SET display_order = 1 + WHERE table_name = 'task_logs' AND column_name = 'updated_at' + """ + ) + cur.execute( + """ + UPDATE _jiangchang_columns + SET display_order = 99 + WHERE table_name = 'task_logs' AND column_name = 'id' + """ + ) + conn.commit() + physical = list_physical_column_names(cur, "task_logs") + self.assertEqual(physical[0], "id") + self.assertEqual(physical[-1], "updated_at") + finally: + conn.close() + + def test_metadata_tables_are_not_user_tables(self) -> None: + with IsolatedDataRoot(): + from db.connection import get_conn, init_db + from db.display_metadata import iter_user_tables + + init_db() + conn = get_conn() + try: + tables = list(iter_user_tables(conn.cursor())) + self.assertEqual(tables, ["task_logs"]) + finally: + conn.close() + + def test_template_database_validation_passes(self) -> None: + with IsolatedDataRoot(): + from db.connection import get_conn, init_db + from db.display_metadata_validator import validate_template_database + + init_db() + conn = get_conn() + try: + report = validate_template_database(conn) + self.assertTrue(report.ok, msg="; ".join(report.errors)) + finally: + conn.close() + + def test_validate_missing_both_metadata_tables(self) -> None: + conn = sqlite3.connect(":memory:") + try: + conn.execute("CREATE TABLE demo_items (id INTEGER PRIMARY KEY, title TEXT)") + from db.display_metadata_validator import validate_display_metadata + + report = validate_display_metadata(conn) + self.assertFalse(report.ok) + self.assertIn("缺少数据管理元数据表 _jiangchang_tables", report.errors) + self.assertIn("缺少数据管理元数据表 _jiangchang_columns", report.errors) + finally: + conn.close() + + def test_validate_missing_jiangchang_tables_only(self) -> None: + from db.display_metadata import _JIANGCHANG_COLUMNS_DDL + from db.display_metadata_validator import validate_display_metadata + + conn = sqlite3.connect(":memory:") + try: + conn.execute(_JIANGCHANG_COLUMNS_DDL) + report = validate_display_metadata(conn) + self.assertFalse(report.ok) + self.assertIn("缺少数据管理元数据表 _jiangchang_tables", report.errors) + self.assertNotIn("缺少数据管理元数据表 _jiangchang_columns", report.errors) + finally: + conn.close() + + def test_validate_missing_jiangchang_columns_only(self) -> None: + from db.display_metadata import _JIANGCHANG_TABLES_DDL + from db.display_metadata_validator import validate_display_metadata + + conn = sqlite3.connect(":memory:") + try: + conn.execute(_JIANGCHANG_TABLES_DDL) + report = validate_display_metadata(conn) + self.assertFalse(report.ok) + self.assertIn("缺少数据管理元数据表 _jiangchang_columns", report.errors) + self.assertNotIn("缺少数据管理元数据表 _jiangchang_tables", report.errors) + finally: + conn.close() + + def test_missing_table_metadata_is_reported(self) -> None: + with IsolatedDataRoot(): + from db.connection import get_conn, init_db + from db.display_metadata_validator import validate_display_metadata + + init_db() + conn = get_conn() + try: + conn.execute("CREATE TABLE demo_items (id INTEGER PRIMARY KEY, title TEXT)") + conn.execute("DELETE FROM _jiangchang_tables WHERE table_name = 'demo_items'") + conn.commit() + report = validate_display_metadata(conn) + self.assertFalse(report.ok) + self.assertTrue(any("demo_items" in err for err in report.errors)) + finally: + conn.close() + + def test_missing_column_metadata_is_reported(self) -> None: + with IsolatedDataRoot(): + from db.connection import get_conn, init_db + from db.display_metadata_validator import validate_display_metadata + + init_db() + conn = get_conn() + try: + conn.execute( + "DELETE FROM _jiangchang_columns WHERE table_name = 'task_logs' AND column_name = 'status'" + ) + conn.commit() + report = validate_display_metadata(conn) + self.assertFalse(report.ok) + self.assertTrue(any("task_logs.status" in err for err in report.errors)) + finally: + conn.close() + + def test_metadata_reference_to_missing_column_is_reported(self) -> None: + with IsolatedDataRoot(): + from db.connection import get_conn, init_db + from db.display_metadata_validator import validate_display_metadata + + init_db() + conn = get_conn() + try: + conn.execute( + """ + INSERT INTO _jiangchang_columns + (table_name, column_name, display_name, visible, searchable, editable) + VALUES ('task_logs', 'not_exists', '不存在', 1, 1, 1) + """ + ) + conn.commit() + report = validate_display_metadata(conn) + self.assertFalse(report.ok) + self.assertTrue(any("not_exists" in err for err in report.errors)) + finally: + conn.close() + + def test_ordering_test_table_not_alphabetized(self) -> None: + conn = sqlite3.connect(":memory:") + try: + conn.executescript( + """ + CREATE TABLE ordering_test ( + z_field TEXT, + id INTEGER PRIMARY KEY, + a_field TEXT, + created_at INTEGER, + updated_at INTEGER + ); + """ + ) + from db.display_metadata import list_physical_column_names + + physical = list_physical_column_names(conn.cursor(), "ordering_test") + self.assertEqual(physical, ["z_field", "id", "a_field", "created_at", "updated_at"]) + finally: + conn.close() + + def test_skill_frontmatter_validation_for_template(self) -> None: + from db.display_metadata_validator import validate_skill_frontmatter + + report = validate_skill_frontmatter(get_skill_root(), allow_template_placeholders=True) + self.assertTrue(report.ok, msg="; ".join(report.errors)) + + def test_skill_frontmatter_rejects_english_placeholder_name(self) -> None: + import os + import tempfile + + from db.display_metadata_validator import validate_skill_frontmatter + + with tempfile.TemporaryDirectory() as tmp: + skill_md = """--- +name: My Skill +description: demo +metadata: + openclaw: + slug: demo-skill +--- +""" + with open(os.path.join(tmp, "SKILL.md"), "w", encoding="utf-8") as f: + f.write(skill_md) + report = validate_skill_frontmatter(tmp, allow_template_placeholders=False) + self.assertFalse(report.ok) + self.assertTrue(any("name" in err for err in report.errors)) + + def test_column_order_warning_for_created_at_in_middle(self) -> None: + from db.display_metadata_validator import column_order_warnings + + warnings = column_order_warnings( + "bad_order", + ["created_at", "id", "title", "updated_at"], + ) + self.assertTrue(any("id" in item for item in warnings)) + + +if __name__ == "__main__": + unittest.main()