docs: add PRODUCT_SURFACES peer entry contract for skill authors

docs: 沉淀 Action 表单 visibleWhen 条件显隐契约
docs: precipitate Action/CRUD Lookup contract for skill authors
2026-08-17 18:49:05 +08:00 · 2026-08-16 14:26:56 +08:00 · 2026-08-16 12:58:39 +08:00 · 2026-08-15 10:02:27 +08:00
20 changed files with 737 additions and 66 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,29 @@
 - 小节正文写用户能看懂的变化（新能力、修复、注意事项），避免堆砌内部实现细节
 - 打 tag 前**必须**为即将发布的版本新增一节；找不到匹配小节时，本次发布不会更新 changelog 字段

+## 1.0.85
+
+- 新增开发主文 `development/PRODUCT_SURFACES.md`：说明对话 / 数据管理 / 定时任务平级关系、何时走哪个入口、如何做入口定位
+- 需求与交活清单增加入口定位表；纠正「只做对话即可」与「Action 一概可选」的误导语气
+- 数据管理明确为 UI 执行面 + 过程可见，与对话同内核
+
+## 1.0.84
+
+- 沉淀 Action 参数表单字段条件显隐契约 `visibleWhen`（先选模式再出对应参数）
+- 文档入口：`ACTIONS.md` / `SKILL_ACTION_RUNTIME.md` / `CHECKLIST` A4-7；与 Policy L3 行态 `visibleWhen` 消歧
+- 新增示例 `assets/examples/visible-when-action.example.json`；Schema 已支持该字段
+
+## 1.0.83
+
+- 沉淀跨表 Lookup 契约：Action 可用内联 `lookup` 或绑列下拉，禁止让用户手填内部编号
+- 统一展示：`编号 · 名称`，可选 `extra_column` 时为 `编号 · 名称（额外）`
+- 更新 `ACTIONS.md` / `SCHEMA.md` / `skill-actions.schema.json`、示例与验收清单
+
+## 1.0.82
+
+- 沉淀数据管理技能按钮可选悬停字段 `hoverHint`：短名看不懂或会覆盖数据时再写；不回退说明或确认黄条
+- 宿主内置删除/刷新/新增/导入/导出不走该字段；默认 health/version/config-path 不加悬停
+
 ## 1.0.81

 - 模板默认不再创建或写入 `task_logs`：过程看运行日志，进度看任务中心，业务结果看业务表
--- a/SKILL.md
+++ b/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: 技能开发模板（通用业务版）
 description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。"
-version: 1.0.81
+version: 1.0.85
 author: 深圳匠厂科技有限公司
 metadata:
  openclaw:
@@ -31,7 +31,9 @@ allowed-tools:

 ### 架构铁律（先读）

+- **宿主产品入口平级**：对话任务 / 数据管理 / 定时任务是同一技能能力的不同触发场景，**同等重要**；挂哪些由本技能 UX 定义（入口定位表），详见 `development/PRODUCT_SURFACES.md`。以后宿主若增加新入口，仍是「新触发场景 + 同一内核」。
 - **单业务内核、多入口**：数据管理 / 定时任务 / Agent / 技能详情 / 直接 CLI 必须复用同一 domain service；禁止按入口复制业务逻辑，禁止按 `source` 分叉业务行为。
+- **数据管理**：既是 **UI 执行面**（点按钮走与对话相同的闭环），也是数据与过程可见；不是「只读库」。
 - **`placements`**：只决定 Action **出现在哪里**（toolbar / row / batch / cron / agent / skill-detail）。其中 `row` 表示**行级入口**（宿主可呈现为操作列、行右键、行内「⋯」等；技能配什么就显示什么，无独立菜单 DSL）。数据管理技能按钮顺序见 `actions` **数组相对顺序**（详见 `references/ACTIONS.md`），无独立 sortOrder。
 - **`bind.tables`**：只决定数据管理出现在哪些表；含 `toolbar` 时**必须**显式非空绑定。
 - **`executionProfile`**：只决定执行方式——`sync` 当场返回结果，`async` 进**任务中心**。与 placements / 入口**无关**。心智上多数为 sync，仅长任务 / RPA 标 async；宿主省略该字段时按 sync。每个 Action **仍必须**显式写 `sync` 或 `async`。
@@ -66,7 +68,7 @@ allowed-tools:
 1. **禁止**对长任务使用 `exec`/`bash` 跑 `…/scripts/main.py run`（或等价业务命令）再 `process poll` 干等。
 2. **禁止**用 `uv run python …` 跑技能脚本（会建临时环境，缺 `jiangchang_skill_core`）。
 3. **禁止** Agent 自行 `pip install`。
-4. Action **可选**：无数据管理 / 定时 / Agent 结构化调用需求时可不提供 `actions.json`；有长任务 / RPA 时**必须**提供至少一条 `executionProfile: "async"` 且 `placements` 含 `agent` 的 Action。
+4. **入口按定位表挂载**：复制业务技能后须在 `development/REQUIREMENTS.md` 填写入口定位表（见 `development/PRODUCT_SURFACES.md`）。定位需要数据管理 / 定时 / Agent 结构化调用时，必须提供 `actions.json` 并声明对应 `placements`；定位确认无需任何宿主结构化入口时可不提供。有长任务 / RPA 时**必须**提供至少一条 `executionProfile: "async"` 且 `placements` 含 `agent` 的 Action。
 5. **一个业务能力一个 Action**，用多个 `placements` 挂入口；底层仍是同一 `scripts/main.py` CLI。
 6. 是否进任务中心**只**看该 Action 的 `executionProfile`，与数据管理 / 定时 / Agent 入口无关。

@@ -128,7 +130,7 @@ python {baseDir}/scripts/main.py init-db
 | 根目录 `CHANGELOG.md` | 普通用户 | 市场 **更新日志** Tab（按版本小节 → `changelog`） |
 | `SKILL.md`（本文） | LLM / OpenClaw 平台 | 技能入口、触发与运行契约摘要 |
 | `references/` | Agent 编排 / 调用 | CLI、Action、schema 契约（Agent 主读） |
-| `development/` | 开发者 / AI 编程代理 | 需求、开发教程、测试、深度技术规范 |
+| `development/` | 开发者 / AI 编程代理 | 需求、开发教程、测试、深度技术规范；**产品入口**见 `development/PRODUCT_SURFACES.md` |

 ## 目录约定

@@ -143,7 +145,7 @@ python {baseDir}/scripts/main.py init-db
 1. 从本模板创建新业务技能时，**不得保留模板 `.git`**；优先使用 [`tools/scaffold_skill.ps1`](tools/scaffold_skill.ps1)（见 [`tools/README.md`](tools/README.md)）。
 2. 业务技能仓库中**不得**存在 `.openclaw-skill-template`（仅 template 源仓库保留）。
 3. 复制目录为你的新 skill 仓库，全局替换 `your-skill-slug` 等占位词。
-4. 按 `development/DEVELOPMENT.md` 完成开发与文档定制。
+4. 按 `development/DEVELOPMENT.md` 完成开发与文档定制；开发前先读 `development/PRODUCT_SURFACES.md` 并填写入口定位表。
 5. 用户市场四 Tab 材料写入根 `README.md` / `TUTORIAL.md` / `DEMO.md` / `CHANGELOG.md`；Agent 调用契约见 `references/CLI.md`、`references/SCHEMA.md`、`references/ACTIONS.md`。
 6. 同步修改 `scripts/util/constants.py` 中的 `SKILL_SLUG` / `SKILL_VERSION`。
 7. 本地 SQLite 的中文表名/字段名、标准时间字段与字段顺序规范见 `references/SCHEMA.md`。
--- a/assets/README.md
+++ b/assets/README.md
@@ -1,11 +1,11 @@
 # assets

- `actions.json`：Skill Action manifest 最小示例（**可选**；不需要宿主入口时可删除）。每个 action **必须**显式声明 `executionProfile`（`sync` \| `async`）。默认仅 `health` / `version` / `config-path`，不放 toolbar，故无 `bind` 示例。
+- `actions.json`：Skill Action manifest 最小示例（按入口定位表决定是否保留/扩展；见 `development/PRODUCT_SURFACES.md`）。每个 action **必须**显式声明 `executionProfile`（`sync` \| `async`）。默认仅 `health` / `version` / `config-path`，不放 toolbar，故无 `bind` 示例。
 - `html/example-report.html`：HTML 报告页最小壳（`{{TITLE}}` / `{{GENERATED_AT}}` / `{{BODY}}`）；渲染后须写入数据目录 `html/`，见 `references/ACTIONS.md`「HTML 页面报告」。
 - `examples/`：CLI 成功输出形状示例、以及 `render-html.action.example.json`（虚构路径与数据）。
 - `schemas/`：轻量 JSON Schema（`skill-actions.schema.json` 为**新技能严格规范**）。

-`skill-actions.schema.json` 使用 `additionalProperties: false`。正式支持 `bind.tables`（toolbar Action 必填）与可选 `bind.inputMapping`；placements 含 `toolbar` / `row` / `batch` / `cron` / `agent` / `skill-detail`（对齐匠厂宿主）。`concurrency`/`locks` 仍为预留。`placements` 与 `executionProfile` 正交——进任务中心只看 `async`，与入口无关。表级 Action 与 Agent 契约见 [`references/ACTIONS.md`](../references/ACTIONS.md)；开发深度规范见 [`development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。
+`skill-actions.schema.json` 使用 `additionalProperties: false`。正式支持 `bind.tables`（toolbar Action 必填）与可选 `bind.inputMapping`；placements 含 `toolbar` / `row` / `batch` / `cron` / `agent` / `skill-detail`（对齐匠厂宿主）。可选 `hoverHint` 为数据管理工具栏悬停（省略不显示，不回退）。`concurrency`/`locks` 仍为预留。`placements` 与 `executionProfile` 正交——进任务中心只看 `async`，与入口无关。表级 Action 与 Agent 契约见 [`references/ACTIONS.md`](../references/ACTIONS.md)；开发深度规范见 [`development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。

 - 用户市场四 Tab 见根目录 [`README.md`](../README.md) / [`TUTORIAL.md`](../TUTORIAL.md) / [`DEMO.md`](../DEMO.md) / [`CHANGELOG.md`](../CHANGELOG.md)
 - Agent 调用/编排参考见 [`references/`](../references/)（含 [`ACTIONS.md`](../references/ACTIONS.md)）
--- a/assets/examples/README.md
+++ b/assets/examples/README.md
@@ -4,3 +4,5 @@
 - `skill-policy-snapshot.*.example.json`：Data Policy Snapshot 形状参考（见 `references/POLICY.md`）。
 - `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）。
--- a/assets/examples/lookup-action.example.json
+++ b/assets/examples/lookup-action.example.json
@@ -0,0 +1,48 @@
+{
+  "_comment": "形状参考：Action 参数引用同库另一张表时用 Lookup 下拉，勿让用户填内部编号。完整契约见 references/ACTIONS.md「跨表引用：Lookup」与 references/SCHEMA.md。",
+  "schemaVersion": 1,
+  "skill": "your-skill-slug",
+  "actions": [
+    {
+      "id": "send-with-template",
+      "label": "按模板发送（示例）",
+      "description": "演示内联 lookup：从 message_templates 选模板；-- 表示自动挑选。",
+      "placements": ["toolbar"],
+      "executionProfile": "async",
+      "interaction": "form",
+      "bind": {
+        "tables": ["leads"]
+      },
+      "entrypoint": {
+        "type": "cli",
+        "command": "engage",
+        "args": ["--template-id", "{{templateId}}", "--content", "{{content}}"]
+      },
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "content": {
+            "type": "string",
+            "title": "正文",
+            "description": "填了就按这里发；留空则用下面的话术模板。",
+            "display_type": "textarea"
+          },
+          "templateId": {
+            "type": "number",
+            "title": "话术模板",
+            "description": "仅在正文留空时生效。选 -- = 自动挑选。",
+            "display_type": "lookup",
+            "lookup": {
+              "ref_table": "message_templates",
+              "value_column": "id",
+              "label_column": "name",
+              "extra_column": "channel",
+              "filter_column": "is_active",
+              "filter_value": 1
+            }
+          }
+        }
+      }
+    }
+  ]
+}
--- a/assets/examples/visible-when-action.example.json
+++ b/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
+          }
+        }
+      }
+    }
+  ]
+}
--- a/assets/schemas/skill-actions.schema.json
+++ b/assets/schemas/skill-actions.schema.json
@@ -2,7 +2,7 @@
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://openclaw.local/skill-template/skill-actions.schema.json",
  "title": "SkillActionManifest",
-  "description": "匠厂 skill-template 对新技能的严格 Action manifest 规范（schemaVersion 1）。additionalProperties=false 表示模板推荐契约；宿主运行时可能为兼容历史 manifest 接受部分缺省字段，但新技能不应依赖缺省行为。含可选 hostEffects/steps（匠厂宿主 ≥2.8.5）。",
+  "description": "匠厂 skill-template 对新技能的严格 Action manifest 规范（schemaVersion 1）。additionalProperties=false 表示模板推荐契约；宿主运行时可能为兼容历史 manifest 接受部分缺省字段，但新技能不应依赖缺省行为。含可选 hostEffects/steps（匠厂宿主 ≥2.8.5）与可选 hoverHint（数据管理工具栏悬停，需宿主已支持该字段）。",
  "type": "object",
  "required": ["schemaVersion", "skill", "actions"],
  "additionalProperties": false,
@@ -116,20 +116,108 @@
          "type": "string",
          "minLength": 1,
          "pattern": "^[a-z][a-z0-9_]*$",
-          "description": "可选。绑定业务表物理列名；replaces create/update 时宿主可复用该列的中文名与 lookup 下拉"
+          "description": "可选。绑定业务表物理列名；Action 弹窗（toolbar/batch）与 replaces create/update 抽屉均可复用该列的中文名与 lookup 下拉"
        },
        "display_type": {
          "type": "string",
-          "enum": ["textarea", "date", "datetime_unix_seconds", "url", "email"],
-          "description": "可选。表单控件提示；与 format 二选一即可。须与 CRUD display_type 语义对齐（见 ACTIONS.md / SCHEMA.md）。"
+          "enum": ["textarea", "date", "datetime_unix_seconds", "url", "email", "lookup"],
+          "description": "可选。表单控件提示；与 format 二选一即可。lookup=关联下拉（须配 lookup 对象或绑到已有 lookup 列）。须与 CRUD display_type 语义对齐（见 ACTIONS.md / SCHEMA.md）。"
        },
        "format": {
          "type": "string",
-          "enum": ["textarea", "date", "datetime_unix_seconds", "url", "email"],
+          "enum": ["textarea", "date", "datetime_unix_seconds", "url", "email", "lookup"],
          "description": "可选。display_type 别名，语义相同。"
+        },
+        "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"] }
+                  }
+                ]
+              }
+            }
+          ]
        }
      }
    },
+    "lookupConfig": {
+      "type": "object",
+      "required": ["ref_table", "value_column", "label_column"],
+      "additionalProperties": false,
+      "properties": {
+        "ref_table": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
+          "description": "同库被引用表名"
+        },
+        "value_column": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
+          "description": "提交值列（编号 / 外键）"
+        },
+        "label_column": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
+          "description": "主文案列"
+        },
+        "extra_column": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
+          "description": "可选。第三展示列；有值时宿主拼成「value · label（extra）」"
+        },
+        "filter_column": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
+          "description": "可选。等值过滤列"
+        },
+        "filter_value": {
+          "type": ["string", "number", "boolean", "null"],
+          "description": "可选。与 filter_column 配对的等值"
+        }
+      },
+      "description": "同库 FK 式 Lookup。展示：value · label；有 extra 时 value · label（extra）。宿主亦接受 camelCase 键名。"
+    },
    "inputSchema": {
      "type": "object",
      "required": ["type", "properties"],
@@ -203,7 +291,7 @@
            "minLength": 1,
            "pattern": "^[a-z][a-z0-9_]*$"
          },
-          "description": "可选。将 inputSchema 属性名映射到业务表物理列名，供 replaces create/update 抽屉复用列 displayName / lookup options。"
+          "description": "可选。将 inputSchema 属性名映射到业务表物理列名，供 Action 弹窗与 replaces create/update 抽屉复用列 displayName / lookup options。"
        }
      },
      "description": "表级绑定；toolbar 必填。可选 inputMapping / columnMapping。concurrency/locks 勿写入。"
@@ -295,6 +383,11 @@
          "type": "string",
          "minLength": 1
        },
+        "hoverHint": {
+          "type": "string",
+          "minLength": 1,
+          "description": "可选。数据管理工具栏悬停文案。与 description / confirmation.message 独立；省略则不显示悬停，不回退。需宿主已支持该字段。当前实现为顶栏技能按钮，不含宿主内置删除/刷新/新增/导入/导出。"
+        },
        "placements": {
          "type": "array",
          "minItems": 0,
--- a/development/CHECKLIST.md
+++ b/development/CHECKLIST.md
@@ -57,6 +57,8 @@ checklist_version: 1.0
 - [ ] S0-6 是否需要在任务中心查看进度或结果：是 / 否
 - [ ] S0-7 外部系统账号、数据、设备与操作权限的授权来源：
 - [ ] S0-8 是否包含提交、付款、删除、审批、发布、发送等不可逆副作用：是 / 否
+- [ ] S0-9 **入口定位表**（见 `PRODUCT_SURFACES.md` / `REQUIREMENTS` §0.1）：已填写 / 未填写
+- [ ] S0-10 本技能宣称的主用户路径涉及：对话 / 数据管理（执行或仅展示） / 定时（可多选；与定位表一致）

 ---

@@ -86,6 +88,8 @@ checklist_version: 1.0
 - [ ] A3-2 **P0** 缺参或非法输入时稳定失败（可读错误，不假成功）
 - [ ] A3-3 **P1** 失败可诊断：能从任务记录/提示判断失败阶段，而非只有“失败了”
 - [ ] A3-4 **P0** 同一能力从已声明的不同入口触发时，业务结果一致（不出现入口分叉成两套逻辑）
+- [ ] A3-5 **P0** `REQUIREMENTS` 入口定位表已填写；定位为「挂」的入口在 `actions.json`（及必要表元数据）中有对应声明
+- [ ] A3-6 **P1** 定位为「不挂」的入口有书面理由（不是空白遗漏）

 ---

@@ -96,6 +100,8 @@ checklist_version: 1.0
 - [ ] A4-3 **P0** 异步任务在任务中心能看到进行中与结束状态；结束有成功或失败结论
 - [ ] A4-4 **P1** 进行中的进度/步骤信息对用户可理解
 - [ ] A4-5 **P1** 已对外暴露的动作参数覆盖主路径关键输入（无“命令行能做、动作入口不能做”的关键缺口）
+- [ ] A4-6 **P0** 若 Action 需引用同库另一张业务表（话术/平台/账号等）：参数为 Lookup 下拉（内联 `lookup` 或绑列），**不是**手填内部编号；可选「自动」可留空提交
+- [ ] A4-7 **P1** 若 Action 有互斥采集/操作模式（如「按关键词 / 按主页」）：用 `inputSchema` 字段级 **`visibleWhen`** 联动显隐，勿只靠 `description` 灰字说明「仅某某时填写」（见 `references/ACTIONS.md`；勿与 Policy L3 行态 `visibleWhen` 混淆）

 ---

@@ -162,7 +168,7 @@ checklist_version: 1.0

 - [ ] A9-1 **P0** 仓库默认测试套件通过（执行技能约定的一键测试命令，如 `python tests/run_tests.py -v`）
 - [ ] A9-2 **P0** 不以「仅模拟档通过」作为交活依据（有真实档要求时必须真实跑通或书面阶段性豁免）
- [ ] A9-3 **P0** **NEED_MANUAL** 已声明的宿主入口（详情/Agent/工具栏/定时等）按声明抽测可通过
+- [ ] A9-3 **P0** **NEED_MANUAL** 入口定位表中定为「挂」的宿主入口（详情/Agent/工具栏/定时等）按声明抽测可通过；未在定位表中规划且未声明的入口可标 N/A（须引用定位表理由），**禁止**用「未声明」掩盖「从未做入口定位」
 - [ ] A9-4 **P1** 对外版本一致：详情、version、更新日志、发布标签能对上
 - [ ] A9-5 **P1** 开发者按平台规则能安装并测到该技能（若平台有开发者可见性要求）

--- a/development/DEVELOPMENT.md
+++ b/development/DEVELOPMENT.md
@@ -543,17 +543,20 @@ assets/actions.json             → placements / bind / executionProfile / entry
 - 打印用户提示
 - 拼接业务流程

-## 11.5 Skill Action manifest（可选）
+## 11.5 Skill Action manifest（按入口定位挂载）

-若技能需要出现在宿主**数据管理按钮**、**技能详情**、**定时任务**或 **Agent 直接调用**中，提供 `assets/actions.json`。
+先读 [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md)：对话 / 数据管理 / 定时任务**平级**；哪个主能力出现在哪个入口，由本技能 UX 在 `REQUIREMENTS` 入口定位表中定义。

+若定位表要求出现在宿主**数据管理按钮**、**技能详情**、**定时任务**或 **Agent 直接调用**中，提供 `assets/actions.json` 并写入对应 `placements`。
+
+- **产品入口与何时走哪个**见 [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md)
 - **运行时金标准**见 [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md)
 - 字段契约见 [`references/ACTIONS.md`](../references/ACTIONS.md)（`placements` / `bind.tables` / `executionProfile` 正交）
 - JSON Schema 见 [`assets/schemas/skill-actions.schema.json`](../assets/schemas/skill-actions.schema.json)
 - 模板最小示例仅暴露 `health` / `version` / `config-path`（均显式 `executionProfile: "sync"`；**不**自动加 toolbar）；CLI 另含 `init-db` 供宿主静默建库（不必做成 Action）
 - 含 `toolbar` 的 Action：**必须**声明合法 `bind.tables`（`POLICY-SKILL-ACTION-003`）
 - 含浏览器 RPA / 长耗时的业务技能：**必须**增加至少一条 `"executionProfile": "async"` 且 `placements` 含 `agent` 的 action（`POLICY-SKILL-ACTION-001`）
- 没有宿主直接操作需求时，**可以删除** `actions.json`；删除后勿保留失效引用
+- 入口定位表确认无任何宿主结构化入口需求时，**可以删除** `actions.json`；删除后勿保留失效引用
 - scaffold **不会**移除 Schema 中的 `bind` 支持，**不会**生成平台业务 Action 或业务表名；仅替换占位 slug

 宿主执行方式：
@@ -818,9 +821,14 @@ uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-relea
 - 安装后状态正常
 - 不会出现缺文件、缺入口或安装失败的问题

-### 第七步：按声明做宿主多入口验收（已声明的入口都要测；须看用户体验）
+### 第七步：按入口定位与声明做宿主多入口验收（须看用户体验）

-安装完成后，不要只停留在“已安装”状态，也**不要**只在本地 mock 通就认为完成。宿主侧栏有多条与技能相关的入口；**按本技能 `assets/actions.json` 的 `placements` / `executionProfile` 声明逐项自测**（契约见 [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md)、[`../references/ACTIONS.md`](../references/ACTIONS.md)）。未声明的入口可以跳过；**已声明却测不到，视为验收失败**。不要只测对话、忽略其它入口。
+安装完成后，不要只停留在“已安装”状态，也**不要**只在本地 mock 通就认为完成。对话任务 / 数据管理 / 定时任务在宿主上**平级**（见 [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md)）。先核对本技能 `REQUIREMENTS` **入口定位表**，再按 `assets/actions.json` 的 `placements` / `executionProfile` 对「定位为挂」的入口逐项自测（字段契约见 [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md)、[`../references/ACTIONS.md`](../references/ACTIONS.md)）。
+
+- 定位为「挂」却未声明或测不到 → **验收失败**
+- 定位为「不挂」且写了理由 → 可跳过该入口
+- **禁止**从未做入口定位、却用「未声明所以跳过」交差
+- 不要只测对话、忽略定位表中已挂的其它入口

 **用户体验（与功能入口并列，后台通了不算完）：**

--- a/development/PRODUCT_SURFACES.md
+++ b/development/PRODUCT_SURFACES.md
@@ -0,0 +1,172 @@
+# 宿主产品入口（对话 / 数据管理 / 定时任务）
+
+本文给**技能开发者**与 **AI 编程助手**读：说明匠厂宿主上几个**平级**业务入口各自干什么、**什么时候走哪个**、以及如何为本技能做入口定位。
+
+字段怎么写见 [`../references/ACTIONS.md`](../references/ACTIONS.md)、[`../references/SCHEMA.md`](../references/SCHEMA.md)；任务中心 / sync·async 见 [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md)。
+
+**与其它分类正交：**
+
+| 文档维度 | 回答的问题 |
+|----------|------------|
+| 本文（产品入口） | 用户从宿主哪条路径触发同一能力 |
+| Type A–D / 目录分层 | 技能有没有库、会不会调兄弟技能 |
+| RPA 四象限 | 外部系统怎么接 |
+
+不要把三者合并成一个大枚举。
+
+---
+
+## 1. 入口是什么（先立规矩）
+
+技能跑在**匠厂宿主**上，不是独立软件。宿主侧栏里的入口，是同一技能能力的不同**触发场景**：
+
+| 今日常见入口 | 触发方式 | 底层 |
+|--------------|----------|------|
+| **对话任务**（新建任务） | 自然语言 → Agent | 短 CLI，或 `run_skill_action`（`placements` 含 `agent`） |
+| **数据管理** | 点工具栏 / 行 / 批量 / 表单（UI） | `run_skill_action`（`source=data-management`）→ **同一 CLI** |
+| **定时任务** | 到点「技能直调」或定时 Agent | `run_skill_action`（`cron` / `cron-agent`）→ **同一 CLI** |
+
+**铁律：**
+
+1. **入口平级**：没有「对话主、数据管理/定时辅」。只是触发场景与交互方式不同，各自有优势。
+2. **同一业务能力、同一 domain service**：禁止按入口复制逻辑，禁止按 `source` 分叉业务结果。
+3. **同能力可挂多个入口**：不是三选一；按本技能 UX 决定挂哪些。
+4. **可扩展**：以后若宿主增加新入口，仍是「新触发场景 + 同一内核」，定位方法不变（定位表多一列即可）。
+5. **任务中心不是业务入口**：只表示 `executionProfile: async` 的执行壳；与从哪个入口点进来无关。
+
+---
+
+## 2. 什么时候走哪个入口
+
+### 2.1 对话任务——「用嘴发起」
+
+**适合：**
+
+- 用户用自然语言描述意图，条件一次说清或还要追问
+- 探索式：「能不能帮我……」「先看看再决定」
+- 对象临时指定（贴链接、说一个范围）
+- 需要 Agent 解释结果、失败原因、下一步
+- 用户不想打开数据管理，只想在聊天里办完
+
+**技术自问：** 用户会不会用一句话说清这件事？需要模型帮理解和确认吗？——会，就为该能力挂 `agent`（长任务 / RPA 必须 Action + 通常 `async`；短查询可用共享 Python CLI）。
+
+**注意：** 若技能还有「对着表运营 / 定时啃队列」等场景，**不要把对话当成唯一路径**，否则传统用户与省 token 路径会丢掉。
+
+### 2.2 数据管理——「用界面发起 + 看着数据做」
+
+数据管理有两层，**同等重要**：
+
+1. **执行面**：工具栏 / 行级 / 批量 / `replaces` 接管 CRUD —— 与对话一样触发同一 CLI，走完整业务闭环（传统用户可不聊天）。
+2. **运营面**：业务表、状态流向、配置、input/output、日志、HTML —— 看清数据从哪来、到哪去、卡在哪。
+
+**适合：**
+
+- 在业务数据上操作：看队列、选一行重试、勾选批量、顶栏「处理 N 条 / 同步」
+- 已知流程、参数结构化（表单 / 确认 / 一点即跑）——**省 token**，不必每次过模型
+- 准备与执行拆开：表里先准备，再在表上点执行
+- 服务不愿用 AI 对话的用户
+
+**技术自问：** 用户会不会打开这张表，靠点选就把主流程跑完？——要，就挂 `toolbar` / `row` / `batch` / `replaces`，并做好 `_jiangchang_*` 中文元数据。
+
+**不要：** 把数据管理理解成「只给开发者看 SQLite」；也不要在完全没有结构化操作对象时硬造空表按钮。
+
+### 2.3 定时任务——「到点自动发起」
+
+**适合：**
+
+- 同一能力需按节奏重复：消费队列、定期同步、巡检
+- 无人值守：默认参数即可跑，人不在场也正确、安全
+- 与对话 / 数据管理挂**同一个** Action，只改触发方式
+
+**技术自问：** 这件事明天能不能在人不盯着时自动再跑一遍？——能，挂 `cron`；不能，定位表写明不挂及理由。
+
+**慎挂：** 每次对象都不同须人指定；强不可逆且须当场确认；主路径依赖验证码 / 人工介入。
+
+### 2.4 场景对照（贴需求用）
+
+| 若用户场景是… | 优先考虑 | 说明 |
+|---------------|----------|------|
+| 「帮我处理这个……」（临时、口语） | 对话 | 灵活、可追问 |
+| 「对着表点一下就跑」 | 数据管理 | 结构化、省 token、传统用户 |
+| 「每天自动跑，不用我管」 | 定时 | 无人值守 |
+| 「偶尔对话下发，平时表上运营，夜里自动啃队列」 | **多个入口都挂同一能力** | 平级互补，不是重复开发 |
+| 「只看结果，从不在表上触发」 | 表可仅展示；执行挂对话/定时 | 由本技能 UX 定 |
+
+---
+
+## 3. 如何为本技能做入口定位（必做）
+
+模板**不**规定「某类技能必须三入口都挂满」。由技术按**本技能干什么 + 用户体验**填写定位表（写入 [`REQUIREMENTS.md`](REQUIREMENTS.md)）。
+
+对每个**主能力**（一条业务 CLI / 一个 Action）填一行：
+
+| 主能力（Action id / CLI） | 对话 | 数据管理 | 定时 | 不挂理由（若不挂） |
+|---------------------------|------|----------|------|--------------------|
+| （例）`download-run-pick` | 挂 | toolbar | 挂 | — |
+| （例）`download-video` | 挂 | 不挂 | 不挂 | 对象每次不同，须人指定链接 |
+
+**数据管理列怎么写：** `不挂` / `toolbar` / `row` / `batch` / `replaces` / `仅展示表（无业务按钮）`（可组合）。
+
+**规则只有三条：**
+
+1. 定位为「挂」的入口：必须在 `actions.json`（及必要元数据）中声明，且宿主可测通，并走同一内核。
+2. 定位为「不挂」的入口：必须有一句理由；禁止空白「忘了」。
+3. 未来新入口：表上多一列，方法不变。
+
+完整 ≠ 每个命令塞满所有入口；完整 = **想清楚用户路径后，该出现的入口都挂上了，且同内核**。
+
+---
+
+## 4. 怎么挂（最小路径）
+
+| 我想让用户… | 主要改什么 |
+|-------------|------------|
+| 能在对话里触发 | `SKILL.md` 意图路由 + `actions.json` 的 `placements` 含 `agent`（长任务 `async`） |
+| 能在数据管理看见结果 / 过程 | 业务表 + `init-db` + `_jiangchang_*`（见 SCHEMA） |
+| 能在表上点按钮走闭环 | `placements` 含 `toolbar`/`row`/`batch`，`toolbar` 须 `bind.tables` |
+| 能设定时自动跑 | 同一 Action 的 `placements` 含 `cron`；参数适合无人值守 |
+
+细节与 Schema：[`../references/ACTIONS.md`](../references/ACTIONS.md)。运行时：[`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md)。
+
+---
+
+## 5. 反例（不要这样做）
+
+- 只做对话 Action，从未填写入口定位表，也未考虑数据管理 / 定时用户路径
+- 为 toolbar / cron / agent 复制三套业务实现，或按 `source` 分叉结果
+- 把数据管理当成只读调试窗，主闭环只能聊天完成（若 UX 上本应支持 UI）
+- 不可逆、须确认的主路径默认挂 `cron` 且无产品确认
+- 用「Action 可选 / 定时以后再说」当作「可以不思考入口」
+
+---
+
+## 6. 附录：定位表示例（参考，非强制）
+
+### 示例 A：队列消费类（对话 + 表上处理 + 定时）
+
+| 主能力 | 对话 | 数据管理 | 定时 | 理由摘要 |
+|--------|------|----------|------|----------|
+| 入队 / 准备 | 挂 | 可 replaces 或表新增 | 不挂 | 准备态由人或对话写入 |
+| 处理 N 条 pending | 挂 | toolbar | 挂 | 运营点选与无人值守同一内核 |
+| 单条立即执行 | 挂 | 可选 row | 不挂 | 对象临时指定 |
+
+### 示例 B：单次确认发布类
+
+| 主能力 | 对话 | 数据管理 | 定时 | 理由摘要 |
+|--------|------|----------|------|----------|
+| 发布一条 | 挂 | 按是否落草稿表决定 | 不挂 | 不可逆，需人确认；不做无人值守 |
+
+### 示例 C：无库短查询
+
+| 主能力 | 对话 | 数据管理 | 定时 | 理由摘要 |
+|--------|------|----------|------|----------|
+| 查询 | 挂（或短 CLI） | 不挂 | 不挂 | 无本地业务表与重复批跑需求 |
+
+---
+
+## 7. 相关文档
+
+- 需求里填定位表：[`REQUIREMENTS.md`](REQUIREMENTS.md)
+- 交活怎么验：[`CHECKLIST.md`](CHECKLIST.md)
+- 开发步骤中的 Action 挂载：[`DEVELOPMENT.md`](DEVELOPMENT.md) §11.5、§15
+- Agent 侧字段契约：[`../references/ACTIONS.md`](../references/ACTIONS.md)
--- a/development/README.md
+++ b/development/README.md
@@ -9,13 +9,14 @@
 | 步骤 | 做什么 | 详见 |
 |------|--------|------|
 | 1 | **拿到仓库**：① 项目经理在 [自建 Gitea](https://git.jc2009.com/)（`git.jc2009.com`，非 Gitea 官网）开仓并授权后 `git clone`；或 ② 本地已有 `skill-template` 时用 scaffold / 复制出新目录（遵守 Git 红线） | [`DEVELOPMENT.md`](DEVELOPMENT.md) §1、§4 |
-| 2 | **先读 AI + RPA 总纲**；界面技能先完成元素拾取/element map，再按浏览器、桌面或手机读分端手册 | [`AI_RPA.md`](AI_RPA.md)、[`RPA_ELEMENT_LOCATING.md`](RPA_ELEMENT_LOCATING.md) |
-| 3 | 按 [`NAMING.md`](NAMING.md) 确认 slug；**先填** [`REQUIREMENTS.md`](REQUIREMENTS.md)，再写业务代码 | [`REQUIREMENTS.md`](REQUIREMENTS.md)、[`NAMING.md`](NAMING.md) |
-| 4 | 替换标识与占位，按四象限 / examples 实现 `scripts/service/` | [`DEVELOPMENT.md`](DEVELOPMENT.md) §4～§14 |
-| 5 | **配置 `developer_ids`（开发自测必做）**：开发期技能在匠厂默认不公开；不加则开发者自己也装测不了。从宿主设置复制用户 ID 写入 `SKILL.md` | [`DEVELOPMENT.md`](DEVELOPMENT.md) §6「关于 developer_ids」 |
-| 6 | 本地单测（mock）通过后，按业务默认 **`real_rpa`** 真实跑通；再 `release.ps1`；看 Gitea CI。**mock 通 ≠ 完成** | [`ADAPTER.md`](ADAPTER.md)；[`DEVELOPMENT.md`](DEVELOPMENT.md) §15 |
-| 7 | 匠厂安装后，按已声明入口自测，并看**用户体验**（进度、失败提示、有头 RPA 等） | [`DEVELOPMENT.md`](DEVELOPMENT.md) §15；[`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md) |
-| 8 | **交活验收（第三方）**：对照 [`CHECKLIST.md`](CHECKLIST.md) 验收；报告写入仓库根目录 [`acceptance-reports/`](../acceptance-reports/) | [`CHECKLIST.md`](CHECKLIST.md) |
+| 2 | **先读宿主产品入口**：对话 / 数据管理 / 定时任务平级；何时走哪个；为本技能填入口定位表 | [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md) |
+| 3 | **先读 AI + RPA 总纲**；界面技能先完成元素拾取/element map，再按浏览器、桌面或手机读分端手册 | [`AI_RPA.md`](AI_RPA.md)、[`RPA_ELEMENT_LOCATING.md`](RPA_ELEMENT_LOCATING.md) |
+| 4 | 按 [`NAMING.md`](NAMING.md) 确认 slug；**先填** [`REQUIREMENTS.md`](REQUIREMENTS.md)（含入口定位表），再写业务代码 | [`REQUIREMENTS.md`](REQUIREMENTS.md)、[`NAMING.md`](NAMING.md) |
+| 5 | 替换标识与占位，按四象限 / examples 实现 `scripts/service/` | [`DEVELOPMENT.md`](DEVELOPMENT.md) §4～§14 |
+| 6 | **配置 `developer_ids`（开发自测必做）**：开发期技能在匠厂默认不公开；不加则开发者自己也装测不了。从宿主设置复制用户 ID 写入 `SKILL.md` | [`DEVELOPMENT.md`](DEVELOPMENT.md) §6「关于 developer_ids」 |
+| 7 | 本地单测（mock）通过后，按业务默认 **`real_rpa`** 真实跑通；再 `release.ps1`；看 Gitea CI。**mock 通 ≠ 完成** | [`ADAPTER.md`](ADAPTER.md)；[`DEVELOPMENT.md`](DEVELOPMENT.md) §15 |
+| 8 | 匠厂安装后，按**入口定位表已挂**的入口自测，并看**用户体验**（进度、失败提示、有头 RPA 等） | [`DEVELOPMENT.md`](DEVELOPMENT.md) §15；[`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md)；[`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md) |
+| 9 | **交活验收（第三方）**：对照 [`CHECKLIST.md`](CHECKLIST.md) 验收；报告写入仓库根目录 [`acceptance-reports/`](../acceptance-reports/) | [`CHECKLIST.md`](CHECKLIST.md) |

 脚手架与 Git 防串库：[`../tools/README.md`](../tools/README.md)（`scaffold_skill.ps1`）。业务仓也可直接从自建 Gitea clone，见 [`DEVELOPMENT.md`](DEVELOPMENT.md) §4 来源 A。

@@ -25,23 +26,24 @@

 开始定制 skill 前，建议按以下顺序阅读：

-1. [`AI_RPA.md`](AI_RPA.md) — **AI Agent + RPA 总纲**：职责边界、合规红线、风控、操作节奏与完整闭环
-2. [`ACCOUNT_MANAGER.md`](ACCOUNT_MANAGER.md) — **浏览器账号标准**：一账号一 Profile、租约、多账号、数据查看、验收与排障
-3. [`SHARED_REPOS.md`](SHARED_REPOS.md) — **公共仓库目录**（模板 / 账号管理 / platform-kit 等，可扩展）
-4. [`REQUIREMENTS.md`](REQUIREMENTS.md) — 需求文档模板与验收标准
-5. [`NAMING.md`](NAMING.md) — slug / 仓库名命名规范（复制模板前必读）
-6. [`DEVELOPMENT.md`](DEVELOPMENT.md) — 完整开发步骤与目录规范
-7. [`TESTING.md`](TESTING.md) — 测试分层、隔离数据根与档位开关
-8. [`LOGGING.md`](LOGGING.md) — 日志分层、必打节点、敏感信息红线（**涉及长任务、RPA、外部系统时必读**）
-9. [`ADAPTER.md`](ADAPTER.md) — 涉及外部系统对接时
-10. [`RPA.md`](RPA.md) — 涉及浏览器 / 桌面 / 手机自动化时的会话、风控和工程总纲
-11. [`RPA_ELEMENT_LOCATING.md`](RPA_ELEMENT_LOCATING.md) — **所有界面技能必读**：真实拾取、element map、唯一性、降级和 AI 编程约束
-12. 按执行端选读：[`RPA_BROWSER.md`](RPA_BROWSER.md) / [`RPA_DESKTOP.md`](RPA_DESKTOP.md) / [`RPA_MOBILE.md`](RPA_MOBILE.md)
-13. [`CONFIG.md`](CONFIG.md) — `.env` 规范与 bootstrap 机制
-14. [`DATA_PATHS.md`](DATA_PATHS.md) — 下载/导入/导出等本地文件路径标准（涉及文件读写时必读）
-15. [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md) — Skill Action sync/async、任务中心、Agent 禁令、队列 pick（涉及 RPA / 长任务 / 数据管理按钮 / Cron / Agent 时必读）
-16. [`RUNTIME.md`](RUNTIME.md) — 共享 runtime、数据路径、发布打包与编码约定
-17. [`CHECKLIST.md`](CHECKLIST.md) — **交活验收清单（第三方视角）**；报告输出到 [`../acceptance-reports/`](../acceptance-reports/)
+1. [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md) — **宿主产品入口**：对话 / 数据管理 / 定时任务平级；何时走哪个；入口定位表
+2. [`AI_RPA.md`](AI_RPA.md) — **AI Agent + RPA 总纲**：职责边界、合规红线、风控、操作节奏与完整闭环
+3. [`ACCOUNT_MANAGER.md`](ACCOUNT_MANAGER.md) — **浏览器账号标准**：一账号一 Profile、租约、多账号、数据查看、验收与排障
+4. [`SHARED_REPOS.md`](SHARED_REPOS.md) — **公共仓库目录**（模板 / 账号管理 / platform-kit 等，可扩展）
+5. [`REQUIREMENTS.md`](REQUIREMENTS.md) — 需求文档模板与验收标准（含入口定位表）
+6. [`NAMING.md`](NAMING.md) — slug / 仓库名命名规范（复制模板前必读）
+7. [`DEVELOPMENT.md`](DEVELOPMENT.md) — 完整开发步骤与目录规范
+8. [`TESTING.md`](TESTING.md) — 测试分层、隔离数据根与档位开关
+9. [`LOGGING.md`](LOGGING.md) — 日志分层、必打节点、敏感信息红线（**涉及长任务、RPA、外部系统时必读**）
+10. [`ADAPTER.md`](ADAPTER.md) — 涉及外部系统对接时
+11. [`RPA.md`](RPA.md) — 涉及浏览器 / 桌面 / 手机自动化时的会话、风控和工程总纲
+12. [`RPA_ELEMENT_LOCATING.md`](RPA_ELEMENT_LOCATING.md) — **所有界面技能必读**：真实拾取、element map、唯一性、降级和 AI 编程约束
+13. 按执行端选读：[`RPA_BROWSER.md`](RPA_BROWSER.md) / [`RPA_DESKTOP.md`](RPA_DESKTOP.md) / [`RPA_MOBILE.md`](RPA_MOBILE.md)
+14. [`CONFIG.md`](CONFIG.md) — `.env` 规范与 bootstrap 机制
+15. [`DATA_PATHS.md`](DATA_PATHS.md) — 下载/导入/导出等本地文件路径标准（涉及文件读写时必读）
+16. [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md) — Skill Action sync/async、任务中心、Agent 禁令、队列 pick（涉及 RPA / 长任务 / 数据管理按钮 / Cron / Agent 时必读）
+17. [`RUNTIME.md`](RUNTIME.md) — 共享 runtime、数据路径、发布打包与编码约定
+18. [`CHECKLIST.md`](CHECKLIST.md) — **交活验收清单（第三方视角）**；报告输出到 [`../acceptance-reports/`](../acceptance-reports/)

 Agent 调用契约见 [`../references/CLI.md`](../references/CLI.md)、[`../references/SCHEMA.md`](../references/SCHEMA.md)、[`../references/ACTIONS.md`](../references/ACTIONS.md)。  
 用户市场四 Tab 见根目录 [`README.md`](../README.md) / [`TUTORIAL.md`](../TUTORIAL.md) / [`DEMO.md`](../DEMO.md) / [`CHANGELOG.md`](../CHANGELOG.md)，不要写进本目录。
--- a/development/REQUIREMENTS.md
+++ b/development/REQUIREMENTS.md
@@ -31,7 +31,23 @@
  - **登记 ≠ 登录**：ensure/add-web 只建账号与 Profile；站点登录由本技能在有头浏览器中完成
  - **反模式**：把「需要登录态才能采到数据」的需求写成 `optional`，再省略 `ensure_logged_in`

-## 0.1 AI + RPA 协作与授权边界（涉及外部系统时必填）
+## 0.1 宿主入口定位（必填）
+
+先读 [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md)。对话任务 / 数据管理 / 定时任务在宿主上**平级**；挂哪些由本技能业务与 UX 定，模板不规定「必须三入口都挂满」。
+
+对每个主能力填一行（可增行；「不挂」必须写理由）：
+
+| 主能力（Action id / CLI） | 对话 | 数据管理 | 定时 | 不挂理由（若不挂） |
+|---------------------------|------|----------|------|--------------------|
+| （例）`<action-or-cli>` | 挂 / 不挂 | 不挂 / toolbar / row / batch / replaces / 仅展示表 | 挂 / 不挂 | |
+
+说明：
+
+- 数据管理列可写组合（如 `toolbar + row`）
+- 「仅展示表」= 用户要看过程/结果，但不在表上触发该能力
+- 定位为「挂」的入口须在 `assets/actions.json`（及必要表元数据）中落实，并与对话路径共用同一 domain service
+
+## 0.2 AI + RPA 协作与授权边界（涉及外部系统时必填）

 ### Agent 设计

@@ -131,12 +147,13 @@
 - 支持 `python scripts/main.py <your-main-command>`
 - 支持核心业务编排（HTTP / 批处理 / 可选 RPA，按四档 adapter 选型）
 - 支持失败可诊断（统一文件日志 + 任务中心 `finish`）
+- 完成 [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md) 入口定位表，并按表落实已挂入口（对话 / 数据管理 / 定时按本技能 UX）

 ### 可后续扩展

- 支持定时批跑
 - 支持失败自动重试
 - 支持多 `<目标系统>` 轮询
+- 入口定位表中已标明「本期不挂」且写了理由的能力（例如暂不挂定时）

 ## 5. 非功能要求

@@ -214,7 +231,7 @@
 - 真实联调样例仍放 `tests/integration/`，默认套件不包含真实外联（与业务 `.env` 默认 `real_rpa` 不冲突）
 - `SKILL.md` 的 `developer_ids` 已配置为开发者本人匠厂用户 ID（开发期不公开时，否则本人无法在市场安装自测；取 ID 步骤见 `development/DEVELOPMENT.md` §6）
 - 发布后 Gitea 工作流成功；匠厂技能市场对开发者账号可见最新版本并可安装
- 安装后按本技能 `actions.json` 声明完成宿主多入口验收（见 `development/DEVELOPMENT.md` §15）；**须看用户体验**（进度可见、失败可读、RPA 有头、文案与真实行为一致等），后台通了不算完
+- 安装后按本技能入口定位表与 `actions.json` 声明完成宿主多入口验收（见 `development/DEVELOPMENT.md` §15、`PRODUCT_SURFACES.md`）；**须看用户体验**（进度可见、失败可读、RPA 有头、文案与真实行为一致等），后台通了不算完
 - 已人工核验授权与技术路线：无破解、逆向、私有协议、验证码绕过、Hook / 注入、自动换号或其他规避平台限制的实现
 - RPA 真实主路径已验证状态等待、`1～3` 秒正常操作节奏、有限重试、账号 / 设备串行、人工介入、结果核验和结束存证
 - RPA 关键元素已在真实界面拾取并登记 element map；关键动作唯一定位，重启会话后复测通过
@@ -304,7 +321,7 @@
 - 命令可运行；tests/run_tests.py -v 通过
 - 业务表（若有）符合 SCHEMA；过程看运行日志，进度看任务中心
 - `developer_ids` 已配置为「你的用户ID」（匠厂设置中复制的正整数）
- 正式环境安装验证通过；已声明的宿主入口（新建任务 / 数据管理 / 定时任务 / 任务中心 / 技能详情等）按 DEVELOPMENT §15 自测
+- 正式环境安装验证通过；已声明的宿主入口（新建任务 / 数据管理 / 定时任务 / 任务中心 / 技能详情等）按 DEVELOPMENT §15 与入口定位表自测
 ## 10. 开发注意事项

 - 不修改无关项目；不引入旧模板结构
--- a/development/SKILL_ACTION_RUNTIME.md
+++ b/development/SKILL_ACTION_RUNTIME.md
@@ -2,12 +2,14 @@

 本文是匠厂宿主 **Skill Action / 任务中心** 的技能侧金标准。涉及浏览器 RPA、长耗时任务、数据管理按钮、定时任务或 Agent 直接调用时**必读**。

+**产品入口（平级关系、何时挂哪个）**先读 [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md)；本文管 sync/async、任务中心与编排。
+
 **边界：**

 | 文档 | 职责 |
 |------|------|
 | 本文 | sync/async、任务中心、Agent 禁令、单内核编排、队列 pick、同步 vs 导出 |
-| [`../references/ACTIONS.md`](../references/ACTIONS.md) | `actions.json` 字段、placements、`bind.tables`、inputSchema |
+| [`../references/ACTIONS.md`](../references/ACTIONS.md) | `actions.json` 字段、placements、`bind.tables`、inputSchema、跨表 Lookup、字段条件显隐 `visibleWhen` |
 | [`LOGGING.md`](LOGGING.md) | `job_context` / `emit` / `finish` / Run Journal |
 | [`DATA_PATHS.md`](DATA_PATHS.md) | 下载/导入等落盘路径 |

@@ -19,7 +21,7 @@

 1. **宿主管调度，技能管业务** — 不自行实现任务中心 / Job 轮询 / 后台守护进程。
 2. **单业务内核、多入口** — 数据管理、定时任务、Agent、技能详情与直接 CLI 复用同一 domain service；禁止按入口复制业务逻辑。
-3. **五职责正交** — `placements` / `bind.tables` / `executionProfile` / `entrypoint` / domain service 各管一事（见 ACTIONS.md）。可选第六轴 **policy**（见 `references/POLICY.md`）：未启用 = L0 与今日一致。可选 **`hostEffects` / `steps`**（见 ACTIONS.md）：数据管理交互前后的 UI/级联编排；省略 = 不额外改 UI（匠厂宿主 ≥2.8.5）。可选 **`cellPresentation`**（见 `references/CELL_PRESENTATION.md`）：单元格语义标色；省略 = P0。
+3. **五职责正交** — `placements` / `bind.tables` / `executionProfile` / `entrypoint` / domain service 各管一事（见 ACTIONS.md）。可选第六轴 **policy**（见 `references/POLICY.md`）：未启用 = L0 与今日一致。可选 **`hostEffects` / `steps`**（见 ACTIONS.md）：数据管理交互前后的 UI/级联编排；省略 = 不额外改 UI（匠厂宿主 ≥2.8.5）。可选 **`hoverHint`**（见 ACTIONS.md）：数据管理工具栏悬停；省略 = 不显示，不回退说明或确认黄条。可选 **`visibleWhen`**（见 ACTIONS.md）：Action 参数表单字段条件显隐；省略 = 字段始终平铺；**勿与** Policy L3 行态 `visibleWhen` 混淆。可选 **`cellPresentation`**（见 `references/CELL_PRESENTATION.md`）：单元格语义标色；省略 = P0。
 4. **长耗时建议 async** — 开浏览器、RPA、HTTP 大文件下载等建议 `executionProfile: "async"`，进**任务中心**；这是对**方法**的选择，**不**限制可以出现在哪些 placement / 入口。
 5. **Agent：短 CLI / 长 Action** — 短查询可用共享 Python bash CLI；长任务 / RPA **禁止** `exec` + `process poll`，必须 `run_skill_action`。
 6. **进度走 Journal** — `emit` / `video.add_step` → Run Journal；UI / Skill Run Card / 任务中心展示；**不靠 stdout 流**。
--- a/references/ACTIONS.md
+++ b/references/ACTIONS.md
@@ -2,6 +2,8 @@

 本文件说明 `assets/actions.json` 与 `scripts/main.py` CLI 的对应关系，供 **Agent 编排**与宿主 **Skill Action Runtime** 使用。这是 Agent 侧关于 Action / 任务中心的**主契约**；实现细节与开发规范见 [`../development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。

+**先读产品入口：** 对话 / 数据管理 / 定时任务在宿主上**平级**，何时挂哪个入口见 [`../development/PRODUCT_SURFACES.md`](../development/PRODUCT_SURFACES.md)（本文只讲字段与执行模型）。
+
 **边界：** 用户市场四 Tab 见根目录 [`README.md`](../README.md) / [`TUTORIAL.md`](../TUTORIAL.md) / [`DEMO.md`](../DEMO.md) / [`CHANGELOG.md`](../CHANGELOG.md)；CLI 参数见 [`CLI.md`](CLI.md)。

 ## Agent 何时用 Action（与 CLI 的分工）
@@ -48,10 +50,10 @@ JSON Schema 使用 `additionalProperties: false` 表达模板严格边界；这

 ## Action 是否必需

-Action 是**可选能力**：
+Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**决定（见 [`../development/PRODUCT_SURFACES.md`](../development/PRODUCT_SURFACES.md)），不是「可有可无的附属能力」：

- 没有宿主直接操作需求的技能，**可以不提供** `actions.json`。
- 需要出现在**数据管理按钮**、**技能详情**、**定时任务**或 **Agent 直接调用**中的技能，**必须**提供 `assets/actions.json`。
+- 定位需要出现在**数据管理按钮**、**技能详情**、**定时任务**或 **Agent 直接调用**中时，**必须**提供 `assets/actions.json` 并声明对应入口。
+- 定位确认无任何宿主结构化入口时，**可以不提供** `actions.json`。
 - **含浏览器 RPA / 长耗时任务**的技能：**必须**提供至少一条 `executionProfile: "async"` 且 `placements` 含 `agent` 的 action（见 `POLICY-SKILL-ACTION-001`）。

 ## 文件位置
@@ -85,6 +87,8 @@ Action 是**可选能力**：
 | **`bind.tables`** | 数据管理里出现在**哪些业务表** | 不决定业务实现 |
 | **`executionProfile`** | 宿主是**同步等待**还是**异步 Job** | 不限制可展示入口，不决定是否弹窗 |
 | **`interaction`** | 可点击入口（数据管理 toolbar/row/batch、默认 CRUD 接管、未来 skill-detail）**点了怎么交互** | 不决定 sync/async；**cron 触发与 agent 忽略** |
+| **`hoverHint`** | **可选**：数据管理**工具栏悬停**文案 | 不决定短按钮名；不决定点下去弹不弹窗；**不回退** `description` / `confirmation.message`；省略 = 不显示悬停。当前宿主实现为顶栏技能按钮 |
+| **`inputSchema.visibleWhen`** | **可选**：Action **参数表单**字段条件显隐（先选模式再出对应参数） | **不是** Data Policy L3 行态 `visibleWhen`；不决定 placements；旧宿主忽略则字段平铺全显 |
 | **`hostEffects` / `steps`** | **可选**：数据管理交互跑完前后，宿主要不要刷新表 / 清选区 / 级联删等 | 不决定业务写什么；**省略 = 宿主不额外改 UI**（≥2.8.5 起不再硬编码 mutation 后刷新）；cron/agent 忽略 |
 | **`cellPresentation`** | **可选**：某表某行某列的语义标色/强调（tone + 说明） | 不替代业务列；不下发 CSS；用途不限（超时、预警、驳回等）；见 [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md) |
 | **`policy` / Snapshot** | **可选**：当前身份在数据管理下允许哪些 Action / 宿主内置能力 / 行列范围 | 不替代 placements；不替代 domain 写路径鉴权；多数技能不配 = L0 全开 |
@@ -98,15 +102,17 @@ Action 是**可选能力**：
 | 层级 | 稳定字段 / 能力 |
 |------|----------------|
 | 顶层 | `schemaVersion`、`skill`、`actions`；可选 **`policy`**（Data Policy 启用块）；可选 **`cellPresentation`**（单元格呈现启用块） |
-| action | `id`、`label`、`description`、`placements`、`entrypoint`、**`executionProfile`（必填）**；可选 `inputSchema`、`confirmation`、**`interaction`**、**`interactionByPlacement`**、**`bind`**、**`replaces`**、**`hostEffects`**、**`steps`**、**`authz`**（仅文档提示） |
+| action | `id`、`label`、`description`、`placements`、`entrypoint`、**`executionProfile`（必填）**；可选 `hoverHint`、`inputSchema`、`confirmation`、**`interaction`**、**`interactionByPlacement`**、**`bind`**、**`replaces`**、**`hostEffects`**、**`steps`**、**`authz`**（仅文档提示） |
 | entrypoint | `type = cli`、`command`、`args`（**必填** JSON 数组，项为 `string` / `number` / `boolean`） |
 | placements | `toolbar`、`row`、`batch`、`skill-detail`、`agent`、`cron`；仅 `replaces` 时可为空数组 |
 | **replaces** | 可选 `"create"` \| `"update"` \| `"delete"` — 接管默认新增/编辑/删除（须 `bind.tables`） |
 | **bind** | `{ "tables": ["business_table"] }`；可选 `inputMapping`（行内/批量预填，见下节） |
 | **policy** | 可选；`enabled` + `entrypoint`（推荐 `policy` CLI）；见 POLICY.md。未启用 = L0 |
 | **cellPresentation** | 可选；`{ "enabled": true }` 时宿主应加载单元格呈现；见 [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md)。未启用 = P0 |
-| inputSchema | 根 `type: object`；properties 使用 `string` / `number` / `boolean`；支持 `enum`、`default`、`required`、`sensitive`、`readOnly`；可选 `display_type` / `format`（`textarea` / `date` / `datetime_unix_seconds` / `url` / `email`） |
+| inputSchema | 根 `type: object`；properties 使用 `string` / `number` / `boolean`；支持 `enum`、`default`、`required`、`sensitive`、`readOnly`；可选 `display_type` / `format`（`textarea` / `date` / `datetime_unix_seconds` / `url` / `email` / `lookup`）；可选 **`visibleWhen`**（字段条件显隐，见专节） |
 | confirmation | `{ "message": "..." }` — **风险文案**（confirm/form 弹窗黄条；agent 元数据）；**不是**「要不要弹窗」的开关 |
+| **hoverHint** | 可选字符串。数据管理**工具栏悬停**文案；与 `description` / `confirmation.message` **独立**。省略则不显示悬停，不回退。短名已够懂时不要写。需宿主已支持该字段；当前实现为顶栏技能按钮，不含宿主内置删除/刷新/新增/导入/导出 |
+| **visibleWhen** | 可选。写在 **property** 上（非 action 顶层）：依赖同表单其它字段值决定是否展示；隐藏字段不提交、不校验 `required`。**勿与** [`POLICY.md`](POLICY.md) L3 行态 `visibleWhen` 混淆 |
 | **executionProfile** | `"sync"` \| `"async"`（**必须显式写出**，禁止依赖缺省） |
 | **interaction** | `"auto"` \| `"direct"` \| `"confirm"` \| `"form"`（可选；省略≈`auto`） |
 | **interactionByPlacement** | 可选；按 placement 覆盖为 `direct`/`confirm`/`form`（不可写 `auto`） |
@@ -174,11 +180,12 @@ Action 是**可选能力**：
 - `update` / `delete` 可用 `inputMapping`（`$row.$pk`、`$selection.ids`）预填主键。
 - 宿主导入仍直写：有 `replaces:create` 的表慎用宿主导入，或另做 import Action。
 - 整表 `_jiangchang_tables.readonly=1` 时仍隐藏写按钮（优先于 `replaces`）。
- **列元数据复用（lookup）**：create/update 抽屉可将 `inputSchema` 字段对齐业务列，复用中文名与 lookup 下拉：
+- **列元数据复用（lookup）**：Action 表单（含 toolbar/batch 弹窗与 create/update 抽屉）可将 `inputSchema` 字段对齐业务列，复用中文名与 lookup 下拉：
  - 优先让属性名 = 物理列名（如 `platform_key`）；
  - 或 `bind.columnMapping`：`{ "platform": "platform_key" }`；
  - 或字段上写 `"column": "platform_key"`。
-  - **不要**在 actions.json 里写死会过期的全量平台 `enum`。
+  - 当前表没有对应列时，用字段内联 `lookup`（见下文「跨表引用：Lookup」）。
+  - **不要**在 actions.json 里写死会过期的全量平台 `enum`，也**不要**让用户手填内部编号。

 ## `interaction`（点击交互方式）

@@ -253,6 +260,30 @@ Action 是**可选能力**：
 - **cron 触发 / agent**：忽略 `interaction`（无人值守 / 模型填参）；`confirmation` 对 agent 仍作 `requiresConfirmation` 元数据。
 - 不要用 `interaction: "direct"` 掩盖需要用户填写的可编辑字段——宿主在 `auto` 下会因可编辑参数回落到 `form`；显式 `direct` + 可编辑字段时参数取 default/预填，作者须自觉。

+## `hoverHint`（工具栏悬停，可选）
+
+与 `label` / `description` / `confirmation.message` **独立**。只决定数据管理**顶栏技能按钮**鼠标悬停时显示什么。
+
+- **省略 / 空白** ⇒ 不显示悬停，**不回退**灰色说明或确认黄条。
+- 短按钮名已经够懂时**不要写**，避免噪音。适合：业务黑话、会覆盖本机/远程、不点进去看不出后果。
+- 悬停文案不要写成「确认开始？」；那是点下去之后黄条的口吻。
+- 当前宿主实现为**工具栏技能按钮**；宿主内置删除/刷新/新增/导入/导出不走本字段。
+- 需宿主已支持 `hoverHint`；更旧宿主会忽略未知字段（模板 Schema 仍会校验新技能）。
+
+```json
+{
+  "id": "kb-sync-feishu",
+  "label": "拉取到本机",
+  "description": "把飞书知识库覆盖到本机工作区。未发布的本地修改会丢失。",
+  "hoverHint": "将用飞书覆盖本机知识库，未发布的本地修改会丢失。",
+  "placements": ["toolbar"],
+  "executionProfile": "async",
+  "interaction": "confirm",
+  "confirmation": { "message": "将用飞书覆盖本机知识库，未发布的本地修改会丢失。确认开始？" },
+  "bind": { "tables": ["kb_sources"] }
+}
+```
+
 ## `hostEffects` / `steps`（执行前后宿主编排，≥2.8.5）

 与 `placements` / `executionProfile` / `interaction` **正交**。决定的是：数据管理里点完 Action 之后（或之前），宿主要不要**刷新当前表、刷新目录、清空多选、级联删子表**等。
@@ -471,6 +502,7 @@ HINT: <next step>
 禁止：

 - 臆造 `sortOrder` / `order` / `priority` 等字段指望宿主排序（模板 Schema `additionalProperties: false` 会拒收）。
+- 臆造 `tooltip` / `title` 等字段当悬停（用可选 `hoverHint`；不要把 `confirmation.message` 复用成悬停）。
 - 依赖或宣传表顶栏「更多操作」溢出菜单（宿主已取消该能力）。
 - 把「表格行数据默认排序」与按钮顺序混淆——行排序见 [`SCHEMA.md`](SCHEMA.md) 的 `default_sort_json`。
 - 把「默认展示列」与 `visible=0` 硬隐藏混淆——默认展示列见 [`SCHEMA.md`](SCHEMA.md) 的 `default_visible_columns_json`。
@@ -556,6 +588,57 @@ HINT: <next step>
 - [ ] 成功路径带 `refreshCatalog`（或等价让侧栏/预览看到更新）

 ## inputSchema 与参数表单
+
+### 跨表引用：Lookup（宿主已支持；勿让用户填编号）
+
+当 Action 参数要引用**同库另一张业务表**的一行（话术模板、平台、账号等）时，必须用 Lookup 下拉，**禁止**做成「请填写编号」的数字框（用户记不住内部 id，体验差）。
+
+| 场景 | 怎么配 | 说明 |
+|------|--------|------|
+| 当前表已有同含义列，且列上已是 CRUD lookup | `column` / `bind.columnMapping`，或属性名 = 列名 | toolbar/batch 弹窗与 create/update 抽屉都会复用该列已解析的选项 |
+| 当前表没有该列（如在「潜客」表上选「话术模板」） | `display_type: "lookup"` + 字段内联 `lookup` 对象 | 打开表单时宿主按当前技能库解析选项 |
+
+内联 `lookup` 与列元数据 `options_json` **同构**（见 [`SCHEMA.md`](SCHEMA.md)「表关联 lookup」）：
+
+```json
+{
+  "templateId": {
+    "type": "number",
+    "title": "话术模板",
+    "description": "仅在正文留空时生效；选 -- 表示自动挑选。",
+    "display_type": "lookup",
+    "lookup": {
+      "ref_table": "message_templates",
+      "value_column": "id",
+      "label_column": "name",
+      "extra_column": "channel",
+      "filter_column": "is_active",
+      "filter_value": 1
+    }
+  }
+}
+```
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `ref_table` | 是 | 同库被引用表 |
+| `value_column` | 是 | 提交给 CLI 的值（编号 / 外键） |
+| `label_column` | 是 | 主文案列 |
+| `extra_column` | 否 | 第三展示列（任意列名，不限「备注」） |
+| `filter_column` / `filter_value` | 否 | 等值过滤 |
+
+**下拉展示（宿主统一，技能只配列）：** `{value} · {label}`；有非空 `extra_column` 时为 `{value} · {label}（{extra}）`。例：`2 · 通用私信-留资`、`2 · 通用私信-留资（dm）`。
+
+**可选「自动」：** 字段不要放进 `required`；不要用 `minimum: 1` 卡死留空。宿主会省略空的可选数字参数，避免「提交的数据无效」。
+
+**反模式（勿做）：**
+
+- 标题写成「某某编号」，说明里教用户去左侧表抄 id
+- 用静态 `enum` 罗列会增长/变更的业务行（会过期）
+- 在技能里自己拼假 label 列代替宿主统一格式（难维护）
+
+形状参考：[`assets/examples/lookup-action.example.json`](../assets/examples/lookup-action.example.json)。
+
 ### 表单字段类型对照（须与 CRUD 对称）

 Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件语义**。CRUD 侧配置见 [`SCHEMA.md`](SCHEMA.md)「表单与展示：稳定字段类型」；本表只写 Action 怎么配。
@@ -568,7 +651,7 @@ Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件
 | 数字 | `type: number` | `display_type: number` 或 INT/REAL/NUMERIC |
 | 开关 | `type: boolean` | `display_type: boolean` |
 | 枚举下拉 | `enum: [...]` | `options_json` 数组 |
-| 关联下拉 | 绑列 lookup（`column` / `columnMapping`） | `display_type: lookup` |
+| 关联下拉（Lookup） | 内联 `display_type: lookup` + `lookup`，或绑列 `column` / `columnMapping` | `display_type: lookup` + `options_json` 对象 |
 | 密码 | `sensitive: true` | 列 `sensitive` |
 | 日期（日） | `display_type` 或 `format`: `date` | `display_type: date` → 存 `YYYY-MM-DD` |
 | 日期时间 | `display_type` 或 `format`: `datetime_unix_seconds` | 同左；**存/传 Unix 秒** |
@@ -577,8 +660,9 @@ Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件
 | 说明灰字 | `description` | `_jiangchang_columns.description` |
 | 默认值 | `default` | SQLite 列 `DEFAULT` |
 | 只读 | `readOnly: true` | 列 `editable: 0` / 宿主只读规则 |
+| **条件显隐** | **`visibleWhen`**（见下节） | **本版 CRUD 无对称**；仅 Action / 定时任务参数表单 |

-**本版不做（勿宣传）：** 文件上传、多选/标签数组、复杂 `oneOf` / nested object 专用表单。
+**本版不做（勿宣传）：** 文件上传、多选/标签数组、复杂 `oneOf` / nested object 专用表单；`visibleWhen` 多条件 AND/OR 树、跨 Action 依赖、CRUD 新增/编辑对称显隐。

 日期时间约定：

@@ -590,9 +674,51 @@ Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件

 - 根：`object`；属性：`string` / `number` / `boolean`（`object`/`array` 仅作 JSON 多行编辑兼容，新技能慎用）
 - `enum` / `default` / `required` / `sensitive` / `readOnly`
- `display_type` / `format`：`textarea` | `date` | `datetime_unix_seconds` | `url` | `email`
+- `display_type` / `format`：`textarea` | `date` | `datetime_unix_seconds` | `url` | `email` | **`lookup`**
+- 字段内联 `lookup`（与 CRUD `options_json` lookup 对象同构；可选 `extra_column`）
 - 属性级 `description`（表单标签下方灰字说明）
 - 简单模板替换（`{{fieldName}}`）
+- 可选空数字字段提交时由宿主省略，避免 `""` 触发 number 校验失败
+- **字段条件显隐 `visibleWhen`**（可选）：依赖同表单其它字段值决定是否展示；隐藏字段不进提交、不校验 `required`
+
+### 字段条件显隐（`visibleWhen`）
+
+用于「先选模式，再出对应参数」类表单。写在 `inputSchema.properties.<field>` 上（**不是** action 顶层字段）。
+
+> **消歧义：** 本文的 `visibleWhen` = **Action 参数表单控件显隐**。  
+> [`POLICY.md`](POLICY.md) L3 预留的 `visibleWhen` = **行态/权限策略**（未冻结），**不是**同一能力。勿混用、勿互相替代。
+
+```json
+"keyword": {
+  "type": "string",
+  "title": "关键词",
+  "visibleWhen": { "field": "collectMode", "equals": "按关键词采集" }
+},
+"authorUrl": {
+  "type": "string",
+  "title": "作者主页链接",
+  "visibleWhen": { "collectMode": "按作者主页采集" }
+}
+```
+
+支持形态：
+
+| 写法 | 含义 |
+|------|------|
+| `{ "field": "x", "equals": "a" }` | `x === a` 时显示 |
+| `{ "field": "x", "in": ["a", "b"] }` | `x` 属于集合时显示 |
+| `{ "x": "a" }` / `{ "x": ["a","b"] }` | 单键简写，同上 |
+
+宿主行为（需已支持该字段的匠厂宿主；更旧版本会忽略未知字段 → 参数平铺全显）：
+
+- 数据管理 / 定时任务参数表单按当前值求值并隐藏
+- 若依赖字段自身因 `visibleWhen` 隐藏，则下游字段一并隐藏（避免切模式后残留）
+- 提交与服务端 `validateActionInput` 会剥离隐藏字段；隐藏字段不校验 `required`
+- 无 `visibleWhen` 的字段保持始终可见（兼容旧技能）
+
+形状参考：[`assets/examples/visible-when-action.example.json`](../assets/examples/visible-when-action.example.json)。
+
+互斥模式**优先**用 `visibleWhen`，不要只靠 `description` 灰字写「仅某某时填写」。

 **与数据管理「新增 / 编辑」表单的分工（勿混用配置入口）：**

@@ -670,6 +796,7 @@ CRUD 侧宿主义务与禁止事项见 [`SCHEMA.md`](SCHEMA.md)「表单与展
 - `readOnly: true` 时数据管理表单只读展示该字段（仍随提交传入）；适合行内/勾选预填的主键、编号列表
 - `placements` 含 `batch` 的动作在数据管理表顶常驻，无勾选时禁用（与表删除一致）
 - 需要确认的副作用操作使用 `confirmation.message`
+- 短名看不懂或会覆盖数据时，用独立的 `hoverHint`；不要把确认黄条复用成悬停
 - 模板参数使用 `{{fieldName}}`，且必须在 `inputSchema.properties` 中声明
 - `entrypoint.args` 项当前只允许 `string`、`number`、`boolean`；不允许对象或 `null`
 - **不要**在当前模板中宣传文件上传、多选数组、`oneOf`、复杂 nested object 等尚未稳定支持的能力
--- a/references/POLICY.md
+++ b/references/POLICY.md
@@ -2,7 +2,8 @@

 > **状态：正式契约 v1.0（`schemaVersion` 1）。**  
 > **目标：** 冻结「启用方式 + Snapshot 最小字段 + L2 scope 白名单」，使多数技能（L0）零配置，需要权限的技能（L1/L2）有稳定扩展面。  
-> **非目标：** 宿主实现业务用户/角色库；规定飞书/HTTP/本地表等权限数据源；本期不强制 L3（`visibleWhen` 等）。  
+> **非目标：** 宿主实现业务用户/角色库；规定飞书/HTTP/本地表等权限数据源；本期不强制 L3（行态 `visibleWhen` 等）。  
+> **注意：** L3 预留的行态 `visibleWhen` **不是** Action 参数表单的 `inputSchema.properties.*.visibleWhen`（表单控件显隐，见 [`ACTIONS.md`](ACTIONS.md)「字段条件显隐」）。二者同名不同义，勿混用。  
 > **配套 Schema：** [`../assets/schemas/skill-policy-snapshot.schema.json`](../assets/schemas/skill-policy-snapshot.schema.json)；启用块见 [`../assets/schemas/skill-actions.schema.json`](../assets/schemas/skill-actions.schema.json)。

 相关正交轴见 [`ACTIONS.md`](ACTIONS.md)。本契约增加第六轴：**policy（当前身份允许什么）**。
@@ -16,7 +17,7 @@
 | **L0** | 无 `policy`，或 `policy.enabled !== true` | **与今日完全一致**：不拉 Snapshot，不按身份过滤按钮/行/列 |
 | **L1** | `policy.enabled: true`，Snapshot 至少给出 Action 授权 | 数据管理展示 skill Action 前与 allowlist 求交；可选限制宿主内置能力 |
 | **L2** | 在 L1 基础上 Snapshot 带 `data.tables[table]` | 列表查询应用声明式 `rows.scope`；列按 `columns` 投影 |
-| **L3** | （预留，本契约不冻结行为） | 如行态 `visibleWhen`、菜单级藏表、`rows.mode=delegate` 等 |
+| **L3** | （预留，本契约不冻结行为） | 如**行态** `visibleWhen`、菜单级藏表、`rows.mode=delegate` 等（≠ Action 表单 `inputSchema.visibleWhen`） |

 **80% 技能停留 L0。** 启用 policy 的技能必须实现约定 CLI，并在写路径自行再鉴权（见 §7）。

@@ -366,7 +367,7 @@ IF mode == open: 候选不变
 |----|------|
 | `actions.mode: denylist` | 另开 `schemaVersion` |
 | `valueFrom: actor.roles` | **明确不做** |
-| `visibleWhen` / 嵌套 scope / `like` | L3 或永不做 |
+| `visibleWhen` / 嵌套 scope / `like` | L3 或永不做（此处指**行态**策略字段；Action 表单 `inputSchema.visibleWhen` 见 ACTIONS.md，不属本表） |
 | `rows.mode: delegate` 宿主实现 | 字段名已占坑 |
 | 平台全局 Role UI / cron·agent 套用 Snapshot | 另议 |

--- a/references/README.md
+++ b/references/README.md
@@ -17,7 +17,7 @@
 | 根目录 [`CHANGELOG.md`](../CHANGELOG.md) | 市场更新日志 Tab（版本小节 → `changelog`） |
 | [`SKILL.md`](../SKILL.md) | LLM / OpenClaw 平台技能入口与触发摘要 |
 | [`CLI.md`](CLI.md) | 共享 Python、命令行入口、参数与短操作契约 |
-| [`ACTIONS.md`](ACTIONS.md) | Skill Action、sync/async、任务中心、多入口（可选能力） |
+| [`ACTIONS.md`](ACTIONS.md) | Skill Action、sync/async、任务中心、多入口（按入口定位表挂载；先读 `development/PRODUCT_SURFACES.md`） |
 | [`SCHEMA.md`](SCHEMA.md) | 本地 SQLite 与数据管理展示契约 |
 | [`POLICY.md`](POLICY.md) | Data Policy：可选身份授权、Snapshot、行 scope（多数技能 L0 不配） |
 | [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md) | 数据管理单元格呈现：语义 tone 标色/强调（用途不限；多数技能 P0 不配） |
--- a/references/SCHEMA.md
+++ b/references/SCHEMA.md
@@ -1,6 +1,9 @@
 # 数据存储与数据管理展示规范

 本文是 skill 本地 SQLite 与匠厂宿主「数据管理」页面展示契约的**权威说明**。
+
+**产品定位：** 数据管理既是业务数据与过程的可见面，也是与对话**平级**的 **UI 执行面**（表上 Action 走同一 CLI 闭环）。何时挂执行入口见 [`../development/PRODUCT_SURFACES.md`](../development/PRODUCT_SURFACES.md)；本文管表结构与展示元数据。
+
 实现上的 DDL 与默认中文元数据种子见 `scripts/db/display_metadata.py`；`scripts/db/connection.py` 的 `init_db()` 会一并初始化。

 ## 职责边界
@@ -518,6 +521,7 @@ CREATE TABLE demo_items (
  "ref_table": "platforms",
  "value_column": "platform_key",
  "label_column": "display_name",
+  "extra_column": "category",
  "filter_column": "enabled",
  "filter_value": 1
 }
@@ -526,13 +530,23 @@ CREATE TABLE demo_items (
 | 字段 | 必填 | 说明 |
 |---|---|---|
 | `ref_table` | 是 | 同库被引用表名（snake_case 标识符） |
-| `value_column` | 是 | 写入当前字段的值列 |
-| `label_column` | 是 | 下拉展示名列 |
+| `value_column` | 是 | 写入当前字段的值列（编号 / 外键） |
+| `label_column` | 是 | 下拉主文案列（名称） |
+| `extra_column` | 否 | 第三展示列（不必叫「备注」）；有值时拼进括号 |
 | `filter_column` / `filter_value` | 否 | 等值过滤（如只列出 `enabled=1`） |

 宿主在加载表 schema 时查询 `ref_table`，把结果展开成 `{value,label}` 下拉选项；**物理列仍存标量**（如 `platform_key` 文本、`account_id` 整数），不做嵌套子表。

-示例：账号表的平台字段 → 平台信息表；凭据表的账号编号 → 账号信息表。
+**统一展示文案（宿主固定一种，技能只配列）：**
+
+- 默认：`{value} · {label}`，例如 `2 · 通用私信-留资`、`douyin · 抖音`
+- 配置了 `extra_column` 且该行有非空值：`{value} · {label}（{extra}）`
+- 未配置 `extra_column`、或额外列为空：不加 `（）`
+- `label` 为空或与 `value` 相同时：只显示 `value`（可再带额外括号）
+
+Action 弹窗内联 Lookup 与上表 **同构**（字段名一致），见 [`ACTIONS.md`](ACTIONS.md)「跨表引用：Lookup」。
+
+示例：账号表的平台字段 → 平台信息表；凭据表的账号编号 → 账号信息表；私信 Action 选话术 → `message_templates`。

 ## 幂等初始化标准

--- a/scripts/util/constants.py
+++ b/scripts/util/constants.py
@@ -1,6 +1,6 @@
 """技能标识、版本与平台公共库约束（复制后请修改 slug/version/logger）。"""

 SKILL_SLUG = "your-skill-slug"
-SKILL_VERSION = "1.0.81"
+SKILL_VERSION = "1.0.85"
 LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug"
 PLATFORM_KIT_MIN_VERSION = "1.2.11"
--- a/tests/test_actions_manifest.py
+++ b/tests/test_actions_manifest.py
@@ -249,6 +249,54 @@ class TestActionsManifest(unittest.TestCase):
            {"create", "update", "delete"},
        )

+    def test_schema_defines_hover_hint(self) -> None:
+        schema = _load_actions_schema()
+        action_def = schema["$defs"]["action"]
+        props = action_def["properties"]
+        self.assertIn("hoverHint", props)
+        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(
+                "hoverHint",
+                action,
+                msg=f"{action['id']} default template action should omit hoverHint",
+            )
+
    def test_schema_defines_host_effects_and_steps(self) -> None:
        schema = _load_actions_schema()
        action_def = schema["$defs"]["action"]
@@ -537,6 +585,9 @@ class TestActionsManifest(unittest.TestCase):
            "POLICY.md",
            "hostEffects",
            "steps",
+            "hoverHint",
+            "visibleWhen",
+            "字段条件显隐",
            "reloadTable",
            "afterSuccess",
            "afterFailure",
--- a/tests/test_docs_standards.py
+++ b/tests/test_docs_standards.py
@@ -341,6 +341,8 @@ class TestDocsStandards(unittest.TestCase):
            "表单与展示：稳定字段类型（宿主支持，须与 Action 对称）",
            "datetime_unix_seconds",
            "display_type: \"number\"",
+            "extra_column",
+            "{value} · {label}",
            "DEFAULT",
            "description",
            "文件 / 图片上传",
@@ -354,13 +356,41 @@ class TestDocsStandards(unittest.TestCase):
        for marker in (
            "inputSchema 与参数表单",
            "表单字段类型对照（须与 CRUD 对称）",
+            "跨表引用：Lookup",
+            "display_type: \"lookup\"",
+            "extra_column",
            "数据管理新增/编辑",
            "_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",
@@ -457,6 +487,7 @@ class TestDocsStandards(unittest.TestCase):
        text = self._read("references/ACTIONS.md")
        self.assertIn("最小组合", text)
        self.assertIn("confirmation.message", text)
+        self.assertIn("hoverHint", text)
        self.assertIn("用户意图路由表", text)

    def test_actions_md_states_profile_not_entry_for_task_center(self) -> None:
Author	SHA1	Message	Date
chendelian	f221f81d4e	docs: add PRODUCT_SURFACES peer entry contract for skill authors All checks were successful 技能自动化发布 / release (push) Successful in 5s Details	2026-08-17 18:49:05 +08:00
chendelian	3738f0bea2	docs: 沉淀 Action 表单 visibleWhen 条件显隐契约 All checks were successful 技能自动化发布 / release (push) Successful in 5s Details	2026-08-16 14:26:56 +08:00
chendelian	6ebc570632	docs: precipitate Action/CRUD Lookup contract for skill authors All checks were successful 技能自动化发布 / release (push) Successful in 5s Details	2026-08-16 12:58:39 +08:00
chendelian	2d02ccff5d	Release v1.0.82: add optional hoverHint contract for toolbar skill actions All checks were successful 技能自动化发布 / release (push) Successful in 5s Details	2026-08-15 10:02:27 +08:00