feat: 规范标准时间字段 created_at/updated_at（Unix 秒级、元数据、trigger）

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。
 
 ## 平台元数据
 

development/DEVELOPMENT.md

@@ -445,6 +445,10 @@ metadata:
 
 - `db/task_logs_repository.py`
   只做增删查改（模板默认表：`task_logs`）
+- `db/display_metadata.py`
+  创建 `_jiangchang_tables` / `_jiangchang_columns` 并幂等写入中文展示名（见 `references/SCHEMA.md`）
+- `db/timestamp_columns.py`
+  标准时间字段 trigger 与维护约定（`created_at` / `updated_at`，Unix 秒级）
 
 不要在 `db` 层里：
 

development/REQUIREMENTS.md

@@ -149,7 +149,10 @@
 - `health`、`version` 命令执行正常
 - 主命令（如 `run`）在 mock / simulator 档位可重复验证
 - `python tests/run_tests.py -v` 必跑测试全部通过
-- `task_logs` 写入和查询符合 `references/SCHEMA.md`
+- `task_logs` 写入和查询符合 `references/SCHEMA.md`（含 `created_at` / `updated_at` Unix 秒级规范）
+- `init_db()` 已写入 `_jiangchang_tables` / `_jiangchang_columns`；用户可见表/字段具备中文 `display_name`
+- 字段展示顺序与 `PRAGMA table_info(task_logs)` 的 cid 一致；不依赖 `display_order`
+- `tests/test_display_metadata.py` 通过
 - 真实联调（如有）放在 `tests/integration/`，且默认套件不包含真实外联
 - 发布后 Gitea 工作流成功；匠厂技能市场可见最新版本；安装后可在“新建任务”中调用
 

development/RUNTIME.md

@@ -71,7 +71,7 @@ RPA 录屏成片（`RpaVideoSession`）、ffmpeg 路径、背景音乐探测均
 
 - `scripts/main.py`：唯一 CLI 入口
 - `scripts/cli/`：参数解析与命令分发
-- `scripts/db/`：SQLite 或本地持久化层
+- `scripts/db/`：SQLite 或本地持久化层（标准时间字段见 `references/SCHEMA.md`）
 - `scripts/service/`：业务用例与外部交互
 - `scripts/util/`：通用工具、常量、日志、路径薄封装
 
@@ -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/`

development/TESTING.md

@@ -28,6 +28,8 @@
 - 运行时：`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`）；
+- 标准时间字段：`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。
 

references/SCHEMA.md

@@ -1,38 +1,204 @@
-# 数据存储模板
+# 数据存储与数据管理展示规范
 
-## 数据库路径
+本文是 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 | 自增主键 |
+| `table_name` | 是 | 物理表名 |
-| `task_type` | TEXT NOT NULL | 任务类型（disburse / reconcile / verify ...） |
+| `display_name` | 是 | 中文表名（用户可见） |
-| `target_id` | TEXT | 任务目标（账号、平台、客户等的 ID） |
+| `description` | 否 | 表说明 |
-| `input_id` | TEXT | 输入对象 ID |
+| `sort_order` | 否 | 宿主目录排序；与字段顺序无关 |
-| `input_title` | TEXT | 输入对象标题快照 |
+| `visible` | 是 | `1` 展示 / `0` 隐藏 |
-| `status` | TEXT NOT NULL | success / failed / partial / require_login 等 |
+| `readonly` | 是 | `1` 只读 / `0` 可写（业务语义） |
-| `error_msg` | TEXT | 错误说明 |
-| `result_summary` | TEXT | 结果摘要（建议存 JSON 字符串） |
-| `created_at` | INTEGER | Unix 时间戳 |
-| `updated_at` | INTEGER | Unix 时间戳 |
 
-## 不同业务的字段映射建议
+### `_jiangchang_columns`
 
-| 业务场景 | task_type | target_id 含义 | input_id 含义 |
+| 字段 | 必填 | 说明 |
-|---|---|---|---|
+|------|------|------|
-| 发布类 | publish | 账号 ID | 文章 ID |
+| `table_name` | 是 | 物理表名 |
-| 工资代发 | disburse | 付款账户 | 工资表批次 ID |
+| `column_name` | 是 | 物理字段名 |
-| 对账 | reconcile | 银行 / 平台 | 对账批次 ID |
+| `display_name` | 是 | 中文字段名（用户可见） |
+| `description` | 否 | 字段说明 |
+| `display_order` | 否 | **遗留兼容字段；模板写入时固定 NULL，重复初始化会清理历史非空值，不得用于调整展示顺序** |
+| `visible` | 是 | 是否展示 |
+| `searchable` | 是 | 是否可搜索 |
+| `editable` | 是 | 是否可编辑（与宿主权限结合） |
+| `display_type` | 否 | 如 `text` / `textarea` / `datetime_unix_seconds`（标准时间字段见下文） |
+| `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（如有）
+
+## 标准时间字段（新技能统一规范）
+
+新技能业务表若需要时间审计字段，**统一**采用 Unix **秒级**时间戳，不要使用毫秒时间戳、ISO 字符串或 SQLite 文本 datetime。
+
+| 项目 | 规范 |
+|------|------|
+| 物理字段 | `created_at INTEGER`、`updated_at INTEGER` |
+| 存储格式 | Unix 秒级整数 |
+| 展示元数据 `display_type` | `datetime_unix_seconds` |
+| 中文名 | `created_at` → **创建时间**；`updated_at` → **更新时间** |
+| 用户编辑 | `editable = 0`（系统字段，宿主只展示格式化结果，不写回字符串） |
+| 字段顺序 | 位于业务字段末尾：`… → created_at → updated_at` |
+| 排序 | **不使用** `display_order`；顺序仅来自 `PRAGMA table_info` |
+
+### 自动生成与维护
+
+- **created_at**：`INTEGER NOT NULL DEFAULT (unixepoch())`；插入时可省略，由数据库生成。
+- **updated_at**：`INTEGER NOT NULL DEFAULT (unixepoch())`；插入时同样可省略。
+- **updated_at 更新**：模板默认表 `task_logs` 通过 SQLite trigger `{table}_set_updated_at` 在业务字段更新后自动刷新；若技能所有 UPDATE 都经过统一 repository，也可在 repository 层设置 `updated_at = unixepoch()`，**不要**叠加两套机制。
+
+实现参考：
+
+- DDL 与 trigger：`scripts/db/connection.py`、`scripts/db/timestamp_columns.py`
+- 中文元数据种子：`scripts/db/display_metadata.py`
+- 自检：`scripts/db/display_metadata_validator.py`
+
+宿主（匠厂）只负责把 `display_type = datetime_unix_seconds` 格式化为 `YYYY-MM-DD HH:mm:ss` 展示，**不修改**数据库原始值。
+
+> `datetime_unix_milliseconds`、`datetime_iso` 是宿主兼容能力，**不是**新技能模板推荐标准。
+
+### 模板默认：`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 DEFAULT (unixepoch()),
+    updated_at INTEGER NOT NULL DEFAULT (unixepoch())
+);
+```
+
+插入时可省略 `created_at`、`updated_at`；`updated_at` 在 UPDATE 时由 trigger `task_logs_set_updated_at` 自动维护（见 `scripts/db/timestamp_columns.py`）。
+
+对应中文展示（由 `init_db()` 写入元数据表）：
+
+| 物理字段 | 中文名 |
+|----------|--------|
+| id | 编号 |
+| task_type | 任务类型 |
+| target_id | 目标编号 |
+| input_id | 输入编号 |
+| input_title | 输入标题 |
+| status | 状态 |
+| error_msg | 错误信息 |
+| result_summary | 结果摘要 |
+| created_at | 创建时间（`display_type = datetime_unix_seconds`，不可编辑） |
+| updated_at | 更新时间（`display_type = datetime_unix_seconds`，不可编辑） |
+
+表中文名：**任务日志**。
+
+禁止事项：
+
+- 不要把 `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 起步。
-- 新 skill 直接从当前 schema 起步
+- 元数据 DDL 与 `task_logs` 中文种子以 `scripts/db/display_metadata.py` 为单一权威来源。
-- 业务有特殊字段时，建议放 `result_summary`（JSON 字符串），不要乱加列

scripts/db/connection.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 
 import sqlite3
 
+from db.display_metadata import init_display_metadata
+from db.timestamp_columns import init_task_logs_timestamp_maintenance
 from util.runtime_paths import get_db_path
 
 
@@ -26,11 +28,13 @@ def init_db() -> None:
                 status TEXT NOT NULL,
                 error_msg TEXT,
                 result_summary TEXT,
-                created_at INTEGER NOT NULL,
+                created_at INTEGER NOT NULL DEFAULT (unixepoch()),
-                updated_at INTEGER NOT NULL
+                updated_at INTEGER NOT NULL DEFAULT (unixepoch())
             )
             """
         )
+        init_task_logs_timestamp_maintenance(cur)
+        init_display_metadata(cur)
         conn.commit()
     finally:
         conn.close()

scripts/db/display_metadata.py

@@ -0,0 +1,185 @@
+"""匠厂数据管理展示元数据（_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"
+DATETIME_UNIX_SECONDS = "datetime_unix_seconds"
+STANDARD_TIMESTAMP_COLUMNS = frozenset({"created_at", "updated_at"})
+
+_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": "记录创建时间（Unix 秒级时间戳，数据库自动生成）",
+        "visible": 1,
+        "searchable": 0,
+        "editable": 0,
+        "display_type": DATETIME_UNIX_SECONDS,
+    },
+    {
+        "column_name": "updated_at",
+        "display_name": "更新时间",
+        "description": "记录最后更新时间（Unix 秒级时间戳，自动维护）",
+        "visible": 1,
+        "searchable": 0,
+        "editable": 0,
+        "display_type": DATETIME_UNIX_SECONDS,
+    },
+)
+
+
+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,
+    display_type: str | None = None,
+) -> 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, display_type
+        )
+        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,
+            display_type = excluded.display_type
+        """,
+        (table_name, column_name, display_name, description, visible, searchable, editable, display_type),
+    )
+
+
+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"]),
+            display_type=str(column["display_type"]) if column.get("display_type") else None,
+        )
+
+
+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]

scripts/db/display_metadata_validator.py

@@ -0,0 +1,369 @@
+"""数据管理展示元数据校验（模板开发自检，不依赖宿主）。"""
+
+from __future__ import annotations
+
+import os
+import re
+import sqlite3
+from dataclasses import dataclass, field
+
+from db.display_metadata import (
+    DATETIME_UNIX_SECONDS,
+    METADATA_TABLES,
+    STANDARD_TIMESTAMP_COLUMNS,
+    TASK_LOGS_COLUMN_METADATA,
+    TASK_LOGS_TABLE,
+    iter_user_tables,
+    list_physical_column_names,
+)
+from db.timestamp_columns import has_updated_at_trigger
+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 _quote_identifier(name: str) -> str:
+    return '"' + name.replace('"', '""') + '"'
+
+
+def _table_column_info(cursor, table_name: str) -> dict[str, dict[str, object]]:
+    cursor.execute(f"PRAGMA table_info({_quote_identifier(table_name)})")
+    info: dict[str, dict[str, object]] = {}
+    for row in cursor.fetchall():
+        info[str(row[1])] = {
+            "cid": int(row[0]),
+            "name": str(row[1]),
+            "type": str(row[2] or ""),
+            "notnull": int(row[3] or 0),
+            "dflt_value": row[4],
+            "pk": int(row[5] or 0),
+        }
+    return info
+
+
+def _default_uses_unixepoch(default_value: object) -> bool:
+    if default_value is None:
+        return False
+    text = str(default_value).strip().lower()
+    return "unixepoch" in text
+
+
+def _expected_timestamp_display_name(column_name: str) -> str:
+    if column_name == "created_at":
+        return "创建时间"
+    if column_name == "updated_at":
+        return "更新时间"
+    return ""
+
+
+def validate_standard_timestamp_columns(
+    cursor,
+    table_name: str,
+    *,
+    physical_columns: list[str] | None = None,
+) -> tuple[list[str], list[str]]:
+    errors: list[str] = []
+    warnings: list[str] = []
+    ordered = physical_columns or list_physical_column_names(cursor, table_name)
+    column_info = _table_column_info(cursor, table_name)
+
+    for column_name in STANDARD_TIMESTAMP_COLUMNS:
+        if column_name not in ordered:
+            continue
+
+        physical = column_info.get(column_name)
+        if not physical:
+            errors.append(f"{table_name}.{column_name} 缺少物理字段定义")
+            continue
+
+        if "INT" not in str(physical["type"]).upper():
+            errors.append(
+                f"{table_name}.{column_name} 字段类型应为 INTEGER（Unix 秒级时间戳），当前为 {physical['type']!r}"
+            )
+
+        if column_name == "created_at" and not _default_uses_unixepoch(physical["dflt_value"]):
+            errors.append(
+                f"{table_name}.created_at 应设置数据库默认值 DEFAULT (unixepoch())，当前默认值为 {physical['dflt_value']!r}"
+            )
+        if column_name == "updated_at" and not _default_uses_unixepoch(physical["dflt_value"]):
+            errors.append(
+                f"{table_name}.updated_at 应设置数据库初始默认值 DEFAULT (unixepoch())，当前默认值为 {physical['dflt_value']!r}"
+            )
+
+        cursor.execute(
+            """
+            SELECT display_name, display_type, editable, searchable, display_order
+            FROM _jiangchang_columns
+            WHERE table_name = ? AND column_name = ?
+            """,
+            (table_name, column_name),
+        )
+        meta_row = cursor.fetchone()
+        if not meta_row:
+            errors.append(f"{table_name}.{column_name} 缺少 _jiangchang_columns 元数据")
+            continue
+
+        display_name, display_type, editable, searchable, display_order = meta_row
+        expected_name = _expected_timestamp_display_name(column_name)
+        if str(display_name or "").strip() != expected_name:
+            errors.append(
+                f"{table_name}.{column_name} 的 display_name 应为 {expected_name!r}，当前为 {display_name!r}"
+            )
+        if str(display_type or "").strip() != DATETIME_UNIX_SECONDS:
+            errors.append(
+                f"{table_name}.{column_name} 的 display_type 应为 {DATETIME_UNIX_SECONDS!r}，当前为 {display_type!r}"
+            )
+        if editable is None or int(editable) != 0:
+            errors.append(f"{table_name}.{column_name} 的 editable 应为 0（系统时间字段不可编辑）")
+        if display_order is not None:
+            errors.append(f"{table_name}.{column_name} 的 display_order 应为 NULL")
+        if searchable is not None and int(searchable) != 0:
+            warnings.append(f"{table_name}.{column_name} 的时间字段通常不必开启 searchable")
+
+    if "created_at" in ordered and "updated_at" in ordered:
+        if ordered.index("updated_at") < ordered.index("created_at"):
+            warnings.append(f"{table_name}: updated_at 不应出现在 created_at 之前")
+
+    if "updated_at" in ordered and not has_updated_at_trigger(cursor, table_name):
+        errors.append(
+            f"{table_name}.updated_at 缺少自动维护 trigger（期望 {table_name}_set_updated_at）"
+        )
+
+    return errors, warnings
+
+
+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}"
+                )
+
+        ts_errors, ts_warnings = validate_standard_timestamp_columns(
+            cur,
+            table_name,
+            physical_columns=physical_columns,
+        )
+        report.errors.extend(ts_errors)
+        report.warnings.extend(ts_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:
+            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

scripts/db/task_logs_repository.py

@@ -9,7 +9,6 @@ from __future__ import annotations
 from typing import Any, List, Optional, Tuple
 
 from db.connection import get_conn, init_db
-from util.timeutil import now_unix
 
 
 def save_task_log(
@@ -22,17 +21,16 @@ def save_task_log(
     result_summary: Optional[str] = None,
 ) -> int:
     init_db()
-    now = now_unix()
     conn = get_conn()
     try:
         cur = conn.cursor()
         cur.execute(
             """
             INSERT INTO task_logs
-                (task_type, target_id, input_id, input_title, status, error_msg, result_summary, created_at, updated_at)
+                (task_type, target_id, input_id, input_title, status, error_msg, result_summary)
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
             """,
-            (task_type, target_id, input_id, input_title or "", status, error_msg, result_summary, now, now),
+            (task_type, target_id, input_id, input_title or "", status, error_msg, result_summary),
         )
         new_id = int(cur.lastrowid)
         conn.commit()

scripts/db/timestamp_columns.py

@@ -0,0 +1,36 @@
+"""标准时间字段：Unix 秒级时间戳、默认值与 updated_at 自动维护。"""
+
+from __future__ import annotations
+
+STANDARD_TIMESTAMP_COLUMNS = frozenset({"created_at", "updated_at"})
+DATETIME_UNIX_SECONDS = "datetime_unix_seconds"
+TASK_LOGS_UPDATED_AT_TRIGGER = "task_logs_set_updated_at"
+
+_TASK_LOGS_UPDATED_AT_TRIGGER_DDL = f"""
+CREATE TRIGGER IF NOT EXISTS {TASK_LOGS_UPDATED_AT_TRIGGER}
+AFTER UPDATE ON task_logs
+FOR EACH ROW
+BEGIN
+    UPDATE task_logs
+    SET updated_at = unixepoch()
+    WHERE id = NEW.id AND updated_at = OLD.updated_at;
+END
+"""
+
+
+def init_task_logs_timestamp_maintenance(cursor) -> None:
+    """幂等创建 task_logs.updated_at 自动维护 trigger。"""
+    cursor.execute(_TASK_LOGS_UPDATED_AT_TRIGGER_DDL)
+
+
+def has_updated_at_trigger(cursor, table_name: str) -> bool:
+    trigger_name = f"{table_name}_set_updated_at"
+    cursor.execute(
+        """
+        SELECT 1 FROM sqlite_master
+        WHERE type = 'trigger' AND name = ? AND tbl_name = ?
+        LIMIT 1
+        """,
+        (trigger_name, table_name),
+    )
+    return cursor.fetchone() is not None

tests/README.md

@@ -73,6 +73,8 @@ 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`` |
+| 标准时间字段（Unix 秒 / trigger / 元数据） | ``test_timestamp_columns.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`` |

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",

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()

tests/test_timestamp_columns.py

@@ -0,0 +1,336 @@
+# -*- coding: utf-8 -*-
+"""标准时间字段：Unix 秒级时间戳、默认值、trigger 与元数据。"""
+from __future__ import annotations
+
+import sqlite3
+import time
+import unittest
+
+from _support import IsolatedDataRoot
+
+
+class TestTimestampColumns(unittest.TestCase):
+    def test_init_db_creates_integer_timestamp_columns_with_defaults(self) -> None:
+        with IsolatedDataRoot():
+            from db.connection import get_conn, init_db
+            from db.display_metadata import list_physical_column_names
+            from db.display_metadata_validator import _table_column_info
+
+            init_db()
+            conn = get_conn()
+            try:
+                cur = conn.cursor()
+                physical = list_physical_column_names(cur, "task_logs")
+                self.assertEqual(physical[-2:], ["created_at", "updated_at"])
+
+                info = _table_column_info(cur, "task_logs")
+                for column_name in ("created_at", "updated_at"):
+                    column = info[column_name]
+                    self.assertIn("INT", str(column["type"]).upper())
+                    self.assertTrue(str(column["dflt_value"]).lower().find("unixepoch") >= 0)
+            finally:
+                conn.close()
+
+    def test_insert_without_timestamps_auto_generates_unix_seconds(self) -> None:
+        with IsolatedDataRoot():
+            from db.connection import get_conn, init_db
+
+            init_db()
+            conn = get_conn()
+            try:
+                cur = conn.cursor()
+                before = int(time.time())
+                cur.execute(
+                    "INSERT INTO task_logs (task_type, status) VALUES ('auto-ts', 'success')"
+                )
+                conn.commit()
+                cur.execute(
+                    "SELECT created_at, updated_at FROM task_logs ORDER BY id DESC LIMIT 1"
+                )
+                created_at, updated_at = cur.fetchone()
+                after = int(time.time())
+                self.assertIsInstance(created_at, int)
+                self.assertIsInstance(updated_at, int)
+                self.assertGreaterEqual(created_at, before)
+                self.assertLessEqual(created_at, after)
+                self.assertEqual(created_at, updated_at)
+            finally:
+                conn.close()
+
+    def test_update_business_field_keeps_created_at_and_refreshes_updated_at(self) -> None:
+        with IsolatedDataRoot():
+            from db.connection import get_conn, init_db
+
+            init_db()
+            conn = get_conn()
+            try:
+                cur = conn.cursor()
+                cur.execute(
+                    """
+                    INSERT INTO task_logs (task_type, status, created_at, updated_at)
+                    VALUES ('update-ts', 'success', 1000, 1000)
+                    """
+                )
+                log_id = int(cur.lastrowid)
+                conn.commit()
+
+                cur.execute("UPDATE task_logs SET status = 'failed' WHERE id = ?", (log_id,))
+                conn.commit()
+
+                cur.execute(
+                    "SELECT created_at, updated_at FROM task_logs WHERE id = ?",
+                    (log_id,),
+                )
+                created_at, updated_at = cur.fetchone()
+                self.assertEqual(created_at, 1000)
+                self.assertGreater(updated_at, 1000)
+            finally:
+                conn.close()
+
+    def test_reinit_does_not_rewrite_existing_timestamps(self) -> None:
+        with IsolatedDataRoot():
+            from db.connection import get_conn, init_db
+
+            init_db()
+            conn = get_conn()
+            try:
+                cur = conn.cursor()
+                cur.execute(
+                    """
+                    INSERT INTO task_logs (task_type, status, created_at, updated_at)
+                    VALUES ('stable-ts', 'success', 1234567890, 1234567891)
+                    """
+                )
+                conn.commit()
+            finally:
+                conn.close()
+
+            init_db()
+            conn = get_conn()
+            try:
+                cur = conn.cursor()
+                cur.execute(
+                    "SELECT created_at, updated_at FROM task_logs WHERE task_type = 'stable-ts'"
+                )
+                self.assertEqual(cur.fetchone(), (1234567890, 1234567891))
+            finally:
+                conn.close()
+
+    def test_timestamp_metadata_contract(self) -> None:
+        with IsolatedDataRoot():
+            from db.connection import get_conn, init_db
+            from db.display_metadata import DATETIME_UNIX_SECONDS
+
+            init_db()
+            conn = get_conn()
+            try:
+                cur = conn.cursor()
+                cur.execute(
+                    """
+                    SELECT column_name, display_name, display_type, editable, display_order
+                    FROM _jiangchang_columns
+                    WHERE table_name = 'task_logs'
+                      AND column_name IN ('created_at', 'updated_at')
+                    """
+                )
+                by_name = {
+                    name: (display_name, display_type, editable, display_order)
+                    for name, display_name, display_type, editable, display_order in cur.fetchall()
+                }
+                self.assertEqual(by_name["created_at"][0], "创建时间")
+                self.assertEqual(by_name["updated_at"][0], "更新时间")
+                self.assertEqual(by_name["created_at"][1], DATETIME_UNIX_SECONDS)
+                self.assertEqual(by_name["updated_at"][1], DATETIME_UNIX_SECONDS)
+                self.assertEqual(int(by_name["created_at"][2]), 0)
+                self.assertEqual(int(by_name["updated_at"][2]), 0)
+                self.assertIsNone(by_name["created_at"][3])
+                self.assertIsNone(by_name["updated_at"][3])
+            finally:
+                conn.close()
+
+    def test_metadata_upsert_keeps_timestamp_display_type(self) -> None:
+        with IsolatedDataRoot():
+            from db.connection import get_conn, init_db
+            from db.display_metadata import DATETIME_UNIX_SECONDS
+
+            init_db()
+            init_db()
+            conn = get_conn()
+            try:
+                cur = conn.cursor()
+                cur.execute(
+                    """
+                    SELECT display_type FROM _jiangchang_columns
+                    WHERE table_name = 'task_logs' AND column_name = 'created_at'
+                    """
+                )
+                self.assertEqual(cur.fetchone()[0], DATETIME_UNIX_SECONDS)
+            finally:
+                conn.close()
+
+    def test_repository_insert_uses_database_timestamps(self) -> None:
+        with IsolatedDataRoot():
+            from db import task_logs_repository as tlr
+            from db.connection import get_conn, init_db
+
+            init_db()
+            before = int(time.time())
+            new_id = tlr.save_task_log(task_type="repo-ts", status="success")
+            after = int(time.time())
+
+            conn = get_conn()
+            try:
+                cur = conn.cursor()
+                cur.execute(
+                    "SELECT created_at, updated_at FROM task_logs WHERE id = ?",
+                    (new_id,),
+                )
+                created_at, updated_at = cur.fetchone()
+                self.assertGreaterEqual(int(created_at), before)
+                self.assertLessEqual(int(created_at), after)
+                self.assertEqual(created_at, updated_at)
+            finally:
+                conn.close()
+
+    def test_validator_rejects_missing_display_type(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:
+                conn.execute(
+                    "UPDATE _jiangchang_columns SET display_type = NULL WHERE table_name = 'task_logs' AND column_name = 'created_at'"
+                )
+                conn.commit()
+                report = validate_template_database(conn)
+                self.assertFalse(report.ok)
+                self.assertTrue(any("display_type" in err for err in report.errors))
+            finally:
+                conn.close()
+
+    def test_validator_rejects_wrong_timestamp_type(self) -> None:
+        conn = sqlite3.connect(":memory:")
+        try:
+            from db.display_metadata import init_display_metadata
+            from db.display_metadata_validator import validate_display_metadata
+
+            conn.executescript(
+                """
+                CREATE TABLE demo_items (
+                    id INTEGER PRIMARY KEY,
+                    title TEXT,
+                    created_at TEXT
+                );
+                """
+            )
+            init_display_metadata(conn.cursor())
+            conn.execute(
+                """
+                INSERT INTO _jiangchang_tables (table_name, display_name, visible, readonly)
+                VALUES ('demo_items', '演示', 1, 0)
+                """
+            )
+            for column_name, display_name in (
+                ("id", "编号"),
+                ("title", "标题"),
+                ("created_at", "创建时间"),
+            ):
+                conn.execute(
+                    """
+                    INSERT INTO _jiangchang_columns
+                    (table_name, column_name, display_name, visible, searchable, editable, display_type)
+                    VALUES ('demo_items', ?, ?, 1, 0, 0, 'datetime_unix_seconds')
+                    """,
+                    (column_name, display_name),
+                )
+            conn.commit()
+            report = validate_display_metadata(conn)
+            self.assertFalse(report.ok)
+            self.assertTrue(any("created_at 字段类型应为 INTEGER" in err for err in report.errors))
+        finally:
+            conn.close()
+
+    def test_validator_rejects_editable_timestamp(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:
+                conn.execute(
+                    "UPDATE _jiangchang_columns SET editable = 1 WHERE table_name = 'task_logs' AND column_name = 'updated_at'"
+                )
+                conn.commit()
+                report = validate_template_database(conn)
+                self.assertFalse(report.ok)
+                self.assertTrue(any("editable 应为 0" in err for err in report.errors))
+            finally:
+                conn.close()
+
+    def test_validator_does_not_flag_amount_as_timestamp(self) -> None:
+        conn = sqlite3.connect(":memory:")
+        try:
+            from db.display_metadata import init_display_metadata
+            from db.display_metadata_validator import validate_display_metadata
+
+            conn.executescript(
+                """
+                CREATE TABLE demo_items (
+                    id INTEGER PRIMARY KEY,
+                    amount INTEGER,
+                    count INTEGER
+                );
+                """
+            )
+            init_display_metadata(conn.cursor())
+            conn.execute(
+                """
+                INSERT INTO _jiangchang_tables (table_name, display_name, visible, readonly)
+                VALUES ('demo_items', '演示', 1, 0)
+                """
+            )
+            for column_name, display_name in (
+                ("id", "编号"),
+                ("amount", "数量"),
+                ("count", "计数"),
+            ):
+                conn.execute(
+                    """
+                    INSERT INTO _jiangchang_columns
+                    (table_name, column_name, display_name, visible, searchable, editable)
+                    VALUES ('demo_items', ?, ?, 1, 1, 1)
+                    """,
+                    (column_name, display_name),
+                )
+            conn.commit()
+            report = validate_display_metadata(conn)
+            self.assertFalse(any("amount" in err and "display_type" in err for err in report.errors))
+            self.assertFalse(any("count" in err and "display_type" in err for err in report.errors))
+        finally:
+            conn.close()
+
+    def test_trigger_creation_is_idempotent(self) -> None:
+        with IsolatedDataRoot():
+            from db.connection import get_conn, init_db
+            from db.timestamp_columns import TASK_LOGS_UPDATED_AT_TRIGGER, has_updated_at_trigger
+
+            init_db()
+            init_db()
+            conn = get_conn()
+            try:
+                self.assertTrue(has_updated_at_trigger(conn.cursor(), "task_logs"))
+                cur = conn.cursor()
+                cur.execute(
+                    "SELECT COUNT(*) FROM sqlite_master WHERE type = 'trigger' AND name = ?",
+                    (TASK_LOGS_UPDATED_AT_TRIGGER,),
+                )
+                self.assertEqual(int(cur.fetchone()[0]), 1)
+            finally:
+                conn.close()
+
+
+if __name__ == "__main__":
+    unittest.main()