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

assets/examples/README.md

@@ -5,3 +5,4 @@
 - `skill-cell-presentation.example.json`：数据管理单元格呈现文档形状参考（见 `references/CELL_PRESENTATION.md`）。
 - `render-html.action.example.json`：HTML 报告「重新生成」Action 形状参考（固定 id `render-html`；见 `references/ACTIONS.md`）。
 - `lookup-action.example.json`：Action 内联 Lookup 下拉形状参考（跨表引用勿填编号；见 `references/ACTIONS.md`「跨表引用：Lookup」）。
+- `visible-when-action.example.json`：Action 参数字段条件显隐 `visibleWhen` 形状参考（互斥模式联动；见 `references/ACTIONS.md`「字段条件显隐」；≠ Policy L3）。

assets/examples/visible-when-action.example.json

@@ -0,0 +1,72 @@
+{
+  "_comment": "形状参考：互斥模式用 inputSchema.properties.*.visibleWhen 联动显隐，勿只靠 description 灰字。完整契约见 references/ACTIONS.md「字段条件显隐」。勿与 POLICY.md L3 行态 visibleWhen 混淆。",
+  "schemaVersion": 1,
+  "skill": "your-skill-slug",
+  "actions": [
+    {
+      "id": "scrape-links-demo",
+      "label": "采集链接（示例）",
+      "description": "演示按采集方式切换参数：关键词路径 vs 作者主页路径。",
+      "placements": ["toolbar"],
+      "executionProfile": "async",
+      "interaction": "form",
+      "bind": {
+        "tables": ["demo_items"]
+      },
+      "confirmation": {
+        "message": "将按所选方式采集链接（示例确认文案）。是否继续？"
+      },
+      "entrypoint": {
+        "type": "cli",
+        "command": "run",
+        "args": [
+          "--collect-mode",
+          "{{collectMode}}",
+          "--keyword",
+          "{{keyword}}",
+          "--author-url",
+          "{{authorUrl}}",
+          "--max-count",
+          "{{maxCount}}"
+        ]
+      },
+      "inputSchema": {
+        "type": "object",
+        "required": ["collectMode"],
+        "properties": {
+          "collectMode": {
+            "type": "string",
+            "title": "采集方式",
+            "description": "先选方式，下方只出现对应参数。",
+            "enum": ["按关键词采集", "按作者主页采集"],
+            "default": "按关键词采集"
+          },
+          "keyword": {
+            "type": "string",
+            "title": "关键词",
+            "description": "例如 rpa。",
+            "visibleWhen": {
+              "field": "collectMode",
+              "equals": "按关键词采集"
+            }
+          },
+          "authorUrl": {
+            "type": "string",
+            "title": "作者主页链接",
+            "description": "例如 https://example.com/author/...",
+            "display_type": "url",
+            "visibleWhen": {
+              "collectMode": "按作者主页采集"
+            }
+          },
+          "maxCount": {
+            "type": "number",
+            "title": "数量上限",
+            "default": 50,
+            "minimum": 1
+          }
+        }
+      }
+    }
+  ]
+}

assets/schemas/skill-actions.schema.json

@@ -131,6 +131,48 @@
         "lookup": {
           "$ref": "#/$defs/lookupConfig",
           "description": "可选。内联同库表关联 Lookup（与列 options_json lookup 对象同构）。用于当前表没有对应列时；推荐同时设 display_type=lookup。见 ACTIONS.md「跨表引用：Lookup」。"
+        },
+        "visibleWhen": {
+          "description": "可选。表单字段条件显隐。宿主在数据管理/定时任务参数表单中：规则不满足则隐藏该字段、提交时省略、且不校验 required。支持 {field,equals} / {field,in:[...]}，或单键简写 {collectMode:\"按关键词采集\"} / {collectMode:[\"a\",\"b\"]}。Agent/CLI 无 UI 时同样按当前 input 求值后剥离隐藏字段。",
+          "oneOf": [
+            {
+              "type": "object",
+              "required": ["field", "equals"],
+              "additionalProperties": false,
+              "properties": {
+                "field": { "type": "string", "minLength": 1 },
+                "equals": { "type": ["string", "number", "boolean"] }
+              }
+            },
+            {
+              "type": "object",
+              "required": ["field", "in"],
+              "additionalProperties": false,
+              "properties": {
+                "field": { "type": "string", "minLength": 1 },
+                "in": {
+                  "type": "array",
+                  "minItems": 1,
+                  "items": { "type": ["string", "number", "boolean"] }
+                }
+              }
+            },
+            {
+              "type": "object",
+              "minProperties": 1,
+              "maxProperties": 1,
+              "additionalProperties": {
+                "oneOf": [
+                  { "type": ["string", "number", "boolean"] },
+                  {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": { "type": ["string", "number", "boolean"] }
+                  }
+                ]
+              }
+            }
+          ]
         }
       }
     },