docs: 沉淀 Action 表单 visibleWhen 条件显隐契约

tests/test_actions_manifest.py

@@ -257,6 +257,38 @@ class TestActionsManifest(unittest.TestCase):
         self.assertNotIn("hoverHint", action_def.get("required") or [])
         self.assertEqual(props["hoverHint"].get("type"), "string")
 
+    def test_schema_defines_visible_when_on_input_property(self) -> None:
+        schema = _load_actions_schema()
+        prop_def = schema["$defs"]["inputProperty"]
+        props = prop_def["properties"]
+        self.assertIn("visibleWhen", props)
+        self.assertNotIn("visibleWhen", prop_def.get("required") or [])
+        # Must live on input property, not action top-level (≠ Policy L3).
+        action_props = schema["$defs"]["action"]["properties"]
+        self.assertNotIn("visibleWhen", action_props)
+
+    def test_default_manifest_omits_visible_when(self) -> None:
+        for action in _load_actions_manifest()["actions"]:
+            properties = ((action.get("inputSchema") or {}).get("properties")) or {}
+            for name, prop in properties.items():
+                self.assertNotIn(
+                    "visibleWhen",
+                    prop if isinstance(prop, dict) else {},
+                    msg=f"{action['id']}.{name} default template should omit visibleWhen",
+                )
+
+    def test_visible_when_example_exists_and_uses_field_rules(self) -> None:
+        path = os.path.join(
+            get_skill_root(), "assets", "examples", "visible-when-action.example.json"
+        )
+        self.assertTrue(os.path.isfile(path), msg="visible-when example must exist")
+        with open(path, encoding="utf-8") as f:
+            example = json.load(f)
+        props = example["actions"][0]["inputSchema"]["properties"]
+        self.assertIn("visibleWhen", props["keyword"])
+        self.assertIn("visibleWhen", props["authorUrl"])
+        self.assertNotIn("visibleWhen", props["collectMode"])
+
     def test_default_manifest_omits_hover_hint(self) -> None:
         for action in _load_actions_manifest()["actions"]:
             self.assertNotIn(
@@ -554,6 +586,8 @@ class TestActionsManifest(unittest.TestCase):
             "hostEffects",
             "steps",
             "hoverHint",
+            "visibleWhen",
+            "字段条件显隐",
             "reloadTable",
             "afterSuccess",
             "afterFailure",

tests/test_docs_standards.py

@@ -363,9 +363,34 @@ class TestDocsStandards(unittest.TestCase):
             "_jiangchang_columns.description",
             "datetime_unix_seconds",
             "SCHEMA.md",
+            "字段条件显隐",
+            "visibleWhen",
         ):
             self.assertIn(marker, text, msg=f"ACTIONS.md missing {marker!r}")
 
+    def test_actions_md_disambiguates_visible_when_from_policy(self) -> None:
+        actions = self._read("references/ACTIONS.md")
+        policy = self._read("references/POLICY.md")
+        self.assertIn("字段条件显隐", actions)
+        self.assertIn("inputSchema.properties", actions)
+        self.assertTrue(
+            "POLICY.md" in actions and "L3" in actions,
+            msg="ACTIONS.md must point readers away from Policy L3 visibleWhen",
+        )
+        self.assertTrue(
+            "inputSchema" in policy and "ACTIONS.md" in policy,
+            msg="POLICY.md must disambiguate L3 visibleWhen from Action form visibleWhen",
+        )
+
+    def test_visible_when_example_is_listed(self) -> None:
+        text = self._read("assets/examples/README.md")
+        self.assertIn("visible-when-action.example.json", text)
+        checklist = self._read("development/CHECKLIST.md")
+        self.assertIn("A4-7", checklist)
+        self.assertIn("visibleWhen", checklist)
+        runtime = self._read("development/SKILL_ACTION_RUNTIME.md")
+        self.assertIn("visibleWhen", runtime)
+
     def test_guarded_docs_do_not_reference_amazon_implementation(self) -> None:
         forbidden = (
             "download-settlement-report-amazon",