docs: codify free PyArmor Trial packaging guidance

新增 DATA_SOURCES.md、data-sources 示例与双后端 connection 骨架；CLI 与宿主 UI 可读写同一库。要求匠厂 Host ≥ 6.9.28。

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

.env.example

@@ -53,3 +53,6 @@ HUMAN_WAIT_TIMEOUT=180                 # 单位：秒；来不及处理时可调
 
 # 临时目录：运行中临时文件的位置（不上侧栏）
 # SKILL_TEMP_DIR=temp                   # 相对本技能数据目录；留空或保持注释则用默认 temp
+
+# MySQL 云库连接：技能走云库时在用户数据目录配置 data-sources.json，并在此填写 DSN
+# MYSQL_DSN=mysql://user:password@192.168.0.20:3306/your_database  # 留空或不写=本地 SQLite；须 mysql:// 开头且含库名；匠厂 Host 须 ≥ 6.9.28；见 references/DATA_SOURCES.md

CHANGELOG.md

@@ -9,6 +9,60 @@
 - 小节正文写用户能看懂的变化（新能力、修复、注意事项），避免堆砌内部实现细节
 - 打 tag 前**必须**为即将发布的版本新增一节；找不到匹配小节时，本次发布不会更新 changelog 字段
 
+## 1.0.125
+
+- 固化免费 PyArmor Trial 发布约定：行数门槛是预防线；实际失败时按日志定位模块并按职责拆分，保留兼容门面，以 Gitea Trial 加密结果验收
+- 记录 field_locator 拆分后同一免费 Trial 链路成功的复盘案例；不使用未经验证的统一字节数阈值
+
+## 1.0.124
+
+- 沉淀宿主能力：Excel 导入模板按列元数据自动加下拉（有可选集合的列展示 label；CSV 无下拉）；技能只需声明 `_jiangchang_columns` 选项即可受益
+- 更新 `references/SCHEMA.md`「宿主负责」与 `options_json` 说明
+
+
+## 1.0.123
+
+- 沉淀 `selectionMode: optional` 在**定时任务等无表勾选入口**的宿主约定：配置页按无勾选分支，隐藏空「编号列表」、只保留数量字段；勿为 cron 再拆 Action
+- 更新 ACTIONS / CHECKLIST A4-9 / RUNTIME / DEVELOPMENT 验收表；门禁用例覆盖关键表述
+
+## 1.0.122
+
+- 沉淀 Action **静态枚举中文 label**：`enum` + **`enumNames`**，或绑列复用列 `options_json` 数组
+- 约定宿主优先序：**绑列 options → enumNames → 纯 enum**；固定小枚举不要造假 Lookup
+- 更新 Schema / ACTIONS / SCHEMA / CHECKLIST A4-13；新增 `enum-names-action.example.json`
+
+## 1.0.121
+
+- 沉淀 Lookup **分页勾选小表**：`display_type: lookup` + `presentation: "paged_table"` + 可选 `page_size`（仍是 Lookup，不要新造控件类型）
+- 约定 `skill_cli` 追加 `--page` / `--limit`，stdout 为一行 `{"items","total"}`；0 条也是成功，界面显示「暂无可选项」
+- 只读列表命令不要在入口加载整包 platform-kit 或 Playwright；同库一个过滤条件优先 `local_sql`
+- 更新 Schema / ACTIONS / SCHEMA / CHECKLIST A4-12；新增 `lookup-paged-table.action.example.json`
+
+## 1.0.120
+
+- 正式沉淀行菜单显隐契约 **`bind.visibleWhen`**（宿主已支持：按当前行列值显示/隐藏行按钮）
+- 与表单字段 `visibleWhen`、Policy L3 预留消歧；更新 Schema / ACTIONS / POLICY / CHECKLIST A4-11 / RUNTIME
+- 新增示例 `bind-visible-when-row.action.example.json`
+
+## 1.0.119
+
+- 沉淀匠厂宿主 **Action Lookup 三源**：`local_sql`（同库）/ **`skill_cli`（兄弟技能 CLI JSON）** / `external_api`（预留）
+- 明确列 Lookup 仍仅 `local_sql`；跨技能账号列表用 `skill_cli`，**禁止**本库镜像缓存表
+- 更新 `ACTIONS.md` / `SCHEMA.md` / `skill-actions.schema.json` / CHECKLIST A4-6 / `ACCOUNT_MANAGER.md`；新增 `lookup-skill-cli.action.example.json`
+
+## 1.0.118
+
+- 沉淀浏览器 RPA 窗口/viewport 最佳实践（`RPA.md` §1.2.1）：`no_viewport=True` + `--start-maximized`，禁止 `viewport=None` 与 CDP/JS 中途改窗
+- `RPA_BROWSER.md` 补充 Shadow DOM 双 input 陷阱与 Cookie 可选 dismiss 模式
+- 新增 `POLICY-RPA-007` 文档标记与 launch 禁止模式门禁；CHECKLIST A5-4 对齐
+
+## 1.0.117
+
+- 沉淀匠厂 Host ≥ 6.9.28 **多数据源**契约：可选 MySQL 云库 + `data-sources.json` 声明；默认仍为本地 SQLite
+- 新增 `references/DATA_SOURCES.md`、`assets/data-sources.example.json`（SQLite 默认）、`assets/examples/data-sources.mysql.example.json`
+- `scripts/db/backend.py`、`cursor_compat.py` 与双后端 `connection.py`：CLI / Action 与宿主 UI 读写同一库
+- `.env.example` 增加 `MYSQL_DSN` 说明；CHECKLIST / CONFIG / DATA_PATHS / SCHEMA / ACTIONS 口径同步
+
 ## 1.0.116
 
 - 沉淀宿主 **年 / 年月** 表单字段契约：`display_type: year`（`YYYY`）、`year_month` / `month`（`YYYY-MM`）；与 `date` / `datetime_unix_seconds` 对称，Action 与 CRUD 均适用

SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: 技能开发模板（通用业务版）
 description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。"
-version: 1.0.116
+version: 1.0.125
 author: 深圳匠厂科技有限公司
 metadata:
   openclaw:
@@ -38,7 +38,8 @@ allowed-tools:
 - **数据管理**：既是 **UI 执行面**（点按钮走与对话相同的闭环），也是数据与过程可见；不是「只读库」。
 - **`placements`**：只决定 Action **出现在哪里**（toolbar / row / batch / cron / agent / skill-detail）。其中 `row` 表示**行级入口**（宿主可呈现为操作列、行右键、行内「⋯」等；技能配什么就显示什么，无独立菜单 DSL）。数据管理技能按钮顺序见 `actions` **数组相对顺序**（详见 `references/ACTIONS.md`），无独立 sortOrder。
 - **`bind.tables`**：只决定数据管理出现在哪些表；含 `toolbar` 时**必须**显式非空绑定。
-- **`bind.selectionMode`（可选）**：表勾选如何驱动 Action（`required` / `none` / `optional`）；省略由宿主推断。同一能力勿拆两个同义顶栏按钮，见 `references/ACTIONS.md`。
+- **`bind.selectionMode`（可选）**：表勾选如何驱动 Action（`required` / `none` / `optional`）；省略由宿主推断。同一能力勿拆两个同义顶栏按钮；定时任务配置页按无勾选分支隐藏 `$selection.ids`，见 `references/ACTIONS.md`。
+- **`bind.visibleWhen`（可选）**：`row` 菜单/按钮按当前行列值显隐（如仅已采用可入队）；省略则始终显示。≠ 表单字段 `visibleWhen`，≠ Policy L3。见 `references/ACTIONS.md`「行菜单显隐」。
 - **用户可见文案**：数据管理弹窗 / 任务中心文案须全中文产品用语；勿把 `pickCount`、`async`、`pending`、CLI 子命令写进弹窗（见 `references/ACTIONS.md`「用户可见文案」）。
 - **`executionProfile`**：只决定执行方式——`sync` 当场返回结果，`async` 进**任务中心**。与 placements / 入口**无关**。心智上多数为 sync，仅长任务 / RPA 标 async；宿主省略该字段时按 sync。每个 Action **仍必须**显式写 `sync` 或 `async`。
 - **`policy`（可选）**：需要按用户/角色控制数据管理按钮或行列时，在 `actions.json` 顶层启用 Data Policy，由技能 `policy` CLI 输出 Snapshot；**未启用 = 与今日一致（L0）**。详见 `references/POLICY.md`。用户/角色数据源（飞书/库/API）属技能内部，宿主不托管。
@@ -155,7 +156,7 @@ python {baseDir}/scripts/main.py init-db
 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`。
+7. 本地 SQLite 或可选 MySQL 云库：数据源声明见 `references/DATA_SOURCES.md`；中文表名/字段名、标准时间字段与字段顺序规范见 `references/SCHEMA.md`。
 
 ## 技能命名与 slug
 

assets/README.md

@@ -4,10 +4,11 @@
 - **业务技能注意：** 若主路径在数据管理，准备/载入/导入类 Action 应挂 `toolbar` + `bind.tables`（用户看得见），**不要**只挂 `skill-detail` 却在教程里写成「技能详情点按钮」。见 `development/TUTORIAL_SURFACES.md` §5、`references/ACTIONS.md`「用户可见性」。
 - `html/example-report.html`：HTML 快照页最小壳（`{{TITLE}}` / `{{GENERATED_AT}}` / `{{BODY}}`）；含数据管理 iframe 预览布局基线（流体铺满、禁横向滚动）；渲染后须写入数据目录 `html/`。不要放进 `pages/`。
 - `html/pages/*.html`：装完就出现在侧栏的壳子页（宿主直接读安装包，不经生成）。页面用 `jiangchang.call` 调本技能已声明的命令。见 `references/ACTIONS.md`「HTML 页面报告」。模板仓库不要在这里放示例页。
-- `examples/`：CLI 成功输出形状示例、Action 形状参考（含 `path-root-file-action.example.json`、`selection-label-column.action.example.json`、`selection-mode-optional.action.example.json`、`render-html.action.example.json` 等；虚构路径与数据）。
+- `data-sources.example.json`：声明式数据源默认示例（SQLite `{skillSlug}.db`）；宿主安装时可复制到用户目录。MySQL 参考见 `examples/data-sources.mysql.example.json`。
+- `examples/`：CLI 成功输出形状示例、Action 形状参考（含 `data-sources.mysql.example.json`、`path-root-file-action.example.json`、`selection-label-column.action.example.json`、`selection-mode-optional.action.example.json`、`render-html.action.example.json` 等；虚构路径与数据）。
 - `schemas/`：轻量 JSON Schema（`skill-actions.schema.json` 为**新技能严格规范**）。
 
-`skill-actions.schema.json` 使用 `additionalProperties: false`。正式支持 `bind.tables`（toolbar Action 必填）与可选 `bind.inputMapping` / `columnMapping` / **`labelColumn`**（选择摘要标签列）/ **`selectionMode`**（`required` \| `none` \| `optional`：表勾选如何驱动 Action；省略则宿主兼容推断）。placements 含 `toolbar` / `row` / `batch` / `cron` / `agent` / `skill-detail`（对齐匠厂宿主）。数据管理 confirm/form 弹层在会应用勾选时展示「已选择」摘要；**form + 有摘要时映射 `readOnly` 默认不占参数区（仍提交）**，可选 **`revealInForm`** 强制显示。弹窗 `description` / 确认黄条 / 参数说明须**用户可见中文**（勿写 `pickCount`/`async`/`pending`/CLI 子命令；见 ACTIONS.md「用户可见文案」）。可选 `hoverHint` 为数据管理工具栏悬停（省略不显示，不回退）。`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` / `columnMapping` / **`labelColumn`**（选择摘要标签列）/ **`selectionMode`**（`required` \| `none` \| `optional`：表勾选如何驱动 Action；省略则宿主兼容推断）/ **`visibleWhen`**（行菜单/行按钮按当前行列值显隐）。Action Lookup 可选 **`presentation: "paged_table"`** + **`page_size`**（分页勾选小表，仍是 `display_type: lookup`）。placements 含 `toolbar` / `row` / `batch` / `cron` / `agent` / `skill-detail`（对齐匠厂宿主）。数据管理 confirm/form 弹层在会应用勾选时展示「已选择」摘要；**form + 有摘要时映射 `readOnly` 默认不占参数区（仍提交）**，可选 **`revealInForm`** 强制显示。弹窗 `description` / 确认黄条 / 参数说明须**用户可见中文**（勿写 `pickCount`/`async`/`pending`/CLI 子命令；见 ACTIONS.md「用户可见文案」）。可选 `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)；写法契约见 [`development/TUTORIAL_SURFACES.md`](../development/TUTORIAL_SURFACES.md)
 - Agent 调用/编排参考见 [`references/`](../references/)（含 [`ACTIONS.md`](../references/ACTIONS.md)）

assets/data-sources.example.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "sources": [
+    {
+      "id": "primary",
+      "kind": "sqlite",
+      "displayName": "本地库",
+      "path": "{skillSlug}.db"
+    }
+  ]
+}

assets/examples/README.md

@@ -1,13 +1,17 @@
 # 示例 JSON
 
+- `data-sources.mysql.example.json`：MySQL 云库 `data-sources.json` 形状参考（复制到用户数据目录并配 `.env` 中 `MYSQL_DSN`；见 `references/DATA_SOURCES.md`）。
 - `version-response.json`：`python main.py version` 成功时 stdout 单行对象的形状参考。
 - `skill-policy-snapshot.*.example.json`：Data Policy Snapshot 形状参考（见 `references/POLICY.md`）。
 - `skill-cell-presentation.example.json`：数据管理单元格呈现文档形状参考（见 `references/CELL_PRESENTATION.md`）。
 - `skill-grid-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 形状参考（单选 + `multiple: true` 多选并列；跨表引用勿填编号；见 `references/ACTIONS.md`「跨表引用：Lookup」）。
+- `lookup-action.example.json`：Action 内联 Lookup（**local_sql**）形状参考（单选 + `multiple: true`；同库跨表勿填编号；见 `references/ACTIONS.md`「跨表引用：Lookup」）。
+- `lookup-skill-cli.action.example.json`：Action Lookup **`skill_cli`** 形状参考（打开表单时宿主调兄弟技能 CLI 抽 JSON 选项；跨技能账号列表勿再造本库缓存表；见同节）。
+- `lookup-paged-table.action.example.json`：Lookup **分页勾选小表** `presentation: "paged_table"` 形状参考（仍是 `display_type: lookup`；见 `references/ACTIONS.md`「分页勾选小表」）。
 - `year-month-action.example.json`：Action / CRUD 账期月份字段 `display_type: year_month` 形状参考（见 `references/ACTIONS.md`「表单字段类型对照」）。
-- `visible-when-action.example.json`：Action 参数字段条件显隐 `visibleWhen` 形状参考（互斥模式联动；见 `references/ACTIONS.md`「字段条件显隐」；≠ Policy L3）。
+- `visible-when-action.example.json`：Action 参数字段条件显隐 `visibleWhen` 形状参考（互斥模式联动；见 `references/ACTIONS.md`「字段条件显隐」；≠ `bind.visibleWhen`，≠ Policy L3）。
+- `bind-visible-when-row.action.example.json`：行菜单显隐 `bind.visibleWhen` 形状参考（按当前行状态显示/隐藏行按钮；见 `references/ACTIONS.md`「行菜单显隐」）。
 - `selection-label-column.action.example.json`：选择摘要 `bind.labelColumn` 形状参考（见 `references/ACTIONS.md`「选择摘要」）。
-- `selection-mode-optional.action.example.json`：`bind.selectionMode: "optional"` 智能勾选/按数量合并形状参考；用户可见文案为口语中文（见 `references/ACTIONS.md`「勾选驱动模式」「用户可见文案」）。
+- `selection-mode-optional.action.example.json`：`bind.selectionMode: "optional"` 智能勾选/按数量合并形状参考（含 `cron`：配置页按无勾选分支，只见数量字段）；用户可见文案为口语中文（见 `references/ACTIONS.md`「勾选驱动模式」「用户可见文案」）。
 - `replaces-create.action.example.json` / `replaces-update.action.example.json` / `replaces-delete.action.example.json` / `replaces-import.action.example.json`：数据管理默认按钮接管（`replaces`）形状参考；**import 时 UI 仍用宿主「导入数据」面板**，确认后调技能写库（见 `references/ACTIONS.md`「`replaces`」）。

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

@@ -0,0 +1,39 @@
+{
+  "id": "approve-item",
+  "label": "采用",
+  "description": "把当前记录改为已采用。仅待确认或已跳过的行显示此按钮。",
+  "placements": ["row", "agent"],
+  "executionProfile": "sync",
+  "interaction": "direct",
+  "bind": {
+    "tables": ["business_items"],
+    "visibleWhen": {
+      "field": "status",
+      "in": ["pending_review", "skipped"]
+    },
+    "labelColumn": "display_name",
+    "inputMapping": {
+      "itemId": "$row.$pk"
+    }
+  },
+  "inputSchema": {
+    "type": "object",
+    "required": ["itemId"],
+    "properties": {
+      "itemId": {
+        "type": "number",
+        "title": "编号",
+        "description": "行内触发时自动填入，一般无需修改",
+        "readOnly": true
+      }
+    }
+  },
+  "entrypoint": {
+    "type": "cli",
+    "command": "approve",
+    "args": ["--id", "{{itemId}}"]
+  },
+  "hostEffects": {
+    "onSuccess": ["reloadTable"]
+  }
+}

assets/examples/data-sources.mysql.example.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "sources": [
+    {
+      "id": "primary",
+      "kind": "mysql",
+      "displayName": "业务云库",
+      "connectionEnv": "MYSQL_DSN"
+    }
+  ]
+}

assets/examples/enum-names-action.example.json

@@ -0,0 +1,51 @@
+{
+  "_comment": "形状参考：Action 静态枚举用 enum + enumNames 显示中文；提交仍是 enum value。有对应表列时优先 column 绑列复用 options_json。完整契约见 references/ACTIONS.md「静态枚举 label」。",
+  "schemaVersion": 1,
+  "skill": "your-skill-slug",
+  "actions": [
+    {
+      "id": "create-ticket",
+      "label": "新建工单（示例）",
+      "description": "演示 enumNames：界面显示中文，CLI 仍收到英文枚举值。",
+      "placements": ["toolbar", "agent"],
+      "executionProfile": "sync",
+      "interaction": "form",
+      "bind": {
+        "tables": ["tickets"]
+      },
+      "entrypoint": {
+        "type": "cli",
+        "command": "ticket-create",
+        "args": [
+          "--category", "{{category}}",
+          "--priority", "{{priority}}",
+          "--title", "{{title}}"
+        ]
+      },
+      "inputSchema": {
+        "type": "object",
+        "required": ["title", "category"],
+        "properties": {
+          "title": {
+            "type": "string",
+            "title": "标题"
+          },
+          "category": {
+            "type": "string",
+            "title": "类型",
+            "column": "category",
+            "enum": ["incident", "request", "consult", "other"],
+            "enumNames": ["故障", "需求", "咨询", "其他"]
+          },
+          "priority": {
+            "type": "string",
+            "title": "优先级",
+            "enum": ["low", "medium", "high", "urgent"],
+            "enumNames": ["低", "中", "高", "紧急"],
+            "description": "无对应列时仅靠 enumNames 展示中文"
+          }
+        }
+      }
+    }
+  ]
+}

assets/examples/lookup-action.example.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "形状参考：Action 参数引用同库另一张表时用 Lookup。单选与多选同一 lookup 对象，多选只加 multiple:true。完整契约见 references/ACTIONS.md「跨表引用：Lookup」与 references/SCHEMA.md。",
+  "_comment": "形状参考：Action 参数引用同库另一张表时用 Lookup（local_sql）。单选与多选同一 lookup 对象，多选只加 multiple:true。跨技能列表见 lookup-skill-cli.action.example.json。完整契约见 references/ACTIONS.md「跨表引用：Lookup」。",
   "schemaVersion": 1,
   "skill": "your-skill-slug",
   "actions": [

assets/examples/lookup-paged-table.action.example.json

@@ -0,0 +1,47 @@
+{
+  "_comment": "形状参考：Action Lookup 分页勾选小表。仍是 display_type=lookup，加 presentation=paged_table。完整契约见 references/ACTIONS.md「分页勾选小表」。不要新造 display_type。skill_cli 的 stdout 须为一行 {items,total}；0 条也成功退出。列表命令不要在 main.py 入口加载整包 jiangchang_skill_core 或 Playwright。",
+  "schemaVersion": 1,
+  "skill": "your-skill-slug",
+  "actions": [
+    {
+      "id": "import-picked",
+      "label": "导入文章",
+      "description": "从已生成文章里勾选要导入的，可翻页。",
+      "placements": ["toolbar"],
+      "executionProfile": "sync",
+      "interaction": "form",
+      "bind": {
+        "tables": ["articles"],
+        "selectionMode": "none"
+      },
+      "entrypoint": {
+        "type": "cli",
+        "command": "import-articles",
+        "args": ["--ids", "{{articleIds}}"]
+      },
+      "inputSchema": {
+        "type": "object",
+        "required": ["articleIds"],
+        "properties": {
+          "articleIds": {
+            "type": "string",
+            "title": "选择文章",
+            "description": "勾选要导入的文章。可翻页，可本页全选。",
+            "display_type": "lookup",
+            "lookup": {
+              "source": "skill_cli",
+              "skill": "geo-generate-article-all",
+              "command": "title",
+              "args": ["list-generated-json", "--platform", "toutiaohao"],
+              "value_column": "id",
+              "label_column": "title",
+              "multiple": true,
+              "presentation": "paged_table",
+              "page_size": 10
+            }
+          }
+        }
+      }
+    }
+  ]
+}

assets/examples/lookup-skill-cli.action.example.json

@@ -0,0 +1,51 @@
+{
+  "_comment": "形状参考：Action Lookup 的 skill_cli 源——打开表单时宿主 sync 调用兄弟技能 CLI，从 stdout JSON 抽选项。完整契约见 references/ACTIONS.md「跨表引用：Lookup」。本例对标 account-manager 遗留 list-json（stdout 为账号数组，字段 id / account_label）；其它依赖技能请核对自己的命令与 JSON 形状。",
+  "schemaVersion": 1,
+  "skill": "your-skill-slug",
+  "actions": [
+    {
+      "id": "publish-with-account",
+      "label": "发布（示例）",
+      "description": "演示跨技能选账号：skill_cli 调 account-manager，勿在本技能维护账号缓存表。",
+      "placements": ["toolbar", "cron"],
+      "executionProfile": "async",
+      "interaction": "form",
+      "bind": {
+        "tables": ["articles"],
+        "selectionMode": "none"
+      },
+      "entrypoint": {
+        "type": "cli",
+        "command": "run",
+        "args": ["--account-id", "{{accountId}}", "--pick", "{{pickCount}}"]
+      },
+      "inputSchema": {
+        "type": "object",
+        "required": ["pickCount"],
+        "properties": {
+          "pickCount": {
+            "type": "number",
+            "title": "发布数量",
+            "description": "从未发布队列领取的条数",
+            "default": 1,
+            "minimum": 1
+          },
+          "accountId": {
+            "type": "string",
+            "title": "发布账号",
+            "description": "不选则由系统自动分配；选定后本次全部使用该号。",
+            "display_type": "lookup",
+            "lookup": {
+              "source": "skill_cli",
+              "skill": "account-manager",
+              "command": "list-json",
+              "args": ["toutiao"],
+              "value_column": "id",
+              "label_column": "account_label"
+            }
+          }
+        }
+      }
+    }
+  ]
+}

assets/schemas/skill-actions.schema.json

@@ -85,11 +85,53 @@
     "mutationKind": {
       "type": "string",
       "enum": ["create", "update", "delete", "import"],
-      "description": "可选。接管数据管理默认按钮：create=新增、update=编辑、delete=删除、import=导入。须配合非空 bind.tables；无配置时宿主仍直写 SQLite。import 时 UI 仍用宿主「导入数据」面板，确认后调用本 Action 写库。"
+      "description": "可选。接管数据管理默认按钮：create=新增、update=编辑、delete=删除、import=导入。须配合非空 bind.tables；无配置时宿主仍直写已注册数据源（默认 SQLite）。import 时 UI 仍用宿主「导入数据」面板，确认后调用本 Action 写库。"
     },
     "scalarArg": {
       "type": ["string", "number", "boolean"]
     },
+    "visibleWhenRule": {
+      "description": "条件显隐规则。支持 {field,equals} / {field,in:[...]}，或单键简写 {status:\"approved\"} / {status:[\"a\",\"b\"]}。",
+      "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"] }
+              }
+            ]
+          }
+        }
+      ]
+    },
     "inputProperty": {
       "type": "object",
       "required": ["type"],
@@ -105,7 +147,13 @@
         "default": {},
         "enum": {
           "type": "array",
-          "minItems": 1
+          "minItems": 1,
+          "description": "静态枚举取值（提交/存库用）。展示中文时配 enumNames，或绑列复用 options_json；勿用 Lookup 冒充固定小枚举。"
+        },
+        "enumNames": {
+          "type": "array",
+          "minItems": 1,
+          "description": "可选。与 enum 一一对应的展示文案（JSON Schema / OpenAPI 风格）。缺项或空串时宿主回退为对应 enum 原文。有对应表列时优先绑列复用 options_json（见 ACTIONS.md「静态枚举 label」）。"
         },
         "sensitive": { "type": "boolean" },
         "readOnly": {
@@ -120,7 +168,7 @@
           "type": "string",
           "minLength": 1,
           "pattern": "^[a-z][a-z0-9_]*$",
-          "description": "可选。绑定业务表物理列名；Action 弹窗（toolbar/batch）与 replaces create/update 抽屉均可复用该列的中文名与 lookup 下拉"
+          "description": "可选。绑定业务表物理列名；Action 弹窗（toolbar/batch）与 replaces create/update 抽屉可复用该列的中文名与 options（静态枚举 options_json 数组，或已解析的 lookup）。"
         },
         "display_type": {
           "type": "string",
@@ -139,74 +187,45 @@
         },
         "lookup": {
           "$ref": "#/$defs/lookupConfig",
-          "description": "可选。内联同库表关联 Lookup（与列 options_json lookup 对象同构）。用于当前表没有对应列时；推荐同时设 display_type=lookup。见 ACTIONS.md「跨表引用：Lookup」。"
+          "description": "可选。Action 内联 Lookup：local_sql（同库表）/ skill_cli（兄弟技能 CLI JSON）/ external_api（预留）。打开表单时由宿主解析。推荐同时设 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"] }
-                  }
-                ]
-              }
-            }
-          ]
+          "description": "可选。表单字段条件显隐。宿主在数据管理/定时任务参数表单中：规则不满足则隐藏该字段、提交时省略、且不校验 required。Agent/CLI 无 UI 时同样按当前 input 求值后剥离隐藏字段。≠ bind.visibleWhen（行菜单），≠ Policy L3。",
+          "allOf": [{ "$ref": "#/$defs/visibleWhenRule" }]
         }
       }
     },
     "lookupConfig": {
       "type": "object",
-      "required": ["ref_table", "value_column", "label_column"],
       "additionalProperties": false,
       "properties": {
+        "source": {
+          "type": "string",
+          "enum": ["local_sql", "skill_cli", "external_api"],
+          "description": "可选。显式数据源；省略时：有 ref_table→local_sql，有 skill→skill_cli，有 url→external_api。"
+        },
+        "lookup_source": {
+          "type": "string",
+          "enum": ["local_sql", "skill_cli", "external_api"],
+          "description": "可选。source 别名。"
+        },
         "ref_table": {
           "type": "string",
           "minLength": 1,
           "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
-          "description": "同库被引用表名"
+          "description": "local_sql：同库被引用表名"
         },
         "value_column": {
           "type": "string",
           "minLength": 1,
           "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
-          "description": "提交值列（编号 / 外键）"
+          "description": "提交值列；local_sql 必填；skill_cli/external_api 默认可为 id"
         },
         "label_column": {
           "type": "string",
           "minLength": 1,
           "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
-          "description": "主文案列"
+          "description": "主文案列；local_sql 必填；skill_cli 默认可为 display_label"
         },
         "extra_column": {
           "type": "string",
@@ -218,18 +237,101 @@
           "type": "string",
           "minLength": 1,
           "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
-          "description": "可选。等值过滤列"
+          "description": "可选。local_sql 等值过滤列"
         },
         "filter_value": {
           "type": ["string", "number", "boolean", "null"],
           "description": "可选。与 filter_column 配对的等值"
         },
+        "skill": {
+          "type": "string",
+          "minLength": 1,
+          "description": "skill_cli：兄弟/依赖技能 slug"
+        },
+        "skill_slug": {
+          "type": "string",
+          "minLength": 1,
+          "description": "skill_cli：skill 别名"
+        },
+        "command": {
+          "type": "string",
+          "minLength": 1,
+          "description": "skill_cli：CLI 子命令（argv[0]）"
+        },
+        "cli_command": {
+          "type": "string",
+          "minLength": 1,
+          "description": "skill_cli：command 别名"
+        },
+        "args": {
+          "oneOf": [
+            {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            { "type": "string" }
+          ],
+          "description": "skill_cli：追加 argv；数组或逗号分隔串"
+        },
+        "items_path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "skill_cli / external_api：stdout JSON 内选项数组点路径，默认 items"
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1,
+          "description": "external_api（预留）：HTTP URL"
+        },
+        "endpoint": {
+          "type": "string",
+          "minLength": 1,
+          "description": "external_api：url 别名"
+        },
+        "method": {
+          "type": "string",
+          "enum": ["GET", "POST"],
+          "description": "external_api：HTTP 方法，默认 GET"
+        },
         "multiple": {
           "type": "boolean",
-          "description": "可选。true=多选 Lookup（存/提交 TEXT 逗号分隔 id）；省略或 false=单选（默认）。与 CRUD options_json lookup 同构。"
+          "description": "可选。true=多选 Lookup（存/提交 TEXT 逗号分隔 id）；省略或 false=单选（默认）。"
+        },
+        "presentation": {
+          "type": "string",
+          "enum": ["select", "paged_table"],
+          "description": "可选。省略或 select=下拉/勾选/Chip。paged_table=分页勾选小表（编号|文案，可翻页、可本页全选）。仍是 lookup，不要新造 display_type。"
+        },
+        "page_size": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100,
+          "description": "可选。presentation=paged_table 时每页条数，默认 10，最大 100。"
         }
       },
-      "description": "同库 FK 式 Lookup。展示：value · label；有 extra 时 value · label（extra）。multiple 时多选。宿主亦接受 camelCase 键名。"
+      "oneOf": [
+        {
+          "required": ["ref_table", "value_column", "label_column"],
+          "description": "local_sql（同库表）"
+        },
+        {
+          "anyOf": [
+            { "required": ["skill", "command"] },
+            { "required": ["skill", "cli_command"] },
+            { "required": ["skill_slug", "command"] },
+            { "required": ["skill_slug", "cli_command"] }
+          ],
+          "description": "skill_cli（兄弟技能 CLI JSON）"
+        },
+        {
+          "anyOf": [
+            { "required": ["url"] },
+            { "required": ["endpoint"] }
+          ],
+          "description": "external_api（预留）"
+        }
+      ],
+      "description": "Action Lookup：local_sql / skill_cli / external_api。展示：value · label；有 extra 时 value · label（extra）。宿主亦接受 camelCase。列 Lookup 仅 local_sql，见 SCHEMA.md。"
     },
     "inputSchema": {
       "type": "object",
@@ -316,9 +418,13 @@
           "type": "string",
           "enum": ["required", "none", "optional"],
           "description": "可选。数据管理勾选如何驱动本 Action：required=必须有勾选（无勾选禁用）；none=忽略表勾选（不出现假「已选择」）；optional=有勾选走 $selection.ids，无勾选走 pickCount/maxLeads 等空选数量字段。省略时宿主推断：有 $selection.ids 或 batch → required，否则 → none。与 placements/executionProfile 正交。"
+        },
+        "visibleWhen": {
+          "description": "可选。placements 含 row 时：按当前行原始列值决定是否出现在行菜单/行按钮（宿主已支持）。形状同表单字段 visibleWhen。省略=始终显示。≠ inputSchema 字段 visibleWhen，≠ Policy L3 预留。见 ACTIONS.md「行菜单显隐」。",
+          "allOf": [{ "$ref": "#/$defs/visibleWhenRule" }]
         }
       },
-      "description": "表级绑定；toolbar 必填。可选 inputMapping / columnMapping / labelColumn / selectionMode。concurrency/locks 勿写入。"
+      "description": "表级绑定；toolbar 必填。可选 inputMapping / columnMapping / labelColumn / selectionMode / visibleWhen。concurrency/locks 勿写入。"
     },
     "hostEffectId": {
       "type": "string",

development/ACCOUNT_MANAGER.md

@@ -93,6 +93,17 @@ finally:
 
 ## 5. 账号选择与多账号
 
+### 5.0 数据管理 / 定时任务表单选账号（Action Lookup）
+
+若 Action 参数需要用户**点选账号**（而非手填编号）：
+
+- 在 `actions.json` 用 **`display_type: lookup` + `lookup.source: skill_cli`**，指向 `account-manager` 能吐 JSON 选项列表的 CLI（字段名 / `items_path` 以 account-manager 文档与实际 stdout 为准）。
+- **禁止**在本技能库再建「账号选项缓存表」再 `local_sql`——易过期，且定时任务等入口容易空下拉。
+- 契约与示例见 [`references/ACTIONS.md`](../references/ACTIONS.md)「跨表引用：Lookup」、`assets/examples/lookup-skill-cli.action.example.json`。
+
+表单 Lookup **只负责填参数**；真正开浏览器前的 ensure / pick / 租约仍按下文与 `account_client` 执行，二者不要混成「打开表单就 pick-web」。
+
+### 5.1 运行时选择顺序
 选择优先级：
 
 1. 用户明确指定纯数字 `DEFAULT_ACCOUNT_ID`：先确认账号存在且平台一致，再通过可定位该账号的 pick 流程取得租约；不得只 `get` 后返回空租约。

development/CHECKLIST.md

@@ -108,11 +108,14 @@ 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` 混淆）
-- [ ] A4-8 **P1** 行内/勾选打开的 `form`：有「已选择」时参数区不应再重复映射主键（`inputMapping` + `readOnly`）；需要强制露出时用 `revealInForm`，**禁止**用 `visibleWhen` 藏主键（会不提交）
-- [ ] A4-9 **P1** 若同一能力既支持「勾选处理」又支持「按数量从队列领取」：用一个 Action + `bind.selectionMode: "optional"`（勿拆两个同义顶栏按钮）；无勾选可点、有勾选显示「已选择」、空选数量字段用 `pickCount` 等约定名（见 `references/ACTIONS.md`）
+- [ ] A4-6 **P0** 若 Action 需引用业务行（话术/平台/账号等）：参数为 Lookup 下拉（**不是**手填内部编号）；同库用 `local_sql`（内联或绑列），跨技能用 **`skill_cli`**（勿在本库造镜像缓存表）；可选「自动」可留空提交（见 `references/ACTIONS.md`）
+- [ ] A4-7 **P1** 若 Action 有互斥采集/操作模式（如「按关键词 / 按主页」）：用 `inputSchema` 字段级 **`visibleWhen`** 联动显隐，勿只靠 `description` 灰字说明「仅某某时填写」（见 `references/ACTIONS.md`；勿与 **`bind.visibleWhen`** 行菜单、Policy L3 混淆）
+- [ ] A4-8 **P1** 行内/勾选打开的 `form`：有「已选择」时参数区不应再重复映射主键（`inputMapping` + `readOnly`）；需要强制露出时用 `revealInForm`，**禁止**用表单 `visibleWhen` 藏主键（会不提交）
+- [ ] A4-9 **P1** 若同一能力既支持「勾选处理」又支持「按数量从队列领取」：用一个 Action + `bind.selectionMode: "optional"`（勿拆两个同义顶栏 / cron 按钮）；无勾选可点、有勾选显示「已选择」、空选数量字段用 `pickCount` 等约定名；**定时任务配置页**只应出现数量字段、不应出现空的「编号列表」（见 `references/ACTIONS.md`）
 - [ ] A4-10 **P0** 数据管理弹窗与任务失败文案：全中文产品用语；禁止在 `description` / `confirmation.message` / 参数 `description` / 用户向 `message` 写英文字段名、CLI 子命令、`async`/`pending`/`status=` 等（Agent 路由放 `SKILL.md`；见 `references/ACTIONS.md`「用户可见文案」）
+- [ ] A4-11 **P1** 若行操作应按业务状态显隐（如仅待确认可「采用」、仅已采用可「加入待写」）：用 **`bind.visibleWhen`**（对当前行列值求值；存库原始值如 `approved`）；勿指望 Policy L3；CLI 侧仍须校验状态（见 `references/ACTIONS.md`「行菜单显隐」）
+- [ ] A4-12 **P1** 若要在表单里翻页勾选一批业务行（文章、平台等）：用 Lookup **`presentation: "paged_table"`**（仍是 `display_type: lookup`，勿新造类型）；`skill_cli` 的 stdout 为一行 `{"items","total"}`，0 条也成功退出；该列表命令不要在入口加载整包 platform-kit 或 Playwright（见 `references/ACTIONS.md`「分页勾选小表」）
+- [ ] A4-13 **P1** 若 Action 有固定小枚举（状态/船司/优先级等）需中文展示：用 `enum` + **`enumNames`**，或绑列复用列 `options_json` 数组；宿主优先序为绑列 options → enumNames → 纯 enum；**禁止**为中文展示造假 Lookup（见 `references/ACTIONS.md`「静态枚举 label」）
 ---
 
 ## 5. 账号与浏览器会话（网页 RPA 适用；其他形态标 N/A 或改测等价项）
@@ -120,7 +123,7 @@ checklist_version: 1.0
 - [ ] A5-1 **P0** 未准备好账号/浏览器档案时，主路径失败并提示，不会默默用本机默认浏览器身份跑起来
 - [ ] A5-2 **P0** 登录策略为 required 时：未登录不能把做不成的事当成成功
 - [ ] A5-3 **P0** 交付联调默认能看见浏览器窗口（有头）；不能把无头当作唯一可验收形态
-- [ ] A5-4 **P1** 浏览器窗口启动形态满足交付约定（如最大化或可视区域足够操作与人工介入）
+- [ ] A5-4 **P1** 浏览器窗口启动形态满足交付约定（如最大化或可视区域足够操作与人工介入）；`no_viewport=True` + `--start-maximized`，无「先小后大」或右侧留白/scrollbar 后遗症（见 `RPA.md` §1.2.1）
 - [ ] A5-5 **P1** 验证码或人工确认：有等待与超时；超时后任务失败可理解，不无限挂死或假成功
 - [ ] A5-6 **P0** **NEED_MANUAL** 真实站或约定仿真站主路径至少完整跑通 1 次；仅模拟数据通过不算交活
 - [ ] A5-7 **P0** 账号创建后可在宿主数据管理和 `account list/get` 查到，返回的 `profile_dir` 在当前用户数据目录真实存在
@@ -151,6 +154,7 @@ checklist_version: 1.0
 - [ ] A6-13 **P0** 新技能**不得**创建 `task_logs`；过程/进度/业务结果走运行日志、任务中心、业务表（见 `LOGGING.md`、`SCHEMA.md`）
 - [ ] A6-14 **P0** 废弃用户可见表时：`drop_deprecated_user_table` 物理删表 + 清元数据；**禁止**只删元数据留物理表；有迁移时须提供旧库回归测试（见 `SCHEMA.md`、`tests/samples/test_table_deprecation_migration.py.sample`）
 - [ ] A6-15 **P1** 若启用 `cellPresentation`：旁路表不得出现在数据管理侧栏；整行着色不得铺到详情每个字段；禁止 `all`×`all`；tone 闭集。未启用 → **N/A**（见 `references/CELL_PRESENTATION.md`）
+- [ ] A6-16 **P0** 若走 **MySQL 云库**：用户目录 `data-sources.json` + `.env` DSN 已配置；Host ≥ 6.9.28；CLI / Action 与数据管理 UI 读写**同一库**（抽测 list/create）；业务 DDL 支持所选后端。纯 SQLite → **N/A**（见 `references/DATA_SOURCES.md`）
 
 ---
 

development/CONFIG.md

@@ -230,8 +230,25 @@ config.get_float("STEP_DELAY_MIN", 1.0)
 - `python scripts/main.py doctor`：检查浏览器、Profile/账号、`.env` 落盘、设备等。
 - `python scripts/main.py setup`：初始化演示账号、首次落盘 `.env`。
 
+## MySQL 云库（可选）
+
+技能若走 MySQL 云库（匠厂 Host **≥ 6.9.28**），须同时满足：
+
+1. 用户数据目录有 [`data-sources.json`](../references/DATA_SOURCES.md)（声明 `kind: mysql` 与 `connectionEnv`）
+2. `.env` 配置对应 DSN，模板默认为 `MYSQL_DSN`
+
+```env
+# MySQL 云库连接（留空=本地 SQLite）
+MYSQL_DSN=mysql://user:password@host:3306/database_name
+```
+
+**不要**把 DSN 写进 `data-sources.json`。技能 CLI 通过 `scripts/db/backend.py` 读取同一 key，与宿主 UI 保持一致。
+
+完整契约见 [`../references/DATA_SOURCES.md`](../references/DATA_SOURCES.md)。
+
 ## 相关文档
 
+- `DATA_SOURCES.md` — 多数据源声明（SQLite 默认 / MySQL opt-in）
 - `RPA.md` — 三端 RPA 标准与各开关含义（开发向；勿写入 `.env` 注释）
 - `ACCOUNT_MANAGER.md` — 账号选择、Profile、租约、数据位置与验收
 - `ADAPTER.md` — `OPENCLAW_TEST_TARGET` 四档模式（开发向；勿写入 `.env` 注释）

development/DATA_PATHS.md

@@ -52,8 +52,9 @@ D:\jiangchang-data\12500\download-video-baidu-haokan\
 | `temp/` | 单次任务 scratch，任务结束可删 | `get_temp_dir()` |
 | `rpa-artifacts/` | RPA 失败截图、录屏中间产物 | `get_rpa_artifacts_dir(batch_id)` |
 | `videos/` | RPA 录屏成片 MP4 | `get_videos_dir()` |
-| `{skill_slug}.db` | SQLite | `get_db_path()` |
-| `.env` | 用户配置 | `config.get_env_file_path()` |
+| `{skill_slug}.db` | SQLite（默认本地库） | `get_db_path()` |
+| `data-sources.json` | 声明式数据源（可选；不配则宿主自动扫描 `.db`） | 用户目录根；格式见 [`../references/DATA_SOURCES.md`](../references/DATA_SOURCES.md) |
+| `.env` | 用户配置（含可选 `MYSQL_DSN`） | `config.get_env_file_path()` |
 
 复制后若业务不需要某目录，可不创建；**但一旦写入该类文件，必须走对应 helper**。
 

development/DEVELOPMENT.md

@@ -118,8 +118,8 @@ scripts/
   不写具体业务逻辑
 
 - `db/`
-  作用：SQLite 连接、建表、repository
-  不写页面操作和业务编排
+  作用：数据库连接（默认 SQLite；配 `MYSQL_DSN` 时为 MySQL）、建表、repository
+  不写页面操作和业务编排；多数据源契约见 [`../references/DATA_SOURCES.md`](../references/DATA_SOURCES.md)
 
 - `service/`
   作用：核心业务逻辑
@@ -213,6 +213,14 @@ release workflow 会对 `scripts/` 下的 Python 源码做加密/打包。当前
 - 不要把完整 RPA 主流程、DOM 选择器、数据库、CLI、日志全部堆进一个大文件。
 - 正确做法是拆分到 `scripts/cli/`、`scripts/service/`、`scripts/db/`、`scripts/util/`。
 
+以上行数是预防性硬门槛，**不是 Trial 加密成功的充分条件**。PyArmor Trial 对具体源码模块的限制不能用一个未经验证的字节数阈值代替；即使文件低于 1000 行，实际加密仍可能因单个模块过大或过于复杂而失败。免费模式下的处理约定：
+
+1. 以 Gitea release workflow 使用的 Trial 加密步骤和目标平台为准做实际验证；查看日志确认失败发生在哪个 `.py` 文件，不以本地行数检查通过推断加密一定成功。
+2. 若日志指出某个模块加密失败（例如 Trial license / big script 一类限制），按职责把该模块拆成更小的实现模块；原文件保留为兼容门面，重导出原有公开函数、类或常量，避免改坏已有 import 路径。
+3. 拆分后先跑完整测试，再升补丁版本并 release；检查 Gitea job 中所有 Python 模块均已加密、加密包成功生成/上传且 job 最终成功。失败时继续针对日志定位的模块拆分并重新验证，不放宽免费模式、不猜统一字节上限。
+
+模板案例：得一智慧审单的 `field_locator.py` 在免费 Trial 加密阶段失败；按职责拆分为多个实现模块并保留原文件兼容门面后，同一免费 Trial 发布链路成功。这个案例用于说明应对**具体失败模块做职责拆分并复验**，不作为其他技能的固定文件字节数阈值。
+
 `examples/` 里的 Python 示例也建议保持模块化，但**行数限制不作为 examples 的发布硬约束**；不要对 README、HTML、测试数据等文档/资源套用 PyArmor 行数规则。
 
 **文本编码（UTF-8 without BOM）**
@@ -928,7 +936,7 @@ uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-relea
 | **数据管理 · HTML 报告** | 壳子页放 `assets/html/pages/*.html`；快照写出 `html/*.html` 并提供 `render-html` | 壳子装完即现、右键无「重新生成」；快照可重新生成；页面 `jiangchang.call` 能拿到 JSON |
 | **数据管理 · 行级** | `placements` 含 `row`（建议 `bind.tables` + `bind.inputMapping` 预填主键） | 操作列和/或行右键（及可选「⋯」）出现本技能行级 Action（需有主键列）；点按后入参/行为与壳无关、均正确 |
 | **数据管理 · 批量** | `placements` 含 `batch` | 勾选行后批量按钮可用；无勾选时禁用；批量行为正确 |
-| **定时任务** | `placements` 含 `cron`（创建时选「技能直调」） | 能选到本技能 Action、保存并触发；到点或「立即运行」行为正确 |
+| **定时任务** | `placements` 含 `cron`（创建时选「技能直调」） | 能选到本技能 Action、保存并触发；到点或「立即运行」行为正确；`selectionMode: optional` 时参数区只见数量字段、不见空「编号列表」 |
 | **任务中心** | 不是 placement；由 `executionProfile: "async"` 决定是否进 Job | 长任务出现进度 / 可取消；来源标签与触发入口一致 |
 | **技能市场 → 技能详情** | `placements` 含 `skill-detail`（详情直调） | **必验**安装与四 Tab。详情页「技能直调」按钮随宿主版本上线；**已声明则须在具备该 UI 的宿主上完成按钮自测**（与其它入口同等对待，不要只靠 Agent） |
 

development/POLICY_MATRIX.md

@@ -23,7 +23,8 @@
 | POLICY-RPA-004 | 网页 RPA：`.env.example` 若声明 `OPENCLAW_BROWSER_HEADLESS` 则默认必须为 `0`；`scripts/` 若使用 `launch_persistent_*` 则必须同时存在 `pick_web_account`（先 Profile 再开浏览器；实现上应走 ensure-web）；登录不全局强制，但不得跳过 account-manager | development/RPA.md §0.2；development/ADAPTER.md §兄弟依赖 | hard | 解析 `.env.example` + 扫描 `scripts/**/*.py` | `tests/test_development_policy_guard.py::TestPolicyRpa004` |
 | POLICY-RPA-005 | 必须保留 AI + RPA 总纲，明确 Agent / RPA 职责、授权范围、禁止破解/逆向/私有协议/安全验证绕过、人工介入、状态等待；真实业务默认动作节奏为 1～3 秒 | development/AI_RPA.md §4–§6；development/RPA.md §0.0/§0.3 | hard（文档与默认配置） / soft（真实行为） | 检查总纲关键边界；解析 `.env.example` 的 `STEP_DELAY_MIN=1.0` / `STEP_DELAY_MAX=3.0` | `tests/test_development_policy_guard.py::TestPolicyRpa005` |
 | POLICY-RPA-006 | 浏览器 RPA 必须保留 account-manager 生命周期标准；所有样例账号选择路径都须返回非空 `profile_dir + lease_token`，指定数字账号 ID 不得退化为无租约 `account get` | development/ACCOUNT_MANAGER.md；development/ADAPTER.md §兄弟依赖；development/RPA.md §0.2 | hard | 检查标准文档关键标记；扫描真实/仿真 `account_client.py` 的指定 ID 带租约实现并禁止空租约赋值 | `tests/test_development_policy_guard.py::TestPolicyRpa006` |
-| POLICY-PACKAGING-001 | `scripts/**/*.py` 单文件 < 1000 行 | development/DEVELOPMENT.md §3.4 发布打包约束；development/RUNTIME.md §发布打包约束 | hard | 行数统计 | **已有测试覆盖**：`tests/test_release_packaging_constraints.py::test_scripts_py_files_under_pyarmor_line_limit` |
+| POLICY-RPA-007 | 网页 RPA 启动须 `no_viewport=True` + `--start-maximized`；禁止 `viewport=None`、CDP/JS 中途改窗；`RPA.md` §1.2.1 须保留窗口标准 | development/RPA.md §1.2.1；development/RPA_BROWSER.md §4；examples/real_browser_rpa | hard | 文档标记 + 扫描含 `launch_persistent_*` 的 Python 禁止模式；校验 real_browser 示例 | `tests/test_development_policy_guard.py::TestPolicyRpa007` |
+| POLICY-PACKAGING-001 | `scripts/**/*.py` 单文件 < 1000 行；该门槛不保证 Trial 加密成功。免费 Trial 实际失败时按报错模块拆分职责、保留兼容门面，并以 Gitea 实际加密 job 成功作为发布验收 | development/DEVELOPMENT.md §3.4 发布打包约束；development/RUNTIME.md §发布打包约束 | hard | 行数测试 + Trial 发布 job 结果 | **已有测试覆盖**：`tests/test_release_packaging_constraints.py::test_scripts_py_files_under_pyarmor_line_limit`、`test_trial_packaging_guidance_is_documented`；实际加密由 Gitea release workflow 验证 |
 | POLICY-PACKAGING-002 | 文本文件 UTF-8 without BOM，无 `U+FEFF` | development/DEVELOPMENT.md §3.4；development/RUNTIME.md §编码与输出 | hard | BOM / 解码检查 | **已有测试覆盖**：`tests/test_release_packaging_constraints.py::test_text_files_are_utf8_without_bom` |
 | POLICY-RELEASE-001 | 发布 tag（去掉前缀）必须等于 `SKILL.md` 的 `version:` 且等于 `scripts/util/constants.py` 的 `SKILL_VERSION`；`release.ps1` 打 tag 前硬失败，不自动改写字段 | development/DEVELOPMENT.md §15 发布；宿主市场「最新版本」来自 tag、「当前版本」来自包内 `SKILL.md` | hard | `release.ps1` 门禁 + 日常版本字段对齐测试 | `release.ps1`（`Assert-SkillReleaseVersionAlignment`）；`tests/test_development_policy_guard.py::TestPolicyRelease001`；`tests/test_skill_metadata.py::test_skill_version_alignment` |
 | POLICY-DOCS-001 | 本矩阵存在且包含上述全部 `policy_id` | 本次规范化约定 | hard | 解析 `development/POLICY_MATRIX.md` | `tests/test_development_policy_guard.py::TestPolicyDocs001` |

development/RPA.md

@@ -189,18 +189,35 @@ BrowserType.launch_persistent_context: Arguments can not specify page to be open
 
 **正确做法（生产路径）：**
 
-1. `launch_persistent_context(user_data_dir=profile_dir, executable_path=chrome, args=chrome_args, ...)`
+1. `launch_persistent_context(user_data_dir=profile_dir, executable_path=chrome, args=chrome_args, locale="zh-CN", no_viewport=True, ...)`
 2. `page = await context.new_page()`
 3. `await page.goto(start_url, wait_until="domcontentloaded", timeout=60000)`
 
 对强风控站点，如果需要更拟人，可以启动后通过**地址栏输入 / 真实点击进入**目标页，但**仍然不能把 URL 塞进 launch args**。
 
+#### 1.2.1 窗口与 viewport（`POLICY-RPA-007`）
+
+persistent profile 会记住上次窗口大小；**最大化与 layout 同步**须按下列标准，避免「先小后大、右侧留白、scrollbar 后遗症」：
+
+| 必须 | 禁止 |
+|------|------|
+| `no_viewport=True`（页面 layout 跟随真实窗口） | `viewport=None` 或固定 `viewport={width,height}` 冒充全屏 |
+| launch args 含 `--start-maximized` | CDP `Browser.setWindowBounds` / JS `resizeTo` **中途改窗** |
+| 真实站：`browser_session` 内 **启动后尽快 `goto` 业务页** | 长时间停空白页再导航、goto 后再 CDP 最大化 |
+| 优先复制 `examples/real_browser_rpa/scripts/service/browser_session.py` | 自造 maximize / CDP 窗口 hack |
+
+说明：
+
+- **`no_viewport=True` ≠ `viewport=None`**。后者在 Playwright 中不等于「跟窗口走」，易导致 OS 窗口已最大化但页面仍按窄 viewport 排版。
+- **仿真站**（`examples/simulator_browser_rpa`）可在 `browser_session` 只做 launch、由上层 `goto`；仍须 **`no_viewport=True`**。
+- 共享库 `jiangchang_skill_core.rpa.launch_persistent_browser` 已内置 `no_viewport=True`；自写 `browser_session` 时勿漏。
+
 完整参考实现见：
 
 - `examples/real_browser_rpa/README.md`（**开发真实浏览器 RPA 类 skill 时必须先读**）
 - `examples/real_browser_rpa/scripts/service/browser_session.py`
 
-**生产路径不要依赖 CDP 接管现有页面**；CDP 仅用于诊断或桌面宿主已打开浏览器的场景。
+**生产路径不要依赖 CDP 接管现有页面**；CDP 仅用于诊断或桌面宿主已打开浏览器的场景（**含禁止用 CDP 最大化窗口**）。
 
 ### 1.3 HITL / 验证码
 

development/RPA_BROWSER.md

@@ -90,6 +90,19 @@ button = row.get_by_role("button", name="添加")
 
 Playwright CSS locator 默认可穿透 open Shadow DOM；XPath 不穿透。closed Shadow DOM 无法正常读取时，评估目标应用是否提供可访问性属性，不能注入破解。
 
+**Web Component 双 input 陷阱**（常见于 `<mc-input>` 等宿主）：
+
+- 轻 DOM 内可能有 **hidden 同步用 input**（`aria-hidden="true"`、`tabindex="-1"`）。
+- 裸写 `host >> input` 时 Playwright 常默认匹配**第一个** hidden input，等 `visible` 会超时。
+- 做法：等 **host 可见**作 page ready；输入用 shadow 内真实字段（如 `>> #mc-input-track-input` 或 `>> input.input:not([aria-hidden="true"])`）；或 click host + keyboard。
+
+### Cookie / 同意条（可选出现）
+
+Profile 已点过「允许全部」后，下次可能**不再出现** Cookie 条。不要无限等待：
+
+- 短超时（约 2～3s）探测可见 → 点击；
+- 超时或无元素 → **skip 继续**，不要阻塞主流程。
+
 ### 动态列表
 
 等待列表完成加载后再读取；`locator.all()` 不会等待动态列表稳定。滚动或刷新后重新获取 locator。
@@ -109,6 +122,7 @@ Playwright CSS locator 默认可穿透 open Shadow DOM；XPath 不穿透。close
 ## 6. 禁止模式
 
 - 用全页所有 `input` 的尺寸和位置猜搜索框。
+- 对 Web Component 裸用 `host >> input` 且不等 shadow 内真实可编辑 input。
 - 用 `.first` 绕过严格模式。
 - 从 DevTools 复制深层 `nth-child` 或绝对 XPath。
 - 只等 URL 含 `search` 就判定结果成功。

development/RUNTIME.md

@@ -140,6 +140,8 @@ RPA 录屏成片（`RpaVideoSession`）、ffmpeg 路径、背景音乐探测均
 
 release workflow 加密 `scripts/` 源码时，可能运行在 PyArmor 免费/试用模式：
 
-- `scripts/**/*.py` 单文件必须 **< 1000 行**（`>= 1000` 可能在 CI 失败）；推荐 **< 900 行**。
-- 接近上限时拆分到 `cli/`、`service/`、`db/`、`util/`，不要把 RPA 主流程、选择器、DB、CLI 堆进单文件。
+- `scripts/**/*.py` 单文件必须 **< 1000 行**（`>= 1000` 可能在 CI 失败）；推荐 **< 900 行**。这是预防性硬门槛，不代表低于该行数就一定能被 Trial 加密。
+- 模块应按职责拆分到 `cli/`、`service/`、`db/`、`util/`；不要把 RPA 主流程、选择器、DB、CLI 堆进单文件。发现某个文件在免费 Trial 加密时报错时，按报错定位该文件并继续拆分其职责，重新走实际加密验证；不要通过猜测统一的源码字节数阈值代替验证。
+- 拆分已有模块时，尽量保留原模块作为兼容门面（re-export / 委托到新模块），避免破坏现有 import 路径；先跑测试，再发布验证。
+- 发布验收以 Gitea release workflow 中实际的 PyArmor Trial 加密结果为准：确认全部 `scripts/**/*.py` 均成功加密、加密包成功生成/上传且 job 成功。若 PyArmor 步骤失败，不得把版本视为已发布成功；按日志中的失败文件拆分、升补丁版本并重新 release。
 - 此行数限制**仅适用于** `scripts/**/*.py`；不限制 README 等文档行数，也不把 examples 里的 HTML/README 纳入 PyArmor 行数约束。

development/SKILL_ACTION_RUNTIME.md

@@ -9,7 +9,7 @@
 | 文档 | 职责 |
 |------|------|
 | 本文 | sync/async、任务中心、Agent 禁令、单内核编排、队列 pick、同步 vs 导出 |
-| [`../references/ACTIONS.md`](../references/ACTIONS.md) | `actions.json` 字段、placements、`bind.tables`、`bind.selectionMode`、**用户可见文案**、inputSchema、跨表 Lookup、字段条件显隐 `visibleWhen`、本地路径 `file`/`directory` + 可选 **`pathRoot`**、选择摘要「已选择」与映射 **`readOnly` / `revealInForm`**、**按钮中文名 `label` 参考** |
+| [`../references/ACTIONS.md`](../references/ACTIONS.md) | `actions.json` 字段、placements、`bind.tables`、`bind.selectionMode`、`bind.visibleWhen`（行菜单显隐）、**用户可见文案**、inputSchema、跨表 Lookup（含分页勾选 `presentation: paged_table`）、字段条件显隐 `visibleWhen`、本地路径 `file`/`directory` + 可选 **`pathRoot`**、选择摘要「已选择」与映射 **`readOnly` / `revealInForm`**、**按钮中文名 `label` 参考** |
 | [`LOGGING.md`](LOGGING.md) | `job_context` / `emit` / `finish` / Run Journal |
 | [`DATA_PATHS.md`](DATA_PATHS.md) | 下载/导入等落盘路径 |
 
@@ -21,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）。可选 **`hoverHint`**（见 ACTIONS.md）：数据管理工具栏悬停；省略 = 不显示，不回退说明或确认黄条。可选 **`visibleWhen`**（见 ACTIONS.md）：Action 参数表单字段条件显隐；省略 = 字段始终平铺；**勿与** Policy L3 行态 `visibleWhen` 混淆；**勿**用其藏映射主键。可选 **`pathRoot`**（见 ACTIONS.md）：`file`/`directory` 原生选路对话框起始目录（相对技能数据根；省略默认 `{skill_data}/input`）。可选 **`bind.labelColumn`**（见 ACTIONS.md）：选择摘要可读标签列；省略 = 宿主常见列名启发。可选 **`bind.selectionMode`**（见 ACTIONS.md）：表勾选如何驱动 Action（`required` / `none` / `optional`）；省略 = 宿主按 `$selection.ids` / `batch` 推断。可选 **`revealInForm`**（见 ACTIONS.md）：有「已选择」时仍强制显示某 `readOnly` 字段；省略 = 映射只读默认不占 form 参数区（仍提交）。可选 **`cellPresentation`**（见 `references/CELL_PRESENTATION.md`）：单元格/整行/整列/区域语义标色；省略 = P0。**用户可见文案**（见 ACTIONS.md「用户可见文案」）：弹窗 `description` / 确认黄条 / 参数说明 / 任务失败 `message` 须全中文产品用语；Agent 路由勿塞进弹窗。
+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 参数表单字段条件显隐；省略 = 字段始终平铺；**勿与** **`bind.visibleWhen`**（行菜单）或 Policy L3 混淆；**勿**用其藏映射主键。可选 **`pathRoot`**（见 ACTIONS.md）：`file`/`directory` 原生选路对话框起始目录（相对技能数据根；省略默认 `{skill_data}/input`）。可选 **`bind.labelColumn`**（见 ACTIONS.md）：选择摘要可读标签列；省略 = 宿主常见列名启发。可选 **`bind.selectionMode`**（见 ACTIONS.md）：表勾选如何驱动 Action（`required` / `none` / `optional`）；省略 = 宿主按 `$selection.ids` / `batch` 推断；**定时任务等无表勾选入口按无勾选分支**（隐藏 `$selection.ids`，保留 `pickCount`）。可选 **`bind.visibleWhen`**（见 ACTIONS.md「行菜单显隐」）：`row` 菜单按当前行列值显隐；省略 = 始终显示。可选 **`revealInForm`**（见 ACTIONS.md）：有「已选择」时仍强制显示某 `readOnly` 字段；省略 = 映射只读默认不占 form 参数区（仍提交）。可选 **`cellPresentation`**（见 `references/CELL_PRESENTATION.md`）：单元格/整行/整列/区域语义标色；省略 = P0。**用户可见文案**（见 ACTIONS.md「用户可见文案」）：弹窗 `description` / 确认黄条 / 参数说明 / 任务失败 `message` 须全中文产品用语；Agent 路由勿塞进弹窗。
 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 流**。

development/TESTING.md

@@ -32,7 +32,7 @@
 - Skill Action manifest：`assets/actions.json` 结构、CLI 映射、placements 与 inputSchema 守护（见 `test_actions_manifest.py`）；
 - 标准时间字段：`created_at` / `updated_at` 默认值、trigger 维护与 `datetime_unix_seconds` 元数据（见 `test_timestamp_columns.py`）；
 - **adapter profile**：[`tests/test_adapter_profile_policy.py`](../tests/test_adapter_profile_policy.py) + [`adapter_test_utils`](../tests/adapter_test_utils.py) ——验证在未授权情况下绝不误判开启真实网络/RPA。
-- **发布打包守护**：[`tests/test_release_packaging_constraints.py`](../tests/test_release_packaging_constraints.py) ——`scripts/**/*.py` 单文件 < 1000 行、文本文件 UTF-8 without BOM。
+- **发布打包守护**：[`tests/test_release_packaging_constraints.py`](../tests/test_release_packaging_constraints.py) ——`scripts/**/*.py` 单文件 < 1000 行、PyArmor Trial 拆分/实际发布验证约定、文本文件 UTF-8 without BOM。行数通过只表示通过预防性门槛；免费 Trial 是否能加密成功仍以 Gitea 实际加密 job 为准。
 - **开发规范守护（hard policy）**：[`tests/test_development_policy_guard.py`](../tests/test_development_policy_guard.py) ——规则索引见 [`development/POLICY_MATRIX.md`](POLICY_MATRIX.md)，只执行可机器检测的 hard 规则。
 - **slug 语义**：[`tests/test_slug_naming.py`](../tests/test_slug_naming.py) ——动词-名词命名；平台可选，`default` 不再作为占位。
 - **HTML 报告壳**：[`tests/test_html_page_service.py`](../tests/test_html_page_service.py) 守护 `assets/html/example-report.html` 的数据管理 iframe 预览布局基线，并守护 ACTIONS.md 里的壳子页目录 `assets/html/pages` 与 `jiangchang.call`。业务技能若有自定义 `assets/html/*.html` 或 `pages/*.html`，建议在自有仓库加同类静态断言（见 `references/ACTIONS.md`「宿主预览布局」）。不要把 `example-report.html` 放进 `pages/`。

examples/real_browser_rpa/README.md

@@ -91,6 +91,7 @@ real_browser_rpa/
 - **不要**在技能内安装 Playwright；浏览器与 Python 包由宿主/runtime 提供
 - `launch_persistent_context` 的 `args` **只放 Chrome 参数**；**不要把 URL 放进 `args`**
 - 页面必须通过 `new_page()` + `goto()`，或通过真实地址栏/点击进入
+- **必须** `no_viewport=True` + `--start-maximized`；**禁止** `viewport=None` 与 CDP/JS 中途改窗（见 `development/RPA.md` §1.2.1、`POLICY-RPA-007`）
 
 ## 复制边界：哪些能复制，哪些必须替换
 

examples/real_browser_rpa/scripts/service/browser_session.py

@@ -59,6 +59,7 @@ async def start_browser_session(
     """
     启动持久化 Chrome profile，new_page + goto 入口页，返回 (playwright, context, page)。
 
+    窗口标准（POLICY-RPA-007）：no_viewport=True + --start-maximized；勿用固定 viewport 或 CDP 改窗。
     真实 skill 需要安装 playwright 与 jiangchang_skill_core。
     """
     from playwright.async_api import async_playwright

references/ACTIONS.md

@@ -84,7 +84,7 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 | 字段 / 层 | 只决定什么 | 不决定什么 |
 |-----------|------------|------------|
 | **`placements`** | Action **出现在哪里**（toolbar / row / batch / cron / agent / skill-detail；`row`=行级入口，壳由宿主呈现） | 不决定 sync/async，不决定点了是否弹窗，不决定行级用操作列还是右键，不决定谁能点 |
-| **`replaces`** | **可选**：接管数据管理默认「新增 / 编辑 / 删除 / **导入**」 | 不强制；无配置时宿主仍直写 SQLite；**import 时 UI 仍用宿主「导入数据」面板** |
+| **`replaces`** | **可选**：接管数据管理默认「新增 / 编辑 / 删除 / **导入**」 | 不强制；无配置时宿主仍直写**已注册数据源**（默认本地 SQLite）；**import 时 UI 仍用宿主「导入数据」面板** |
 | **`bind.tables`** | 数据管理里出现在**哪些业务表** | 不决定业务实现 |
 | **`executionProfile`** | 宿主是**同步等待**还是**异步 Job** | 不限制可展示入口，不决定是否弹窗 |
 | **`interaction`** | 可点击入口（数据管理 toolbar/row/batch、默认 CRUD 接管、未来 skill-detail）**点了怎么交互** | 不决定 sync/async；**cron 触发与 agent 忽略** |
@@ -107,10 +107,10 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 | entrypoint | `type = cli`、`command`、`args`（**必填** JSON 数组，项为 `string` / `number` / `boolean`） |
 | placements | `toolbar`、`row`、`batch`、`skill-detail`、`agent`、`cron`；仅 `replaces` 时可为空数组 |
 | **replaces** | 可选 `"create"` \| `"update"` \| `"delete"` \| `"import"` — 接管默认新增/编辑/删除/导入（须 `bind.tables`） |
-| **bind** | `{ "tables": ["business_table"] }`；可选 `inputMapping`、`columnMapping`、**`labelColumn`**、**`selectionMode`**（行内/批量预填、选择摘要标签、勾选驱动模式，见下节） |
+| **bind** | `{ "tables": ["business_table"] }`；可选 `inputMapping`、`columnMapping`、**`labelColumn`**、**`selectionMode`**、**`visibleWhen`**（行内/批量预填、选择摘要标签、勾选驱动模式、**行菜单显隐**，见下节） |
 | **policy** | 可选；`enabled` + `entrypoint`（推荐 `policy` CLI）；见 POLICY.md。未启用 = L0 |
 | **cellPresentation** | 可选；`{ "enabled": true }` 时宿主应加载格子与 grid 呈现；见 [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md)。未启用 = P0 |
-| inputSchema | 根 `type: object`；properties 使用 `string` / `number` / `boolean`；支持 `enum`、`default`、`required`、`sensitive`、`readOnly`、可选 **`revealInForm`**；可选 `display_type` / `format`（含 `file` / `directory` 等）；可选 **`pathRoot`**（file/directory 起始目录，相对技能数据根）；可选 **`visibleWhen`**（字段条件显隐，见专节） |
+| inputSchema | 根 `type: object`；properties 使用 `string` / `number` / `boolean`；支持 `enum`、可选 **`enumNames`**、`default`、`required`、`sensitive`、`readOnly`、可选 **`revealInForm`**；可选 `column`（绑列复用 options）；可选 `display_type` / `format`（含 `file` / `directory` 等）；可选 **`pathRoot`**（file/directory 起始目录，相对技能数据根）；可选 **`visibleWhen`**（字段条件显隐，见专节） |
 | confirmation | `{ "message": "..." }` — **风险文案**（confirm/form 弹窗黄条；agent 元数据）；**不是**「要不要弹窗」的开关 |
 | **hoverHint** | 可选字符串。数据管理**工具栏悬停**文案；与 `description` / `confirmation.message` **独立**。省略则不显示悬停，不回退。短名已够懂时不要写。需宿主已支持该字段；当前实现为顶栏技能按钮，不含宿主内置删除/刷新/新增/导入/导出 |
 | **visibleWhen** | 可选。写在 **property** 上（非 action 顶层）：依赖同表单其它字段值决定是否展示；隐藏字段不提交、不校验 `required`。**勿与** [`POLICY.md`](POLICY.md) L3 行态 `visibleWhen` 混淆；也**勿**用它藏「已选择」已表达的映射主键（见「选择摘要」） |
@@ -133,7 +133,7 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 
 规则：
 
-- `bind` 为 object，`additionalProperties: false`；当前允许 `tables`（必填键当存在 bind 时）与可选 `inputMapping`、`columnMapping`、**`labelColumn`**、**`selectionMode`**。
+- `bind` 为 object，`additionalProperties: false`；当前允许 `tables`（必填键当存在 bind 时）与可选 `inputMapping`、`columnMapping`、**`labelColumn`**、**`selectionMode`**、**`visibleWhen`**。
 - `tables` 非空数组、元素唯一、英文 **snake_case**、不得为空字符串。
 - **`placements` 含 `toolbar` 时必须显式声明非空 `bind.tables`**（模板 Schema `if/then` + 自动测试强制）。
 - `row` / `batch` **建议**同样声明 `bind.tables`，避免在无关表上露出按钮；未声明时宿主可能按兼容逻辑在更多表上展示。
@@ -143,8 +143,42 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 - **`columnMapping`（可选）**：把 inputSchema 属性名映射到物理列名，供表单复用列展示名 / lookup。
 - **`labelColumn`（可选）**：物理列名，供数据管理 Action 弹层「已选择」摘要展示 `#id + 标签`。**仅影响展示，不改变 CLI/提交 payload，也不决定业务是否跳过某些状态。** 省略时宿主用常见列名启发（如 `title` / `name` / `nickname` 等）；再没有则只显示编号。列名不常见、或启发会选错列时再显式声明。
 - **`selectionMode`（可选）**：数据管理**表勾选**如何驱动本 Action（与 `placements` / `executionProfile` 正交）。见下节「勾选驱动模式」。
+- **`visibleWhen`（可选）**：`placements` 含 `row` 时，按**当前行原始列值**决定是否出现在行菜单 / 行按钮。见下节「行菜单显隐」。
 - `concurrency` / `locks` 仍未稳定，**不要**写入新技能 manifest。
 
+### 数据管理：行菜单显隐 `bind.visibleWhen`
+
+行级 Action 常需按业务状态显隐，例如：已采用不再出「采用」；仅已采用才出「加入待写」。**宿主已支持**写在 `bind.visibleWhen`（对当前行求值；不匹配则该行菜单不出现此项）。这是正式 Action 契约，**不是** Policy L3 预留，也**不是**表单字段 `inputSchema.properties.*.visibleWhen`。
+
+| | `bind.visibleWhen` | 表单字段 `visibleWhen` | Policy L3（预留） |
+|--|--------------------|------------------------|-------------------|
+| 作用对象 | 行菜单 / 行按钮是否出现 | Action 参数表单里某个控件 | （未冻结）权限策略等 |
+| 求值上下文 | **当前行列值** | 当前表单参数值 | — |
+| 省略时 | 始终显示 | 字段始终显示 | — |
+
+**写法（形状与表单字段相同）：**
+
+```json
+"bind": {
+  "tables": ["long_tails"],
+  "visibleWhen": { "status": "approved" },
+  "inputMapping": { "longTailId": "$row.$pk" }
+}
+```
+
+```json
+"visibleWhen": { "field": "status", "in": ["pending_review", "skipped"] }
+```
+
+也支持 `{ "field": "status", "equals": "approved" }`。规则缺失或无法解析时宿主视为始终可见（兼容旧技能）。
+
+**要点：**
+
+1. 只影响 **UI 是否展示**；CLI / Agent 仍可直接调同一 entrypoint，技能侧仍应校验状态。
+2. 比较用行的**存库原始值**（如 `approved`），不是界面中文「已采用」。
+3. 顶栏 / batch 按钮不受 `bind.visibleWhen` 约束（无「当前行」）；批量入口靠勾选 + 技能跳过非法状态。
+4. 示例：[`assets/examples/bind-visible-when-row.action.example.json`](../assets/examples/bind-visible-when-row.action.example.json)。
+
 ### 数据管理：勾选驱动模式 `bind.selectionMode`
 
 同一业务能力应尽量用**一个** Action（多个 `placements`），避免「勾选下载」与「按数量处理队列」拆成两个同义顶栏按钮、却让用户误以为勾选生效。
@@ -163,7 +197,8 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 3. 空选数量字段名约定（宿主按字段名识别，保守列表）：`pickCount` / `maxLeads` / `maxCount` / `takeCount` / `pick`。
 4. `entrypoint.args` 可同时写 `--ids {{itemIds}}` 与 `--pick {{pickCount}}`；缺值的 `--flag` + 空串由宿主压缩掉，不会留下脏 argv。
 5. 有勾选时隐藏数量字段；无勾选时隐藏 `$selection.ids` 映射字段（`$row.*` 行上下文不受影响）。
-6. **不要**为同一能力再挂第二个 toolbar 按钮。
+6. **定时任务 / 技能详情等无表勾选入口**：宿主须按「无勾选」分支渲染与保存——只展示 `pickCount` 等数量字段，**不**画出空的「编号列表」类 `$selection.ids` 映射只读框；保存的 `actionInput` 也不应再带上空 `itemIds`。不要为 cron 再拆第二个 Action。
+7. **不要**为同一能力再挂第二个 toolbar 按钮。
 
 示例：[`assets/examples/selection-mode-optional.action.example.json`](../assets/examples/selection-mode-optional.action.example.json)。
 
@@ -231,7 +266,7 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 
 ## `replaces`（可选：接管默认新增 / 编辑 / 删除 / 导入）
 
-有领域副作用的表（归一化字段、建目录、加密、级联清理）不要依赖宿主直写 SQLite。此时可为该表声明 `replaces`，**用户仍点宿主默认按钮**，由技能 CLI 完成写入。
+有领域副作用的表（归一化字段、建目录、加密、级联清理）不要依赖宿主直写默认 CRUD。此时可为该表声明 `replaces`，**用户仍点宿主默认按钮**，由技能 CLI 完成写入。
 
 ### 怎么选
 
@@ -250,7 +285,7 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 2. **写库**按表能力分流：
    - 有 `replaces: import` → 把选中文件路径 + 出错规则交给该 Action（技能解析并写入）
    - 仅有 `replaces: create` → 宿主按行调用 create（兼容）
-   - 都没有 → 宿主直写 SQLite
+   - 都没有 → 宿主直写已注册数据源（默认 SQLite）
 
 **不要**再做一张技能自己的「开始执行」导入表单来冒充导入体验。`placements` 对 import 保持 `[]`；`description` 写明「由宿主导入面板调用」。
 
@@ -403,13 +438,14 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 - 点默认「导入」时**固定**打开宿主导入面板；确认后若有 `replaces:import` 则调用该 Action（`interaction` 不决定是否再弹技能表单）。
 - `update` / `delete` 可用 `inputMapping`（`$row.$pk`、`$selection.ids`）预填主键。
 - `import` 约定：`filePath`（或 `file`）+ 可选 `onError`（`skip`/`abort` 或上例中文枚举）；技能自行解析文件与表头。
-- 整表 `_jiangchang_tables.readonly=1` 时仍隐藏写按钮（优先于 `replaces`）。
-- **列元数据复用（lookup）**：Action 表单（含 toolbar/batch 弹窗与 create/update 抽屉）可将 `inputSchema` 字段对齐业务列，复用中文名与 lookup 下拉：
-  - 优先让属性名 = 物理列名（如 `platform_key`）；
-  - 或 `bind.columnMapping`：`{ "platform": "platform_key" }`；
-  - 或字段上写 `"column": "platform_key"`。
-  - 当前表没有对应列时，用字段内联 `lookup`（见下文「跨表引用：Lookup」）。
-  - **不要**在 actions.json 里写死会过期的全量平台 `enum`，也**不要**让用户手填内部编号。
+- 整表 `_jiangchang_tables.readonly=1` 时仍隐藏宿主默认新增/编辑/导入与直写删除；**若声明了 `replaces: delete`，宿主仍显示「删除」并走技能 CLI**（不直写 SQLite）。
+- **列元数据复用**：Action 表单（含 toolbar/batch 弹窗与 create/update 抽屉）可将 `inputSchema` 字段对齐业务列，复用中文名与列上 **options**（静态枚举 `options_json` **数组**，或已解析的 lookup）：
+  - 优先让属性名 = 物理列名（如 `carrier_code` / `platform_key`）；
+  - 或 `bind.columnMapping`：`{ "carrierCode": "carrier_code" }`；
+  - 或字段上写 `"column": "carrier_code"`（推荐：驼峰属性名时显式写出，避免只靠启发式）。
+  - 当前表没有对应列、且选项是**固定小枚举**时：用 `enum` + **`enumNames`**（见下文「静态枚举 label」），**不要**为中文展示去造 Lookup。
+  - 当前表没有对应列、且选项是**跨表/跨技能业务行**时：用字段内联 `lookup`（见下文「跨表引用：Lookup」）。
+  - **不要**在 actions.json 里写死会过期的全量业务行 `enum`，也**不要**让用户手填内部编号。
 
 ## `interaction`（点击交互方式）
 
@@ -480,7 +516,7 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 
 **边界：**
 
-- **cron 配置**：仍展示可编辑参数；`confirmation.message` 可作为配置页风险提示（由宿主决定）。
+- **cron 配置**：仍展示可编辑参数；`confirmation.message` 可作为配置页风险提示（由宿主决定）。若 Action 为 `selectionMode: "optional"`（或 `none`），配置页按**无表勾选**分支：隐藏 `$selection.ids` 映射字段，只保留数量等可编辑参数（见上文「勾选驱动模式」第 6 点）。
 - **cron 触发 / agent**：忽略 `interaction`（无人值守 / 模型填参）；`confirmation` 对 agent 仍作 `requiresConfirmation` 元数据。
 - 不要用 `interaction: "direct"` 掩盖需要用户填写的可编辑字段——宿主在 `auto` 下会因可编辑参数回落到 `form`；显式 `direct` + 可编辑字段时参数取 default/预填，作者须自觉。
 
@@ -746,7 +782,7 @@ HINT: <next step>
 
 ### 行级入口 `row`（宿主呈现契约）
 
-- **技能决定有什么**：`placements` 含 `"row"`（且通过 `bind.tables` / policy 等过滤）的 Action，构成该表行的技能菜单项集合；配什么就出现什么。
+- **技能决定有什么**：`placements` 含 `"row"`（且通过 `bind.tables` / policy 等过滤）的 Action，构成该表行的技能菜单项集合；再用可选 **`bind.visibleWhen`** 按行状态过滤（见「行菜单显隐」）。
 - **宿主决定怎么摆**：可用操作列、行右键、行内「⋯」等呈现**同一批** Action；点击均走同一 `launch`（`placement: "row"`），`interaction` / `executionProfile` 与壳无关。
 - **顺序**：各壳内技能项顺序 = 下方「数据管理技能按钮顺序」契约（`actions` 数组相对顺序）。
 - **宿主内置项**：查看 / 编辑 / 删除由宿主提供，**不是**技能 `actions.json` 配置出来的；若出现在行右键，须与技能项分组（例如分隔线后），且不得要求技能再配一份菜单 DSL。
@@ -910,14 +946,37 @@ const data = await jiangchang.call("方法名", { date: "2026-09-19" });
 
 ### 跨表引用：Lookup（宿主已支持；勿让用户填编号）
 
-当 Action 参数要引用**同库另一张业务表**的一行（话术模板、平台、账号等）时，必须用 Lookup 下拉，**禁止**做成「请填写编号」的数字框（用户记不住内部 id，体验差）。
+当 Action 参数要引用**一行业务实体**（话术模板、平台、账号等）时，必须用 Lookup 下拉，**禁止**做成「请填写编号」的数字框（用户记不住内部 id，体验差）。
 
-| 场景 | 怎么配 | 说明 |
-|------|--------|------|
-| 当前表已有同含义列，且列上已是 CRUD lookup | `column` / `bind.columnMapping`，或属性名 = 列名 | toolbar/batch 弹窗与 create/update 抽屉都会复用该列已解析的选项 |
-| 当前表没有该列（如在「潜客」表上选「话术模板」） | `display_type: "lookup"` + 字段内联 `lookup` 对象 | 打开表单时宿主按当前技能库解析选项 |
+#### 两种 Lookup 入口（勿混）
 
-内联 `lookup` 与列元数据 `options_json` **同构**（见 [`SCHEMA.md`](SCHEMA.md)「跨表引用 lookup」）：
+| 种类 | 声明位置 | 何时解析 | 允许的数据源 |
+|------|----------|----------|--------------|
+| **列 Lookup** | `_jiangchang_columns.display_type = lookup` + `options_json` 对象 | 拉表 schema 时 | **仅** `local_sql`（同库表） |
+| **Action Lookup** | `inputSchema.properties.*.lookup`（推荐同时 `display_type: lookup`） | **打开动作表单** / 字段因 `visibleWhen` 变为可见时 | `local_sql` / **`skill_cli`** / `external_api`（预留） |
+
+固定小枚举仍用 `options_json` **数组**或 Action `enum`，**不走** Lookup 解析器。
+
+#### Action Lookup 三种 source（匠厂宿主已统一）
+
+| `source` | 何时用 | 核心字段 | 推断（可省略显式 `source`） |
+|----------|--------|----------|------------------------------|
+| `local_sql` | 选项在**本技能库**另一张表 | `ref_table` + `value_column` + `label_column` | 有 `ref_table` |
+| `skill_cli` | 选项在**兄弟/依赖技能**（如 account-manager 账号列表） | `skill` + `command`；可选 `args` / `items_path` / `value_column` / `label_column` | 有 `skill` / `skill_slug` |
+| `external_api` | 第三方 HTTP（预留） | `url`（或 `endpoint`） | 有 `url` / `endpoint` |
+
+**选型：**
+
+| 场景 | 怎么配 |
+|------|--------|
+| 当前表已有同含义列，且列上已是 CRUD lookup | `column` / `bind.columnMapping`，或属性名 = 列名（复用列上已解析的 **local_sql** 选项） |
+| 同库另一张表、当前表没有对应列 | Action 内联 `lookup` → `local_sql`（可只写 `ref_table`…） |
+| 跨技能列表（账号、批次、其它技能业务行） | Action 内联 `lookup` → **`skill_cli`**（`skill` + `command`） |
+| 固定三五个状态 | `enum` / 列 `options_json` 数组，**不要** Lookup |
+
+**反模式（跨技能）：** 在本技能再造一张「账号选项缓存表」再 `local_sql`——选项会过期，定时任务等入口也容易空下拉。应直接 `skill_cli` 调依赖技能。
+
+#### `local_sql`（同库；与列 `options_json` 对象同构）
 
 ```json
 {
@@ -954,29 +1013,124 @@ const data = await jiangchang.call("方法名", { date: "2026-09-19" });
 
 | 字段 | 必填 | 说明 |
 |------|------|------|
-| `ref_table` | 是 | 同库被引用表 |
+| `ref_table` | 是（local_sql） | 同库被引用表 |
 | `value_column` | 是 | 提交给 CLI 的值（业务 id / 编号） |
 | `label_column` | 是 | 主文案列 |
 | `extra_column` | 否 | 第三展示列（任意列名，不限「备注」） |
 | `filter_column` / `filter_value` | 否 | 等值过滤 |
 | `multiple` | 否 | `true` = 多选；省略/`false` = 单选（默认） |
 
-**下拉/选项展示（宿主统一，技能只配列）：** 单选为 `{value} · {label}`；有非空 `extra_column` 时为 `{value} · {label}（{extra}）`。例：`2 · 通用私信-留资`、`2 · 通用私信-留资（dm）`。
+列 Lookup 字段表与加载时机见 [`SCHEMA.md`](SCHEMA.md)「跨表引用 lookup」（**仅 local_sql**）。
+
+#### `skill_cli`（兄弟/依赖技能 CLI）
+
+打开表单时，宿主对声明的技能执行一次 **sync** CLI，从 **stdout JSON** 抽出选项列表（默认路径 `items`）。
+
+```json
+{
+  "accountId": {
+    "type": "string",
+    "title": "发布账号",
+    "description": "不选则由系统自动分配。",
+    "display_type": "lookup",
+    "lookup": {
+      "source": "skill_cli",
+      "skill": "account-manager",
+      "command": "list-json",
+      "args": ["toutiao"],
+      "value_column": "id",
+      "label_column": "account_label"
+    }
+  }
+}
+```
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `skill` / `skill_slug` | 是（二选一） | 兄弟技能 slug |
+| `command` / `cli_command` | 是（二选一） | CLI 子命令（argv 第一段） |
+| `args` | 否 | 追加参数；数组或逗号串 |
+| `value_column` | 否 | 默认 `id` |
+| `label_column` | 否 | 默认 `display_label` |
+| `extra_column` | 否 | 第三展示列 |
+| `items_path` | 否 | JSON 内数组点路径，默认 `items`；若 stdout 本身就是数组可省略 |
+| `multiple` | 否 | 同 local_sql |
+
+**依赖技能侧约定：** 该命令须成功退出并打印可解析 JSON；宿主接受**顶层数组**，或对象内由 `items_path`（默认 `items`）指向的数组。元素须含 value/label 列。具体子命令与字段名以依赖技能文档为准（上例对标 account-manager 遗留 `list-json <platform>`，字段为 `id` / `account_label`；其它技能请核对 stdout）。
+
+**与运行时分流：** 表单选账号用 `skill_cli` Lookup；真正开浏览器 / 占租约仍走本技能 `account_client`（见 [`development/ACCOUNT_MANAGER.md`](../development/ACCOUNT_MANAGER.md)），二者不要混成「表单打开就 pick-web」。
+
+#### 展示、多选与可选空
+
+**下拉/选项展示（宿主统一，技能只配列）：** 单选为 `{value} · {label}`；有非空 `extra_column` 时为 `{value} · {label}（{extra}）`。列表/详情单元格优先 `listLabel`（不带 id 前缀）。例：`2 · 通用私信-留资`。
 
 **多选存值与模板：** Action / CRUD 存 **`TEXT` 逗号分隔 id**（如 `1,2,5`）；`{{engineIds}}` 原样替换进 CLI。多选字段在 `inputSchema` 里用 `type: "string"`（逗号串），不要用尚未稳定的 JSON array 当业务控件。
 
-**多选控件（宿主策略）：** 选项少（建议 ≤6）用勾选列表；选项多用字段内 Chip + 可搜索下拉（不是再开业务弹窗）。
+**多选控件（宿主策略）：** 选项少（建议 ≤6）用勾选列表；选项多用字段内 Chip + 可搜索下拉（不是再开业务弹窗）。需要编号+文案的小表、翻页、本页全选时，用下面的 `paged_table`，不要再做一套控件。
+
+#### 分页勾选小表（`presentation: "paged_table"`）
+
+仍是 **`display_type: "lookup"`**。在已有 `lookup` 上增加 `presentation` 与可选 `page_size`。提交值与 `multiple: true` 相同：**TEXT 逗号分隔 id**。`local_sql` 与 `skill_cli` 都能用。列 Lookup（`_jiangchang_columns`）**不要**声明 `paged_table`。
+
+```json
+{
+  "articleIds": {
+    "type": "string",
+    "title": "选择文章",
+    "description": "勾选要导入的文章。可翻页，可本页全选。",
+    "display_type": "lookup",
+    "lookup": {
+      "source": "skill_cli",
+      "skill": "geo-generate-article-all",
+      "command": "title",
+      "args": ["list-generated-json", "--platform", "toutiaohao"],
+      "value_column": "id",
+      "label_column": "title",
+      "multiple": true,
+      "presentation": "paged_table",
+      "page_size": 10
+    }
+  }
+}
+```
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `presentation` | 用小表时必填 | 只认 `"paged_table"`。省略或 `"select"` = 现有下拉 / 勾选 / Chip |
+| `page_size` | 否 | 每页条数，默认 10，限制 1–100 |
+| `multiple` | 建议 `true` | 小表按多选提交；一个都不勾时把字段放进 `required`，宿主拒绝空提交 |
+
+**`skill_cli` 分页：** 宿主在 argv 后追加 `--page`、`--limit`。stdout **只有一行 JSON 对象**：`{"items":[{"id":"1","title":"标题"}],"total":42}`。`total` 是过滤后的总条数，不是本页条数。命令可以自己切片；若一次返回全量且带 `total`，宿主也会按页切开。
+
+**空列表：** 分页小表把 `{"items":[],"total":0}` 且退出码 0 当成成功，界面显示「暂无可选项」。普通下拉 Lookup 仍把 0 条当成命令失败。不要为「没有数据」退出码 1，也不要往 stdout 打日志。
+
+**同库过滤只有一列：** `local_sql` 的 `filter_column` / `filter_value` 只支持一个等值条件。要「已启用并且提示词齐全」这类两个条件，用一条只读 `skill_cli`，或先做成同库视图再 `local_sql`。同库、一个条件就能列出来的，优先 `local_sql`（打开即查库）。`skill_cli` 每次打开和翻页都会再起进程。
+
+**只读列表命令要轻：** 供这张表调用的命令，在 `scripts/main.py` 分到该命令之前，不要 `import jiangchang_skill_core` 整包（包初始化会带上授权客户端），也不要导入 Playwright / 发布栈。0 条也打印空 `items` 后退出码 0。健康检查、真正执行任务仍走 `cli/app.py` 的 `setup_skill_logging`，不要把那条路径拆掉。
+
+**反模式（在上一节之外再加）：**
+
+- 新造 `display_type: "paged_lookup"` 或另一套分页控件（应只加 `lookup.presentation`）
+- 列表命令在模块顶导入浏览器 / RPA / 整包 platform-kit，打开小表要等数秒
+- 没有数据时让命令失败，小表里出现英文报错而不是「暂无可选项」
+- 用两个 `filter_column` 表达 AND（宿主只认一个等值过滤）
+
+形状参考：[`assets/examples/lookup-paged-table.action.example.json`](../assets/examples/lookup-paged-table.action.example.json)。
 
 **可选「自动」（单选常见）：** 字段不要放进 `required`；不要用 `minimum: 1` 卡死留空。宿主会省略空的可选数字参数，避免「提交的数据无效」。
 
+**解析失败：** 单字段 Lookup 失败时该字段选项为空，表单仍可开（可留空提交的场景不受阻）。
+
 **反模式（勿做）：**
 
 - 标题写成「某某编号」，说明里教用户去左侧表抄 id
 - 用静态 `enum` 罗列会增长/变更的业务行（会过期）
 - 在技能里自己拼假 label 列代替宿主统一格式（难维护）
-- 另造 `lookup_multi` / 第二套 display_type（应只加 `multiple: true`）
+- 另造 `lookup_multi` / `paged_lookup` / 第二套 display_type（多选只加 `multiple: true`；小表只加 `presentation: "paged_table"`）
+- 为跨技能列表在本库维护镜像缓存表再 `local_sql`（应用 `skill_cli`）
+- 在列 `options_json` 上声明 `skill_cli`（列 Lookup **只**支持同库）
 
-形状参考：[`assets/examples/lookup-action.example.json`](../assets/examples/lookup-action.example.json)。
+形状参考：[`assets/examples/lookup-action.example.json`](../assets/examples/lookup-action.example.json)、[`assets/examples/lookup-skill-cli.action.example.json`](../assets/examples/lookup-skill-cli.action.example.json)、[`assets/examples/lookup-paged-table.action.example.json`](../assets/examples/lookup-paged-table.action.example.json)。
 
 ### 表单字段类型对照（须与 CRUD 对称）
 
@@ -989,8 +1143,8 @@ Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件
 | JSON 长文本 | `type: object`/`array`（以 JSON 字符串编辑）或 `textarea` | `display_type: json` / `textarea` |
 | 数字 | `type: number` | `display_type: number` 或 INT/REAL/NUMERIC |
 | 开关 | `type: boolean` | `display_type: boolean` |
-| 枚举下拉 | `enum: [...]` | `options_json` 数组 |
-| 关联下拉（Lookup） | 内联 `display_type: lookup` + `lookup`（可选 `multiple`），或绑列 | 同左；多选存 `TEXT` 逗号分隔 id |
+| 枚举下拉 | `enum: [...]` + 可选 **`enumNames`**；有对应列时再加 `column` / 属性名对齐，复用列 `options_json` | `options_json` **数组** `{value,label}` |
+| 关联下拉（Lookup） | 内联 `display_type: lookup` + `lookup`（`local_sql` / `skill_cli` / `external_api`；可选 `multiple`；可选 `presentation: "paged_table"`），或绑列 | 列侧仅同库 `local_sql`；多选存 `TEXT` 逗号分隔 id；分页小表只在 Action |
 | 密码 | `sensitive: true` | 列 `sensitive` |
 | 年份 | `display_type` 或 `format`: `year` | `display_type: year` → 存 `YYYY` |
 | 年月 | `display_type` 或 `format`: `year_month`（别名 `month`） | `display_type: year_month` → 存 `YYYY-MM` |
@@ -1008,8 +1162,35 @@ Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件
 | **列筛选「值」** | **无对称**（Action 无表格筛选） | 见 [`SCHEMA.md`](SCHEMA.md)「数据管理：列筛选与全局搜索」：枚举 / boolean / lookup 在筛选栏用**下拉 Select**（非开关、非分段单选）；存库仍用 value，展示与搜索认 label |
 
 **本版不做（勿宣传）：** 浏览器内文件上传控件、复杂 `oneOf` / nested object 专用表单；`visibleWhen` 多条件 AND/OR 树、跨 Action 依赖、CRUD 新增/编辑对称显隐；Action 参数表单的列筛选对称。  
-（**Lookup 多选**已支持：同一 `lookup` + `multiple: true`，见上文；不是任意标签数组。）  
-（**本地路径选择**已支持：`file` / `directory` + 可选 `pathRoot`，见下节；提交值仍是本机绝对路径字符串，不是 multipart 上传。）
+（**Lookup 多选**已支持：同一 `lookup` + `multiple: true`，见上文；不是任意标签数组。**分页勾选小表**已支持：同一 `lookup` + `presentation: "paged_table"`，见「分页勾选小表」。）  
+（**本地路径选择**已支持：`file` / `directory` + 可选 `pathRoot`，见下节；提交值仍是本机绝对路径字符串，不是 multipart 上传。）  
+（**静态枚举中文 label**已支持：Action `enumNames` 与列 `options_json` 数组对称，见下节「静态枚举 label」。）
+
+### 静态枚举 label（`enum` / `enumNames` / 绑列）
+
+固定小枚举（状态、船司代码、优先级等）**不要**走 Lookup。CRUD 用列 `options_json` 数组；Action 表单要与「新增记录」对齐中文展示时，按下面做。
+
+**宿主解析优先序（高 → 低）：**
+
+1. **绑列 options**：字段通过 `column` / `columnMapping` / 属性名（含 camelCase→snake_case）对齐到当前表列，且该列已有解析后的 `options`（来自 `options_json` 数组或 lookup）→ 用列上的 `{value,label}`。
+2. **`enumNames`**：与 `enum` 下标一一对应的展示文案；缺项或空串回退为该位 `enum` 原文。
+3. **纯 `enum`**：无 label 时宿主只能显示代码值（体验差，新技能避免）。
+
+```json
+"carrierCode": {
+  "type": "string",
+  "title": "船司",
+  "column": "carrier_code",
+  "enum": ["maersk", "hmm"],
+  "enumNames": ["MAERSK 马士基", "HMM 现代商船"]
+}
+```
+
+推荐：
+
+- 表上已有同义枚举列 → **显式 `column`**（或属性名 = 列名）+ 列侧写好 `options_json`；`enum`/`enumNames` 可保留作无列上下文时的兜底（如 agent-only Action）。
+- 无对应列、仅 Action 表单需要 → 只写 `enum` + `enumNames`（见 [`assets/examples/enum-names-action.example.json`](../assets/examples/enum-names-action.example.json)）。
+- **禁止**为了中文展示把固定枚举改成假 Lookup。
 
 日期时间约定：
 
@@ -1083,7 +1264,8 @@ Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件
 ### 当前宿主稳定支持（摘要）
 
 - 根：`object`；属性：`string` / `number` / `boolean`（`object`/`array` 仅作 JSON 多行编辑兼容，新技能慎用）
-- `enum` / `default` / `required` / `sensitive` / `readOnly` / 可选 `revealInForm`
+- `enum` / 可选 **`enumNames`** / `default` / `required` / `sensitive` / `readOnly` / 可选 `revealInForm`
+- 可选 **`column`**：绑列复用 displayName 与 options（静态枚举或 lookup）
 - `display_type` / `format`：`textarea` | **`year`** | **`year_month`** / `month` | `date` | `datetime_unix_seconds` | `url` | `email` | **`lookup`** | **`file`** | **`directory`**
 - 可选 **`pathRoot`**（仅 `file` / `directory`）：相对技能数据根的起始目录；省略默认 `{skill_data}/input`
 - 字段内联 `lookup`（与 CRUD `options_json` lookup 对象同构；可选 `extra_column`、`multiple`）
@@ -1097,8 +1279,10 @@ Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件
 
 用于「先选模式，再出对应参数」类表单。写在 `inputSchema.properties.<field>` 上（**不是** action 顶层字段）。
 
-> **消歧义：** 本文的 `visibleWhen` = **Action 参数表单控件显隐**。  
-> [`POLICY.md`](POLICY.md) L3 预留的 `visibleWhen` = **行态/权限策略**（未冻结），**不是**同一能力。勿混用、勿互相替代。
+> **消歧义：**  
+> - **表单** `inputSchema.properties.*.visibleWhen` = Action **参数控件**显隐。  
+> - **`bind.visibleWhen`** = 数据管理 **行菜单 / 行按钮**显隐（见上文「行菜单显隐」）。  
+> - [`POLICY.md`](POLICY.md) L3 预留的行态 `visibleWhen` = **权限策略**（未冻结），**不是**以上二者。勿混用、勿互相替代。
 
 ```json
 "keyword": {
@@ -1206,12 +1390,12 @@ CRUD 侧宿主义务与禁止事项见 [`SCHEMA.md`](SCHEMA.md)「表单与展
 
 若还需要默认篇数，可在同一 `properties` 里为 `pickCount` 增加 `"default": 1`、`"minimum": 1`。
 
-与 **`bind.selectionMode: "optional"`** 联用时：无勾选弹层展示 `pickCount`；有勾选则隐藏 `pickCount`、提交 `$selection.ids`。不要再拆第二个「只 pick / 只勾选」toolbar 按钮。见上文「勾选驱动模式」。
+与 **`bind.selectionMode: "optional"`** 联用时：无勾选弹层展示 `pickCount`；有勾选则隐藏 `pickCount`、提交 `$selection.ids`。定时任务配置页同无勾选分支（不展示空「编号列表」）。不要再拆第二个「只 pick / 只勾选」toolbar / cron 按钮。见上文「勾选驱动模式」。
 
 约定：
 
 - `boolean` 在宿主中渲染为开关
-- `enum` 在宿主中渲染为选择框
+- `enum` 在宿主中渲染为选择框（或短列表分段控件）；**展示文案**优先绑列 options，其次 `enumNames`，再次纯 `enum` 值
 - `type: number` 渲染为数字输入
 - `display_type`/`format: year` 渲染为年份选择；`year_month` / `month` 渲染为年月选择
 - `display_type`/`format: date` 渲染为日期（日）；`datetime_unix_seconds` 渲染为日期时间并按 **Unix 秒**提交

references/CLI.md

@@ -44,7 +44,7 @@ python {baseDir}/scripts/main.py init-db
 - **`health`**：只读 runtime 诊断，**不下载、不修复 media-assets，不执行业务动作**；不输出敏感值。
 - **`config-path`**：输出 JSON，包含 `skill`、`env_path`、`example_path`。
 - **`version`**：输出 JSON（`version`、`skill`）。
-- **`init-db`**：幂等创建/迁移本地 SQLite（含 `_jiangchang_*` 展示元数据）。成功输出一行 JSON（`ok` / `skill` / `db_path`），退出码 `0`。宿主可在技能安装或更新成功后静默调用；不要并入 `health`。
+- **`init-db`**：幂等创建/迁移当前 active 后端（默认本地 SQLite；配 `MYSQL_DSN` 时为 MySQL 云库，见 `references/DATA_SOURCES.md`），含 `_jiangchang_*` 展示元数据。成功输出一行 JSON（`ok` / `skill` / `db_path` 或等价字段），退出码 `0`。宿主可在技能安装或更新成功后静默调用；不要并入 `health`。
 - **`policy`（可选）**：仅当 `actions.json` 顶层启用 Data Policy 时需要；向 stdout 输出 Snapshot JSON（见 `references/POLICY.md`）。模板默认不实现；多数技能保持 L0 即可。
 - **`run` / RPA / 长任务**：CLI 仍是同一内核；**Agent 禁止**用 bash 干等长任务结束。须走宿主 Skill Action（`run_skill_action`），且该 Action 一般为 `executionProfile: "async"` → **任务中心**。长时间无 stdout **不代表卡死**；进度看任务中心 / Run Journal。
 - **排查顺序**（由快到慢）：

references/DATA_SOURCES.md

@@ -0,0 +1,139 @@
+# 多数据源声明（SQLite / MySQL 云库）
+
+本文说明技能如何向匠厂宿主**声明**业务数据库，以及技能 CLI / Action 如何与宿主读写**同一物理库**。
+
+**产品定位：** 默认仍是本地 SQLite（`{skill_slug}.db`）。需要多用户共享、集中运维或云库时，可显式声明 **MySQL**。UI / API 契约不变；`_jiangchang_*` 展示元数据仍写在同一逻辑库中。
+
+**宿主版本：** 匠厂 Host **≥ 6.9.28** 才支持 `data-sources.json` 与 MySQL 连接器。
+
+**完整参考实现：** [`process-work-order`](https://git.jc2009.com/client-commons/process-work-order) @ v1.0.2（工单管理 + MySQL 云库试点）。
+
+---
+
+## 何时用哪种后端
+
+| 场景 | 推荐 |
+|------|------|
+| 单机、离线、小数据量、便携部署 | **SQLite**（默认，不配声明文件亦可） |
+| 多用户共享、运维集中管库、与外部系统共库 | **MySQL 云库**（显式 opt-in） |
+
+**硬规则：一个 `sourceId` 对应一个物理库。** 禁止双写、禁止 SQLite 与 MySQL 同步镜像。
+
+---
+
+## 文件位置
+
+均在**用户数据目录**（不是安装包目录）：
+
+```
+{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/{skill_slug}/
+├── data-sources.json      # 声明式数据源（可选；见下）
+├── .env                   # MYSQL_DSN 等连接配置
+└── {skill_slug}.db        # SQLite 模式下的本地库文件
+```
+
+安装/升级时，若用户目录尚无 `data-sources.json` 且技能包内有 `assets/data-sources.example.json`，宿主会**复制一次**示例（不覆盖已有文件）。
+
+模板默认示例为 **SQLite 显式声明**（与自动扫描 `{skill_slug}.db` 等价）。改走 MySQL 时，请参照 `assets/examples/data-sources.mysql.example.json` 手工替换用户目录中的 `data-sources.json`，并在 `.env` 配置 DSN。
+
+若不需要声明式接入，可删除用户目录中的 `data-sources.json`，宿主恢复自动扫描 `.db` 文件。
+
+---
+
+## `data-sources.json` 格式
+
+根对象：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `version` | `1` | 固定为 1 |
+| `sources` | 数组 | 至少一条数据源 |
+
+每条 `sources[]`：
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `id` | 是 | 英文标识，如 `primary` |
+| `kind` | 是 | `sqlite` 或 `mysql` |
+| `displayName` | 否 | 侧栏展示名；多库时建议填写 |
+| `path` | sqlite 必填 | 相对技能数据目录的路径；可用 `{skillSlug}` 占位 |
+| `connectionEnv` | mysql 必填 | `.env` 中 DSN 的环境变量名，如 `MYSQL_DSN` |
+
+### SQLite 示例（模板默认）
+
+见 [`../assets/data-sources.example.json`](../assets/data-sources.example.json)。
+
+### MySQL 示例
+
+见 [`../assets/examples/data-sources.mysql.example.json`](../assets/examples/data-sources.mysql.example.json)。
+
+---
+
+## `.env` 与 DSN
+
+MySQL 连接串写在用户 `.env`（或进程环境变量），**不要**写进 `data-sources.json`：
+
+```env
+# MySQL 云库连接（不配则走本地 SQLite）
+MYSQL_DSN=mysql://user:password@192.168.0.20:3306/your_database
+```
+
+格式：`mysql://` 或 `mysql2://`，须含库名。注释写法须符合 [`../development/CONFIG.md`](../development/CONFIG.md)（配置管理会展示给用户）。
+
+技能 Python 侧：`scripts/db/backend.py` 读取同一 `MYSQL_DSN`；有值则 `resolve_backend()` 为 `mysql`，否则 `sqlite`。
+
+---
+
+## 技能代码职责
+
+### 宿主 UI（数据管理）
+
+宿主读取用户目录 `data-sources.json` + `.env`，经 Host 内置连接器访问库。**不依赖**技能 `connection.py`。
+
+### CLI / Action / `init-db`
+
+**必须**与宿主使用同一后端策略，否则会出现「UI 看云库、CLI 写本地 `.db`」的分裂。
+
+模板已提供：
+
+| 模块 | 作用 |
+|------|------|
+| `scripts/db/backend.py` | `resolve_backend()`、`parse_mysql_dsn()` |
+| `scripts/db/cursor_compat.py` | 统一 `?` 占位符与 `executescript` |
+| `scripts/db/connection.py` | `get_conn()` 双分支；`init_db()` 幂等建 `_jiangchang_*` |
+
+业务表 DDL / 迁移仍在技能自己的 `schema` / `init_db()` 中按 `conn.backend` 分支处理（见工单参考实现）。
+
+可选：`describe_active_store()` 用于 health / 排障，输出当前连的是 sqlite 还是 mysql。
+
+---
+
+## MySQL 当前限制（Host）
+
+- 不支持 `tableAdmin`（建表/改表 UI）
+- 不支持 `cellPresentation`
+- 元数据与 CRUD 与 SQLite 路径一致
+
+表结构变更仍由技能 `init-db` / 迁移脚本负责。
+
+---
+
+## 开发 Checklist（云库）
+
+复制新业务技能并选择 MySQL 时：
+
+1. Host ≥ 6.9.28
+2. 用户目录放置 `data-sources.json`（mysql 源 + `connectionEnv`）
+3. `.env` 配置 `MYSQL_DSN`（或你在 json 里声明的 env 名）
+4. `requirements.txt` 含 `PyMySQL>=1.1.0`（模板已声明）
+5. 业务 DDL 同时支持 sqlite / mysql 分支（或仅部署 mysql）
+6. **抽测**：数据管理 UI 与 CLI（如 list / create）读写同一库
+7. 见 [`../development/CHECKLIST.md`](../development/CHECKLIST.md) A6-16
+
+---
+
+## 与 SCHEMA / ACTIONS 的关系
+
+- [`SCHEMA.md`](SCHEMA.md)：`_jiangchang_*` 契约适用于**已注册数据源**上的表，不限于本地文件。
+- [`ACTIONS.md`](ACTIONS.md)：无 `replaces` 时宿主直写**已注册数据源**（默认本地 SQLite）。
+- [`CLI.md`](CLI.md)：`init-db` 对当前 active backend 幂等初始化元数据。

references/POLICY.md

@@ -2,8 +2,10 @@
 
 > **状态：正式契约 v1.0（`schemaVersion` 1）。**  
 > **目标：** 冻结「启用方式 + Snapshot 最小字段 + L2 scope 白名单」，使多数技能（L0）零配置，需要权限的技能（L1/L2）有稳定扩展面。  
-> **非目标：** 宿主实现业务用户/角色库；规定飞书/HTTP/本地表等权限数据源；本期不强制 L3（行态 `visibleWhen` 等）。  
-> **注意：** L3 预留的行态 `visibleWhen` **不是** Action 参数表单的 `inputSchema.properties.*.visibleWhen`（表单控件显隐，见 [`ACTIONS.md`](ACTIONS.md)「字段条件显隐」）。二者同名不同义，勿混用。  
+> **非目标：** 宿主实现业务用户/角色库；规定飞书/HTTP/本地表等权限数据源；本期不强制 L3（菜单级藏表、`rows.mode=delegate` 等）。  
+> **注意：**  
+> - 行菜单按业务状态显隐请用 Action 契约 **`bind.visibleWhen`**（见 [`ACTIONS.md`](ACTIONS.md)「行菜单显隐」）——宿主已支持，**不属于**本 Policy L3。  
+> - L3 预留的行态 `visibleWhen` **不是** Action 参数表单的 `inputSchema.properties.*.visibleWhen`，也**不是** `bind.visibleWhen`。三者同名不同义，勿混用。  
 > **配套 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（当前身份允许什么）**。
@@ -17,7 +19,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` 等（≠ Action 表单 `inputSchema.visibleWhen`） |
+| **L3** | （预留，本契约不冻结行为） | 如菜单级藏表、`rows.mode=delegate`、更复杂的行态策略字段等（≠ `bind.visibleWhen` 行菜单，≠ 表单 `inputSchema.visibleWhen`） |
 
 **80% 技能停留 L0。** 启用 policy 的技能必须实现约定 CLI，并在写路径自行再鉴权（见 §7）。
 

references/README.md

@@ -18,10 +18,11 @@
 | [`SKILL.md`](../SKILL.md) | LLM / OpenClaw 平台技能入口与触发摘要 |
 | [`CLI.md`](CLI.md) | 共享 Python、命令行入口、参数与短操作契约 |
 | [`ACTIONS.md`](ACTIONS.md) | Skill Action、sync/async、任务中心、多入口、按钮中文名 `label` 参考（按入口定位表挂载；先读 `development/PRODUCT_SURFACES.md`） |
-| [`SCHEMA.md`](SCHEMA.md) | 本地 SQLite 与数据管理展示契约 |
+| [`SCHEMA.md`](SCHEMA.md) | 业务表与数据管理展示契约（SQLite / MySQL） |
+| [`DATA_SOURCES.md`](DATA_SOURCES.md) | 多数据源声明：SQLite 默认、可选 MySQL 云库（Host ≥ 6.9.28） |
 | [`POLICY.md`](POLICY.md) | Data Policy：可选身份授权、Snapshot、行 scope（多数技能 L0 不配） |
 | [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md) | 数据管理呈现：格子 / 整行 / 整列 / 区域语义 tone（用途不限；多数技能 P0 不配） |
 | [`WORK_ITEM_STATUS.md`](WORK_ITEM_STATUS.md) | 业务行生命周期：处理队列的可操作/进行中/终态角色与重做规则（有处理行 Action 时适用） |
 | [`../development/`](../development/) | 开发、测试、RPA 深度规范（给人 / 编码助手） |
 
-按需阅读：短操作优先 `CLI.md`；Action / 任务中心读 `ACTIONS.md`；结构化字段读 `SCHEMA.md`；权限 opt-in 读 `POLICY.md`；格子/行/列标色读 `CELL_PRESENTATION.md`；队列处理状态机读 `WORK_ITEM_STATUS.md`。
+按需阅读：短操作优先 `CLI.md`；Action / 任务中心读 `ACTIONS.md`；结构化字段读 `SCHEMA.md`；云库 / 声明式数据源读 `DATA_SOURCES.md`；权限 opt-in 读 `POLICY.md`；格子/行/列标色读 `CELL_PRESENTATION.md`；队列处理状态机读 `WORK_ITEM_STATUS.md`。

references/SCHEMA.md

@@ -1,6 +1,6 @@
 # 数据存储与数据管理展示规范
 
-本文是 skill 本地 SQLite 与匠厂宿主「数据管理」页面展示契约的**权威说明**。
+本文是 skill **已注册数据源**（默认本地 SQLite 文件；可选 MySQL 云库，见 [`DATA_SOURCES.md`](DATA_SOURCES.md)）与匠厂宿主「数据管理」页面展示契约的**权威说明**。
 
 **产品定位：** 数据管理既是业务数据与过程的可见面，也是与对话**平级**的 **UI 执行面**（表上 Action 走同一 CLI 闭环）。何时挂执行入口见 [`../development/PRODUCT_SURFACES.md`](../development/PRODUCT_SURFACES.md)；本文管表结构与展示元数据。
 
@@ -10,7 +10,7 @@
 
 ### 技能负责
 
-- 定义真实 SQLite 表结构
+- 定义真实业务表结构（SQLite 或 MySQL，按技能所选后端）
 - 使用英文 `snake_case` 表名和字段名
 - 使用 `_jiangchang_tables` 提供表级展示元数据
 - 使用 `_jiangchang_columns` 提供字段级展示元数据（含可选 `description` 表单说明、可选 `grid_help` 表格说明）
@@ -37,6 +37,7 @@
 - 不根据具体技能名称写特殊逻辑
 - 可在技能安装/更新成功后静默调用 `python scripts/main.py init-db` 做幂等 ensure（内部即 `init_db()`）；失败不影响安装结果
 - 若技能启用了单元格呈现（见 [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md)），读取旁路呈现数据并为格子 / 行 / 列 / 区域映射语义样式（`tone`）；不猜测业务规则；整行色只涂表格行，不铺到详情字段
+- **导入模板下拉（宿主能力）**：下载「Excel 模板」时，宿主按本表可导入列的元数据自动加 Excel 数据有效性下拉——凡列已有可选集合（`options_json` 静态枚举、schema 已解析的 lookup 选项、未写 options 的 `boolean` 默认「是/否」等）即加下拉；无选项的列仍为自由文本。下拉展示 **label**；导入写库时宿主（或 `replaces: import` 技能）再 **label → value**。CSV 模板**不能**带下拉，可选值仍写在导入弹窗「可导入字段说明」与 Excel「填写说明」页。技能**无需**自备带下拉的模板文件；把字段选项声明在 `_jiangchang_columns` 即可让所有技能受益。宿主不按技能名写死「只支持某几种业务字段」。
 
 ## 初始化入口
 
@@ -621,7 +622,7 @@ readonly = 0
 
 | 层级 | 值 | 说明 |
 |------|-----|------|
-| 表级 `readonly` | `1` | 宿主数据管理只读展示，不提供新增/编辑/删除表单 |
+| 表级 `readonly` | `1` | 宿主数据管理只读展示，不提供新增/编辑/导入与直写删除；若技能声明 `replaces: delete` 仍可显示删除并走 CLI |
 | 相关业务字段 `editable` | `0` | 元数据权限只约束宿主 UI，不限制技能代码写库 |
 
 模板**默认不建**此类审计表。过程看 `jiangchang.log`，进度/终态看任务中心，业务结果看业务表。
@@ -671,7 +672,7 @@ CREATE TABLE demo_items (
 
 ## 枚举字段 options_json
 
-`options_json` 支持两种形态：
+`options_json` 支持两种形态。正确声明后，数据管理「新增/编辑」下拉、列筛选、**以及 Excel 导入模板下拉**共用同一套选项（见上文「宿主负责」中的导入模板下拉）。
 
 ### 1）静态枚举（数组）
 
@@ -687,6 +688,8 @@ CREATE TABLE demo_items (
 
 宿主据此渲染选择框；技能侧负责保证 JSON 合法且与物理字段取值一致。
 
+**与 Action 表单对称：** 数据管理「新增/编辑」读列 `options_json`；Skill Action 弹窗用 `enum` + 可选 **`enumNames`**，或字段绑列（`column` / 属性名对齐）直接复用本列 options。宿主优先序：**绑列 options → enumNames → 纯 enum**。详见 [`ACTIONS.md`](ACTIONS.md)「静态枚举 label」。固定小枚举**不要**改成 Lookup。
+
 ### 2）跨表引用 lookup（对象，用于关联 id 字段）
 
 当字段取值依赖同库另一张业务表时，`display_type` 设为 `lookup`，`options_json` 写对象（**不是**数组）。这是**展示与表单选择**契约，**不是** SQLite 外键。
@@ -728,6 +731,8 @@ CREATE TABLE demo_items (
 
 宿主在加载表 schema 时查询 `ref_table`，把结果展开成 `{value,label}` 选项列表。
 
+> **列 Lookup 仅支持同库 `local_sql`。** Action 表单若要从兄弟技能拉选项（如 account-manager 账号列表），须在 `actions.json` 的 `inputSchema.lookup` 使用 **`skill_cli`**，见 [`ACTIONS.md`](ACTIONS.md)「跨表引用：Lookup」。不要在列 `options_json` 上声明 `skill` / `command`。
+
 **存库约定：**
 
 | 模式 | 物理列建议 | 存什么 |
@@ -748,8 +753,9 @@ CREATE TABLE demo_items (
 - 单选：下拉 Select（现状）
 - 多选且选项较少（建议 ≤6）：勾选列表
 - 多选且选项较多：字段内 Chip + 可搜索下拉（**不是**再开一层业务弹窗）
+- **分页勾选小表**（`lookup.presentation: "paged_table"`）只属于 **Action** 参数表单，列 Lookup 不声明。见 [`ACTIONS.md`](ACTIONS.md)「分页勾选小表」
 
-Action 弹窗内联 Lookup 与上表 **同构**（字段名一致，含 `multiple`），见 [`ACTIONS.md`](ACTIONS.md)「跨表引用：Lookup」。
+Action 弹窗内联 Lookup 与上表 **同构**（字段名一致，含 `multiple`；Action 另可加 `presentation` / `page_size`），见 [`ACTIONS.md`](ACTIONS.md)「跨表引用：Lookup」。
 
 示例：账号表的平台字段 → 平台信息表；凭据表的账号编号 → 账号信息表；私信 Action 选话术 → `message_templates`；抽检 Action 多选引擎 → `engines` + `multiple: true`。
 

requirements.txt

@@ -1 +1,2 @@
 # 公共依赖由宿主共享 runtime 提供；这里只声明技能特有 Python 依赖。
+PyMySQL>=1.1.0

scripts/db/backend.py

@@ -0,0 +1,35 @@
+"""数据库后端选择：配置了 MYSQL_DSN 时走 MySQL，否则回退本地 SQLite。"""
+
+from __future__ import annotations
+
+from typing import Literal
+from urllib.parse import unquote, urlparse
+
+from jiangchang_skill_core import config
+
+DbBackend = Literal["sqlite", "mysql"]
+
+
+def get_mysql_dsn() -> str:
+    return (config.get("MYSQL_DSN") or "").strip()
+
+
+def resolve_backend() -> DbBackend:
+    return "mysql" if get_mysql_dsn() else "sqlite"
+
+
+def parse_mysql_dsn(dsn: str) -> dict[str, object]:
+    text = dsn.strip()
+    if not text.startswith(("mysql://", "mysql2://")):
+        raise ValueError("MYSQL_DSN must be a mysql:// URL.")
+    parsed = urlparse(text)
+    database = (parsed.path or "").lstrip("/")
+    if not database:
+        raise ValueError("MYSQL_DSN must include a database name.")
+    return {
+        "host": parsed.hostname or "127.0.0.1",
+        "port": parsed.port or 3306,
+        "user": unquote(parsed.username or ""),
+        "password": unquote(parsed.password or ""),
+        "database": database,
+    }

scripts/db/connection.py

@@ -1,18 +1,38 @@
-"""SQLite 连接与幂等初始化模板。
+"""SQLite / MySQL 连接与幂等初始化模板。
 
 模板默认只建数据管理元数据表。业务表由复制后的技能自行 CREATE，并同步展示元数据。
+配置了 MYSQL_DSN 时走 MySQL 云库，否则使用本地 {skill_slug}.db。见 references/DATA_SOURCES.md。
 """
 
 from __future__ import annotations
 
 import sqlite3
 
+from db.backend import get_mysql_dsn, parse_mysql_dsn, resolve_backend
+from db.cursor_compat import AdaptedConnection
 from db.display_metadata import init_display_metadata
 from util.runtime_paths import get_db_path
 
 
-def get_conn() -> sqlite3.Connection:
-    return sqlite3.connect(get_db_path())
+def get_conn() -> AdaptedConnection:
+    backend = resolve_backend()
+    if backend == "mysql":
+        import pymysql
+
+        params = parse_mysql_dsn(get_mysql_dsn())
+        raw = pymysql.connect(
+            host=str(params["host"]),
+            port=int(params["port"]),
+            user=str(params["user"]),
+            password=str(params["password"]),
+            database=str(params["database"]),
+            charset="utf8mb4",
+            autocommit=False,
+        )
+        return AdaptedConnection(raw, "mysql")
+
+    raw = sqlite3.connect(get_db_path())
+    return AdaptedConnection(raw, "sqlite")
 
 
 def init_db() -> None:
@@ -23,3 +43,18 @@ def init_db() -> None:
         conn.commit()
     finally:
         conn.close()
+
+
+def describe_active_store() -> dict[str, str]:
+    backend = resolve_backend()
+    if backend == "mysql":
+        params = parse_mysql_dsn(get_mysql_dsn())
+        return {
+            "backend": "mysql",
+            "host": str(params["host"]),
+            "database": str(params["database"]),
+        }
+    return {
+        "backend": "sqlite",
+        "db_path": get_db_path(),
+    }

scripts/db/cursor_compat.py

@@ -0,0 +1,96 @@
+"""统一 SQLite / MySQL 游标：占位符 ? 与 executescript。"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from db.backend import DbBackend
+
+_PLACEHOLDER_RE = re.compile(r"\?")
+
+
+def adapt_sql(sql: str, backend: DbBackend) -> str:
+    if backend != "mysql":
+        return sql
+    return _PLACEHOLDER_RE.sub("%s", sql)
+
+
+def _split_sql_script(script: str) -> list[str]:
+    parts: list[str] = []
+    for chunk in script.split(";"):
+        stmt = chunk.strip()
+        if stmt:
+            parts.append(stmt)
+    return parts
+
+
+class AdaptedCursor:
+    backend: DbBackend
+
+    def __init__(self, cursor: Any, backend: DbBackend) -> None:
+        self._cursor = cursor
+        self.backend = backend
+
+    def execute(self, sql: str, params: tuple[Any, ...] | list[Any] | None = None) -> Any:
+        adapted = adapt_sql(sql, self.backend)
+        if params is None:
+            return self._cursor.execute(adapted)
+        return self._cursor.execute(adapted, params)
+
+    def executemany(self, sql: str, seq_of_params: list[tuple[Any, ...]]) -> Any:
+        return self._cursor.executemany(adapt_sql(sql, self.backend), seq_of_params)
+
+    def fetchone(self) -> Any:
+        return self._cursor.fetchone()
+
+    def fetchall(self) -> list[Any]:
+        return self._cursor.fetchall()
+
+    @property
+    def lastrowid(self) -> int:
+        return int(self._cursor.lastrowid)
+
+    @property
+    def rowcount(self) -> int:
+        return int(self._cursor.rowcount)
+
+    def executescript(self, script: str) -> None:
+        if self.backend == "sqlite":
+            self._cursor.connection.executescript(script)
+            return
+        for stmt in _split_sql_script(script):
+            self.execute(stmt)
+
+
+class AdaptedConnection:
+    backend: DbBackend
+
+    def __init__(self, conn: Any, backend: DbBackend) -> None:
+        self._conn = conn
+        self.backend = backend
+
+    def cursor(self) -> AdaptedCursor:
+        return AdaptedCursor(self._conn.cursor(), self.backend)
+
+    def commit(self) -> None:
+        self._conn.commit()
+
+    def close(self) -> None:
+        self._conn.close()
+
+    def execute(self, sql: str, params: tuple[Any, ...] | list[Any] | None = None) -> Any:
+        cur = self.cursor()
+        return cur.execute(sql, params)
+
+    def executemany(self, sql: str, seq_of_params: list[tuple[Any, ...]]) -> Any:
+        cur = self.cursor()
+        return cur.executemany(sql, seq_of_params)
+
+    def executescript(self, script: str) -> None:
+        if self.backend == "sqlite":
+            self._conn.executescript(script)
+            return
+        cur = self.cursor()
+        for stmt in _split_sql_script(script):
+            cur.execute(stmt)

scripts/util/constants.py

@@ -1,6 +1,6 @@
 """技能标识、版本与平台公共库约束（复制后请修改 slug/version/logger）。"""
 
 SKILL_SLUG = "your-skill-slug"
-SKILL_VERSION = "1.0.116"
+SKILL_VERSION = "1.0.125"
 LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug"
 PLATFORM_KIT_MIN_VERSION = "1.2.11"

tests/test_actions_manifest.py

@@ -74,7 +74,14 @@ def _validate_bind_tables(action_id: str, bind: object) -> list[str]:
     errors: list[str] = []
     if not isinstance(bind, dict):
         return [f"{action_id}: bind must be object"]
-    allowed = {"tables", "inputMapping", "columnMapping", "labelColumn", "selectionMode"}
+    allowed = {
+        "tables",
+        "inputMapping",
+        "columnMapping",
+        "labelColumn",
+        "selectionMode",
+        "visibleWhen",
+    }
     unknown = set(bind.keys()) - allowed
     if unknown:
         errors.append(f"{action_id}: bind only allows {sorted(allowed)}, got {sorted(bind.keys())}")
@@ -103,6 +110,9 @@ def _validate_bind_tables(action_id: str, bind: object) -> list[str]:
         errors.append(
             f"{action_id}: bind.selectionMode must be required|none|optional, got {selection_mode!r}"
         )
+    visible_when = bind.get("visibleWhen")
+    if visible_when is not None and (not isinstance(visible_when, dict) or not visible_when):
+        errors.append(f"{action_id}: bind.visibleWhen must be a non-empty object")
     return errors
 
 
@@ -280,6 +290,29 @@ class TestActionsManifest(unittest.TestCase):
         action_props = schema["$defs"]["action"]["properties"]
         self.assertNotIn("visibleWhen", action_props)
 
+    def test_schema_defines_enum_names_on_input_property(self) -> None:
+        schema = _load_actions_schema()
+        props = schema["$defs"]["inputProperty"]["properties"]
+        self.assertIn("enum", props)
+        self.assertIn("enumNames", props)
+        self.assertEqual(props["enumNames"].get("type"), "array")
+        self.assertEqual(props["enumNames"].get("minItems"), 1)
+        self.assertIn("column", props)
+
+    def test_enum_names_example_exists_and_aligns_labels(self) -> None:
+        path = os.path.join(
+            get_skill_root(), "assets", "examples", "enum-names-action.example.json"
+        )
+        self.assertTrue(os.path.isfile(path), msg="enum-names example must exist")
+        with open(path, encoding="utf-8") as f:
+            example = json.load(f)
+        props = example["actions"][0]["inputSchema"]["properties"]
+        category = props["category"]
+        self.assertEqual(len(category["enum"]), len(category["enumNames"]))
+        self.assertEqual(category.get("column"), "category")
+        priority = props["priority"]
+        self.assertEqual(len(priority["enum"]), len(priority["enumNames"]))
+
     def test_default_manifest_omits_visible_when(self) -> None:
         for action in _load_actions_manifest()["actions"]:
             properties = ((action.get("inputSchema") or {}).get("properties")) or {}
@@ -522,6 +555,51 @@ class TestActionsManifest(unittest.TestCase):
         }
         jsonschema.validate(instance=manifest, schema=schema)
 
+    def test_schema_allows_bind_visible_when(self) -> None:
+        try:
+            import jsonschema
+        except ImportError:
+            self.fail("jsonschema is required")
+        schema = _load_actions_schema()
+        bind_props = schema["$defs"]["bind"]["properties"]
+        self.assertIn("visibleWhen", bind_props)
+        self.assertIn("visibleWhenRule", schema["$defs"])
+        manifest = {
+            "schemaVersion": 1,
+            "skill": "your-skill-slug",
+            "actions": [
+                {
+                    "id": "probe-bind-visible-when",
+                    "label": "采用",
+                    "description": "验证 bind.visibleWhen 可通过 Schema",
+                    "placements": ["row"],
+                    "executionProfile": "sync",
+                    "interaction": "direct",
+                    "bind": {
+                        "tables": ["demo_items"],
+                        "visibleWhen": {
+                            "field": "status",
+                            "in": ["pending_review", "skipped"],
+                        },
+                        "inputMapping": {"itemId": "$row.$pk"},
+                    },
+                    "inputSchema": {
+                        "type": "object",
+                        "required": ["itemId"],
+                        "properties": {
+                            "itemId": {"type": "number", "readOnly": True},
+                        },
+                    },
+                    "entrypoint": {
+                        "type": "cli",
+                        "command": "approve",
+                        "args": ["--id", "{{itemId}}"],
+                    },
+                }
+            ],
+        }
+        jsonschema.validate(instance=manifest, schema=schema)
+
     def test_action_examples_user_facing_copy_avoids_jargon(self) -> None:
         """示例 Action 的用户可见字符串不得含常见开发黑话（属性名本身除外）。"""
         examples_dir = os.path.join(get_skill_root(), "assets", "examples")
@@ -740,11 +818,16 @@ class TestActionsManifest(unittest.TestCase):
             "labelColumn",
             "selectionMode",
             "勾选驱动",
+            "行菜单显隐",
+            "bind.visibleWhen",
             "用户可见文案",
             "双受众",
             "已选择",
             "revealInForm",
             "映射只读",
+            "enumNames",
+            "静态枚举 label",
+            "绑列 options",
         ):
             self.assertIn(marker, text, msg=f"ACTIONS.md missing {marker!r}")
         self.assertNotIn(

tests/test_db_backend.py

@@ -0,0 +1,49 @@
+# -*- coding: utf-8 -*-
+"""数据库后端选择：默认 SQLite，DSN 解析。"""
+from __future__ import annotations
+
+import os
+import unittest
+
+from _support import IsolatedDataRoot
+
+
+class TestDbBackend(unittest.TestCase):
+    def test_resolve_backend_defaults_to_sqlite(self) -> None:
+        with IsolatedDataRoot():
+            from db.backend import resolve_backend
+
+            self.assertEqual(resolve_backend(), "sqlite")
+
+    def test_parse_mysql_dsn(self) -> None:
+        with IsolatedDataRoot():
+            from db.backend import parse_mysql_dsn
+
+            params = parse_mysql_dsn("mysql://root:secret@192.168.0.20:3306/demo_db")
+            self.assertEqual(params["host"], "192.168.0.20")
+            self.assertEqual(params["port"], 3306)
+            self.assertEqual(params["user"], "root")
+            self.assertEqual(params["password"], "secret")
+            self.assertEqual(params["database"], "demo_db")
+
+    def test_resolve_backend_uses_mysql_dsn_from_env(self) -> None:
+        with IsolatedDataRoot():
+            from db.backend import resolve_backend
+
+            os.environ["MYSQL_DSN"] = "mysql://u:p@127.0.0.1:3306/t"
+            try:
+                self.assertEqual(resolve_backend(), "mysql")
+            finally:
+                os.environ.pop("MYSQL_DSN", None)
+
+    def test_describe_active_store_sqlite(self) -> None:
+        with IsolatedDataRoot():
+            from db.connection import describe_active_store
+
+            info = describe_active_store()
+            self.assertEqual(info["backend"], "sqlite")
+            self.assertIn("db_path", info)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_development_policy_guard.py

@@ -39,6 +39,7 @@ POLICY_IDS = (
     "POLICY-RPA-004",
     "POLICY-RPA-005",
     "POLICY-RPA-006",
+    "POLICY-RPA-007",
     "POLICY-PACKAGING-001",
     "POLICY-PACKAGING-002",
     "POLICY-RELEASE-001",
@@ -205,6 +206,26 @@ RPA_006_EXAMPLE_CLIENTS = (
     "examples/simulator_browser_rpa/scripts/service/account_client.py",
 )
 
+RPA_007_SOURCE = (
+    "development/RPA.md §1.2.1; development/RPA_BROWSER.md §4; "
+    "examples/real_browser_rpa; development/POLICY_MATRIX.md"
+)
+RPA_007_DOC_MARKERS = (
+    "no_viewport=True",
+    "viewport=None",
+    "setWindowBounds",
+    "POLICY-RPA-007",
+)
+RPA_007_LAUNCH_MARKERS = RPA_004_LAUNCH_MARKERS
+RPA_007_FORBIDDEN_PATTERNS = (
+    "viewport=None",
+    "setWindowBounds",
+    "maximize_browser_window",
+)
+RPA_007_REAL_BROWSER_SESSION = (
+    "examples/real_browser_rpa/scripts/service/browser_session.py"
+)
+
 LOGGING_001_SOURCE = "development/LOGGING.md; development/RUNTIME.md"
 LOGGING_002_SOURCE = "development/LOGGING.md; development/DEVELOPMENT.md"
 LOGGING_003_SOURCE = "development/LOGGING.md"
@@ -837,6 +858,84 @@ class TestPolicyRpa005(unittest.TestCase):
         )
 
 
+class TestPolicyRpa007(unittest.TestCase):
+    def test_rpa_md_documents_viewport_window_standard(self) -> None:
+        skill_root = get_skill_root()
+        path = os.path.join(skill_root, "development", "RPA.md")
+        text = _read_text(path)
+        missing = [marker for marker in RPA_007_DOC_MARKERS if marker not in text]
+        self.assertEqual(
+            missing,
+            [],
+            msg=_policy_msg(
+                "POLICY-RPA-007",
+                RPA_007_SOURCE,
+                "RPA.md missing viewport/window markers: " + ", ".join(missing),
+            ),
+        )
+
+    def test_real_browser_example_uses_no_viewport(self) -> None:
+        skill_root = get_skill_root()
+        path = os.path.join(skill_root, *RPA_007_REAL_BROWSER_SESSION.split("/"))
+        text = _read_text(path)
+        self.assertIn(
+            "no_viewport=True",
+            text,
+            msg=_policy_msg(
+                "POLICY-RPA-007",
+                RPA_007_SOURCE,
+                f"{RPA_007_REAL_BROWSER_SESSION} must use no_viewport=True",
+            ),
+        )
+        self.assertNotIn(
+            "viewport=None",
+            text,
+            msg=_policy_msg(
+                "POLICY-RPA-007",
+                RPA_007_SOURCE,
+                f"{RPA_007_REAL_BROWSER_SESSION} must not use viewport=None",
+            ),
+        )
+
+    def test_launch_persistent_forbids_bad_viewport_and_cdp_maximize(self) -> None:
+        skill_root = get_skill_root()
+        rel_paths: list[str] = []
+        for root_name in ("scripts", "examples"):
+            root = os.path.join(skill_root, root_name)
+            if not os.path.isdir(root):
+                continue
+            for dirpath, dirnames, filenames in os.walk(root):
+                dirnames[:] = [d for d in dirnames if d not in SKIP_DIR_NAMES]
+                rel_dir = os.path.relpath(dirpath, skill_root).replace("\\", "/")
+                if any(rel_dir == p or rel_dir.startswith(p + "/") for p in SKIP_REL_PREFIXES):
+                    continue
+                for name in filenames:
+                    if not name.endswith(".py"):
+                        continue
+                    rel = os.path.relpath(os.path.join(dirpath, name), skill_root).replace(
+                        "\\", "/"
+                    )
+                    rel_paths.append(rel)
+        violations: list[str] = []
+        for rel in rel_paths:
+            text = _read_text(os.path.join(skill_root, *rel.split("/")))
+            if not any(marker in text for marker in RPA_007_LAUNCH_MARKERS):
+                continue
+            for pattern in RPA_007_FORBIDDEN_PATTERNS:
+                if pattern in text:
+                    violations.append(f"{rel}: forbidden {pattern!r}")
+        self.assertEqual(
+            violations,
+            [],
+            msg=_policy_msg(
+                "POLICY-RPA-007",
+                RPA_007_SOURCE,
+                "launch_persistent files with forbidden viewport/window hacks: "
+                + "; ".join(violations),
+            ),
+        )
+
+
 class TestPolicyRpa006(unittest.TestCase):
     def test_account_manager_lifecycle_doc_has_required_markers(self) -> None:
         skill_root = get_skill_root()

tests/test_docs_standards.py

@@ -385,15 +385,44 @@ class TestDocsStandards(unittest.TestCase):
         ):
             self.assertIn(marker, text, msg=f"SCHEMA.md missing {marker!r}")
 
+    def test_data_sources_md_documents_mysql_and_declaration(self) -> None:
+        text = self._read("references/DATA_SOURCES.md")
+        for marker in (
+            "data-sources.json",
+            "MYSQL_DSN",
+            "6.9.28",
+            "resolve_backend",
+            "一个 `sourceId`",
+            "process-work-order",
+            "tableAdmin",
+        ):
+            self.assertIn(marker, text, msg=f"DATA_SOURCES.md missing {marker!r}")
+        self.assertTrue(os.path.isfile(os.path.join(get_skill_root(), "assets/data-sources.example.json")))
+        self.assertTrue(
+            os.path.isfile(os.path.join(get_skill_root(), "assets/examples/data-sources.mysql.example.json"))
+        )
+        env_example = self._read(".env.example")
+        self.assertIn("MYSQL_DSN", env_example)
+        checklist = self._read("development/CHECKLIST.md")
+        self.assertIn("A6-16", checklist)
+        self.assertIn("DATA_SOURCES.md", checklist)
+
     def test_actions_md_documents_form_schema_split(self) -> None:
         text = self._read("references/ACTIONS.md")
         for marker in (
             "inputSchema 与参数表单",
             "表单字段类型对照（须与 CRUD 对称）",
             "跨表引用：Lookup",
-            "display_type: \"lookup\"",
+            '"display_type": "lookup"',
             "extra_column",
             "multiple",
+            "skill_cli",
+            "paged_table",
+            "page_size",
+            "暂无可选项",
+            "local_sql",
+            "external_api",
+            "items_path",
             "数据管理新增/编辑",
             "_jiangchang_columns.description",
             "datetime_unix_seconds",
@@ -405,6 +434,41 @@ class TestDocsStandards(unittest.TestCase):
             "列筛选",
         ):
             self.assertIn(marker, text, msg=f"ACTIONS.md missing {marker!r}")
+        self.assertTrue(
+            os.path.isfile(
+                os.path.join(get_skill_root(), "assets/examples/lookup-skill-cli.action.example.json")
+            ),
+            msg="lookup-skill-cli.action.example.json missing",
+        )
+        self.assertTrue(
+            os.path.isfile(
+                os.path.join(get_skill_root(), "assets/examples/lookup-paged-table.action.example.json")
+            ),
+            msg="lookup-paged-table.action.example.json missing",
+        )
+        self.assertTrue(
+            os.path.isfile(
+                os.path.join(get_skill_root(), "assets/examples/enum-names-action.example.json")
+            ),
+            msg="enum-names-action.example.json missing",
+        )
+        checklist = self._read("development/CHECKLIST.md")
+        self.assertIn("skill_cli", checklist)
+        self.assertIn("A4-12", checklist)
+        self.assertIn("A4-13", checklist)
+        self.assertIn("enumNames", checklist)
+        self.assertIn("paged_table", checklist)
+        account_mgr = self._read("development/ACCOUNT_MANAGER.md")
+        self.assertIn("skill_cli", account_mgr)
+        schema = self._read("references/SCHEMA.md")
+        self.assertIn("skill_cli", schema)
+        self.assertIn("enumNames", schema)
+        schema_json = self._read("assets/schemas/skill-actions.schema.json")
+        self.assertIn("skill_cli", schema_json)
+        self.assertIn("paged_table", schema_json)
+        self.assertIn("enumNames", schema_json)
+        self.assertIn("page_size", schema_json)
+        self.assertIn('"skill"', schema_json)
 
     def test_actions_md_disambiguates_visible_when_from_policy(self) -> None:
         actions = self._read("references/ACTIONS.md")
@@ -423,6 +487,7 @@ class TestDocsStandards(unittest.TestCase):
     def test_visible_when_example_is_listed(self) -> None:
         text = self._read("assets/examples/README.md")
         self.assertIn("visible-when-action.example.json", text)
+        self.assertIn("bind-visible-when-row.action.example.json", text)
         self.assertIn("selection-mode-optional.action.example.json", text)
         self.assertIn("skill-cell-presentation.example.json", text)
         self.assertIn("skill-grid-presentation.example.json", text)
@@ -433,16 +498,25 @@ class TestDocsStandards(unittest.TestCase):
         self.assertIn("revealInForm", checklist)
         self.assertIn("A4-9", checklist)
         self.assertIn("selectionMode", checklist)
+        self.assertIn("定时任务配置页", checklist)
         self.assertIn("A4-10", checklist)
+        self.assertIn("A4-11", checklist)
+        self.assertIn("bind.visibleWhen", checklist)
         self.assertIn("用户可见文案", checklist)
         runtime = self._read("development/SKILL_ACTION_RUNTIME.md")
         self.assertIn("visibleWhen", runtime)
         self.assertIn("revealInForm", runtime)
         self.assertIn("selectionMode", runtime)
+        self.assertIn("bind.visibleWhen", runtime)
         self.assertIn("用户可见文案", runtime)
+        self.assertIn("无表勾选入口按无勾选分支", runtime)
         actions = self._read("references/ACTIONS.md")
         self.assertIn("用户可见文案", actions)
         self.assertIn("双受众", actions)
+        self.assertIn("行菜单显隐", actions)
+        self.assertIn("bind.visibleWhen", actions)
+        self.assertIn("无表勾选入口", actions)
+        self.assertIn("编号列表", actions)
 
     def test_guarded_docs_do_not_reference_amazon_implementation(self) -> None:
         forbidden = (

tests/test_release_packaging_constraints.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""发布打包守护：PyArmor 单文件行数与 UTF-8 without BOM。"""
+"""发布打包守护：PyArmor Trial 约定、单文件行数与 UTF-8 without BOM。"""
 from __future__ import annotations
 
 import os
@@ -89,6 +89,26 @@ def _iter_scripts_py_files(skill_root: str) -> list[str]:
 
 
 class TestReleasePackagingConstraints(unittest.TestCase):
+    def test_trial_packaging_guidance_is_documented(self) -> None:
+        skill_root = get_skill_root()
+        runtime_path = os.path.join(skill_root, "development", "RUNTIME.md")
+        development_path = os.path.join(skill_root, "development", "DEVELOPMENT.md")
+        with open(runtime_path, encoding="utf-8") as f:
+            runtime = f.read()
+        with open(development_path, encoding="utf-8") as f:
+            development = f.read()
+
+        required_guidance = {
+            "free/trial mode": (runtime + development, "Trial"),
+            "line limit is not sufficient": (runtime + development, "不是 Trial 加密成功的充分条件"),
+            "split the failing module by responsibility": (runtime + development, "按职责"),
+            "preserve compatibility imports": (runtime + development, "兼容门面"),
+            "verify real release encryption": (runtime + development, "实际加密"),
+            "inspect Gitea release result": (runtime + development, "Gitea"),
+        }
+        missing = [label for label, (text, needle) in required_guidance.items() if needle not in text]
+        self.assertEqual(missing, [], msg=f"Missing PyArmor Trial guidance: {missing}")
+
     def test_scripts_py_files_under_pyarmor_line_limit(self) -> None:
         skill_root = get_skill_root()
         offenders: list[str] = []
@@ -104,8 +124,9 @@ class TestReleasePackagingConstraints(unittest.TestCase):
             offenders,
             [],
             msg=(
-                "PyArmor trial/free mode may fail when a single Python file reaches "
-                f"{SCRIPTS_MAX_LINES} lines; split this file into smaller modules. "
+                "PyArmor trial/free mode has a preventive single-file line guard; "
+                "passing it does not guarantee Trial encryption succeeds. Split any "
+                "module identified by the actual Trial release error. "
                 f"Recommended keep each file < {SCRIPTS_RECOMMENDED_MAX_LINES} lines. "
                 f"Offenders: {offenders}"
             ),