skill-template/references/SCHEMA.md

数据存储与数据管理展示规范

本文是 skill 本地 SQLite 与匠厂宿主「数据管理」页面展示契约的权威说明。 实现上的 DDL 与默认中文元数据种子见 scripts/db/display_metadata.py；scripts/db/connection.py 的 init_db() 会一并初始化。

职责边界

层级	负责内容
技能（本仓库）	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）

---
name: 中文业务名称
description: 中文技能说明
metadata:
  openclaw:
    slug: english-kebab-slug
---

• name：用户可见的中文业务名称（可含品牌，如 GEO 文章生成、1688 联系人采集）。
• description：能力说明，不是技能名称。
• metadata.openclaw.slug：机器标识，kebab-case 英文；目录名与默认数据库文件名使用 slug。
• 复制模板后不得将 your-skill-slug、My Skill 等占位内容作为正式技能发布名称。

数据库路径与命名

{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

字段	必填	说明
table_name	是	物理表名
display_name	是	中文表名（用户可见）
description	否	表说明
sort_order	否	宿主目录排序；与字段顺序无关
visible	是	1 展示 / 0 隐藏
readonly	是	1 只读 / 0 可写（业务语义）

_jiangchang_columns

字段	必填	说明
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 或语义规则重排。

推荐顺序（可按业务裁剪，但已有字段应遵守相对位置）：

1. 主键 id
2. 关联标识与核心业务字段
3. 普通业务字段
4. 状态、结果、错误等辅助字段
5. created_at（如有）
6. updated_at（如有）

模板默认：task_logs

物理定义（权威顺序）：

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

业务特有字段优先放入 result_summary（JSON 字符串），避免随意加列；若确需新列，必须同步元数据并保持合理物理顺序。

开发自检

• init_db() 后运行 tests/test_display_metadata.py。
• 复制为真实技能后，使用 scripts/db/display_metadata_validator.py 中的校验函数检查 SKILL 名称、slug 与元数据完整性。

模板原则

• 模板不做复杂历史迁移框架；新 skill 从当前 schema 起步。
• 元数据 DDL 与 task_logs 中文种子以 scripts/db/display_metadata.py 为单一权威来源。