feat: 初始化高校人事请假考勤技能 (process-leave-attendance-default)

基于 skill-template 脚手架开发，包含： - 5 张业务表（教职工、请假政策、考勤日历、请假记录、假期余额） - 请假核算引擎（扣薪计算、审批层级判定、年假抵扣） - CLI 入口（import-employees / calculate-leave / render-html） - HTML 审批与扣薪报告生成 - 示例数据与完整测试套件（295 tests passed）
2026-09-07 16:59:24 +08:00
commit ee2a4d9e22
206 changed files with 29510 additions and 0 deletions
--- a/references/ACTIONS.md
+++ b/references/ACTIONS.md
--- a/references/CELL_PRESENTATION.md
+++ b/references/CELL_PRESENTATION.md
@@ -0,0 +1,210 @@
+# 数据管理单元格呈现（Cell Presentation）契约（v1.0）
+
+> **状态：正式契约 v1.0（`schemaVersion` 1）。**  
+> **目标：** 冻结「技能声明某表某行某列的语义呈现 → 宿主映射主题样式」的通用能力，供任意业务场景复用。  
+> **非目标：** 超时/SLA 专用字段；技能下发任意 CSS / 任意色值；宿主实现业务规则引擎。  
+> **配套 Schema：** [`../assets/schemas/skill-cell-presentation.schema.json`](../assets/schemas/skill-cell-presentation.schema.json)。
+
+相关正交轴见 [`ACTIONS.md`](ACTIONS.md)、[`POLICY.md`](POLICY.md)、[`SCHEMA.md`](SCHEMA.md)。
+
+---
+
+## 0. 一句话
+
+技能可以声明：**哪张业务表、哪一行、哪一列**需要特殊标色/强调（语义 `tone` + 可选说明）。  
+用途不限：时效超时未填、库存预警、状态异常、必填缺失、审核驳回等。  
+**不是**「再加一列超时文字」；强调落在**真正要关注的业务格子**上。
+
+---
+
+## 0.1 能力档位
+
+| 档位 | 技能行为 | 宿主行为 |
+|------|----------|----------|
+| **P0（默认）** | 不写呈现数据 / 未启用 | 数据管理表格与今日一致，无特殊标色 |
+| **P1** | 按规则写入呈现文档或推荐旁路表 | 渲染对应单元格的语义样式；可选汇总 `alert: true` 做进页提醒 |
+
+多数技能保持 **P0**。需要视觉强调时再启用。
+
+---
+
+## 1. 职责边界
+
+| 角色 | 负责 | 不负责 |
+|------|------|--------|
+| **技能** | 按**当前业务数据**算出哪些格子要强调；在数据变更后**重算**并覆盖旧结果 | 不写宿主 CSS；不把强调文案污染进业务真值列冒充「变红」 |
+| **宿主** | 读取呈现结果，按闭集 `tone` 映射主题样式；可选 Toast/提醒汇总 | 不理解「提前 3 天交单」等业务规则；不为单个技能写死样式 |
+
+**派生状态（重要）：** 呈现是计算结果，不是粘性开关。  
+用户补填数据 / 同步刷新后技能重算 → 该项消失 → **样式与提醒自然关闭**。不要单独维护「已关闭提醒」状态机（除非产品另做「忽略此条」能力，本契约不冻结）。
+
+---
+
+## 2. 文档形状（冻）
+
+技能产出一份 **Cell Presentation Document**（可落库、可 CLI 打印，形状相同），须符合 Schema。
+
+```json
+{
+  "schemaVersion": 1,
+  "skill": "process-leave-attendance-default",
+  "table": "business_records",
+  "rowKey": "id",
+  "generatedAt": "2026-08-10T06:00:00Z",
+  "cells": [
+    {
+      "rowId": "42",
+      "column": "qty",
+      "tone": "danger",
+      "message": "库存低于安全线",
+      "alert": true
+    },
+    {
+      "rowId": "42",
+      "column": "status",
+      "tone": "warning",
+      "message": "待审核"
+    }
+  ]
+}
+```
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `schemaVersion` | 是 | 固定 `1` |
+| `skill` | 是 | 与 slug 一致 |
+| `table` | 是 | 当前文档作用的业务表 |
+| `rowKey` | 是 | 行匹配列（`id` / `feishu_record_id` 等） |
+| `generatedAt` | 否 | 排障用 |
+| `cells` | 是 | 数组；**空数组 = 该表清除全部特殊呈现** |
+
+### 2.1 `cells[]` 项
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `rowId` | 是 | `rowKey` 列值的字符串形式 |
+| `column` | 是 | 要强调的**业务列**（snake_case），须真实存在 |
+| `tone` | 是 | 见 §3 |
+| `message` | 否 | 短说明（≤500）；悬停 / 无障碍 |
+| `alert` | 否 | 默认 `false`；`true` 可计入进页/同步提醒汇总 |
+
+同一 `(rowId, column)` 多条：宿主可**后者覆盖前者**。  
+`column` 对用户不可见（policy 打码 / 列隐藏）时：宿主可仍应用样式，或跳过——**推荐跳过不可见列的强调**，避免泄露「有问题」的存在感（技能仍可写，宿主按可见性过滤）。
+
+---
+
+## 3. `tone` 闭集（冻）
+
+| tone | 语义（技能怎么选） | 宿主怎么呈现（示例，主题可调） |
+|------|-------------------|-------------------------------|
+| `danger` | 必须立刻处理 / 已违规 / 严重超时 | 强强调（如浅红底） |
+| `warning` | 即将到期 / 需注意 | 中等强调（如浅黄） |
+| `info` | 提示性标记 | 轻强调（如浅蓝） |
+| `success` | 正向完成态（少用在「待填」场景） | 浅绿等 |
+| `muted` | 弱化 / 次要 | 灰底或灰字 |
+
+**禁止：** 技能下发原始 `#RRGGBB`、任意 CSS class、内联 style。  
+以后若扩展色板，只能**追加新 tone token** 并升契约，不能开放任意色值。
+
+「技能配置什么就显示什么」在本契约中的含义是：技能选择 **哪一格 + 哪个 tone + 什么说明**；**像素级颜色由宿主主题决定**，以保证多技能 UI 一致与安全。
+
+---
+
+## 4. 推荐持久化（给宿主实现）
+
+v1 **推荐**技能将「当前表」的呈现写入用户库旁路表（与业务表分离，**不是**多余业务超时列）：
+
+```sql
+CREATE TABLE IF NOT EXISTS _jiangchang_cell_presentation (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  table_name TEXT NOT NULL,
+  row_key TEXT NOT NULL,
+  row_id TEXT NOT NULL,
+  column_name TEXT NOT NULL,
+  tone TEXT NOT NULL,
+  message TEXT,
+  alert INTEGER NOT NULL DEFAULT 0,
+  generated_at TEXT,
+  updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  UNIQUE (table_name, row_id, column_name)
+);
+```
+
+约定：
+
+- 重算某表时：**先删该 `table_name` 全部行，再插入新结果**（或等价事务替换），保证填完后旧 `danger` 不会残留。  
+- 宿主打开数据管理某表时：若该技能启用了呈现（见 §5）且存在此表，则按当前页行的 `rowKey` 值匹配并着色。  
+- 也允许技能用 CLI 打印整份 Document 供调试；**运行时以库内旁路表为准**（除非后续宿主另定拉取入口）。
+
+未创建该旁路表 = P0，宿主忽略。
+
+---
+
+## 5. 在 `actions.json` 中启用（可选，推荐）
+
+与 `policy` 类似，顶层可选：
+
+```json
+{
+  "schemaVersion": 1,
+  "skill": "process-leave-attendance-default",
+  "cellPresentation": {
+    "enabled": true
+  },
+  "actions": []
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `cellPresentation` | 省略 = P0 |
+| `cellPresentation.enabled` | 仅 `true` 表示宿主应尝试加载呈现；`false`/缺省等同 P0 |
+
+v1 **不**要求单独 CLI entrypoint（与 policy 不同）；技能在 `sync` / 写路径 / `init-db` 后自行维护旁路表即可。若未来需要「仅刷新呈现」Action，用普通 Skill Action 即可，不必扩展本启用块。
+
+---
+
+## 6. 何时重算（技能必须遵守）
+
+至少在以下时机用**同一套 domain 规则**重算并覆盖该表呈现：
+
+1. 全量/增量把外部数据写入本地投影之后（如同步成功）  
+2. 会改变「是否仍需强调」的写路径成功之后（新建、更新、登记等）  
+3. （可选）用户显式「刷新呈现」类 Action  
+
+进页 Toast：宿主可在加载表后统计当前页或全表 `alert=1` 的条数；**0 则不打扰**。  
+提醒关闭 = 重算后没有对应 cell，而不是用户点「我知道了」写死关闭（除非另做忽略列表，本契约不冻）。
+
+---
+
+## 7. 与其它契约的关系
+
+| 契约 | 关系 |
+|------|------|
+| **SCHEMA / `_jiangchang_columns`** | 管列是否可见、类型、中文名；**不管**条件标色 |
+| **POLICY Snapshot** | 管谁能看哪些 Action/行列；呈现仍建议按可见列过滤 |
+| **hostEffects / steps** | 管 Action 跑完后是否 `reloadTable`；重载后宿主应重新读呈现 |
+| **业务列真值** | 保持干净；不要把 `【超时】` 写进业务字段冒充变色 |
+
+---
+
+## 8. 反模式
+
+- 为标色新增「超时环节」「时效状态」等**业务展示冗余列**当作终态方案  
+- 技能下发 CSS / 内联颜色  
+- 只在首次超时时打标、填完不重算导致红字残留  
+- 宿主写死某个技能 slug 的特殊染色逻辑  
+- 把 Cell Presentation 做成仅服务 SLA 的专用协议  
+
+---
+
+## 9. 示例场景（说明用途不限）
+
+| 场景 | column | tone | message 例 |
+|------|--------|------|------------|
+| 打单超时未填 | `print_done_at` | `danger` | 打单已超 1 天未填 |
+| 库存低于安全线 | `qty` | `warning` | 低于安全库存 |
+| 审核驳回 | `status` | `danger` | 已驳回，请修改 |
+| 选填备注缺失但不紧急 | `notes` | `muted` | 建议补充备注 |
+
+完整 JSON 例见 [`../assets/examples/skill-cell-presentation.example.json`](../assets/examples/skill-cell-presentation.example.json)。
--- a/references/CLI.md
+++ b/references/CLI.md
@@ -0,0 +1,88 @@
+# 通用业务技能模板 CLI 标准
+
+将 `{baseDir}` 替换为技能根目录（含 `SKILL.md`、`scripts/` 的目录）。
+
+## 解释器（必读）
+
+必须使用宿主**共享 Python runtime**（`{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`，已在 PATH / `VIRTUAL_ENV`）。一条命令直接跑，不要先探系统 Python。
+
+```bash
+python {baseDir}/scripts/main.py <command> …
+```
+
+| 场景 | 写法 |
+|------|------|
+| **推荐（Agent）** | `python {baseDir}/scripts/main.py <command> …` |
+| 手工排查（环境未注入时） | `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv/Scripts/python.exe`（Windows）或 `…/.venv/bin/python3`（Unix） |
+
+**禁止**对技能脚本使用 `uv run python …`（会创建临时环境，加载不到 `jiangchang-platform-kit` / `jiangchang_skill_core`）。  
+**禁止** Agent 自行 `pip install` / `uv pip install` 往临时环境塞依赖。
+
+## Agent 分流（业务技能复制后必改）
+
+用本表列出**本技能**哪些子命令可走短 CLI，哪些必须走 Skill Action。默认：短查询/只读写本地可用短 CLI；长耗时 / RPA / 需进度取消进**黑名单**。有 async/RPA 的技能：**黑名单不得为空**，且黑名单命令须映射到 `actions.json` 中的 async Action。
+
+| 类型 | 本技能命令（自填） | Agent |
+|------|--------------------|-------|
+| **短 CLI 白名单** | （例）`health` / `version` / `render-html` / `<your-read-or-prep>` | 可用 bash/exec + 共享 `python` |
+| **Action 强制黑名单** | （例）`<your-long-or-rpa-command>` | **禁止** bash + `process poll`；必须 `run_skill_action` |
+
+细节与 Action 清单见 [`ACTIONS.md`](ACTIONS.md)。若提供 HTML 报告，「重新生成」须有 Action id **`render-html`**（可同时进短 CLI 白名单）；见 ACTIONS.md「HTML 页面报告」。
+
+## 最小命令
+
+```bash
+python {baseDir}/scripts/main.py health
+python {baseDir}/scripts/main.py config-path
+python {baseDir}/scripts/main.py version
+python {baseDir}/scripts/main.py init-db
+```
+
+## 标准行为
+
+- **任意 CLI 启动前**执行 `bootstrap_skill_config()`（`main.py` 与 `cli.app.main()` 均触发）。
+- **`health`**：只读 runtime 诊断，**不下载、不修复 media-assets，不执行业务动作**；不输出敏感值。
+- **`config-path`**：输出 JSON，包含 `skill`、`env_path`、`example_path`。
+- **`version`**：输出 JSON（`version`、`skill`）。
+- **`init-db`**：幂等创建/迁移本地 SQLite（含 `_jiangchang_*` 展示元数据）。成功输出一行 JSON（`ok` / `skill` / `db_path`），退出码 `0`。宿主可在技能安装或更新成功后静默调用；不要并入 `health`。
+- **`policy`（可选）**：仅当 `actions.json` 顶层启用 Data Policy 时需要；向 stdout 输出 Snapshot JSON（见 `references/POLICY.md`）。模板默认不实现；多数技能保持 L0 即可。
+- **`run` / RPA / 长任务**：CLI 仍是同一内核；**Agent 禁止**用 bash 干等长任务结束。须走宿主 Skill Action（`run_skill_action`），且该 Action 一般为 `executionProfile: "async"` → **任务中心**。长时间无 stdout **不代表卡死**；进度看任务中心 / Run Journal。
+- **排查顺序**（由快到慢）：
+  1. 任务中心 / Run Journal `{JIANGCHANG_DATA_ROOT}/.jiangchang/runs/{job_id}.jsonl`
+  2. 统一日志文件 `{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/logs/jiangchang.log`（含 `trace_id`、`task_failed` 等）
+  3. 业务表（宿主数据管理；有才建）
+  4. RPA artifacts / `video_log` / 失败截图（开发规范见 `development/RPA.md`）；未开启录屏时可能只有截图或日志
+- **录屏默认关闭**：模板 `.env.example` 为 `OPENCLAW_RECORD_VIDEO=0`；若未开启录屏，任务**可能不会**打印录屏路径。
+- 需要录屏时在用户 `.env` 或进程环境变量中设置 **`OPENCLAW_RECORD_VIDEO=1`**；开启后任务完成时 CLI 应打印录屏路径、录屏日志、视频/音频诊断（见 `task_run_support._print_video_summary`），且 `finish()` 含 video 字段。
+
+## config-path（配置路径）
+
+```json
+{
+  "skill": "process-leave-attendance-default",
+  "env_path": "{DATA_ROOT}/{USER_ID}/process-leave-attendance-default/.env",
+  "example_path": "{skill_root}/.env.example"
+}
+```
+
+## health 标准输出（runtime diagnostics）
+
+`health` 委托 `jiangchang_skill_core.collect_runtime_diagnostics`，典型字段：
+
+- `python_executable` — 当前 Python 解释器路径（应落在共享 python-runtime）
+- `platform_kit_version` / `platform_kit_min_version` / `platform_kit_version_ok`
+- `jiangchang_skill_core_file` — 公共库加载来源（若来自技能目录副本会报 warning）
+- `media_assets_root`、`ffmpeg_path`、`ffmpeg_available`、`background_music_mp3_count`
+- `runtime_issue[warning|error]` — 非致命/致命问题列表
+- `env_path` / `env_exists` / `example_path` — 用户 `.env` 与仓库模板路径
+
+## 通用业务命令骨架
+
+```bash
+python {baseDir}/scripts/main.py run
+python {baseDir}/scripts/main.py run -t <target> -i <input_id>
+```
+
+| 命令 | 用途 | Agent 注意 |
+|------|------|------------|
+| `run` | 执行一次任务（常为长任务 / RPA） | **走 `run_skill_action`**，不要 bash poll |
--- a/references/POLICY.md
+++ b/references/POLICY.md
@@ -0,0 +1,383 @@
+# Skill Data Policy 契约（v1.0）
+
+> **状态：正式契约 v1.0（`schemaVersion` 1）。**  
+> **目标：** 冻结「启用方式 + Snapshot 最小字段 + L2 scope 白名单」，使多数技能（L0）零配置，需要权限的技能（L1/L2）有稳定扩展面。  
+> **非目标：** 宿主实现业务用户/角色库；规定飞书/HTTP/本地表等权限数据源；本期不强制 L3（行态 `visibleWhen` 等）。  
+> **注意：** L3 预留的行态 `visibleWhen` **不是** Action 参数表单的 `inputSchema.properties.*.visibleWhen`（表单控件显隐，见 [`ACTIONS.md`](ACTIONS.md)「字段条件显隐」）。二者同名不同义，勿混用。  
+> **配套 Schema：** [`../assets/schemas/skill-policy-snapshot.schema.json`](../assets/schemas/skill-policy-snapshot.schema.json)；启用块见 [`../assets/schemas/skill-actions.schema.json`](../assets/schemas/skill-actions.schema.json)。
+
+相关正交轴见 [`ACTIONS.md`](ACTIONS.md)。本契约增加第六轴：**policy（当前身份允许什么）**。
+
+---
+
+## 0. 能力档位（必须按此理解）
+
+| 档位 | 技能配置 | 宿主行为 |
+|------|----------|----------|
+| **L0** | 无 `policy`，或 `policy.enabled !== true` | **与今日完全一致**：不拉 Snapshot，不按身份过滤按钮/行/列 |
+| **L1** | `policy.enabled: true`，Snapshot 至少给出 Action 授权 | 数据管理展示 skill Action 前与 allowlist 求交；可选限制宿主内置能力 |
+| **L2** | 在 L1 基础上 Snapshot 带 `data.tables[table]` | 列表查询应用声明式 `rows.scope`；列按 `columns` 投影 |
+| **L3** | （预留，本契约不冻结行为） | 如**行态** `visibleWhen`、菜单级藏表、`rows.mode=delegate` 等（≠ Action 表单 `inputSchema.visibleWhen`） |
+
+**80% 技能停留 L0。** 启用 policy 的技能必须实现约定 CLI，并在写路径自行再鉴权（见 §7）。
+
+---
+
+## 0.1 已冻结最佳实践（v1.0）
+
+| 议题 | 决定 | 技能开发者怎么做 |
+|------|------|------------------|
+| Skill Action 授权模式 | **仅** `allowlist` / `open`；v1 **禁止** `denylist` | 有角色就算出允许的 action id 列表；只控行不控按钮时用 `open` |
+| `hostCapabilities` | **省略 = 不限制**宿主内置；写出则按 allowlist（`[]` = 全禁内置） | 只控业务按钮时**不要写**该字段；要限导出/删除时再显式列出 |
+| scope 运算符 | 保留小白名单（见 §3.4）；**禁止** like/raw/嵌套 | 日常优先 `eq` / `in` / `is_null`；比较符按需 |
+| `valueFrom` | v1 **仅** `actor.userId` | 角色只在技能内用来算 Snapshot，**不要**用 `actor.roles` 做行过滤 |
+
+---
+
+## 1. 启用字段（冻在 `assets/actions.json` 顶层）
+
+`actions.json` 根对象增加**可选**字段 `policy`（与 `schemaVersion` / `skill` / `actions` 同级）。
+
+### 1.1 形状（L0/L1 必冻）
+
+```json
+{
+  "schemaVersion": 1,
+  "skill": "process-leave-attendance-default",
+  "policy": {
+    "enabled": true,
+    "entrypoint": {
+      "type": "cli",
+      "command": "policy",
+      "args": ["--table", "{{table}}"]
+    },
+    "appliesTo": ["data-management"]
+  },
+  "actions": []
+}
+```
+
+| 字段 | 必填 | 冻结说明 |
+|------|------|----------|
+| `policy` | 否 | 缺省 = L0 |
+| `policy.enabled` | 若存在 `policy` 则**必填** | 仅 `true` 启用；`false` 等同 L0 |
+| `policy.entrypoint` | `enabled: true` 时必填 | 与 Action `entrypoint` 同构：`type` 目前仅 `"cli"` |
+| `policy.entrypoint.command` | 是 | 子命令名；**推荐**固定为 `policy` |
+| `policy.entrypoint.args` | 是 | JSON 数组；可含占位符，由宿主替换后再拼接 CLI |
+| `policy.appliesTo` | 否 | 缺省 `["data-management"]`。本期宿主**只实现** `data-management`；其它值忽略但不报错 |
+
+### 1.2 占位符白名单（冻）
+
+| 占位符 | 含义 | 例 |
+|--------|------|----|
+| `{{table}}` | 当前数据管理选中的**物理表名** | `customs_timelines` |
+| `{{skill}}` | 当前技能 slug | 与 manifest `skill` 一致 |
+| `{{userId}}` | 当前宿主用户 id | 与注入的 `JIANGCHANG_USER_ID` 一致 |
+
+未列出的 `{{…}}`：**禁止**；宿主应视为契约错误（fail-closed，见 §6）。
+
+### 1.3 显式不放进启用块的内容（防推翻）
+
+以下**不得**出现在 `actions.json.policy` 中（属于技能内部或 Snapshot）：
+
+- 角色列表、人员表、飞书 app id、外部 IAM URL  
+- 具体 allowlist / scope（那是 Snapshot 的事）  
+- 按角色复制的 Action 定义  
+
+### 1.4 Action 级可选提示（不冻为运行时权威）
+
+允许（文档/静态检查用），**宿主不得仅凭此显隐按钮**：
+
+```json
+"authz": { "capability": "optional.skill.defined.string" }
+```
+
+运行时权威仅为 Snapshot §2 的 `actions`。
+
+---
+
+## 2. Snapshot 最小字段集（`policy` CLI 标准输出）
+
+- 编码：UTF-8 JSON 对象，写在 **stdout**（可先打日志到 stderr/文件，但 stdout 必须是单 JSON）。  
+- 成功退出码 `0`；业务上「无权限看任何东西」仍是 `0` + 合法 Snapshot（例如空 allowlist），不是靠非 0 表示未授权。  
+- 非 0 或非合法 JSON → §6 fail-closed。
+
+### 2.1 根对象（L0 不出现；L1 必冻）
+
+| 字段 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `schemaVersion` | 是 | `integer` | 本期冻结为 **`1`** |
+| `skill` | 是 | `string` | 必须等于 manifest `skill` |
+| `actor` | 是 | `object` | 见 §2.2 |
+| `actions` | 是 | `object` | 见 §2.3 |
+| `hostCapabilities` | 否 | `string[]` | 见 §2.4；**省略 = 不限制宿主内置按钮**（兼容） |
+| `data` | 否 | `object` | 见 §3；省略 = 不限制行/列（L1-only） |
+| `extensions` | 否 | `object` | 技能私有扩展；宿主**必须忽略**未知键 |
+
+根级未知字段：宿主**忽略**；**不得**依赖未写入本契约的字段做安全决策。
+
+### 2.2 `actor`（L1 必冻）
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `userId` | 是 | 非空；应与 `JIANGCHANG_USER_ID` / `{{userId}}` 对齐 |
+| `displayName` | 否 | 展示用 |
+| `roles` | 否 | `string[]`，角色**码**；仅供展示 / 技能自检。**不得**用于 v1 scope 的 `valueFrom` |
+| `attributes` | 否 | `object`，仅允许 JSON 标量值；本期 scope **不**解引用 |
+
+### 2.3 `actions`（L1 必冻）— Skill Action 授权
+
+**最佳实践：** 角色 → 技能内计算 → `allowlist` 的 id 列表。宿主不理解角色名。
+
+```json
+"actions": {
+  "mode": "allowlist",
+  "ids": ["whoami", "create-record", "register-submit"]
+}
+```
+
+| 字段 | 必填 | 冻结取值 |
+|------|------|----------|
+| `mode` | 是 | **仅两值**：`"allowlist"` \| `"open"` |
+| `ids` | `mode=allowlist` 时必填 | `string[]`；元素为 **`actions.json` 里的 action.id** |
+| `ids` | `mode=open` 时 | 必须省略或 `[]`；宿主视为**不限制** skill Action |
+
+规则：
+
+1. 宿主先按现有规则得到候选集：`placements` ∩ `bind.tables`（及 batch 等）。  
+2. 若 `mode=allowlist`：候选 ∩ `ids`。漏配 id = 少按钮（安全侧失败）。  
+3. `ids` 中的未知 id：**忽略**（不报错）。  
+4. `mode=open`：等价「L1 不限制按钮」，可与 L2 行列限制并存。  
+5. **`denylist` 不是 v1 合法值**；出现则 §6 fail-closed。
+
+`replaces` 接管的默认新增/编辑/删除/导入：视为对应 Action 的 id 是否在 allowlist 中；不在则宿主隐藏该接管按钮（导入按钮是否可用还受 `hostCapabilities` 含 `import` 影响）。`mode=open` 时不按 id 限制 replaces。
+
+### 2.4 `hostCapabilities`（L1 可选冻）
+
+控制数据管理**宿主内置**能力，与 skill `action.id` **命名空间分离**。
+
+本期枚举冻结：`refresh` | `export` | `view` | `edit` | `delete` | `import`。
+
+| 写法 | 含义 | 何时用 |
+|------|------|--------|
+| **省略字段** | **不限制**（与今日一致） | **默认推荐**：只控 skill 按钮 / 行数据时 |
+| 写出非空数组 | 仅允许列出的内置能力（allowlist） | 要限导出、删除等时 |
+| 写出 `[]` | 禁止全部上表内置能力 | 极少见；慎用 |
+
+未知字符串：忽略。**禁止**把「省略」解释成全禁。
+
+---
+
+## 3. L2：`data` 与 scope 语法白名单
+
+### 3.1 `data` 形状
+
+```json
+"data": {
+  "tables": {
+    "customs_timelines": {
+      "accessible": true,
+      "columns": {
+        "visible": ["id", "contract_no", "status"],
+        "writable": ["status"]
+      },
+      "rows": {
+        "mode": "scope",
+        "scope": {
+          "all": [
+            { "field": "owner_user_id", "op": "eq", "valueFrom": "actor.userId" }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `data.tables` | 若存在 `data` 则建议有 | `key` = 物理表名 |
+| `accessible` | 否 | 缺省 `true`。`false`：宿主可拒绝打开该表 |
+| `columns.visible` / `writable` | 否 | 物理列名；省略 = 不额外限制 |
+| `rows` | 否 | 见下 |
+
+`writable` 应 ⊆ `visible`；若违规，宿主按交集降级，不 fail-closed。
+
+### 3.2 `rows.mode`（冻）
+
+| 值 | 本期 | 含义 |
+|----|------|------|
+| `scope` | **实现目标** | 宿主将 `scope` 编译为安全查询约束 |
+| `open` | 允许 | 显式不限制行 |
+| `delegate` | **仅占位** | 本期未实现时 fail-closed / 提示；**禁止**当 `open` |
+
+缺省：无 `rows` = `open`。
+
+### 3.3 `scope` 布尔结构（冻）
+
+```text
+Scope =
+  | { "all": Predicate[] }      // AND，长度 ≥ 1
+  | { "any": Predicate[] }      // OR，长度 ≥ 1
+  | Predicate                   // 单个谓词的语法糖
+```
+
+**禁止**：嵌套超过一层。
+
+### 3.4 `Predicate` 白名单（冻）
+
+**运算符（宿主必须实现）：** `eq` | `ne` | `in` | `not_in` | `gt` | `gte` | `lt` | `lte` | `is_null` | `is_not_null`
+
+**推荐日常只用：** `eq` / `in` / `is_null`（及 `is_not_null`）。
+
+**明确排除：** `like` / `contains` / `sql` / `raw` / `expr`。
+
+**`valueFrom` v1 仅：** `actor.userId`。  
+`actor.roles` / `actor.attributes.*` **非法** → fail-closed。
+
+`value` 与 `valueFrom` 互斥。标量：`string` | `number` | `boolean` | `null`（与 null 比较优先用 `is_null`）。
+
+### 3.5 与宿主原有过滤的关系
+
+最终行集 = **原有表查询**（搜索、排序、分页、用户 Filter） **AND** policy `scope`。宿主必须把 scope 下推到查询层。
+
+---
+
+## 4. 宿主消费算法
+
+```text
+IF manifest.policy?.enabled !== true:
+  → L0；END
+
+调用 entrypoint（替换占位符），解析 Snapshot
+IF 失败 / 非法 / skill 不匹配 / mode 非法:
+  → fail-closed（§6）；END
+
+候选 = filter(placements, bind.tables, …)
+IF mode == allowlist: 候选 ∩ ids
+IF mode == open: 候选不变
+
+渲染 skill 按钮 ← 候选
+渲染宿主内置 ← hostCapabilities（省略则不限制）
+应用 data.tables[T]（若有）
+```
+
+拉取时机（建议）：进入表、切换表、刷新。短缓存不得跨 `userId`。
+
+---
+
+## 5. 身份与环境
+
+| 项 | 约定 |
+|----|------|
+| 用户主键 | `JIANGCHANG_USER_ID` |
+| 技能解析 | 飞书 / 本地表 / HTTP IAM 等，**契约不规定** |
+
+---
+
+## 6. Fail-closed（启用后必冻）
+
+当且仅当 `policy.enabled === true`：
+
+| 情况 | 宿主行为 |
+|------|----------|
+| CLI 非 0 / 超时 / 无 JSON | 不渲染该表 skill 写操作与（建议）导出；明确错误；**禁止**回退 L0 全开 |
+| `schemaVersion` ≠ 1 / `skill` 不匹配 / `actions.mode` 非法 | 同上 |
+| `rows.mode=scope` 但 predicate 非法 | 不返回行或整表不可用；**禁止**忽略 scope |
+| `rows.mode=delegate`（未实现） | 提示不支持；**禁止**当 `open` |
+
+---
+
+## 7. 安全边界
+
+1. Snapshot **只**服务宿主 UI 与查询约束。  
+2. 写 Action / 敏感读的 **domain service 必须再次鉴权**。  
+3. 禁止「只藏按钮」宣称为完整权限方案。  
+4. Cron / Agent **不**自动套用本 Snapshot。
+
+---
+
+## 8. 最小示例
+
+模板仓库另有可复制示例：
+
+- [`../assets/examples/skill-policy-snapshot.allowlist.example.json`](../assets/examples/skill-policy-snapshot.allowlist.example.json)
+- [`../assets/examples/skill-policy-snapshot.scope.example.json`](../assets/examples/skill-policy-snapshot.scope.example.json)
+
+### 8.1 L0
+
+不写 `policy` 字段。
+
+### 8.2 L1 allowlist（不碰宿主内置）
+
+```json
+{
+  "schemaVersion": 1,
+  "skill": "process-leave-attendance-default",
+  "actor": { "userId": "u1", "displayName": "张三", "roles": ["clerk"] },
+  "actions": {
+    "mode": "allowlist",
+    "ids": ["whoami", "create-record", "register-submit"]
+  }
+}
+```
+
+### 8.3 L1 + 限制导出
+
+```json
+{
+  "schemaVersion": 1,
+  "skill": "process-leave-attendance-default",
+  "actor": { "userId": "u1", "roles": ["clerk"] },
+  "actions": { "mode": "allowlist", "ids": ["whoami"] },
+  "hostCapabilities": ["refresh", "view"]
+}
+```
+
+### 8.4 L1 open + L2 scope
+
+```json
+{
+  "schemaVersion": 1,
+  "skill": "process-leave-attendance-default",
+  "actor": { "userId": "u1" },
+  "actions": { "mode": "open" },
+  "data": {
+    "tables": {
+      "orders": {
+        "rows": {
+          "mode": "scope",
+          "scope": {
+            "all": [
+              { "field": "owner_user_id", "op": "eq", "valueFrom": "actor.userId" }
+            ]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## 9. 刻意延后
+
+| 项 | 备注 |
+|----|------|
+| `actions.mode: denylist` | 另开 `schemaVersion` |
+| `valueFrom: actor.roles` | **明确不做** |
+| `visibleWhen` / 嵌套 scope / `like` | L3 或永不做（此处指**行态**策略字段；Action 表单 `inputSchema.visibleWhen` 见 ACTIONS.md，不属本表） |
+| `rows.mode: delegate` 宿主实现 | 字段名已占坑 |
+| 平台全局 Role UI / cron·agent 套用 Snapshot | 另议 |
+
+---
+
+## 10. 冻结检查清单
+
+- [x] L0 缺省无歧义  
+- [x] 启用字段仅 `enabled` + `entrypoint` + 可选 `appliesTo`  
+- [x] `actions.mode` 仅 `allowlist` / `open`  
+- [x] `hostCapabilities` 省略 = 不限制  
+- [x] scope 小白名单；`valueFrom` 仅 `actor.userId`  
+- [x] fail-closed；写路径技能自检  
--- a/references/README.md
+++ b/references/README.md
@@ -0,0 +1,27 @@
+# Agent 参考索引
+
+本目录只是 Agent **运行、编排、调用** skill 时可渐进加载的资料索引，**不是**用户市场说明。
+
+**边界规则：**
+
+- 本文**不得**包含 YAML frontmatter，**不得**包含 `description` 字段。
+- 技能市场四 Tab 材料**必须**放在根目录：[`README.md`](../README.md)、[`TUTORIAL.md`](../TUTORIAL.md)、[`DEMO.md`](../DEMO.md)、[`CHANGELOG.md`](../CHANGELOG.md)。
+- **Agent 主读本目录**（`CLI.md` / `ACTIONS.md` / `SCHEMA.md`）与根 [`SKILL.md`](../SKILL.md)。
+- [`../development/`](../development/) 是开发者 / 编码助手深度规范，**不是**对话 Agent 的默认读盘路径。
+
+| 文档 | 用途 |
+|------|------|
+| 根目录 [`README.md`](../README.md) | 市场说明 Tab（`readme_md`） |
+| 根目录 [`TUTORIAL.md`](../TUTORIAL.md) | 市场教程 Tab（`tutorial_md`） |
+| 根目录 [`DEMO.md`](../DEMO.md) | 市场演示 Tab（`demo_video_url` + `demo_md`） |
+| 根目录 [`CHANGELOG.md`](../CHANGELOG.md) | 市场更新日志 Tab（版本小节 → `changelog`） |
+| [`SKILL.md`](../SKILL.md) | LLM / OpenClaw 平台技能入口与触发摘要 |
+| [`CLI.md`](CLI.md) | 共享 Python、命令行入口、参数与短操作契约 |
+| [`ACTIONS.md`](ACTIONS.md) | Skill Action、sync/async、任务中心、多入口、按钮中文名 `label` 参考（按入口定位表挂载；先读 `development/PRODUCT_SURFACES.md`） |
+| [`SCHEMA.md`](SCHEMA.md) | 本地 SQLite 与数据管理展示契约 |
+| [`POLICY.md`](POLICY.md) | Data Policy：可选身份授权、Snapshot、行 scope（多数技能 L0 不配） |
+| [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md) | 数据管理单元格呈现：语义 tone 标色/强调（用途不限；多数技能 P0 不配） |
+| [`WORK_ITEM_STATUS.md`](WORK_ITEM_STATUS.md) | 业务行生命周期：处理队列的可操作/进行中/终态角色与重做规则（有处理行 Action 时适用） |
+| [`../development/`](../development/) | 开发、测试、RPA 深度规范（给人 / 编码助手） |
+
+按需阅读：短操作优先 `CLI.md`；Action / 任务中心读 `ACTIONS.md`；结构化字段读 `SCHEMA.md`；权限 opt-in 读 `POLICY.md`；格子标色读 `CELL_PRESENTATION.md`；队列处理状态机读 `WORK_ITEM_STATUS.md`。
--- a/references/SCHEMA.md
+++ b/references/SCHEMA.md
@@ -0,0 +1,841 @@
+# 数据存储与数据管理展示规范
+
+本文是 skill 本地 SQLite 与匠厂宿主「数据管理」页面展示契约的**权威说明**。
+
+**产品定位：** 数据管理既是业务数据与过程的可见面，也是与对话**平级**的 **UI 执行面**（表上 Action 走同一 CLI 闭环）。何时挂执行入口见 [`../development/PRODUCT_SURFACES.md`](../development/PRODUCT_SURFACES.md)；本文管表结构与展示元数据。
+
+实现上的 DDL 与默认中文元数据种子见 `scripts/db/display_metadata.py`；`scripts/db/connection.py` 的 `init_db()` 会一并初始化。
+
+## 职责边界
+
+### 技能负责
+
+- 定义真实 SQLite 表结构
+- 使用英文 `snake_case` 表名和字段名
+- 使用 `_jiangchang_tables` 提供表级展示元数据
+- 使用 `_jiangchang_columns` 提供字段级展示元数据（含可选 `description` 表单说明、可选 `grid_help` 表格说明）
+- 需要「新增表单预填」时，在物理列上声明 SQLite `DEFAULT`（勿把默认值只写在文案里）
+- 定义哪些字段可见、可搜索、可创建、可编辑
+- 定义字段展示类型和枚举选项
+- （可选）按业务规则维护单元格呈现旁路数据（语义 tone；见 [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md)）
+- 保证元数据与真实数据库结构一致
+- 保证元数据初始化幂等
+
+### 宿主负责
+
+- 读取 `_jiangchang_*` 元数据
+- 读取 SQLite `PRAGMA table_info`
+- **数据管理侧栏/表列表**：当库中存在 `_jiangchang_tables` 时，**仅展示**在该表注册且 `visible=1` 的业务表；孤儿物理表（有表、无注册元数据）**不得**出现在侧栏，直接访问 schema API 应返回「表不存在」。极老库无 `_jiangchang_tables` 时，宿主可保留物理表枚举 fallback（兼容 `_schema_meta` 时代）
+- 根据 schema 渲染数据管理页面
+- 根据 `editable` 推导字段是否可创建或编辑
+- 在**新增 / 编辑**表单中，若列有 `_jiangchang_columns.description`，在标签下方展示该说明（灰字；空则不显示）
+- 在数据管理**表格**中，若表有 `_jiangchang_tables.grid_help` 则在表上方展示可折叠说明；若列有 `_jiangchang_columns.grid_help` 则在列头显示「?」；空/未写则不渲染。**不**把 `description` 当作表格说明
+- 打开**新增**表单时，对可创建字段用 SQLite 列 `DEFAULT`（`PRAGMA table_info.dflt_value`）预填；无 DEFAULT 则留空
+- 执行通用查询、新增、编辑、删除、导入、导出
+- 对字段名、表名、类型和权限进行最终校验
+- 不猜测技能业务含义
+- 不根据具体技能名称写特殊逻辑
+- 可在技能安装/更新成功后静默调用 `python scripts/main.py init-db` 做幂等 ensure（内部即 `init_db()`）；失败不影响安装结果
+- 若技能启用了单元格呈现（见 [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md)），读取旁路呈现数据并为单元格映射语义样式（`tone`）；不猜测业务规则
+
+## 初始化入口
+
+幂等建库/迁移：`python scripts/main.py init-db`。业务仓储也可懒触发 `init_db()`，与 CLI 结果一致。
+
+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`：用户可见的中文业务名称。
+- `description`：能力说明，不是技能名称。
+- `metadata.openclaw.slug`：机器标识，kebab-case 英文；目录名与默认数据库文件名使用 slug。slug 语义规范见 [`../development/NAMING.md`](../development/NAMING.md)。
+- 复制模板后不得将 `process-leave-attendance-default`、`My Skill` 等占位内容作为正式技能发布名称。
+
+## 数据库路径与命名
+
+```text
+{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/{skill-slug}/{skill-slug}.db
+```
+
+- 数据库文件：英文 slug，例如 `process-leave-attendance-default.db`（默认 `{skill-slug}.db`）。
+- 业务表、字段：**英文 snake_case** 物理名，例如 `demo_items`、`created_at`。
+- **禁止**用中文作为 SQLite 真实表名或字段名。
+
+## 外部来源只读与本地数据可写
+
+某些技能会从外部系统读取数据并写入技能自己的本地数据库。需要区分：
+
+```text
+外部来源数据库：
+  可能只读，不应被修改
+
+技能本地数据库：
+  可以根据业务语义允许新增、编辑或删除
+```
+
+不要把「外部来源只读」错误理解成「技能本地数据库一定只读」。技能通过 `_jiangchang_tables.readonly` 与 `_jiangchang_columns.editable` 声明本地表的实际写权限。
+
+若创建/更新/删除/导入带有领域副作用（自动建目录、加密、级联清理、归一化字段），不要依赖宿主默认直写：在 `assets/actions.json` 用可选字段 `replaces: create|update|delete|import` 接管默认按钮。其中 **import** 时用户仍使用宿主「导入数据」面板，确认后由技能写库。详见 [`ACTIONS.md`](ACTIONS.md) 与 `assets/examples/replaces-*.action.example.json`。
+
+## 表与表之间：禁止 SQLite 外键
+
+业务表之间的「属于哪条父记录 / 引用哪条来源」**只存业务 id**（整数或文本标量），**禁止**在 DDL 中写 SQLite `FOREIGN KEY` / `REFERENCES`，也**不要**指望 `PRAGMA foreign_keys = ON` 替你校验或级联。
+
+| 要做的事 | 正确做法 | 禁止 |
+|----------|----------|------|
+| 子表指向父表 | 子表列如 `case_id INTEGER NOT NULL`；写入前在 repository/service 查父表是否存在 | `FOREIGN KEY (case_id) REFERENCES parent(id)` |
+| 父表记「最新一版」 | 父表列如 `latest_draft_id INTEGER NOT NULL DEFAULT 0`；由 service 更新指针 | 同上 |
+| 删除 / 覆盖 / 级联清理 | repository/service 内显式 `DELETE` / `UPDATE`；需要时用 Action `steps` 的 `deleteByFk` | 依赖 DB 级联或宿主 CRUD 被 FK 拦住 |
+| 数据管理里显示名称 | `_jiangchang_columns.display_type = lookup` + `options_json` 对象（见下文「跨表引用 lookup」） | 把 lookup 当成 DDL 外键 |
+
+**为什么：** 宿主数据管理对业务表执行通用增删改，会直接写 SQLite。一旦 DDL 带外键，删除、迁移 rename 父表、或父表 id 变更时极易出现「本地数据操作失败」且难排查。关联语义属于技能业务，必须在代码里写清。
+
+**迁移注意：** 避免「`ALTER TABLE parent RENAME TO parent_old` → 建新 parent → 删 old」这类会隐性改写子表 FK 指向的套路；优先 `ADD COLUMN` + 拷列，或重建子表且**不带** FK。
+
+`display_metadata_validator` 与 `validate_template_database` 会扫描业务表 DDL；含 `FOREIGN KEY` / `REFERENCES` 时报错（见 `development/CHECKLIST.md` A6-6）。
+
+## 标准数据同步语义（外源 → 本地库）
+
+适用于「同步 / refresh / collect」类能力。使用通用名称表述，勿把具体平台表名写进模板实现。
+
+| 要求 | 说明 |
+|------|------|
+| 外部来源默认只读 | 技能不得修改外源 |
+| 本地 SQLite 可事务写入 | 写入走 repository + 事务 |
+| 幂等 | 同一业务键重复同步结果稳定 |
+| 稳定唯一业务键 | 明确 upsert / 匹配字段 |
+| 全量或增量 | 在实现与文档中显式声明 |
+| 完整快照才提交 | 完整性校验通过后再 commit；调用方**必须显式提供**完整性状态（如 keyword-only 必填的 `snapshot_complete`），**禁止**默认视为完整，**禁止**靠数据条数猜测 |
+| 空结果 / 读取失败保护 | 读取失败、分页不完整或不可信空结果（`snapshot_complete=False`）**不得**清库或误删；仅当完整快照**显式确认**为空（`snapshot_complete=True` 且结果为空）时，才可按全量失效策略处理旧数据 |
+| 全量失效策略 | 物理删除、`removed`/`is_active` 标记、或保留历史——必须三选一并写清 |
+| 部分失败 | 不得伪装成整体成功 |
+| 半成品 | 事务失败不得留下可见不一致状态 |
+
+建议统一返回统计：
+
+```json
+{
+  "total": 100,
+  "inserted": 10,
+  "updated": 20,
+  "unchanged": 65,
+  "removed": 5
+}
+```
+
+### 同步数据 vs 导出当前数据表 vs 特殊业务报告 vs HTML 页面
+
+| 能力 | 语义 | 负责方 |
+|------|------|--------|
+| **同步数据** | 外部来源 → 技能本地数据库 | 技能 Action / domain service |
+| **导出当前数据表** | 本地库 → CSV/Excel 等 | 数据管理页**宿主统一导出** |
+| **生成特殊业务报告（文件）** | 多表合并、特殊排版或附加计算的文件 | 仅当系统导出无法满足时，才提供独立 `export-*`；落 `output/` |
+| **HTML 页面报告** | 侧栏可预览的整页 HTML | 写入 `html/` + Action id **`render-html`**（见 [`ACTIONS.md`](ACTIONS.md)） |
+
+同步型 Action 默认只写库、不生成导出文件。兼容旧 export 命令需要刷新时，必须调用同一 sync 内核。可复用测试范式见 `tests/samples/test_sync_contract.py.sample`。
+
+## 元数据表（宿主兼容）
+
+宿主读取字段（与匠厂 `metadata-resolver` 一致）：
+
+### `_jiangchang_tables` 表级标准
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `table_name` | 是 | 真实英文表名 |
+| `display_name` | 是 | 用户可见的中文业务名称 |
+| `description` | 否 | 表说明（表单/备注用途）；**不**用于表格上方横幅 |
+| `grid_help` | 否 | 数据管理表格上方说明；空/未写则不出横幅。与 `description` 独立，禁止互拷（见下节） |
+| `sort_order` | 否 | 兼容保留字段，不用于替代物理字段顺序 |
+| `visible` | 是 | `1` 在宿主数据管理中展示 / `0` 隐藏 |
+| `readonly` | 是 | `1` 整张表只读；`0` 允许宿主根据字段权限执行写操作 |
+| `default_sort_json` | 否 | 数据管理**默认行排序**（见下节）；空则宿主用内置默认 |
+| `default_visible_columns_json` | 否 | 数据管理**默认展示列**（见下节）；空则全显 |
+
+#### 表级默认排序 `default_sort_json`（宿主支持）
+
+技能可声明该表在数据管理中的默认排序；宿主优先采用，未声明或声明无效时回退：
+
+`updated_at DESC` → `created_at DESC` → 主键 DESC。
+
+JSON 数组（可多字段，按顺序）：
+
+```json
+[{"column":"sent_at","direction":"desc"},{"column":"id","direction":"desc"}]
+```
+
+规则：
+
+- `column` 必须是该表真实列名；敏感列会被宿主忽略
+- `direction` 仅 `asc` / `desc`（缺省按 `desc`）
+- 用户在 UI 上手动改排序后，以用户选择为准；声明只影响未选择时的默认
+- 通过 `upsert_table_metadata(..., default_sort_json=...)` 写入；旧库由 `init_display_metadata_tables` 幂等 `ALTER` 补列
+
+示例（消息时间线）：
+
+```python
+upsert_table_metadata(
+    cursor,
+    table_name="messages",
+    display_name="消息",
+    readonly=0,
+    default_sort_json='[{"column":"sent_at","direction":"desc"},{"column":"id","direction":"desc"}]',
+)
+```
+
+#### 表级默认展示列 `default_visible_columns_json`（宿主支持）
+
+技能可声明该表在数据管理表格中的**默认展示列**（软默认，不是硬隐藏）：
+
+- **已配置**：首次打开（用户尚未改过「列」）只显示名单中的列；其余列仍在「列」面板中，用户可勾回
+- **未配置 / 空 / 无效**：显示全部 schema 可见列（与今日行为一致）
+- **用户改过「列」或表头「隐藏此列」后**：以本机偏好为准；「恢复默认列布局」后重新回到技能默认（若有）
+
+JSON 数组（物理列名；也可写 `{"column":"col"}` 对象，宿主同样接受）：
+
+```json
+["stat_type","period","stage","ops_count","timeout_ratio"]
+```
+
+规则：
+
+- 列名必须是该表真实列，且 `_jiangchang_columns.visible=1`（硬隐藏列本来就不进表格）
+- 与 `visible=0` **不同**：`visible=0` = 列从数据管理 schema /「列」面板移除；本字段只影响默认勾选状态
+- 名单为空或全部无效时，宿主 fail-open：全显
+- 通过 `upsert_table_metadata(..., default_visible_columns_json=...)` 写入；旧库由 `init_display_metadata_tables` 幂等 `ALTER` 补列
+
+示例（时效统计：默认不展示编号与时间戳列）：
+
+```python
+upsert_table_metadata(
+    cursor,
+    table_name="timeliness_stats",
+    display_name="时效统计",
+    readonly=1,
+    default_visible_columns_json=(
+        '["stat_type","period","stage","ops_count",'
+        '"timeout_open","timeout_done","timeout_total","timeout_ratio"]'
+    ),
+)
+```
+
+#### 表格说明 `grid_help`（宿主支持）
+
+技能可给数据管理**表格**写说明，与新增/编辑表单的 `description` **完全独立**：
+
+| 写在哪 | 宿主做什么 | 空/未写 |
+|--------|------------|---------|
+| `_jiangchang_tables.grid_help` | 表格上方可折叠横幅（首行摘要；有后续行才出展开） | 不出横幅 |
+| `_jiangchang_columns.grid_help` | 列头「?」，点击查看该列说明 | 不出「?」 |
+
+规则：
+
+- **opt-in**：大多数表/列不需要写；不写则行为与今日一致
+- **禁止**把 `description` 拷进 `grid_help`，也禁止把表格规则写进 `description`（`description` 只给表单灰字）
+- 多行文本时：第一行是摘要，其余行点「展开」后可见
+- 通过 `upsert_table_metadata(..., grid_help=...)` / `upsert_column_metadata(..., grid_help=...)` 写入；旧库由 `init_display_metadata_tables` 幂等 `ALTER` 补列
+- 需已支持该字段的匠厂宿主；更旧版本会忽略未知列，不写则无影响
+
+示例（仅在确有表格规则时写；模板默认业务表不要预填）：
+
+```python
+upsert_table_metadata(
+    cursor,
+    table_name="timeliness_records",
+    display_name="时效登记",
+    readonly=1,
+    grid_help="超时按环节规则判定。\n交单：预计到港日前 3 天须交单",
+)
+upsert_column_metadata(
+    cursor,
+    table_name="timeliness_records",
+    column_name="submit_date",
+    display_name="交单日期",
+    grid_help="预计到港日前 3 天须交单",
+    editable=0,
+)
+```
+
+禁止：
+
+- 使用中文真实表名
+- 使用 `_schema_meta` 作为新的正式契约
+- 只写英文物理名而不写中文 `display_name`
+- 让元数据引用不存在的表
+- 用 `visible=0` 假装「默认不展示但用户还能勾出来」（那是硬隐藏，勾不回来）
+
+### `_jiangchang_columns` 字段级标准
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `table_name` | 是 | 所属物理表 |
+| `column_name` | 是 | 真实英文字段名 |
+| `display_name` | 是 | 用户可见的中文字段名（表头与表单标签）；保持简短 |
+| `description` | 否 | 字段说明（给人看的短文案）；**宿主在新增/编辑表单标签下方展示**（见下节）；不要塞进 `display_name` |
+| `grid_help` | 否 | 数据管理表头「?」；空/未写则不出。与表单 `description` 独立，禁止互拷 |
+| `display_order` | 否 | 兼容字段，默认保持 `NULL` |
+| `visible` | 是 | 是否进入数据管理 schema /「列」面板（`0` = **硬隐藏**，用户无法勾回；默认不展示但可勾回请用表级 `default_visible_columns_json`） |
+| `searchable` | 是 | 是否参与**列筛选**与**顶栏全局搜索**（`0` = 两者均不参与）；详见下节「数据管理：列筛选与全局搜索」 |
+| `editable` | 是 | `1` 业务字段允许宿主用于新增和编辑；`0` 系统/只读字段 |
+| `display_type` | 否 | 字段渲染类型；稳定取值见下节「表单与展示：稳定字段类型」 |
+| `options_json` | 否 | 枚举选项 JSON |
+
+这两张表是**数据字典**，不是业务数据；宿主不会把它们当作普通业务表展示。
+
+#### 表单与展示：稳定字段类型（宿主支持，须与 Action 对称）
+
+数据管理「新增 / 编辑」表单与 Skill Action 参数表单应使用**同一套控件语义**（配置入口不同，见 [`ACTIONS.md`](ACTIONS.md)）。新技能只使用下表；宿主须两边都实现，避免「Action 有、CRUD 没有」。
+
+**本版稳定支持（须齐）：**
+
+| `display_type`（CRUD） | 物理类型建议 | 列表展示 | 新增/编辑控件 | 存库约定 |
+|------------------------|--------------|----------|---------------|----------|
+| `text`（或缺省） | `TEXT` / 一般标量 | 原文 | 单行文本 | 原文 |
+| `textarea` | `TEXT` | 原文（可截断） | 多行文本 | 原文 |
+| `json` | `TEXT` | 原文 | 多行文本（JSON 字符串） | 原文；提交时宿主可做基础 JSON 合法性校验 |
+| `number` | `INTEGER` / `REAL` / `NUMERIC` | 原文 | **数字输入**（`type=number`） | 数字；无 `display_type` 时，物理类型为 INT/REAL/NUMERIC 也应走数字控件 |
+| `boolean` | `INTEGER` 0/1 或 BOOL | 开关语义展示 | 开关 | `0` / `1` |
+| （枚举） | 任意 + `options_json` **数组** | 标签映射 | 下拉选择 | 选项 `value` |
+| `lookup` | 跨表引用 id；`options_json` **对象**；可选 `multiple` | 单选：标签映射；多选：多标签（如「豆包、元宝」） | 单选下拉；多选见下文 | 单选：业务 id 标量；多选：`TEXT` 逗号分隔 id（非 SQLite 外键） |
+| （敏感） | 任意；列 `sensitive=1` | 掩码/隐藏策略由宿主定 | 新建可用密码框；编辑策略与既有宿主一致 | 原文（勿日志明文） |
+| `date` | `TEXT` 推荐 `YYYY-MM-DD`，或可安全归一的值 | 日期 | **日期选择**（日） | `YYYY-MM-DD` |
+| `datetime_unix_seconds` | `INTEGER` | `YYYY-MM-DD HH:mm:ss` | **日期时间选择**；提交写回 **Unix 秒** | Unix **秒**整数；禁止改成 ISO 字符串 |
+| `url` | `TEXT` | 原文（可作链接） | 单行输入 `type=url`（薄层；校验从宽） | 原文 |
+| `email` | `TEXT` | 原文 | 单行输入 `type=email`（薄层；校验从宽） | 原文 |
+
+说明灰字与创建默认值见下一小节；与 Action 的对照写在 [`ACTIONS.md`](ACTIONS.md)「表单字段类型对照」。
+
+**明确不在本版稳定范围（勿在新技能宣传为已支持）：**
+
+- 文件 / 图片上传
+- 复杂 `oneOf` / nested object 表单（任意 JSON 数组当业务多选控件）
+- 把业务可编辑时间存成毫秒、ISO 文本或 SQLite `datetime` 文本（审计字段规范见「标准时间字段」）
+
+> **Lookup 多选**已纳入本版契约（见下文 `multiple`），与「任意多选/标签数组」不是同一能力。
+
+`datetime_unix_milliseconds`：仅兼容**列表展示**旧数据；**新技能不要用**；可编辑时间一律 `datetime_unix_seconds`。
+
+#### 新增/编辑表单：字段说明与默认值（宿主支持）
+
+数据管理「新增记录 / 编辑记录」与 Skill Action 弹窗是**两套表单**；CRUD 侧约定如下（交互对齐 Action 的 `inputSchema.description` / `default`，但**配置入口不同**）。
+
+| 能力 | 技能写什么 | 宿主做什么 |
+|------|------------|------------|
+| 字段说明 | `_jiangchang_columns.description`（可选） | 新增/编辑表单中，在标签下方以灰字展示；空则不显示 |
+| 创建默认值 | 物理列 SQLite `DEFAULT`（如 `limit_n INTEGER NOT NULL DEFAULT 0`） | 打开「新增」时，对可创建字段预填该默认值；无 DEFAULT 则留空 |
+| 编辑已有行 | — | **不**用 DEFAULT 覆盖已有行数据 |
+| 表格列头标题 | `display_name` | 短名；不要把长说明塞进列头文字 |
+| 表格列头「?」 | `_jiangchang_columns.grid_help`（可选） | 有内容才显示「?」；**不**回退 `description` |
+| 表格上方说明 | `_jiangchang_tables.grid_help`（可选） | 有内容才显示横幅；**不**回退表级 `description` |
+
+规则与禁止：
+
+- **推荐**对易填错、语义特殊的可编辑字段写 `description`（示例链接、`0` 表示不限制等）；非强制每个字段都有
+- **禁止**把说明硬塞进 `display_name`（如 `评论上限(0不限)`）；表头会变脏，也无法与 Action 说明对齐
+- 业务语义（如「0 = 不限制」）写在 `description` 里；宿主只展示，**不**解读业务含义
+- 第一期**不**新增元数据「表单默认值」列；CRUD 默认值 = DDL `DEFAULT`，与 Action 的 `inputSchema.default` 分开配置
+- 同一业务字段若同时出现在 Action 与新增表单，**文案应对齐**（短标题 + 说明），但分别写在 `actions.json` 与 `_jiangchang_columns` / DDL
+- 数字类可编辑列推荐 `display_type: "number"`（或依赖 INT/REAL/NUMERIC 推断）并在 DDL 写清 `DEFAULT`（如条数上限默认 `0`）
+
+示例（可编辑列种子 + DDL 默认）：
+
+```sql
+-- 物理列：创建默认 0
+comment_limit INTEGER NOT NULL DEFAULT 0
+```
+
+```python
+seed_column_metadata_batch(
+    cursor,
+    table_name="videos",
+    columns=(
+        {
+            "column_name": "video_url",
+            "display_name": "视频链接",
+            "editable": 1,
+            "display_type": "url",
+            "description": "填平台视频页链接；需包含可识别的视频路径片段。",
+        },
+        {
+            "column_name": "comment_limit",
+            "display_name": "采集评论条数",
+            "editable": 1,
+            "display_type": "number",
+            "description": "最多采多少条。填 0 = 不限制；填正整数则按该数量封顶。",
+        },
+    ),
+    valid_column_names=physical,
+)
+```
+
+Action 参数表单的 `title` / `description` / `default` / `display_type` 见 [`ACTIONS.md`](ACTIONS.md)；勿与本节 CRUD 配置入口混用。
+
+#### 数据管理：列筛选与全局搜索（宿主支持）
+
+数据管理表格提供两类与 `searchable` 相关的检索能力，技能通过 `_jiangchang_columns.searchable` 声明是否参与：
+
+| 能力 | 用户入口 | `searchable = 1` 时 | `searchable = 0` 时 |
+|------|----------|---------------------|---------------------|
+| **列筛选** | 表格「筛选」→ 字段 / 操作符 / 值 | 出现在「字段」下拉，可按类型选值与操作符 | 不出现在列筛选字段列表 |
+| **全局搜索** | 顶栏搜索框 | 参与 OR 模糊匹配（宿主对参与列数有上限，如最多 8 列） | 不参与全局搜索 |
+
+**存库 vs 展示（核心契约）**
+
+- **列表**：有 `options_json` 时展示 **label**（如「启用」「停用」）
+- **筛选 / 查询 / 全局搜索**：比较与匹配 **value**（如 `0`/`1`、`active`、`toutiaohao`）
+- 宿主负责 label ↔ value 映射；**禁止**为迁就 UI 把存库改成中文枚举，也**禁止**在 `description` 里写「筛选请填 0/1」
+
+**筛选栏控件 ≠ 新增/编辑表单（勿混用）**
+
+列筛选「值」与表单使用同一套**类型语义**，但控件形态不同：筛选栏须与「字段」「操作符」同一行工具栏对齐（如统一 `h-9` 下拉），**枚举 / boolean / lookup 在筛选栏一律用下拉 Select**，不用新增/编辑表单里的开关或横向分段单选。表单侧仍按上表「新增/编辑控件」配置。
+
+| 列类型 | 筛选「值」控件 | 常用操作符（宿主按类型裁剪） | 技能须配置 |
+|--------|----------------|------------------------------|------------|
+| 文本 / `url` / `email` | 文本框 | 等于 / 包含 / 开头 / 结尾 / 为空… | 通常 `searchable: 1` |
+| 数字 | 数字框 | 等于 / 大于 / 小于… | `display_type: number` 或 INT/REAL |
+| 枚举（`options_json` **数组**） | 下拉（展示 label） | 等于 / 不等于 / 为空 | **`options_json` 必填** + `searchable: 1` |
+| `boolean` | 下拉（有 `options_json` 用其 label；否则宿主默认可选「是/否」） | 等于 / 不等于 / 为空 | `display_type: boolean`；**推荐同时写 `options_json`** 指定中文 label |
+| `lookup` 单选 | 下拉 | 等于 / 不等于 / 为空 | `display_type: lookup` + lookup 对象 |
+| `lookup` + `multiple: true` | 列筛选 UI 演进中；**全局搜索**已支持 | 等于时按逗号分隔 id 的 token 匹配 | 多选存 `TEXT` 逗号分隔 id |
+| `date` / `datetime_unix_seconds` | 日期 / 日期时间 | 比较类 | 时间列通常 `searchable: 0` |
+| 敏感列 | **不可筛** | — | 宿主强制排除 |
+
+**全局搜索扩展（用户可搜中文）**
+
+宿主在 `searchable = 1` 的列上除原文 `LIKE` 外，还应：
+
+- 有 `options_json` 枚举：**label 或 value** 均可命中
+- `boolean` 无 options：认「是/否」等常见别名
+- `lookup` 多选：按逗号分隔 id 的 **token 边界** 匹配；选项 label 亦可参与
+- `datetime_unix_seconds`：搜 `YYYY-MM-DD` 形态可匹配当天 Unix 秒区间
+
+**技能配置建议**
+
+推荐：
+
+- 用户常筛的状态列（启用/停用、待生成/已生成、`status` 等）→ `searchable: 1` + `options_json`（value 与 DDL 存库一致）
+- `boolean` 业务列：`display_type: boolean` **且** `options_json` 写中文 label（示例见下）
+
+禁止：
+
+- 仅为筛选把存库 value 改成中文
+- 在文档或 `description` 要求用户记内部 magic number / 英文 code
+
+示例（启用开关 + 中文筛选）：
+
+```python
+{
+    "column_name": "enabled",
+    "display_name": "是否启用",
+    "visible": 1,
+    "searchable": 1,
+    "editable": 1,
+    "display_type": "boolean",
+    "options_json": json.dumps(
+        [{"value": 0, "label": "停用"}, {"value": 1, "label": "启用"}],
+        ensure_ascii=False,
+    ),
+}
+```
+
+Action 参数表单**无**列筛选对称能力；筛选语义以本节为准，表单对照见 [`ACTIONS.md`](ACTIONS.md)「表单字段类型对照」。
+
+## editable 与 createable 的关系
+
+技能模板只维护 `editable` 这一份字段权限声明：
+
+```text
+skill metadata:
+  editable
+
+host runtime:
+  createable / editable
+```
+
+宿主根据以下因素计算字段是否能够出现在新增或编辑表单中：
+
+- 表级 `readonly`
+- 字段 `editable`
+- 主键
+- generated 字段
+- sensitive 字段
+- BLOB 类型
+- not-null 约束
+- default value
+
+通用规则：
+
+```text
+新增表单：
+  editable = 1
+  且不是主键
+  且不是 generated
+  且不是敏感字段
+  且不是 BLOB
+
+编辑表单：
+  editable = 1
+  且不是主键
+  且不是 generated
+  且不是敏感字段
+  且不是 BLOB
+```
+
+若一张表：
+
+```text
+readonly = 0
+但所有字段 editable = 0
+```
+
+则：
+
+- 这张表技术上可写，但不适合手工新增或编辑
+- 宿主不应打开空白新增表单
+- 技能应通过自身业务流程产生数据
+- 这不是宿主猜测业务，而是技能通过元数据声明的结果
+
+## 系统字段标准
+
+通常保持 `editable = 0` 的字段类型包括：
+
+- 自增主键
+- generated 字段
+- `created_at` / `updated_at`
+- 同步时间戳
+- 内容哈希
+- 计算结果
+- 内部状态
+- 删除标记
+- 审计字段
+- 敏感凭据或密钥字段
+
+不要把具体业务字段名写死；按字段类型和职责设置 `editable`。
+
+## 表结构标准
+
+- 业务表和字段使用英文 `snake_case`
+- 可写表优先使用单字段主键
+- 自增主键优先放在 `CREATE TABLE` 第一列
+- `created_at` 和 `updated_at` 放在业务字段末尾
+- 字段展示顺序以 `CREATE TABLE` 和 `PRAGMA table_info(cid)` 为准
+- 不依赖 `display_order` 重新排列字段
+- 不要让宿主通过英文字段名推断展示顺序
+- 复杂字段需要通过 `display_type` 或 `visible` 明确处理
+
+推荐顺序（可按业务裁剪，但已有字段应遵守相对位置）：
+
+```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` |
+
+### 业务可编辑时间 vs 审计时间
+
+| 场景 | `editable` | 列表 | 新增/编辑表单 |
+|------|------------|------|----------------|
+| `created_at` / `updated_at` 等审计列 | `0` | 格式化为 `YYYY-MM-DD HH:mm:ss` | 不出现（或只读，由宿主既有规则） |
+| 业务时间列（预约、截止、活动开始等） | `1` | 同上格式化 | **日期时间控件**；提交写入 Unix **秒**整数 |
+
+宿主对 `display_type = datetime_unix_seconds`：
+
+- **列表**：格式化为 `YYYY-MM-DD HH:mm:ss` 展示，**不**改库内原始整数
+- **可编辑表单**：提供日期时间选择；保存时写回 Unix **秒**（不要写 ISO 字符串、不要写毫秒）
+
+### 自动生成与维护
+
+- **created_at**：`INTEGER NOT NULL DEFAULT (unixepoch())`；插入时可省略，由数据库生成。
+- **updated_at**：`INTEGER NOT NULL DEFAULT (unixepoch())`；插入时同样可省略。
+- **updated_at 更新**：业务表通过 SQLite trigger `{table}_set_updated_at` 在业务字段更新后自动刷新（`init_updated_at_trigger`）。
+
+实现参考：
+
+- DDL 与 trigger：`scripts/db/connection.py`、`scripts/db/timestamp_columns.py`
+- 中文元数据种子：`scripts/db/display_metadata.py`
+- 自检：`scripts/db/display_metadata_validator.py`
+
+### 系统自动写入表的只读约定
+
+技能内部**系统自动写入**、不供用户在宿主数据管理中手工维护的表，应声明：
+
+| 层级 | 值 | 说明 |
+|------|-----|------|
+| 表级 `readonly` | `1` | 宿主数据管理只读展示，不提供新增/编辑/删除表单 |
+| 相关业务字段 `editable` | `0` | 元数据权限只约束宿主 UI，不限制技能代码写库 |
+
+模板**默认不建**此类审计表。过程看 `jiangchang.log`，进度/终态看任务中心，业务结果看业务表。
+
+### 业务行生命周期（处理队列）
+
+若技能对某一业务行做「生成 / 触达 / 私信 / 发布」等有副作用处理，状态字段须遵守 **角色模型**（可操作 / 进行中 / 成功·失败·跳过类终态），**不要**把某一技能的状态名当成全平台唯一枚举。默认只处理可操作态；重做靠人工改回可操作。完整规则见 [`WORK_ITEM_STATUS.md`](WORK_ITEM_STATUS.md)。
+
+建议：
+
+| 项 | 说明 |
+|----|------|
+| 状态列 | `options_json` 列出本技能全部业务状态（含进行中与各类终态） |
+| 失败原因 | 失败类终态应有用户可读的原因字段（勿写密钥） |
+| 可编辑 | 终态/进行中建议可改回可操作，或提供等价 Action |
+| `grid_help` | 可一句话说明「仅某某状态可处理」 |
+
+表级 `readonly = 1` 时，宿主数据管理只读展示；技能 repository 仍可写入。
+
+### 通用示例：`demo_items`（测试 fixture 参考）
+
+以下表结构用于模板测试演示数据管理契约，**不是**模板默认业务表：
+
+```sql
+CREATE TABLE demo_items (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    title TEXT NOT NULL,
+    description TEXT,
+    status TEXT NOT NULL DEFAULT 'draft',
+    generated_value TEXT,
+    created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+    updated_at INTEGER NOT NULL DEFAULT (unixepoch())
+);
+```
+
+对应元数据要点：
+
+| 物理字段 | editable | 说明 |
+|----------|----------|------|
+| id | 0 | 自增主键 |
+| title | 1 | 业务字段 |
+| description | 1 | 业务字段 |
+| status | 1 | 枚举，`options_json` 演示 |
+| generated_value | 0 | 系统/计算字段 |
+| created_at | 0 | 系统时间 |
+| updated_at | 0 | 系统时间 |
+
+## 枚举字段 options_json
+
+`options_json` 支持两种形态：
+
+### 1）静态枚举（数组）
+
+每项包含 `value` 与 `label`：
+
+```json
+[
+  {"value": "draft", "label": "草稿"},
+  {"value": "published", "label": "已发布"},
+  {"value": "archived", "label": "已归档"}
+]
+```
+
+宿主据此渲染选择框；技能侧负责保证 JSON 合法且与物理字段取值一致。
+
+### 2）跨表引用 lookup（对象，用于关联 id 字段）
+
+当字段取值依赖同库另一张业务表时，`display_type` 设为 `lookup`，`options_json` 写对象（**不是**数组）。这是**展示与表单选择**契约，**不是** SQLite 外键。
+
+**单选（默认，与既有行为一致）：**
+
+```json
+{
+  "ref_table": "platforms",
+  "value_column": "platform_key",
+  "label_column": "display_name",
+  "extra_column": "category",
+  "filter_column": "enabled",
+  "filter_value": 1
+}
+```
+
+**多选（平行扩展，仅多一个开关）：**
+
+```json
+{
+  "ref_table": "engines",
+  "value_column": "id",
+  "label_column": "display_name",
+  "filter_column": "enabled",
+  "filter_value": 1,
+  "multiple": true
+}
+```
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `ref_table` | 是 | 同库被引用表名（snake_case 标识符） |
+| `value_column` | 是 | 写入当前字段的值列（业务 id / 编号） |
+| `label_column` | 是 | 选项主文案列（名称） |
+| `extra_column` | 否 | 第三展示列（不必叫「备注」）；有值时拼进括号 |
+| `filter_column` / `filter_value` | 否 | 等值过滤（如只列出 `enabled=1`） |
+| `multiple` | 否 | `true` = 多选 Lookup；省略或 `false` = **单选**（默认） |
+
+宿主在加载表 schema 时查询 `ref_table`，把结果展开成 `{value,label}` 选项列表。
+
+**存库约定：**
+
+| 模式 | 物理列建议 | 存什么 |
+|------|------------|--------|
+| 单选 | 整数或文本标量 | 一个业务 id（如 `2`、`douyin`） |
+| 多选 | **`TEXT`** | 逗号分隔 id，如 `1,2,5`（与 `$selection.ids` 风格一致）；**不要**建联接子表当 UI 多选 |
+
+**统一展示文案（宿主固定一种，技能只配列）：**
+
+- 单选默认：`{value} · {label}`，例如 `2 · 通用私信-留资`、`douyin · 抖音`
+- 配置了 `extra_column` 且该行有非空值：`{value} · {label}（{extra}）`
+- 未配置 `extra_column`、或额外列为空：不加 `（）`
+- `label` 为空或与 `value` 相同时：只显示 `value`（可再带额外括号）
+- **多选列表格**：按 id 拆开后逐个映射为 label，再用顿号/逗号拼接（如 `豆包、元宝`）；过长可截断并提示「+N」
+
+**控件呈现（宿主策略，非第二套契约）：**
+
+- 单选：下拉 Select（现状）
+- 多选且选项较少（建议 ≤6）：勾选列表
+- 多选且选项较多：字段内 Chip + 可搜索下拉（**不是**再开一层业务弹窗）
+
+Action 弹窗内联 Lookup 与上表 **同构**（字段名一致，含 `multiple`），见 [`ACTIONS.md`](ACTIONS.md)「跨表引用：Lookup」。
+
+示例：账号表的平台字段 → 平台信息表；凭据表的账号编号 → 账号信息表；私信 Action 选话术 → `message_templates`；抽检 Action 多选引擎 → `engines` + `multiple: true`。
+
+## 幂等初始化标准
+
+- `_jiangchang_tables` 和 `_jiangchang_columns` 必须通过 upsert 初始化
+- 多次执行初始化不能重复记录
+- 重新初始化可以更新展示名、描述、`grid_help`、`visible`、`searchable`、`editable`、`display_type`、`options_json`
+- 元数据不能残留旧字段（删除或重命名字段时必须同步清理）
+- 元数据不能引用不存在的表或字段
+- 新增字段或表时必须同步增加元数据
+- 不要直接修改用户真实数据库作为迁移方式
+
+实现 helper：
+
+- `upsert_table_metadata` / `upsert_column_metadata` — 幂等写入
+- `seed_column_metadata_batch` — 批量 upsert；**可选**传入 `valid_column_names` 时在 upsert 后自动 prune
+- `prune_stale_column_metadata` — 清理已删除物理字段的元数据
+
+### 新增业务表时如何初始化
+
+1. 在 `connection.py`（或迁移脚本）中 `CREATE TABLE` 真实物理表。
+2. 用 `PRAGMA table_info` 或 `list_physical_column_names` 取得**真实物理字段列表**（顺序以 `cid` 为准）。
+3. 调用 `upsert_table_metadata` 写入表级元数据。
+4. 调用 `seed_column_metadata_batch`，并传入 `valid_column_names=physical_column_names`：
+
+```python
+from db.display_metadata import list_physical_column_names, seed_column_metadata_batch, upsert_table_metadata
+
+physical = list_physical_column_names(cursor, "demo_items")
+upsert_table_metadata(cursor, table_name="demo_items", display_name="示例记录", readonly=0)
+seed_column_metadata_batch(
+    cursor,
+    table_name="demo_items",
+    columns=DEMO_ITEMS_COLUMN_METADATA,
+    valid_column_names=physical,
+)
+```
+
+传入 `valid_column_names` 时：先 upsert，再删除不在物理表中的陈旧 `_jiangchang_columns` 行。
+
+### 字段删除或重命名时如何清理
+
+1. 在 DDL / 迁移中完成物理字段删除或重命名。
+2. 重新执行 `seed_column_metadata_batch(..., valid_column_names=当前物理字段列表)`，自动 prune 旧字段元数据。
+3. 或单独调用 `prune_stale_column_metadata(cursor, table_name, valid_column_names)`。
+
+**不传入 `valid_column_names` 时不会自动 prune**——模板不会猜测真实物理字段，避免误删；文档与实现均以此为准。
+
+不要直接修改用户真实数据库作为迁移方式；元数据初始化必须使用真实物理字段列表。
+
+## 表增删改与退役（技能 schema 迁移）
+
+技能拥有 SQLite 物理 schema；宿主只渲染**已注册**的元数据。增删改表时技能须在 `init_db()` 中做幂等迁移，并与 `_jiangchang_*` 同步。
+
+| 操作 | 技能必须做 |
+|------|------------|
+| **新增**用户可见表 | `CREATE TABLE` + `upsert_table_metadata` + 列元数据种子 |
+| **修改**表/列 | 物理迁移（`ALTER` / 重建）+ 更新或 `prune_stale_column_metadata` |
+| **临时隐藏**（表仍保留） | 元数据 `visible=0`（表与元数据行都保留） |
+| **永久废弃**用户可见表 | `drop_deprecated_user_table(...)`（见下） |
+
+### 永久废弃用户可见表
+
+使用 `scripts/db/display_metadata.py` 的 **`drop_deprecated_user_table`**（幂等）：
+
+1. `DROP TRIGGER`（若有 `{table}_set_updated_at` 等）
+2. `DROP TABLE IF EXISTS`
+3. `DELETE` 对应 `_jiangchang_columns` / `_jiangchang_tables` 行
+
+```python
+from db.display_metadata import drop_deprecated_user_table
+
+def init_db() -> None:
+    ...
+    drop_deprecated_user_table(cur, "task_logs")
+    init_display_metadata(cur)
+```
+
+**反模式（禁止）：** 只删 `_jiangchang_*` 元数据、保留物理表。宿主虽可能不展示孤儿表，但库内残留、自检失败，且违背「元数据与物理结构一致」。
+
+**新技能禁止**创建或写入 `task_logs` 一类通用任务审计表。过程 → `jiangchang.log` / 运行日志；进度/终态 → 任务中心；业务结果 → 业务表（见 [`WORK_ITEM_STATUS.md`](WORK_ITEM_STATUS.md)、[`../development/LOGGING.md`](../development/LOGGING.md)）。
+
+### 旧库迁移测试（废弃表时必做）
+
+复制 `tests/samples/test_table_deprecation_migration.py.sample`，构造「旧库含废弃表 + 元数据 + 历史行」→ `init_db()` 后断言：
+
+- `sqlite_master` 无该表
+- `_jiangchang_*` 无残留行
+- `iter_user_tables` 不含该表
+
+卸载技能**不删**用户数据目录；重装会复用旧库，迁移必须在 `init_db()` 中完成（见 [`../development/DATA_PATHS.md`](../development/DATA_PATHS.md)）。
+
+## 中文命名质量
+
+- 使用普通用户能理解的业务用语：`error_msg` → **错误信息**，`created_at` → **创建时间**。
+- 禁止：`Task Logs`、`input编号`、`errormsg`、直接把物理名当 `display_name`。
+- 不宜向用户暴露的实现细节（如 `payload_json`、`selector`）应设 `visible = 0` 或给出可理解中文名。
+
+## 元数据同步规则
+
+1. 新增用户可见业务表 → 同步 `_jiangchang_tables`（`visible=1` 方可在数据管理展示）。
+2. 新增用户可见字段 → 同步 `_jiangchang_columns`。
+3. 删除/重命名表或字段 → 物理迁移 + 同步清理元数据；**废弃表**用 `drop_deprecated_user_table`，禁止只删元数据留物理表。
+4. 初始化脚本必须幂等。
+5. 元数据中的表、字段必须在库中真实存在；可见项不得缺少中文 `display_name`。
+6. `init_db()` 后：`iter_user_tables` 中每个物理业务表都应有对应 `_jiangchang_tables.display_name`，或已被 `drop_deprecated_user_table` 物理删除。
+
+## 开发自检
+
+- `init_db()` 后运行 `tests/test_display_metadata.py` 与 `tests/test_data_management_contract.py`。
+- 若提供宿主 Action 入口，运行 `tests/test_actions_manifest.py`。
+- 复制为真实技能后，使用 `scripts/db/display_metadata_validator.py` 中的校验函数检查 SKILL 名称、slug 与元数据完整性。
+
+## 模板原则
+
+- 模板不做复杂历史迁移框架；新 skill 从当前 schema 起步。
+- 元数据 DDL 与种子 helper 以 `scripts/db/display_metadata.py` 为单一权威来源。
+- 模板定义「如何声明能力」；具体技能定义「声明什么业务能力」；宿主负责「如何通用渲染和执行」。
--- a/references/WORK_ITEM_STATUS.md
+++ b/references/WORK_ITEM_STATUS.md
@@ -0,0 +1,157 @@
+# 业务行生命周期契约（Work Item Lifecycle）
+
+> **状态：正式契约 v1.0。**  
+> **目标：** 冻结「对某一行做有副作用处理」时的**状态角色与操作权**规则，使队列型技能（生成、触达、私信、发布等）行为一致、可验收。  
+> **非目标：** 规定某一技能的具体状态码或状态个数；强制所有表都有 status；替代任务中心 / 运行日志；规定 Data Policy 授权。  
+> **适用范围：** 有「处理业务行」类 Action 的技能。纯配置表、目录表、只读展示表标 N/A。
+
+相关正交轴：[`ACTIONS.md`](ACTIONS.md)（入口与 sync/async）、[`SCHEMA.md`](SCHEMA.md)（表与展示）、[`POLICY.md`](POLICY.md)（谁能点）、任务中心（宿主 Job）。
+
+---
+
+## 0. 为什么需要本契约
+
+若「处理这一行」的按钮对**任意状态**都可点，会出现：
+
+- 已成功的行被重复执行（重复发信、重复生成、覆盖产物）
+- 失败行被默认批量静默重试，运营无法区分「未做」与「做过但失败」
+- 任务中心显示成功，业务表仍停在初始态（结果未回写）
+
+本契约要求：**默认可自动操作的只有「可操作」角色；其它角色须人工改回可操作后再处理。**
+
+---
+
+## 1. 状态角色（通用，不绑死枚举）
+
+技能自己定义业务状态字符串与中文标签；契约只认**角色**。一个角色可对应**一个或多个**业务状态。
+
+| 角色 | 含义 | 默认可被处理 Action 捞起？ |
+|------|------|---------------------------|
+| **operable（可操作）** | 尚未成功处理、允许自动或行操作启动处理 | **是（默认唯一）** |
+| **in_progress（进行中）** | 已抢占，正在处理 | **否**（防双跑） |
+| **terminal_success（成功类终态）** | 已按业务定义完成 | **否** |
+| **terminal_failure（失败类终态）** | 已尝试且失败；通常带失败原因 | **否** |
+| **terminal_skipped（跳过类终态）** | 人工放弃或不处理 | **否** |
+
+### 1.1 举例（仅对照，不是规范枚举）
+
+| 角色 | 技能 A（内容队列）可能叫 | 技能 B（线索触达）可能叫 |
+|------|--------------------------|--------------------------|
+| operable | 待生成、新建 | 新建、私信未发 |
+| in_progress | 生成中 | 触达中 |
+| terminal_success | 已生成 | 已私信 |
+| terminal_failure | 失败 | 触达失败 |
+| terminal_skipped | 已跳过 | 已忽略 |
+
+技能可以有更多业务状态（审核中、待确认、部分成功等）：须在需求里写明各自映射到哪一角色，或声明「不属于处理队列、本契约 N/A」。
+
+### 1.2 技能必须声明映射
+
+复制模板后，在 `development/REQUIREMENTS.md`（或等价需求）中写清：
+
+```text
+处理队列表：<table>
+状态字段：<column>
+可操作：<status1>, <status2>, …
+进行中：<status…>
+成功类终态：…
+失败类终态：…（失败原因字段：…）
+跳过类终态：…
+```
+
+未声明映射的「处理队列」技能，交活 Checklist 不得标 PASS。
+
+---
+
+## 2. 硬规则（技能实现必须遵守）
+
+1. **默认只认 operable**  
+   行操作 / 批量 / 定时 / Agent 触发的「处理」类 Action，pick 与 claim **默认**只包含可操作状态。  
+   不得把成功、失败、跳过、进行中混进默认捞取集合（除非另做**显式命名**的「重试失败」类 Action，且确认文案写清范围——仍推荐不如人工改回可操作简单）。
+
+2. **开始即原子抢占 → in_progress**  
+   在真正产生副作用前，用「仅当当前为 operable 时 UPDATE 为进行中」的方式抢占。抢占失败 → 跳过或返回明确错误（如「当前不是可操作状态」），**禁止**继续副作用。
+
+3. **结束必须回写业务表**  
+   - 成功 → 对应成功类终态，并写入产物路径/摘要等业务字段（若有）  
+   - 失败 → 对应失败类终态，并写入**失败原因**（用户可读；勿塞密钥）  
+   - 禁止「任务中心成功、业务行仍停在可操作/进行中」而不回写
+
+4. **重做靠人工改回 operable**  
+   成功 / 失败 / 跳过 / 卡住的进行中，默认不能再点处理。运营在数据管理把状态改回可操作后，方可再次处理。
+
+5. **任务中心 ≠ 业务状态**  
+   Job「进行中 / 成功 / 失败」是宿主任务态。业务「进行中」必须写在业务表。进度 `emit` 不替代状态回写。
+
+6. **过程与结果分工**（延续既有约定）  
+   过程 → 运行日志 / 任务中心 Activity；业务结果 → 业务表。**不要**靠新建 `task_logs` 一类审计表充当状态机。
+
+---
+
+## 3. Action 与文案约定
+
+- 处理类 Action 的 `description` / `confirmation.message` 应写明：**仅处理「可操作」状态**（用本技能用户能懂的词，如「仅待生成」「仅新建」）。
+- 对非可操作行触发时：返回明确失败码与中文说明，提示「请先改回 xxx」。
+- 长任务（`async`）：除任务中心进度外，业务行应尽快进入进行中，避免界面长时间仍显示可操作导致连点。
+
+正交提醒：
+
+| 轴 | 管什么 | 不管什么 |
+|----|--------|----------|
+| 本契约 | 什么**状态**能处理 | 谁有权点按钮 |
+| Data Policy | 谁有权 | 状态机 |
+| executionProfile | sync/async 通道 | 业务终态 |
+
+---
+
+## 4. 数据管理展示建议
+
+- 状态列：`options_json` 枚举完整业务状态（含进行中与各类终态）。
+- 失败原因列：失败类终态可见；成功后宜清空或保留末次原因（技能自定，须一致）。
+- 终态与进行中的状态字段建议 **可编辑**（或提供「改回可操作」Action），以便人工重做；**不要**只能靠删行重建。
+- `grid_help` 可一句话写清：「仅某某状态可处理；其它状态请改回后再操作。」
+
+详见 [`SCHEMA.md`](SCHEMA.md)。
+
+---
+
+## 5. 可观测性（与 ACTIONS / 日志约定对齐）
+
+推荐阶段（名称可自定，须能对应到开始 / 关键节点 / 结束）：
+
+1. 已抢占（业务 → 进行中）  
+2. 处理中关键步骤（可 `emit`）  
+3. 回写成功或失败  
+
+故意失败一条时：业务表应为失败类终态 + 原因；任务中心为失败；日志含 `task_failed` / `error_code=`。
+
+---
+
+## 6. 非目标与常见误区
+
+| 误区 | 正确做法 |
+|------|----------|
+| 把「新建/成功/失败/跳过」写成全平台唯一枚举 | 只用角色；各技能自定状态名 |
+| 默认批量包含失败「方便自动重试」 | 默认不含；重试改回可操作或单独显式 Action |
+| 只有任务成功、不改业务状态 | 必须回写业务表 |
+| 用进行中替代任务中心 | 两者都要：业务防双跑，任务轨看进度 |
+| 所有表都套本契约 | 无「处理行」副作用的表标 N/A |
+
+---
+
+## 7. 验收摘要（完整条目见 CHECKLIST）
+
+有处理队列时至少验证：
+
+1. 成功类终态再点处理 → 拒绝或跳过，不产生重复副作用  
+2. 可操作行处理中 → 先见进行中，结束后见成功或失败+原因  
+3. 失败行改回可操作后 → 可以再次处理  
+4. 任务中心有过程（长任务）且业务表状态与结果一致  
+
+---
+
+## 8. 版本
+
+| 版本 | 说明 |
+|------|------|
+| v1.0 | 首版：角色模型 + 硬规则 + 需求映射 + 与 Action/SCHEMA/任务中心边界 |