Release skill-template v1.0.99: table registry contract and drop_deprecated_user_table

CHANGELOG.md

@@ -9,6 +9,24 @@
 - 小节正文写用户能看懂的变化（新能力、修复、注意事项），避免堆砌内部实现细节
 - 打 tag 前**必须**为即将发布的版本新增一节；找不到匹配小节时，本次发布不会更新 changelog 字段
 
+## 1.0.99
+
+- 沉淀数据管理**表注册门禁**契约：存在 `_jiangchang_tables` 时，宿主仅展示注册且 `visible=1` 的表；孤儿物理表不展示（匠厂宿主 ≥6.8.25）
+- 新增「表增删改与退役」：`drop_deprecated_user_table()` 标准迁移；禁止只删元数据留物理表；新技能禁止 `task_logs`
+- `LOGGING.md` 可观测性三分法；`DATA_PATHS.md` 卸载不删用户数据；Checklist A6-13 / A6-14；`tests/samples/test_table_deprecation_migration.py.sample`
+
+## 1.0.98
+
+- 沉淀数据管理**列筛选与全局搜索**契约：`searchable` 同时控制列筛选字段列表与顶栏全局搜索；存库 value / 展示 label 分工；筛选栏枚举/boolean/lookup 用下拉 Select（与表单开关/分段单选区分）
+- 全局搜索：options label 映射、boolean 别名、lookup 多选 token、`datetime_unix_seconds` 日期区间
+- `ACTIONS.md` 表单对照表补充「列筛选」脚注；`CHECKLIST` A6-11 / A6-12；`display_metadata_validator` 对未开 searchable 的枚举/boolean 列软 warning
+
+## 1.0.97
+
+- 沉淀数据管理 HTML 预览**布局契约**：`references/ACTIONS.md` 新增「宿主预览布局」（流体铺满 iframe、禁横向滚动、表格断行等）
+- 升级 `assets/html/example-report.html` 为通用布局基线；`test_html_page_service` 守护不退化
+- `DEVELOPMENT.md` / `CHECKLIST`（S0-12、A6-10）/ `TESTING.md` 交叉引用
+
 ## 1.0.96
 
 - 在 `references/ACTIONS.md` 沉淀数据管理技能按钮中文名（`label`）参考表：同类通用动作用同一动词，不是白名单

SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: 技能开发模板（通用业务版）
 description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。"
-version: 1.0.96
+version: 1.0.99
 author: 深圳匠厂科技有限公司
 metadata:
   openclaw:

assets/README.md

@@ -1,7 +1,7 @@
 # assets
 
 - `actions.json`：Skill Action manifest 最小示例（按入口定位表决定是否保留/扩展；见 `development/PRODUCT_SURFACES.md`）。每个 action **必须**显式声明 `executionProfile`（`sync` \| `async`）。默认仅 `health` / `version` / `config-path`，不放 toolbar，故无 `bind` 示例。
-- `html/example-report.html`：HTML 报告页最小壳（`{{TITLE}}` / `{{GENERATED_AT}}` / `{{BODY}}`）；渲染后须写入数据目录 `html/`，见 `references/ACTIONS.md`「HTML 页面报告」。
+- `html/example-report.html`：HTML 报告页最小壳（`{{TITLE}}` / `{{GENERATED_AT}}` / `{{BODY}}`）；含数据管理 iframe 预览布局基线（流体铺满、禁横向滚动）；渲染后须写入数据目录 `html/`，见 `references/ACTIONS.md`「HTML 页面报告」。
 - `examples/`：CLI 成功输出形状示例、以及 `render-html.action.example.json`（虚构路径与数据）。
 - `schemas/`：轻量 JSON Schema（`skill-actions.schema.json` 为**新技能严格规范**）。
 

assets/html/example-report.html

@@ -11,17 +11,31 @@
       --muted: #64748b;
       --card: #ffffff;
       --line: #e2e8f0;
+      --page-pad-x: clamp(14px, 2.5vw, 24px);
+      --page-pad-y: clamp(12px, 2vw, 20px);
     }
     * { box-sizing: border-box; }
-    html { overflow-y: auto; }
-    body {
+    html {
+      width: 100%;
+      height: 100%;
       margin: 0;
+      overflow-x: hidden;
+      overflow-y: auto;
+    }
+    body {
+      width: 100%;
+      min-height: 100%;
+      margin: 0;
+      overflow-x: hidden;
       font-family: "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
       background: var(--bg);
       color: var(--ink);
+      line-height: 1.5;
     }
     header {
-      padding: 20px 24px 8px;
+      padding: var(--page-pad-y) var(--page-pad-x) 8px;
+      background: var(--card);
+      border-bottom: 1px solid var(--line);
     }
     header h1 {
       margin: 0 0 6px;
@@ -34,7 +48,23 @@
       font-size: 13px;
     }
     main {
-      padding: 8px 24px 28px;
+      width: 100%;
+      min-width: 0;
+      padding: var(--page-pad-y) var(--page-pad-x) 28px;
+    }
+    .section {
+      margin-bottom: 18px;
+    }
+    .section h2 {
+      margin: 0 0 8px;
+      font-size: 13px;
+      font-weight: 650;
+      color: var(--muted);
+    }
+    .meta {
+      margin: 0 0 10px;
+      color: var(--muted);
+      font-size: 12px;
     }
     .card {
       background: var(--card);
@@ -44,6 +74,35 @@
       line-height: 1.6;
       font-size: 14px;
     }
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      table-layout: fixed;
+      background: var(--card);
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      overflow: hidden;
+      font-size: 13px;
+    }
+    th, td {
+      padding: 8px 10px;
+      border-bottom: 1px solid var(--line);
+      text-align: left;
+      vertical-align: top;
+      word-break: break-word;
+      overflow-wrap: anywhere;
+    }
+    th {
+      background: #f8fafc;
+      font-weight: 600;
+      color: var(--muted);
+      font-size: 12px;
+    }
+    tr:last-child td { border-bottom: none; }
+    /*
+      宿主数据管理在 iframe 内预览本页：应横向铺满可用宽度，仅纵向滚动。
+      复杂看板可在 {{BODY}} 内使用 .section / table；布局底线见 references/ACTIONS.md「宿主预览布局」。
+    */
   </style>
 </head>
 <body>

development/CHECKLIST.md

@@ -60,6 +60,7 @@ checklist_version: 1.0
 - [ ] S0-9 **入口定位表**（见 `PRODUCT_SURFACES.md` / `REQUIREMENTS` §0.1）：已填写 / 未填写
 - [ ] S0-10 本技能宣称的主用户路径涉及：对话 / 数据管理（执行或仅展示） / 定时（可多选；与定位表一致）
 - [ ] S0-11 **业务行生命周期**（见 `references/WORK_ITEM_STATUS.md` / `REQUIREMENTS` §0.3）：有处理队列且已声明状态→角色映射 / 不适用
+- [ ] S0-12 **HTML 页面报告**（见 `references/ACTIONS.md`「HTML 页面报告」）：有侧栏可预览的 `html/*.html` + `render-html` / 不适用
 
 ---
 
@@ -134,6 +135,11 @@ checklist_version: 1.0
 - [ ] A6-7 **P0** 有「处理业务行」类 Action 时（见 `WORK_ITEM_STATUS.md`）：默认只处理**可操作**角色状态；成功/失败/跳过/进行中再点处理应拒绝或跳过且不产生重复副作用；重做须人工改回可操作。无处理队列 → **N/A**
 - [ ] A6-8 **P0** 同上适用时：开始处理后业务表进入**进行中**；成功回写成功类终态；失败回写失败类终态且**失败原因**可读（任务成功但业务行仍停在可操作/进行中 → **FAIL**）
 - [ ] A6-9 **P1** 同上适用时：`REQUIREMENTS` §0.3（或等价）已填写本技能状态→角色映射；处理类 Action 确认文案写清仅可操作态
+- [ ] A6-10 **P1** 有 HTML 侧栏预览时（S0-12）：预览区横向铺满、无横向滚动条；重新生成后内容与页头时间更新；布局符合 `references/ACTIONS.md`「宿主预览布局」。无 HTML 报告 → **N/A**
+- [ ] A6-11 **P1** 业务**状态 / 启用类**列若用户需要筛表或顶栏搜中文：`searchable: 1` 且 `options_json`（或 `boolean` + `options_json`）的 **value 与存库一致**；仅 `searchable: 0` 则宿主不提供列筛与全局搜索。见 `references/SCHEMA.md`「列筛选与全局搜索」
+- [ ] A6-12 **P2** `display_type: boolean` 的展示列推荐同时配置 `options_json` 中文 label（如 停用/启用），避免仅靠宿主默认「是/否」；无 boolean 列 → **N/A**
+- [ ] A6-13 **P0** 新技能**不得**创建 `task_logs`；过程/进度/业务结果走运行日志、任务中心、业务表（见 `LOGGING.md`、`SCHEMA.md`）
+- [ ] A6-14 **P0** 废弃用户可见表时：`drop_deprecated_user_table` 物理删表 + 清元数据；**禁止**只删元数据留物理表；有迁移时须提供旧库回归测试（见 `SCHEMA.md`、`tests/samples/test_table_deprecation_migration.py.sample`）
 
 ---
 

development/DATA_PATHS.md

@@ -176,6 +176,10 @@ DOWNLOAD_OUTPUT_DIR=./outputs/videos
 - `tests/test_runtime_paths.py` 覆盖 `resolve_data_path` / `resolve_input_path`。
 - `POLICY-DATA-PATH-001`：禁止 `.env.example` 中 `./` 路径；禁止业务代码 `abspath(config.get(...))`。
 
+### 卸载技能与数据保留
+
+宿主**卸载技能只删除安装目录**（如 `.openclaw/skills/{slug}`），**不会**删除 `{JIANGCHANG_DATA_ROOT}/{user_id}/{skill_slug}/` 下的 SQLite、输入输出与日志。重装会复用同一用户库；schema 迁移须在 `init_db()` 中幂等完成（见 [`../references/SCHEMA.md`](../references/SCHEMA.md)「表增删改与退役」）。
+
 ---
 
 ## 9. 相关文档

development/DEVELOPMENT.md

@@ -590,7 +590,7 @@ cmd_stats()                 # 只读 sync：JSON，无 job_context
 - 批量数量用 **`pickCount` / `--pick N` 参数**（任意正整数），不写死条数。
 - **顺序执行、不并发**同一浏览器 Profile / account lease。
 - **同步数据**与**宿主表导出**职责分离：同步不写 CSV/Excel；表导出交给数据管理。
-- **HTML 页面报告**（可选）：需要侧栏预览整页时，写入 `html/` + Action `render-html`；契约见 [`../references/ACTIONS.md`](../references/ACTIONS.md)「HTML 页面报告」、[`DATA_PATHS.md`](DATA_PATHS.md)；薄写入 helper 见 `scripts/service/html_page_service.py`。
+- **HTML 页面报告**（可选）：需要侧栏预览整页时，写入 `html/` + Action `render-html`；契约见 [`../references/ACTIONS.md`](../references/ACTIONS.md)「HTML 页面报告」（含**宿主预览布局**底线）、[`DATA_PATHS.md`](DATA_PATHS.md)；薄写入 helper 见 `scripts/service/html_page_service.py`。建议从 `assets/html/example-report.html` 复制壳；`{{BODY}}` 内数据须转义；样式升级后提醒用户重新生成。
 - 详情见 [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md)；契约样例见 `tests/samples/test_sync_contract.py.sample`、`tests/samples/test_action_core_contract.py.sample`。
 
 ### 队列 + pick（可选）

development/LOGGING.md

@@ -122,9 +122,15 @@ RPA 等待用 `interruptible_sleep`，**不要**裸 `asyncio.sleep`（否则暂
 
 Journal 会写入 `type: lifecycle` 事件（`paused` / `resumed` / `stopping`），供宿主任务中心显示状态。
 
-### 2.3 业务表（可选，不是默认排障通道）
+### 2.3 可观测性三分法（禁止 task_logs）
 
-模板**默认不建**任务审计表。业务结果写入各技能自己的业务表；过程看 `jiangchang.log`，进度/终态看任务中心。
+| 信息类型 | 去哪里 | 技能怎么做 |
+|----------|--------|------------|
+| **过程**（步骤、异常栈、排查） | `jiangchang.log` / 宿主「运行日志」 | `log.info` / `log.exception`，关键节点见 §3 |
+| **进度 / 终态**（任务中心） | Run Journal：`emit` / `finish` | `job_context` + `finish(status=...)` |
+| **业务结果** | 业务表字段（status、产物路径、统计等） | repository 回写；见 [`WORK_ITEM_STATUS.md`](../references/WORK_ITEM_STATUS.md) |
+
+模板**默认不建** `task_logs` 等通用任务审计表。**不要**用业务表冒充任务进度，也不要用任务表代替业务状态机。
 
 ### 2.4 RPA video step / artifacts（用户可见动作与存证）
 

development/TESTING.md

@@ -35,6 +35,7 @@
 - **发布打包守护**：[`tests/test_release_packaging_constraints.py`](../tests/test_release_packaging_constraints.py) ——`scripts/**/*.py` 单文件 < 1000 行、文本文件 UTF-8 without BOM。
 - **开发规范守护（hard policy）**：[`tests/test_development_policy_guard.py`](../tests/test_development_policy_guard.py) ——规则索引见 [`development/POLICY_MATRIX.md`](POLICY_MATRIX.md)，只执行可机器检测的 hard 规则。
 - **slug 语义**：[`tests/test_slug_naming.py`](../tests/test_slug_naming.py) ——verb-noun-platform 命名规范校验。
+- **HTML 报告壳**：[`tests/test_html_page_service.py`](../tests/test_html_page_service.py) 守护 `assets/html/example-report.html` 的数据管理 iframe 预览布局基线；业务技能若有自定义 `assets/html/*.html`，建议在自有仓库加同类静态断言（见 `references/ACTIONS.md`「宿主预览布局」）。
 
 **原则：`tests/test_*.py` 不允许隐形访问外网、不允许拉起真实浏览器、不允许读写开发者机器的真实数据根**。如果需要仿真服务器，也应仅在 integration（并由档位变量放行）。
 

references/ACTIONS.md

@@ -740,7 +740,25 @@ HINT: <next step>
 | `steps` | `afterSuccess` → **`refreshCatalog`**（重扫 `htmlPages`；不要只 `reloadTable`） |
 | `entrypoint` | CLI 子命令（如 `render-html`）调用同一写入内核 |
 
-完整 JSON 形状见 [`../assets/examples/render-html.action.example.json`](../assets/examples/render-html.action.example.json)。最小页面壳见 [`../assets/html/example-report.html`](../assets/html/example-report.html)。
+完整 JSON 形状见 [`../assets/examples/render-html.action.example.json`](../assets/examples/render-html.action.example.json)。最小页面壳见 [`../assets/html/example-report.html`](../assets/html/example-report.html)（已含数据管理 iframe 预览的布局基线；复制后可按需扩展 `{{BODY}}` 内结构）。
+
+### 宿主预览布局
+
+数据管理在 **iframe** 内预览 `html/*.html`；宿主 iframe 已占满右侧预览区，**技能页不应再人为收窄正文**（尤其数据管理窗口通常较窄）。
+
+| 级别 | 约定 |
+|------|------|
+| **必须** | 页面横向**铺满** iframe 可用宽度：`main { width: 100%; min-width: 0; }` |
+| **必须** | **禁止** `main`（或等价正文容器）使用 `max-width: Npx` 且**无** `margin: 0 auto`（宽屏会左对齐留白；窄宿主窗浪费横向空间） |
+| **必须** | `html` / `body` 设 `overflow-x: hidden`；滚动以**纵向**为主，避免横向滚动条 |
+| **必须** | 写入 `{{BODY}}` 的业务数据经 `html.escape`（或等价）转义，防 XSS |
+| **应当** | `header` 与 `main` 水平内边距一致（如共用 CSS 变量或 `clamp()`） |
+| **应当** | 多列表格：`width: 100%` + 单元格 `word-break` / `overflow-wrap`，长文本在格内换行 |
+| **应当** | KPI / 卡片网格用 `repeat(auto-fit, minmax(…, 1fr))` 等流体列，勿死写固定列数 |
+| **禁止** | 在 `<td>` 上用 `max-width` 限制「说明列」等业务列（易导致列宽异常或横向溢出） |
+| **禁止** | 依赖外链 CSS/JS 或 `networkidle` 式加载（iframe `sandbox` 仅 `allow-scripts`；页面应自包含） |
+
+长文阅读型报告若确需版心，可对整个 `main` 使用 `max-width` **且** `margin: 0 auto`，并令 `header` 与 `main` 同宽；**数据看板类**默认不设 `max-width`。
 
 ### 实现要点
 
@@ -753,6 +771,7 @@ HINT: <next step>
 ### 验收（复制后自测）
 
 - [ ] `html/` 下出现 `.html`，数据管理侧栏能看到报告项，预览正常
+- [ ] 预览区**横向铺满**、**无横向滚动条**；拖窄侧栏后内容自适应（见上节「宿主预览布局」）
 - [ ] 表顶栏（若声明 toolbar）或报告右键「重新生成」能跑通；成功后预览刷新
 - [ ] 未登录/无权限用户被拒绝，且有可读错误
 - [ ] 成功路径带 `refreshCatalog`（或等价让侧栏/预览看到更新）
@@ -852,8 +871,9 @@ Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件
 | 默认值 | `default` | SQLite 列 `DEFAULT` |
 | 只读 | `readOnly: true` | 列 `editable: 0` / 宿主只读规则 |
 | **条件显隐** | **`visibleWhen`**（见下节） | **本版 CRUD 无对称**；仅 Action / 定时任务参数表单 |
+| **列筛选「值」** | **无对称**（Action 无表格筛选） | 见 [`SCHEMA.md`](SCHEMA.md)「数据管理：列筛选与全局搜索」：枚举 / boolean / lookup 在筛选栏用**下拉 Select**（非开关、非分段单选）；存库仍用 value，展示与搜索认 label |
 
-**本版不做（勿宣传）：** 文件上传、复杂 `oneOf` / nested object 专用表单；`visibleWhen` 多条件 AND/OR 树、跨 Action 依赖、CRUD 新增/编辑对称显隐。  
+**本版不做（勿宣传）：** 文件上传、复杂 `oneOf` / nested object 专用表单；`visibleWhen` 多条件 AND/OR 树、跨 Action 依赖、CRUD 新增/编辑对称显隐；Action 参数表单的列筛选对称。  
 （**Lookup 多选**已支持：同一 `lookup` + `multiple: true`，见上文；不是任意标签数组。）
 
 日期时间约定：

references/SCHEMA.md

@@ -25,6 +25,7 @@
 
 - 读取 `_jiangchang_*` 元数据
 - 读取 SQLite `PRAGMA table_info`
+- **数据管理侧栏/表列表**：当库中存在 `_jiangchang_tables` 时，**仅展示**在该表注册且 `visible=1` 的业务表；孤儿物理表（有表、无注册元数据）**不得**出现在侧栏，直接访问 schema API 应返回「表不存在」。极老库无 `_jiangchang_tables` 时，宿主可保留物理表枚举 fallback（兼容 `_schema_meta` 时代）
 - 根据 schema 渲染数据管理页面
 - 根据 `editable` 推导字段是否可创建或编辑
 - 在**新增 / 编辑**表单中，若列有 `_jiangchang_columns.description`，在标签下方展示该说明（灰字；空则不显示）
@@ -287,7 +288,7 @@ upsert_column_metadata(
 | `grid_help` | 否 | 数据管理表头「?」；空/未写则不出。与表单 `description` 独立，禁止互拷 |
 | `display_order` | 否 | 兼容字段，默认保持 `NULL` |
 | `visible` | 是 | 是否进入数据管理 schema /「列」面板（`0` = **硬隐藏**，用户无法勾回；默认不展示但可勾回请用表级 `default_visible_columns_json`） |
-| `searchable` | 是 | 是否参与搜索 |
+| `searchable` | 是 | 是否参与**列筛选**与**顶栏全局搜索**（`0` = 两者均不参与）；详见下节「数据管理：列筛选与全局搜索」 |
 | `editable` | 是 | `1` 业务字段允许宿主用于新增和编辑；`0` 系统/只读字段 |
 | `display_type` | 否 | 字段渲染类型；稳定取值见下节「表单与展示：稳定字段类型」 |
 | `options_json` | 否 | 枚举选项 JSON |
@@ -382,6 +383,76 @@ seed_column_metadata_batch(
 
 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` 这一份字段权限声明：
@@ -700,6 +771,48 @@ seed_column_metadata_batch(
 
 不要直接修改用户真实数据库作为迁移方式；元数据初始化必须使用真实物理字段列表。
 
+## 表增删改与退役（技能 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` → **创建时间**。
@@ -708,11 +821,12 @@ seed_column_metadata_batch(
 
 ## 元数据同步规则
 
-1. 新增用户可见业务表 → 同步 `_jiangchang_tables`。
+1. 新增用户可见业务表 → 同步 `_jiangchang_tables`（`visible=1` 方可在数据管理展示）。
 2. 新增用户可见字段 → 同步 `_jiangchang_columns`。
-3. 删除/重命名表或字段 → 同步清理或迁移元数据。
+3. 删除/重命名表或字段 → 物理迁移 + 同步清理元数据；**废弃表**用 `drop_deprecated_user_table`，禁止只删元数据留物理表。
 4. 初始化脚本必须幂等。
 5. 元数据中的表、字段必须在库中真实存在；可见项不得缺少中文 `display_name`。
+6. `init_db()` 后：`iter_user_tables` 中每个物理业务表都应有对应 `_jiangchang_tables.display_name`，或已被 `drop_deprecated_user_table` 物理删除。
 
 ## 开发自检
 

scripts/db/display_metadata.py

@@ -277,6 +277,32 @@ def init_display_metadata(cursor) -> None:
     init_display_metadata_tables(cursor)
 
 
+def drop_deprecated_user_table(
+    cursor,
+    table_name: str,
+    *,
+    triggers: Iterable[str] | None = None,
+) -> None:
+    """永久退役用户可见表：删 trigger、DROP 物理表、清理展示元数据（幂等）。
+
+    用于废弃 task_logs 等旧表。禁止只删元数据而保留物理表。
+    见 references/SCHEMA.md「表增删改与退役」。
+    """
+    for trigger_name in triggers or ():
+        cursor.execute(f"DROP TRIGGER IF EXISTS {trigger_name}")
+    default_updated_at = f"{table_name}_set_updated_at"
+    cursor.execute(f"DROP TRIGGER IF EXISTS {default_updated_at}")
+    cursor.execute(f"DROP TABLE IF EXISTS {_quote_identifier(table_name)}")
+    cursor.execute(
+        "DELETE FROM _jiangchang_columns WHERE table_name = ?",
+        (table_name,),
+    )
+    cursor.execute(
+        "DELETE FROM _jiangchang_tables WHERE table_name = ?",
+        (table_name,),
+    )
+
+
 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"

scripts/db/display_metadata_validator.py

@@ -235,6 +235,50 @@ def validate_options_json(options_json: str | None) -> tuple[list[str], list[str
     return errors, warnings
 
 
+def validate_filter_search_metadata(
+    cursor,
+    table_name: str,
+) -> tuple[list[str], list[str]]:
+    """对可见但未开启 searchable 的枚举 / boolean 列给出软建议。"""
+    warnings: list[str] = []
+    cursor.execute(
+        """
+        SELECT column_name, visible, searchable, display_type, options_json
+        FROM _jiangchang_columns
+        WHERE table_name = ?
+        """,
+        (table_name,),
+    )
+    for column_name, visible, searchable, display_type, options_json in cursor.fetchall():
+        if visible is not None and int(visible) == 0:
+            continue
+        if searchable is not None and int(searchable) != 0:
+            continue
+
+        display_type_norm = str(display_type or "").strip()
+        is_boolean = display_type_norm == "boolean"
+
+        has_enum = False
+        if options_json is not None and str(options_json).strip():
+            opt_errors, _ = validate_options_json(options_json)
+            if not opt_errors:
+                try:
+                    parsed = json.loads(str(options_json))
+                except json.JSONDecodeError:
+                    parsed = None
+                has_enum = isinstance(parsed, list) and len(parsed) > 0
+
+        if not has_enum and not is_boolean:
+            continue
+
+        warnings.append(
+            f"{table_name}.{column_name}: 枚举/状态类列建议 searchable=1，"
+            "以便宿主列筛选与按中文 label 全局搜索（见 references/SCHEMA.md）"
+        )
+
+    return [], warnings
+
+
 def validate_column_permissions(
     cursor,
     table_name: str,
@@ -511,6 +555,9 @@ def validate_display_metadata(conn: sqlite3.Connection, *, check_column_order: b
         report.errors.extend(perm_errors)
         report.warnings.extend(perm_warnings)
 
+        _, filter_warnings = validate_filter_search_metadata(cur, table_name)
+        report.warnings.extend(filter_warnings)
+
     cur.execute("SELECT table_name, column_name FROM _jiangchang_columns")
     for table_name, column_name in cur.fetchall():
         if table_name in METADATA_TABLES:

scripts/service/html_page_service.py

@@ -4,6 +4,7 @@
 
 - 目录：仅一层 `html/*.html`（非递归）
 - 重新生成 Action id 必须为 `render-html`（宿主硬编码）
+- 页面布局底线见 `references/ACTIONS.md`「宿主预览布局」；模板壳 `assets/html/example-report.html`
 - 成功后建议 `steps: refreshCatalog` 以重扫侧栏
 - 本模块只提供路径/模板/原子写；业务 KPI/表格由各技能自行填充
 """

scripts/util/constants.py

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

tests/samples/test_table_deprecation_migration.py.sample

@@ -0,0 +1,66 @@
+# -*- coding: utf-8 -*-
+"""旧库废弃表迁移样例（复制到 tests/ 并按技能改写）。
+
+验收：给定旧库含废弃物理表 + 元数据 + 历史行 → init_db() 后表与元数据均清除。
+见 references/SCHEMA.md「表增删改与退役」。
+"""
+from __future__ import annotations
+
+import unittest
+
+from _support import IsolatedDataRoot
+
+
+class TestTableDeprecationMigration(unittest.TestCase):
+  def test_init_db_drops_legacy_task_logs(self) -> None:
+    with IsolatedDataRoot():
+      from db.connection import get_conn, init_db
+      from db.display_metadata import iter_user_tables
+
+      # 1) 模拟升级前的旧库
+      init_db()
+      conn = get_conn()
+      try:
+        cur = conn.cursor()
+        cur.execute(
+          """
+          CREATE TABLE task_logs (
+            id INTEGER PRIMARY KEY,
+            task_type TEXT,
+            status TEXT
+          )
+          """
+        )
+        cur.execute(
+          """
+          INSERT INTO _jiangchang_tables
+          (table_name, display_name, visible, readonly)
+          VALUES ('task_logs', '任务日志', 1, 0)
+          """
+        )
+        cur.execute("INSERT INTO task_logs (task_type, status) VALUES ('run', 'ok')")
+        conn.commit()
+      finally:
+        conn.close()
+
+      # 2) 新代码 init_db() 应幂等清除（在 connection.init_db 中调用 drop_deprecated_user_table）
+      init_db()
+
+      conn = get_conn()
+      try:
+        cur = conn.cursor()
+        cur.execute(
+          "SELECT 1 FROM sqlite_master WHERE type='table' AND name='task_logs'"
+        )
+        self.assertIsNone(cur.fetchone())
+        cur.execute(
+          "SELECT COUNT(*) FROM _jiangchang_tables WHERE table_name='task_logs'"
+        )
+        self.assertEqual(int(cur.fetchone()[0]), 0)
+        self.assertNotIn("task_logs", list(iter_user_tables(cur)))
+      finally:
+        conn.close()
+
+
+if __name__ == "__main__":
+  unittest.main()

tests/test_display_metadata.py

@@ -553,6 +553,41 @@ metadata:
         finally:
             conn.close()
 
+    def test_enum_column_without_searchable_warns(self) -> None:
+        conn = sqlite3.connect(":memory:")
+        try:
+            conn.executescript(
+                """
+                CREATE TABLE filter_demo (id INTEGER PRIMARY KEY, enabled INTEGER NOT NULL DEFAULT 1);
+                """
+            )
+            from db.display_metadata import (
+                init_display_metadata_tables,
+                upsert_column_metadata,
+                upsert_table_metadata,
+            )
+            from db.display_metadata_validator import validate_filter_search_metadata
+
+            cur = conn.cursor()
+            init_display_metadata_tables(cur)
+            upsert_table_metadata(cur, table_name="filter_demo", display_name="筛选演示", readonly=0)
+            upsert_column_metadata(
+                cur,
+                table_name="filter_demo",
+                column_name="enabled",
+                display_name="是否启用",
+                visible=1,
+                searchable=0,
+                editable=1,
+                display_type="boolean",
+                options_json='[{"value":0,"label":"停用"},{"value":1,"label":"启用"}]',
+            )
+            conn.commit()
+            _, warnings = validate_filter_search_metadata(cur, "filter_demo")
+            self.assertTrue(any("searchable=1" in item for item in warnings))
+        finally:
+            conn.close()
+
     def test_schema_md_documents_readonly_and_seed_helpers(self) -> None:
         path = os.path.join(get_skill_root(), "references", "SCHEMA.md")
         with open(path, encoding="utf-8") as f:
@@ -703,6 +738,73 @@ metadata:
         finally:
             conn.close()
 
+    def test_drop_deprecated_user_table_removes_physical_and_metadata(self) -> None:
+        conn = sqlite3.connect(":memory:")
+        try:
+            cur = conn.cursor()
+            cur.execute(
+                """
+                CREATE TABLE _jiangchang_tables (
+                    table_name TEXT PRIMARY KEY,
+                    display_name TEXT,
+                    description TEXT,
+                    sort_order INTEGER,
+                    visible INTEGER,
+                    readonly INTEGER
+                )
+                """
+            )
+            cur.execute(
+                """
+                CREATE TABLE _jiangchang_columns (
+                    table_name TEXT,
+                    column_name TEXT,
+                    display_name TEXT,
+                    description TEXT,
+                    display_order INTEGER,
+                    visible INTEGER,
+                    searchable INTEGER,
+                    editable INTEGER,
+                    display_type TEXT,
+                    options_json TEXT,
+                    PRIMARY KEY (table_name, column_name)
+                )
+                """
+            )
+            cur.execute(
+                """
+                CREATE TABLE task_logs (
+                    id INTEGER PRIMARY KEY,
+                    status TEXT,
+                    created_at INTEGER,
+                    updated_at INTEGER
+                )
+                """
+            )
+            cur.execute(
+                "INSERT INTO _jiangchang_tables VALUES ('task_logs', '任务日志', NULL, 1, 1, 0)"
+            )
+            cur.execute(
+                "INSERT INTO _jiangchang_columns VALUES "
+                "('task_logs', 'id', '编号', NULL, 1, 1, 1, 0, 'text', NULL)"
+            )
+            cur.execute("INSERT INTO task_logs (status) VALUES ('success')")
+
+            from db.display_metadata import drop_deprecated_user_table, iter_user_tables
+
+            drop_deprecated_user_table(cur, "task_logs")
+            cur.execute(
+                "SELECT 1 FROM sqlite_master WHERE type='table' AND name='task_logs'"
+            )
+            self.assertIsNone(cur.fetchone())
+            cur.execute(
+                "SELECT COUNT(*) FROM _jiangchang_tables WHERE table_name='task_logs'"
+            )
+            self.assertEqual(int(cur.fetchone()[0]), 0)
+            self.assertNotIn("task_logs", list(iter_user_tables(cur)))
+        finally:
+            conn.close()
+
 
 if __name__ == "__main__":
     unittest.main()

tests/test_docs_standards.py

@@ -356,6 +356,13 @@ class TestDocsStandards(unittest.TestCase):
             "跨表引用 lookup",
             "\"multiple\": true",
             "Lookup 多选",
+            "数据管理：列筛选与全局搜索",
+            "列筛选与全局搜索",
+            "searchable: 1",
+            "筛选栏控件",
+            "表增删改与退役",
+            "drop_deprecated_user_table",
+            "孤儿物理表",
         ):
             self.assertIn(marker, text, msg=f"SCHEMA.md missing {marker!r}")
 
@@ -375,6 +382,7 @@ class TestDocsStandards(unittest.TestCase):
             "字段条件显隐",
             "visibleWhen",
             "grid_help",
+            "列筛选",
         ):
             self.assertIn(marker, text, msg=f"ACTIONS.md missing {marker!r}")
 

tests/test_html_page_service.py

@@ -61,6 +61,15 @@ class TestHtmlPageService(unittest.TestCase):
             with self.assertRaises(ValueError):
                 write_html_page("note.txt", "<html></html>")
 
+    def test_example_report_shell_embedded_preview_layout(self) -> None:
+        """守护 example-report.html：数据管理 iframe 预览布局基线不退化。"""
+        template = load_html_template("assets/html/example-report.html")
+        self.assertIn("overflow-x: hidden", template)
+        self.assertIn("min-width: 0", template)
+        self.assertIn("table-layout: fixed", template)
+        self.assertIn("overflow-wrap: anywhere", template)
+        self.assertNotIn("max-width:", template)
+
 
 if __name__ == "__main__":
     unittest.main()