docs: default visible columns contract (v1.0.79)

沉淀 _jiangchang_tables.default_visible_columns_json：技能声明默认展示列；未配置全显；用户改「列」后本机覆盖；与 visible=0 硬隐藏区分。

Co-authored-by: Cursor <cursoragent@cursor.com>

scripts/db/display_metadata.py

@@ -25,7 +25,8 @@ CREATE TABLE IF NOT EXISTS _jiangchang_tables (
     sort_order INTEGER,
     visible INTEGER NOT NULL DEFAULT 1,
     readonly INTEGER NOT NULL DEFAULT 0,
-    default_sort_json TEXT
+    default_sort_json TEXT,
+    default_visible_columns_json TEXT
 )
 """
 
@@ -89,6 +90,10 @@ def _ensure_jiangchang_tables_columns(cursor) -> None:
     cols = {str(row[1]) for row in cursor.fetchall()}
     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"
+        )
 
 
 def init_display_metadata_tables(cursor) -> None:
@@ -106,27 +111,42 @@ def upsert_table_metadata(
     visible: int = 1,
     readonly: int = 0,
     default_sort_json: str | None = None,
+    default_visible_columns_json: str | None = None,
 ) -> None:
     """写入表级元数据。
 
     default_sort_json: 宿主数据管理默认排序，JSON 数组，例如
     '[{"column":"sent_at","direction":"desc"},{"column":"id","direction":"desc"}]'
     为空则宿主回退到 updated_at → created_at → 主键。
+
+    default_visible_columns_json: 宿主数据管理默认展示列，JSON 字符串数组，例如
+    '["stat_type","period","stage"]'
+    为空则全显；用户改过「列」后以本机偏好为准（软默认，区别于 visible=0 硬隐藏）。
     """
     cursor.execute(
         """
         INSERT INTO _jiangchang_tables (
-            table_name, display_name, description, visible, readonly, default_sort_json
+            table_name, display_name, description, 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,
             visible = excluded.visible,
             readonly = excluded.readonly,
-            default_sort_json = excluded.default_sort_json
+            default_sort_json = excluded.default_sort_json,
+            default_visible_columns_json = excluded.default_visible_columns_json
         """,
-        (table_name, display_name, description, visible, readonly, default_sort_json),
+        (
+            table_name,
+            display_name,
+            description,
+            visible,
+            readonly,
+            default_sort_json,
+            default_visible_columns_json,
+        ),
     )