Release v1.0.90: document grid_help data-management contract

CHANGELOG.md

@@ -9,10 +9,31 @@
 - 小节正文写用户能看懂的变化（新能力、修复、注意事项），避免堆砌内部实现细节
 - 打 tag 前**必须**为即将发布的版本新增一节；找不到匹配小节时，本次发布不会更新 changelog 字段
 
+## 1.0.90
+
+- 沉淀数据管理表格说明契约：`_jiangchang_tables.grid_help` / `_jiangchang_columns.grid_help`
+- 有内容才显示表上方说明和列头「?」；不写则与今日一致
+- 与新增/编辑表单的 `description` 独立，禁止互拷（见 `references/SCHEMA.md`）
+
+## 1.0.89
+
+- 仓库增加 MIT 许可证，版权归属深圳匠厂科技有限公司
+- 增加 SECURITY.md：未公开漏洞请通过匠厂官网联系，不要发在公开 Issue
+- 模板 developer_ids 改为占位 12345，复制后请换成自己的匠厂用户 ID
+
+## 1.0.88
+
+- `release.ps1` 默认 tag 说明改为 UTF-8 字节写入，不再依赖脚本源码里的中文默认参数（Windows PowerShell 5.1 会把无 BOM 的 UTF-8 按系统代码页解析）
+- 不改写已发布 tag（v1.0.86 / v1.0.87 说明仍可能乱码）
+
+## 1.0.87
+
+- `release.ps1` 打 annotated tag / 自动 commit 改为 UTF-8 消息文件 + `git -F`，避免 `-m` 走控制台代码页
+- 默认说明仍可能乱码（见 1.0.88）
+
 ## 1.0.86
 
-- 修复 `release.ps1` 在中文 Windows 下经 `cmd /c` 打 annotated tag 时，默认说明「正式发布」被 OEM 代码页转成乱码的问题
-- 改为直接调用 `git.exe` 并按参数数组传 `-m`，commit / tag 中文说明保持 UTF-8；不改写历史 tag
+- 去掉 `release.ps1` 里通过 `cmd /c` 调 git 的写法；中文 tag 说明在部分 Windows 控制台代码页下仍可能乱码，见 1.0.87
 
 ## 1.0.85
 

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 深圳匠厂科技有限公司
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

SECURITY.md

@@ -0,0 +1,20 @@
+# 安全漏洞披露
+
+本仓库是匠厂技能开发模板。请把**未公开的安全漏洞**发给深圳匠厂科技有限公司，不要在公开 Issue、PR 或讨论区里贴完整复现步骤、PoC 或利用细节。
+
+## 怎么报告
+
+请通过匠厂官网联系渠道提交：[https://www.jc2009.com/](https://www.jc2009.com/)
+
+建议在联系时注明：
+
+- 标题或开头带 `[Security]`
+- 影响的仓库 / 版本（例如 `skill-template`、tag `v1.0.x`）
+- 问题类型、影响范围、复现步骤
+- 若已有修复思路，可一并说明
+
+我们会确认收悉，并在有结论后告知是否修复、是否公开披露。
+
+## 不在本页范围
+
+本页只说明**如何向我们报告漏洞**。技能运行时的权限、RPA 合规、加密发布等产品安全设计，见 `development/` 与 `references/`，不要写进本文件。

SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: 技能开发模板（通用业务版）
 description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。"
-version: 1.0.86
+version: 1.0.90
 author: 深圳匠厂科技有限公司
 metadata:
   openclaw:
@@ -10,8 +10,7 @@ metadata:
     emoji: "📦"
     category: "通用"
     developer_ids:
-      - 10032
-      - 12428
+      - 12345  # 占位，请换成你的匠厂用户 ID
 allowed-tools:
   - bash
 ---

references/ACTIONS.md

@@ -658,6 +658,7 @@ Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件
 | URL（薄层） | `display_type` 或 `format`: `url` | `display_type: url` |
 | Email（薄层） | `display_type` 或 `format`: `email` | `display_type: email` |
 | 说明灰字 | `description` | `_jiangchang_columns.description` |
+| 表格横幅 / 列头「?」 | （无；Action 不用） | `_jiangchang_tables.grid_help` / `_jiangchang_columns.grid_help` |
 | 默认值 | `default` | SQLite 列 `DEFAULT` |
 | 只读 | `readOnly: true` | 列 `editable: 0` / 宿主只读规则 |
 | **条件显隐** | **`visibleWhen`**（见下节） | **本版 CRUD 无对称**；仅 Action / 定时任务参数表单 |
@@ -727,6 +728,8 @@ Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件
 | Skill Action 弹窗 | `inputSchema.title` | `inputSchema.description` | `inputSchema.default` | `type` + `display_type`/`format` |
 | 数据管理新增/编辑 | `_jiangchang_columns.display_name` | `_jiangchang_columns.description` | 物理列 SQLite `DEFAULT` | `display_type` + 物理类型推断 |
 
+数据管理**表格**上方说明与列头「?」用 `_jiangchang_tables.grid_help` / `_jiangchang_columns.grid_help`（空则不渲染），**不要**用 `description`。见 [`SCHEMA.md`](SCHEMA.md)「表格说明 `grid_help`」。
+
 CRUD 侧宿主义务与禁止事项见 [`SCHEMA.md`](SCHEMA.md)「表单与展示：稳定字段类型」「新增/编辑表单：字段说明与默认值」。同一业务含义两边文案与控件应对齐，但分别配置。
 
 示例：

references/SCHEMA.md

@@ -13,7 +13,7 @@
 - 定义真实 SQLite 表结构
 - 使用英文 `snake_case` 表名和字段名
 - 使用 `_jiangchang_tables` 提供表级展示元数据
-- 使用 `_jiangchang_columns` 提供字段级展示元数据（含可选 `description` 字段说明）
+- 使用 `_jiangchang_columns` 提供字段级展示元数据（含可选 `description` 表单说明、可选 `grid_help` 表格说明）
 - 需要「新增表单预填」时，在物理列上声明 SQLite `DEFAULT`（勿把默认值只写在文案里）
 - 定义哪些字段可见、可搜索、可创建、可编辑
 - 定义字段展示类型和枚举选项
@@ -28,6 +28,7 @@
 - 根据 schema 渲染数据管理页面
 - 根据 `editable` 推导字段是否可创建或编辑
 - 在**新增 / 编辑**表单中，若列有 `_jiangchang_columns.description`，在标签下方展示该说明（灰字；空则不显示）
+- 在数据管理**表格**中，若表有 `_jiangchang_tables.grid_help` 则在表上方展示可折叠说明；若列有 `_jiangchang_columns.grid_help` 则在列头显示「?」；空/未写则不渲染。**不**把 `description` 当作表格说明
 - 打开**新增**表单时，对可创建字段用 SQLite 列 `DEFAULT`（`PRAGMA table_info.dflt_value`）预填；无 DEFAULT 则留空
 - 执行通用查询、新增、编辑、删除、导入、导出
 - 对字段名、表名、类型和权限进行最终校验
@@ -138,7 +139,8 @@ metadata:
 |------|------|------|
 | `table_name` | 是 | 真实英文表名 |
 | `display_name` | 是 | 用户可见的中文业务名称 |
-| `description` | 否 | 表说明 |
+| `description` | 否 | 表说明（表单/备注用途）；**不**用于表格上方横幅 |
+| `grid_help` | 否 | 数据管理表格上方说明；空/未写则不出横幅。与 `description` 独立，禁止互拷（见下节） |
 | `sort_order` | 否 | 兼容保留字段，不用于替代物理字段顺序 |
 | `visible` | 是 | `1` 在宿主数据管理中展示 / `0` 隐藏 |
 | `readonly` | 是 | `1` 整张表只读；`0` 允许宿主根据字段权限执行写操作 |
@@ -212,6 +214,43 @@ upsert_table_metadata(
 )
 ```
 
+#### 表格说明 `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,
+)
+```
+
 禁止：
 
 - 使用中文真实表名
@@ -228,6 +267,7 @@ upsert_table_metadata(
 | `column_name` | 是 | 真实英文字段名 |
 | `display_name` | 是 | 用户可见的中文字段名（表头与表单标签）；保持简短 |
 | `description` | 否 | 字段说明（给人看的短文案）；**宿主在新增/编辑表单标签下方展示**（见下节）；不要塞进 `display_name` |
+| `grid_help` | 否 | 数据管理表头「?」；空/未写则不出。与表单 `description` 独立，禁止互拷 |
 | `display_order` | 否 | 兼容字段，默认保持 `NULL` |
 | `visible` | 是 | 是否进入数据管理 schema /「列」面板（`0` = **硬隐藏**，用户无法勾回；默认不展示但可勾回请用表级 `default_visible_columns_json`） |
 | `searchable` | 是 | 是否参与搜索 |
@@ -277,7 +317,9 @@ upsert_table_metadata(
 | 字段说明 | `_jiangchang_columns.description`（可选） | 新增/编辑表单中，在标签下方以灰字展示；空则不显示 |
 | 创建默认值 | 物理列 SQLite `DEFAULT`（如 `limit_n INTEGER NOT NULL DEFAULT 0`） | 打开「新增」时，对可创建字段预填该默认值；无 DEFAULT 则留空 |
 | 编辑已有行 | — | **不**用 DEFAULT 覆盖已有行数据 |
-| 表格列头 | 只用 `display_name` | 长说明**不**进入列头 |
+| 表格列头标题 | `display_name` | 短名；不要把长说明塞进列头文字 |
+| 表格列头「?」 | `_jiangchang_columns.grid_help`（可选） | 有内容才显示「?」；**不**回退 `description` |
+| 表格上方说明 | `_jiangchang_tables.grid_help`（可选） | 有内容才显示横幅；**不**回退表级 `description` |
 
 规则与禁止：
 
@@ -552,7 +594,7 @@ Action 弹窗内联 Lookup 与上表 **同构**（字段名一致），见 [`ACT
 
 - `_jiangchang_tables` 和 `_jiangchang_columns` 必须通过 upsert 初始化
 - 多次执行初始化不能重复记录
-- 重新初始化可以更新展示名、描述、`visible`、`searchable`、`editable`、`display_type`、`options_json`
+- 重新初始化可以更新展示名、描述、`grid_help`、`visible`、`searchable`、`editable`、`display_type`、`options_json`
 - 元数据不能残留旧字段（删除或重命名字段时必须同步清理）
 - 元数据不能引用不存在的表或字段
 - 新增字段或表时必须同步增加元数据

release.ps1

@@ -17,7 +17,7 @@
 [CmdletBinding()]
 param(
   [string]$Prefix = "v",
-  [string]$Message = "正式发布",
+  [string]$Message,
   [switch]$AutoCommit,
   [switch]$RequireClean,
   [string]$CommitMessage,
@@ -28,6 +28,13 @@ param(
 Set-StrictMode -Version Latest
 $ErrorActionPreference = "Stop"
 
+# Default tag message is 「正式发布」 from UTF-8 bytes (not a Chinese literal in
+# this file). Windows PowerShell 5.1 parses UTF-8 scripts without BOM as the
+# system ANSI code page, which would turn a source literal into 「姝ｅ紡鍙戝竷」.
+if (-not $PSBoundParameters.ContainsKey("Message") -or [string]::IsNullOrWhiteSpace($Message)) {
+  $Message = [System.Text.Encoding]::UTF8.GetString([byte[]](0xE6, 0xAD, 0xA3, 0xE5, 0xBC, 0x8F, 0xE5, 0x8F, 0x91, 0xE5, 0xB8, 0x83))
+}
+
 function Remove-GitNoise {
   param([string[]]$Lines)
   return @($Lines | Where-Object {
@@ -45,9 +52,11 @@ function Convert-GitOutputLines {
   )
 }
 
-# Call git.exe directly. Do not wrap with `cmd /c` — on Chinese Windows, cmd
-# re-encodes -m / -F arguments through the OEM code page and garbles UTF-8
-# annotated tag / commit messages (e.g. 「正式发布」 → 「姝ｅ紡鍙戝竷」).
+# Call git.exe directly. Never wrap with `cmd /c`: on Chinese Windows, cmd
+# re-encodes the command line through the OEM code page.
+# Also never pass Chinese via `git -m`: Windows PowerShell 5.1 encodes native
+# argv using the console code page, so 「正式发布」 becomes 「姝ｅ紡鍙戝竷」
+# in the annotated tag. Commit/tag messages go through a UTF-8 file + `-F`.
 function Invoke-GitRaw {
   param([Parameter(Mandatory = $true)][string[]]$GitArgs)
   $prev = $ErrorActionPreference
@@ -73,6 +82,21 @@ function Invoke-Git {
   }
 }
 
+function Invoke-GitWithMessageFile {
+  param(
+    [Parameter(Mandatory = $true)][string[]]$GitArgsPrefix,
+    [Parameter(Mandatory = $true)][string]$Message
+  )
+  $msgFile = Join-Path ([System.IO.Path]::GetTempPath()) ("jiangchang-git-msg-" + [guid]::NewGuid().ToString("N") + ".txt")
+  $utf8NoBom = New-Object System.Text.UTF8Encoding $false
+  [System.IO.File]::WriteAllText($msgFile, ($Message.TrimEnd() + "`n"), $utf8NoBom)
+  try {
+    Invoke-Git -GitArgs (@("-c", "i18n.commitEncoding=utf-8") + $GitArgsPrefix + @("-F", $msgFile))
+  } finally {
+    Remove-Item -LiteralPath $msgFile -Force -ErrorAction SilentlyContinue
+  }
+}
+
 function Get-GitOutput {
   param([Parameter(Mandatory = $true)][string[]]$GitArgs)
   $r = Invoke-GitRaw -GitArgs $GitArgs
@@ -229,7 +253,7 @@ function Ensure-CleanOrAutoCommit {
   }
 
   Invoke-Git -GitArgs @("add", "-A")
-  Invoke-Git -GitArgs @("commit", "-m", $commitMsg)
+  Invoke-GitWithMessageFile -GitArgsPrefix @("commit") -Message $commitMsg
 }
 
 try {
@@ -289,13 +313,13 @@ try {
   }
 
   if ($DryRun) {
-    Write-Host "[DryRun] Would run: git tag -a $nextTag -m `"$Message`"" -ForegroundColor Yellow
+    Write-Host "[DryRun] Would run: git tag -a $nextTag -F <utf8-msg-file> ($Message)" -ForegroundColor Yellow
     Write-Host "[DryRun] Would run: git push origin $nextTag" -ForegroundColor Yellow
     Write-Host "=== DryRun Complete ===" -ForegroundColor Cyan
     exit 0
   }
 
-  Invoke-Git -GitArgs @("tag", "-a", $nextTag, "-m", $Message)
+  Invoke-GitWithMessageFile -GitArgsPrefix @("tag", "-a", $nextTag) -Message $Message
   Invoke-Git -GitArgs @("push", "origin", $nextTag)
 
   Write-Host "Release success: $nextTag" -ForegroundColor Green

scripts/db/display_metadata.py

@@ -21,6 +21,7 @@ CREATE TABLE IF NOT EXISTS _jiangchang_tables (
     table_name TEXT PRIMARY KEY,
     display_name TEXT NOT NULL,
     description TEXT,
+    grid_help TEXT,
     sort_order INTEGER,
     visible INTEGER NOT NULL DEFAULT 1,
     readonly INTEGER NOT NULL DEFAULT 0,
@@ -35,6 +36,7 @@ CREATE TABLE IF NOT EXISTS _jiangchang_columns (
     column_name TEXT NOT NULL,
     display_name TEXT NOT NULL,
     description TEXT,
+    grid_help TEXT,
     display_order INTEGER,
     visible INTEGER NOT NULL DEFAULT 1,
     searchable INTEGER NOT NULL DEFAULT 1,
@@ -45,22 +47,35 @@ CREATE TABLE IF NOT EXISTS _jiangchang_columns (
 )
 """
 
+def _pragma_column_names(cursor, table_name: str) -> set[str]:
+    cursor.execute(f"PRAGMA table_info({table_name!r})")
+    return {str(row[1]) for row in cursor.fetchall()}
+
+
 def _ensure_jiangchang_tables_columns(cursor) -> None:
     """旧库补列：CREATE IF NOT EXISTS 不会给已有表加新字段。"""
-    cursor.execute("PRAGMA table_info('_jiangchang_tables')")
-    cols = {str(row[1]) for row in cursor.fetchall()}
+    cols = _pragma_column_names(cursor, "_jiangchang_tables")
     if "default_sort_json" not in cols:
         cursor.execute("ALTER TABLE _jiangchang_tables ADD COLUMN default_sort_json TEXT")
     if "default_visible_columns_json" not in cols:
         cursor.execute(
             "ALTER TABLE _jiangchang_tables ADD COLUMN default_visible_columns_json TEXT"
         )
+    if "grid_help" not in cols:
+        cursor.execute("ALTER TABLE _jiangchang_tables ADD COLUMN grid_help TEXT")
+
+
+def _ensure_jiangchang_columns_columns(cursor) -> None:
+    cols = _pragma_column_names(cursor, "_jiangchang_columns")
+    if "grid_help" not in cols:
+        cursor.execute("ALTER TABLE _jiangchang_columns ADD COLUMN grid_help TEXT")
 
 
 def init_display_metadata_tables(cursor) -> None:
     cursor.execute(_JIANGCHANG_TABLES_DDL)
     cursor.execute(_JIANGCHANG_COLUMNS_DDL)
     _ensure_jiangchang_tables_columns(cursor)
+    _ensure_jiangchang_columns_columns(cursor)
 
 
 def upsert_table_metadata(
@@ -69,6 +84,7 @@ def upsert_table_metadata(
     table_name: str,
     display_name: str,
     description: str | None = None,
+    grid_help: str | None = None,
     visible: int = 1,
     readonly: int = 0,
     default_sort_json: str | None = None,
@@ -83,17 +99,20 @@ def upsert_table_metadata(
     default_visible_columns_json: 宿主数据管理默认展示列，JSON 字符串数组，例如
     '["stat_type","period","stage"]'
     为空则全显；用户改过「列」后以本机偏好为准（软默认，区别于 visible=0 硬隐藏）。
+
+    grid_help: 数据管理表格上方说明；空则不出横幅。与表单用的 description 独立，禁止互拷。
     """
     cursor.execute(
         """
         INSERT INTO _jiangchang_tables (
-            table_name, display_name, description, visible, readonly,
+            table_name, display_name, description, grid_help, visible, readonly,
             default_sort_json, default_visible_columns_json
         )
-        VALUES (?, ?, ?, ?, ?, ?, ?)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
         ON CONFLICT(table_name) DO UPDATE SET
             display_name = excluded.display_name,
             description = excluded.description,
+            grid_help = excluded.grid_help,
             visible = excluded.visible,
             readonly = excluded.readonly,
             default_sort_json = excluded.default_sort_json,
@@ -103,6 +122,7 @@ def upsert_table_metadata(
             table_name,
             display_name,
             description,
+            grid_help,
             visible,
             readonly,
             default_sort_json,
@@ -118,6 +138,7 @@ def upsert_column_metadata(
     column_name: str,
     display_name: str,
     description: str | None = None,
+    grid_help: str | None = None,
     visible: int = 1,
     searchable: int = 1,
     editable: int = 1,
@@ -125,16 +146,18 @@ def upsert_column_metadata(
     options_json: str | None = None,
 ) -> None:
     # display_order 保留为 NULL：宿主按 PRAGMA table_info cid 展示字段，不读 display_order。
+    # grid_help: 表头「?」；空则不出。与表单用的 description 独立，禁止互拷。
     cursor.execute(
         """
         INSERT INTO _jiangchang_columns (
-            table_name, column_name, display_name, description,
+            table_name, column_name, display_name, description, grid_help,
             display_order, visible, searchable, editable, display_type, options_json
         )
-        VALUES (?, ?, ?, ?, NULL, ?, ?, ?, ?, ?)
+        VALUES (?, ?, ?, ?, ?, NULL, ?, ?, ?, ?, ?)
         ON CONFLICT(table_name, column_name) DO UPDATE SET
             display_name = excluded.display_name,
             description = excluded.description,
+            grid_help = excluded.grid_help,
             display_order = NULL,
             visible = excluded.visible,
             searchable = excluded.searchable,
@@ -147,6 +170,7 @@ def upsert_column_metadata(
             column_name,
             display_name,
             description,
+            grid_help,
             visible,
             searchable,
             editable,
@@ -171,6 +195,7 @@ def seed_column_metadata_batch(
             column_name=str(column["column_name"]),
             display_name=str(column["display_name"]),
             description=str(column["description"]) if column.get("description") else None,
+            grid_help=str(column["grid_help"]) if column.get("grid_help") else None,
             visible=int(column.get("visible", 1)),
             searchable=int(column.get("searchable", 1)),
             editable=int(column.get("editable", 1)),

scripts/util/constants.py

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

tests/test_display_metadata.py

@@ -578,6 +578,100 @@ metadata:
         finally:
             conn.close()
 
+    def test_grid_help_upsert_and_migrate_from_legacy_schema(self) -> None:
+        conn = sqlite3.connect(":memory:")
+        try:
+            from db.display_metadata import (
+                init_display_metadata_tables,
+                upsert_column_metadata,
+                upsert_table_metadata,
+            )
+
+            cur = conn.cursor()
+            cur.execute(
+                """
+                CREATE TABLE _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,
+                    default_sort_json TEXT,
+                    default_visible_columns_json TEXT
+                )
+                """
+            )
+            cur.execute(
+                """
+                CREATE TABLE _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)
+                )
+                """
+            )
+            init_display_metadata_tables(cur)
+            cur.execute("PRAGMA table_info('_jiangchang_tables')")
+            self.assertIn("grid_help", {str(row[1]) for row in cur.fetchall()})
+            cur.execute("PRAGMA table_info('_jiangchang_columns')")
+            self.assertIn("grid_help", {str(row[1]) for row in cur.fetchall()})
+
+            upsert_table_metadata(
+                cur,
+                table_name="demo_items",
+                display_name="示例记录",
+                description="表单备注，不应出现在表格横幅",
+                grid_help="表格横幅说明",
+            )
+            upsert_column_metadata(
+                cur,
+                table_name="demo_items",
+                column_name="title",
+                display_name="标题",
+                description="填标题",
+                grid_help="列头问号说明",
+            )
+            upsert_table_metadata(
+                cur,
+                table_name="empty_help",
+                display_name="无表格说明",
+            )
+            conn.commit()
+            cur.execute(
+                """
+                SELECT description, grid_help
+                FROM _jiangchang_tables
+                WHERE table_name = 'demo_items'
+                """
+            )
+            self.assertEqual(cur.fetchone(), ("表单备注，不应出现在表格横幅", "表格横幅说明"))
+            cur.execute(
+                """
+                SELECT description, grid_help
+                FROM _jiangchang_columns
+                WHERE table_name = 'demo_items' AND column_name = 'title'
+                """
+            )
+            self.assertEqual(cur.fetchone(), ("填标题", "列头问号说明"))
+            cur.execute(
+                """
+                SELECT grid_help FROM _jiangchang_tables
+                WHERE table_name = 'empty_help'
+                """
+            )
+            self.assertTrue(not cur.fetchone()[0])
+        finally:
+            conn.close()
+
 
 if __name__ == "__main__":
     unittest.main()

tests/test_docs_standards.py

@@ -348,6 +348,8 @@ class TestDocsStandards(unittest.TestCase):
             "文件 / 图片上传",
             "default_visible_columns_json",
             "默认展示列",
+            "grid_help",
+            "表格说明 `grid_help`",
         ):
             self.assertIn(marker, text, msg=f"SCHEMA.md missing {marker!r}")
 
@@ -365,6 +367,7 @@ class TestDocsStandards(unittest.TestCase):
             "SCHEMA.md",
             "字段条件显隐",
             "visibleWhen",
+            "grid_help",
         ):
             self.assertIn(marker, text, msg=f"ACTIONS.md missing {marker!r}")