fix: harden skill template contracts and scaffolding

Align scaffold slug replacement, Action manifest strict boundaries, metadata prune API, field permission validation, and task_logs readonly semantics with documented template contracts.

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

tests/test_actions_manifest.py

@@ -15,6 +15,9 @@ from util.constants import SKILL_SLUG
 _TEMPLATE_PLACEHOLDER_SLUG = "your-skill-slug"
 _ALLOWED_PLACEMENTS = frozenset({"toolbar", "row", "batch", "cron", "agent", "skill-detail"})
 _RESERVED_PLACEMENTS = frozenset({"row", "batch"})
+_RESERVED_ACTION_FIELDS = frozenset({"bind", "concurrency", "locks"})
+_REQUIRED_MANIFEST_KEYS = frozenset({"schemaVersion", "skill", "actions"})
+_REQUIRED_ACTION_KEYS = frozenset({"id", "label", "description", "placements", "entrypoint"})
 _FORBIDDEN_BUSINESS_TERMS = (
     "wechat",
     "微信",
@@ -57,6 +60,12 @@ def _collect_template_vars(args: list) -> set[str]:
     return found
 
 
+def _load_actions_schema() -> dict:
+    path = os.path.join(get_skill_root(), "assets", "schemas", "skill-actions.schema.json")
+    with open(path, encoding="utf-8") as f:
+        return json.load(f)
+
+
 class TestActionsManifest(unittest.TestCase):
     def test_manifest_exists_and_schema(self) -> None:
         manifest = _load_actions_manifest()
@@ -181,6 +190,48 @@ class TestActionsManifest(unittest.TestCase):
         self.assertEqual(schema.get("title"), "SkillActionManifest")
         self.assertIn("actions", schema.get("properties", {}))
 
+    def test_skill_actions_schema_json_parses(self) -> None:
+        schema = _load_actions_schema()
+        self.assertEqual(schema["properties"]["schemaVersion"]["const"], 1)
+        self.assertTrue(schema.get("additionalProperties") is False)
+        self.assertIn("action", schema.get("$defs", {}))
+
+    def test_template_manifest_matches_schema_required_keys(self) -> None:
+        manifest = _load_actions_manifest()
+        schema = _load_actions_schema()
+        for key in _REQUIRED_MANIFEST_KEYS:
+            self.assertIn(key, manifest)
+            self.assertIn(key, schema.get("properties", {}))
+        for action in manifest["actions"]:
+            for key in _REQUIRED_ACTION_KEYS:
+                self.assertIn(key, action)
+
+    def test_template_example_does_not_use_reserved_action_fields(self) -> None:
+        manifest = _load_actions_manifest()
+        for action in manifest["actions"]:
+            overlap = set(action.keys()) & _RESERVED_ACTION_FIELDS
+            self.assertFalse(
+                overlap,
+                msg=f"{action['id']} uses reserved action fields not supported in template Phase 1: {overlap}",
+            )
+
+    def test_actions_md_documents_strict_vs_host_boundary(self) -> None:
+        path = os.path.join(get_skill_root(), "references", "ACTIONS.md")
+        with open(path, encoding="utf-8") as f:
+            text = f.read()
+        for marker in (
+            "严格规范",
+            "向后兼容",
+            "Phase 1",
+            "bind",
+            "concurrency",
+            "locks",
+            "row",
+            "batch",
+            "additionalProperties",
+        ):
+            self.assertIn(marker, text, msg=f"ACTIONS.md missing {marker!r}")
+
 
 if __name__ == "__main__":
     unittest.main()

tests/test_data_management_contract.py

@@ -75,11 +75,10 @@ DEMO_ITEMS_COLUMN_METADATA: tuple[dict[str, object], ...] = (
 )
 
 
-def _init_demo_items_fixture(conn: sqlite3.Connection) -> None:
+def _init_demo_items_fixture(conn: sqlite3.Connection, *, prune: bool = True) -> None:
     from db.display_metadata import (
         init_display_metadata_tables,
         list_physical_column_names,
-        prune_stale_column_metadata,
         seed_column_metadata_batch,
         upsert_table_metadata,
     )
@@ -96,9 +95,13 @@ def _init_demo_items_fixture(conn: sqlite3.Connection) -> None:
         visible=int(meta["visible"]),
         readonly=int(meta["readonly"]),
     )
-    seed_column_metadata_batch(cur, table_name="demo_items", columns=DEMO_ITEMS_COLUMN_METADATA)
     physical = list_physical_column_names(cur, "demo_items")
-    prune_stale_column_metadata(cur, "demo_items", physical)
+    seed_column_metadata_batch(
+        cur,
+        table_name="demo_items",
+        columns=DEMO_ITEMS_COLUMN_METADATA,
+        valid_column_names=physical if prune else None,
+    )
     conn.commit()
 
 
@@ -371,11 +374,16 @@ class TestDataManagementContract(unittest.TestCase):
                 """
             )
             conn.commit()
-            from db.display_metadata import list_physical_column_names, prune_stale_column_metadata
+            from db.display_metadata import list_physical_column_names, seed_column_metadata_batch
 
             cur = conn.cursor()
             physical = list_physical_column_names(cur, "demo_items")
-            prune_stale_column_metadata(cur, "demo_items", physical)
+            seed_column_metadata_batch(
+                cur,
+                table_name="demo_items",
+                columns=DEMO_ITEMS_COLUMN_METADATA,
+                valid_column_names=physical,
+            )
             conn.commit()
             cur.execute(
                 "SELECT 1 FROM _jiangchang_columns WHERE table_name = 'demo_items' AND column_name = 'removed_field'"
@@ -384,6 +392,77 @@ class TestDataManagementContract(unittest.TestCase):
         finally:
             conn.close()
 
+    def test_seed_batch_without_valid_column_names_does_not_prune(self) -> None:
+        conn = sqlite3.connect(":memory:")
+        try:
+            _init_demo_items_fixture(conn, prune=False)
+            conn.execute(
+                """
+                INSERT INTO _jiangchang_columns
+                (table_name, column_name, display_name, visible, searchable, editable)
+                VALUES ('demo_items', 'removed_field', '已删除', 0, 0, 0)
+                """
+            )
+            conn.commit()
+            from db.display_metadata import seed_column_metadata_batch
+
+            seed_column_metadata_batch(
+                conn.cursor(),
+                table_name="demo_items",
+                columns=DEMO_ITEMS_COLUMN_METADATA,
+            )
+            conn.commit()
+            cur = conn.cursor()
+            cur.execute(
+                "SELECT 1 FROM _jiangchang_columns WHERE table_name = 'demo_items' AND column_name = 'removed_field'"
+            )
+            self.assertIsNotNone(cur.fetchone())
+        finally:
+            conn.close()
+
+    def test_seed_batch_accepts_list_columns(self) -> None:
+        conn = sqlite3.connect(":memory:")
+        try:
+            _init_demo_items_fixture(conn, prune=False)
+            from db.display_metadata import get_column_editable, seed_column_metadata_batch
+
+            columns = list(DEMO_ITEMS_COLUMN_METADATA)
+            columns[1] = {**columns[1], "display_name": "标题（列表）"}
+            seed_column_metadata_batch(
+                conn.cursor(),
+                table_name="demo_items",
+                columns=columns,
+                valid_column_names=[str(item["column_name"]) for item in DEMO_ITEMS_COLUMN_METADATA],
+            )
+            conn.commit()
+            cur = conn.cursor()
+            cur.execute(
+                "SELECT display_name FROM _jiangchang_columns WHERE table_name = 'demo_items' AND column_name = 'title'"
+            )
+            self.assertEqual(cur.fetchone()[0], "标题（列表）")
+            self.assertEqual(get_column_editable(cur, "demo_items", "title"), 1)
+        finally:
+            conn.close()
+
+    def test_prune_does_not_remove_existing_column_metadata(self) -> None:
+        conn = sqlite3.connect(":memory:")
+        try:
+            _init_demo_items_fixture(conn)
+            from db.display_metadata import get_column_editable, seed_column_metadata_batch
+
+            cur = conn.cursor()
+            before = get_column_editable(cur, "demo_items", "title")
+            seed_column_metadata_batch(
+                cur,
+                table_name="demo_items",
+                columns=DEMO_ITEMS_COLUMN_METADATA,
+                valid_column_names=[str(item["column_name"]) for item in DEMO_ITEMS_COLUMN_METADATA],
+            )
+            conn.commit()
+            self.assertEqual(get_column_editable(cur, "demo_items", "title"), before)
+        finally:
+            conn.close()
+
     def test_demo_items_validation_passes(self) -> None:
         conn = sqlite3.connect(":memory:")
         try:

tests/test_display_metadata.py

@@ -2,6 +2,7 @@
 """数据管理展示元数据：幂等初始化、中文名称、PRAGMA 字段顺序、校验规则。"""
 from __future__ import annotations
 
+import os
 import sqlite3
 import unittest
 
@@ -35,22 +36,39 @@ class TestDisplayMetadata(unittest.TestCase):
             try:
                 cur = conn.cursor()
                 cur.execute(
-                    "SELECT display_name FROM _jiangchang_tables WHERE table_name = 'task_logs'"
+                    "SELECT display_name, readonly FROM _jiangchang_tables WHERE table_name = 'task_logs'"
                 )
-                self.assertEqual(cur.fetchone()[0], "任务日志")
+                display_name, readonly = cur.fetchone()
+                self.assertEqual(display_name, "任务日志")
+                self.assertEqual(int(readonly), 1)
 
                 cur.execute(
                     """
-                    SELECT column_name, display_name
+                    SELECT column_name, display_name, editable
                     FROM _jiangchang_columns
                     WHERE table_name = 'task_logs'
                     ORDER BY column_name
                     """
                 )
-                by_name = dict(cur.fetchall())
-                self.assertEqual(by_name["status"], "状态")
-                self.assertEqual(by_name["error_msg"], "错误信息")
-                self.assertEqual(by_name["created_at"], "创建时间")
+                by_name = {row[0]: (row[1], row[2]) for row in cur.fetchall()}
+                self.assertEqual(by_name["status"][0], "状态")
+                self.assertEqual(int(by_name["status"][1]), 0)
+                self.assertEqual(by_name["error_msg"][0], "错误信息")
+                self.assertEqual(int(by_name["error_msg"][1]), 0)
+                self.assertEqual(by_name["created_at"][0], "创建时间")
+                self.assertEqual(int(by_name["created_at"][1]), 0)
+            finally:
+                conn.close()
+
+    def test_task_logs_not_manual_create_in_host_ui(self) -> None:
+        with IsolatedDataRoot():
+            from db.connection import get_conn, init_db
+            from db.display_metadata import table_allows_manual_create
+
+            init_db()
+            conn = get_conn()
+            try:
+                self.assertFalse(table_allows_manual_create(conn.cursor(), "task_logs"))
             finally:
                 conn.close()
 
@@ -342,6 +360,153 @@ metadata:
         )
         self.assertTrue(any("id" in item for item in warnings))
 
+    def test_generated_column_editable_must_be_zero(self) -> None:
+        conn = sqlite3.connect(":memory:")
+        try:
+            conn.executescript(
+                """
+                CREATE TABLE gen_demo (
+                    id INTEGER PRIMARY KEY,
+                    base_value INTEGER NOT NULL,
+                    generated_value INTEGER GENERATED ALWAYS AS (base_value * 2) STORED
+                );
+                """
+            )
+            from db.display_metadata import init_display_metadata_tables, upsert_column_metadata
+            from db.display_metadata_validator import validate_column_permissions
+
+            cur = conn.cursor()
+            init_display_metadata_tables(cur)
+            upsert_column_metadata(
+                cur,
+                table_name="gen_demo",
+                column_name="generated_value",
+                display_name="生成值",
+                editable=1,
+            )
+            conn.commit()
+            errors, _ = validate_column_permissions(cur, "gen_demo")
+            self.assertTrue(any("generated" in err for err in errors))
+        finally:
+            conn.close()
+
+    def test_blob_column_editable_must_be_zero(self) -> None:
+        conn = sqlite3.connect(":memory:")
+        try:
+            conn.execute(
+                "CREATE TABLE blob_demo (id INTEGER PRIMARY KEY, payload BLOB NOT NULL)"
+            )
+            from db.display_metadata import init_display_metadata_tables, upsert_column_metadata
+            from db.display_metadata_validator import validate_column_permissions
+
+            cur = conn.cursor()
+            init_display_metadata_tables(cur)
+            upsert_column_metadata(
+                cur,
+                table_name="blob_demo",
+                column_name="payload",
+                display_name="载荷",
+                editable=1,
+            )
+            conn.commit()
+            errors, _ = validate_column_permissions(cur, "blob_demo")
+            self.assertTrue(any("BLOB" in err for err in errors))
+        finally:
+            conn.close()
+
+    def test_primary_key_editable_must_be_zero(self) -> None:
+        conn = sqlite3.connect(":memory:")
+        try:
+            conn.execute("CREATE TABLE pk_demo (id INTEGER PRIMARY KEY, title TEXT)")
+            from db.display_metadata import init_display_metadata_tables, upsert_column_metadata
+            from db.display_metadata_validator import validate_column_permissions
+
+            cur = conn.cursor()
+            init_display_metadata_tables(cur)
+            upsert_column_metadata(
+                cur,
+                table_name="pk_demo",
+                column_name="id",
+                display_name="编号",
+                editable=1,
+            )
+            conn.commit()
+            errors, _ = validate_column_permissions(cur, "pk_demo")
+            self.assertTrue(any("主键" in err for err in errors))
+        finally:
+            conn.close()
+
+    def test_readonly_table_with_editable_fields_warns(self) -> None:
+        conn = sqlite3.connect(":memory:")
+        try:
+            conn.executescript(
+                """
+                CREATE TABLE warn_demo (id INTEGER PRIMARY KEY, title TEXT);
+                """
+            )
+            from db.display_metadata import (
+                init_display_metadata_tables,
+                upsert_column_metadata,
+                upsert_table_metadata,
+            )
+            from db.display_metadata_validator import validate_column_permissions
+
+            cur = conn.cursor()
+            init_display_metadata_tables(cur)
+            upsert_table_metadata(cur, table_name="warn_demo", display_name="警告演示", readonly=1)
+            upsert_column_metadata(
+                cur,
+                table_name="warn_demo",
+                column_name="title",
+                display_name="标题",
+                editable=1,
+            )
+            conn.commit()
+            _, warnings = validate_column_permissions(cur, "warn_demo")
+            self.assertTrue(any("readonly=1" in item for item in warnings))
+        finally:
+            conn.close()
+
+    def test_writable_table_without_editable_fields_warns(self) -> None:
+        conn = sqlite3.connect(":memory:")
+        try:
+            conn.executescript(
+                """
+                CREATE TABLE warn_demo2 (id INTEGER PRIMARY KEY, title TEXT);
+                """
+            )
+            from db.display_metadata import (
+                init_display_metadata_tables,
+                upsert_column_metadata,
+                upsert_table_metadata,
+            )
+            from db.display_metadata_validator import validate_column_permissions
+
+            cur = conn.cursor()
+            init_display_metadata_tables(cur)
+            upsert_table_metadata(cur, table_name="warn_demo2", display_name="警告演示二", readonly=0)
+            upsert_column_metadata(
+                cur,
+                table_name="warn_demo2",
+                column_name="title",
+                display_name="标题",
+                editable=0,
+            )
+            conn.commit()
+            _, warnings = validate_column_permissions(cur, "warn_demo2")
+            self.assertTrue(any("readonly=0" in item and "editable=0" in item for item in warnings))
+        finally:
+            conn.close()
+
+    def test_schema_md_documents_task_logs_readonly_semantics(self) -> None:
+        path = os.path.join(get_skill_root(), "references", "SCHEMA.md")
+        with open(path, encoding="utf-8") as f:
+            text = f.read()
+        self.assertIn("readonly = 1", text)
+        self.assertIn("task_logs", text)
+        self.assertIn("seed_column_metadata_batch", text)
+        self.assertIn("valid_column_names", text)
+
 
 if __name__ == "__main__":
     unittest.main()

tests/test_docs_standards.py

@@ -242,6 +242,12 @@ class TestDocsStandards(unittest.TestCase):
         text = self._read("tools/README.md")
         self.assertIn("actions.json", text)
         self.assertIn("your-skill-slug", text)
+        self.assertIn("your_skill_slug", text)
+
+    def test_development_md_documents_both_slug_placeholders(self) -> None:
+        text = self._read("development/DEVELOPMENT.md")
+        self.assertIn("your-skill-slug", text)
+        self.assertIn("your_skill_slug", text)
 
     def test_schema_md_documents_data_management_contract(self) -> None:
         text = self._read("references/SCHEMA.md")

tests/test_scaffold_guard.py

@@ -10,8 +10,10 @@ import unittest
 from _support import get_skill_root
 
 TEMPLATE_MARKER = ".openclaw-skill-template"
-TEMPLATE_SLUG = "your-skill-slug"
+TEMPLATE_SLUG_KEBAB = "your-skill-slug"
+TEMPLATE_SLUG_UNDERSCORE = "your_skill_slug"
 SCAFFOLD_TEST_SLUG = "query-demo-records"
+SCAFFOLD_TEST_SLUG_UNDERSCORE = "query_demo_records"
 
 
 def _read_skill_slug() -> str:
@@ -27,7 +29,7 @@ def _read_skill_slug() -> str:
 class TestScaffoldGuard(unittest.TestCase):
     def test_template_repo_has_marker(self) -> None:
         slug = _read_skill_slug()
-        if slug != TEMPLATE_SLUG:
+        if slug != TEMPLATE_SLUG_KEBAB:
             self.skipTest(f"当前 SKILL_SLUG={slug!r}，非模板占位，跳过 template marker 断言")
         marker = os.path.join(get_skill_root(), TEMPLATE_MARKER)
         self.assertTrue(
@@ -37,7 +39,7 @@ class TestScaffoldGuard(unittest.TestCase):
 
     def test_business_skill_must_not_keep_template_marker(self) -> None:
         slug = _read_skill_slug()
-        if slug == TEMPLATE_SLUG:
+        if slug == TEMPLATE_SLUG_KEBAB:
             self.skipTest("当前仍为模板占位 slug，由 test_template_repo_has_marker 守护")
         marker = os.path.join(get_skill_root(), TEMPLATE_MARKER)
         self.assertFalse(
@@ -64,7 +66,7 @@ class TestScaffoldGuard(unittest.TestCase):
 
     def test_scaffold_replaces_slug_and_copies_actions_manifest(self) -> None:
         slug = _read_skill_slug()
-        if slug != TEMPLATE_SLUG:
+        if slug != TEMPLATE_SLUG_KEBAB:
             self.skipTest("仅在 skill-template 源仓库运行 scaffold 集成测试")
 
         import subprocess
@@ -94,7 +96,9 @@ class TestScaffoldGuard(unittest.TestCase):
             with open(actions_path, encoding="utf-8") as f:
                 manifest = json.load(f)
             self.assertEqual(manifest.get("skill"), SCAFFOLD_TEST_SLUG)
-            self.assertNotIn(TEMPLATE_SLUG, json.dumps(manifest))
+            manifest_raw = json.dumps(manifest)
+            self.assertNotIn(TEMPLATE_SLUG_KEBAB, manifest_raw)
+            self.assertNotIn(TEMPLATE_SLUG_UNDERSCORE, manifest_raw)
 
             actions_md = os.path.join(dest, "references", "ACTIONS.md")
             self.assertTrue(os.path.isfile(actions_md), msg="scaffold must copy references/ACTIONS.md")
@@ -109,7 +113,32 @@ class TestScaffoldGuard(unittest.TestCase):
             constants_path = os.path.join(dest, "scripts", "util", "constants.py")
             with open(constants_path, encoding="utf-8") as f:
                 constants_text = f.read()
-            self.assertNotIn(TEMPLATE_SLUG, constants_text)
+            self.assertNotIn(TEMPLATE_SLUG_KEBAB, constants_text)
+            self.assertNotIn(TEMPLATE_SLUG_UNDERSCORE, constants_text)
+            self.assertIn(f'SKILL_SLUG = "{SCAFFOLD_TEST_SLUG}"', constants_text)
+            self.assertIn(
+                f'LOG_LOGGER_NAME = "openclaw.skill.{SCAFFOLD_TEST_SLUG_UNDERSCORE}"',
+                constants_text,
+            )
+
+            skill_md_path = os.path.join(dest, "SKILL.md")
+            with open(skill_md_path, encoding="utf-8") as f:
+                skill_md = f.read()
+            self.assertIn(f"slug: {SCAFFOLD_TEST_SLUG}", skill_md)
+            self.assertNotIn(TEMPLATE_SLUG_KEBAB, skill_md)
+            self.assertNotIn(TEMPLATE_SLUG_UNDERSCORE, skill_md)
+
+    def test_scaffold_ps1_matches_python_placeholder_rules(self) -> None:
+        slug = _read_skill_slug()
+        if slug != TEMPLATE_SLUG_KEBAB:
+            self.skipTest("仅在 skill-template 源仓库运行 scaffold PS1 文案测试")
+
+        ps1_path = os.path.join(get_skill_root(), "tools", "scaffold_skill.ps1")
+        with open(ps1_path, encoding="utf-8") as f:
+            text = f.read()
+        self.assertIn("your-skill-slug", text)
+        self.assertIn("your_skill_slug", text)
+        self.assertIn('.Replace("-", "_")', text)
 
 
 if __name__ == "__main__":