feat: standardize skill data management and actions

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-11 11:23:14 +08:00
parent 48a86e56f1
commit 35c20fc0f2
18 changed files with 1534 additions and 68 deletions
--- a/scripts/db/display_metadata.py
+++ b/scripts/db/display_metadata.py
@@ -113,15 +113,16 @@ def upsert_column_metadata(
    searchable: int = 1,
    editable: int = 1,
    display_type: str | None = None,
+    options_json: str | None = None,
 ) -> None:
    # display_order 保留为 NULL：宿主按 PRAGMA table_info cid 展示字段，不读 display_order。
    cursor.execute(
        """
        INSERT INTO _jiangchang_columns (
            table_name, column_name, display_name, description,
-            display_order, visible, searchable, editable, display_type
+            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,
@@ -129,9 +130,20 @@ def upsert_column_metadata(
            visible = excluded.visible,
            searchable = excluded.searchable,
            editable = excluded.editable,
-            display_type = excluded.display_type
+            display_type = excluded.display_type,
+            options_json = excluded.options_json
        """,
-        (table_name, column_name, display_name, description, visible, searchable, editable, display_type),
+        (
+            table_name,
+            column_name,
+            display_name,
+            description,
+            visible,
+            searchable,
+            editable,
+            display_type,
+            options_json,
+        ),
    )


@@ -156,9 +168,98 @@ def seed_task_logs_display_metadata(cursor) -> None:
            searchable=int(column["searchable"]),
            editable=int(column["editable"]),
            display_type=str(column["display_type"]) if column.get("display_type") else None,
+            options_json=str(column["options_json"]) if column.get("options_json") else None,
        )


+def seed_column_metadata_batch(
+    cursor,
+    *,
+    table_name: str,
+    columns: tuple[dict[str, object], ...],
+) -> None:
+    for column in columns:
+        upsert_column_metadata(
+            cursor,
+            table_name=table_name,
+            column_name=str(column["column_name"]),
+            display_name=str(column["display_name"]),
+            description=str(column["description"]) if column.get("description") else None,
+            visible=int(column.get("visible", 1)),
+            searchable=int(column.get("searchable", 1)),
+            editable=int(column.get("editable", 1)),
+            display_type=str(column["display_type"]) if column.get("display_type") else None,
+            options_json=str(column["options_json"]) if column.get("options_json") else None,
+        )
+
+
+def prune_stale_column_metadata(cursor, table_name: str, valid_column_names: Iterable[str]) -> None:
+    """删除表中已不存在物理字段的元数据行（幂等初始化后不得残留旧字段）。"""
+    valid = set(valid_column_names)
+    cursor.execute(
+        "SELECT column_name FROM _jiangchang_columns WHERE table_name = ?",
+        (table_name,),
+    )
+    for (column_name,) in cursor.fetchall():
+        if str(column_name) not in valid:
+            cursor.execute(
+                "DELETE FROM _jiangchang_columns WHERE table_name = ? AND column_name = ?",
+                (table_name, column_name),
+            )
+
+
+def get_table_readonly(cursor, table_name: str) -> int | None:
+    cursor.execute(
+        "SELECT readonly FROM _jiangchang_tables WHERE table_name = ?",
+        (table_name,),
+    )
+    row = cursor.fetchone()
+    if not row:
+        return None
+    return int(row[0] or 0)
+
+
+def get_column_editable(cursor, table_name: str, column_name: str) -> int | None:
+    cursor.execute(
+        """
+        SELECT editable FROM _jiangchang_columns
+        WHERE table_name = ? AND column_name = ?
+        """,
+        (table_name, column_name),
+    )
+    row = cursor.fetchone()
+    if not row:
+        return None
+    return int(row[0] or 0)
+
+
+def list_editable_business_columns(cursor, table_name: str) -> list[str]:
+    """返回 editable=1 的业务字段名（不含宿主侧主键/generated 等二次过滤）。"""
+    physical = list_physical_column_names(cursor, table_name)
+    cursor.execute(
+        """
+        SELECT column_name, editable
+        FROM _jiangchang_columns
+        WHERE table_name = ?
+        """,
+        (table_name,),
+    )
+    editable_set = {
+        str(column_name)
+        for column_name, editable in cursor.fetchall()
+        if editable is not None and int(editable) == 1
+    }
+    return [name for name in physical if name in editable_set]
+
+
+def table_allows_manual_create(cursor, table_name: str) -> bool:
+    """表级 readonly=0 且至少有一个 editable=1 字段时，宿主才应提供空白新增表单。"""
+    readonly = get_table_readonly(cursor, table_name)
+    if readonly is None or int(readonly) != 0:
+        return False
+    return bool(list_editable_business_columns(cursor, table_name))
+
+
 def init_display_metadata(cursor) -> None:
    init_display_metadata_tables(cursor)
    seed_task_logs_display_metadata(cursor)
--- a/scripts/db/display_metadata_validator.py
+++ b/scripts/db/display_metadata_validator.py
@@ -2,6 +2,7 @@

 from __future__ import annotations

+import json
 import os
 import re
 import sqlite3
@@ -14,7 +15,9 @@ from db.display_metadata import (
    TASK_LOGS_COLUMN_METADATA,
    TASK_LOGS_TABLE,
    iter_user_tables,
+    list_editable_business_columns,
    list_physical_column_names,
+    table_allows_manual_create,
 )
 from db.timestamp_columns import has_updated_at_trigger
 from util.constants import SKILL_SLUG
@@ -165,6 +168,93 @@ def _default_uses_unixepoch(default_value: object) -> bool:
    return "unixepoch" in text


+def validate_options_json(options_json: str | None) -> tuple[list[str], list[str]]:
+    """校验枚举 options_json 可被解析为 [{value, label}, ...] 结构。"""
+    errors: list[str] = []
+    warnings: list[str] = []
+    if options_json is None or str(options_json).strip() == "":
+        return errors, warnings
+    try:
+        parsed = json.loads(str(options_json))
+    except json.JSONDecodeError as exc:
+        errors.append(f"options_json 不是合法 JSON：{exc}")
+        return errors, warnings
+    if not isinstance(parsed, list):
+        errors.append("options_json 必须是 JSON 数组")
+        return errors, warnings
+    for index, item in enumerate(parsed):
+        if not isinstance(item, dict):
+            errors.append(f"options_json[{index}] 必须是对象")
+            continue
+        if "value" not in item or "label" not in item:
+            errors.append(f"options_json[{index}] 必须包含 value 与 label")
+    return errors, warnings
+
+
+def validate_column_permissions(
+    cursor,
+    table_name: str,
+    *,
+    physical_columns: list[str] | None = None,
+) -> tuple[list[str], list[str]]:
+    """校验常见系统字段 editable=0，并识别技术上可写但不适合手工新增的表。"""
+    errors: list[str] = []
+    warnings: list[str] = []
+    ordered = physical_columns or list_physical_column_names(cursor, table_name)
+    column_info = _table_column_info(cursor, table_name)
+
+    cursor.execute(
+        """
+        SELECT column_name, editable, options_json
+        FROM _jiangchang_columns
+        WHERE table_name = ?
+        """,
+        (table_name,),
+    )
+    meta_by_column = {
+        str(row[0]): {"editable": row[1], "options_json": row[2]}
+        for row in cursor.fetchall()
+    }
+
+    for column_name in ordered:
+        meta = meta_by_column.get(column_name)
+        if not meta:
+            continue
+
+        physical = column_info.get(column_name) or {}
+        pk = int(physical.get("pk") or 0)
+        editable = meta["editable"]
+        if pk and editable is not None and int(editable) != 0:
+            errors.append(f"{table_name}.{column_name} 是主键，editable 应为 0")
+
+        if column_name == "id" and editable is not None and int(editable) != 0:
+            errors.append(f"{table_name}.id 的 editable 应为 0（自增主键）")
+
+        opt_errors, _ = validate_options_json(meta.get("options_json"))
+        for item in opt_errors:
+            errors.append(f"{table_name}.{column_name}: {item}")
+
+    cursor.execute(
+        "SELECT readonly FROM _jiangchang_tables WHERE table_name = ?",
+        (table_name,),
+    )
+    readonly_row = cursor.fetchone()
+    readonly = int(readonly_row[0]) if readonly_row else None
+    editable_columns = list_editable_business_columns(cursor, table_name)
+    if readonly == 0 and not editable_columns:
+        warnings.append(
+            f"{table_name}: 表级 readonly=0 但所有字段 editable=0，"
+            "宿主不应打开空白新增表单；数据应由技能业务流程产生"
+        )
+    if readonly == 1 and editable_columns:
+        warnings.append(
+            f"{table_name}: 表级 readonly=1 但存在 editable=1 字段，"
+            "宿主应以表级只读为准"
+        )
+
+    return errors, warnings
+
+
 def _expected_timestamp_display_name(column_name: str) -> str:
    if column_name == "created_at":
        return "创建时间"
@@ -338,6 +428,14 @@ def validate_display_metadata(conn: sqlite3.Connection, *, check_column_order: b
        report.errors.extend(ts_errors)
        report.warnings.extend(ts_warnings)

+        perm_errors, perm_warnings = validate_column_permissions(
+            cur,
+            table_name,
+            physical_columns=physical_columns,
+        )
+        report.errors.extend(perm_errors)
+        report.warnings.extend(perm_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: