沉淀 Lookup 分页勾选小表契约，避免再造一套控件

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

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

.env.example

@@ -1,6 +1,7 @@
 # 运行模式：决定本技能用模拟数据还是真实浏览器/接口去执行
 OPENCLAW_TEST_TARGET=real_rpa          # 可选：mock=本地模拟，simulator_rpa=仿真站点，real_api=真实接口，real_rpa=真实浏览器；模板默认真实浏览器；本地单测/CI 请用 mock
 
+# @required
 # 目标网站地址：技能要访问的网站或服务地址
 TARGET_BASE_URL=https://sandbox.jc2009.com   # 填写完整网址（含 https://）；换环境时再改，一般保持默认即可
 
@@ -52,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,149 @@
 - 小节正文写用户能看懂的变化（新能力、修复、注意事项），避免堆砌内部实现细节
 - 打 tag 前**必须**为即将发布的版本新增一节；找不到匹配小节时，本次发布不会更新 changelog 字段
 
+## 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 均适用
+- 更新 `ACTIONS.md`、`SCHEMA.md`、`skill-actions.schema.json`；新增 `assets/examples/year-month-action.example.json`；`display_metadata.py` 增加 `YEAR` / `YEAR_MONTH` 常量
+
+## 1.0.115
+
+- 沉淀匠厂配置管理必填项契约：`.env.example` 在行头上方用独立一行 `# @required` 声明；宿主显示红色 `*` 并在保存时校验非空
+- 模板示例已为 `TARGET_BASE_URL` 加上示范；新增 `POLICY-CONFIG-005` 门禁错误用法
+
+## 1.0.114
+
+- 技能根目录增加 `sync.ps1`，和 `release.ps1` 并排。在本机把明文同步到已安装的技能目录，用来在宿主里验收
+- 市场上的最新版本和加密包仍走 `release.ps1`。同步后退出资料管理再打开，不要点技能市场的「更新」
+
+## 1.0.113
+
+- 固化数据管理契约：`visible=0` 只藏界面；`default_sort_json` 仍可引用隐藏的非敏感物理列（含主键）
+- 元数据校验：排序列必须真实存在；引用隐藏列仅提示、不报错
+
+## 1.0.112
+
+- 新技能的名字不必再以平台或 `default` 结尾。没有抖音、小红书、亚马逊这类外部平台时，用动词加名词即可
+- 不要再把 `default` 当作占位平台。已经发布、名字末尾是 `default` 的技能不用改名
+
+## 1.0.111
+
+- 沉淀数据管理呈现加法：同一 `cellPresentation.enabled` 支持单元格、整行、整列、行列交叉区域（闭集 tone）
+- 新增 `_jiangchang_grid_presentation` 契约 / Schema / 示例；v1 `cells[]` 保持不变；禁止整表 `all`×`all`；整行色只涂表格、不铺到详情字段
+- 内部隐藏表补上两张呈现旁路表；模板默认仍不启用着色
+
+## 1.0.110
+
+- 数据管理侧栏除了生成出来的 HTML 快照，也会直接显示安装包里 `assets/html/pages/` 的页面，装完就有，不用点生成
+- 这些页面可以调用本技能已经声明的命令：宿主代为执行 Python，把 JSON 交回页面
+
+## 1.0.109
+
+- 沉淀任务中断与账号租约契约：禁止用裸 `except Exception` 吞掉 `JobStopped`；`finally` 先释租约再关浏览器；宿主只通知不代收租约
+- 补充 CHECKLIST A5-13（中断后租约须释放）及 ACCOUNT_MANAGER / LOGGING / ADAPTER / 样例 README
+
+## 1.0.108
+
+- 沉淀数据管理「用户可见文案」契约：弹窗 description / 确认黄条 / 参数说明 / 任务失败 message 须全中文产品用语
+- 明确禁止把字段名、CLI 子命令、async/pending、Agent 禁令写进用户可见文案；Agent 路由仍放 SKILL.md
+- 修正 `selection-mode-optional` 示例为口语文案；更新 ACTIONS / RUNTIME / CHECKLIST A4-10
+
+## 1.0.107
+
+- 沉淀数据管理 `bind.selectionMode` 契约（`required` / `none` / `optional`）：同一按钮可「有勾选走 ids、无勾选走 pickCount」
+- 明确省略时的宿主兼容推断、空选数量字段名约定，以及勿再拆同义双按钮
+- 更新 ACTIONS.md / Schema / SKILL_ACTION_RUNTIME / CHECKLIST A4-9；新增 `selection-mode-optional.action.example.json`
+
+## 1.0.106
+
+- 文档契约：补充可选 `metadata.openclaw.brands`（OEM 市场编码 → `skill_market_relations`）
+- 明确未写则仅挂 `jiangchang`；与 `developer_ids` 分工；勿用 Gitea 组织名推断市场
+- 更新 `SKILL.md`、`DEVELOPMENT.md` §6、`development/README.md`、`REQUIREMENTS.md` 与发布检查清单
+
+## 1.0.105
+
+- 沉淀数据管理 form 与「已选择」摘要对齐契约：映射 `readOnly` 字段默认不占参数区（仍提交），与 confirm 信息架构一致
+- 新增可选 `revealInForm` 逃生阀；明确禁止用 `visibleWhen` 藏映射主键
+- 更新 ACTIONS.md / Schema / SKILL_ACTION_RUNTIME / CHECKLIST A4-8
+
+## 1.0.104
+
+- 新增发布契约 POLICY-RELEASE-001：`release.ps1` 打 tag 前强制校验 Next tag = `SKILL.md` version = `SKILL_VERSION`，避免市场一直显示「更新」
+- 日常测试增加 `SKILL.md` 与 `SKILL_VERSION` 对齐；更新 DEVELOPMENT / POLICY_MATRIX / CHECKLIST A9-4
+
+## 1.0.103
+
+- 用户市场文档：说明/教程正文禁止与宿主页头、Tab 重复的文首一级标题；主分节统一用 `##`
+- 更新 `TUTORIAL.md` / `README.md` 模板骨架、`TUTORIAL_SURFACES.md` §0.1、CHECKLIST A2-12 与契约测试
+
+## 1.0.102
+
+- 沉淀数据管理 Action「已选择」摘要契约：confirm/form 弹层由宿主默认展示勾选对象（#id + 可读标签）；技能零改动即可用
+- 新增可选 `bind.labelColumn`（仅影响展示，不改提交 payload，不决定业务跳过逻辑）
+- 更新 `skill-actions.schema.json`、`ACTIONS.md`、`SKILL_ACTION_RUNTIME.md`；新增 `selection-label-column.action.example.json`
+
+## 1.0.101
+
+- 沉淀 Action 表单本地路径契约：`file` / `directory` 可选 **`pathRoot`**（相对技能数据根的起始目录；省略则宿主默认打开本技能 `input/`）
+- 更新 `skill-actions.schema.json`、`ACTIONS.md`、`DATA_PATHS.md`；新增 `assets/examples/path-root-file-action.example.json`
+- 与宿主导入面板默认 `input/` 划清边界；禁止技能写死用户 ID 或绝对盘符
+
+## 1.0.100
+
+- 沉淀用户市场文档契约 `development/TUTORIAL_SURFACES.md`：**说明 Tab ≠ 教程 Tab**；教程按数据管理 ∥ 对话、定时可选三入口结构
+- 重写根 `README.md` / `TUTORIAL.md` 模板骨架；CHECKLIST 增 A2-7～A2-11；`actions.json` 准备类优先 toolbar、skill-detail 不可作教程主路径
+- 新增 `tests/test_tutorial_surfaces.py`（POLICY-TUTORIAL-001）；REQUIREMENTS §0.1 增教程章节列与用户文档对齐要求
+
+## 1.0.99
+
+- 沉淀数据管理**表注册门禁**契约：存在 `_jiangchang_tables` 时，宿主仅展示注册且 `visible=1` 的表；孤儿物理表不展示（匠厂宿主 ≥6.8.25）
+- 新增「表增删改与退役」：`drop_deprecated_user_table()` 标准迁移；禁止只删元数据留物理表；新技能禁止 `task_logs`
+- `LOGGING.md` 可观测性三分法；`DATA_PATHS.md` 卸载不删用户数据；Checklist A6-13 / A6-14；`tests/samples/test_table_deprecation_migration.py.sample`
+
+## 1.0.98
+
+- 沉淀数据管理**列筛选与全局搜索**契约：`searchable` 同时控制列筛选字段列表与顶栏全局搜索；存库 value / 展示 label 分工；筛选栏枚举/boolean/lookup 用下拉 Select（与表单开关/分段单选区分）
+- 全局搜索：options label 映射、boolean 别名、lookup 多选 token、`datetime_unix_seconds` 日期区间
+- `ACTIONS.md` 表单对照表补充「列筛选」脚注；`CHECKLIST` A6-11 / A6-12；`display_metadata_validator` 对未开 searchable 的枚举/boolean 列软 warning
+
+## 1.0.97
+
+- 沉淀数据管理 HTML 预览**布局契约**：`references/ACTIONS.md` 新增「宿主预览布局」（流体铺满 iframe、禁横向滚动、表格断行等）
+- 升级 `assets/html/example-report.html` 为通用布局基线；`test_html_page_service` 守护不退化
+- `DEVELOPMENT.md` / `CHECKLIST`（S0-12、A6-10）/ `TESTING.md` 交叉引用
+
 ## 1.0.96
 
 - 在 `references/ACTIONS.md` 沉淀数据管理技能按钮中文名（`label`）参考表：同类通用动作用同一动词，不是白名单

DEMO.md

@@ -15,9 +15,13 @@ demo_video_url: ""
 
 ## 建议观看顺序
 
-1. 如何发起一次典型任务
-2. 执行过程中会看到什么提示 / 进度
-3. 成功后的结果长什么样
+建议与 `TUTORIAL.md` 三入口结构对齐（有则拍、无则跳过）：
+
+1. 数据管理：准备数据 → 主流程按钮 → 结果表/报告
+2. 对话任务（若有）：一句自然语言触发同一能力
+3. 定时任务（若有）：到点自动跑；若本技能无定时，演示中可说明「不需要定时」
+
+成功后的结果长什么样（表、任务中心、HTML 等）
 
 ## 没有视频时
 

README.md

@@ -1,14 +1,14 @@
 ---
-description: "用用户能理解的方式说明这个技能能做什么、适合什么场景，以及如何开始使用。"
+description: "用用户能理解的方式说明这个技能能做什么、适合什么场景，以及边界与结果形态。"
 ---
 
 > **模板说明（复制后删除本段）**  
-> 本文是技能市场详情与普通用户说明，**不是** Agent 参考索引、CLI 契约或开发文档。  
-> frontmatter 的 `description` 必须是用户能看懂的一句话能力描述；**不得**写成 CLI、schema、references、development、契约、数据结构、开发规范或 Agent 参考索引。  
-> 正文只回答用户关心的问题，**不要**把 Playwright、DOM、Python、RPA、references、development、schema 等作为面向用户的主说明内容；若业务上必须出现技术词，须用用户能理解的方式解释，且不能喧宾夺主。  
-> **复制后验收章节（标题可微调，建议保留）：**「能帮你做什么」「适合什么场景」「使用前需要准备什么」「你可以这样告诉 Agent」「执行后你会得到什么」「注意事项」「常见问题」。
-
-# 【技能名称】
+> 本文是技能市场 **「说明」** Tab（`readme_md`），**不是**使用教程。  
+> frontmatter 的 `description` 必须是用户能看懂的一句话能力描述；**不得**写成 CLI、schema、references、development、契约或「如何开始使用」类教程承诺。  
+> **禁止**写入：分步操作（1/2/3）、Agent 示例话术块、「入口一/入口二」专章、逐步排障。这些一律写在根目录 `TUTORIAL.md`。  
+> 正文只回答：是什么、能做什么、适合谁、准备什么、得到什么、注意事项。完整契约见 `development/TUTORIAL_SURFACES.md` §1。  
+> **复制后验收章节（标题可微调）：**「能帮你做什么」「适合什么场景」「使用前需要准备什么」「怎么使用」「执行后你会得到什么」「注意事项」「常见问题」。  
+> **标题层级：** 宿主页头已有技能名——**禁止**文首再写 `# 技能名`；正文主分节用 `##`。
 
 > 用一两句话说明这个技能帮助用户完成什么工作。  
 > 这里不要解释技术实现，要从用户的业务目标出发描述价值。
@@ -17,7 +17,7 @@ description: "用用户能理解的方式说明这个技能能做什么、适合
 
 ## 这个技能能帮你做什么
 
-用 3 到 6 条业务能力说明技能价值，例如：
+用 3 到 6 条业务能力说明技能价值（**不要**写成操作步骤），例如：
 
 - 【自动整理/查询/生成/同步/核对/提交】某类业务数据
 - 帮你减少重复操作，降低人工录入或核对成本
@@ -38,42 +38,33 @@ description: "用用户能理解的方式说明这个技能能做什么、适合
 
 ## 使用前需要准备什么
 
-说明用户在使用前要准备的东西，例如：
+说明**前置条件**（装什么、要不要账号、要不要外站登录），**不要**写「去哪张表点哪个按钮」：
 
-- **网页自动化类：** 首次运行可由技能自动登记平台账号（浏览器会话由系统隔离管理）。也可在「账号管理」里指定登录标识。登记账号 ≠ 已登录目标站
-- **账号在哪里看：** 已登记账号可在「数据管理 / 账号管理」中查看；每个账号使用独立浏览器会话，批量或多账号任务不会共用登录状态
-- **是否要登录目标站：** 按本技能说明（有的平台必须登录，有的公开页可不登录）；与「是否有账号记录」不是一回事
+- **网页自动化类：** 可能需要在账号管理中登记平台账号；登记账号 ≠ 已登录目标站（细节见使用教程）
 - 相关业务权限（查询、导出、提交等）已具备
-- 需要处理的文件、时间范围、订单号、客户名称、项目名称等信息
-- 如果涉及验证码或人工确认，请保证能及时在弹出的浏览器窗口中操作
+- 需要处理的文件、时间范围、单号等信息（若适用）
+- 若涉及验证码或人工确认，使用时请能及时在弹出窗口中操作
 
 ---
 
-## 你可以这样告诉 Agent
+## 怎么使用
 
-用自然语言示例展示用户可以怎么发起任务，例如：
+本技能支持哪些宿主入口，用**一两句话**概括即可，例如：
 
-> “帮我查询今天的【业务对象】，整理成表格。”
->
-> “帮我核对这些【数据/单据】是否有异常，并告诉我问题在哪里。”
->
-> “帮我把【时间范围】内的【业务数据】导出并生成处理报告。”
->
-> “帮我根据这个文件里的内容，逐条完成【业务动作】。”
+- 支持 **数据管理**（点表操作）与 **对话任务**（自然语言）；是否提供定时任务按本技能说明。
 
-> 注意：示例应是自然语言，不要写命令行命令。
+**逐步操作、示例话术与排障，请查看技能市场「使用教程」Tab。**  
+（完整写法见 `development/TUTORIAL_SURFACES.md`。）
 
 ---
 
 ## 执行后你会得到什么
 
-说明用户会看到什么结果，例如：
+说明用户会看到什么**结果形态**（不要教如何点出来），例如：
 
 - 任务是否成功完成
-- 处理了多少条数据
-- 哪些内容成功、哪些失败
-- 失败原因和建议处理方式
-- 生成的文件、表格、报告或记录
+- 处理了多少条数据；哪些成功、哪些失败
+- 生成的文件、表格、报告或业务表记录
 
 ---
 
@@ -90,18 +81,16 @@ description: "用用户能理解的方式说明这个技能能做什么、适合
 
 ## 常见问题
 
-### 为什么任务没有查到数据？
+> FAQ 写**概念与边界**；需要「点哪里」的排障写到「使用教程」。
 
-> 可能是时间范围、关键词、账号权限或系统筛选条件不正确。请先确认输入信息是否准确。
+### 这个技能适合我吗？
 
-### 为什么任务执行到一半需要我操作？
+> 若你的场景与上文「适合什么场景」一致，可以安装后按「使用教程」完成第一次操作。
 
-> 可能遇到了登录、验证码、权限确认、二次审批或系统异常。请根据 Agent 的提示完成必要操作。
+### 我不会操作，从哪里开始？
 
-### 结果文件在哪里查看？
-
-> 请根据 Agent 返回的结果说明查看生成文件、任务记录或处理报告。
+> 请打开技能市场 **「使用教程」** Tab，按「入口一：数据管理」或「入口二：对话任务」任选一种跟做。
 
 ### 已经登记的账号在哪里查看？
 
-> 请到匠厂的「数据管理 / 账号管理」查看账号记录和状态。若任务仍提示账号异常，请把账号编号、任务时间和界面提示原文提供给支持人员；不要发送密码、Cookie 或验证码。
+> 请到匠厂的「数据管理 / 账号管理」查看账号记录和状态。不要发送密码、Cookie 或验证码。

SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: 技能开发模板（通用业务版）
 description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。"
-version: 1.0.96
+version: 1.0.121
 author: 深圳匠厂科技有限公司
 metadata:
   openclaw:
@@ -11,6 +11,9 @@ metadata:
     category: "通用"
     developer_ids:
       - 12345  # 占位，请换成你的匠厂用户 ID
+    # brands:                 # 可选；未写则发布后仅挂匠厂市场（jiangchang）
+    #   - jiangchang          # 匠厂主站
+    #   - huashang            # 华商等 OEM：按目标市场填写，可多选
 allowed-tools:
   - bash
 ---
@@ -35,11 +38,14 @@ 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.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）属技能内部，宿主不托管。
-- **`cellPresentation`（可选）**：需要数据管理「某格特殊标色/强调」时启用；技能按当前数据写入呈现（语义 tone），宿主映射主题样式；**未启用 = P0 无标色**。用途不限（超时、预警、驳回等）。详见 `references/CELL_PRESENTATION.md`。
+- **`cellPresentation`（可选）**：需要数据管理「某格 / 整行 / 整列 / 区域」特殊标色时启用；技能按当前数据写入呈现（语义 tone），宿主映射主题样式；**未启用 = P0 无标色**。用途不限（超时、预警、驳回等）。详见 `references/CELL_PRESENTATION.md`。
 - **业务行生命周期（有处理队列时）**：对某一行做生成/触达/私信等处理时，默认只操作「可操作」角色状态；开始抢占「进行中」；结束回写成功或失败（失败带原因）；重做靠人工改回可操作。状态名由本技能自定。详见 `references/WORK_ITEM_STATUS.md`。
-- **同步数据**写技能本地库、不生成导出文件；**导出当前表**由宿主数据管理负责；文件型特殊报告才另做 `export-*`（落 `output/`）；**HTML 整页报告**写 `html/` 并用固定 Action id `render-html`（见 `references/ACTIONS.md`）。
+- **同步数据**写技能本地库、不生成导出文件；**导出当前表**由宿主数据管理负责；文件型特殊报告才另做 `export-*`（落 `output/`）；**HTML**：壳子页放 `assets/html/pages/`，快照写 `html/` 并用固定 Action id `render-html`；页面用 `jiangchang.call` 调已声明命令（见 `references/ACTIONS.md`）。
 - **准备 vs 执行（适用则拆）**：若技能存在「先写入/准备本地数据」与「再对外产生副作用」两段，Agent 必须能分开触发；禁止默认绑成不可拆的一步。一键无准备态的技能可跳过本条。
 
 ### 如何触发（能力类型）
@@ -109,10 +115,11 @@ python {baseDir}/scripts/main.py init-db
 
 **回答「怎么用 / 能做什么」时的要求：**
 
-1. 「能做什么 / 场景 / FAQ」以 `README.md` 为主；「第一次怎么用完」以 `TUTORIAL.md` 为主。
+1. 「能做什么 / 场景 / 概念类 FAQ」以 `README.md`（说明 Tab）为主；「点哪里 / 说什么 / 排障」以 `TUTORIAL.md`（教程 Tab）为主。说明 Tab **不应**含分步操作；若 README 仍有旧式步骤，以教程为准并提示开发者按 `development/TUTORIAL_SURFACES.md` 修正。
 2. **禁止**在回答中粘贴 `python …/scripts/main.py …` 或其它命令行（除非用户明确索要命令，或自称技术人员/开发者）。
 3. **禁止**为答用法而去 `dir` / `ls` / 列技能目录，或默认打开 `references/`、`development/`；仅当用户明确问命令、参数、集成或排错时再读 `references/`。
 4. **不要**向普通用户暴露 Playwright、DOM、Python、RPA、库表名、`error_code` 等实现细节，除非用户明确询问技术实现。
+5. 用户问「怎么用」时：**优先读 `TUTORIAL.md`**；不要只根据 README 臆造按钮路径。
 
 **文档读取边界：**
 
@@ -125,13 +132,13 @@ python {baseDir}/scripts/main.py init-db
 
 | 文档 | 读者 | 用途 |
 |------|------|------|
-| 根目录 `README.md` | 普通用户 | 市场 **说明** Tab（`readme_md`） |
-| 根目录 `TUTORIAL.md` | 普通用户 | 市场 **教程** Tab（`tutorial_md`） |
+| 根目录 `README.md` | 普通用户 | 市场 **说明** Tab（`readme_md`）：能力/场景/边界；**非教程** |
+| 根目录 `TUTORIAL.md` | 普通用户 | 市场 **教程** Tab（`tutorial_md`）：分入口操作；结构见 `development/TUTORIAL_SURFACES.md` |
 | 根目录 `DEMO.md` | 普通用户 | 市场 **演示** Tab（`demo_video_url` + `demo_md`） |
 | 根目录 `CHANGELOG.md` | 普通用户 | 市场 **更新日志** Tab（按版本小节 → `changelog`） |
 | `SKILL.md`（本文） | LLM / OpenClaw 平台 | 技能入口、触发与运行契约摘要 |
 | `references/` | Agent 编排 / 调用 | CLI、Action、schema 契约（Agent 主读） |
-| `development/` | 开发者 / AI 编程代理 | 需求、开发教程、测试、深度技术规范；**产品入口**见 `development/PRODUCT_SURFACES.md` |
+| `development/` | 开发者 / AI 编程代理 | 需求、开发教程、测试、深度技术规范；**产品入口**见 `development/PRODUCT_SURFACES.md`；**用户文档契约**见 `development/TUTORIAL_SURFACES.md` |
 
 ## 目录约定
 
@@ -149,11 +156,11 @@ 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
 
-- 标准格式：`{verb}-{noun-phrase}-{platform}`（详见 `development/NAMING.md`）。
+- 标准格式：`{verb}-{noun-phrase}`，绑定外部平台时才加 `-{platform}`（详见 `development/NAMING.md`）。不要用 `default` 占位。
 - slug / repo / 目录 / `SKILL_SLUG` / DB 文件名：**英文** kebab-case；`name`、`description`、根 `README.md`：**中文**。
 - 复制为新业务技能前**必须**阅读 `development/NAMING.md`。
 - `name`（frontmatter）：**用户可见的中文业务名称**；`description` 是说明，不是名称。
@@ -166,3 +173,9 @@ python {baseDir}/scripts/main.py init-db
 - 开发期技能常为不公开：不加本人 ID，开发者自己也无法在市场安装自测。取 ID 与写入步骤见 `development/DEVELOPMENT.md` §6。
 - 当 `access_scope = 0`（不公开）时，平台会把 `developer_ids` 中的用户自动补写到 `skill_user_access`。
 - `developer_ids` 建议写为正整数数组；第一个 ID 会作为主开发者同步到 `skills.developer_id`。
+- `metadata.openclaw.brands`（**可选**）：OEM 技能市场编码列表，写入平台 `skill_market_relations.market_code`。兼容别名 `oem_clients` / `client_keys`。
+  - **未写或为空**：发布时仅幂等补默认 `jiangchang`（匠厂主站），兼容老技能。
+  - **显式列表**（如 `jiangchang`、`huashang`）：发布时幂等补写对应市场（**只补不删**）；客户端靠 Header `X-Market-Code` 过滤目录。
+  - **不是** Gitea 组织名推断：仓库在 `client-huashang` 下 ≠ 自动出现在华商市场，必须以 `brands` 声明。
+  - 与 `developer_ids` 分工：`brands` 管「进哪个 OEM 市场目录」；`developer_ids` 管「不公开时谁能看见/安装」。
+  - 完整步骤与验收见 `development/DEVELOPMENT.md` §6「关于 brands」。

TUTORIAL.md

@@ -1,12 +1,33 @@
 > **模板说明（复制后删除本段）**  
 > 本文对应技能市场 **「使用教程」** Tab（发布时同步为 `tutorial_md`）。  
 > 面向普通用户写**可跟着做的步骤**，不要写 CLI、目录结构、release、开发规范。  
-> 与根 `README.md`（技能说明）分工：README 讲「是什么 / 能做什么」；本文讲「第一次怎么用完」。  
-> **复制后验收章节（标题可微调）：**「开始前」「第一步…」「第二步…」「常见卡住怎么办」。
+> 与根 `README.md`（技能说明）分工：README 讲「是什么 / 能做什么 / 边界」；本文讲「从哪个入口怎么用完」。  
+> **完整契约：** `development/TUTORIAL_SURFACES.md`（三入口结构、说明≠教程、skill-detail 不可作主路径）。  
+> **复制后验收章节（标题可微调，语义不可缺）：**「本技能做什么」「开始前」「入口一：数据管理」「入口二：对话任务」「入口三：定时任务」「主能力对照表」「常见卡住怎么办」。  
+> 若本技能 §0.1 未挂数据管理 / 对话 / 定时，对应入口节改为「不适用」并写一句理由（与 REQUIREMENTS 一致）。  
+> **标题层级：** 宿主页头已有技能名、Tab 已有「使用教程」——**禁止**文首再写 `# 技能名 · 使用教程`；正文主分节用 `##`，步骤用 `###`。
 
-# 【技能名称】使用教程
+本技能有两种**平行**的使用方式（按本技能入口定位填写；未挂的入口删掉或写不适用）：
 
-用最短路径带用户完成一次成功使用。步骤要具体，可用「打开匠厂 → …」这类操作语言。
+- **数据管理**：在左侧表上点工具栏 / 行内按钮  
+- **对话任务**：用自然语言让 Agent 完成同一能力  
+
+两种方式触发同一套业务能力，结果一致，选你习惯的即可。  
+定时任务是否提供：见下方「入口三」（没有则写「本技能不需要定时」+ 理由）。
+
+---
+
+## 本技能做什么
+
+用业务语言画清闭环（**不要**写库表英文名或命令行），例如：
+
+```text
+【输入/准备】 → 【核心动作】 → 【结果可见处】 → 【可选报告/导出】
+```
+
+- **输入**：……  
+- **输出**：……  
+- **说明**：边界（教学/正式、是否接外站等）  
 
 ---
 
@@ -14,43 +35,105 @@
 
 确认：
 
-1. 已安装并登录匠厂客户端
-2. 已在技能市场安装本技能（或更新到最新版）
-3. 【网页自动化类技能】首次运行一般会自动登记本平台账号；也可在「账号管理」中指定登录标识。浏览器会话由系统隔离管理——**不要**用本机日常浏览器用户目录去跑真实站
-4. 【按平台】若本技能说明「需要先登录目标站」，请在弹出的有头浏览器中按提示登录或扫码；「登记账号」不等于「已登录目标站」。若说明「可不登录也能用」，仍须有可用的账号会话目录
-5. 【网页自动化类技能】已登记账号可在「数据管理 / 账号管理」查看；每个账号都有独立浏览器会话
-6. 【如需】需要的文件 / 时间范围 / 单号等已准备好
+1. 已安装并登录匠厂客户端  
+2. 已在技能市场安装本技能（建议更新到最新版）  
+3. 【网页自动化类】账号登记 / 目标站登录要求（按本技能；登记 ≠ 已登录）  
+4. 【如需】文件 / 时间范围 / 单号等已准备好  
+5. 【如需】首次须先完成「载入样例 / 导入 / 同步」等准备动作（见入口一或入口二）  
 
 ---
 
-## 第一步：打开技能并说清目标
+## 入口一：数据管理
 
-在匠厂里新建任务或打开对话，用自然语言说明要做什么，例如：
+> 若本技能无业务表、无 toolbar/row/batch：整节改为「不适用」+ 理由。
 
-> “帮我【完成某件业务事】，范围是【时间 / 对象 / 条件】。”
+适合：对照数据、喜欢点界面、机房/运营用户。
 
-建议一次只交代一件事；范围说清楚，减少来回确认。
+### 左侧各表是干什么的
+
+| 表名（中文） | 作用 |
+|--------------|------|
+| 【表 A】 | …… |
+| 【表 B】 | …… |
+
+### 首次准备（若需要）
+
+1. 进入 **数据管理** → **【主表】**  
+2. 点击表顶 **「【准备类按钮 label】」**（若为空表可点，写明是否须选中行）  
+3. 成功后应看到：……  
+
+> **注意：** 准备/载入/导入类按钮须挂在数据管理 **toolbar**（用户看得见）。不要把「技能详情页点按钮」写成主路径——详情页常只显示四 Tab，不一定渲染 Action 按钮。
+
+### 主流程
+
+1. 进入 **【主表】**  
+2. 【是否选中行】  
+3. 点击 **「【主能力 label】」**  
+4. 到 **【结果表 / 任务中心 / 报告】** 核对结果  
+
+### 行级 / 批量（若有）
+
+| 你想做什么 | 操作 |
+|------------|------|
+| …… | **【表】** 行内 → **「【label】」** |
+| …… | 勾选多行 → **「【label】」** |
 
 ---
 
-## 第二步：按提示补充信息
+## 入口二：对话任务
 
-如果 Agent 问你缺什么（账号、文件、筛选条件），按提示补充即可。
+> 若本技能不挂 `agent`：整节改为「不适用」+ 理由。
 
-- 有文件时：按界面提示选择或拖入
-- 有账号时：确认已在对应平台登录，且具备操作权限
+适合：临时提问、要解释、不想切换表。
+
+### 什么时候用对话
+
+- ……  
+- 与入口一效果相同；习惯看表时优先用数据管理  
+
+### 示例话术
+
+| 你想做什么 | 可以这样说 |
+|------------|------------|
+| …… | 「……」 |
+| …… | 「……」 |
+
+### Agent 可能追问什么
+
+- 缺参数时：……  
+- 失败时：可改用数据管理点按钮  
 
 ---
 
-## 第三步：等待结果并核对
+## 入口三：定时任务
 
-任务结束后，请核对：
+> **有 `cron`：** 写如何新建定时、选哪个 Action、默认参数、预期结果。  
+> **无 `cron`：** 用下面「不需要」模板，删掉「如何配置」小节。
 
-- 是否成功完成
-- 处理了多少条 / 哪些失败
-- 生成的文件、表格或记录是否在预期位置
+### 本技能不需要定时时（示例文案，按需保留/改写）
 
-若失败，先看失败原因说明，再按下一节排查。
+本技能**未提供定时任务入口**，原因：【一次性 / 须人指定对象 / 须当场确认 / ……】。  
+请使用 **数据管理** 或 **对话任务**。
+
+### 本技能需要定时时（示例结构）
+
+1. 打开侧栏 **定时任务** → 新建  
+2. 选择本技能 → Action **「【label】」**  
+3. 填写参数 → 保存；可「立即运行」验证  
+4. 到点后在【结果表 / 任务中心】查看  
+
+---
+
+## 主能力对照表
+
+同一能力，两种主入口（按本技能实际填写；只挂一端的注明）：
+
+| 想做什么 | 数据管理 | 对话任务 |
+|----------|----------|----------|
+| …… | **【表】** → **「【label】」** | 「……」 |
+| …… | …… | …… |
+
+按钮名必须与 `assets/actions.json` 的 `label` 一致。
 
 ---
 
@@ -58,10 +141,10 @@
 
 | 现象 | 你可以先试 |
 |------|------------|
-| 提示未登录 / 无权限 | 确认匠厂已登录；业务账号是否在线、权限是否足够 |
-| 提示账号不存在 / 被占用 | 到「数据管理 / 账号管理」确认账号记录和状态，稍后再试；不要重复创建账号 |
-| 提示缺少必要信息 | 把时间范围、单号、文件等说完整后再试一次 |
-| 一直没有结果 | 到任务中心查看进度或失败原因；必要时重新发起 |
-| 结果不对 | 用更明确的条件再说一次，或缩小范围重试 |
+| 主表是空的 | 先做「首次准备」或对话载入/导入 |
+| 按钮点不了 | 是否须先选中行；是否装错版本 |
+| 一直没有结果 | 看任务中心 / 运行日志；async 任务看进度 |
+| 【网页自动化】未登录 / 无权限 | 确认账号在线与目标站登录状态 |
+| 结果不对 | 缩小范围重试，或改用数据管理核对表数据 |
 
-仍无法解决时，把「你说了什么 + 界面提示原文」发给支持人员，便于排查。
+仍无法解决时，把「你用的入口 + 操作步骤 + 界面提示原文」发给支持人员。

assets/README.md

@@ -1,12 +1,15 @@
 # assets
 
 - `actions.json`：Skill Action manifest 最小示例（按入口定位表决定是否保留/扩展；见 `development/PRODUCT_SURFACES.md`）。每个 action **必须**显式声明 `executionProfile`（`sync` \| `async`）。默认仅 `health` / `version` / `config-path`，不放 toolbar，故无 `bind` 示例。
-- `html/example-report.html`：HTML 报告页最小壳（`{{TITLE}}` / `{{GENERATED_AT}}` / `{{BODY}}`）；渲染后须写入数据目录 `html/`，见 `references/ACTIONS.md`「HTML 页面报告」。
-- `examples/`：CLI 成功输出形状示例、以及 `render-html.action.example.json`（虚构路径与数据）。
+- **业务技能注意：** 若主路径在数据管理，准备/载入/导入类 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 页面报告」。模板仓库不要在这里放示例页。
+- `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`；placements 含 `toolbar` / `row` / `batch` / `cron` / `agent` / `skill-detail`（对齐匠厂宿主）。可选 `hoverHint` 为数据管理工具栏悬停（省略不显示，不回退）。`concurrency`/`locks` 仍为预留。`placements` 与 `executionProfile` 正交——进任务中心只看 `async`，与入口无关。表级 Action 与 Agent 契约见 [`references/ACTIONS.md`](../references/ACTIONS.md)；开发深度规范见 [`development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。
+`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)
+- 用户市场四 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)）
 - 开发规范见 [`development/`](../development/)

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,9 +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」）。
-- `visible-when-action.example.json`：Action 参数字段条件显隐 `visibleWhen` 形状参考（互斥模式联动；见 `references/ACTIONS.md`「字段条件显隐」；≠ Policy L3）。
+- `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`「字段条件显隐」；≠ `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`「勾选驱动模式」「用户可见文案」）。
 - `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/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/examples/path-root-file-action.example.json

@@ -0,0 +1,36 @@
+{
+  "_comment": "形状参考：Action 表单 file/directory 用 pathRoot 指定原生对话框起始目录（相对技能数据根）。省略则宿主默认 {skill_data}/input。完整契约见 references/ACTIONS.md「本地路径选择与 pathRoot」。勿与宿主导入面板（replaces:import）混用本示例。",
+  "schemaVersion": 1,
+  "skill": "your-skill-slug",
+  "actions": [
+    {
+      "id": "import-pack",
+      "label": "导入数据包",
+      "description": "从本技能输入目录子文件夹选择 JSON 并写入业务表。",
+      "placements": ["toolbar", "agent"],
+      "executionProfile": "sync",
+      "interaction": "form",
+      "bind": { "tables": ["business_items"] },
+      "inputSchema": {
+        "type": "object",
+        "required": ["file"],
+        "properties": {
+          "file": {
+            "type": "string",
+            "title": "数据包文件",
+            "description": "请选择 input/数据包/ 下的 JSON。",
+            "format": "file",
+            "display_type": "file",
+            "pathRoot": "input/数据包"
+          }
+        }
+      },
+      "entrypoint": {
+        "type": "cli",
+        "command": "import-pack",
+        "args": ["--file", "{{file}}"]
+      },
+      "steps": [{ "when": "afterSuccess", "do": "reloadTable" }]
+    }
+  ]
+}

assets/examples/selection-label-column.action.example.json

@@ -0,0 +1,38 @@
+{
+  "id": "process-selected",
+  "label": "处理勾选",
+  "description": "对勾选行执行业务处理。示例：声明 labelColumn，让确认弹层「已选择」摘要显示可读名称。",
+  "placements": ["toolbar", "batch"],
+  "executionProfile": "async",
+  "interaction": "confirm",
+  "confirmation": {
+    "message": "将按技能业务规则处理勾选记录（具体是否跳过某些状态由 CLI 决定）。"
+  },
+  "bind": {
+    "tables": ["business_items"],
+    "inputMapping": {
+      "ids": "$selection.ids"
+    },
+    "labelColumn": "display_name"
+  },
+  "inputSchema": {
+    "type": "object",
+    "required": ["ids"],
+    "properties": {
+      "ids": {
+        "type": "string",
+        "title": "编号列表",
+        "description": "逗号分隔主键；宿主会预填勾选行",
+        "readOnly": true
+      }
+    }
+  },
+  "entrypoint": {
+    "type": "cli",
+    "command": "process",
+    "args": ["--ids", "{{ids}}"]
+  },
+  "hostEffects": {
+    "onSuccess": ["reloadTable"]
+  }
+}

assets/examples/selection-mode-optional.action.example.json

@@ -0,0 +1,46 @@
+{
+  "id": "process-queue",
+  "label": "处理队列",
+  "description": "从业务队列处理待处理记录。有勾选则处理勾选的；没有勾选则按下方数量从队列领取。已成功或失败的会自动跳过。进度可在任务中心查看。",
+  "placements": ["toolbar", "batch", "cron", "agent"],
+  "executionProfile": "async",
+  "interaction": "form",
+  "confirmation": {
+    "message": "将按规则处理记录（有勾选则处理勾选的；未勾选则按数量从队列领取），是否继续？"
+  },
+  "bind": {
+    "tables": ["business_items"],
+    "selectionMode": "optional",
+    "labelColumn": "display_name",
+    "inputMapping": {
+      "itemIds": "$selection.ids"
+    }
+  },
+  "inputSchema": {
+    "type": "object",
+    "required": ["itemIds", "pickCount"],
+    "properties": {
+      "itemIds": {
+        "type": "string",
+        "title": "编号列表",
+        "description": "有勾选时自动填入，一般无需修改",
+        "readOnly": true
+      },
+      "pickCount": {
+        "type": "number",
+        "title": "处理数量",
+        "description": "没有勾选时：从待处理队列里领取的条数",
+        "default": 1,
+        "minimum": 1
+      }
+    }
+  },
+  "entrypoint": {
+    "type": "cli",
+    "command": "process",
+    "args": ["--ids", "{{itemIds}}", "--pick", "{{pickCount}}"]
+  },
+  "hostEffects": {
+    "onSuccess": ["reloadTable", "clearSelection"]
+  }
+}

assets/examples/skill-grid-presentation.example.json

@@ -0,0 +1,32 @@
+{
+  "schemaVersion": 1,
+  "skill": "your-skill-slug",
+  "table": "business_records",
+  "rowKey": "id",
+  "generatedAt": "2026-08-10T06:00:00Z",
+  "rules": [
+    {
+      "ruleKey": "qty-low-rows",
+      "rows": ["42", "99"],
+      "columns": "all",
+      "tone": "danger",
+      "message": "库存低于安全线",
+      "alert": true
+    },
+    {
+      "ruleKey": "status-column",
+      "rows": "all",
+      "columns": ["status"],
+      "tone": "warning",
+      "message": "待审核"
+    },
+    {
+      "ruleKey": "overdue-print-region",
+      "rows": ["7", "8"],
+      "columns": ["print_done_at", "ship_done_at"],
+      "tone": "danger",
+      "message": "环节到期未填",
+      "alert": true
+    }
+  ]
+}

assets/examples/year-month-action.example.json

@@ -0,0 +1,40 @@
+{
+  "_comment": "形状参考：账期/月份字段用 year_month，宿主渲染年月选择器。完整契约见 references/ACTIONS.md「表单字段类型对照」与 references/SCHEMA.md。",
+  "schemaVersion": 1,
+  "skill": "your-skill-slug",
+  "actions": [
+    {
+      "id": "create-period-job",
+      "label": "新建账期作业（示例）",
+      "description": "演示 year_month 字段：提交值为 YYYY-MM 字符串，不要用 date。",
+      "placements": ["toolbar"],
+      "executionProfile": "sync",
+      "interaction": "form",
+      "bind": {
+        "tables": ["close_jobs"]
+      },
+      "entrypoint": {
+        "type": "cli",
+        "command": "create-job",
+        "args": ["--period", "{{period}}", "--title", "{{title}}"]
+      },
+      "inputSchema": {
+        "type": "object",
+        "required": ["period"],
+        "properties": {
+          "period": {
+            "type": "string",
+            "title": "月份",
+            "description": "格式 YYYY-MM，例如 2026-05",
+            "display_type": "year_month"
+          },
+          "title": {
+            "type": "string",
+            "title": "标题",
+            "description": "可留空，默认按月份生成"
+          }
+        }
+      }
+    }
+  ]
+}

assets/html/example-report.html

@@ -11,17 +11,31 @@
       --muted: #64748b;
       --card: #ffffff;
       --line: #e2e8f0;
+      --page-pad-x: clamp(14px, 2.5vw, 24px);
+      --page-pad-y: clamp(12px, 2vw, 20px);
     }
     * { box-sizing: border-box; }
-    html { overflow-y: auto; }
-    body {
+    html {
+      width: 100%;
+      height: 100%;
       margin: 0;
+      overflow-x: hidden;
+      overflow-y: auto;
+    }
+    body {
+      width: 100%;
+      min-height: 100%;
+      margin: 0;
+      overflow-x: hidden;
       font-family: "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
       background: var(--bg);
       color: var(--ink);
+      line-height: 1.5;
     }
     header {
-      padding: 20px 24px 8px;
+      padding: var(--page-pad-y) var(--page-pad-x) 8px;
+      background: var(--card);
+      border-bottom: 1px solid var(--line);
     }
     header h1 {
       margin: 0 0 6px;
@@ -34,7 +48,23 @@
       font-size: 13px;
     }
     main {
-      padding: 8px 24px 28px;
+      width: 100%;
+      min-width: 0;
+      padding: var(--page-pad-y) var(--page-pad-x) 28px;
+    }
+    .section {
+      margin-bottom: 18px;
+    }
+    .section h2 {
+      margin: 0 0 8px;
+      font-size: 13px;
+      font-weight: 650;
+      color: var(--muted);
+    }
+    .meta {
+      margin: 0 0 10px;
+      color: var(--muted);
+      font-size: 12px;
     }
     .card {
       background: var(--card);
@@ -44,6 +74,35 @@
       line-height: 1.6;
       font-size: 14px;
     }
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      table-layout: fixed;
+      background: var(--card);
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      overflow: hidden;
+      font-size: 13px;
+    }
+    th, td {
+      padding: 8px 10px;
+      border-bottom: 1px solid var(--line);
+      text-align: left;
+      vertical-align: top;
+      word-break: break-word;
+      overflow-wrap: anywhere;
+    }
+    th {
+      background: #f8fafc;
+      font-weight: 600;
+      color: var(--muted);
+      font-size: 12px;
+    }
+    tr:last-child td { border-bottom: none; }
+    /*
+      宿主数据管理在 iframe 内预览本页：应横向铺满可用宽度，仅纵向滚动。
+      复杂看板可在 {{BODY}} 内使用 .section / table；布局底线见 references/ACTIONS.md「宿主预览布局」。
+    */
   </style>
 </head>
 <body>

assets/naming/platforms.txt

@@ -11,3 +11,4 @@ lianlian
 single-window
 export-rebate
 etax
+colipu

assets/naming/scopes.txt

@@ -1,4 +1,3 @@
 all
 batch
 multi
-default

assets/schemas/skill-actions.schema.json

@@ -28,7 +28,7 @@
     },
     "cellPresentation": {
       "$ref": "#/$defs/cellPresentationDeclaration",
-      "description": "可选。启用数据管理单元格呈现（P1）。缺省或不 enabled = P0，宿主不读标色。详见 references/CELL_PRESENTATION.md。"
+      "description": "可选。启用数据管理呈现（P1：格子/行/列/区域）。缺省或不 enabled = P0，宿主不读标色。详见 references/CELL_PRESENTATION.md。"
     }
   },
   "$defs": {
@@ -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"],
@@ -110,7 +152,11 @@
         "sensitive": { "type": "boolean" },
         "readOnly": {
           "type": "boolean",
-          "description": "宿主数据管理表单只读展示该字段（仍会随提交传入 entrypoint）；用于行内/勾选预填的主键等"
+          "description": "只读。有「已选择」且字段来自 inputMapping（或约定 id 字段）时，宿主 form 默认不渲染该控件，预设值仍提交；无摘要时只读展示。勿用 visibleWhen 代替（visibleWhen 隐藏不提交）。"
+        },
+        "revealInForm": {
+          "type": "boolean",
+          "description": "可选逃生阀。true 时即使弹层有「已选择」摘要，也仍渲染该 readOnly 字段。不改变提交 payload。省略=映射只读字段在有摘要时默认折叠。"
         },
         "column": {
           "type": "string",
@@ -120,84 +166,60 @@
         },
         "display_type": {
           "type": "string",
-          "enum": ["textarea", "date", "datetime_unix_seconds", "url", "email", "lookup", "directory", "file"],
-          "description": "可选。表单控件提示；与 format 二选一即可。lookup=关联下拉（须配 lookup 对象或绑到已有 lookup 列）。file/directory=本地路径选择。须与 CRUD display_type 语义对齐（见 ACTIONS.md / SCHEMA.md）。"
+          "enum": ["textarea", "year", "year_month", "month", "date", "datetime_unix_seconds", "url", "email", "lookup", "directory", "file"],
+          "description": "可选。表单控件提示；与 format 二选一即可。year/year_month=年或年月选择器（YYYY / YYYY-MM；month 为 year_month 别名）。lookup=关联下拉（须配 lookup 对象或绑到已有 lookup 列）。file/directory=本地路径选择（可选 pathRoot 指定起始目录，见 ACTIONS.md）。须与 CRUD display_type 语义对齐。"
         },
         "format": {
           "type": "string",
-          "enum": ["textarea", "date", "datetime_unix_seconds", "url", "email", "lookup", "directory", "file"],
+          "enum": ["textarea", "year", "year_month", "month", "date", "datetime_unix_seconds", "url", "email", "lookup", "directory", "file"],
           "description": "可选。display_type 别名，语义相同。"
         },
+        "pathRoot": {
+          "type": "string",
+          "minLength": 1,
+          "description": "可选。仅对 display_type/format 为 file 或 directory 有意义：原生选文件/目录对话框的起始文件夹，相对当前技能数据根（如 input/库存数据）。省略则宿主默认打开 {skill_data}/input。禁止绝对路径、盘符与 ..。Agent/CLI 忽略。见 references/ACTIONS.md「本地路径选择与 pathRoot」。"
+        },
         "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",
@@ -209,18 +231,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",
@@ -296,9 +401,24 @@
             "pattern": "^[a-z][a-z0-9_]*$"
           },
           "description": "可选。将 inputSchema 属性名映射到业务表物理列名，供 Action 弹窗与 replaces create/update 抽屉复用列 displayName / lookup options。"
+        },
+        "labelColumn": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-z][a-z0-9_]*$",
+          "description": "可选。数据管理 Action 确认/表单弹层「已选择」摘要用的可读标签列（#id + 标签）。仅影响展示，不改变提交 payload。省略时宿主按常见列名启发（title/name 等），再不行只显示编号。"
+        },
+        "selectionMode": {
+          "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。concurrency/locks 勿写入。"
+      "description": "表级绑定；toolbar 必填。可选 inputMapping / columnMapping / labelColumn / selectionMode / visibleWhen。concurrency/locks 勿写入。"
     },
     "hostEffectId": {
       "type": "string",

assets/schemas/skill-cell-presentation.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openclaw.local/skill-template/skill-cell-presentation.schema.json",
   "title": "SkillCellPresentationDocument",
-  "description": "匠厂数据管理「单元格呈现」文档（schemaVersion 1）。技能按业务规则为「某表某行某列」声明语义 tone（非任意 CSS）；宿主映射主题样式。用途不限（时效超时、库存预警、状态异常、必填缺失等）。详见 references/CELL_PRESENTATION.md。",
+  "description": "匠厂数据管理「单元格呈现」文档（schemaVersion 1）。技能按业务规则为「某表某行某列」声明语义 tone（非任意 CSS）；宿主映射主题样式。整行/整列/区域见 skill-grid-presentation.schema.json，同一 cellPresentation.enabled。用途不限（时效超时、库存预警、状态异常、必填缺失等）。详见 references/CELL_PRESENTATION.md。",
   "type": "object",
   "required": ["schemaVersion", "skill", "table", "rowKey", "cells"],
   "additionalProperties": false,

assets/schemas/skill-grid-presentation.schema.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openclaw.local/skill-template/skill-grid-presentation.schema.json",
+  "title": "SkillGridPresentationDocument",
+  "description": "匠厂数据管理「Grid Presentation」文档（schemaVersion 1）。技能按业务规则为 rows×columns 声明语义 tone（整行、整列、区域或单格）；禁止 all×all。非任意 CSS。与 skill-cell-presentation.schema.json（v1 cells[]）并存，同一 cellPresentation.enabled。详见 references/CELL_PRESENTATION.md。",
+  "type": "object",
+  "required": ["schemaVersion", "skill", "table", "rowKey", "rules"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1
+    },
+    "skill": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+      "minLength": 1,
+      "description": "与 SKILL.md metadata.openclaw.slug / actions.json skill 一致"
+    },
+    "table": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "description": "业务表物理名（snake_case）"
+    },
+    "rowKey": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "description": "用于匹配行的业务表列名（如 id）；rules[].rows 的 id 取自该列"
+    },
+    "generatedAt": {
+      "type": "string",
+      "minLength": 1,
+      "description": "可选。ISO-8601 或技能约定的生成时间，便于排障"
+    },
+    "rules": {
+      "type": "array",
+      "description": "当前应对该表生效的 grid 规则；空数组 = 该表无 grid 呈现（清除旧行/列/区域样式）。同 ruleKey 由 UNIQUE 约束覆盖。",
+      "items": { "$ref": "#/$defs/ruleItem" }
+    }
+  },
+  "$defs": {
+    "tone": {
+      "type": "string",
+      "enum": ["danger", "warning", "info", "success", "muted"],
+      "description": "语义色板（闭集）。宿主映射到底色/字色/左边线等；禁止技能下发原始 CSS 或任意 hex。"
+    },
+    "axisTarget": {
+      "description": "\"all\" = 该轴全部；非空字符串数组 = 有限集合（行 id 或列名）",
+      "oneOf": [
+        { "type": "string", "const": "all" },
+        {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      ]
+    },
+    "ruleItem": {
+      "type": "object",
+      "required": ["ruleKey", "rows", "columns", "tone"],
+      "additionalProperties": false,
+      "not": {
+        "properties": {
+          "rows": { "const": "all" },
+          "columns": { "const": "all" }
+        },
+        "required": ["rows", "columns"]
+      },
+      "properties": {
+        "ruleKey": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "description": "本表内唯一。建议稳定业务键（重算时覆盖同一条）"
+        },
+        "rows": { "$ref": "#/$defs/axisTarget" },
+        "columns": { "$ref": "#/$defs/axisTarget" },
+        "tone": { "$ref": "#/$defs/tone" },
+        "message": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "可选。悬停/无障碍说明（短文案）；不要塞长报告"
+        },
+        "alert": {
+          "type": "boolean",
+          "description": "可选，默认 false。true = 按本条规则计入进页/同步提醒（不按命中格子数）"
+        }
+      }
+    }
+  }
+}

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` 后返回空租约。
@@ -173,7 +184,9 @@ python scripts/main.py account open <account_id>
 - 租约持有者应使用技能 slug 或可追踪任务标识，`purpose` 写明用途。
 - 租约 TTL 应覆盖正常任务时长；长任务需要平台支持的续租策略，不能依赖永不过期。
 - `finally release_lease(...)` 是最低要求，浏览器关闭失败也不能跳过释放尝试。
-- 进程被强制结束后可能留下租约；先用 `lease list --active` 核对，确认没有真实任务仍在使用后再释放或清理。
+- **清理顺序**：`finally` 内**先 `release_lease`，再关浏览器**。关浏览器（含 CDP / 强杀 Profile 进程）可能耗时或卡住；先释租约可避免「窗还没关完、账号已被下一任务抢走失败」的空窗拉长。
+- **任务中心中断**：宿主只下发 `stop` 并等待技能退出；技能须在闸门抛出 `JobStopped` 后进入 `finally` 自清。禁止用 `except Exception` 吞掉 `JobStopped`（详见 [`LOGGING.md`](LOGGING.md) §2.5）。不要指望宿主代收租约。
+- 进程被强制结束后可能留下租约；先用 `lease list --active` 核对，确认没有真实任务仍在使用后再释放或清理；亦可等待 TTL 过期。
 - 禁止看到租约冲突就直接删数据库记录、删 Profile、换账号或新建重复账号。
 
 ## 9. 工业级测试
@@ -184,6 +197,7 @@ python scripts/main.py account open <account_id>
 - 账号不存在、平台不匹配、Profile 缺失、返回格式异常；
 - 同一账号并发抢占和 `LEASE_CONFLICT`；
 - 业务成功、业务失败、用户取消、浏览器崩溃后的租约释放；
+- **NEED_MANUAL** 任务中心运行中点「中断」：租约变为 `released`（或无 active），马上再采不因残留租约 `LEASE_CONFLICT`；
 - 登录过期、验证码 / 二次验证、账号风险和权限不足；
 - 两个以上账号轮换且 Profile、登录态、结果互不污染；
 - 关闭重开后登录保持；

development/ADAPTER.md

@@ -102,7 +102,7 @@ def get_adapter():
 2. **普通兄弟技能调用**，优先走统一 **`service.sibling_bridge`**（`call_sibling_json`），**不要**在 `task_service.py`、`task_rpa.py` 等业务流程文件中到处散落 `subprocess.run`。
 3. **account-manager 账号/租约能力**是例外：可参考 `examples/real_browser_rpa/scripts/service/account_client.py` 与 `examples/simulator_browser_rpa/scripts/service/account_client.py`，封装为**单一** `account_client.py`；允许在该文件内部集中通过 subprocess 调 account-manager CLI。**禁止** import `rpa_helpers` 等 account-manager 内部模块；`simulator_rpa` 与 `real_rpa` 均走同一 `pick_web_account` / `release_lease` 模式。
 4. **不允许**直接 `import account-manager` 的内部 Python 模块（如 `service/`、`util/`、`db/`）。
-5. **所有选择路径都必须取得 lease**：包括纯数字 `DEFAULT_ACCOUNT_ID`。`account get <id>` 只能读取账号，不能单独作为运行结果；必须再通过可定位该账号的 pick 流程取得非空 `lease_token`。随后必须 `finally release lease`；进程被 kill 后可能残留 lease，需按 [`ACCOUNT_MANAGER.md`](ACCOUNT_MANAGER.md) 排查。
+5. **所有选择路径都必须取得 lease**：包括纯数字 `DEFAULT_ACCOUNT_ID`。`account get <id>` 只能读取账号，不能单独作为运行结果；必须再通过可定位该账号的 pick 流程取得非空 `lease_token`。随后必须 `finally` **先 `release_lease`、再关浏览器**；进程被 kill 后可能残留 lease，需按 [`ACCOUNT_MANAGER.md`](ACCOUNT_MANAGER.md) 排查。宿主中断只通知技能，**不**代收租约；禁止 `except Exception` 吞掉 `JobStopped`（见 [`LOGGING.md`](LOGGING.md) §2.5）。
 6. **网页 RPA 硬规则**（详见 [`RPA.md`](RPA.md) §0.2）：必须先经 `pick_web_account`（底层 **`ensure-web` / `pick-web --ensure`**）拿到 `profile_dir` 再开浏览器；拿不到则失败退出；生产有头；**是否站点登录**按平台约定，但**不等于**可以跳过 account-manager。登记账号 ≠ 站点已登录。
 7. **账号选择优先级**：纯数字 `DEFAULT_ACCOUNT_ID` → 校验指定账号后带租约 pick；`DEFAULT_LOGIN_ID` / 非数字标识 → `ensure-web --login-id --lease`；皆空 → 按平台 `ensure-web --lease`。人读展示优先 `login_id` / `account_label`，不要只用数字 id。多条匹配或无法确保拿到指定 ID → `ERROR:AMBIGUOUS_ACCOUNT`。
 8. **运行前校验**：`profile_dir` 和 `lease_token` 均须非空；账号平台必须匹配；缺任一字段立即失败，不打开浏览器。
@@ -119,10 +119,12 @@ result = call_sibling_json("account-manager", ["list", "--limit", "10"])
 from service.account_client import pick_web_account, release_lease
 
 account = pick_web_account(platform="target_platform", login_id=None)
+lease_token = account.get("lease_token")
 try:
     ...
 finally:
-    release_lease(account.get("lease_token"))
+    release_lease(lease_token)  # 先释租约
+    # 再关浏览器 / Playwright
 ```
 
 ## 相关文档

development/CHECKLIST.md

@@ -60,6 +60,7 @@ checklist_version: 1.0
 - [ ] S0-9 **入口定位表**（见 `PRODUCT_SURFACES.md` / `REQUIREMENTS` §0.1）：已填写 / 未填写
 - [ ] S0-10 本技能宣称的主用户路径涉及：对话 / 数据管理（执行或仅展示） / 定时（可多选；与定位表一致）
 - [ ] S0-11 **业务行生命周期**（见 `references/WORK_ITEM_STATUS.md` / `REQUIREMENTS` §0.3）：有处理队列且已声明状态→角色映射 / 不适用
+- [ ] S0-12 **HTML 页面报告**（见 `references/ACTIONS.md`「HTML 页面报告」）：壳子页 `assets/html/pages/*.html` / 快照 `html/*.html` + `render-html` / 不适用
 
 ---
 
@@ -76,10 +77,16 @@ checklist_version: 1.0
 
 - [ ] A2-1 **P0** 市场「说明」能让非开发者理解：做什么、给谁用、开始前准备什么
 - [ ] A2-2 **P0** 「说明/教程」不以开发目录、内部实现细节作为用户主路径
-- [ ] A2-3 **P1** 「教程」可按真实顺序跟做（准备 → 步骤 → 失败怎么办）
+- [ ] A2-3 **P1** 「教程」可按真实顺序跟做（准备 → 分入口步骤 → 失败怎么办）；结构见 `TUTORIAL_SURFACES.md`
 - [ ] A2-4 **P1** 「演示」结构完整（有演示信息位；无视频则标明暂无，不假装有）
 - [ ] A2-5 **P0** 「更新日志」能对应到当前交付版本
 - [ ] A2-6 **P0** 平台/Agent 侧说明中，常见用户意图的触发方式与真实能力一致（短操作 vs 长任务不混淆）
+- [ ] A2-7 **P0** 「说明」Tab（`README.md`）**不含**分步操作（1/2/3）、Agent 话术块、「入口一/二」专章；操作指引指向「使用教程」
+- [ ] A2-8 **P0** 「教程」Tab 覆盖 `REQUIREMENTS` §0.1 / `actions.json` 中所有「挂」的入口（数据管理 / 对话；结构见 `TUTORIAL_SURFACES.md`）
+- [ ] A2-9 **P0** 无 `cron` 时教程有「不需要定时」+ 理由；有 `cron` 时教程写清如何配置
+- [ ] A2-10 **P1** 教程主能力对照表与 `actions.json` 的 `label` 一致
+- [ ] A2-11 **P1** 若有数据管理主路径：准备/载入/导入类能力在对应表 **toolbar** 可见；教程**不以** skill-detail 为唯一主路径
+- [ ] A2-12 **P0** 说明/教程正文**不以** `# 技能名` 或 `# 技能名 · 使用教程` 开篇（宿主页头/Tab 已有）；主分节用 `##`，不要把原 `##` 升成 `#`（见 `TUTORIAL_SURFACES.md` §0.1）
 
 ---
 
@@ -101,9 +108,13 @@ 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-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"`（勿拆两个同义顶栏按钮）；无勾选可点、有勾选显示「已选择」、空选数量字段用 `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`「分页勾选小表」）
 ---
 
 ## 5. 账号与浏览器会话（网页 RPA 适用；其他形态标 N/A 或改测等价项）
@@ -111,15 +122,16 @@ 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` 在当前用户数据目录真实存在
 - [ ] A5-8 **P0** 每个账号使用独立且稳定的 Profile；不同账号不共用，本机日常浏览器目录不参与运行
-- [ ] A5-9 **P0** 指定账号 ID、指定登录标识和自动选择均取得非空租约；成功、失败、取消和异常路径最终释放
+- [ ] A5-9 **P0** 指定账号 ID、指定登录标识和自动选择均取得非空租约；成功、失败、取消和异常路径最终释放；`finally` 先释租约再关浏览器
 - [ ] A5-10 **P0** **NEED_MANUAL** 登录后关闭浏览器并释放租约，再取同一账号重开，登录状态仍有效；失效时明确提示重新登录
 - [ ] A5-11 **P1** 至少两个账号连续或轮换测试通过，Profile、登录态、结果和失败互不污染
 - [ ] A5-12 **P1** 租约冲突、残留租约和账号登录失效能按文档自助定位，不通过删库、删 Profile 或自动换号处理
+- [ ] A5-13 **P0** **NEED_MANUAL** 任务中心运行中点「中断」：技能响应 `JobStopped` 并释放租约（数据管理「账号租约」为 `released` / 无 active）；立即再跑不因残留租约失败；进度 `emit` 不得用裸 `except Exception` 吞掉停止
 
 ---
 
@@ -134,6 +146,14 @@ checklist_version: 1.0
 - [ ] A6-7 **P0** 有「处理业务行」类 Action 时（见 `WORK_ITEM_STATUS.md`）：默认只处理**可操作**角色状态；成功/失败/跳过/进行中再点处理应拒绝或跳过且不产生重复副作用；重做须人工改回可操作。无处理队列 → **N/A**
 - [ ] A6-8 **P0** 同上适用时：开始处理后业务表进入**进行中**；成功回写成功类终态；失败回写失败类终态且**失败原因**可读（任务成功但业务行仍停在可操作/进行中 → **FAIL**）
 - [ ] A6-9 **P1** 同上适用时：`REQUIREMENTS` §0.3（或等价）已填写本技能状态→角色映射；处理类 Action 确认文案写清仅可操作态
+- [ ] A6-10 **P1** 有 HTML 侧栏预览时（S0-12）：预览区横向铺满、无横向滚动条；重新生成后内容与页头时间更新；布局符合 `references/ACTIONS.md`「宿主预览布局」。无 HTML 报告 → **N/A**
+- [ ] A6-11 **P1** 业务**状态 / 启用类**列若用户需要筛表或顶栏搜中文：`searchable: 1` 且 `options_json`（或 `boolean` + `options_json`）的 **value 与存库一致**；仅 `searchable: 0` 则宿主不提供列筛与全局搜索。见 `references/SCHEMA.md`「列筛选与全局搜索」
+- [ ] A6-12 **P2** `display_type: boolean` 的展示列推荐同时配置 `options_json` 中文 label（如 停用/启用），避免仅靠宿主默认「是/否」；无 boolean 列 → **N/A**
+- [ ] A6-13 **P2** 账期/月份/生效月等 `YYYY-MM` 字段用 `display_type: year_month`（或 Action 同义 `format`），**不要**只用 `description` 写格式却留纯文本框；完整日才用 `date`
+- [ ] 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`）
 
 ---
 
@@ -144,7 +164,7 @@ checklist_version: 1.0
 - [ ] A7-3 **P0** 故意失败一条时，文件日志先有 `task_failed`/`warning`，再有 `ERROR:CODE` 或任务中心失败态
 - [ ] A7-4 **P1** 关键步骤有据可查（能对应到开始/关键节点/结束；RPA 宜有多个 `stage=`）
 - [ ] A7-5 **P1** 若宣称支持录屏或截图存证：打开开关后关键步骤或失败能留下可查看产物；宣称支持却完全无产物 → **FAIL**
-- [ ] A7-6 **P2** 用户可见文案偏业务语言，而非大段开发黑话
+- [ ] A7-6 **P2** 用户可见文案偏业务语言，而非大段开发黑话（数据管理弹窗 / 任务失败见 **A4-10**，更高优先级）
 - [ ] A7-7 **P2** 数据管理技能按钮（toolbar / row / batch）中文名对照 `references/ACTIONS.md`「Action 按钮中文名」；不与宿主「查看 / 编辑 / 删除」抢名；打开类成功不弹成功条。行业专有按钮名可自创
 
 ---
@@ -175,7 +195,8 @@ checklist_version: 1.0
 - [ ] A9-1 **P0** 仓库默认测试套件通过（执行技能约定的一键测试命令，如 `python tests/run_tests.py -v`）
 - [ ] A9-2 **P0** 不以「仅模拟档通过」作为交活依据（有真实档要求时必须真实跑通或书面阶段性豁免）
 - [ ] A9-3 **P0** **NEED_MANUAL** 入口定位表中定为「挂」的宿主入口（详情/Agent/工具栏/定时等）按声明抽测可通过；未在定位表中规划且未声明的入口可标 N/A（须引用定位表理由），**禁止**用「未声明」掩盖「从未做入口定位」
-- [ ] A9-4 **P1** 对外版本一致：详情、version、更新日志、发布标签能对上
+- [ ] A9-4 **P0** 对外版本一致（POLICY-RELEASE-001）：`SKILL.md` version = `SKILL_VERSION` = 发布 git tag（无前缀）；`release.ps1` 打 tag 前会硬校验，漏改不得发布；CHANGELOG 有对应小节
+- [ ] A9-4b **P1** 本机宿主验收用根目录 `.\sync.ps1` 覆盖已安装明文；市场上的最新版本和加密包仍走 `.\release.ps1`。同步后退出资料管理再打开，不要点技能市场「更新」
 - [ ] A9-5 **P1** 开发者按平台规则能安装并测到该技能（若平台有开发者可见性要求）
 
 ---

development/CONFIG.md

@@ -26,6 +26,45 @@
 
 **不要**依赖 `# ── 分组 ──` 装饰线给整组做唯一说明：宿主只会把行头挂到**紧挨着的下一个活跃 key**，后面的 key 不会自动继承。分组可用空行区分；**逐 key 自带行头（+ 行尾）才是硬要求**。
 
+### 必填项：`# @required`（匠厂配置管理）
+
+匠厂宿主「数据管理 → 配置管理」支持把部分配置项标为**必填**：模板在**行头注释上方**加独立一行 `# @required`，宿主会在 key 前显示红色 `*`，并在键值模式保存时拦截空值。
+
+| 规则 | 说明 |
+|------|------|
+| **写法** | `# @required` 单独占一行，紧挨在该 key 的**中文行头**上方 |
+| **语义** | 保存时该 key 的值不得为空（trim 后）；模板里可以有默认值 |
+| **展示** | `@required` 行本身**不展示**给用户，只用于打标 |
+| **声明位置** | 只在仓库 `.env.example` 声明；用户数据目录 `.env` 里的 `@required` 不算 |
+
+正例：
+
+```ini
+# @required
+# 目标网站地址：技能要访问的网站或服务地址
+TARGET_BASE_URL=https://sandbox.jc2009.com   # 填写完整网址（含 https://）；换环境时再改
+
+# 默认登录账号：仅填写非敏感的账号标识（如工号/登录名）
+DEFAULT_LOGIN_ID=                      # 留空=按平台自动选用；本项未标 @required，宿主不强制
+```
+
+反例（禁止）：
+
+```ini
+# 目标网站地址（必填）
+TARGET_BASE_URL=                       # @required  ← 禁止写在行尾
+
+# @required
+TARGET_BASE_URL=                       # ← 禁止：@required 下方缺少中文行头
+
+# @required
+# 共用说明
+KEY_A=
+KEY_B=                                 # ← 禁止：一个 @required 给多个 key 共用
+```
+
+**机器门禁**：`POLICY-CONFIG-005` 校验 `@required` 用法；与 `POLICY-CONFIG-004`（行头/行尾中文）一并生效。
+
 ### 必须做到
 
 1. 每个会进入配置管理的活跃 `KEY=` 都有完整中文**行头**。
@@ -191,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**。
 
@@ -67,9 +68,10 @@ D:\jiangchang-data\12500\download-video-baidu-haokan\
 
 宿主约定（与本模板对齐）：
 
-- 工具栏「导入」**UI 一律**打开宿主「导入数据」面板（默认从 `input/` 选文件）；「导出」默认写到 `output/`
+- 工具栏「导入」**UI 一律**打开宿主「导入数据」面板（默认从本技能 `input/` 选文件）；「导出」默认写到 `output/`
+- **Action 表单**里 `display_type`/`format` 为 `file` 或 `directory` 时：宿主原生对话框默认打开**当前技能** `{skill_data}/input`；若字段声明可选 **`pathRoot`**（相对技能数据根，如 `input/库存数据`），则打开该子目录。禁止在技能里写用户 ID 或绝对盘符。契约见 [`../references/ACTIONS.md`](../references/ACTIONS.md)「本地路径选择与 pathRoot」
 - 若表声明了 `replaces: import`，确认导入后由技能 CLI 写库（见 [`../references/ACTIONS.md`](../references/ACTIONS.md)「`replaces`」）；仅有 `replaces: create` 时宿主可按行调 create（兼容）
-- 数据管理扫描 `{skill_data}/html/*.html`（一层、非递归）；`<title>` → 侧栏显示名；「重新生成」调用 Action id **`render-html`**（见 [`../references/ACTIONS.md`](../references/ACTIONS.md)「HTML 页面报告」）
+- 数据管理扫描两处 HTML（都只扫一层）：安装包 `assets/html/pages/*.html` 是装完就有的壳子页；`{skill_data}/html/*.html` 是快照，「重新生成」调用 Action id **`render-html`**。页面里用 `jiangchang.call` 调本技能已声明的命令。详见 [`../references/ACTIONS.md`](../references/ACTIONS.md)「HTML 页面报告」
 
 ---
 
@@ -176,6 +178,10 @@ DOWNLOAD_OUTPUT_DIR=./outputs/videos
 - `tests/test_runtime_paths.py` 覆盖 `resolve_data_path` / `resolve_input_path`。
 - `POLICY-DATA-PATH-001`：禁止 `.env.example` 中 `./` 路径；禁止业务代码 `abspath(config.get(...))`。
 
+### 卸载技能与数据保留
+
+宿主**卸载技能只删除安装目录**（如 `.openclaw/skills/{slug}`），**不会**删除 `{JIANGCHANG_DATA_ROOT}/{user_id}/{skill_slug}/` 下的 SQLite、输入输出与日志。重装会复用同一用户库；schema 迁移须在 `init_db()` 中幂等完成（见 [`../references/SCHEMA.md`](../references/SCHEMA.md)「表增删改与退役」）。
+
 ---
 
 ## 9. 相关文档

development/DEVELOPMENT.md

@@ -74,6 +74,7 @@ your-skill/
 ├─ CHANGELOG.md
 ├─ requirements.txt
 ├─ release.ps1
+├─ sync.ps1
 └─ SKILL.md
 ```
 
@@ -85,6 +86,8 @@ your-skill/
 - `DEMO.md`：市场 **演示** Tab（`demo_video_url` + `demo_md`）
 - `CHANGELOG.md`：市场 **更新日志** Tab（按版本小节同步 `changelog`）
 - `SKILL.md`：面向 LLM / 平台的技能入口
+- `release.ps1`：发布到服务器（提交、tag、CI 加密包）
+- `sync.ps1`：把明文同步到本机宿主，供界面验收
 - `references/`：Agent 运行/编排/调用时渐进加载的补充上下文（如 CLI、SCHEMA）
 - `development/`：面向开发者与 AI 编程代理的开发资料、需求、测试与技术规范
 - `scripts/`：放真正的代码
@@ -115,8 +118,8 @@ scripts/
   不写具体业务逻辑
 
 - `db/`
-  作用：SQLite 连接、建表、repository
-  不写页面操作和业务编排
+  作用：数据库连接（默认 SQLite；配 `MYSQL_DSN` 时为 MySQL）、建表、repository
+  不写页面操作和业务编排；多数据源契约见 [`../references/DATA_SOURCES.md`](../references/DATA_SOURCES.md)
 
 - `service/`
   作用：核心业务逻辑
@@ -173,6 +176,7 @@ scripts/
 - `SKILL.md` 的 `metadata.openclaw.platform_kit_min_version`（当前 `1.2.11`）是运行契约/兼容性声明，供宿主安装与启用时校验，**不是** pip 依赖声明。
 - 匠厂宿主安装/更新技能后，会将技能 `requirements.txt` 安装到共享 venv：`{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。
 - **不要**在业务代码中 `subprocess` / `pip install`；缺依赖由 `health` 报错，由宿主负责安装。
+- 根目录 `sync.ps1` 是开发者手动执行的本机同步，允许用 `uv pip install` 把本技能 `requirements.txt` 装进宿主共享 venv。业务代码和其它脚本仍然不要自己装包。
 - **版本约束尽量收窄**，降低多技能共享 venv 时的冲突风险。推荐范围写法：
   - `pkg>=1.2.0,<2`
 - 对**原生扩展 / 高风险依赖**（如 `chromadb`、`onnxruntime`）建议 pin 或窄范围，避免无上限：
@@ -335,7 +339,7 @@ git remote -v
 
 应该重点写：
 
-- YAML frontmatter：`name`、`description`、`version`、`metadata.openclaw`（含 `slug`、`platform_kit_min_version`、`developer_ids` 等）
+- YAML frontmatter：`name`、`description`、`version`、`metadata.openclaw`（含 `slug`、`platform_kit_min_version`、`developer_ids`、可选 `brands` 等）
 - 何时触发本技能、CLI 入口摘要、运行契约要点
 - 指向 `references/`（Agent 调用）与 `development/`（开发规范）的分工说明
 
@@ -352,9 +356,9 @@ git remote -v
 | `DEMO.md` | 演示 | `demo_md` + frontmatter `demo_video_url` |
 | `CHANGELOG.md` | 更新日志 | 匹配当前 tag 版本的 `##` 小节 → `changelog` |
 
-**`README.md`**：能力与场景说明。含 frontmatter `description`；写能做什么、场景、准备、如何告诉 Agent、结果、注意事项、FAQ。不要写开发教程、目录规范、release、requirements。
+**`README.md`（说明 Tab）**：能力、场景、前置条件、结果形态、注意事项、概念类 FAQ。含 frontmatter `description`（**不要**写「如何开始使用」）。**禁止**分步操作、Agent 话术块、「入口一/二」专章、逐步排障——这些属教程。**禁止**文首再写 `# 技能名`（页头已有）；正文主分节用 `##`。完整契约见 [`TUTORIAL_SURFACES.md`](TUTORIAL_SURFACES.md) §0.1 / §1。
 
-**`TUTORIAL.md`**：第一次怎么用完的逐步操作。写「开始前 → 步骤 → 卡住怎么办」；不要写 CLI / 目录 / 开发规范。
+**`TUTORIAL.md`（教程 Tab）**：按 [`TUTORIAL_SURFACES.md`](TUTORIAL_SURFACES.md) 写三入口结构（数据管理 ∥ 对话；定时有则教、无则 N/A）+ 主能力对照表 + 常见卡住。步骤必须与 `REQUIREMENTS` §0.1、`actions.json` 及宿主真实 UI 对齐；**禁止**把仅 `skill-detail` 的 Action 写成用户主路径。**禁止**文首 `# 技能名 · 使用教程`；正文最高用 `##`。不要写 CLI / 目录 / 开发规范。
 
 **`DEMO.md`**：演示视频与补充说明。frontmatter 必须含 `demo_video_url`（无视频时用 `""`）；正文可选。
 
@@ -407,6 +411,51 @@ metadata:
 - 一期只做“补授权”，不会因为你 later 修改数组而自动撤销旧授权
 - **首次正式 release 前**就应配好；配错或漏配时，CI 可能成功，但你在技能市场仍找不到技能
 
+### 关于 `metadata.openclaw.brands`（OEM 市场，按需）
+
+#### 目的
+
+匠厂与华商、Lili、GDCM 等 OEM 客户端共用同一技能库，但技能市场目录按 **`market_code`** 过滤（客户端 Header `X-Market-Code`；缺省为 `jiangchang`）。
+
+发布接口 `POST /api/skill/update` 会把 `metadata.openclaw.brands` 幂等写入 `skill_market_relations`（**只补不删**）。**未声明 `brands` 时仅补默认 `jiangchang`**，因此只写在 Gitea 的 `client-huashang` 组织下、却不写 `brands: [huashang]`，华商市场仍然搜不到该技能。
+
+`brands` 与 `developer_ids` 正交：
+
+| 字段 | 管什么 |
+|------|--------|
+| `brands` | 技能出现在哪些 OEM 市场目录 |
+| `developer_ids` | 技能不公开（`access_scope = 0`）时，哪些用户仍可见并可安装 |
+
+#### 何时填写
+
+- **仅匠厂验收 / 通用技能**：可省略（默认匠厂）。
+- **须在华商或其他 OEM 客户端出现**：必须显式列出对应编码（通常同时保留 `jiangchang` 以便主站也能看到）。
+
+常见编码（小写机器码，非中文展示名）：`jiangchang`、`huashang`、`lili`、`gdcm` 等。非法编码会导致发布接口 400，CI 失败。
+
+#### 在 `SKILL.md` 中声明
+
+```yaml
+metadata:
+  openclaw:
+    slug: your-skill-slug
+    category: 通用
+    developer_ids:
+      - 12345
+    brands:
+      - jiangchang
+      - huashang
+```
+
+兼容别名（平台按优先级取第一个出现的键）：`brands` → `oem_clients` → `client_keys`。模板与文档统一推荐写 **`brands`**。
+
+约定：
+
+- **可选字段**：未写或空列表 → 行为与历史一致，只挂 `jiangchang`
+- **一期只补不删**：从 `brands` 去掉某市场后，不会自动删除库中已有关联；若需下架请走运营/后台或后续平台能力
+- **不要**指望 Gitea 组织名、目录名 `client-*` 自动映射市场
+- 发布后在对应 OEM 客户端（须带正确 `X-Market-Code`）搜索验收；也可查库 `skill_market_relations`
+
 ## 7. 文档目录分工
 
 当前规范 skill 的文档按读者拆分：
@@ -590,7 +639,7 @@ cmd_stats()                 # 只读 sync：JSON，无 job_context
 - 批量数量用 **`pickCount` / `--pick N` 参数**（任意正整数），不写死条数。
 - **顺序执行、不并发**同一浏览器 Profile / account lease。
 - **同步数据**与**宿主表导出**职责分离：同步不写 CSV/Excel；表导出交给数据管理。
-- **HTML 页面报告**（可选）：需要侧栏预览整页时，写入 `html/` + Action `render-html`；契约见 [`../references/ACTIONS.md`](../references/ACTIONS.md)「HTML 页面报告」、[`DATA_PATHS.md`](DATA_PATHS.md)；薄写入 helper 见 `scripts/service/html_page_service.py`。
+- **HTML 页面报告**（可选）：壳子页放 `assets/html/pages/*.html`，装完即进侧栏；快照才写入 `html/` + Action `render-html`。页面用 `jiangchang.call` 调已声明命令。契约见 [`../references/ACTIONS.md`](../references/ACTIONS.md)「HTML 页面报告」（含**宿主预览布局**底线）、[`DATA_PATHS.md`](DATA_PATHS.md)。快照可从 `assets/html/example-report.html` 复制壳，不要把该文件放进 `pages/`。
 - 详情见 [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md)；契约样例见 `tests/samples/test_sync_contract.py.sample`、`tests/samples/test_action_core_contract.py.sample`。
 
 ### 队列 + pick（可选）
@@ -702,6 +751,33 @@ python scripts/main.py <your-command>
 
 详见 `TESTING.md`。
 
+## 14.6 同步到本机宿主
+
+`sync.ps1` 和 `release.ps1` 并排，都在技能根目录执行。`release.ps1` 发布到服务器并触发加密打包；`sync.ps1` 把当前明文覆盖到本机已安装的技能目录，用来在宿主里验收，不必每次都走服务器构建。
+
+在技能根目录：
+
+```powershell
+.\sync.ps1
+.\sync.ps1 -DryRun
+.\sync.ps1 -SkipDeps
+.\sync.ps1 -ForceDeps
+.\sync.ps1 -SkipInitDb
+```
+
+脚本会：
+
+- 按 `SKILL.md` 的 slug 镜像到 `%USERPROFILE%\.openclaw\skills\<slug>`，排除 `.git` 等开发目录
+- 去掉安装目录里残留的 `pyarmor_runtime_*`
+- 把 `requirements.txt` 装进宿主共享 venv（与宿主安装技能同一条路径）。依赖未变时可跳过；`-SkipDeps` 只跳过安装，仍会跑 `init-db`
+- 用宿主 `settings.json` 里的当前登录用户跑 `scripts\main.py init-db`。没有登录用户时停止，不会猜用户 ID
+
+同步完成后：先停掉该技能正在跑的任务，退出资料管理再打开。不要点技能市场的「更新」，那会用加密包装掉这份明文。
+
+技能至少要从市场安装过一次，宿主才会启用它。`sync.ps1` 覆盖的是已经装上的那一份。市场上的「最新版本」仍只在 `release.ps1` 的 CI 成功后变化；本机「当前版本」来自这次同步写进去的 `SKILL.md`。
+
+`sync.ps1` 须为 UTF-8 无 BOM，且不要写中文：Windows PowerShell 5.1 会把无 BOM 的中文脚本解析错。
+
 ## 15. 发布到正式环境验证
 
 ### release workflow 通道
@@ -720,9 +796,15 @@ uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-relea
 
 在执行 `release.ps1` 之前，必须先在本地确认 `python tests/run_tests.py -v` 通过。测试不通过不得发起正式发布。
 
-**发布前必须**将 `SKILL.md` 的 `version:` 与 `scripts/util/constants.py` 的 `SKILL_VERSION` 调整为将打出的版本（例如下一 patch），再执行 `release.ps1`。`release.ps1` **不会**自动改这两个字段；漏改会造成 git tag 与技能版本号不一致。
+**POLICY-RELEASE-001（硬门禁）**：发布前必须将 `SKILL.md` 的 `version:`、`scripts/util/constants.py` 的 `SKILL_VERSION`、以及 `CHANGELOG.md` 对应小节，调整为**即将打出的**版本（与 `.\release.ps1 -DryRun` 打印的 `Next tag` 去掉 `v` 前缀一致）。`release.ps1` **不会**自动改这些字段；若三者与 Next tag 不一致，脚本在跑测试/打 tag **之前**直接失败，避免市场「最新版本」(git tag) 与安装包「当前版本」(本地 `SKILL.md`) 长期错位、技能市场一直显示「更新」。
 
-`release.ps1` 会在 **auto commit 之前**、推送 tag 之前，对**当前工作区**自动执行默认测试（`python tests/run_tests.py -v`）；失败则中止 release，不会留下失败状态的自动提交。仅紧急排障可使用 `-SkipTests` 跳过（会打印黄色警告）。`-DryRun` 预览发布时**仍会实际运行**默认测试，便于在不打 tag 的情况下验证门禁。
+建议流程：
+
+1. `.\release.ps1 -DryRun` 查看 `Next tag`（例如 `v1.0.104`）
+2. 将 `SKILL.md` / `SKILL_VERSION` / `CHANGELOG` 改为 `1.0.104`
+3. 再执行正式 `.\release.ps1`（可用 `-AutoCommit`）
+
+`release.ps1` 会在 **auto commit 之前**、推送 tag 之前，对**当前工作区**自动执行默认测试（`python tests/run_tests.py -v`）；失败则中止 release，不会留下失败状态的自动提交。仅紧急排障可使用 `-SkipTests` 跳过（会打印黄色警告）。`-DryRun` 预览发布时**仍会实际运行**版本对齐门禁与默认测试，便于在不打 tag 的情况下验证。
 
 新增或调整开发规范时，须同步 [`development/POLICY_MATRIX.md`](POLICY_MATRIX.md) 与 [`tests/test_development_policy_guard.py`](../tests/test_development_policy_guard.py)（或注明由既有测试覆盖）。
 
@@ -837,13 +919,13 @@ uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-relea
 - 长任务（async）是否有可见进度，能否取消或等待说明
 - 网页 RPA 是否有头运行；需登录/验证码时是否停下等人，而不是静默失败
 - 数据管理：表名/字段中文、按钮文案是否清楚；结果是否写回用户看得见的地方
-- 市场说明 / 教程是否与真实行为一致
+- 市场说明 / 教程是否与真实行为一致；**说明 Tab 不含分步操作**，教程覆盖已挂入口（见 [`TUTORIAL_SURFACES.md`](TUTORIAL_SURFACES.md)）
 
 | 宿主入口（侧栏 / 界面） | 技能侧如何挂上 | 建议验收什么 |
 |-------------------------|----------------|--------------|
 | **新建任务**（对话 Agent） | `placements` 含 `agent`；或短查询走共享 Python CLI | 自然语言能触发主流程；长任务 / RPA 须走 `run_skill_action`，禁止 bash 干等 |
 | **数据管理 · 表顶栏** | `placements` 含 `toolbar`（须合法非空 `bind.tables`） | 左侧能看到本技能库表；表顶栏出现按钮；点按行为符合预期 |
-| **数据管理 · HTML 报告** | 写出 `html/*.html`；提供 Action id `render-html` | 侧栏出现报告项；预览正常；右键「重新生成」成功且时间/内容更新 |
+| **数据管理 · HTML 报告** | 壳子页放 `assets/html/pages/*.html`；快照写出 `html/*.html` 并提供 `render-html` | 壳子装完即现、右键无「重新生成」；快照可重新生成；页面 `jiangchang.call` 能拿到 JSON |
 | **数据管理 · 行级** | `placements` 含 `row`（建议 `bind.tables` + `bind.inputMapping` 预填主键） | 操作列和/或行右键（及可选「⋯」）出现本技能行级 Action（需有主键列）；点按后入参/行为与壳无关、均正确 |
 | **数据管理 · 批量** | `placements` 含 `batch` | 勾选行后批量按钮可用；无勾选时禁用；批量行为正确 |
 | **定时任务** | `placements` 含 `cron`（创建时选「技能直调」） | 能选到本技能 Action、保存并触发；到点或「立即运行」行为正确 |
@@ -874,16 +956,18 @@ uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-relea
 每个新 skill 发布前，建议技术人员逐条确认：
 
 - [ ] 目录结构符合当前模板
-- [ ] slug 符合 [`NAMING.md`](NAMING.md)（verb-noun-platform）
+- [ ] slug 符合 [`NAMING.md`](NAMING.md)（动词-名词，平台可选；不要用 `default` 占位）
 - [ ] 目录名、`SKILL.md` slug、`constants.SKILL_SLUG` 三者一致
 - [ ] `SKILL.md` 中 slug、名称、描述都已替换
 - [ ] `SKILL.md` 的 `developer_ids` 已换成**本人**匠厂用户 ID（设置 → 用户信息 → 复制），不是模板示例 ID
+- [ ] 若须在华商等 OEM 市场出现：`SKILL.md` 的 `brands` 已声明（如 `jiangchang` + `huashang`）；未写则仅匠厂；不要用 Gitea 组织名代替
 - [ ] `scripts/util/constants.py` 已修改
 - [ ] `../references/CLI.md` 示例命令已改成真实命令
 - [ ] `service` 下的核心业务文件（如 `task_service.py`）已按领域改名并实现
 - [ ] 没有残留旧平台名
 - [ ] `health` / `version` 可运行
 - [ ] `.env.example` 注释已按 [`CONFIG.md`](CONFIG.md)「行头 = 是什么、行尾 = 怎么填」写全（面向配置管理用户；无 `见 development/...` 等开发文档指向）
+- [ ] 业务必填项已在 `.env.example` 用独立一行 `# @required` 标记（见 [`CONFIG.md`](CONFIG.md) §必填项）；未标则宿主不显示红色 `*`
 - [ ] `.gitignore` 生效，没有把 `__pycache__` 提交进去
 - [ ] `release.ps1` 存在（发布前会自动跑 `python tests/run_tests.py -v`；失败不得打 tag）
 - [ ] `.github/workflows/release_skill.yaml` 存在

development/LOGGING.md

@@ -122,9 +122,35 @@ RPA 等待用 `interruptible_sleep`，**不要**裸 `asyncio.sleep`（否则暂
 
 Journal 会写入 `type: lifecycle` 事件（`paused` / `resumed` / `stopping`），供宿主任务中心显示状态。
 
-### 2.3 业务表（可选，不是默认排障通道）
+**宿主中断（`stop`）与 `JobStopped`（必读）：**
 
-模板**默认不建**任务审计表。业务结果写入各技能自己的业务表；过程看 `jiangchang.log`，进度/终态看任务中心。
+- 用户在任务中心点「中断」时，宿主写入 `control.json` `command=stop`，并**等待技能进程协作退出**（超时后才可能强杀）。
+- 技能在 `emit` / `checkpoint` / `interruptible_sleep` / `rpa_step` 等闸门处会抛出 `JobStopped`；业务代码须让其冒泡到 `job_context` / 外层 `finally`，由技能**自己**释放租约、关闭浏览器等资源。
+- **禁止**用裸 `except Exception:` 包住上述闸门调用。`JobStopped` 是 `Exception` 子类，会被吞掉，导致 UI 已停、进程仍占账号租约，下次采集必 `LEASE_CONFLICT`。
+- 若必须兜底「emit 写 Journal 失败」，正确写法：
+
+```python
+from jiangchang_skill_core.activity import JobStopped, emit
+
+try:
+    emit("正在处理…", skill=SKILL_SLUG, stage="fetch")
+except JobStopped:
+    raise
+except Exception:
+    log.debug("emit_failed", exc_info=True)
+```
+
+- 宿主**不会**按技能类型统一代收 account-manager 租约（许多技能根本不用账号管理）。强杀后的残留靠租约 TTL / 数据管理手工 force-release；主路径必须是技能自清。
+
+### 2.3 可观测性三分法（禁止 task_logs）
+
+| 信息类型 | 去哪里 | 技能怎么做 |
+|----------|--------|------------|
+| **过程**（步骤、异常栈、排查） | `jiangchang.log` / 宿主「运行日志」 | `log.info` / `log.exception`，关键节点见 §3 |
+| **进度 / 终态**（任务中心） | Run Journal：`emit` / `finish` | `job_context` + `finish(status=...)` |
+| **业务结果** | 业务表字段（status、产物路径、统计等） | repository 回写；见 [`WORK_ITEM_STATUS.md`](../references/WORK_ITEM_STATUS.md) |
+
+模板**默认不建** `task_logs` 等通用任务审计表。**不要**用业务表冒充任务进度，也不要用任务表代替业务状态机。
 
 ### 2.4 RPA video step / artifacts（用户可见动作与存证）
 

development/NAMING.md

@@ -13,23 +13,24 @@
 | ❌ **不修改** | 其他仓库（尤其 `account-manager`）不在本文约束范围内 |
 | ✅ **模板占位** | 模板本体的 `your-skill-slug` 占位必须继续通过全部测试 |
 
-**新技能勿仿**历史 2 段无平台形态（如 `reconcile-finance`）或不符合 verb-noun-platform 的旧 repo 名；校验器对历史 repo **不追溯**，但规范中明确标注为反模式。
+**新技能**使用「动词-名词」，外部平台可选。不要再为了凑段数追加 `default`。校验器不追溯已上线仓库；已经发布、末尾是 `default` 的技能不用改名。
 
 ---
 
 ## 2. 命名格式
 
-标准形态（约 95% 新技能）：
+标准形态：
 
 ```text
-{verb}-{noun-phrase}-{platform}
+{verb}-{noun-phrase}
+{verb}-{noun-phrase}-{platform}    # 仅当技能绑定外部平台时
 ```
 
 | 部分 | 规则 |
 |------|------|
 | **verb** | 1 个词，来自 [动词白名单](#5-动词白名单) |
 | **noun-phrase** | 1～3 个词（按 `-` 分段），描述业务对象 |
-| **platform** | 1 个词，来自 [平台白名单](#6-平台白名单)；可含连字符（如 `single-window`） |
+| **platform** | **可选**。没有抖音、小红书、亚马逊这类外部系统时省略。有平台时 1 个词，来自 [平台白名单](#6-平台白名单)；可含连字符（如 `single-window`） |
 
 **展示层分工不变：**
 
@@ -44,8 +45,8 @@
 
 | 约束 | 值 |
 |------|-----|
-| 格式 | `{verb}-{noun-phrase}-{platform}`（标准型，默认） |
-| 总段数（按 `-` 分割） | **3～5 段**（标准型）；scope 型见 [§4](#4-三类合法形态) |
+| 格式 | `{verb}-{noun-phrase}`；有外部平台时才加 `-{platform}` |
+| 总段数（按 `-` 分割） | **2～5 段** |
 | 总长度 | **≤ 48 字符** |
 | 字符集 | 小写字母、数字、连字符；kebab-case |
 | 禁止 | 中文 slug、下划线、**平台放最前**（如 `amazon-download-xxx`） |
@@ -56,12 +57,26 @@
 
 ## 4. 三类合法形态
 
-### 4.1 标准型（95%）
+### 4.1 无平台（常见）
 
-`verb-noun-platform` 或 `verb-noun-noun-platform`（3～5 段）
+`verb-noun` 或 `verb-noun-noun`（2～4 段）
 
 - 第 1 段 ∈ 动词白名单
-- 最后 1 段（或 hyphenated 平台的最后 2 段）∈ 平台白名单
+- 其余为 noun-phrase（1～3 段）
+- **不要**追加 `default`
+
+示例：
+
+- `generate-monthly-statements`
+- `reconcile-finance`
+- `process-article`
+
+### 4.2 标准型（绑定外部平台）
+
+`verb-noun-platform`（在无平台形态后加平台，总段数仍 ≤ 5）
+
+- 第 1 段 ∈ 动词白名单
+- 最后 1 段（或 hyphenated 平台的最后若干段）∈ 平台白名单
 - 中间为 noun-phrase（1～3 段）
 
 示例：
@@ -71,19 +86,19 @@
 - `enter-sales-receipt-kingdee`
 - `fill-export-declaration-single-window`
 
-### 4.2 scope 型（少见）
+### 4.3 scope 型（少见）
 
 `verb-noun-scope`
 
-- 最后 1 段 ∈ scope 白名单：`all` | `batch` | `multi` | `default`
+- 最后 1 段 ∈ scope 白名单：`all` | `batch` | `multi`
 - 第 1 段 ∈ 动词白名单
-- 总段数 3～5
+- 至少还有一段名词（因此最少 3 段）
 
 示例：`generate-article-all`
 
-> 说明：`geo-generate-article-all` 若作为新技能且不在豁免表、首段 `geo` 不在动词表，应写为 `generate-article-all`。
+> `default` 已从 scope 词表移除。它不是平台，也不表示范围。新技能不要写 `generate-article-default` 这类占位。已发布且末尾为 `default` 的仓库保持原 slug；同步本校验后只会警告，不会因此失败。
 
-### 4.3 历史豁免（不校验语义）
+### 4.4 历史豁免（不校验语义）
 
 以下 slug 跳过 verb/platform 语义校验（见 `LEGACY_EXEMPT_SLUGS`）：
 
@@ -121,7 +136,7 @@
 | lianlian | single-window | export-rebate |
 | etax | | |
 
-scope 词表：[`assets/naming/scopes.txt`](../assets/naming/scopes.txt) — `all`、`batch`、`multi`、`default`
+scope 词表：[`assets/naming/scopes.txt`](../assets/naming/scopes.txt) — `all`、`batch`、`multi`。不含 `default`。
 
 ---
 
@@ -164,7 +179,7 @@ slug **末段 platform** 与 `account-manager` 中的 `platform_key` **语义对
 
 ## 9. 复制新技能流程
 
-1. **先定 slug** — 按本文规范拟定 `{verb}-{noun-phrase}-{platform}`，确认在白名单内且 ≤ 48 字符
+1. **先定 slug** — `{verb}-{noun-phrase}`，仅在绑定外部平台时加 `-{platform}`。确认动词/平台在白名单内且 ≤ 48 字符。不要用 `default` 占位。
 2. **复制目录** — **推荐** [`tools/scaffold_skill.ps1`](../tools/scaffold_skill.ps1)（`-Slug` 与目录名一致）；勿整包复制带走 `.git`
 2.5. **清理 Git（若未用 scaffold）** — 删除 `.git`、`.openclaw-skill-template`、`.pytest_cache`；再 `git init` 与 `git remote add origin`
 3. **全局替换** — `your-skill-slug` → 新 slug；更新 `SKILL.md`、`constants.py`、文档中的占位
@@ -179,10 +194,12 @@ slug **末段 platform** 与 `account-manager` 中的 `platform_key` **语义对
 
 | slug | 说明 |
 |------|------|
-| `download-settlement-report-amazon` | 标准型，4 段 |
-| `add-product-shopee` | 标准型，3 段 |
-| `enter-sales-receipt-kingdee` | 标准型 |
-| `fill-export-declaration-single-window` | 标准型，平台含连字符 |
+| `generate-monthly-statements` | 无平台 |
+| `reconcile-finance` | 无平台，动词 + 一个名词 |
+| `download-settlement-report-amazon` | 有平台 |
+| `add-product-shopee` | 有平台 |
+| `enter-sales-receipt-kingdee` | 有平台 |
+| `fill-export-declaration-single-window` | 有平台，平台含连字符 |
 | `generate-article-all` | scope 型 |
 
 ### ❌ 反例
@@ -191,7 +208,7 @@ slug **末段 platform** 与 `account-manager` 中的 `platform_key` **语义对
 |------|------|
 | `amazon-download-settlement-report` | 平台在最前 |
 | `enter-cross-border-sales-receipt-voucher-kingdee` | 过长、noun 臃肿 |
-| `reconcile-finance` | 新技能禁止 2 段无平台 |
+| `generate-article-default` | `default` 不是平台；应写成 `generate-article` |
 | `download_settlement_amazon` | 非 kebab-case（下划线） |
 
 ---
@@ -201,14 +218,14 @@ slug **末段 platform** 与 `account-manager` 中的 `platform_key` **语义对
 - **平台前置**：`amazon-download-...`、`shopee-add-...`
 - **英文占位 name**：复制后仍保留 `My Skill` 或纯英文 slug 风格名称
 - **只改目录名**：`SKILL.md` slug 与 `constants.SKILL_SLUG` 未同步
-- **noun 堆砌**：中间段过多导致超 48 字符或难以阅读
-- **仿历史 2 段 repo**：`reconcile-finance`、`content-manager` 等
+- **用 default 占位**：`generate-article-default`。没有外部平台就省略末段
+- **名词堆砌**：中间段过多导致超 48 字符或难以阅读
 
 ---
 
 ## 12. 演进说明（当前不启用）
 
-当技能库规模 **> 200** 时，可再评估引入 `{domain}-verb-noun-platform` 前缀形态。**当前不启用**，新技能一律使用本文 verb-noun-platform 标准型或 scope 型。
+当技能库规模 **> 200** 时，可再评估引入 `{domain}-verb-noun-platform` 前缀形态。**当前不启用**。新技能使用动词-名词；只有绑定外部平台时才使用 verb-noun-platform，或使用 scope 型。
 
 ---
 
@@ -218,9 +235,9 @@ slug **末段 platform** 与 `account-manager` 中的 `platform_key` **语义对
 
 | 历史 slug | 说明 |
 |-----------|------|
-| `account-manager` | 跨平台账号管理，非 verb-noun-platform |
-| `reconcile-finance` | 2 段无 platform |
-| `scrape-contacts-lianjia` | 平台名不在当前白名单（链家） |
+| `account-manager` | 跨平台账号管理，非动词-名词 |
+| `reconcile-finance` | 现已是合法的无平台形态；旧文档曾把它标成反例 |
+| `scrape-contacts-lianjia` | 平台名不在当前白名单（链家）；新技能若要表达链家，先把平台加入白名单 |
 | `skill-template` | 模板仓库本身 |
 
 校验器通过 `LEGACY_EXEMPT_SLUGS` 对模板占位与少数豁免 slug 跳过语义检查；**新复制出去的业务 skill 不在豁免表内**，必须满足 §3 硬约束。

development/POLICY_MATRIX.md

@@ -9,11 +9,12 @@
 | POLICY-RUNTIME-002 | `requirements.txt` 非注释依赖行不得声明 `jiangchang-platform-kit` / `playwright` | development/RUNTIME.md §共享 Python Runtime；development/DEVELOPMENT.md §3.1 requirements.txt 依赖规范 | hard | 解析依赖行 | `tests/test_development_policy_guard.py::TestPolicyRuntime002`（另见 `tests/test_platform_import.py`） |
 | POLICY-RUNTIME-003 | Agent/CLI 文档须要求共享 Python（python-runtime / PATH 上的 `python` + `{baseDir}`）；须明确**禁止**对技能脚本使用 `uv run python` | development/RUNTIME.md；references/CLI.md；SKILL.md | hard | 文档标记扫描 | `tests/test_docs_standards.py::test_cli_md_requires_shared_python_not_uv_run`；`tests/test_docs_standards.py::test_skill_md_requires_shared_python_not_uv_run` |
 | POLICY-AGENT-001 | `SKILL.md` 须含「用户意图路由表」结构；`CLI.md` 须含短 CLI 白名单 / Action 强制黑名单表；用法回答须禁止无故粘贴 CLI、禁止为答用法列目录挖 references | SKILL.md；references/CLI.md | hard | 文档标记扫描 | `tests/test_docs_standards.py::test_skill_md_has_intent_routing_table`；`tests/test_docs_standards.py::test_cli_md_has_agent_routing_tables`；`tests/test_docs_standards.py::test_skill_md_how_to_forbids_cli_paste` |
-| POLICY-INSTALL-001 | 交付执行文件不得含 `pip install` / `python -m pip install` / `uv pip install` / `playwright install` | development/RUNTIME.md §共享 Python Runtime；development/RPA.md §1.4 Playwright 与安装边界；development/DEVELOPMENT.md §3.1 | hard | 扫描 `scripts/**/*.py`、`*.ps1`、`*.sh`、`requirements.txt`、`.github/workflows/*`（不扫 `development/*.md`） | `tests/test_development_policy_guard.py::TestPolicyInstall001` |
+| POLICY-INSTALL-001 | 交付执行文件不得含 `pip install` / `python -m pip install` / `uv pip install` / `playwright install` | development/RUNTIME.md §共享 Python Runtime；development/RPA.md §1.4 Playwright 与安装边界；development/DEVELOPMENT.md §3.1 | hard | 扫描 `scripts/**/*.py`、`*.ps1`、`*.sh`、`requirements.txt`、`.github/workflows/*`（不扫 `development/*.md`；根目录 `sync.ps1` 除外，它是开发者手动执行的本机同步，用 `uv pip install` 装进宿主共享 venv） | `tests/test_development_policy_guard.py::TestPolicyInstall001` |
 | POLICY-CONFIG-001 | 仓库根目录必须存在 `.env.example` | development/CONFIG.md §核心原则、§标准配置项 | hard | 文件存在性 | `tests/test_development_policy_guard.py::TestPolicyConfig001` |
 | POLICY-CONFIG-002 | `.gitignore` 必须忽略 `.env` 与 `*.env.local` | development/CONFIG.md §红线：敏感信息不进 .env | hard | 解析 `.gitignore` 行 | `tests/test_development_policy_guard.py::TestPolicyConfig002` |
 | POLICY-CONFIG-003 | 业务代码不得直接 `os.environ` / `os.getenv` / `os.putenv` / `environ.get`；须经 `jiangchang_skill_core.config.get*`（允许 `main.py`、测试、config_bootstrap/runtime 边界文件） | development/CONFIG.md §配置 bootstrap；development/ADAPTER.md §档位 dispatch | hard | 扫描 `scripts/**/*.py` 并排除边界文件 | `tests/test_development_policy_guard.py::TestPolicyConfig003` |
 | POLICY-CONFIG-004 | `.env.example` 每个活跃 `KEY=` 必须有中文**行头**（是什么）与中文**行尾**（怎么填）；注释禁止 `development/`、`*.md` 文档指向、`account-manager`、`adapter 档位` 等开发黑话 | development/CONFIG.md §.env.example 注释 = 配置管理用户文案 | hard | 解析 `.env.example` 活跃行与注释 | `tests/test_development_policy_guard.py::TestPolicyConfig004` |
+| POLICY-CONFIG-005 | 若 `.env.example` 使用 `# @required`，须单独占一行且在下一行中文行头之上；禁止写在行尾；禁止无中文行头或多 key 共用 | development/CONFIG.md §必填项：# @required | hard | 解析 `.env.example` 活跃行与 `@required` 标记 | `tests/test_development_policy_guard.py::TestPolicyConfig005` |
 | POLICY-TESTING-001 | 默认根目录 `tests/test_*.py` 不得硬编码 `real_api` / `real_rpa` / `OPENCLAW_TEST_TARGET`（白名单仅 `test_adapter_profile_policy.py`，用于档位 helper 自测） | development/TESTING.md §默认必跑测试要做什么、§4 测试目标档位 | hard | 扫描 `tests/test_*.py` 非注释行；白名单外禁止上述文本 | `tests/test_development_policy_guard.py::TestPolicyTesting001` |
 | POLICY-TESTING-002 | `tests/integration/` 下 Python 测试文件若存在，默认应为 `.sample`，不得进入默认套件 | development/TESTING.md §7 真实联调测试的安全约束、§8 新 skill 的最小测试清单 | hard | 检查 `tests/integration/*.py` 无 `.sample` 后缀 | `tests/test_development_policy_guard.py::TestPolicyTesting002` |
 | POLICY-RPA-001 | 不得 import/use account-manager 内部 `rpa_helpers` / `inject_account_manager_scripts_path` / `get_account_credential` | development/ADAPTER.md §兄弟依赖；development/RPA.md §1.7 | hard | 扫描 `scripts/**/*.py` 禁止模式 | `tests/test_development_policy_guard.py::TestPolicyRpa001`（另见 `tests/test_no_rpa_helpers_import.py`） |
@@ -22,8 +23,10 @@
 | 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-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 行 | development/DEVELOPMENT.md §3.4 发布打包约束；development/RUNTIME.md §发布打包约束 | hard | 行数统计 | **已有测试覆盖**：`tests/test_release_packaging_constraints.py::test_scripts_py_files_under_pyarmor_line_limit` |
 | 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` |
 | POLICY-LOGGING-001 | CLI 入口必须调用 `setup_skill_logging` | development/LOGGING.md；development/RUNTIME.md | hard | 扫描 `scripts/cli/app.py` 含 `setup_skill_logging` 与 logger info | `tests/test_development_policy_guard.py::TestPolicyLogging001` |
 | POLICY-LOGGING-002 | service 主任务入口必须使用 `get_skill_logger` | development/LOGGING.md；development/DEVELOPMENT.md | hard | 扫描 `scripts/service/task_service.py` | `tests/test_development_policy_guard.py::TestPolicyLogging002` |
@@ -41,6 +44,7 @@
 | POLICY-SKILL-ACTION-002 | 每个 Action 必须显式声明 `executionProfile`，且只能是 `sync` 或 `async` | development/SKILL_ACTION_RUNTIME.md；references/ACTIONS.md；assets/schemas/skill-actions.schema.json | hard | schema required + manifest 扫描 | `tests/test_development_policy_guard.py::TestPolicySkillAction002`；`tests/test_actions_manifest.py` |
 | POLICY-SKILL-ACTION-003 | toolbar Action 必须声明合法非空 `bind.tables`（snake_case、唯一） | references/ACTIONS.md；assets/schemas/skill-actions.schema.json | hard | schema if/then + manifest 扫描 | `tests/test_development_policy_guard.py::TestPolicySkillAction003`；`tests/test_actions_manifest.py` |
 | POLICY-SKILL-ACTION-004 | `placements` 与 `executionProfile` 正交；文档不得把数据管理入口与异步执行方式硬绑定；Schema 须接受 toolbar/row/batch/cron/agent/skill-detail × sync/async 全部组合 | development/SKILL_ACTION_RUNTIME.md；references/ACTIONS.md；assets/schemas/skill-actions.schema.json | hard | Schema 6×2 矩阵校验 + 文档禁止短语扫描 | `tests/test_actions_manifest.py::test_schema_allows_all_placement_execution_profile_combinations`；`tests/test_development_policy_guard.py::TestPolicySkillAction004` |
+| POLICY-TUTORIAL-001 | 存在 `development/TUTORIAL_SURFACES.md`；`TUTORIAL.md` 须含数据管理/对话/定时/对照表骨架；`README.md` 禁止「告诉 Agent」专章与入口专章；说明/教程正文禁止与页头重复的 `#` H1（主分节用 `##`）；业务技能教程与 `actions.json` placements 对齐（无 cron 须声明不需要定时） | development/TUTORIAL_SURFACES.md；development/CHECKLIST.md A2-7～A2-12 | hard | 文档存在性 + 章节/反模式扫描 + placements 对齐 | `tests/test_tutorial_surfaces.py`；`tests/test_docs_standards.py::test_tutorial_surfaces_contract_doc_and_checklist` |
 | POLICY-ARCH-CORE-001 | 同一业务能力的 Action、CLI、Agent、cron、数据管理入口复用同一业务内核（文档要求已声明） | development/DEVELOPMENT.md；development/SKILL_ACTION_RUNTIME.md | hard（文档标记） / soft（语义） | 文档关键表述存在性；真实复用靠 sample/review | `tests/test_development_policy_guard.py::TestPolicyArchCore001`；`tests/samples/test_action_core_contract.py.sample` |
 | POLICY-DATA-SYNC-001 | 同步型业务须遵循幂等、事务、完整性与空结果保护（文档已声明） | references/SCHEMA.md；development/SKILL_ACTION_RUNTIME.md | hard（文档标记） / soft（语义） | 文档关键表述存在性；完整语义靠 sample/review | `tests/test_development_policy_guard.py::TestPolicyDataSync001`；`tests/samples/test_sync_contract.py.sample` |
 
@@ -58,7 +62,7 @@
 | 是否满足完整快照语义 / 空结果保护实现 | references/SCHEMA.md | 见 `test_sync_contract.py.sample` |
 | 是否把系统导出与业务同步混淆 | references/ACTIONS.md；SCHEMA.md | 文档 + sample；勿做源码关键词误报扫描 |
 | `db/` 层不得调浏览器或拼业务流程 | development/DEVELOPMENT.md §11 | 需跨文件调用图 |
-| slug 命名语义（verb-noun-platform） | development/NAMING.md | 部分覆盖于 `tests/test_slug_naming.py`，非本矩阵 hard policy |
+| slug 命名语义（动词-名词，平台可选） | development/NAMING.md | 部分覆盖于 `tests/test_slug_naming.py`，非本矩阵 hard policy |
 | 复制模板不得保留 `.git` / template marker | development/DEVELOPMENT.md §4 | 由 `tests/test_scaffold_guard.py` 守护，属脚手架场景 |
 | 共享 runtime 导入来源非技能目录 | development/RUNTIME.md | 运行时依赖已安装包，见 `tests/test_platform_import.py` |
 | RPA 真实轨迹、选择器纪律、状态等待、HITL 超时与有限重试是否正确实现 | development/AI_RPA.md；development/RPA.md §0–§1 | 文档和默认节奏已守护，真实行为与 DOM 质量仍需人工验收 |
@@ -67,6 +71,7 @@
 | `SKILL.md` / `constants.SKILL_SLUG` 一致性 | development/DEVELOPMENT.md §16 | 已有 `tests/test_skill_metadata.py` |
 | platform_kit_min_version >= 1.2.11 | development/RUNTIME.md | 已有 `tests/test_platform_import.py` |
 | 宿主按 `bind.tables` 过滤 toolbar 按钮 | references/ACTIONS.md | 待宿主升级后完整生效；模板侧已强制显式绑定 |
+| form +「已选择」时映射 `readOnly` 默认不占参数区（仍提交）；`revealInForm` 逃生阀 | references/ACTIONS.md「选择摘要」 | soft（宿主 UX）；文档与 schema 已声明；勿用 `visibleWhen` 代替 |
 | 数据管理技能按钮中文名（`label`）对照 ACTIONS.md 建议表；打开类成功静默 | references/ACTIONS.md「Action 按钮中文名」 | 参考非白名单；行业词允许自创；勿做 label 关键字扫描 |
 | Data Policy 未启用（L0）时宿主不得拉 Snapshot / 不得改按钮与行列行为 | references/POLICY.md | soft；宿主实现契约 |
 | Data Policy 启用后 fail-closed（禁止回退 L0 全开）；写路径 domain 必须再鉴权 | references/POLICY.md §6–§7 | soft；`POLICY-SKILL-AUTHZ-*` 硬门禁可后续加 |

development/PRODUCT_SURFACES.md

@@ -164,9 +164,25 @@
 
 ---
 
-## 7. 相关文档
+## 7. 用户教程如何投影本文
+
+入口定位表填完后，**必须**落到用户市场文档（见 [`TUTORIAL_SURFACES.md`](TUTORIAL_SURFACES.md)）：
+
+| 定位结果 | `TUTORIAL.md` | `README.md` |
+|----------|---------------|-------------|
+| 挂数据管理 | 「入口一」专章 + 表/按钮步骤 | 仅一句「支持数据管理」 |
+| 挂对话 | 「入口二」专章 + 话术 | 仅一句「支持对话」；**禁止**话术块 |
+| 挂定时 | 「入口三」教怎么建 | 可选一句边界 |
+| 不挂定时 | 「入口三」写不需要 + 理由 | 可选一句「不提供定时」 |
+
+准备/载入类 Action：优先 `toolbar` + `bind.tables`，避免教程写「技能详情点按钮」而宿主详情页不渲染。
+
+---
+
+## 8. 相关文档
 
 - 需求里填定位表：[`REQUIREMENTS.md`](REQUIREMENTS.md)
+- **用户说明 / 教程怎么写：** [`TUTORIAL_SURFACES.md`](TUTORIAL_SURFACES.md)
 - 交活怎么验：[`CHECKLIST.md`](CHECKLIST.md)
 - 开发步骤中的 Action 挂载：[`DEVELOPMENT.md`](DEVELOPMENT.md) §11.5、§15
 - Agent 侧字段契约：[`../references/ACTIONS.md`](../references/ACTIONS.md)

development/README.md

@@ -10,10 +10,12 @@
 |------|--------|------|
 | 1 | **拿到仓库**：① 项目经理在 [自建 Gitea](https://git.jc2009.com/)（`git.jc2009.com`，非 Gitea 官网）开仓并授权后 `git clone`；或 ② 本地已有 `skill-template` 时用 scaffold / 复制出新目录（遵守 Git 红线） | [`DEVELOPMENT.md`](DEVELOPMENT.md) §1、§4 |
 | 2 | **先读宿主产品入口**：对话 / 数据管理 / 定时任务平级；何时走哪个；为本技能填入口定位表 | [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md) |
+| 2b | **用户市场文档**：说明 Tab ≠ 教程 Tab；教程按三入口写；与 §0.1 / actions 对齐 | [`TUTORIAL_SURFACES.md`](TUTORIAL_SURFACES.md) |
 | 3 | **先读 AI + RPA 总纲**；界面技能先完成元素拾取/element map，再按浏览器、桌面或手机读分端手册 | [`AI_RPA.md`](AI_RPA.md)、[`RPA_ELEMENT_LOCATING.md`](RPA_ELEMENT_LOCATING.md) |
 | 4 | 按 [`NAMING.md`](NAMING.md) 确认 slug；**先填** [`REQUIREMENTS.md`](REQUIREMENTS.md)（含入口定位表），再写业务代码 | [`REQUIREMENTS.md`](REQUIREMENTS.md)、[`NAMING.md`](NAMING.md) |
 | 5 | 替换标识与占位，按四象限 / examples 实现 `scripts/service/` | [`DEVELOPMENT.md`](DEVELOPMENT.md) §4～§14 |
 | 6 | **配置 `developer_ids`（开发自测必做）**：开发期技能在匠厂默认不公开；不加则开发者自己也装测不了。从宿主设置复制用户 ID 写入 `SKILL.md` | [`DEVELOPMENT.md`](DEVELOPMENT.md) §6「关于 developer_ids」 |
+| 6b | **按需配置 `brands`（OEM 市场）**：须在华商等 OEM 客户端出现时声明 `brands`（如 `jiangchang` + `huashang`）；未写则仅挂匠厂。Gitea 组织名不会自动映射市场 | [`DEVELOPMENT.md`](DEVELOPMENT.md) §6「关于 brands」 |
 | 7 | 本地单测（mock）通过后，按业务默认 **`real_rpa`** 真实跑通；再 `release.ps1`；看 Gitea CI。**mock 通 ≠ 完成** | [`ADAPTER.md`](ADAPTER.md)；[`DEVELOPMENT.md`](DEVELOPMENT.md) §15 |
 | 8 | 匠厂安装后，按**入口定位表已挂**的入口自测，并看**用户体验**（进度、失败提示、有头 RPA 等） | [`DEVELOPMENT.md`](DEVELOPMENT.md) §15；[`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md)；[`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md) |
 | 9 | **交活验收（第三方）**：对照 [`CHECKLIST.md`](CHECKLIST.md) 验收；报告写入仓库根目录 [`acceptance-reports/`](../acceptance-reports/) | [`CHECKLIST.md`](CHECKLIST.md) |
@@ -27,6 +29,7 @@
 开始定制 skill 前，建议按以下顺序阅读：
 
 1. [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md) — **宿主产品入口**：对话 / 数据管理 / 定时任务平级；何时走哪个；入口定位表
+1b. [`TUTORIAL_SURFACES.md`](TUTORIAL_SURFACES.md) — **用户说明 / 教程契约**：README≠TUTORIAL；三入口结构；skill-detail 不可作主路径
 2. [`AI_RPA.md`](AI_RPA.md) — **AI Agent + RPA 总纲**：职责边界、合规红线、风控、操作节奏与完整闭环
 3. [`ACCOUNT_MANAGER.md`](ACCOUNT_MANAGER.md) — **浏览器账号标准**：一账号一 Profile、租约、多账号、数据查看、验收与排障
 4. [`SHARED_REPOS.md`](SHARED_REPOS.md) — **公共仓库目录**（模板 / 账号管理 / platform-kit 等，可扩展）

development/REQUIREMENTS.md

@@ -23,6 +23,7 @@
 - 中文 description（一句话）：
 - account-manager platform_key（如有）：
 - 命名形态：标准型 / scope 型
+- **目标 OEM 市场 `brands`（可选）**：未写则发布后仅挂匠厂（`jiangchang`）。须在华商等 OEM 客户端可见时填写，例如 `jiangchang`、`huashang`（见 `DEVELOPMENT.md` §6「关于 brands」）。**不要**用 Gitea 组织名代替本字段。
 - **网页 RPA（如有）— 登录策略（三选一，须写明）：**
   - `required`：目标站必须登录才能闭环（用户须完成/保持站点登录；技能每轮主路径须有登录门禁 + 验证码/人工等待）
   - `optional`：登录可提升能力，但不登录也能完成主路径（**仅当**公开页确可闭环时选用；会话依赖型采集/评论/私信**禁止**默认抄成 optional）
@@ -33,19 +34,26 @@
 
 ## 0.1 宿主入口定位（必填）
 
-先读 [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md)。对话任务 / 数据管理 / 定时任务在宿主上**平级**；挂哪些由本技能业务与 UX 定，模板不规定「必须三入口都挂满」。
+先读 [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md)。对话任务 / 数据管理 / 定时任务在宿主上**平级**；挂哪些由本技能业务与 UX 定，模板不规定「必须三入口都挂满」。用户文档如何写见 [`TUTORIAL_SURFACES.md`](TUTORIAL_SURFACES.md)。
 
 对每个主能力填一行（可增行；「不挂」必须写理由）：
 
-| 主能力（Action id / CLI） | 对话 | 数据管理 | 定时 | 不挂理由（若不挂） |
-|---------------------------|------|----------|------|--------------------|
-| （例）`<action-or-cli>` | 挂 / 不挂 | 不挂 / toolbar / row / batch / replaces / 仅展示表 | 挂 / 不挂 | |
+| 主能力（Action id / CLI） | 对话 | 数据管理 | 定时 | 教程章节 | 不挂理由（若不挂） |
+|---------------------------|------|----------|------|----------|--------------------|
+| （例）`<action-or-cli>` | 挂 / 不挂 | 不挂 / toolbar / row / batch / replaces / 仅展示表 | 挂 / 不挂 | 入口一 / 入口二 / 入口三 / N/A | |
 
 说明：
 
 - 数据管理列可写组合（如 `toolbar + row`）
 - 「仅展示表」= 用户要看过程/结果，但不在表上触发该能力
 - 定位为「挂」的入口须在 `assets/actions.json`（及必要表元数据）中落实，并与对话路径共用同一 domain service
+- **教程章节**：该能力在 `TUTORIAL.md` 中落在哪一节；整技能无定时时，入口三仍须写「不需要 + 理由」
+
+### 0.1.1 用户市场文档（与入口表一致）
+
+- `README.md`（说明 Tab）：只写能力 / 场景 / 边界；**禁止**分步操作与 Agent 话术（见 `TUTORIAL_SURFACES.md` §1）
+- `TUTORIAL.md`（教程 Tab）：覆盖 §0.1 中所有「挂」的入口；准备/载入类优先数据管理 toolbar，**不要**把 skill-detail 当主路径
+- 定位为「不挂」定时：教程须有 N/A 声明，与本表理由一致
 
 ## 0.2 AI + RPA 协作与授权边界（涉及外部系统时必填）
 
@@ -244,7 +252,9 @@
 - `tests/test_display_metadata.py` 通过
 - 真实联调样例仍放 `tests/integration/`，默认套件不包含真实外联（与业务 `.env` 默认 `real_rpa` 不冲突）
 - `SKILL.md` 的 `developer_ids` 已配置为开发者本人匠厂用户 ID（开发期不公开时，否则本人无法在市场安装自测；取 ID 步骤见 `development/DEVELOPMENT.md` §6）
+- 若目标含华商等 OEM 客户端：`SKILL.md` 的 `brands` 已声明对应 `market_code`（通常含 `jiangchang` + 目标 OEM）；未写则仅匠厂市场可见
 - 发布后 Gitea 工作流成功；匠厂技能市场对开发者账号可见最新版本并可安装
+- 若声明了 OEM `brands`：在对应 OEM 客户端（`X-Market-Code` 正确）也能检索到该技能
 - 安装后按本技能入口定位表与 `actions.json` 声明完成宿主多入口验收（见 `development/DEVELOPMENT.md` §15、`PRODUCT_SURFACES.md`）；**须看用户体验**（进度可见、失败可读、RPA 有头、文案与真实行为一致等），后台通了不算完
 - 已人工核验授权与技术路线：无破解、逆向、私有协议、验证码绕过、Hook / 注入、自动换号或其他规避平台限制的实现
 - RPA 真实主路径已验证状态等待、`1～3` 秒正常操作节奏、有限重试、账号 / 设备串行、人工介入、结果核验和结束存证

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/SKILL_ACTION_RUNTIME.md

@@ -9,7 +9,7 @@
 | 文档 | 职责 |
 |------|------|
 | 本文 | sync/async、任务中心、Agent 禁令、单内核编排、队列 pick、同步 vs 导出 |
-| [`../references/ACTIONS.md`](../references/ACTIONS.md) | `actions.json` 字段、placements、`bind.tables`、inputSchema、跨表 Lookup、字段条件显隐 `visibleWhen`、**按钮中文名 `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` 混淆。可选 **`cellPresentation`**（见 `references/CELL_PRESENTATION.md`）：单元格语义标色；省略 = P0。
+3. **五职责正交** — `placements` / `bind.tables` / `executionProfile` / `entrypoint` / domain service 各管一事（见 ACTIONS.md）。可选第六轴 **policy**（见 `references/POLICY.md`）：未启用 = L0 与今日一致。可选 **`hostEffects` / `steps`**（见 ACTIONS.md）：数据管理交互前后的 UI/级联编排；省略 = 不额外改 UI（匠厂宿主 ≥2.8.5）。可选 **`hoverHint`**（见 ACTIONS.md）：数据管理工具栏悬停；省略 = 不显示，不回退说明或确认黄条。可选 **表单 `visibleWhen`**（见 ACTIONS.md）：Action 参数表单字段条件显隐；省略 = 字段始终平铺；**勿与** **`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` 推断。可选 **`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 流**。
@@ -167,7 +167,7 @@ cmd_stats()                 # 只读 sync：JSON stdout，无 job_context
 | 同步 / refresh / collect | 外部来源 → 技能本地 SQLite | 技能 domain service |
 | 导出当前数据表 | 本地库 → CSV/Excel | **宿主**数据管理统一导出 |
 | 特殊业务报告（文件） | 多表合并 / 特殊格式 → `output/` | 仅系统导出不足时提供 `export-*` |
-| HTML 页面报告 | 写入 `{skill_data}/html/*.html` | 技能生成；宿主扫描预览；重新生成 Action id 固定为 **`render-html`** |
+| HTML 页面报告 | 壳子页 `assets/html/pages/*.html`；快照写入 `{skill_data}/html/*.html` | 壳子装完即现；快照由技能生成，重新生成 Action id 固定为 **`render-html`**。页面用 `jiangchang.call` 调已声明命令 |
 
 同步 Action 默认写库、不写导出文件。HTML 报告契约见 [`../references/ACTIONS.md`](../references/ACTIONS.md)「HTML 页面报告」与 [`DATA_PATHS.md`](DATA_PATHS.md)。通用幂等 / 事务 / 空结果保护见 [`../references/SCHEMA.md`](../references/SCHEMA.md)。
 

development/TESTING.md

@@ -34,7 +34,8 @@
 - **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。
 - **开发规范守护（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) ——verb-noun-platform 命名规范校验。
+- **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/`。
 
 **原则：`tests/test_*.py` 不允许隐形访问外网、不允许拉起真实浏览器、不允许读写开发者机器的真实数据根**。如果需要仿真服务器，也应仅在 integration（并由档位变量放行）。
 

development/TUTORIAL_SURFACES.md

@@ -0,0 +1,222 @@
+# 用户市场文档契约（说明 Tab / 教程 Tab）
+
+本文给**技能开发者**与 **AI 编程助手**读：规定根目录 `README.md`（技能说明）与 `TUTORIAL.md`（使用教程）**写什么、不写什么**，以及如何与宿主三入口、入口定位表、`actions.json` 对齐。
+
+**单一真相链：**
+
+```text
+REQUIREMENTS.md §0.1 入口定位表
+        ↓
+assets/actions.json（placements / label / bind）
+        ↓
+TUTORIAL.md（用户可读、分入口操作）
+README.md（能力与边界；不写步骤）
+```
+
+产品入口「挂什么」见 [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md)。本文只管**用户市场文档怎么投影**。
+
+---
+
+## 0. 与四 Tab 的关系
+
+| 文件 | 市场 Tab | 本文角色 |
+|------|----------|----------|
+| `README.md` | **说明** | §1：是什么 / 给谁 / 边界 |
+| `TUTORIAL.md` | **教程** | §2～§6：怎么用（分入口） |
+| `DEMO.md` | 演示 | 观看顺序可对齐三入口，不另造标准 |
+| `CHANGELOG.md` | 更新日志 | 与文档契约无关 |
+
+**铁律：** 说明就是说明，教程就是教程。**禁止**在 README 里写分步操作、Agent 话术块、排障「点哪里」；这些一律进 `TUTORIAL.md`。
+
+### 0.1 标题层级（说明 / 教程共用）
+
+宿主详情页**已经**展示技能名；「说明 / 使用教程」Tab（及数据管理右侧教程抽屉）**已经**标明文档类型。因此：
+
+| 层级 | 用途 |
+|------|------|
+| `#` | **正文不要用**（会与页头/Tab 标题重复抢视觉） |
+| `##` | 主分节（能帮你做什么、入口一：数据管理…） |
+| `###` | 分节内步骤 |
+
+**禁止：**
+
+- `README.md` 文首 `# 【技能名】` / `# 审计疑点辅助` 这类与页头重复的 H1  
+- `TUTORIAL.md` 文首 `# 【技能名】· 使用教程` 这类与 Tab/抽屉标题重复的 H1  
+
+去掉重复 H1 后，**不要**把原来的 `##` 全部升成 `#`。
+
+---
+
+## 1. README.md（说明 Tab）
+
+### 1.1 必须回答
+
+| 问题 | 写法 |
+|------|------|
+| 这是什么 | 开篇一两句价值（**普通段落或引用**，不要再写技能名 H1） |
+| 能做什么 | 3～6 条能力 bullet（**无步骤编号**） |
+| 适合谁 / 场景 | 业务语言 |
+| 使用前准备 | 安装、账号、权限等**前置条件**；不写「去哪张表点哪」 |
+| 执行后得到什么 | 结果形态（表、报告、文件），**不教怎么生成** |
+| 注意事项 | 边界、风险、人工复核 |
+| 怎么使用（可选，短） | **一两句**：支持哪些入口 + **「步骤见使用教程 Tab」** |
+
+### 1.2 禁止写入 README
+
+- `1.` `2.` `3.` 操作步骤（如「选品任务 → 点某某按钮」）
+- 「你可以这样告诉 Agent」整节或大块 `>` 示例话术
+- 「入口一 / 入口二」专章结构
+- 逐步排障（「先点 A 再点 B」）
+- frontmatter `description` 不要写「以及如何开始使用」类教程承诺
+
+### 1.3 FAQ 边界
+
+- README FAQ：**概念类**（和真实系统区别、从哪开始学、是否支持定时）→ 可指向「使用教程」Tab
+- **操作类**排障 → 只写在 `TUTORIAL.md`「常见卡住怎么办」
+
+### 1.4 建议章节（标题可微调）
+
+```text
+（开篇一两句价值；不要写 # 技能名）
+## 这个技能能帮你做什么
+## 适合什么场景
+## 使用前需要准备什么
+## 怎么使用          ← 仅短摘要 + 指向教程
+## 执行后你会得到什么
+## 注意事项
+## 常见问题          ← 概念类
+```
+
+---
+
+## 2. TUTORIAL.md（教程 Tab）必选结构
+
+复制业务技能后，**验收章节（标题可微调，语义不可缺）**：
+
+```text
+（开篇：数据管理与对话平行；定时有/无一句。不要写 # 技能名 · 使用教程）
+
+## 本技能做什么      ← 业务数据流（非 CLI/SQL）
+## 开始前
+## 入口一：数据管理  ← §0.1 有 toolbar/row/batch/replaces 则必填
+## 入口二：对话任务  ← §0.1 有 agent 则必填
+## 入口三：定时任务  ← 有 cron：怎么用；无 cron：不需要 + 理由
+## 主能力对照表      ← 双挂能力必填
+## 常见卡住怎么办
+```
+
+### 2.1 与入口定位表的关系
+
+| §0.1 / actions | TUTORIAL 要求 |
+|----------------|---------------|
+| 任一能力挂数据管理（toolbar/row/batch/replaces） | **必须**有「入口一：数据管理」专章 |
+| 任一能力挂 `agent` | **必须**有「入口二：对话任务」专章（**禁止**用「或者你也可以说…」替代专章） |
+| 任一能力挂 `cron` | **必须**有「入口三」且写清如何建定时、选哪个 Action |
+| **无** `cron` | **必须**写「本技能不需要定时」+ 一句理由（与 §0.1 一致） |
+| 某能力只挂一端 | 对照表注明「仅数据管理」或「仅对话」 |
+
+### 2.2 平行关系（数据管理 ∥ 对话）
+
+- 两者是**平行主入口**，不是「对话主、点表辅」或反过来
+- 禁止全文只有「第一步：打开对话说清目标」且无数据管理专章
+- 允许用户只用其中一种；教程须写清「两种效果一致，选你习惯的」
+
+---
+
+## 3. 入口一：数据管理（怎么写）
+
+适合写：
+
+1. 左侧有哪些业务表、各干什么（业务语言）
+2. 首次准备（载入/导入/新建）——**按钮必须出现在用户能看到的地方**（见 §5）
+3. 主流程：进哪张表 → 是否要选中行 → 点哪个 `label` → 去哪看结果
+4. 行级 / 批量操作（若有 `row` / `batch`）
+
+按钮中文名 = `assets/actions.json` 的 `label`，不要另造别名。
+
+---
+
+## 4. 入口二：对话任务（怎么写）
+
+适合写：
+
+1. 什么时候用对话（与数据管理互补）
+2. 示例话术表（与主能力一一对应）
+3. Agent 可能追问什么、用户怎么答
+
+**不要**把对话写成唯一路径；也不要把话术塞进 README。
+
+---
+
+## 5. 准确性铁律（用户看得见才写）
+
+教程步骤必须对应 **宿主真实 UI**，不是只对应 manifest 声明。
+
+| 规则 | 说明 |
+|------|------|
+| **placements 对齐** | 教程写的入口 ∈ `actions.json` 已挂 placement |
+| **skill-detail 不可作主路径** | 声明了 `skill-detail` **不等于**详情页一定渲染出按钮；当前宿主常只显示四 Tab。**禁止**把「技能详情 → 点某某」写成用户主路径 |
+| **准备/载入/导入类** | 优先挂 **数据管理 `toolbar`** + `bind.tables`（空表也可点的能力尤其如此）；可保留 `agent`；`skill-detail` 仅作可选兼容 |
+| **写入后刷新** | 建议 `steps: [{ "when": "afterSuccess", "do": "refreshCatalog" }]`，避免用户点完表不刷新 |
+| **对照表** | 「想做什么 \| 数据管理 \| 对话」覆盖双挂主能力；`label` 与界面一致 |
+
+字段细节见 [`../references/ACTIONS.md`](../references/ACTIONS.md)「用户可见性与教程准确性」。
+
+---
+
+## 6. 入口三：定时任务（可选）
+
+### 6.1 何时挂 `cron`（教程教「怎么用定时」）
+
+- 参数相对固定、按节奏重复（同步、巡检、消费队列）
+- 无人值守仍安全、可幂等或可失败重试
+- 与数据管理是「白天点选 + 夜里自动啃」组合
+
+教程写：侧栏定时任务 → 新建 → 选本技能 → 选 Action → 填参 → 保存/立即运行。
+
+### 6.2 何时不挂（教程写「不需要」）
+
+- 一次性 / 课堂演示，对象当场指定
+- 强不可逆、须当场确认
+- 每次对象不同、须人指定链接或范围
+- 主路径依赖验证码 / 人工介入
+
+决策三问（与 [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md) §2.3 一致）：
+
+1. 明天人不盯着、同样参数再跑一遍，业务上合理吗？  
+2. 失败后自动重跑可接受吗？  
+3. 有没有须人当场确认或动态指定的输入？  
+
+①是 且 ②可接受 且 ③否 → 可挂 cron；否则不挂，§0.1 写理由，教程声明 N/A。
+
+---
+
+## 7. 复制后自检（发布前）
+
+- [ ] README 无分步操作、无 Agent 话术块
+- [ ] TUTORIAL 有三入口结构（定时有或 N/A）
+- [ ] 对照表与 `actions.json` `label` 一致
+- [ ] 准备类按钮在数据管理表顶可见（若技能有数据管理主路径）
+- [ ] 教程未把 skill-detail 当唯一载入/主流程入口
+- [ ] §0.1「挂」的入口在 TUTORIAL 有专章；「不挂」有理由且教程一致
+
+交活清单见 [`CHECKLIST.md`](CHECKLIST.md) A2-7～A2-11。
+
+---
+
+## 8. 参考样例
+
+已验收参考（业务技能，非模板正文）：`client-gdcm/review-sku-selection-default`  
+（说明 Tab 瘦身 + 教程三入口 + 「载入课堂样例」挂 `selection_cases` toolbar。）
+
+复制模板后**不要**照搬选品表名与样例编码；只复用**章节结构与职责划分**。
+
+---
+
+## 9. 相关文档
+
+- 宿主入口何时挂：[`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md)
+- 入口定位表：[`REQUIREMENTS.md`](REQUIREMENTS.md) §0.1
+- Action placements / 可见性：[`../references/ACTIONS.md`](../references/ACTIONS.md)
+- 市场四 Tab 同步：[`DEVELOPMENT.md`](DEVELOPMENT.md) §6 附近「用户市场四 Tab」
+- 交活验收：[`CHECKLIST.md`](CHECKLIST.md) §2

examples/real_browser_rpa/README.md

@@ -52,7 +52,7 @@ real_browser_rpa/
 8. **等待结果容器** — `#search-result-container`（示例 selector）
 9. **滚动采集循环** — 采集可见条目 → 判断 stop_reason → 滚动加载
 10. **返回结果** — `ScrapeRunResult` + `format_stop_reason_for_user()`
-11. **释放租约** — `finally` 中 `release_lease()`
+11. **释放租约** — `finally` 中**先** `release_lease()`，**再**关浏览器；进度 `emit` 不得用裸 `except Exception` 吞掉 `JobStopped`
 
 ## 开发新 skill 时如何复制
 
@@ -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`）
 
 ## 复制边界：哪些能复制，哪些必须替换
 
@@ -150,7 +151,7 @@ real_browser_rpa/
 - **不自动破解验证码** — 滑块/短信只检测 + 等待人工完成
 - **不对抗平台风控** — 频控、账号风险、封禁或权限不足时停止并交由人工处理
 - **日志脱敏** — 不输出完整手机号/账号
-- **租约释放** — `ensure-web` / `pick-web --lease` 后必须在 `finally` 释放
+- **租约释放** — `ensure-web` / `pick-web --lease` 后必须在 `finally` **先**释放租约再关浏览器；任务中心中断靠 `JobStopped` 进 `finally`，禁止吞掉停止信号
 - **失败留痕** — 真实 skill 应在关键失败点截图（示例中已留注释位）
 
 ## 常见坑

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

examples/simulator_browser_rpa/README.md

@@ -55,7 +55,7 @@ simulator_browser_rpa/
 | `browser_session.py` | async 系统 Chrome/Edge + launch args；**不在此 goto** |
 | `account_client.py` | **唯一** account-manager subprocess 封装（`pick_web_account`→ensure-web / `release_lease`） |
 | `simulator_playwright.py` | 门户轮询、登录、批量表单、PIN、解析 `batch_id`、截图 |
-| `adapter/simulator_rpa.py` | **薄** adapter：pick 账号、lease、委托 RPA、`finally release_lease` |
+| `adapter/simulator_rpa.py` | **薄** adapter：pick 账号、lease、委托 RPA、`finally` 先 `release_lease` 再关浏览器 |
 | `adapter/mock.py` | 不启浏览器，供 unit/mock/CI |
 | `task_service.py` | async 校验输入 → 选 adapter → `await submit_batch` |
 | `sandbox/demo_app.html` | 可控 DOM；含可选门户门闩 + 原批量提交流程 |

references/ACTIONS.md

@@ -77,21 +77,21 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 | `skill` | 是 | 必须与 `SKILL.md` 的 `metadata.openclaw.slug` 一致 |
 | `actions` | 是 | Action 数组，每项 `id` 唯一；**数组相对顺序**决定数据管理 toolbar / row / batch 技能按钮的展示顺序（见下节） |
 
-模板最小示例见 [`assets/actions.json`](../assets/actions.json)；JSON Schema 见 [`assets/schemas/skill-actions.schema.json`](../assets/schemas/skill-actions.schema.json)。可选 Data Policy 见 [`POLICY.md`](POLICY.md) 与 [`assets/schemas/skill-policy-snapshot.schema.json`](../assets/schemas/skill-policy-snapshot.schema.json)。可选单元格呈现见 [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md) 与 [`assets/schemas/skill-cell-presentation.schema.json`](../assets/schemas/skill-cell-presentation.schema.json)。
+模板最小示例见 [`assets/actions.json`](../assets/actions.json)；JSON Schema 见 [`assets/schemas/skill-actions.schema.json`](../assets/schemas/skill-actions.schema.json)。可选 Data Policy 见 [`POLICY.md`](POLICY.md) 与 [`assets/schemas/skill-policy-snapshot.schema.json`](../assets/schemas/skill-policy-snapshot.schema.json)。可选单元格/整行/整列呈现见 [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md)、[`assets/schemas/skill-cell-presentation.schema.json`](../assets/schemas/skill-cell-presentation.schema.json) 与 [`assets/schemas/skill-grid-presentation.schema.json`](../assets/schemas/skill-grid-presentation.schema.json)。
 
 ## 六职责正交（必读）
 
 | 字段 / 层 | 只决定什么 | 不决定什么 |
 |-----------|------------|------------|
 | **`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 忽略** |
 | **`hoverHint`** | **可选**：数据管理**工具栏悬停**文案 | 不决定短按钮名；不决定点下去弹不弹窗；**不回退** `description` / `confirmation.message`；省略 = 不显示悬停。当前宿主实现为顶栏技能按钮 |
 | **`inputSchema.visibleWhen`** | **可选**：Action **参数表单**字段条件显隐（先选模式再出对应参数） | **不是** Data Policy L3 行态 `visibleWhen`；不决定 placements；旧宿主忽略则字段平铺全显 |
 | **`hostEffects` / `steps`** | **可选**：数据管理交互跑完前后，宿主要不要刷新表 / 清选区 / 级联删等 | 不决定业务写什么；**省略 = 宿主不额外改 UI**（≥2.8.5 起不再硬编码 mutation 后刷新）；cron/agent 忽略 |
-| **`cellPresentation`** | **可选**：某表某行某列的语义标色/强调（tone + 说明） | 不替代业务列；不下发 CSS；用途不限（超时、预警、驳回等）；见 [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md) |
+| **`cellPresentation`** | **可选**：某表某格 / 整行 / 整列 / 区域的语义标色/强调（tone + 说明） | 不替代业务列；不下发 CSS；用途不限（超时、预警、驳回等）；见 [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md) |
 | **`policy` / Snapshot** | **可选**：当前身份在数据管理下允许哪些 Action / 宿主内置能力 / 行列范围 | 不替代 placements；不替代 domain 写路径鉴权；多数技能不配 = L0 全开 |
 | **`entrypoint`** | 实际执行哪个 CLI 命令与参数 | 不写业务逻辑 |
 | **domain service** | **真正完成什么业务** | 不感知 toolbar / cron / agent 来源 |
@@ -102,18 +102,19 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 
 | 层级 | 稳定字段 / 能力 |
 |------|----------------|
-| 顶层 | `schemaVersion`、`skill`、`actions`；可选 **`policy`**（Data Policy 启用块）；可选 **`cellPresentation`**（单元格呈现启用块） |
+| 顶层 | `schemaVersion`、`skill`、`actions`；可选 **`policy`**（Data Policy 启用块）；可选 **`cellPresentation`**（格子/行/列/区域呈现启用块） |
 | action | `id`、`label`、`description`、`placements`、`entrypoint`、**`executionProfile`（必填）**；可选 `hoverHint`、`inputSchema`、`confirmation`、**`interaction`**、**`interactionByPlacement`**、**`bind`**、**`replaces`**、**`hostEffects`**、**`steps`**、**`authz`**（仅文档提示） |
 | entrypoint | `type = cli`、`command`、`args`（**必填** JSON 数组，项为 `string` / `number` / `boolean`） |
 | placements | `toolbar`、`row`、`batch`、`skill-detail`、`agent`、`cron`；仅 `replaces` 时可为空数组 |
 | **replaces** | 可选 `"create"` \| `"update"` \| `"delete"` \| `"import"` — 接管默认新增/编辑/删除/导入（须 `bind.tables`） |
-| **bind** | `{ "tables": ["business_table"] }`；可选 `inputMapping`（行内/批量预填，见下节） |
+| **bind** | `{ "tables": ["business_table"] }`；可选 `inputMapping`、`columnMapping`、**`labelColumn`**、**`selectionMode`**、**`visibleWhen`**（行内/批量预填、选择摘要标签、勾选驱动模式、**行菜单显隐**，见下节） |
 | **policy** | 可选；`enabled` + `entrypoint`（推荐 `policy` CLI）；见 POLICY.md。未启用 = L0 |
-| **cellPresentation** | 可选；`{ "enabled": true }` 时宿主应加载单元格呈现；见 [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md)。未启用 = P0 |
-| inputSchema | 根 `type: object`；properties 使用 `string` / `number` / `boolean`；支持 `enum`、`default`、`required`、`sensitive`、`readOnly`；可选 `display_type` / `format`（`textarea` / `date` / `datetime_unix_seconds` / `url` / `email` / `lookup`）；可选 **`visibleWhen`**（字段条件显隐，见专节） |
+| **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`**（字段条件显隐，见专节） |
 | confirmation | `{ "message": "..." }` — **风险文案**（confirm/form 弹窗黄条；agent 元数据）；**不是**「要不要弹窗」的开关 |
 | **hoverHint** | 可选字符串。数据管理**工具栏悬停**文案；与 `description` / `confirmation.message` **独立**。省略则不显示悬停，不回退。短名已够懂时不要写。需宿主已支持该字段；当前实现为顶栏技能按钮，不含宿主内置删除/刷新/新增/导入/导出 |
-| **visibleWhen** | 可选。写在 **property** 上（非 action 顶层）：依赖同表单其它字段值决定是否展示；隐藏字段不提交、不校验 `required`。**勿与** [`POLICY.md`](POLICY.md) L3 行态 `visibleWhen` 混淆 |
+| **visibleWhen** | 可选。写在 **property** 上（非 action 顶层）：依赖同表单其它字段值决定是否展示；隐藏字段不提交、不校验 `required`。**勿与** [`POLICY.md`](POLICY.md) L3 行态 `visibleWhen` 混淆；也**勿**用它藏「已选择」已表达的映射主键（见「选择摘要」） |
+| **revealInForm** | 可选。写在 **property** 上：有「已选择」时仍强制画出该 `readOnly` 字段；省略 = 映射只读字段默认不占参数区（仍提交） |
 | **executionProfile** | `"sync"` \| `"async"`（**必须显式写出**，禁止依赖缺省） |
 | **interaction** | `"auto"` \| `"direct"` \| `"confirm"` \| `"form"`（可选；省略≈`auto`） |
 | **interactionByPlacement** | 可选；按 placement 覆盖为 `direct`/`confirm`/`form`（不可写 `auto`） |
@@ -132,18 +133,139 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 
 规则：
 
-- `bind` 为 object，`additionalProperties: false`；当前允许 `tables`（必填键当存在 bind 时）与可选 `inputMapping`。
+- `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`，避免在无关表上露出按钮；未声明时宿主可能按兼容逻辑在更多表上展示。
 - 表名须真实存在于技能 SQLite 与 `_jiangchang_tables`。
 - 希望出现在多张表时，显式列出所有表；**不要**依赖「无 bind 则全表展示」——那是宿主对**旧技能**的兼容，不是新技能标准。
-- **`inputMapping`（可选）**：把行/勾选映射到 `inputSchema` 字段，例如 `"leadId": "$row.$pk"`、`"ids": "$selection.ids"`。适合 `row` / `batch`。宿主仍会提交这些字段；可用 `inputSchema.properties.*.readOnly: true` 在表单中只读展示。
+- **`inputMapping`（可选）**：把行/勾选映射到 `inputSchema` 字段，例如 `"leadId": "$row.$pk"`、`"ids": "$selection.ids"`。适合 `row` / `batch`。宿主仍会提交这些字段。映射字段建议标 `readOnly: true`：无「已选择」时只读展示；**有「已选择」时默认不占参数区**（仍提交，见下节）。不要用 `visibleWhen` 去「藏」映射主键。
+- **`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`），避免「勾选下载」与「按数量处理队列」拆成两个同义顶栏按钮、却让用户误以为勾选生效。
+
+| 值 | 含义 | 典型场景 |
+|----|------|----------|
+| `required` | 必须有表勾选；无勾选时宿主**禁用**按钮；弹层可显示「已选择」 | 经典批量：仅处理勾选行 |
+| `none` | **忽略**表勾选；即使勾选了也不显示「已选择」、也不把 `$selection.ids` 带进提交 | 经典工具栏「按数量从队列领取」 |
+| `optional` | **智能合并**：有勾选 → 走 `$selection.ids`（显示「已选择」）；无勾选 → 走空选数量字段（如 `pickCount`） | 统一「视频下载 / 处理队列」一类按钮 |
+| **省略** | 宿主兼容推断：`inputMapping` 含 `$selection.ids` 或 `placements` 含 `batch` → `required`；否则 → `none` | 旧技能零改动 |
+
+**`optional` 写法要点：**
+
+1. `bind.inputMapping` 声明 `"itemIds": "$selection.ids"`（字段名自定），并 `selectionMode: "optional"`。
+2. `inputSchema` 同时声明勾选字段与空选数量字段；两者都可写进 `required`——宿主只校验**当前分支**。
+3. 空选数量字段名约定（宿主按字段名识别，保守列表）：`pickCount` / `maxLeads` / `maxCount` / `takeCount` / `pick`。
+4. `entrypoint.args` 可同时写 `--ids {{itemIds}}` 与 `--pick {{pickCount}}`；缺值的 `--flag` + 空串由宿主压缩掉，不会留下脏 argv。
+5. 有勾选时隐藏数量字段；无勾选时隐藏 `$selection.ids` 映射字段（`$row.*` 行上下文不受影响）。
+6. **不要**为同一能力再挂第二个 toolbar 按钮。
+
+示例：[`assets/examples/selection-mode-optional.action.example.json`](../assets/examples/selection-mode-optional.action.example.json)。
+
+弹窗上的 `description` / 参数说明须用**普通用户中文**（见下节「用户可见文案」）；`pickCount` 等只作 **property 名 / CLI 参数名**，不要写进用户可读句子。
+
+### 用户可见文案（双受众，必读）
+
+宿主会把下列字段**原样展示给普通用户**（数据管理弹窗、任务中心时间线、表说明等）：
+
+| 字段 | 出现位置 |
+|------|----------|
+| Action `description` | 弹窗顶部说明 |
+| `confirmation.message` | 确认/表单黄条 |
+| `inputSchema` 各字段 `title` / `description` | 参数区标签与帮助 |
+| CLI / `finish` 返回的用户向 `message` | 任务中心、失败摘要 |
+| 表/列 `display_name`、表 `description` | 数据管理侧栏与表头帮助 |
+
+**总原则：** 以上文案 = **产品用语、全中文**。Agent 路由禁令、实现细节、契约自述放在 **`SKILL.md` / `references/`**，**不要**塞进弹窗 `description`。
+
+**允许写：** 待下载、任务中心、打开浏览器、有勾选 / 没有勾选、下载数量、按钮中文名（如「导入待下载链接」）。
+
+**禁止写进用户文案（常见反例）：**
+
+| 类型 | 反例 |
+|------|------|
+| 字段名 / CLI 子命令 | `pickCount`、`itemIds`、`import-urls`、`enqueue` |
+| 英文状态 / 条件式 | `pending`、`status=pending`、`failed` |
+| 执行剖面黑话 | `async`、`sync`、单独甩 `Job`（可说「任务中心」） |
+| Agent 禁令 | 「不是明确 URL 入口」「不要先 download-enqueue…」 |
+| 契约自述 | 「示例：bind.selectionMode=optional」 |
+
+**对照：**
+
+| 差（开发者备注） | 好（普通用户） |
+|------------------|----------------|
+| 按 `pickCount` 从 `pending` 领取（async） | 没有勾选则按下方数量从待下载队列领取；进度可在任务中心查看 |
+| 请先 import-urls | 请先在数据管理录入链接，或使用「导入待下载链接」 |
+
+**边界：**
+
+- `inputSchema` **属性名**、`entrypoint` 参数、库表状态枚举值可以仍是英文；变的是 **title / description / message**。
+- `label` 仍遵循上文「Action 按钮中文名」；本节约束的是说明与帮助文字。
+- 与 `bind.selectionMode` 正交：行为对了，文案仍须对人说人话。
+
+### 数据管理：选择摘要（宿主默认能力）
+
+当用户在数据管理**勾选行**（或行内打开带行上下文的动作）后打开 `confirm` / `form` 弹层时，若当前 Action 的 `selectionMode` 会**应用**表勾选（`required`，或 `optional` 且已勾选），宿主会展示通用 **「已选择 · N 条」** 摘要（`#主键` + 可读标签；超过约 3 条可展开查看全部）。这是**宿主 UX**，对适用技能默认生效：
+
+- **技能零改动即可受益**（省略 `selectionMode` 时的 `required` 推断路径）；不要在 `confirmation.message` 里手写「已选 id 列表」，也不要为了面板去拼业务状态跳过文案。
+- 摘要与执行解耦：勾选了谁由 UI 说明；**实际处理哪些行、是否跳过某些状态，仍由技能 CLI / domain service 决定**。
+- `selectionMode: "none"` 时即使表上有勾选，也**不**展示假「已选择」、不把勾选 id 预填进本 Action。
+- 需要稳定标签列时，在 `bind` 上声明可选 `labelColumn`（见上）。示例：[`assets/examples/selection-label-column.action.example.json`](../assets/examples/selection-label-column.action.example.json)。
+
+**与 `confirm` / `form` 的信息架构对齐（映射只读字段）：**
+
+| 交互 | 参数区 | 映射主键（`inputMapping` + `readOnly`） |
+|------|--------|----------------------------------------|
+| `confirm` | 整区不画 | 不画；预设值仍提交 |
+| `form`（有「已选择」） | 只画用户要填/要改的字段 | **默认不画**；预设值仍提交 |
+| `form`（无「已选择」） | 正常画字段 | `readOnly` **只读展示**（如工具栏靠 lookup 手选作业） |
+
+- 需要用户在有「已选择」时仍看见某只读字段：该 property 加 **`revealInForm: true`**（逃生阀；不改变提交）。
+- **禁止**用 `visibleWhen` 藏映射主键：`visibleWhen` 隐藏的字段**不进提交**、不校验 `required`，会弄断 `--id` / `{{job_id}}`。
+- 非映射的只读说明字段（未出现在 `inputMapping`）在有摘要时**仍会显示**；仅映射上下文字段被默认折叠。
+
 ## `replaces`（可选：接管默认新增 / 编辑 / 删除 / 导入）
 
-有领域副作用的表（归一化字段、建目录、加密、级联清理）不要依赖宿主直写 SQLite。此时可为该表声明 `replaces`，**用户仍点宿主默认按钮**，由技能 CLI 完成写入。
+有领域副作用的表（归一化字段、建目录、加密、级联清理）不要依赖宿主直写默认 CRUD。此时可为该表声明 `replaces`，**用户仍点宿主默认按钮**，由技能 CLI 完成写入。
 
 ### 怎么选
 
@@ -162,7 +284,7 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 2. **写库**按表能力分流：
    - 有 `replaces: import` → 把选中文件路径 + 出错规则交给该 Action（技能解析并写入）
    - 仅有 `replaces: create` → 宿主按行调用 create（兼容）
-   - 都没有 → 宿主直写 SQLite
+   - 都没有 → 宿主直写已注册数据源（默认 SQLite）
 
 **不要**再做一张技能自己的「开始执行」导入表单来冒充导入体验。`placements` 对 import 保持 `[]`；`description` 写明「由宿主导入面板调用」。
 
@@ -330,8 +452,8 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 | 值 | 数据管理体验 | 典型场景 |
 |----|--------------|----------|
 | `direct` | **一点即跑**，无弹窗 | 打开目录、打开浏览器、无参只读、行内主键已映射 |
-| `confirm` | 轻量确认弹窗（无参数区；文案优先 `confirmation.message`） | 处理待发送、删除前确认、有副作用但无可编辑入参 |
-| `form` | 完整参数表单（现状默认路径） | 导入、查询条件、需用户改写的字段 |
+| `confirm` | 轻量确认弹窗（无参数区；文案优先 `confirmation.message`；有勾选时宿主展示「已选择」摘要；映射主键仍提交） | 处理待发送、删除前确认、有副作用但无可编辑入参 |
+| `form` | 完整参数表单（有勾选时同样展示「已选择」摘要；**映射 `readOnly` 默认不占参数区**，见「选择摘要」） | 导入、选文件、查询条件、需用户改写的字段 |
 | `auto` / 省略 | 宿主推断：有**可编辑**参数 → `form`；仅有 `confirmation` → `confirm`；否则 → `direct` | 旧技能兼容；新技能建议显式写出 |
 
 ```json
@@ -639,14 +761,26 @@ HINT: <next step>
 |----|------|
 | `toolbar` | 数据管理表顶栏技能按钮（须配合 `bind.tables`） |
 | `row` | 数据管理**行级入口**（建议 `bind.tables` + `inputMapping`；表需有主键）。技能声明后，由宿主呈现为操作列链接、**行右键菜单**和/或行内「⋯」等壳；**不**新增 `row-context-menu` 等 placement |
-| `batch` | 数据管理批量操作（需勾选行；无勾选时宿主禁用按钮） |
+| `batch` | 数据管理批量操作入口。默认（`selectionMode` 省略或 `required`）需勾选行，无勾选时宿主禁用按钮；`optional` / `none` 时无勾选也可点（见 `bind.selectionMode`） |
 | `skill-detail` | 技能详情页直调（与安装/四 Tab 同属技能市场详情；已声明则须自测） |
 | `agent` | Agent 可直接调用（`run_skill_action`） |
 | `cron` | 定时任务「技能直调」 |
 
+### 用户可见性与教程准确性
+
+`placements` 决定 Action **可以**出现在哪；教程只能写用户在宿主里**实际能点到**的路径。完整用户文档契约见 [`../development/TUTORIAL_SURFACES.md`](../development/TUTORIAL_SURFACES.md)。
+
+| 规则 | 说明 |
+|------|------|
+| **skill-detail ≠ 一定可见** | 声明 `skill-detail` 不保证详情页渲染出按钮；当前宿主详情常只有说明/教程/演示/更新日志四 Tab。**禁止**把「技能详情 → 点某某」写成用户主路径或教程唯一入口 |
+| **准备 / 载入 / 导入 / 重置** | 若技能以数据管理为主路径，此类能力优先 `toolbar` + 非空 `bind.tables`（空表也可点的准备动作尤其如此）；可同时挂 `agent`；`skill-detail` 仅作可选兼容 |
+| **写入后刷新** | 会写入业务表的 Action 建议 `steps: [{ "when": "afterSuccess", "do": "refreshCatalog" }]`，避免用户点完表不更新 |
+| **教程按钮名** | 必须等于本文件 `label`；对照表与数据管理顶栏/行内文案一致 |
+| **README vs 教程** | 说明 Tab 不写分步；操作步骤只写 `TUTORIAL.md` |
+
 ### 行级入口 `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。
@@ -676,6 +810,7 @@ HINT: <next step>
 - 依赖或宣传表顶栏「更多操作」溢出菜单（宿主已取消该能力）。
 - 把「表格行数据默认排序」与按钮顺序混淆——行排序见 [`SCHEMA.md`](SCHEMA.md) 的 `default_sort_json`。
 - 把「默认展示列」与 `visible=0` 硬隐藏混淆——默认展示列见 [`SCHEMA.md`](SCHEMA.md) 的 `default_visible_columns_json`。
+- 误以为 `visible=0` 的列不能出现在 `default_sort_json`——隐藏只影响展示/筛选/搜索；ORDER BY 仍可用非敏感物理列（含隐藏主键）。
 - 新增 `row-context-menu` 等 placement，或要求技能再维护一份与 `row` 平行的菜单清单。
 
 ### Action 类型 × placements（常见示例，不是限制）
@@ -689,7 +824,7 @@ HINT: <next step>
 | 数据同步（外源 → 本地库） | sync 或 async | toolbar + cron + agent + skill-detail（按需） | 可选 |
 | 单行重试 / 行内处理 | sync 或 async | row（可加 agent） | 可选 |
 | 批量处理勾选行 | sync 或 async | batch（可加 toolbar/cron） | 可选 |
-| 导入 / 重置 | sync 或 async | skill-detail, agent | 可选 |
+| 导入 / 重置 | sync 或 async | **优先** toolbar（须 `bind.tables`）+ agent；skill-detail 仅可选 | 可选 |
 | 单条副作用 RPA | async（建议） | agent, skill-detail | **建议** |
 | 批量顺序 pick RPA | async（建议） | toolbar, cron, agent | **建议** |
 ## 同步数据 vs 导出当前表 vs 特殊业务报告 vs HTML 页面
@@ -701,28 +836,55 @@ HINT: <next step>
 | **同步数据**（sync / refresh / collect） | 外部来源 → 技能本地数据库 | 技能 Action / domain service |
 | **导出当前数据表** | 技能本地数据库 → CSV/Excel 等 | 数据管理页**宿主统一导出** |
 | **生成特殊业务报告（文件）** | 多表合并、特殊排版或附加计算的 **xlsx/csv/json 等文件** | 仅当系统导出无法满足时，才提供独立 `export-*` Action；文件落 `output/` |
-| **HTML 页面报告** | 可在数据管理侧栏预览的整页 HTML | 技能写入 `{skill_data}/html/*.html` + Action id **`render-html`**（见下节） |
+| **HTML 页面报告** | 可在数据管理侧栏预览的整页 HTML | 壳子页放安装包 `assets/html/pages/`；快照写入 `{skill_data}/html/*.html` + Action id **`render-html`**（见下节） |
 
 同步型 Action 默认：读外部数据、写技能自己的库、**不**生成 CSV/Excel/JSON 文件、不重复实现宿主表导出。兼容旧 export 命令若需要刷新数据，必须调用同一个 sync 业务内核。通用同步语义见 [`SCHEMA.md`](SCHEMA.md) 与 [`../development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。
 
 ## HTML 页面报告（数据管理预览）
 
-> 一句话：**技能负责生成并覆盖 `html/*.html`；宿主负责发现、预览、用 `render-html` 触发重新生成。**
+> 一句话：**壳子页跟安装包走，装完就在侧栏；快照由技能写入 `html/*.html`，宿主用 `render-html` 重新生成。** 页面上的按钮通过宿主调用本技能已声明的命令，不自己起 Python。
 
 ### 何时用
 
-- 需要**可浏览的整页报告**（KPI + 表格 + 自带样式），而不是再导出一张表
-- 与 `export-*` / 宿主表导出**并列**：HTML 走 `html/`；文件型特殊报告仍走 `output/` + `export-*`
+- 需要**可浏览的整页**（KPI + 表格 + 自带样式），而不是再导出一张表
+- **壳子页**：样式和脚本随技能安装就有，数字在打开后向宿主要。不要为了让它出现而点「生成 HTML」，也不要在 `init-db` 里拷进数据目录
+- **快照**：把算好的报告烘进文件（往来对账单一类）。与 `export-*` / 宿主表导出**并列**：快照走 `html/`；文件型特殊报告仍走 `output/` + `export-*`
 
 ### 目录与发现（宿主契约）
 
 | 项 | 约定 |
 |----|------|
-| 路径 | `{skill_data}/html/*.html`，**只扫一层**（子目录忽略） |
-| helper | `util.runtime_paths.get_html_dir()`；写入用 `service.html_page_service.write_html_page` |
+| 壳子页 | 安装包 `assets/html/pages/*.html`，**只扫一层**（子目录忽略）。装完即进侧栏，不经 `render-html` |
+| 快照 | `{skill_data}/html/*.html`，**只扫一层**。helper：`get_html_dir()` / `write_html_page` |
 | 侧栏名 | 取文件内 `<title>`（缺省则用文件名） |
-| 预览 | 宿主 iframe 预览；右键：重新生成 / 浏览器打开 / 刷新 |
-| 模板资源 | 建议放 `assets/html/*.html`（安装包内），渲染后**写出**到数据目录 `html/` |
+| 预览 | 宿主 iframe 预览。壳子页右键：打开 / 打开目录 / 刷新，**没有**「重新生成」。快照右键另有「重新生成」 |
+| 同名 | 壳子和快照文件名相同则留下快照。两边不要用同一个文件名 |
+| 快照模板 | `assets/html/example-report.html` 是写出快照时用的壳，**不要**放进 `pages/` |
+
+### 壳子页
+
+1. 把自包含 HTML 放到 `assets/html/pages/`（一层，不要子目录）。`<title>` 就是侧栏名字。
+2. 布局底线与下面「宿主预览布局」相同：铺满、禁横向滚动、禁外链 CSS/JS。
+3. 不要在初始化数据库时把这些文件拷进 `{skill_data}/html/`。升级技能后宿主读的是新安装包里的文件。
+
+### 页面调用
+
+宿主在数据管理预览里注入 `jiangchang.call`。页面脚本把它当成普通函数调用；宿主只在**当前技能** `actions.json` 已声明的方法里查找，命中后走和表按钮同一条 Python CLI，把 CLI 打出的 JSON 交回。
+
+```javascript
+const data = await jiangchang.call("方法名", { date: "2026-09-19" });
+```
+
+| 项 | 约定 |
+|----|------|
+| 方法名 | `actions.json` 里该条的 `id`。没声明则调用失败。不能传任意命令，也不能调别的技能 |
+| 参数 | 一个 JSON 对象，字段必须落在该条 `inputSchema` 里 |
+| 入口 | 可以不挂 `toolbar`。页面调用不要求表按钮。`placements` 仍不能为空（例如只挂 `agent`） |
+| 成功 | CLI 退出码 0，并打印**一个** JSON 对象。页面拿到的就是这个对象 |
+| 失败 | 退出码非 0，JSON 里带可读的 `message`（`type` 为 `result`、`status` 为 `failed` 时宿主会把 `message` 交给页面） |
+| 范围 | 只在数据管理预览里有这个函数。用浏览器单独打开该文件时没有，页面应说明「请在数据管理中打开」 |
+
+异步命令当场只返回任务号，不在这一节展开。写入和只读是同一种调用，差在技能声明了哪条命令。
 
 ### Action：`render-html`（固定 id）
 
@@ -740,7 +902,25 @@ HINT: <next step>
 | `steps` | `afterSuccess` → **`refreshCatalog`**（重扫 `htmlPages`；不要只 `reloadTable`） |
 | `entrypoint` | CLI 子命令（如 `render-html`）调用同一写入内核 |
 
-完整 JSON 形状见 [`../assets/examples/render-html.action.example.json`](../assets/examples/render-html.action.example.json)。最小页面壳见 [`../assets/html/example-report.html`](../assets/html/example-report.html)。
+完整 JSON 形状见 [`../assets/examples/render-html.action.example.json`](../assets/examples/render-html.action.example.json)。最小页面壳见 [`../assets/html/example-report.html`](../assets/html/example-report.html)（已含数据管理 iframe 预览的布局基线；复制后可按需扩展 `{{BODY}}` 内结构）。
+
+### 宿主预览布局
+
+数据管理在 **iframe** 内预览壳子页和快照；宿主 iframe 已占满右侧预览区，**技能页不应再人为收窄正文**（尤其数据管理窗口通常较窄）。
+
+| 级别 | 约定 |
+|------|------|
+| **必须** | 页面横向**铺满** iframe 可用宽度：`main { width: 100%; min-width: 0; }` |
+| **必须** | **禁止** `main`（或等价正文容器）使用 `max-width: Npx` 且**无** `margin: 0 auto`（宽屏会左对齐留白；窄宿主窗浪费横向空间） |
+| **必须** | `html` / `body` 设 `overflow-x: hidden`；滚动以**纵向**为主，避免横向滚动条 |
+| **必须** | 写入 `{{BODY}}` 的业务数据经 `html.escape`（或等价）转义，防 XSS |
+| **应当** | `header` 与 `main` 水平内边距一致（如共用 CSS 变量或 `clamp()`） |
+| **应当** | 多列表格：`width: 100%` + 单元格 `word-break` / `overflow-wrap`，长文本在格内换行 |
+| **应当** | KPI / 卡片网格用 `repeat(auto-fit, minmax(…, 1fr))` 等流体列，勿死写固定列数 |
+| **禁止** | 在 `<td>` 上用 `max-width` 限制「说明列」等业务列（易导致列宽异常或横向溢出） |
+| **禁止** | 依赖外链 CSS/JS 或 `networkidle` 式加载（iframe `sandbox` 仅 `allow-scripts`；页面应自包含） |
+
+长文阅读型报告若确需版心，可对整个 `main` 使用 `max-width` **且** `margin: 0 auto`，并令 `header` 与 `main` 同宽；**数据看板类**默认不设 `max-width`。
 
 ### 实现要点
 
@@ -752,7 +932,10 @@ HINT: <next step>
 
 ### 验收（复制后自测）
 
-- [ ] `html/` 下出现 `.html`，数据管理侧栏能看到报告项，预览正常
+- [ ] 壳子页：安装后侧栏能看到 `assets/html/pages/` 里的标题，无需点生成；右键没有「重新生成」
+- [ ] 页面调用：`jiangchang.call` 能拿到 CLI 的 JSON；未声明的方法名失败且有可读错误
+- [ ] 快照：`html/` 下出现 `.html`，数据管理侧栏能看到报告项，预览正常
+- [ ] 预览区**横向铺满**、**无横向滚动条**；拖窄侧栏后内容自适应（见上节「宿主预览布局」）
 - [ ] 表顶栏（若声明 toolbar）或报告右键「重新生成」能跑通；成功后预览刷新
 - [ ] 未登录/无权限用户被拒绝，且有可读错误
 - [ ] 成功路径带 `refreshCatalog`（或等价让侧栏/预览看到更新）
@@ -761,14 +944,37 @@ HINT: <next step>
 
 ### 跨表引用：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
 {
@@ -805,29 +1011,124 @@ HINT: <next step>
 
 | 字段 | 必填 | 说明 |
 |------|------|------|
-| `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 对称）
 
@@ -841,44 +1142,117 @@ Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件
 | 数字 | `type: number` | `display_type: number` 或 INT/REAL/NUMERIC |
 | 开关 | `type: boolean` | `display_type: boolean` |
 | 枚举下拉 | `enum: [...]` | `options_json` 数组 |
-| 关联下拉（Lookup） | 内联 `display_type: lookup` + `lookup`（可选 `multiple`），或绑列 | 同左；多选存 `TEXT` 逗号分隔 id |
+| 关联下拉（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` |
 | 日期（日） | `display_type` 或 `format`: `date` | `display_type: date` → 存 `YYYY-MM-DD` |
 | 日期时间 | `display_type` 或 `format`: `datetime_unix_seconds` | 同左；**存/传 Unix 秒** |
 | URL（薄层） | `display_type` 或 `format`: `url` | `display_type: url` |
 | Email（薄层） | `display_type` 或 `format`: `email` | `display_type: email` |
+| **本地文件路径** | `display_type`/`format`: **`file`**；可选 **`pathRoot`** | CRUD 一般不用；见下节 |
+| **本地目录路径** | `display_type`/`format`: **`directory`**；可选 **`pathRoot`** | CRUD 一般不用；见下节 |
 | 说明灰字 | `description` | `_jiangchang_columns.description` |
 | 表格横幅 / 列头「?」 | （无；Action 不用） | `_jiangchang_tables.grid_help` / `_jiangchang_columns.grid_help` |
 | 默认值 | `default` | SQLite 列 `DEFAULT` |
 | 只读 | `readOnly: true` | 列 `editable: 0` / 宿主只读规则 |
 | **条件显隐** | **`visibleWhen`**（见下节） | **本版 CRUD 无对称**；仅 Action / 定时任务参数表单 |
+| **列筛选「值」** | **无对称**（Action 无表格筛选） | 见 [`SCHEMA.md`](SCHEMA.md)「数据管理：列筛选与全局搜索」：枚举 / boolean / lookup 在筛选栏用**下拉 Select**（非开关、非分段单选）；存库仍用 value，展示与搜索认 label |
 
-**本版不做（勿宣传）：** 文件上传、复杂 `oneOf` / nested object 专用表单；`visibleWhen` 多条件 AND/OR 树、跨 Action 依赖、CRUD 新增/编辑对称显隐。  
-（**Lookup 多选**已支持：同一 `lookup` + `multiple: true`，见上文；不是任意标签数组。）
+**本版不做（勿宣传）：** 浏览器内文件上传控件、复杂 `oneOf` / nested object 专用表单；`visibleWhen` 多条件 AND/OR 树、跨 Action 依赖、CRUD 新增/编辑对称显隐；Action 参数表单的列筛选对称。  
+（**Lookup 多选**已支持：同一 `lookup` + `multiple: true`，见上文；不是任意标签数组。**分页勾选小表**已支持：同一 `lookup` + `presentation: "paged_table"`，见「分页勾选小表」。）  
+（**本地路径选择**已支持：`file` / `directory` + 可选 `pathRoot`，见下节；提交值仍是本机绝对路径字符串，不是 multipart 上传。）
 
 日期时间约定：
 
 - Action 提交与 CRUD 写库统一用 Unix **秒**整数（与 SCHEMA 标准时间字段一致）
+- `year` 只表示公历年份，值为 `YYYY`（如 `2026`）
+- `year_month` 只表示年月，值为 `YYYY-MM`（如 `2026-05`）；**不要**用 `date` 表示账期/月份
 - `date` 只表示日历日，值为 `YYYY-MM-DD`
-- 脏/无法归一的旧预设：日期控件可回退为普通文本，避免卡死表单
+- 脏/无法归一的旧预设：日期/年月控件可回退为普通文本，避免卡死表单
+
+### 本地路径选择与 `pathRoot`
+
+用于数据管理 / 定时任务 **Action 参数表单**里选本机文件或目录（原生对话框）。与宿主工具栏内置「导入」面板（默认打开本技能 `input/`，见 [`../development/DATA_PATHS.md`](../development/DATA_PATHS.md)）是**两条 UI 路径**，不要混为一谈。
+
+| 字段 | 含义 |
+|------|------|
+| `display_type` / `format`: `file` \| `directory` | 渲染「选文件 / 选文件夹」控件；提交值为本机**绝对路径**字符串 |
+| **`pathRoot`（可选）** | 对话框**起始目录**，相对**当前技能数据根** `{JIANGCHANG_DATA_ROOT}/{USER_ID}/{slug}/` |
+
+宿主行为（匠厂已支持）：
+
+| `pathRoot` | 打开对话框时 |
+|------------|--------------|
+| 省略 / 空 | `{skill_data}/input` |
+| `input/库存数据` 等 | `{skill_data}/` + 该相对路径 |
+| `output` / `output/…` | 落在技能 `output` 下 |
+| 裸 `库存数据` | 视为 `input/库存数据` |
+| 绝对路径、盘符、`..` | 非法 → 回退 `{skill_data}/input` |
+
+硬规则：
+
+1. **禁止**写用户 ID、盘符、绝对路径；用户与数据根由宿主按当前登录解析。
+2. **`description` 只给人看**，宿主**不会**解析文案来决定起始目录；要默认进子目录必须写 `pathRoot`。
+3. Agent / CLI **忽略** `pathRoot`（仍直接传路径字符串）。
+4. 输入框**已有路径**时，宿主优先用已有值作为起始（便于再次浏览）。
+
+```json
+{
+  "id": "refresh-inventory",
+  "label": "刷新库存数据",
+  "description": "从输入目录选择 JSON 快照并更新库存。",
+  "placements": ["toolbar", "agent"],
+  "executionProfile": "sync",
+  "interaction": "form",
+  "bind": { "tables": ["sku_inventory"] },
+  "inputSchema": {
+    "type": "object",
+    "required": ["file"],
+    "properties": {
+      "file": {
+        "type": "string",
+        "title": "库存数据文件",
+        "description": "请选择 input/库存数据/ 下的 JSON。",
+        "format": "file",
+        "display_type": "file",
+        "pathRoot": "input/库存数据"
+      }
+    }
+  },
+  "entrypoint": {
+    "type": "cli",
+    "command": "refresh-inventory",
+    "args": ["--file", "{{file}}"]
+  }
+}
+```
+
+形状参考：[`assets/examples/path-root-file-action.example.json`](../assets/examples/path-root-file-action.example.json)。
+
+账期/月份（`YYYY-MM`）字段形状参考：[`assets/examples/year-month-action.example.json`](../assets/examples/year-month-action.example.json)。
 
 ### 当前宿主稳定支持（摘要）
 
 - 根：`object`；属性：`string` / `number` / `boolean`（`object`/`array` 仅作 JSON 多行编辑兼容，新技能慎用）
-- `enum` / `default` / `required` / `sensitive` / `readOnly`
-- `display_type` / `format`：`textarea` | `date` | `datetime_unix_seconds` | `url` | `email` | **`lookup`**
+- `enum` / `default` / `required` / `sensitive` / `readOnly` / 可选 `revealInForm`
+- `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`）
 - 属性级 `description`（表单标签下方灰字说明）
 - 简单模板替换（`{{fieldName}}`）
 - 可选空数字字段提交时由宿主省略，避免 `""` 触发 number 校验失败
 - **字段条件显隐 `visibleWhen`**（可选）：依赖同表单其它字段值决定是否展示；隐藏字段不进提交、不校验 `required`
+- **选择摘要下的映射只读折叠**：`form` +「已选择」时，`inputMapping` 映射且 `readOnly` 的字段默认不渲染（仍提交）；`revealInForm: true` 可强制显示；**勿**用 `visibleWhen` 代替
 
 ### 字段条件显隐（`visibleWhen`）
 
 用于「先选模式，再出对应参数」类表单。写在 `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": {
@@ -942,6 +1316,12 @@ CRUD 侧宿主义务与禁止事项见 [`SCHEMA.md`](SCHEMA.md)「表单与展
         "description": "最多返回多少条；填 0 表示不限制（若业务支持）",
         "default": 50
       },
+      "period": {
+        "type": "string",
+        "title": "账期月份",
+        "display_type": "year_month",
+        "description": "格式 YYYY-MM，例如 2026-05"
+      },
       "dueDate": {
         "type": "string",
         "title": "截止日期",
@@ -980,17 +1360,20 @@ CRUD 侧宿主义务与禁止事项见 [`SCHEMA.md`](SCHEMA.md)「表单与展
 
 若还需要默认篇数，可在同一 `properties` 里为 `pickCount` 增加 `"default": 1`、`"minimum": 1`。
 
+与 **`bind.selectionMode: "optional"`** 联用时：无勾选弹层展示 `pickCount`；有勾选则隐藏 `pickCount`、提交 `$selection.ids`。不要再拆第二个「只 pick / 只勾选」toolbar 按钮。见上文「勾选驱动模式」。
+
 约定：
 
 - `boolean` 在宿主中渲染为开关
 - `enum` 在宿主中渲染为选择框
 - `type: number` 渲染为数字输入
+- `display_type`/`format: year` 渲染为年份选择；`year_month` / `month` 渲染为年月选择
 - `display_type`/`format: date` 渲染为日期（日）；`datetime_unix_seconds` 渲染为日期时间并按 **Unix 秒**提交
 - `display_type`/`format: url` / `email` 为薄层输入类型（校验从宽，勿当强校验网关）
 - `required` 字段在提交前校验
 - `sensitive` 字段不得出现在低信任入口
-- `readOnly: true` 时数据管理表单只读展示该字段（仍随提交传入）；适合行内/勾选预填的主键、编号列表
-- `placements` 含 `batch` 的动作在数据管理表顶常驻，无勾选时禁用（与表删除一致）
+- `readOnly: true`：数据管理表单中标记为只读；**有「已选择」且该字段来自 `inputMapping`（或无 mapping 时的约定 id 字段）时，宿主默认不渲染该控件，预设值仍随提交传入**（与 `confirm` 无参数区对齐信息架构）。无「已选择」时仍只读展示。需要强制露出时加 `revealInForm: true`。**不要**用 `visibleWhen` 藏映射主键（会不提交）。
+- `placements` 含 `batch` 的动作：默认（`selectionMode` 为 `required` 或省略推断为 required）无勾选时禁用；`selectionMode` 为 `optional` / `none` 时无勾选也可点（见「勾选驱动模式」）
 - 需要确认的副作用操作使用 `confirmation.message`
 - 短名看不懂或会覆盖数据时，用独立的 `hoverHint`；不要把确认黄条复用成悬停
 - 模板参数使用 `{{fieldName}}`，且必须在 `inputSchema.properties` 中声明

references/CELL_PRESENTATION.md

@@ -1,9 +1,9 @@
 # 数据管理单元格呈现（Cell Presentation）契约（v1.0）
 
-> **状态：正式契约 v1.0（`schemaVersion` 1）。**  
-> **目标：** 冻结「技能声明某表某行某列的语义呈现 → 宿主映射主题样式」的通用能力，供任意业务场景复用。  
+> **状态：正式契约 v1.0（`cells[]` 文档 `schemaVersion` 1）+ 加法 Grid Presentation。**  
+> **目标：** 冻结「技能声明语义呈现 → 宿主映射主题样式」的通用能力：某一格、整行、整列、若干行×若干列，供任意业务场景复用。  
 > **非目标：** 超时/SLA 专用字段；技能下发任意 CSS / 任意色值；宿主实现业务规则引擎。  
-> **配套 Schema：** [`../assets/schemas/skill-cell-presentation.schema.json`](../assets/schemas/skill-cell-presentation.schema.json)。
+> **配套 Schema：** [`../assets/schemas/skill-cell-presentation.schema.json`](../assets/schemas/skill-cell-presentation.schema.json)（格子）、[`../assets/schemas/skill-grid-presentation.schema.json`](../assets/schemas/skill-grid-presentation.schema.json)（行/列/区域）。
 
 相关正交轴见 [`ACTIONS.md`](ACTIONS.md)、[`POLICY.md`](POLICY.md)、[`SCHEMA.md`](SCHEMA.md)。
 
@@ -11,9 +11,17 @@
 
 ## 0. 一句话
 
-技能可以声明：**哪张业务表、哪一行、哪一列**需要特殊标色/强调（语义 `tone` + 可选说明）。  
+技能可以声明：**哪张业务表**上，**哪些行 × 哪些列**需要特殊标色/强调（语义 `tone` + 可选说明）。
+
+| 想涂什么 | 怎么声明 |
+|----------|----------|
+| 某一格 | 一行 × 一列（v1 `cells[]` 或一条格子规则） |
+| 整行 | 若干行 × 该轴全部列 |
+| 整列 | 该轴全部行 × 若干列 |
+| 区域 | 若干行 × 若干列 |
+
 用途不限：时效超时未填、库存预警、状态异常、必填缺失、审核驳回等。  
-**不是**「再加一列超时文字」；强调落在**真正要关注的业务格子**上。
+**不是**「再加一列超时文字」；强调落在**真正要关注的业务格子或行**上。
 
 ---
 
@@ -22,9 +30,20 @@
 | 档位 | 技能行为 | 宿主行为 |
 |------|----------|----------|
 | **P0（默认）** | 不写呈现数据 / 未启用 | 数据管理表格与今日一致，无特殊标色 |
-| **P1** | 按规则写入呈现文档或推荐旁路表 | 渲染对应单元格的语义样式；可选汇总 `alert: true` 做进页提醒 |
+| **P1** | 按规则写入呈现文档或推荐旁路表 | 渲染对应格子 / 行 / 列 / 区域的语义样式；可选汇总 `alert: true` 做进页提醒 |
 
-多数技能保持 **P0**。需要视觉强调时再启用。
+多数技能保持 **P0**。需要视觉强调时再启用。模板 `actions.json` **默认不启用**。
+
+---
+
+## 0.2 宿主能力
+
+| 能力 | 旁路表 | 宿主 |
+|------|--------|------|
+| 格子着色 | `_jiangchang_cell_presentation` | 既有宿主即可 |
+| 整行 / 整列 / 区域 | `_jiangchang_grid_presentation` | 需已读取该表（匠厂数据管理已支持）。**旧宿主忽略该表**，格子着色仍有效 |
+
+同一开关 `cellPresentation.enabled` 同时打开两张旁路表。未建表 = 该通道为空，宿主忽略。
 
 ---
 
@@ -32,17 +51,17 @@
 
 | 角色 | 负责 | 不负责 |
 |------|------|--------|
-| **技能** | 按**当前业务数据**算出哪些格子要强调；在数据变更后**重算**并覆盖旧结果 | 不写宿主 CSS；不把强调文案污染进业务真值列冒充「变红」 |
-| **宿主** | 读取呈现结果，按闭集 `tone` 映射主题样式；可选 Toast/提醒汇总 | 不理解「提前 3 天交单」等业务规则；不为单个技能写死样式 |
+| **技能** | 按**当前业务数据**算出哪些格子/行/列要强调；在数据变更后**重算**并覆盖旧结果 | 不写宿主 CSS；不把强调文案污染进业务真值列冒充「变红」 |
+| **宿主** | 读取呈现结果，按闭集 `tone` 映射主题样式；按几何涂表格；可选 Toast/提醒汇总 | 不理解「提前 3 天交单」等业务规则；不为单个技能写死样式 |
 
 **派生状态（重要）：** 呈现是计算结果，不是粘性开关。  
 用户补填数据 / 同步刷新后技能重算 → 该项消失 → **样式与提醒自然关闭**。不要单独维护「已关闭提醒」状态机（除非产品另做「忽略此条」能力，本契约不冻结）。
 
 ---
 
-## 2. 文档形状（冻）
+## 2. 格子文档形状（冻，`schemaVersion` 1）
 
-技能产出一份 **Cell Presentation Document**（可落库、可 CLI 打印，形状相同），须符合 Schema。
+技能产出一份 **Cell Presentation Document**（可落库、可 CLI 打印，形状相同），须符合格子 Schema。v1 **只描述某一格**；整行/整列用 §2.1。
 
 ```json
 {
@@ -71,14 +90,14 @@
 
 | 字段 | 必填 | 说明 |
 |------|------|------|
-| `schemaVersion` | 是 | 固定 `1` |
+| `schemaVersion` | 是 | 固定 `1`（本形状不升版本） |
 | `skill` | 是 | 与 slug 一致 |
 | `table` | 是 | 当前文档作用的业务表 |
 | `rowKey` | 是 | 行匹配列（`id` / `feishu_record_id` 等） |
 | `generatedAt` | 否 | 排障用 |
-| `cells` | 是 | 数组；**空数组 = 该表清除全部特殊呈现** |
+| `cells` | 是 | 数组；**空数组 = 该表清除全部格子呈现** |
 
-### 2.1 `cells[]` 项
+### 2.0 `cells[]` 项
 
 | 字段 | 必填 | 说明 |
 |------|------|------|
@@ -91,6 +110,74 @@
 同一 `(rowId, column)` 多条：宿主可**后者覆盖前者**。  
 `column` 对用户不可见（policy 打码 / 列隐藏）时：宿主可仍应用样式，或跳过——**推荐跳过不可见列的强调**，避免泄露「有问题」的存在感（技能仍可写，宿主按可见性过滤）。
 
+### 2.1 Grid 文档形状（加法，独立 Schema）
+
+整行 / 整列 / 区域用 **Grid Presentation Document**（`rules[]`）。与 `cells[]` **并存**，不替代、不升 `cells` 的 `schemaVersion`。
+
+统一几何：**`rows` × `columns`**。某一侧为 `"all"`（或省略，落库时写成 JSON `"all"`）= 该轴全部。禁止两侧都是全部（见 §4.2）。
+
+```json
+{
+  "schemaVersion": 1,
+  "skill": "your-skill-slug",
+  "table": "business_records",
+  "rowKey": "id",
+  "generatedAt": "2026-08-10T06:00:00Z",
+  "rules": [
+    {
+      "ruleKey": "qty-low-rows",
+      "rows": ["42", "99"],
+      "columns": "all",
+      "tone": "danger",
+      "message": "库存低于安全线",
+      "alert": true
+    },
+    {
+      "ruleKey": "status-column",
+      "rows": "all",
+      "columns": ["status"],
+      "tone": "warning",
+      "message": "待审核"
+    },
+    {
+      "ruleKey": "overdue-print-region",
+      "rows": ["7", "8"],
+      "columns": ["print_done_at", "ship_done_at"],
+      "tone": "danger",
+      "message": "环节到期未填",
+      "alert": true
+    }
+  ]
+}
+```
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `schemaVersion` | 是 | 固定 `1` |
+| `skill` / `table` / `rowKey` | 是 | 同格子文档；`rowKey` 用于匹配 `rows` 里的 id |
+| `rules` | 是 | 数组；**空数组 = 该表清除全部 grid 规则** |
+
+#### `rules[]` 项
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `ruleKey` | 是 | 本表内唯一（建议稳定业务键，便于重算覆盖） |
+| `rows` | 是 | `"all"` 或行 id 字符串数组（对应 `rowKey` 列值） |
+| `columns` | 是 | `"all"` 或业务列名数组 |
+| `tone` | 是 | 见 §3 |
+| `message` | 否 | ≤500 |
+| `alert` | 否 | 默认 `false`；按**规则条数**计提醒，不按命中格子数 |
+
+| `rows` × `columns` | 宿主 scope |
+|--------------------|-----------|
+| 1 行 × 1 列 | `cell` |
+| 若干行 × 若干列（非单格） | `region` |
+| 若干行 × `"all"` | `row`（整行） |
+| `"all"` × 若干列 | `column`（整列） |
+| `"all"` × `"all"` | **禁止**，宿主丢弃该规则 |
+
+完整 JSON 例见 [`../assets/examples/skill-grid-presentation.example.json`](../assets/examples/skill-grid-presentation.example.json)。
+
 ---
 
 ## 3. `tone` 闭集（冻）
@@ -106,13 +193,13 @@
 **禁止：** 技能下发原始 `#RRGGBB`、任意 CSS class、内联 style。  
 以后若扩展色板，只能**追加新 tone token** 并升契约，不能开放任意色值。
 
-「技能配置什么就显示什么」在本契约中的含义是：技能选择 **哪一格 + 哪个 tone + 什么说明**；**像素级颜色由宿主主题决定**，以保证多技能 UI 一致与安全。
+「技能配置什么就显示什么」在本契约中的含义是：技能选择 **哪一格/行/列 + 哪个 tone + 什么说明**；**像素级颜色由宿主主题决定**，以保证多技能 UI 一致与安全。
 
 ---
 
 ## 4. 推荐持久化（给宿主实现）
 
-v1 **推荐**技能将「当前表」的呈现写入用户库旁路表（与业务表分离，**不是**多余业务超时列）：
+v1 **推荐**技能将「当前表」的**格子**呈现写入用户库旁路表（与业务表分离，**不是**多余业务超时列）：
 
 ```sql
 CREATE TABLE IF NOT EXISTS _jiangchang_cell_presentation (
@@ -130,19 +217,60 @@ CREATE TABLE IF NOT EXISTS _jiangchang_cell_presentation (
 );
 ```
 
+### 4.1 整行 / 整列 / 区域（`_jiangchang_grid_presentation`）
+
+```sql
+CREATE TABLE IF NOT EXISTS _jiangchang_grid_presentation (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  table_name TEXT NOT NULL,
+  rule_key TEXT NOT NULL,
+  row_key TEXT NOT NULL DEFAULT '',
+  rows_json TEXT NOT NULL,
+  columns_json TEXT NOT NULL,
+  tone TEXT NOT NULL,
+  message TEXT,
+  alert INTEGER NOT NULL DEFAULT 0,
+  generated_at TEXT,
+  updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  UNIQUE (table_name, rule_key)
+);
+```
+
+`rows_json` / `columns_json` 存 JSON：字符串 `"all"`，或 id / 列名数组（如 `["42","99"]`）。  
+`row_key`：有限行集合时必填（与文档 `rowKey` 相同，如 `id`）；整列（`rows_json = "all"`）可空字符串。
+
+两张表都列入技能 `INTERNAL_METADATA_TABLES`（见 `scripts/db/display_metadata.py`），**不得**作为业务表出现在数据管理侧栏。模板 **不**在 `init_db()` 里默认建这两张表；技能用到时再 `CREATE`。
+
+### 4.2 冲突与特异性
+
+同一格被多条规则命中时，宿主按 **格子 > 区域 > 行 > 列** 取胜。同级后者覆盖前者。
+
+宿主先加载 grid 规则，再加载 v1 `cells[]`（同级时 **v1 格子仍赢**），因此旧技能只写 `cells[]` 的行为不变。
+
+**禁止 `all` × `all`**（会把整张表涂满）。技能不要写；宿主遇到则丢弃该规则。
+
+### 4.3 表格 vs 详情
+
+| 表面 | 整行（scope=`row`） | 格子 / 列 / 区域 |
+|------|-------------------|------------------|
+| 数据管理表格 | 给整行（`<tr>`）上色 | 给对应单元格上色 |
+| 行详情 | **不**把行色铺到每个字段 | 对应字段可保留 tone |
+
+整行强调的是「这一行在表里扎眼」，不是「打开详情后每个值都变色」。
+
 约定：
 
-- 重算某表时：**先删该 `table_name` 全部行，再插入新结果**（或等价事务替换），保证填完后旧 `danger` 不会残留。  
-- 宿主打开数据管理某表时：若该技能启用了呈现（见 §5）且存在此表，则按当前页行的 `rowKey` 值匹配并着色。  
+- 重算某表时：**先删该 `table_name` 在两张旁路表中的全部行，再插入新结果**（或等价事务替换），保证填完后旧 `danger` 不会残留。只维护其中一张时，至少清掉自己负责的那张，并删掉已迁走的旧行（例如从格子改成整行后，删掉对应 `_jiangchang_cell_presentation`）。  
+- 宿主打开数据管理某表时：若该技能启用了呈现（见 §5）且存在旁路表，则按当前页行的 `rowKey` 值匹配并着色。  
 - 也允许技能用 CLI 打印整份 Document 供调试；**运行时以库内旁路表为准**（除非后续宿主另定拉取入口）。
 
-未创建该旁路表 = P0，宿主忽略。
+未创建该旁路表 = 该通道 P0，宿主忽略。
 
 ---
 
 ## 5. 在 `actions.json` 中启用（可选，推荐）
 
-与 `policy` 类似，顶层可选：
+与 `policy` 类似，顶层可选。**一份开关同时启用格子与 grid：**
 
 ```json
 {
@@ -158,7 +286,7 @@ CREATE TABLE IF NOT EXISTS _jiangchang_cell_presentation (
 | 字段 | 说明 |
 |------|------|
 | `cellPresentation` | 省略 = P0 |
-| `cellPresentation.enabled` | 仅 `true` 表示宿主应尝试加载呈现；`false`/缺省等同 P0 |
+| `cellPresentation.enabled` | 仅 `true` 表示宿主应尝试加载呈现（两张旁路表）；`false`/缺省等同 P0 |
 
 v1 **不**要求单独 CLI entrypoint（与 policy 不同）；技能在 `sync` / 写路径 / `init-db` 后自行维护旁路表即可。若未来需要「仅刷新呈现」Action，用普通 Skill Action 即可，不必扩展本启用块。
 
@@ -172,8 +300,8 @@ v1 **不**要求单独 CLI entrypoint（与 policy 不同）；技能在 `sync`
 2. 会改变「是否仍需强调」的写路径成功之后（新建、更新、登记等）  
 3. （可选）用户显式「刷新呈现」类 Action  
 
-进页 Toast：宿主可在加载表后统计当前页或全表 `alert=1` 的条数；**0 则不打扰**。  
-提醒关闭 = 重算后没有对应 cell，而不是用户点「我知道了」写死关闭（除非另做忽略列表，本契约不冻）。
+进页 Toast：宿主可在加载表后统计当前页或全表 `alert=1` 的**规则条数**（grid 按规则计，不按命中格子数）；**0 则不打扰**。  
+提醒关闭 = 重算后没有对应 cell/rule，而不是用户点「我知道了」写死关闭（除非另做忽略列表，本契约不冻）。
 
 ---
 
@@ -181,7 +309,7 @@ v1 **不**要求单独 CLI entrypoint（与 policy 不同）；技能在 `sync`
 
 | 契约 | 关系 |
 |------|------|
-| **SCHEMA / `_jiangchang_columns`** | 管列是否可见、类型、中文名；**不管**条件标色 |
+| **SCHEMA / `_jiangchang_columns`** | 管列是否可见、类型、中文名；**不管**条件标色。呈现旁路表须进内部隐藏表集合 |
 | **POLICY Snapshot** | 管谁能看哪些 Action/行列；呈现仍建议按可见列过滤 |
 | **hostEffects / steps** | 管 Action 跑完后是否 `reloadTable`；重载后宿主应重新读呈现 |
 | **业务列真值** | 保持干净；不要把 `【超时】` 写进业务字段冒充变色 |
@@ -195,16 +323,21 @@ v1 **不**要求单独 CLI entrypoint（与 policy 不同）；技能在 `sync`
 - 只在首次超时时打标、填完不重算导致红字残留  
 - 宿主写死某个技能 slug 的特殊染色逻辑  
 - 把 Cell Presentation 做成仅服务 SLA 的专用协议  
+- 写 `rows: "all"` 且 `columns: "all"` 企图整表变色  
+- 假定打开行详情后，整行色会铺到每一个字段  
+- 把某一业务技能的检查逻辑（例如「检查列 → 整行」）复制进模板当通用运行时  
 
 ---
 
 ## 9. 示例场景（说明用途不限）
 
-| 场景 | column | tone | message 例 |
-|------|--------|------|------------|
-| 打单超时未填 | `print_done_at` | `danger` | 打单已超 1 天未填 |
-| 库存低于安全线 | `qty` | `warning` | 低于安全库存 |
-| 审核驳回 | `status` | `danger` | 已驳回，请修改 |
-| 选填备注缺失但不紧急 | `notes` | `muted` | 建议补充备注 |
+| 场景 | 几何 | tone | message 例 |
+|------|------|------|------------|
+| 打单超时未填 | 格子 `print_done_at` | `danger` | 打单已超 1 天未填 |
+| 库存低于安全线 | **整行**（该行 × `all`） | `warning` | 低于安全库存 |
+| 审核驳回 | 格子或整列 `status` | `danger` | 已驳回，请修改 |
+| 选填备注缺失但不紧急 | 格子 `notes` | `muted` | 建议补充备注 |
+| 两个日期列同时逾期 | 区域：若干行 × `print_done_at`+`ship_done_at` | `danger` | 环节到期未填 |
 
-完整 JSON 例见 [`../assets/examples/skill-cell-presentation.example.json`](../assets/examples/skill-cell-presentation.example.json)。
+格子 JSON 例见 [`../assets/examples/skill-cell-presentation.example.json`](../assets/examples/skill-cell-presentation.example.json)。  
+Grid JSON 例见 [`../assets/examples/skill-grid-presentation.example.json`](../assets/examples/skill-grid-presentation.example.json)。

references/CLI.md

@@ -27,7 +27,7 @@ python {baseDir}/scripts/main.py <command> …
 | **短 CLI 白名单** | （例）`health` / `version` / `render-html` / `<your-read-or-prep>` | 可用 bash/exec + 共享 `python` |
 | **Action 强制黑名单** | （例）`<your-long-or-rpa-command>` | **禁止** bash + `process poll`；必须 `run_skill_action` |
 
-细节与 Action 清单见 [`ACTIONS.md`](ACTIONS.md)。若提供 HTML 报告，「重新生成」须有 Action id **`render-html`**（可同时进短 CLI 白名单）；见 ACTIONS.md「HTML 页面报告」。
+细节与 Action 清单见 [`ACTIONS.md`](ACTIONS.md)。快照「重新生成」须有 Action id **`render-html`**；壳子页与页面调用 `jiangchang.call` 见 ACTIONS.md「HTML 页面报告」。
 
 ## 最小命令
 
@@ -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 不配） |
+| [`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,14 +10,14 @@
 
 ### 技能负责
 
-- 定义真实 SQLite 表结构
+- 定义真实业务表结构（SQLite 或 MySQL，按技能所选后端）
 - 使用英文 `snake_case` 表名和字段名
 - 使用 `_jiangchang_tables` 提供表级展示元数据
 - 使用 `_jiangchang_columns` 提供字段级展示元数据（含可选 `description` 表单说明、可选 `grid_help` 表格说明）
 - 需要「新增表单预填」时，在物理列上声明 SQLite `DEFAULT`（勿把默认值只写在文案里）
 - 定义哪些字段可见、可搜索、可创建、可编辑
 - 定义字段展示类型和枚举选项
-- （可选）按业务规则维护单元格呈现旁路数据（语义 tone；见 [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md)）
+- （可选）按业务规则维护单元格 / 整行 / 整列 / 区域呈现旁路数据（语义 tone；见 [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md)）
 - 保证元数据与真实数据库结构一致
 - 保证元数据初始化幂等
 
@@ -25,6 +25,7 @@
 
 - 读取 `_jiangchang_*` 元数据
 - 读取 SQLite `PRAGMA table_info`
+- **数据管理侧栏/表列表**：当库中存在 `_jiangchang_tables` 时，**仅展示**在该表注册且 `visible=1` 的业务表；孤儿物理表（有表、无注册元数据）**不得**出现在侧栏，直接访问 schema API 应返回「表不存在」。极老库无 `_jiangchang_tables` 时，宿主可保留物理表枚举 fallback（兼容 `_schema_meta` 时代）
 - 根据 schema 渲染数据管理页面
 - 根据 `editable` 推导字段是否可创建或编辑
 - 在**新增 / 编辑**表单中，若列有 `_jiangchang_columns.description`，在标签下方展示该说明（灰字；空则不显示）
@@ -35,7 +36,7 @@
 - 不猜测技能业务含义
 - 不根据具体技能名称写特殊逻辑
 - 可在技能安装/更新成功后静默调用 `python scripts/main.py init-db` 做幂等 ensure（内部即 `init_db()`）；失败不影响安装结果
-- 若技能启用了单元格呈现（见 [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md)），读取旁路呈现数据并为单元格映射语义样式（`tone`）；不猜测业务规则
+- 若技能启用了单元格呈现（见 [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md)），读取旁路呈现数据并为格子 / 行 / 列 / 区域映射语义样式（`tone`）；不猜测业务规则；整行色只涂表格行，不铺到详情字段
 
 ## 初始化入口
 
@@ -44,7 +45,8 @@
 SQLite **没有**可靠的 `COMMENT ON TABLE/COLUMN`；SQL 文件里的 `-- 注释` 也不会成为可查询结构。
 因此中文展示名称必须写入元数据表；字段顺序必须写在 `CREATE TABLE` 的列定义顺序中（`PRAGMA table_info` 的 `cid`）。
 
-> **禁止**新技能使用宿主的旧版 `_schema_meta` 表。仅 `_jiangchang_tables` / `_jiangchang_columns` 为正式契约。
+> **禁止**新技能使用宿主的旧版 `_schema_meta` 表。仅 `_jiangchang_tables` / `_jiangchang_columns` 为正式契约。  
+> 可选呈现旁路表 `_jiangchang_cell_presentation` / `_jiangchang_grid_presentation` **不是**展示元数据，但须列入 `INTERNAL_METADATA_TABLES`（侧栏不可见）。见 [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md)。
 
 ## 技能名称（SKILL.md）
 
@@ -142,7 +144,7 @@ metadata:
 | **同步数据** | 外部来源 → 技能本地数据库 | 技能 Action / domain service |
 | **导出当前数据表** | 本地库 → CSV/Excel 等 | 数据管理页**宿主统一导出** |
 | **生成特殊业务报告（文件）** | 多表合并、特殊排版或附加计算的文件 | 仅当系统导出无法满足时，才提供独立 `export-*`；落 `output/` |
-| **HTML 页面报告** | 侧栏可预览的整页 HTML | 写入 `html/` + Action id **`render-html`**（见 [`ACTIONS.md`](ACTIONS.md)） |
+| **HTML 页面报告** | 侧栏可预览的整页 HTML | 壳子页 `assets/html/pages/`；快照写入 `html/` + Action id **`render-html`**（见 [`ACTIONS.md`](ACTIONS.md)） |
 
 同步型 Action 默认只写库、不生成导出文件。兼容旧 export 命令需要刷新时，必须调用同一 sync 内核。可复用测试范式见 `tests/samples/test_sync_contract.py.sample`。
 
@@ -178,11 +180,36 @@ JSON 数组（可多字段，按顺序）：
 
 规则：
 
-- `column` 必须是该表真实列名；敏感列会被宿主忽略
+- `column` 必须是该表**真实物理列名**（存在于 SQLite 表）；不存在则宿主忽略该段或技能校验报错
+- **可以**引用 `visible=0` 的列（含隐藏的主键 `id`）。`visible=0` 只表示界面不展示 / 不进默认 SELECT·筛选·搜索；**不表示不能 ORDER BY**
+- 敏感列（宿主标为 sensitive）不得用于排序；技能侧勿把密钥类字段写进 `default_sort_json`
 - `direction` 仅 `asc` / `desc`（缺省按 `desc`）
 - 用户在 UI 上手动改排序后，以用户选择为准；声明只影响未选择时的默认
 - 通过 `upsert_table_metadata(..., default_sort_json=...)` 写入；旧库由 `init_display_metadata_tables` 幂等 `ALTER` 补列
 
+与 `visible` 的分工（勿再踩坑）：
+
+| 能力 | `visible=0` 是否仍可用 |
+|------|------------------------|
+| 表格列展示 / 「列」面板 | 否（硬隐藏） |
+| 默认 SELECT、列筛选、顶栏搜索 | 否 |
+| **`default_sort_json` / ORDER BY** | **是**（非敏感列） |
+| 行主键定位（`$row.$pk` 等） | 是（主键即使隐藏仍应可排序、可定位；宿主查询层保留） |
+
+示例（编号硬隐藏，但仍按编号排序——合法）：
+
+```python
+upsert_table_metadata(
+    cursor,
+    table_name="period_rule_overrides",
+    display_name="本月默认金额",
+    readonly=1,
+    default_sort_json='[{"column":"period","direction":"desc"},{"column":"id","direction":"asc"}]',
+)
+# id 列元数据可见性：
+# upsert_column_metadata(..., column_name="id", visible=0, ...)
+```
+
 示例（消息时间线）：
 
 ```python
@@ -275,6 +302,8 @@ upsert_column_metadata(
 - 只写英文物理名而不写中文 `display_name`
 - 让元数据引用不存在的表
 - 用 `visible=0` 假装「默认不展示但用户还能勾出来」（那是硬隐藏，勾不回来）
+- 误以为「列 `visible=0` 就不能写进 `default_sort_json`」——排序与展示已拆开；隐藏编号/主键仍可排序（须列真实存在且非敏感）
+- 把不存在的列名写进 `default_sort_json`（技能校验应报错；宿主也会忽略无效段）
 
 ### `_jiangchang_columns` 字段级标准
 
@@ -287,7 +316,7 @@ upsert_column_metadata(
 | `grid_help` | 否 | 数据管理表头「?」；空/未写则不出。与表单 `description` 独立，禁止互拷 |
 | `display_order` | 否 | 兼容字段，默认保持 `NULL` |
 | `visible` | 是 | 是否进入数据管理 schema /「列」面板（`0` = **硬隐藏**，用户无法勾回；默认不展示但可勾回请用表级 `default_visible_columns_json`） |
-| `searchable` | 是 | 是否参与搜索 |
+| `searchable` | 是 | 是否参与**列筛选**与**顶栏全局搜索**（`0` = 两者均不参与）；详见下节「数据管理：列筛选与全局搜索」 |
 | `editable` | 是 | `1` 业务字段允许宿主用于新增和编辑；`0` 系统/只读字段 |
 | `display_type` | 否 | 字段渲染类型；稳定取值见下节「表单与展示：稳定字段类型」 |
 | `options_json` | 否 | 枚举选项 JSON |
@@ -310,6 +339,8 @@ upsert_column_metadata(
 | （枚举） | 任意 + `options_json` **数组** | 标签映射 | 下拉选择 | 选项 `value` |
 | `lookup` | 跨表引用 id；`options_json` **对象**；可选 `multiple` | 单选：标签映射；多选：多标签（如「豆包、元宝」） | 单选下拉；多选见下文 | 单选：业务 id 标量；多选：`TEXT` 逗号分隔 id（非 SQLite 外键） |
 | （敏感） | 任意；列 `sensitive=1` | 掩码/隐藏策略由宿主定 | 新建可用密码框；编辑策略与既有宿主一致 | 原文（勿日志明文） |
+| `year` | `TEXT` 推荐 `YYYY` | 原文 | **年份选择** | `YYYY` 字符串 |
+| `year_month` | `TEXT` 推荐 `YYYY-MM` | 原文 | **年月选择** | `YYYY-MM` 字符串；别名 `month` |
 | `date` | `TEXT` 推荐 `YYYY-MM-DD`，或可安全归一的值 | 日期 | **日期选择**（日） | `YYYY-MM-DD` |
 | `datetime_unix_seconds` | `INTEGER` | `YYYY-MM-DD HH:mm:ss` | **日期时间选择**；提交写回 **Unix 秒** | Unix **秒**整数；禁止改成 ISO 字符串 |
 | `url` | `TEXT` | 原文（可作链接） | 单行输入 `type=url`（薄层；校验从宽） | 原文 |
@@ -382,6 +413,76 @@ seed_column_metadata_batch(
 
 Action 参数表单的 `title` / `description` / `default` / `display_type` 见 [`ACTIONS.md`](ACTIONS.md)；勿与本节 CRUD 配置入口混用。
 
+#### 数据管理：列筛选与全局搜索（宿主支持）
+
+数据管理表格提供两类与 `searchable` 相关的检索能力，技能通过 `_jiangchang_columns.searchable` 声明是否参与：
+
+| 能力 | 用户入口 | `searchable = 1` 时 | `searchable = 0` 时 |
+|------|----------|---------------------|---------------------|
+| **列筛选** | 表格「筛选」→ 字段 / 操作符 / 值 | 出现在「字段」下拉，可按类型选值与操作符 | 不出现在列筛选字段列表 |
+| **全局搜索** | 顶栏搜索框 | 参与 OR 模糊匹配（宿主对参与列数有上限，如最多 8 列） | 不参与全局搜索 |
+
+**存库 vs 展示（核心契约）**
+
+- **列表**：有 `options_json` 时展示 **label**（如「启用」「停用」）
+- **筛选 / 查询 / 全局搜索**：比较与匹配 **value**（如 `0`/`1`、`active`、`toutiaohao`）
+- 宿主负责 label ↔ value 映射；**禁止**为迁就 UI 把存库改成中文枚举，也**禁止**在 `description` 里写「筛选请填 0/1」
+
+**筛选栏控件 ≠ 新增/编辑表单（勿混用）**
+
+列筛选「值」与表单使用同一套**类型语义**，但控件形态不同：筛选栏须与「字段」「操作符」同一行工具栏对齐（如统一 `h-9` 下拉），**枚举 / boolean / lookup 在筛选栏一律用下拉 Select**，不用新增/编辑表单里的开关或横向分段单选。表单侧仍按上表「新增/编辑控件」配置。
+
+| 列类型 | 筛选「值」控件 | 常用操作符（宿主按类型裁剪） | 技能须配置 |
+|--------|----------------|------------------------------|------------|
+| 文本 / `url` / `email` | 文本框 | 等于 / 包含 / 开头 / 结尾 / 为空… | 通常 `searchable: 1` |
+| 数字 | 数字框 | 等于 / 大于 / 小于… | `display_type: number` 或 INT/REAL |
+| 枚举（`options_json` **数组**） | 下拉（展示 label） | 等于 / 不等于 / 为空 | **`options_json` 必填** + `searchable: 1` |
+| `boolean` | 下拉（有 `options_json` 用其 label；否则宿主默认可选「是/否」） | 等于 / 不等于 / 为空 | `display_type: boolean`；**推荐同时写 `options_json`** 指定中文 label |
+| `lookup` 单选 | 下拉 | 等于 / 不等于 / 为空 | `display_type: lookup` + lookup 对象 |
+| `lookup` + `multiple: true` | 列筛选 UI 演进中；**全局搜索**已支持 | 等于时按逗号分隔 id 的 token 匹配 | 多选存 `TEXT` 逗号分隔 id |
+| `year` / `year_month` / `date` / `datetime_unix_seconds` | 年 / 年月 / 日期 / 日期时间 | 比较类 | 账期/月份列推荐 `year_month`；时间列通常 `searchable: 0` |
+| 敏感列 | **不可筛** | — | 宿主强制排除 |
+
+**全局搜索扩展（用户可搜中文）**
+
+宿主在 `searchable = 1` 的列上除原文 `LIKE` 外，还应：
+
+- 有 `options_json` 枚举：**label 或 value** 均可命中
+- `boolean` 无 options：认「是/否」等常见别名
+- `lookup` 多选：按逗号分隔 id 的 **token 边界** 匹配；选项 label 亦可参与
+- `datetime_unix_seconds`：搜 `YYYY-MM-DD` 形态可匹配当天 Unix 秒区间
+
+**技能配置建议**
+
+推荐：
+
+- 用户常筛的状态列（启用/停用、待生成/已生成、`status` 等）→ `searchable: 1` + `options_json`（value 与 DDL 存库一致）
+- `boolean` 业务列：`display_type: boolean` **且** `options_json` 写中文 label（示例见下）
+
+禁止：
+
+- 仅为筛选把存库 value 改成中文
+- 在文档或 `description` 要求用户记内部 magic number / 英文 code
+
+示例（启用开关 + 中文筛选）：
+
+```python
+{
+    "column_name": "enabled",
+    "display_name": "是否启用",
+    "visible": 1,
+    "searchable": 1,
+    "editable": 1,
+    "display_type": "boolean",
+    "options_json": json.dumps(
+        [{"value": 0, "label": "停用"}, {"value": 1, "label": "启用"}],
+        ensure_ascii=False,
+    ),
+}
+```
+
+Action 参数表单**无**列筛选对称能力；筛选语义以本节为准，表单对照见 [`ACTIONS.md`](ACTIONS.md)「表单字段类型对照」。
+
 ## editable 与 createable 的关系
 
 技能模板只维护 `editable` 这一份字段权限声明：
@@ -627,6 +728,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`。
+
 **存库约定：**
 
 | 模式 | 物理列建议 | 存什么 |
@@ -647,8 +750,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`。
 
@@ -700,6 +804,48 @@ seed_column_metadata_batch(
 
 不要直接修改用户真实数据库作为迁移方式；元数据初始化必须使用真实物理字段列表。
 
+## 表增删改与退役（技能 schema 迁移）
+
+技能拥有 SQLite 物理 schema；宿主只渲染**已注册**的元数据。增删改表时技能须在 `init_db()` 中做幂等迁移，并与 `_jiangchang_*` 同步。
+
+| 操作 | 技能必须做 |
+|------|------------|
+| **新增**用户可见表 | `CREATE TABLE` + `upsert_table_metadata` + 列元数据种子 |
+| **修改**表/列 | 物理迁移（`ALTER` / 重建）+ 更新或 `prune_stale_column_metadata` |
+| **临时隐藏**（表仍保留） | 元数据 `visible=0`（表与元数据行都保留） |
+| **永久废弃**用户可见表 | `drop_deprecated_user_table(...)`（见下） |
+
+### 永久废弃用户可见表
+
+使用 `scripts/db/display_metadata.py` 的 **`drop_deprecated_user_table`**（幂等）：
+
+1. `DROP TRIGGER`（若有 `{table}_set_updated_at` 等）
+2. `DROP TABLE IF EXISTS`
+3. `DELETE` 对应 `_jiangchang_columns` / `_jiangchang_tables` 行
+
+```python
+from db.display_metadata import drop_deprecated_user_table
+
+def init_db() -> None:
+    ...
+    drop_deprecated_user_table(cur, "task_logs")
+    init_display_metadata(cur)
+```
+
+**反模式（禁止）：** 只删 `_jiangchang_*` 元数据、保留物理表。宿主虽可能不展示孤儿表，但库内残留、自检失败，且违背「元数据与物理结构一致」。
+
+**新技能禁止**创建或写入 `task_logs` 一类通用任务审计表。过程 → `jiangchang.log` / 运行日志；进度/终态 → 任务中心；业务结果 → 业务表（见 [`WORK_ITEM_STATUS.md`](WORK_ITEM_STATUS.md)、[`../development/LOGGING.md`](../development/LOGGING.md)）。
+
+### 旧库迁移测试（废弃表时必做）
+
+复制 `tests/samples/test_table_deprecation_migration.py.sample`，构造「旧库含废弃表 + 元数据 + 历史行」→ `init_db()` 后断言：
+
+- `sqlite_master` 无该表
+- `_jiangchang_*` 无残留行
+- `iter_user_tables` 不含该表
+
+卸载技能**不删**用户数据目录；重装会复用旧库，迁移必须在 `init_db()` 中完成（见 [`../development/DATA_PATHS.md`](../development/DATA_PATHS.md)）。
+
 ## 中文命名质量
 
 - 使用普通用户能理解的业务用语：`error_msg` → **错误信息**，`created_at` → **创建时间**。
@@ -708,11 +854,12 @@ seed_column_metadata_batch(
 
 ## 元数据同步规则
 
-1. 新增用户可见业务表 → 同步 `_jiangchang_tables`。
+1. 新增用户可见业务表 → 同步 `_jiangchang_tables`（`visible=1` 方可在数据管理展示）。
 2. 新增用户可见字段 → 同步 `_jiangchang_columns`。
-3. 删除/重命名表或字段 → 同步清理或迁移元数据。
+3. 删除/重命名表或字段 → 物理迁移 + 同步清理元数据；**废弃表**用 `drop_deprecated_user_table`，禁止只删元数据留物理表。
 4. 初始化脚本必须幂等。
 5. 元数据中的表、字段必须在库中真实存在；可见项不得缺少中文 `display_name`。
+6. `init_db()` 后：`iter_user_tables` 中每个物理业务表都应有对应 `_jiangchang_tables.display_name`，或已被 `drop_deprecated_user_table` 物理删除。
 
 ## 开发自检
 

release.ps1

@@ -7,6 +7,10 @@
   Encryption, ZIP packaging, and marketplace sync are done by CI
   (.github/workflows/release_skill.yaml → reusable-release-skill.yaml@main).
 
+  POLICY-RELEASE-001: before tagging, requires SKILL.md version and
+  scripts/util/constants.py SKILL_VERSION to equal the next tag (without prefix).
+  release.ps1 does not auto-edit those fields.
+
   Requires: git, PowerShell 5+
 
   After fetch, runs default tests against the current working tree (before auto-commit):
@@ -162,6 +166,93 @@ function Get-NextTag {
   return "$TagPrefix$($latest.Major).$($latest.Minor).$([int]$latest.Patch + 1)"
 }
 
+function Read-SkillMdVersion {
+  param([Parameter(Mandatory = $true)][string]$SkillRoot)
+
+  $path = Join-Path $SkillRoot "SKILL.md"
+  if (-not (Test-Path -LiteralPath $path)) {
+    return $null
+  }
+  $text = Get-Content -LiteralPath $path -Raw -Encoding UTF8 -ErrorAction SilentlyContinue
+  if ([string]::IsNullOrWhiteSpace($text)) {
+    return $null
+  }
+  $m = [regex]::Match($text, '(?m)^version:\s*["'']?([0-9]+\.[0-9]+\.[0-9]+)["'']?\s*$')
+  if (-not $m.Success) {
+    return $null
+  }
+  return $m.Groups[1].Value.Trim()
+}
+
+function Read-SkillConstantsVersion {
+  param([Parameter(Mandatory = $true)][string]$SkillRoot)
+
+  $path = Join-Path $SkillRoot "scripts\util\constants.py"
+  if (-not (Test-Path -LiteralPath $path)) {
+    return $null
+  }
+  $text = Get-Content -LiteralPath $path -Raw -Encoding UTF8 -ErrorAction SilentlyContinue
+  if ([string]::IsNullOrWhiteSpace($text)) {
+    return $null
+  }
+  $m = [regex]::Match($text, '(?m)^SKILL_VERSION\s*=\s*["'']([0-9]+\.[0-9]+\.[0-9]+)["'']')
+  if (-not $m.Success) {
+    return $null
+  }
+  return $m.Groups[1].Value.Trim()
+}
+
+# POLICY-RELEASE-001: marketplace latest (git tag) must equal package manifest versions.
+function Assert-SkillReleaseVersionAlignment {
+  param(
+    [Parameter(Mandatory = $true)][string]$SkillRoot,
+    [Parameter(Mandatory = $true)][string]$NextTag,
+    [Parameter(Mandatory = $true)][string]$TagPrefix
+  )
+
+  $skillMdPath = Join-Path $SkillRoot "SKILL.md"
+  if (-not (Test-Path -LiteralPath $skillMdPath)) {
+    return
+  }
+
+  $expected = $NextTag
+  if ($TagPrefix -and $expected.StartsWith($TagPrefix)) {
+    $expected = $expected.Substring($TagPrefix.Length)
+  }
+  $expected = $expected.Trim()
+  if ($expected -notmatch '^\d+\.\d+\.\d+$') {
+    throw "Release check failed (POLICY-RELEASE-001): cannot derive semver from Next tag '$NextTag'."
+  }
+
+  $mdVersion = Read-SkillMdVersion -SkillRoot $SkillRoot
+  $constVersion = Read-SkillConstantsVersion -SkillRoot $SkillRoot
+
+  $problems = @()
+  if ([string]::IsNullOrWhiteSpace($mdVersion)) {
+    $problems += "SKILL.md missing top-level version: X.Y.Z"
+  }
+  elseif ($mdVersion -ne $expected) {
+    $problems += "SKILL.md version=$mdVersion (want $expected)"
+  }
+  if ([string]::IsNullOrWhiteSpace($constVersion)) {
+    $problems += "scripts/util/constants.py missing SKILL_VERSION = `"X.Y.Z`""
+  }
+  elseif ($constVersion -ne $expected) {
+    $problems += "SKILL_VERSION=$constVersion (want $expected)"
+  }
+
+  if ($problems.Count -gt 0) {
+    throw (
+      "Release aborted (POLICY-RELEASE-001): Next tag=$NextTag requires manifest version $expected, but " +
+      ($problems -join "; ") +
+      ". Bump SKILL.md version and scripts/util/constants.py SKILL_VERSION to $expected (and CHANGELOG), then re-run release.ps1. " +
+      "release.ps1 does not auto-edit these fields."
+    )
+  }
+
+  Write-Host "Version alignment OK: tag=$NextTag == SKILL.md=$mdVersion == SKILL_VERSION=$constVersion" -ForegroundColor DarkGray
+}
+
 function Assert-SkillReleasePackagingSources {
   param([Parameter(Mandatory = $true)][string]$SkillRoot)
 
@@ -283,6 +374,15 @@ try {
     Assert-SkillReleasePackagingSources -SkillRoot $skillRoot
   }
 
+  $nextTag = Get-NextTag -TagPrefix $Prefix
+  Write-Host "Next tag: $nextTag" -ForegroundColor Green
+  Assert-SkillReleaseVersionAlignment -SkillRoot $skillRoot -NextTag $nextTag -TagPrefix $Prefix
+
+  $existing = @(Get-GitOutput -GitArgs @("tag", "--list", $nextTag))
+  if ($existing.Length -gt 0) {
+    throw "Tag already exists: $nextTag"
+  }
+
   Invoke-DefaultTests -SkillRoot $skillRoot -Skip:$SkipTests
 
   Ensure-CleanOrAutoCommit -DoAutoCommit:$AutoCommit -NeedClean:$RequireClean -IsDryRun:$DryRun -Msg $CommitMessage
@@ -304,14 +404,6 @@ try {
     }
   }
 
-  $nextTag = Get-NextTag -TagPrefix $Prefix
-  Write-Host "Next tag: $nextTag" -ForegroundColor Green
-
-  $existing = @(Get-GitOutput -GitArgs @("tag", "--list", $nextTag))
-  if ($existing.Length -gt 0) {
-    throw "Tag already exists: $nextTag"
-  }
-
   if ($DryRun) {
     Write-Host "[DryRun] Would run: git tag -a $nextTag -F <utf8-msg-file> ($Message)" -ForegroundColor Yellow
     Write-Host "[DryRun] Would run: git push origin $nextTag" -ForegroundColor Yellow

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/db/display_metadata.py

@@ -9,11 +9,21 @@ from __future__ import annotations
 from typing import Iterable
 
 # 宿主会隐藏这些表，不作为业务表展示（见 jiangchang electron/data-management/types.ts）
-INTERNAL_METADATA_TABLES = frozenset({"_jiangchang_tables", "_jiangchang_columns"})
+# 呈现旁路表由技能按需 CREATE，见 references/CELL_PRESENTATION.md；未建表不影响 P0。
+INTERNAL_METADATA_TABLES = frozenset(
+    {
+        "_jiangchang_tables",
+        "_jiangchang_columns",
+        "_jiangchang_cell_presentation",
+        "_jiangchang_grid_presentation",
+    }
+)
 LEGACY_METADATA_TABLES = frozenset({"_schema_meta"})
 METADATA_TABLES = INTERNAL_METADATA_TABLES | LEGACY_METADATA_TABLES
 
 DATETIME_UNIX_SECONDS = "datetime_unix_seconds"
+YEAR_MONTH = "year_month"
+YEAR = "year"
 STANDARD_TIMESTAMP_COLUMNS = frozenset({"created_at", "updated_at"})
 
 _JIANGCHANG_TABLES_DDL = """
@@ -95,6 +105,7 @@ def upsert_table_metadata(
     default_sort_json: 宿主数据管理默认排序，JSON 数组，例如
     '[{"column":"sent_at","direction":"desc"},{"column":"id","direction":"desc"}]'
     为空则宿主回退到 updated_at → created_at → 主键。
+    排序列须为真实物理列；**允许**引用 visible=0 的非敏感列（隐藏≠不能 ORDER BY）。
 
     default_visible_columns_json: 宿主数据管理默认展示列，JSON 字符串数组，例如
     '["stat_type","period","stage"]'
@@ -277,6 +288,32 @@ def init_display_metadata(cursor) -> None:
     init_display_metadata_tables(cursor)
 
 
+def drop_deprecated_user_table(
+    cursor,
+    table_name: str,
+    *,
+    triggers: Iterable[str] | None = None,
+) -> None:
+    """永久退役用户可见表：删 trigger、DROP 物理表、清理展示元数据（幂等）。
+
+    用于废弃 task_logs 等旧表。禁止只删元数据而保留物理表。
+    见 references/SCHEMA.md「表增删改与退役」。
+    """
+    for trigger_name in triggers or ():
+        cursor.execute(f"DROP TRIGGER IF EXISTS {trigger_name}")
+    default_updated_at = f"{table_name}_set_updated_at"
+    cursor.execute(f"DROP TRIGGER IF EXISTS {default_updated_at}")
+    cursor.execute(f"DROP TABLE IF EXISTS {_quote_identifier(table_name)}")
+    cursor.execute(
+        "DELETE FROM _jiangchang_columns WHERE table_name = ?",
+        (table_name,),
+    )
+    cursor.execute(
+        "DELETE FROM _jiangchang_tables WHERE table_name = ?",
+        (table_name,),
+    )
+
+
 def iter_user_tables(cursor) -> Iterable[str]:
     cursor.execute(
         "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name"

scripts/db/display_metadata_validator.py

@@ -235,6 +235,139 @@ def validate_options_json(options_json: str | None) -> tuple[list[str], list[str
     return errors, warnings
 
 
+def validate_filter_search_metadata(
+    cursor,
+    table_name: str,
+) -> tuple[list[str], list[str]]:
+    """对可见但未开启 searchable 的枚举 / boolean 列给出软建议。"""
+    warnings: list[str] = []
+    cursor.execute(
+        """
+        SELECT column_name, visible, searchable, display_type, options_json
+        FROM _jiangchang_columns
+        WHERE table_name = ?
+        """,
+        (table_name,),
+    )
+    for column_name, visible, searchable, display_type, options_json in cursor.fetchall():
+        if visible is not None and int(visible) == 0:
+            continue
+        if searchable is not None and int(searchable) != 0:
+            continue
+
+        display_type_norm = str(display_type or "").strip()
+        is_boolean = display_type_norm == "boolean"
+
+        has_enum = False
+        if options_json is not None and str(options_json).strip():
+            opt_errors, _ = validate_options_json(options_json)
+            if not opt_errors:
+                try:
+                    parsed = json.loads(str(options_json))
+                except json.JSONDecodeError:
+                    parsed = None
+                has_enum = isinstance(parsed, list) and len(parsed) > 0
+
+        if not has_enum and not is_boolean:
+            continue
+
+        warnings.append(
+            f"{table_name}.{column_name}: 枚举/状态类列建议 searchable=1，"
+            "以便宿主列筛选与按中文 label 全局搜索（见 references/SCHEMA.md）"
+        )
+
+    return [], warnings
+
+
+def parse_default_sort_json(raw: object) -> tuple[list[dict[str, str]], list[str]]:
+    """解析 default_sort_json；返回 (specs, errors)。specs 项含 column / direction。"""
+    errors: list[str] = []
+    if raw is None or str(raw).strip() == "":
+        return [], []
+    text = str(raw).strip()
+    try:
+        parsed = json.loads(text)
+    except json.JSONDecodeError:
+        return [], ["default_sort_json 不是合法 JSON"]
+    if not isinstance(parsed, list):
+        return [], ["default_sort_json 必须是 JSON 数组"]
+    out: list[dict[str, str]] = []
+    for index, item in enumerate(parsed):
+        if not isinstance(item, dict):
+            errors.append(f"default_sort_json[{index}] 必须是对象")
+            continue
+        column = str(
+            item.get("column")
+            or item.get("columnName")
+            or item.get("column_name")
+            or ""
+        ).strip()
+        direction_raw = str(item.get("direction") or "desc").strip().lower()
+        if not column:
+            errors.append(f"default_sort_json[{index}] 缺少 column")
+            continue
+        if direction_raw not in {"asc", "desc"}:
+            errors.append(f"default_sort_json[{index}].direction 只能是 asc 或 desc")
+            continue
+        out.append({"column": column, "direction": direction_raw})
+    return out, errors
+
+
+def validate_default_sort_metadata(
+    cursor,
+    table_name: str,
+    *,
+    physical_columns: list[str] | None = None,
+) -> tuple[list[str], list[str]]:
+    """校验表级 default_sort_json：列须真实存在；允许 visible=0；不存在则报错。
+
+    契约：visible=0 只藏界面，ORDER BY 仍可用非敏感物理列（含隐藏主键）。
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+    table_cols = {
+        str(row[1]) for row in cursor.execute("PRAGMA table_info(_jiangchang_tables)").fetchall()
+    }
+    if "default_sort_json" not in table_cols:
+        return [], []
+    cursor.execute(
+        "SELECT default_sort_json FROM _jiangchang_tables WHERE table_name = ?",
+        (table_name,),
+    )
+    row = cursor.fetchone()
+    if not row:
+        return [], []
+    specs, parse_errors = parse_default_sort_json(row[0])
+    for msg in parse_errors:
+        errors.append(f"{table_name}: {msg}")
+    if parse_errors:
+        return errors, warnings
+
+    physical = set(physical_columns or list_physical_column_names(cursor, table_name))
+    for spec in specs:
+        column = spec["column"]
+        if column not in physical:
+            errors.append(
+                f"{table_name}: default_sort_json 引用了不存在的列 {column!r}"
+            )
+            continue
+        # visible=0 合法：不报错。仅提示契约，避免作者误删排序列。
+        cursor.execute(
+            """
+            SELECT visible FROM _jiangchang_columns
+            WHERE table_name = ? AND column_name = ?
+            """,
+            (table_name, column),
+        )
+        meta = cursor.fetchone()
+        if meta is not None and meta[0] is not None and int(meta[0]) == 0:
+            warnings.append(
+                f"{table_name}.{column}: default_sort_json 引用了 visible=0 列"
+                "（合法：隐藏列仍可 ORDER BY；见 references/SCHEMA.md）"
+            )
+    return errors, warnings
+
+
 def validate_column_permissions(
     cursor,
     table_name: str,
@@ -511,6 +644,17 @@ def validate_display_metadata(conn: sqlite3.Connection, *, check_column_order: b
         report.errors.extend(perm_errors)
         report.warnings.extend(perm_warnings)
 
+        _, filter_warnings = validate_filter_search_metadata(cur, table_name)
+        report.warnings.extend(filter_warnings)
+
+        sort_errors, sort_warnings = validate_default_sort_metadata(
+            cur,
+            table_name,
+            physical_columns=physical_columns,
+        )
+        report.errors.extend(sort_errors)
+        report.warnings.extend(sort_warnings)
+
     cur.execute("SELECT table_name, column_name FROM _jiangchang_columns")
     for table_name, column_name in cur.fetchall():
         if table_name in METADATA_TABLES:

scripts/service/html_page_service.py

@@ -1,9 +1,11 @@
-"""技能 HTML 报告页：写入 `{skill_data}/html/*.html`（宿主扫描预览）。
+"""技能 HTML 快照：写入 `{skill_data}/html/*.html`（宿主扫描预览）。
 
 契约要点（权威说明见 `references/ACTIONS.md`「HTML 页面报告」）：
 
-- 目录：仅一层 `html/*.html`（非递归）
-- 重新生成 Action id 必须为 `render-html`（宿主硬编码）
+- 本模块只写快照。装完就有的壳子页放安装包 `assets/html/pages/*.html`，不要从这里拷过去
+- 快照目录：仅一层 `html/*.html`（非递归）
+- 重新生成 Action id 必须为 `render-html`（宿主硬编码；只针对快照）
+- 页面布局底线见 `references/ACTIONS.md`「宿主预览布局」；模板壳 `assets/html/example-report.html`
 - 成功后建议 `steps: refreshCatalog` 以重扫侧栏
 - 本模块只提供路径/模板/原子写；业务 KPI/表格由各技能自行填充
 """

scripts/util/constants.py

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

scripts/util/runtime_paths.py

@@ -134,7 +134,7 @@ def get_videos_dir(*, create: bool = True) -> str:
 
 
 def get_html_dir(*, create: bool = True) -> str:
-    """HTML 报告页目录：宿主扫描 `{skill_data}/html/*.html`（一层、非递归）。"""
+    """HTML 快照目录：宿主扫描 `{skill_data}/html/*.html`（一层、非递归）。壳子页不在这里。"""
     path = os.path.join(get_skill_data_dir(), STANDARD_SUBDIR_HTML)
     if create:
         os.makedirs(path, exist_ok=True)

scripts/util/slug_naming.py

@@ -7,7 +7,7 @@ import re
 
 _KEBAB_SLUG = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
 _MAX_SLUG_LENGTH = 48
-_MIN_SEGMENTS = 3
+_MIN_SEGMENTS = 2
 _MAX_SEGMENTS = 5
 _MAX_NOUN_SEGMENTS = 3
 
@@ -60,7 +60,9 @@ _BUILTIN_PLATFORMS = frozenset(
         "etax",
     }
 )
-_BUILTIN_SCOPES = frozenset({"all", "batch", "multi", "default"})
+_BUILTIN_SCOPES = frozenset({"all", "batch", "multi"})
+# 旧技能用 default 占位末段。不再当成合法 scope；校验只警告，避免同步后挡住已发布仓库。
+_DEPRECATED_PLATFORM_PLACEHOLDER = "default"
 
 LEGACY_EXEMPT_SLUGS: frozenset[str] = frozenset(
     {
@@ -117,11 +119,12 @@ def _match_platform_suffix(
 
 def classify_slug_form(segments: list[str], *, slug: str = "") -> str:
     """
-    返回: 'legacy_exempt' | 'standard' | 'scope' | 'invalid'
+    返回: 'legacy_exempt' | 'standard' | 'scope' | 'plain' | 'invalid'
 
     - legacy_exempt: slug in LEGACY_EXEMPT_SLUGS
-    - standard: 末段匹配 platforms, 首段 in verbs, 3<=len<=5
-    - scope: 末段 in scopes, 首段 in verbs, 3<=len<=5
+    - standard: 末段匹配 platforms，首段 in verbs，2<=len<=5，且动词后至少还有一段名词
+    - scope: 末段 in scopes（all/batch/multi），首段 in verbs，至少 verb-noun-scope
+    - plain: 动词 + 名词，无平台、无 scope
     - invalid: 其他
     """
     if slug in LEGACY_EXEMPT_SLUGS:
@@ -138,12 +141,14 @@ def classify_slug_form(segments: list[str], *, slug: str = "") -> str:
         return "invalid"
 
     if segments[-1] in scopes:
+        if len(segments) < 3:
+            return "invalid"
         return "scope"
 
     if _match_platform_suffix(segments, platforms) is not None:
         return "standard"
 
-    return "invalid"
+    return "plain"
 
 
 def validate_slug_semantics(
@@ -173,8 +178,8 @@ def validate_slug_semantics(
 
     if segment_count < _MIN_SEGMENTS:
         msg = (
-            f"slug 段数应为 {_MIN_SEGMENTS}～{_MAX_SEGMENTS}（verb-noun-platform），"
-            f"当前为 {segment_count} 段：{slug!r}；新技能禁止 2 段无平台形态（如 reconcile-finance）"
+            f"slug 段数应为 {_MIN_SEGMENTS}～{_MAX_SEGMENTS}（动词-名词，平台可选），"
+            f"当前为 {segment_count} 段：{slug!r}"
         )
         (errors if strict else warnings).append(msg)
         return errors, warnings
@@ -197,9 +202,6 @@ def validate_slug_semantics(
 
     form = classify_slug_form(segments, slug=slug)
     if form == "scope":
-        if segments[-1] not in scopes:
-            msg = f"slug 末段应为 scope 白名单中的词：{segments[-1]!r}（slug={slug!r}）"
-            (errors if strict else warnings).append(msg)
         noun_count = segment_count - 2
     elif form == "standard":
         platform_match = _match_platform_suffix(segments, platforms)
@@ -210,13 +212,17 @@ def validate_slug_semantics(
         else:
             _platform_name, platform_part_count = platform_match
             noun_count = segment_count - 1 - platform_part_count
+    elif form == "plain":
+        noun_count = segment_count - 1
+        if segments[-1] == _DEPRECATED_PLATFORM_PLACEHOLDER:
+            warnings.append(
+                "slug 末段 default 已不再作为平台占位；没有外部平台时直接省略。"
+                f"已发布的技能不用改名：{slug!r}"
+            )
     else:
-        if segment_count >= _MIN_SEGMENTS:
-            if segments[-1] not in scopes:
-                platform_match = _match_platform_suffix(segments, platforms)
-                if platform_match is None:
-                    msg = f"slug 末段应匹配平台或 scope 白名单：{slug!r}"
-                    (errors if strict else warnings).append(msg)
+        if segments and segments[-1] in scopes and segment_count < 3:
+            msg = f"scope 型 slug 至少为动词-名词-scope：{slug!r}"
+            (errors if strict else warnings).append(msg)
         noun_count = 0
 
     if noun_count > _MAX_NOUN_SEGMENTS:

sync.ps1

@@ -0,0 +1,668 @@
+<#
+.SYNOPSIS
+  Sync this skill's plaintext source into the local OpenClaw skills directory.
+
+.DESCRIPTION
+  Local development only. Does not commit, tag, push, or trigger Gitea CI.
+  release.ps1 remains the formal publish path.
+  Ships in skill-template beside release.ps1. Scaffold copies this file into each new skill.
+
+  Mirrors this repo onto ~/.openclaw/skills/<slug> and removes marketplace
+  pyarmor_runtime_* leftovers. Stop any running job for this skill first;
+  otherwise the copy can fail because files are in use.
+
+  Dependencies follow the host skill:direct-install path:
+    uv pip install --python <JIANGCHANG_DATA_ROOT>/python-runtime/.venv/Scripts/python.exe -r requirements.txt
+  Packages are not installed into system Python. Unchanged requirements that
+  are already present in the shared venv are skipped.
+
+  platform_kit_min_version is provided by jiangchang-platform-kit in the shared
+  runtime. This script only checks it. It does not upgrade the kit. If the
+  installed kit is too old, install or update the skill once from the market,
+  or upgrade the host.
+
+  After the copy, this script runs scripts\main.py init-db the same way the
+  host does after a market install. The user id is read from
+  %APPDATA%\jiangchang\settings.json (jiangchangUserId), which the host writes
+  on login and logout. It is never hardcoded. An empty id or _anon stops the
+  script so the anonymous data folder is not initialized by mistake.
+  -SkipInitDb skips that step. -SkipDeps still runs init-db.
+
+  No Chinese literals in this file: the skill repo requires UTF-8 without BOM,
+  and Windows PowerShell 5.1 would mis-parse a no-BOM UTF-8 script.
+
+.EXAMPLE
+  .\sync.ps1
+  .\sync.ps1 -DryRun
+  .\sync.ps1 -ForceDeps
+  .\sync.ps1 -SkipDeps
+  .\sync.ps1 -SkipInitDb
+  .\sync.ps1 -DataRoot D:\jiangchang-data
+#>
+[CmdletBinding()]
+param(
+  [string]$Destination,
+  [string]$DataRoot,
+  [switch]$SkipDeps,
+  [switch]$ForceDeps,
+  [switch]$SkipInitDb,
+  [switch]$DryRun
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$SourceRoot = $PSScriptRoot
+$PypiMirrors = @(
+  @{ Name = "aliyun"; Url = "https://mirrors.aliyun.com/pypi/simple/" },
+  @{ Name = "tuna"; Url = "https://pypi.tuna.tsinghua.edu.cn/simple/" },
+  @{ Name = "tencent"; Url = "https://mirrors.cloud.tencent.com/pypi/simple/" },
+  @{ Name = "huawei"; Url = "https://repo.huaweicloud.com/repository/pypi/simple/" },
+  @{ Name = "pypi"; Url = "https://pypi.org/simple/" }
+)
+
+function Read-Utf8Text {
+  param([Parameter(Mandatory = $true)][string]$Path)
+  return [System.IO.File]::ReadAllText($Path)
+}
+
+function Get-SkillFrontmatter {
+  param([Parameter(Mandatory = $true)][string]$SkillMdPath)
+  $raw = Read-Utf8Text -Path $SkillMdPath
+  if ($raw -notmatch '(?s)\A---\s*\r?\n(.*?)\r?\n---') {
+    throw "SKILL.md is missing frontmatter: $SkillMdPath"
+  }
+  return $Matches[1]
+}
+
+function Get-FrontmatterScalar {
+  param(
+    [Parameter(Mandatory = $true)][string]$Body,
+    [Parameter(Mandatory = $true)][string]$Key
+  )
+  $pattern = '(?m)^\s*' + [regex]::Escape($Key) + ':\s*["'']?([^\s"''#]+)["'']?\s*$'
+  $match = [regex]::Match($Body, $pattern)
+  if (-not $match.Success) {
+    return $null
+  }
+  return $match.Groups[1].Value.Trim()
+}
+
+function Get-RequirementsLines {
+  param([Parameter(Mandatory = $true)][string]$Content)
+  $lines = New-Object System.Collections.Generic.List[string]
+  foreach ($raw in ($Content -split '\r?\n')) {
+    $trimmed = $raw.Trim()
+    if (-not $trimmed -or $trimmed.StartsWith('#')) {
+      continue
+    }
+    $withoutInline = ($trimmed -split '\s+#', 2)[0].Trim()
+    if ($withoutInline) {
+      $lines.Add($withoutInline)
+    }
+  }
+  return @($lines)
+}
+
+function Get-RequirementsHash {
+  param([Parameter(Mandatory = $true)][string]$Content)
+  $normalized = (@(Get-RequirementsLines -Content $Content)) -join "`n"
+  $sha = [System.Security.Cryptography.SHA256]::Create()
+  try {
+    $bytes = [System.Text.Encoding]::UTF8.GetBytes($normalized)
+    $hash = $sha.ComputeHash($bytes)
+  } finally {
+    $sha.Dispose()
+  }
+  return ([System.BitConverter]::ToString($hash) -replace '-', '').ToLowerInvariant()
+}
+
+function Get-DistributionNames {
+  param([Parameter(Mandatory = $true)][string[]]$Lines)
+  $names = New-Object System.Collections.Generic.List[string]
+  $seen = New-Object 'System.Collections.Generic.HashSet[string]'
+  foreach ($line in $Lines) {
+    $trimmed = $line.Trim()
+    if (-not $trimmed -or $trimmed.StartsWith('#') -or $trimmed.StartsWith('-')) {
+      continue
+    }
+    if ($trimmed -match '^(https?:|git\+|svn\+|hg\+|file:)') {
+      continue
+    }
+    $match = [regex]::Match($trimmed, '^([A-Za-z0-9][A-Za-z0-9._-]*)')
+    if (-not $match.Success) {
+      continue
+    }
+    $name = $match.Groups[1].Value
+    $key = $name.ToLowerInvariant().Replace('_', '-')
+    if ($seen.Add($key)) {
+      $names.Add($name)
+    }
+  }
+  return @($names)
+}
+
+function Resolve-SkillDataRoot {
+  param([string]$Explicit)
+  if ($Explicit -and $Explicit.Trim()) {
+    return $Explicit.Trim().TrimEnd('\')
+  }
+
+  $settingsPath = Join-Path $env:APPDATA "jiangchang\settings.json"
+  if (Test-Path -LiteralPath $settingsPath) {
+    try {
+      $settings = Read-Utf8Text -Path $settingsPath | ConvertFrom-Json
+      $fromSettings = [string]$settings.jiangchangSkillDataRoot
+      if ($fromSettings -and $fromSettings.Trim()) {
+        return $fromSettings.Trim().TrimEnd('\')
+      }
+    } catch {
+      Write-Warning "Could not read $settingsPath. Falling back to the default data root. $($_.Exception.Message)"
+    }
+  }
+
+  foreach ($candidate in @("D:\jiangchang-data", (Join-Path $env:USERPROFILE ".jiangchang-data"))) {
+    $python = Join-Path $candidate "python-runtime\.venv\Scripts\python.exe"
+    if (Test-Path -LiteralPath $python) {
+      return $candidate
+    }
+  }
+
+  return "D:\jiangchang-data"
+}
+
+function Resolve-JiangchangUserId {
+  $settingsPath = Join-Path $env:APPDATA "jiangchang\settings.json"
+  if (-not (Test-Path -LiteralPath $settingsPath)) {
+    throw "Jiangchang settings were not found: $settingsPath`nOpen Jiangchang and log in, then run this script again."
+  }
+  try {
+    $settings = Read-Utf8Text -Path $settingsPath | ConvertFrom-Json
+  } catch {
+    throw "Could not read the logged-in user from $settingsPath. $($_.Exception.Message)"
+  }
+  $userId = ""
+  if ($null -ne $settings -and $settings.PSObject.Properties.Name -contains "jiangchangUserId" -and $null -ne $settings.jiangchangUserId) {
+    $userId = ([string]$settings.jiangchangUserId).Trim()
+  }
+  if (-not $userId -or $userId -eq "_anon") {
+    throw "Jiangchang has no logged-in user. Open Jiangchang and log in, then run this script again. This script does not guess a user id."
+  }
+  $normalized = $userId.Replace("\", "/")
+  if ($normalized.Contains("..") -or $normalized.Contains("/") -or $userId.StartsWith("\") -or $userId -match '^[A-Za-z]:') {
+    throw "jiangchangUserId is not a single folder name: $userId"
+  }
+  return $userId
+}
+
+function Test-InitDbJsonOk {
+  param([Parameter(Mandatory = $true)][string]$Text)
+  foreach ($line in ($Text -split "`r?`n")) {
+    $trimmed = $line.Trim()
+    if (-not $trimmed.StartsWith("{")) {
+      continue
+    }
+    try {
+      $parsed = $trimmed | ConvertFrom-Json
+      if ($parsed.ok -eq $true) {
+        return $true
+      }
+    } catch {
+      continue
+    }
+  }
+  return $false
+}
+
+function Test-InitDbUnknownCommand {
+  param(
+    [Parameter(Mandatory = $true)][string]$Text,
+    [Parameter(Mandatory = $true)][int]$ExitCode
+  )
+  if ($ExitCode -eq 2) {
+    return $true
+  }
+  $lower = $Text.ToLowerInvariant()
+  if ($lower.Contains("invalid choice") -or $lower.Contains("unrecognized arguments") -or $lower.Contains("unknown command")) {
+    return $true
+  }
+  if ($lower.Contains("invalid") -and $lower.Contains("init-db")) {
+    return $true
+  }
+  return $false
+}
+
+function Invoke-SkillInitDb {
+  param(
+    [Parameter(Mandatory = $true)][string]$PythonExe,
+    [Parameter(Mandatory = $true)][string]$SkillDir,
+    [Parameter(Mandatory = $true)][string]$DataRoot,
+    [Parameter(Mandatory = $true)][string]$UserId,
+    [switch]$DryRun
+  )
+  $mainPy = Join-Path $SkillDir "scripts\main.py"
+  if (-not (Test-Path -LiteralPath $mainPy)) {
+    Write-Host "No scripts\main.py. Skipping init-db."
+    return
+  }
+  if ($DryRun) {
+    Write-Host "DryRun: would run init-db" -ForegroundColor Yellow
+    Write-Host "  python   $PythonExe"
+    Write-Host "  script   $mainPy init-db"
+    Write-Host "  data     $DataRoot"
+    Write-Host "  user     $UserId"
+    return
+  }
+  if (-not (Test-Path -LiteralPath $PythonExe)) {
+    throw "Shared Python was not found: $PythonExe`nOpen Jiangchang and wait for the shared runtime, or pass -DataRoot."
+  }
+
+  Write-Host ">> Initialize the logged-in user's database (init-db)" -ForegroundColor DarkGray
+  Write-Host "   user=$UserId"
+
+  $psi = New-Object System.Diagnostics.ProcessStartInfo
+  $psi.FileName = $PythonExe
+  $psi.WorkingDirectory = $SkillDir
+  $psi.UseShellExecute = $false
+  $psi.RedirectStandardOutput = $true
+  $psi.RedirectStandardError = $true
+  $psi.CreateNoWindow = $true
+  $psi.Arguments = '"' + $mainPy + '" init-db'
+  $psi.StandardOutputEncoding = [System.Text.Encoding]::UTF8
+  $psi.StandardErrorEncoding = [System.Text.Encoding]::UTF8
+  $psi.EnvironmentVariables["JIANGCHANG_DATA_ROOT"] = $DataRoot
+  $psi.EnvironmentVariables["JIANGCHANG_USER_ID"] = $UserId
+  $psi.EnvironmentVariables["JIANGCHANG_RUN_MODE"] = "cli"
+  $psi.EnvironmentVariables["PYTHONIOENCODING"] = "utf-8"
+
+  $proc = New-Object System.Diagnostics.Process
+  $proc.StartInfo = $psi
+  [void]$proc.Start()
+  $stdoutTask = $proc.StandardOutput.ReadToEndAsync()
+  $stderrTask = $proc.StandardError.ReadToEndAsync()
+  if (-not $proc.WaitForExit(60000)) {
+    try { $proc.Kill() } catch { }
+    throw "init-db timed out after 60 seconds."
+  }
+  $proc.WaitForExit()
+  $stdout = $stdoutTask.Result
+  $stderr = $stderrTask.Result
+  $combined = ($stdout + "`n" + $stderr).Trim()
+  if ($stdout.Trim()) {
+    Write-Host $stdout.Trim()
+  }
+  if ($stderr.Trim()) {
+    Write-Host $stderr.Trim()
+  }
+
+  if (Test-InitDbJsonOk -Text $combined) {
+    Write-Host "init-db finished for user $UserId." -ForegroundColor Green
+    return
+  }
+  if ($proc.ExitCode -eq 0 -and $combined -match '(?m)^OK:\s*INIT_DB\b') {
+    Write-Host "init-db finished for user $UserId." -ForegroundColor Green
+    return
+  }
+  if (Test-InitDbUnknownCommand -Text $combined -ExitCode $proc.ExitCode) {
+    Write-Warning "This skill has no init-db command. Database initialization was skipped."
+    return
+  }
+
+  $detail = $stderr.Trim()
+  if (-not $detail) {
+    $detail = $stdout.Trim()
+  }
+  if ($detail.Length -gt 500) {
+    $detail = $detail.Substring($detail.Length - 500)
+  }
+  if (-not $detail) {
+    $detail = "init-db exited with code $($proc.ExitCode)"
+  }
+  throw "init-db failed for user ${UserId}: $detail"
+}
+
+function Resolve-UvExecutable {
+  $cmd = Get-Command uv -ErrorAction SilentlyContinue
+  if ($cmd -and $cmd.Source) {
+    return $cmd.Source
+  }
+  throw "uv was not found on PATH. The host installs skill requirements with uv pip, not pip."
+}
+
+function Test-DistributionsPresent {
+  param(
+    [Parameter(Mandatory = $true)][string]$PythonExe,
+    [Parameter(Mandatory = $true)][string[]]$Names
+  )
+  if ($Names.Count -eq 0) {
+    return $false
+  }
+  $probe = @'
+from importlib.metadata import PackageNotFoundError, version
+import sys
+missing = []
+for n in sys.argv[1:]:
+    try:
+        version(n)
+    except PackageNotFoundError:
+        missing.append(n)
+sys.stderr.write("missing:" + ",".join(missing) if missing else "")
+raise SystemExit(1 if missing else 0)
+'@
+  $prev = $ErrorActionPreference
+  $ErrorActionPreference = "Continue"
+  try {
+    & $PythonExe -c $probe @Names 2>&1 | Out-Null
+    return ($LASTEXITCODE -eq 0)
+  } finally {
+    $ErrorActionPreference = $prev
+  }
+}
+
+function Get-InstalledDistributionVersion {
+  param(
+    [Parameter(Mandatory = $true)][string]$PythonExe,
+    [Parameter(Mandatory = $true)][string]$Name
+  )
+  $prev = $ErrorActionPreference
+  $ErrorActionPreference = "Continue"
+  try {
+    $output = & $PythonExe -c "from importlib.metadata import version, PackageNotFoundError`nimport sys`nname=sys.argv[1]`ntry:`n print(version(name))`nexcept PackageNotFoundError:`n print('')" $Name 2>$null
+    $code = $LASTEXITCODE
+  } finally {
+    $ErrorActionPreference = $prev
+  }
+  if ($code -ne 0) {
+    return $null
+  }
+  return ([string]$output).Trim()
+}
+
+function Compare-VersionPrefix {
+  param(
+    [Parameter(Mandatory = $true)][string]$Installed,
+    [Parameter(Mandatory = $true)][string]$Required
+  )
+  function Convert-ToVersion([string]$Text) {
+    $core = ($Text -split '[^0-9.]', 2)[0].Trim('.')
+    $parts = @($core -split '\.' | Where-Object { $_ -ne '' })
+    while ($parts.Count -lt 3) {
+      $parts += '0'
+    }
+    $take = @($parts | Select-Object -First 3)
+    return [version]($take -join '.')
+  }
+  try {
+    return (Convert-ToVersion $Installed) -ge (Convert-ToVersion $Required)
+  } catch {
+    return $true
+  }
+}
+
+function Invoke-RobocopyMirror {
+  param(
+    [Parameter(Mandatory = $true)][string]$Source,
+    [Parameter(Mandatory = $true)][string]$Dest,
+    [switch]$ListOnly
+  )
+  $excludeDirs = @(
+    ".git", ".github", "__pycache__", ".pytest_cache", "htmlcov",
+    "dist", "build", ".venv", "_fix_workspace", ".skill-requirements"
+  )
+  $excludeFiles = @(".env", "*.env.local", "*.pyc", "*.pyo")
+  $robocopyArgs = @($Source, $Dest, "/MIR", "/R:2", "/W:1", "/XD") + $excludeDirs + @("/XF") + $excludeFiles
+  if ($ListOnly) {
+    $robocopyArgs += "/L"
+  }
+  & robocopy.exe @robocopyArgs
+  $code = $LASTEXITCODE
+  if ($code -ge 8) {
+    throw "Copy failed (robocopy exit $code). Stop the running skill job in Task Center, then retry."
+  }
+}
+
+function Remove-PyarmorRuntimes {
+  param([Parameter(Mandatory = $true)][string]$Dest)
+  $removed = @()
+  $dirs = @(Get-ChildItem -LiteralPath $Dest -Recurse -Directory -Force -ErrorAction SilentlyContinue |
+    Where-Object { $_.Name -like "pyarmor_runtime_*" })
+  foreach ($dir in $dirs) {
+    Remove-Item -LiteralPath $dir.FullName -Recurse -Force
+    $removed += $dir.FullName
+  }
+  return $removed
+}
+
+function Assert-PlainMainPy {
+  param([Parameter(Mandatory = $true)][string]$MainPy)
+  if (-not (Test-Path -LiteralPath $MainPy)) {
+    throw "scripts\main.py is missing after sync: $MainPy"
+  }
+  $head = Read-Utf8Text -Path $MainPy
+  if ($head -match 'pyarmor_runtime_|__pyarmor__') {
+    throw "scripts\main.py is still PyArmor-encrypted. Re-run .\sync.ps1 so the whole scripts tree is replaced."
+  }
+}
+
+function Write-RequirementsState {
+  param(
+    [Parameter(Mandatory = $true)][string]$RuntimeDir,
+    [Parameter(Mandatory = $true)][string]$Slug,
+    [Parameter(Mandatory = $true)][string]$RequirementsPath,
+    [Parameter(Mandatory = $true)][string]$RequirementsHash,
+    [string]$RuntimeFingerprint
+  )
+  $stateDir = Join-Path $RuntimeDir ".skill-requirements"
+  New-Item -ItemType Directory -Force -Path $stateDir | Out-Null
+  $state = [ordered]@{
+    skill              = $Slug
+    requirementsPath   = $RequirementsPath
+    requirementsHash   = $RequirementsHash
+    runtimeFingerprint = $RuntimeFingerprint
+    installedAt        = [DateTime]::UtcNow.ToString("o")
+    status             = "ok"
+  }
+  $json = ($state | ConvertTo-Json -Depth 4) + "`n"
+  $statePath = Join-Path $stateDir "$Slug.json"
+  $utf8 = New-Object System.Text.UTF8Encoding $false
+  [System.IO.File]::WriteAllText($statePath, $json, $utf8)
+}
+
+$skillMd = Join-Path $SourceRoot "SKILL.md"
+$sourceMain = Join-Path $SourceRoot "scripts\main.py"
+$sourceReq = Join-Path $SourceRoot "requirements.txt"
+if (-not (Test-Path -LiteralPath $skillMd)) {
+  throw "SKILL.md not found: $skillMd"
+}
+if (-not (Test-Path -LiteralPath $sourceMain)) {
+  throw "scripts\main.py not found: $sourceMain"
+}
+
+$frontmatter = Get-SkillFrontmatter -SkillMdPath $skillMd
+$slug = Get-FrontmatterScalar -Body $frontmatter -Key "slug"
+$version = Get-FrontmatterScalar -Body $frontmatter -Key "version"
+$platformKitMin = Get-FrontmatterScalar -Body $frontmatter -Key "platform_kit_min_version"
+if (-not $slug) {
+  throw "metadata.openclaw.slug in SKILL.md is empty, so the install directory cannot be determined."
+}
+
+if (-not $Destination -or -not $Destination.Trim()) {
+  $Destination = Join-Path $env:USERPROFILE ".openclaw\skills\$slug"
+}
+$Destination = $Destination.Trim().TrimEnd('\')
+
+$sourceFull = [System.IO.Path]::GetFullPath($SourceRoot)
+$destFull = [System.IO.Path]::GetFullPath($Destination)
+if ($sourceFull.TrimEnd('\') -eq $destFull.TrimEnd('\')) {
+  throw "Source and destination are the same directory: $sourceFull"
+}
+
+$resolvedDataRoot = Resolve-SkillDataRoot -Explicit $DataRoot
+$runtimeDir = Join-Path $resolvedDataRoot "python-runtime"
+$pythonExe = Join-Path $runtimeDir ".venv\Scripts\python.exe"
+$resolvedUserId = $null
+if (-not $SkipInitDb) {
+  $resolvedUserId = Resolve-JiangchangUserId
+}
+
+Write-Host ""
+Write-Host "Local skill sync (does not publish to the skill market)" -ForegroundColor Cyan
+Write-Host "  source   $sourceFull"
+Write-Host "  dest     $destFull"
+Write-Host "  slug     $slug"
+Write-Host "  version  $(if ($version) { $version } else { '(none)' })"
+Write-Host "  data     $resolvedDataRoot"
+Write-Host "  python   $pythonExe"
+Write-Host "  user     $(if ($SkipInitDb) { '(init-db skipped)' } else { $resolvedUserId })"
+if ($DryRun) {
+  Write-Host "  mode     DryRun (no writes)" -ForegroundColor Yellow
+}
+Write-Host ""
+
+if (-not (Test-Path -LiteralPath $destFull)) {
+  Write-Warning "Destination does not exist yet. Files can be created, but if this skill was never installed from the market the host may not have enabled it. Install it once, then use this script to overwrite."
+}
+
+$configPath = Join-Path $env:USERPROFILE ".openclaw\openclaw.json"
+if (Test-Path -LiteralPath $configPath) {
+  try {
+    $config = Read-Utf8Text -Path $configPath | ConvertFrom-Json
+    $entry = $null
+    if ($config.PSObject.Properties.Name -contains "skills" -and $null -ne $config.skills -and $config.skills.PSObject.Properties.Name -contains "entries" -and $null -ne $config.skills.entries) {
+      $entryProp = $config.skills.entries.PSObject.Properties[$slug]
+      if ($entryProp) {
+        $entry = $entryProp.Value
+      }
+    }
+    if ($null -eq $entry) {
+      Write-Warning "openclaw.json has no skills.entries.$slug. Install the skill once from the market, or chat and data management may not see it."
+    } elseif ($entry.PSObject.Properties.Name -contains "enabled" -and $entry.enabled -eq $false) {
+      Write-Warning "skills.entries.$slug is disabled. Syncing files does not re-enable it."
+    }
+  } catch {
+    Write-Warning "Could not check openclaw.json enablement: $($_.Exception.Message)"
+  }
+}
+
+Write-Host ">> Mirror source onto the install directory (exclude .git, drop encrypted runtime)" -ForegroundColor DarkGray
+Invoke-RobocopyMirror -Source $sourceFull -Dest $destFull -ListOnly:$DryRun
+if (-not $DryRun) {
+  $removed = @(Remove-PyarmorRuntimes -Dest $destFull)
+  foreach ($path in $removed) {
+    Write-Host "  removed $path"
+  }
+  Assert-PlainMainPy -MainPy (Join-Path $destFull "scripts\main.py")
+  Write-Host "scripts\main.py is plaintext." -ForegroundColor Green
+} else {
+  Write-Host "DryRun: pyarmor_runtime_* was not deleted, and no destination file was changed." -ForegroundColor Yellow
+}
+
+$skipInstall = $false
+if ($SkipDeps) {
+  Write-Host "Skipped dependency install (-SkipDeps)." -ForegroundColor Yellow
+  $skipInstall = $true
+} elseif (-not (Test-Path -LiteralPath $pythonExe)) {
+  throw "Shared Python was not found: $pythonExe`nOpen Jiangchang and wait for the shared runtime, or pass -DataRoot. If the copy already finished, install dependencies before running the skill."
+} else {
+  $reqPath = if ($DryRun) { $sourceReq } else { Join-Path $destFull "requirements.txt" }
+  if (-not (Test-Path -LiteralPath $reqPath)) {
+    Write-Host "No requirements.txt. Skipping dependency install."
+    $skipInstall = $true
+  } else {
+    $reqContent = Read-Utf8Text -Path $reqPath
+    $reqLines = @(Get-RequirementsLines -Content $reqContent)
+    if ($reqLines.Count -eq 0) {
+      Write-Host "requirements.txt has no effective lines. Skipping install."
+      $skipInstall = $true
+    }
+  }
+}
+
+if (-not $skipInstall) {
+
+$reqHash = Get-RequirementsHash -Content $reqContent
+$stampPath = Join-Path $runtimeDir ".jiangchang-runtime-stamp.json"
+$runtimeFingerprint = ""
+if (Test-Path -LiteralPath $stampPath) {
+  try {
+    $stamp = Read-Utf8Text -Path $stampPath | ConvertFrom-Json
+    $runtimeFingerprint = [string]$stamp.fingerprint
+  } catch {
+    $runtimeFingerprint = ""
+  }
+}
+
+$statePath = Join-Path $runtimeDir ".skill-requirements\$slug.json"
+$previousHash = ""
+$previousFingerprint = ""
+$previousStatus = ""
+if (Test-Path -LiteralPath $statePath) {
+  try {
+    $previous = Read-Utf8Text -Path $statePath | ConvertFrom-Json
+    $previousHash = [string]$previous.requirementsHash
+    $previousFingerprint = [string]$previous.runtimeFingerprint
+    $previousStatus = [string]$previous.status
+  } catch {
+    $previousStatus = ""
+  }
+}
+
+$distributionNames = @(Get-DistributionNames -Lines $reqLines)
+$unchanged = (
+  -not $ForceDeps -and
+  $previousStatus -eq "ok" -and
+  $previousHash -eq $reqHash -and
+  $runtimeFingerprint -and
+  $previousFingerprint -eq $runtimeFingerprint
+)
+if ($unchanged -and $distributionNames.Count -gt 0 -and (Test-DistributionsPresent -PythonExe $pythonExe -Names $distributionNames)) {
+  Write-Host "Requirements unchanged and already present in the shared environment. Skipping uv pip install." -ForegroundColor Green
+} elseif ($DryRun) {
+  Write-Host "DryRun: would run uv pip install -r requirements.txt" -ForegroundColor Yellow
+  $distributionNames | ForEach-Object { Write-Host "  - $_" }
+} else {
+  $uv = Resolve-UvExecutable
+  Write-Host ">> Install skill requirements into the shared environment" -ForegroundColor DarkGray
+  Write-Host "   uv=$uv"
+  $installed = $false
+  foreach ($mirror in $PypiMirrors) {
+    Write-Host ">> uv pip install --index-url $($mirror.Url)" -ForegroundColor DarkGray
+    & $uv pip install --index-url $mirror.Url --python $pythonExe -r $reqPath
+    if ($LASTEXITCODE -eq 0) {
+      $installed = $true
+      break
+    }
+    Write-Warning "Mirror $($mirror.Name) failed (exit $LASTEXITCODE). Trying the next one."
+  }
+  if (-not $installed) {
+    throw "requirements.txt install failed. Code is already at $destFull, but the shared environment is missing dependencies."
+  }
+  Write-RequirementsState -RuntimeDir $runtimeDir -Slug $slug -RequirementsPath $reqPath -RequirementsHash $reqHash -RuntimeFingerprint $runtimeFingerprint
+  Write-Host "Dependencies are installed in the shared environment." -ForegroundColor Green
+  }
+}
+
+if ($platformKitMin -and (Test-Path -LiteralPath $pythonExe)) {
+  $kitVersion = Get-InstalledDistributionVersion -PythonExe $pythonExe -Name "jiangchang-platform-kit"
+  if (-not $kitVersion) {
+    Write-Warning "jiangchang-platform-kit is not installed in the shared environment, but this skill requires >= $platformKitMin."
+  } elseif (-not (Compare-VersionPrefix -Installed $kitVersion -Required $platformKitMin)) {
+    Write-Warning "jiangchang-platform-kit $kitVersion is below this skill's requirement >= $platformKitMin. This script does not upgrade the platform kit."
+  } else {
+    Write-Host "platform kit $kitVersion satisfies >= $platformKitMin." -ForegroundColor Green
+  }
+}
+
+if ($SkipInitDb) {
+  Write-Host "Skipped init-db (-SkipInitDb). The database was not updated." -ForegroundColor Yellow
+} else {
+  $initSkillDir = $destFull
+  if ($DryRun -and -not (Test-Path -LiteralPath (Join-Path $destFull "scripts\main.py"))) {
+    $initSkillDir = $sourceFull
+  }
+  Invoke-SkillInitDb -PythonExe $pythonExe -SkillDir $initSkillDir -DataRoot $resolvedDataRoot -UserId $resolvedUserId -DryRun:$DryRun
+}
+
+Write-Host ""
+Write-Host "Done. Stop any running job, leave Data Management, then open it again." -ForegroundColor Cyan
+Write-Host "Do not click Update in the skill market. That replaces this source with the encrypted package." -ForegroundColor Cyan

tests/samples/test_table_deprecation_migration.py.sample

@@ -0,0 +1,66 @@
+# -*- coding: utf-8 -*-
+"""旧库废弃表迁移样例（复制到 tests/ 并按技能改写）。
+
+验收：给定旧库含废弃物理表 + 元数据 + 历史行 → init_db() 后表与元数据均清除。
+见 references/SCHEMA.md「表增删改与退役」。
+"""
+from __future__ import annotations
+
+import unittest
+
+from _support import IsolatedDataRoot
+
+
+class TestTableDeprecationMigration(unittest.TestCase):
+  def test_init_db_drops_legacy_task_logs(self) -> None:
+    with IsolatedDataRoot():
+      from db.connection import get_conn, init_db
+      from db.display_metadata import iter_user_tables
+
+      # 1) 模拟升级前的旧库
+      init_db()
+      conn = get_conn()
+      try:
+        cur = conn.cursor()
+        cur.execute(
+          """
+          CREATE TABLE task_logs (
+            id INTEGER PRIMARY KEY,
+            task_type TEXT,
+            status TEXT
+          )
+          """
+        )
+        cur.execute(
+          """
+          INSERT INTO _jiangchang_tables
+          (table_name, display_name, visible, readonly)
+          VALUES ('task_logs', '任务日志', 1, 0)
+          """
+        )
+        cur.execute("INSERT INTO task_logs (task_type, status) VALUES ('run', 'ok')")
+        conn.commit()
+      finally:
+        conn.close()
+
+      # 2) 新代码 init_db() 应幂等清除（在 connection.init_db 中调用 drop_deprecated_user_table）
+      init_db()
+
+      conn = get_conn()
+      try:
+        cur = conn.cursor()
+        cur.execute(
+          "SELECT 1 FROM sqlite_master WHERE type='table' AND name='task_logs'"
+        )
+        self.assertIsNone(cur.fetchone())
+        cur.execute(
+          "SELECT COUNT(*) FROM _jiangchang_tables WHERE table_name='task_logs'"
+        )
+        self.assertEqual(int(cur.fetchone()[0]), 0)
+        self.assertNotIn("task_logs", list(iter_user_tables(cur)))
+      finally:
+        conn.close()
+
+
+if __name__ == "__main__":
+  unittest.main()

tests/test_actions_manifest.py

@@ -74,8 +74,17 @@ 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"]
-    if set(bind.keys()) - {"tables"}:
-        errors.append(f"{action_id}: bind only allows tables, got {sorted(bind.keys())}")
+    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())}")
     tables = bind.get("tables")
     if not isinstance(tables, list) or len(tables) < 1:
         errors.append(f"{action_id}: bind.tables must be non-empty array")
@@ -90,6 +99,20 @@ def _validate_bind_tables(action_id: str, bind: object) -> list[str]:
         if table in seen:
             errors.append(f"{action_id}: bind.tables duplicate {table!r}")
         seen.add(table)
+    label_column = bind.get("labelColumn")
+    if label_column is not None:
+        if not isinstance(label_column, str) or not label_column.strip():
+            errors.append(f"{action_id}: bind.labelColumn must be non-empty string")
+        elif not _TABLE_NAME_PATTERN.fullmatch(label_column):
+            errors.append(f"{action_id}: bind.labelColumn {label_column!r} must be snake_case")
+    selection_mode = bind.get("selectionMode")
+    if selection_mode is not None and selection_mode not in ("required", "none", "optional"):
+        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
 
 
@@ -432,6 +455,181 @@ class TestActionsManifest(unittest.TestCase):
         with self.assertRaises(ValidationError):
             jsonschema.validate(instance=manifest, schema=schema)
 
+    def test_schema_allows_bind_label_column(self) -> None:
+        try:
+            import jsonschema
+        except ImportError:
+            self.fail("jsonschema is required")
+        schema = _load_actions_schema()
+        bind_props = schema["$defs"]["bind"]["properties"]
+        self.assertIn("labelColumn", bind_props)
+        manifest = {
+            "schemaVersion": 1,
+            "skill": "your-skill-slug",
+            "actions": [
+                {
+                    "id": "probe-label-column",
+                    "label": "处理勾选",
+                    "description": "验证 bind.labelColumn 可通过 Schema",
+                    "placements": ["toolbar", "batch"],
+                    "executionProfile": "sync",
+                    "interaction": "confirm",
+                    "bind": {
+                        "tables": ["demo_items"],
+                        "inputMapping": {"ids": "$selection.ids"},
+                        "labelColumn": "display_name",
+                    },
+                    "entrypoint": {"type": "cli", "command": "health", "args": []},
+                }
+            ],
+        }
+        jsonschema.validate(instance=manifest, schema=schema)
+
+    def test_schema_allows_bind_selection_mode(self) -> None:
+        try:
+            import jsonschema
+        except ImportError:
+            self.fail("jsonschema is required")
+        schema = _load_actions_schema()
+        bind_props = schema["$defs"]["bind"]["properties"]
+        self.assertIn("selectionMode", bind_props)
+        self.assertEqual(
+            bind_props["selectionMode"].get("enum"),
+            ["required", "none", "optional"],
+        )
+        manifest = {
+            "schemaVersion": 1,
+            "skill": "your-skill-slug",
+            "actions": [
+                {
+                    "id": "probe-selection-mode",
+                    "label": "处理队列",
+                    "description": "验证 bind.selectionMode 可通过 Schema",
+                    "placements": ["toolbar", "batch"],
+                    "executionProfile": "async",
+                    "interaction": "form",
+                    "bind": {
+                        "tables": ["demo_items"],
+                        "selectionMode": "optional",
+                        "inputMapping": {"itemIds": "$selection.ids"},
+                        "labelColumn": "display_name",
+                    },
+                    "inputSchema": {
+                        "type": "object",
+                        "required": ["itemIds", "pickCount"],
+                        "properties": {
+                            "itemIds": {"type": "string", "readOnly": True},
+                            "pickCount": {"type": "number", "default": 1, "minimum": 1},
+                        },
+                    },
+                    "entrypoint": {
+                        "type": "cli",
+                        "command": "process",
+                        "args": ["--ids", "{{itemIds}}", "--pick", "{{pickCount}}"],
+                    },
+                }
+            ],
+        }
+        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")
+        # 故意拆开，避免本测试源码触发自身扫描。
+        forbidden = (
+            "pickCount",
+            "itemIds",
+            "status=",
+            "import-urls",
+            "download-enqueue",
+            "bind.selectionMode",
+            "selectionMode=",
+        )
+        # async/pending 作为整词出现在 description 才禁止；executionProfile 值除外。
+        word_forbidden = re.compile(r"\b(async|pending|sync)\b", re.I)
+
+        for name in os.listdir(examples_dir):
+            if not name.endswith(".action.example.json"):
+                continue
+            path = os.path.join(examples_dir, name)
+            with open(path, encoding="utf-8") as f:
+                data = json.load(f)
+            actions = data["actions"] if isinstance(data, dict) and "actions" in data else [data]
+            for action in actions:
+                if not isinstance(action, dict):
+                    continue
+                texts: list[str] = []
+                for key in ("description",):
+                    if action.get(key):
+                        texts.append(str(action[key]))
+                conf = action.get("confirmation") or {}
+                if isinstance(conf, dict) and conf.get("message"):
+                    texts.append(str(conf["message"]))
+                props = ((action.get("inputSchema") or {}).get("properties")) or {}
+                for prop in props.values():
+                    if not isinstance(prop, dict):
+                        continue
+                    for key in ("title", "description"):
+                        if prop.get(key):
+                            texts.append(str(prop[key]))
+                blob = "\n".join(texts)
+                for token in forbidden:
+                    self.assertNotIn(
+                        token,
+                        blob,
+                        msg=f"{name} user-facing copy must not contain {token!r}",
+                    )
+                match = word_forbidden.search(blob)
+                if match is not None:
+                    self.fail(
+                        f"{name} user-facing copy must not contain {match.group(0)!r}"
+                    )
+
     def test_no_execution_profile_placement_coupling_in_tests(self) -> None:
         """守护：本文件不得引入入口位置与 sync/async 的错误硬耦合断言。"""
         path = os.path.join(get_skill_root(), "tests", "test_actions_manifest.py")
@@ -593,6 +791,17 @@ class TestActionsManifest(unittest.TestCase):
             "afterFailure",
             "cellPresentation",
             "CELL_PRESENTATION.md",
+            "整行",
+            "labelColumn",
+            "selectionMode",
+            "勾选驱动",
+            "行菜单显隐",
+            "bind.visibleWhen",
+            "用户可见文案",
+            "双受众",
+            "已选择",
+            "revealInForm",
+            "映射只读",
         ):
             self.assertIn(marker, text, msg=f"ACTIONS.md missing {marker!r}")
         self.assertNotIn(

tests/test_cell_presentation_contract.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""Cell Presentation 契约：schema + 文档 + 示例。"""
+"""Cell / Grid Presentation 契约：schema + 文档 + 示例。"""
 from __future__ import annotations
 
 import json
@@ -9,31 +9,34 @@ import unittest
 from util.runtime_paths import get_skill_root
 
 
-def _load_schema() -> dict:
-    path = os.path.join(
-        get_skill_root(),
-        "assets",
-        "schemas",
-        "skill-cell-presentation.schema.json",
-    )
-    with open(path, encoding="utf-8") as f:
+def _skill_path(*parts: str) -> str:
+    return os.path.join(get_skill_root(), *parts)
+
+
+def _load_json(*parts: str) -> dict:
+    with open(_skill_path(*parts), encoding="utf-8") as f:
         return json.load(f)
 
 
-def _load_example() -> dict:
-    path = os.path.join(
-        get_skill_root(),
-        "assets",
-        "examples",
-        "skill-cell-presentation.example.json",
-    )
-    with open(path, encoding="utf-8") as f:
-        return json.load(f)
+def _load_cell_schema() -> dict:
+    return _load_json("assets", "schemas", "skill-cell-presentation.schema.json")
+
+
+def _load_cell_example() -> dict:
+    return _load_json("assets", "examples", "skill-cell-presentation.example.json")
+
+
+def _load_grid_schema() -> dict:
+    return _load_json("assets", "schemas", "skill-grid-presentation.schema.json")
+
+
+def _load_grid_example() -> dict:
+    return _load_json("assets", "examples", "skill-grid-presentation.example.json")
 
 
 class TestCellPresentationContract(unittest.TestCase):
     def test_schema_file_exists_and_parses(self) -> None:
-        schema = _load_schema()
+        schema = _load_cell_schema()
         self.assertEqual(schema.get("title"), "SkillCellPresentationDocument")
         self.assertIs(schema.get("additionalProperties"), False)
         self.assertEqual(schema["properties"]["schemaVersion"].get("const"), 1)
@@ -45,33 +48,38 @@ class TestCellPresentationContract(unittest.TestCase):
             import jsonschema
         except ImportError:
             self.skipTest("jsonschema not installed")
-        jsonschema.validate(instance=_load_example(), schema=_load_schema())
+        jsonschema.validate(instance=_load_cell_example(), schema=_load_cell_schema())
 
     def test_actions_schema_defines_cell_presentation_enable_block(self) -> None:
-        path = os.path.join(
-            get_skill_root(), "assets", "schemas", "skill-actions.schema.json"
-        )
-        with open(path, encoding="utf-8") as f:
-            actions_schema = json.load(f)
+        actions_schema = _load_json("assets", "schemas", "skill-actions.schema.json")
         self.assertIn("cellPresentation", actions_schema["properties"])
         self.assertIn("cellPresentationDeclaration", actions_schema["$defs"])
 
     def test_docs_and_example_exist(self) -> None:
-        root = get_skill_root()
-        self.assertTrue(os.path.isfile(os.path.join(root, "references", "CELL_PRESENTATION.md")))
+        self.assertTrue(os.path.isfile(_skill_path("references", "CELL_PRESENTATION.md")))
         self.assertTrue(
             os.path.isfile(
-                os.path.join(root, "assets", "schemas", "skill-cell-presentation.schema.json")
+                _skill_path("assets", "schemas", "skill-cell-presentation.schema.json")
             )
         )
         self.assertTrue(
             os.path.isfile(
-                os.path.join(root, "assets", "examples", "skill-cell-presentation.example.json")
+                _skill_path("assets", "examples", "skill-cell-presentation.example.json")
+            )
+        )
+        self.assertTrue(
+            os.path.isfile(
+                _skill_path("assets", "schemas", "skill-grid-presentation.schema.json")
+            )
+        )
+        self.assertTrue(
+            os.path.isfile(
+                _skill_path("assets", "examples", "skill-grid-presentation.example.json")
             )
         )
 
     def test_cell_presentation_md_covers_contract(self) -> None:
-        path = os.path.join(get_skill_root(), "references", "CELL_PRESENTATION.md")
+        path = _skill_path("references", "CELL_PRESENTATION.md")
         with open(path, encoding="utf-8") as f:
             text = f.read()
         for marker in (
@@ -80,14 +88,77 @@ class TestCellPresentationContract(unittest.TestCase):
             "warning",
             "alert",
             "_jiangchang_cell_presentation",
+            "_jiangchang_grid_presentation",
             "cellPresentation",
             "派生",
             "任意 CSS",
             "用途不限",
             "schemaVersion",
+            "整行",
+            "整列",
+            "all",
+            "格子 > 区域 > 行 > 列",
+            "详情",
         ):
             self.assertIn(marker, text, msg=f"CELL_PRESENTATION.md missing {marker!r}")
 
+    def test_grid_schema_file_exists_and_parses(self) -> None:
+        schema = _load_grid_schema()
+        self.assertEqual(schema.get("title"), "SkillGridPresentationDocument")
+        self.assertIs(schema.get("additionalProperties"), False)
+        self.assertEqual(schema["properties"]["schemaVersion"].get("const"), 1)
+        tones = set(schema["$defs"]["tone"].get("enum") or [])
+        self.assertEqual(tones, {"danger", "warning", "info", "success", "muted"})
+        self.assertIn("not", schema["$defs"]["ruleItem"])
+
+    def test_grid_example_validates_against_schema(self) -> None:
+        try:
+            import jsonschema
+        except ImportError:
+            self.skipTest("jsonschema not installed")
+        jsonschema.validate(instance=_load_grid_example(), schema=_load_grid_schema())
+
+    def test_grid_schema_rejects_all_by_all(self) -> None:
+        try:
+            import jsonschema
+        except ImportError:
+            self.skipTest("jsonschema not installed")
+        payload = {
+            "schemaVersion": 1,
+            "skill": "your-skill-slug",
+            "table": "business_records",
+            "rowKey": "id",
+            "rules": [
+                {
+                    "ruleKey": "paint-everything",
+                    "rows": "all",
+                    "columns": "all",
+                    "tone": "danger",
+                }
+            ],
+        }
+        with self.assertRaises(jsonschema.ValidationError):
+            jsonschema.validate(instance=payload, schema=_load_grid_schema())
+
+    def test_internal_metadata_hides_presentation_tables(self) -> None:
+        from db.display_metadata import INTERNAL_METADATA_TABLES, METADATA_TABLES
+
+        self.assertIn("_jiangchang_cell_presentation", INTERNAL_METADATA_TABLES)
+        self.assertIn("_jiangchang_grid_presentation", INTERNAL_METADATA_TABLES)
+        self.assertTrue(INTERNAL_METADATA_TABLES <= METADATA_TABLES)
+
+    def test_template_actions_do_not_enable_presentation_by_default(self) -> None:
+        manifest = _load_json("assets", "actions.json")
+        self.assertNotEqual(manifest.get("cellPresentation", {}).get("enabled"), True)
+
+    def test_checklist_covers_grid_presentation(self) -> None:
+        path = _skill_path("development", "CHECKLIST.md")
+        with open(path, encoding="utf-8") as f:
+            text = f.read()
+        self.assertIn("A6-15", text)
+        self.assertIn("cellPresentation", text)
+        self.assertIn("CELL_PRESENTATION.md", text)
+
 
 if __name__ == "__main__":
     unittest.main()

tests/test_cli_smoke.py

@@ -14,7 +14,7 @@ from jiangchang_skill_core import config
 
 # scripts/ 已由 _support 注入 sys.path
 from cli.app import main
-from util.constants import SKILL_SLUG
+from util.constants import SKILL_SLUG, SKILL_VERSION
 
 
 class TestCliSmoke(unittest.TestCase):
@@ -57,6 +57,7 @@ class TestCliSmoke(unittest.TestCase):
         self.assertIn("version", payload)
         self.assertIn("skill", payload)
         self.assertEqual(payload["skill"], SKILL_SLUG)
+        self.assertEqual(payload["version"], SKILL_VERSION)
 
     def test_init_db_creates_database_and_is_idempotent(self) -> None:
         with IsolatedDataRoot(user_id="_cli_init_db"):

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

@@ -30,6 +30,7 @@ POLICY_IDS = (
     "POLICY-CONFIG-002",
     "POLICY-CONFIG-003",
     "POLICY-CONFIG-004",
+    "POLICY-CONFIG-005",
     "POLICY-TESTING-001",
     "POLICY-TESTING-002",
     "POLICY-RPA-001",
@@ -38,8 +39,10 @@ POLICY_IDS = (
     "POLICY-RPA-004",
     "POLICY-RPA-005",
     "POLICY-RPA-006",
+    "POLICY-RPA-007",
     "POLICY-PACKAGING-001",
     "POLICY-PACKAGING-002",
+    "POLICY-RELEASE-001",
     "POLICY-DOCS-001",
     "POLICY-LOGGING-001",
     "POLICY-LOGGING-002",
@@ -57,6 +60,7 @@ POLICY_IDS = (
     "POLICY-SKILL-ACTION-002",
     "POLICY-SKILL-ACTION-003",
     "POLICY-SKILL-ACTION-004",
+    "POLICY-TUTORIAL-001",
     "POLICY-ARCH-CORE-001",
     "POLICY-DATA-SYNC-001",
 )
@@ -94,8 +98,11 @@ CONFIG_ENV_FORBIDDEN_PATTERNS = (
 )
 
 CONFIG_004_SOURCE = "development/CONFIG.md §.env.example 注释 = 配置管理用户文案"
+CONFIG_005_SOURCE = "development/CONFIG.md §必填项：# @required"
 CONFIG_004_ENV_KEY_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
 CONFIG_004_CJK_RE = re.compile(r"[\u4e00-\u9fff]")
+CONFIG_005_REQUIRED_MARKER_RE = re.compile(r"^@required\b", re.IGNORECASE)
+CONFIG_005_INLINE_REQUIRED_RE = re.compile(r"@required\b", re.IGNORECASE)
 # 注释中禁止出现的开发向指向 / 黑话（大小写不敏感子串）
 CONFIG_004_FORBIDDEN_COMMENT_SUBSTRINGS = (
     "development/",
@@ -199,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"
@@ -314,6 +341,34 @@ def _config_004_comment_offenders(path: str) -> list[str]:
     return offenders
 
 
+def _is_env_required_marker(text: str) -> bool:
+    return bool(CONFIG_005_REQUIRED_MARKER_RE.match(text.strip()))
+
+
+def _config_005_offenders(path: str) -> list[str]:
+    offenders: list[str] = []
+    for lineno, key, _value, headers, inline in _iter_env_example_active_entries(path):
+        if inline and CONFIG_005_INLINE_REQUIRED_RE.search(inline):
+            offenders.append(
+                f".env.example:{lineno}: {key}= 禁止在行尾写 @required（须单独一行放在中文行头上方）"
+            )
+
+        required_markers = [part for part in headers if _is_env_required_marker(part)]
+        non_marker_headers = [part for part in headers if not _is_env_required_marker(part)]
+        if not required_markers:
+            continue
+        if not non_marker_headers:
+            offenders.append(
+                f".env.example:{lineno}: {key}= 使用了 # @required 但缺少中文行头"
+            )
+            continue
+        if not any(CONFIG_004_CJK_RE.search(part) for part in non_marker_headers):
+            offenders.append(
+                f".env.example:{lineno}: {key}= # @required 下方须有中文行头（说明「是什么」）"
+            )
+    return offenders
+
+
 def _rel(skill_root: str, path: str) -> str:
     return os.path.relpath(path, skill_root).replace("\\", "/")
 
@@ -404,6 +459,12 @@ def _scan_install_delivery_files(skill_root: str) -> list[str]:
                 continue
             if suffix == ".sh" and not path.endswith(".sh"):
                 continue
+            # Root sync.ps1 is the manual local-host mirror. It installs
+            # requirements into the shared venv the same way the host does.
+            if os.path.basename(path) == "sync.ps1" and os.path.normcase(
+                os.path.dirname(os.path.abspath(path))
+            ) == os.path.normcase(os.path.abspath(skill_root)):
+                continue
             text = _read_text(path)
             for pattern in INSTALL_FORBIDDEN_PATTERNS:
                 if pattern.search(text):
@@ -567,6 +628,23 @@ class TestPolicyConfig004(unittest.TestCase):
         )
 
 
+class TestPolicyConfig005(unittest.TestCase):
+    def test_env_example_required_markers_are_well_formed(self) -> None:
+        path = os.path.join(get_skill_root(), ".env.example")
+        self.assertTrue(os.path.isfile(path), msg=".env.example missing")
+        offenders = _config_005_offenders(path)
+        self.assertEqual(
+            offenders,
+            [],
+            msg=_policy_msg(
+                "POLICY-CONFIG-005",
+                CONFIG_005_SOURCE,
+                "\n".join(offenders)
+                or "every # @required marker needs its own Chinese header line above the key",
+            ),
+        )
+
+
 class TestPolicyTesting001(unittest.TestCase):
     def test_root_tests_do_not_hardcode_real_targets(self) -> None:
         skill_root = get_skill_root()
@@ -780,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()
@@ -1529,6 +1685,44 @@ class TestPolicyDataSync001(unittest.TestCase):
         )
 
 
+class TestPolicyRelease001(unittest.TestCase):
+    def test_release_ps1_enforces_version_alignment(self) -> None:
+        skill_root = get_skill_root()
+        path = os.path.join(skill_root, "release.ps1")
+        self.assertTrue(
+            os.path.isfile(path),
+            msg=_policy_msg("POLICY-RELEASE-001", "release.ps1", "file missing"),
+        )
+        text = _read_text(path)
+        self.assertIn(
+            "Assert-SkillReleaseVersionAlignment",
+            text,
+            msg=_policy_msg(
+                "POLICY-RELEASE-001",
+                "release.ps1",
+                "must define Assert-SkillReleaseVersionAlignment",
+            ),
+        )
+        self.assertIn(
+            "POLICY-RELEASE-001",
+            text,
+            msg=_policy_msg(
+                "POLICY-RELEASE-001",
+                "release.ps1",
+                "must reference POLICY-RELEASE-001",
+            ),
+        )
+        self.assertRegex(
+            text,
+            r"Assert-SkillReleaseVersionAlignment\s+-SkillRoot",
+            msg=_policy_msg(
+                "POLICY-RELEASE-001",
+                "release.ps1",
+                "must invoke Assert-SkillReleaseVersionAlignment before tagging",
+            ),
+        )
+
+
 class TestPolicyDocs001(unittest.TestCase):
     def test_policy_matrix_exists_and_lists_policy_ids(self) -> None:
         skill_root = get_skill_root()

tests/test_display_metadata.py

@@ -553,6 +553,41 @@ metadata:
         finally:
             conn.close()
 
+    def test_enum_column_without_searchable_warns(self) -> None:
+        conn = sqlite3.connect(":memory:")
+        try:
+            conn.executescript(
+                """
+                CREATE TABLE filter_demo (id INTEGER PRIMARY KEY, enabled INTEGER NOT NULL DEFAULT 1);
+                """
+            )
+            from db.display_metadata import (
+                init_display_metadata_tables,
+                upsert_column_metadata,
+                upsert_table_metadata,
+            )
+            from db.display_metadata_validator import validate_filter_search_metadata
+
+            cur = conn.cursor()
+            init_display_metadata_tables(cur)
+            upsert_table_metadata(cur, table_name="filter_demo", display_name="筛选演示", readonly=0)
+            upsert_column_metadata(
+                cur,
+                table_name="filter_demo",
+                column_name="enabled",
+                display_name="是否启用",
+                visible=1,
+                searchable=0,
+                editable=1,
+                display_type="boolean",
+                options_json='[{"value":0,"label":"停用"},{"value":1,"label":"启用"}]',
+            )
+            conn.commit()
+            _, warnings = validate_filter_search_metadata(cur, "filter_demo")
+            self.assertTrue(any("searchable=1" in item for item in warnings))
+        finally:
+            conn.close()
+
     def test_schema_md_documents_readonly_and_seed_helpers(self) -> None:
         path = os.path.join(get_skill_root(), "references", "SCHEMA.md")
         with open(path, encoding="utf-8") as f:
@@ -560,6 +595,53 @@ metadata:
         self.assertIn("readonly = 1", text)
         self.assertIn("seed_column_metadata_batch", text)
         self.assertIn("valid_column_names", text)
+        self.assertIn("可以**引用 `visible=0` 的列", text)
+        self.assertIn("default_sort_json` / ORDER BY", text)
+
+    def test_default_sort_json_allows_hidden_column_and_rejects_missing(self) -> None:
+        conn = sqlite3.connect(":memory:")
+        try:
+            from db.display_metadata import (
+                init_display_metadata_tables,
+                seed_column_metadata_batch,
+                upsert_table_metadata,
+            )
+            from db.display_metadata_validator import validate_default_sort_metadata
+
+            cur = conn.cursor()
+            init_display_metadata_tables(cur)
+            cur.execute(
+                "CREATE TABLE demo_sort (id INTEGER PRIMARY KEY, title TEXT NOT NULL)"
+            )
+            upsert_table_metadata(
+                cur,
+                table_name="demo_sort",
+                display_name="排序示例",
+                default_sort_json='[{"column":"title","direction":"asc"},{"column":"id","direction":"desc"}]',
+            )
+            seed_column_metadata_batch(
+                cur,
+                table_name="demo_sort",
+                columns=(
+                    {"column_name": "id", "display_name": "编号", "visible": 0, "editable": 0},
+                    {"column_name": "title", "display_name": "标题", "visible": 1, "editable": 1},
+                ),
+                valid_column_names=["id", "title"],
+            )
+            errors, warnings = validate_default_sort_metadata(cur, "demo_sort")
+            self.assertEqual(errors, [])
+            self.assertTrue(any("visible=0" in w and "id" in w for w in warnings))
+
+            upsert_table_metadata(
+                cur,
+                table_name="demo_sort",
+                display_name="排序示例",
+                default_sort_json='[{"column":"missing_col","direction":"asc"}]',
+            )
+            errors, _ = validate_default_sort_metadata(cur, "demo_sort")
+            self.assertTrue(any("missing_col" in e for e in errors))
+        finally:
+            conn.close()
 
     def test_default_visible_columns_json_upsert_and_migrate(self) -> None:
         conn = sqlite3.connect(":memory:")
@@ -703,6 +785,73 @@ metadata:
         finally:
             conn.close()
 
+    def test_drop_deprecated_user_table_removes_physical_and_metadata(self) -> None:
+        conn = sqlite3.connect(":memory:")
+        try:
+            cur = conn.cursor()
+            cur.execute(
+                """
+                CREATE TABLE _jiangchang_tables (
+                    table_name TEXT PRIMARY KEY,
+                    display_name TEXT,
+                    description TEXT,
+                    sort_order INTEGER,
+                    visible INTEGER,
+                    readonly INTEGER
+                )
+                """
+            )
+            cur.execute(
+                """
+                CREATE TABLE _jiangchang_columns (
+                    table_name TEXT,
+                    column_name TEXT,
+                    display_name TEXT,
+                    description TEXT,
+                    display_order INTEGER,
+                    visible INTEGER,
+                    searchable INTEGER,
+                    editable INTEGER,
+                    display_type TEXT,
+                    options_json TEXT,
+                    PRIMARY KEY (table_name, column_name)
+                )
+                """
+            )
+            cur.execute(
+                """
+                CREATE TABLE task_logs (
+                    id INTEGER PRIMARY KEY,
+                    status TEXT,
+                    created_at INTEGER,
+                    updated_at INTEGER
+                )
+                """
+            )
+            cur.execute(
+                "INSERT INTO _jiangchang_tables VALUES ('task_logs', '任务日志', NULL, 1, 1, 0)"
+            )
+            cur.execute(
+                "INSERT INTO _jiangchang_columns VALUES "
+                "('task_logs', 'id', '编号', NULL, 1, 1, 1, 0, 'text', NULL)"
+            )
+            cur.execute("INSERT INTO task_logs (status) VALUES ('success')")
+
+            from db.display_metadata import drop_deprecated_user_table, iter_user_tables
+
+            drop_deprecated_user_table(cur, "task_logs")
+            cur.execute(
+                "SELECT 1 FROM sqlite_master WHERE type='table' AND name='task_logs'"
+            )
+            self.assertIsNone(cur.fetchone())
+            cur.execute(
+                "SELECT COUNT(*) FROM _jiangchang_tables WHERE table_name='task_logs'"
+            )
+            self.assertEqual(int(cur.fetchone()[0]), 0)
+            self.assertNotIn("task_logs", list(iter_user_tables(cur)))
+        finally:
+            conn.close()
+
 
 if __name__ == "__main__":
     unittest.main()

tests/test_docs_standards.py

@@ -181,6 +181,18 @@ class TestDocsStandards(unittest.TestCase):
         self.assertIn("CHANGELOG.md", text)
         self.assertIn("demo_video_url", text)
         self.assertIn("tutorial_md", text)
+        self.assertIn("TUTORIAL_SURFACES.md", text)
+
+    def test_tutorial_surfaces_contract_doc_and_checklist(self) -> None:
+        surfaces = self._read("development/TUTORIAL_SURFACES.md")
+        self.assertIn("说明", surfaces)
+        self.assertIn("教程", surfaces)
+        self.assertIn("skill-detail", surfaces)
+        checklist = self._read("development/CHECKLIST.md")
+        self.assertIn("A2-7", checklist)
+        self.assertIn("A2-8", checklist)
+        self.assertIn("A2-12", checklist)
+        self.assertIn("TUTORIAL_SURFACES.md", checklist)
 
     def test_naming_md_exists_and_covers_standards(self) -> None:
         text = self._read("development/NAMING.md")
@@ -315,6 +327,11 @@ class TestDocsStandards(unittest.TestCase):
                 os.path.join(root, "assets", "schemas", "skill-cell-presentation.schema.json")
             )
         )
+        self.assertTrue(
+            os.path.isfile(
+                os.path.join(root, "assets", "schemas", "skill-grid-presentation.schema.json")
+            )
+        )
         self.assertTrue(os.path.isfile(os.path.join(root, "tests", "test_actions_manifest.py")))
         self.assertTrue(os.path.isfile(os.path.join(root, "tests", "test_data_management_contract.py")))
 
@@ -341,6 +358,7 @@ class TestDocsStandards(unittest.TestCase):
             "新增/编辑表单：字段说明与默认值（宿主支持）",
             "表单与展示：稳定字段类型（宿主支持，须与 Action 对称）",
             "datetime_unix_seconds",
+            "year_month",
             "display_type: \"number\"",
             "extra_column",
             "{value} · {label}",
@@ -356,27 +374,91 @@ class TestDocsStandards(unittest.TestCase):
             "跨表引用 lookup",
             "\"multiple\": true",
             "Lookup 多选",
+            "数据管理：列筛选与全局搜索",
+            "列筛选与全局搜索",
+            "searchable: 1",
+            "筛选栏控件",
+            "表增删改与退役",
+            "drop_deprecated_user_table",
+            "孤儿物理表",
+            "_jiangchang_grid_presentation",
         ):
             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",
+            "year_month",
             "SCHEMA.md",
             "字段条件显隐",
             "visibleWhen",
             "grid_help",
+            "列筛选",
         ):
             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",
+        )
+        checklist = self._read("development/CHECKLIST.md")
+        self.assertIn("skill_cli", checklist)
+        self.assertIn("A4-12", 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)
+        schema_json = self._read("assets/schemas/skill-actions.schema.json")
+        self.assertIn("skill_cli", schema_json)
+        self.assertIn("paged_table", 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")
@@ -395,11 +477,32 @@ 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)
         checklist = self._read("development/CHECKLIST.md")
         self.assertIn("A4-7", checklist)
         self.assertIn("visibleWhen", checklist)
+        self.assertIn("A4-8", checklist)
+        self.assertIn("revealInForm", checklist)
+        self.assertIn("A4-9", checklist)
+        self.assertIn("selectionMode", 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)
+        actions = self._read("references/ACTIONS.md")
+        self.assertIn("用户可见文案", actions)
+        self.assertIn("双受众", actions)
+        self.assertIn("行菜单显隐", actions)
+        self.assertIn("bind.visibleWhen", actions)
 
     def test_guarded_docs_do_not_reference_amazon_implementation(self) -> None:
         forbidden = (

tests/test_html_page_service.py

@@ -61,6 +61,29 @@ class TestHtmlPageService(unittest.TestCase):
             with self.assertRaises(ValueError):
                 write_html_page("note.txt", "<html></html>")
 
+    def test_example_report_shell_embedded_preview_layout(self) -> None:
+        """守护 example-report.html：数据管理 iframe 预览布局基线不退化。"""
+        template = load_html_template("assets/html/example-report.html")
+        self.assertIn("overflow-x: hidden", template)
+        self.assertIn("min-width: 0", template)
+        self.assertIn("table-layout: fixed", template)
+        self.assertIn("overflow-wrap: anywhere", template)
+        self.assertNotIn("max-width:", template)
+
+    def test_actions_contract_keeps_shell_pages_and_call(self) -> None:
+        from util.runtime_paths import get_skill_root
+
+        root = get_skill_root()
+        actions_path = os.path.join(root, "references", "ACTIONS.md")
+        with open(actions_path, encoding="utf-8") as f:
+            actions = f.read()
+        self.assertIn("assets/html/pages", actions)
+        self.assertIn("jiangchang.call", actions)
+        self.assertTrue(os.path.isfile(os.path.join(root, "assets", "html", "example-report.html")))
+        self.assertFalse(
+            os.path.isfile(os.path.join(root, "assets", "html", "pages", "example-report.html"))
+        )
+
 
 if __name__ == "__main__":
     unittest.main()

tests/test_skill_metadata.py

@@ -50,6 +50,26 @@ class TestSkillMetadata(unittest.TestCase):
             self.assertEqual(SKILL_SLUG, skill_dir)
             self.assertEqual(slug_md, skill_dir)
 
+    def test_skill_version_alignment(self) -> None:
+        """SKILL.md version 必须与 constants.SKILL_VERSION 一致（POLICY-RELEASE-001 日常侧）。"""
+        root = get_skill_root()
+        md_path = os.path.join(root, "SKILL.md")
+        with open(md_path, encoding="utf-8") as f:
+            md = f.read()
+        match = re.search(r"(?m)^version:\s*[\"']?([0-9]+\.[0-9]+\.[0-9]+)[\"']?\s*$", md)
+        self.assertIsNotNone(match, "SKILL.md must declare top-level semver version")
+        assert match is not None
+        md_version = match.group(1)
+
+        from util.constants import SKILL_VERSION
+
+        self.assertEqual(
+            md_version,
+            SKILL_VERSION,
+            "SKILL.md version 必须与 constants.SKILL_VERSION 一致（发布前再与 git tag 对齐）",
+        )
+        self.assertRegex(SKILL_VERSION, r"^\d+\.\d+\.\d+$")
+
 
 if __name__ == "__main__":
     unittest.main()

tests/test_slug_naming.py

@@ -44,6 +44,8 @@ class TestSlugNaming(unittest.TestCase):
         for slug in (
             "download-settlement-report-amazon",
             "add-product-shopee",
+            "generate-monthly-statements",
+            "reconcile-finance",
             "generate-article-all",
             "your-skill-slug",
             "account-manager",
@@ -56,8 +58,7 @@ class TestSlugNaming(unittest.TestCase):
         cases = (
             "amazon-download-settlement-report",
             "enter-cross-border-sales-receipt-voucher-kingdee",
-            "reconcile-finance",
-            "download-settlement-report-unknownplat",
+            "generate",
             "foobar-settlement-report-amazon",
         )
         for slug in cases:
@@ -78,6 +79,19 @@ class TestSlugNaming(unittest.TestCase):
         self.assertTrue(errors)
         self.assertTrue(any("48" in err for err in errors))
 
+    def test_plain_slug_without_platform(self) -> None:
+        slug = "generate-monthly-statements"
+        self.assertEqual(classify_slug_form(parse_slug_segments(slug), slug=slug), "plain")
+        errors, warnings = validate_slug_semantics(slug)
+        self.assertEqual(errors, [], msg=f"errors={errors!r} warnings={warnings!r}")
+        self.assertEqual(warnings, [])
+
+    def test_default_suffix_warns_but_does_not_fail(self) -> None:
+        slug = "generate-article-default"
+        errors, warnings = validate_slug_semantics(slug)
+        self.assertEqual(errors, [], msg=f"errors={errors!r}")
+        self.assertTrue(any("default" in item for item in warnings), msg=f"warnings={warnings!r}")
+
     def test_legacy_exempt_set(self) -> None:
         self.assertIn("your-skill-slug", LEGACY_EXEMPT_SLUGS)
         self.assertIn("account-manager", LEGACY_EXEMPT_SLUGS)

tests/test_tutorial_surfaces.py

@@ -0,0 +1,221 @@
+# -*- coding: utf-8 -*-
+"""用户市场文档契约：README≠教程、TUTORIAL 三入口结构、与 actions.json 对齐。
+
+契约全文：development/TUTORIAL_SURFACES.md
+- 模板占位 slug（your-skill-slug）：只检查骨架与契约文档存在
+- 业务技能：按 actions.json placements 硬校验教程章节与 README 反模式
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import unittest
+
+from _support import get_skill_root
+from util.constants import SKILL_SLUG
+
+TEMPLATE_PLACEHOLDER_SLUG = "your-skill-slug"
+
+_SECTION_DATA_MGMT = re.compile(r"(?m)^##\s*.*数据管理")
+_SECTION_DIALOG = re.compile(r"(?m)^##\s*.*(对话任务|对话)")
+_SECTION_CRON = re.compile(r"(?m)^##\s*.*定时任务")
+_SECTION_COMPARE = re.compile(r"(?m)^##\s*.*(对照表|主能力)")
+_SECTION_STUCK = re.compile(r"(?m)^##\s*.*(常见卡住|卡住怎么办)")
+_SECTION_WHAT = re.compile(r"(?m)^##\s*.*(本技能做什么|做什么)")
+_NO_CRON_HINT = re.compile(r"不需要定时|未提供定时|不提供定时|不适用.*定时|定时.*不适用")
+
+# README 反模式：分步操作 / Agent 话术专章（说明 Tab 禁止）
+_README_HOWTO_AGENT = re.compile(r"(?m)^##\s*.*告诉\s*Agent")
+_README_ENTRY_CHAPTER = re.compile(r"(?m)^##\s*入口[一二三]")
+_README_NUMBERED_DM_PATH = re.compile(
+    r"(?m)^\d+[\.、]\s*.*(数据管理|选品任务|表顶).{0,40}(点击|点\s*「)"
+)
+
+
+def _read(rel: str) -> str:
+    path = os.path.join(get_skill_root(), rel)
+    with open(path, encoding="utf-8") as f:
+        return f.read()
+
+
+def _load_actions() -> list[dict]:
+    path = os.path.join(get_skill_root(), "assets", "actions.json")
+    if not os.path.isfile(path):
+        return []
+    with open(path, encoding="utf-8") as f:
+        data = json.load(f)
+    return list(data.get("actions") or [])
+
+
+def _placement_sets(actions: list[dict]) -> tuple[bool, bool, bool]:
+    has_dm = False
+    has_agent = False
+    has_cron = False
+    dm_tokens = frozenset({"toolbar", "row", "batch"})
+    for action in actions:
+        placements = set(action.get("placements") or [])
+        if placements & dm_tokens:
+            has_dm = True
+        if "agent" in placements and str(action.get("id") or "") not in (
+            "health",
+            "version",
+            "config-path",
+        ):
+            has_agent = True
+        if "cron" in placements:
+            has_cron = True
+    return has_dm, has_agent, has_cron
+
+
+class TestTutorialSurfacesContract(unittest.TestCase):
+    def test_tutorial_surfaces_doc_exists(self) -> None:
+        path = os.path.join(get_skill_root(), "development", "TUTORIAL_SURFACES.md")
+        self.assertTrue(
+            os.path.isfile(path),
+            msg="development/TUTORIAL_SURFACES.md must exist (user market doc contract)",
+        )
+        text = _read("development/TUTORIAL_SURFACES.md")
+        for marker in (
+            "README.md",
+            "TUTORIAL.md",
+            "数据管理",
+            "对话",
+            "定时",
+            "skill-detail",
+            "对照表",
+            "正文不要用",
+            "禁止",
+        ):
+            self.assertIn(marker, text, msg=f"TUTORIAL_SURFACES.md missing {marker!r}")
+
+    def test_market_docs_forbid_redundant_page_h1(self) -> None:
+        """宿主已有技能名与 Tab 标题：说明/教程正文禁止再用 # 一级标题。"""
+
+        def strip_fences(src: str) -> str:
+            return re.sub(r"```.*?```", "", src, flags=re.S)
+
+        for rel in ("README.md", "TUTORIAL.md"):
+            body = strip_fences(_read(rel))
+            # YAML frontmatter 里不应出现 ATX H1；正文亦禁止 #
+            self.assertIsNone(
+                re.search(r"(?m)^#\s+\S", body),
+                msg=(
+                    f"{rel} must not use ATX H1 (# …); host already shows skill name / tab. "
+                    "Use ## for sections (see TUTORIAL_SURFACES.md §0.1)."
+                ),
+            )
+            self.assertIsNone(
+                re.search(r"(?m)^#\s+.·\s*使用教程\s*$", body),
+                msg=f"{rel} must not start sections with '# … · 使用教程'",
+            )
+
+    def test_development_md_points_to_tutorial_surfaces(self) -> None:
+        text = _read("development/DEVELOPMENT.md")
+        self.assertIn(
+            "TUTORIAL_SURFACES.md",
+            text,
+            msg="DEVELOPMENT.md must reference TUTORIAL_SURFACES.md for market docs",
+        )
+
+    def test_template_or_business_tutorial_has_required_skeleton(self) -> None:
+        tutorial = _read("TUTORIAL.md")
+        self.assertRegex(
+            tutorial,
+            _SECTION_WHAT,
+            msg="TUTORIAL.md must have a '本技能做什么' (or equivalent) section",
+        )
+        self.assertRegex(
+            tutorial,
+            _SECTION_DATA_MGMT,
+            msg="TUTORIAL.md must have a 数据管理 section (or 不适用 placeholder)",
+        )
+        self.assertRegex(
+            tutorial,
+            _SECTION_DIALOG,
+            msg="TUTORIAL.md must have a 对话 section (or 不适用 placeholder)",
+        )
+        self.assertRegex(
+            tutorial,
+            _SECTION_CRON,
+            msg="TUTORIAL.md must have a 定时任务 section (teach or N/A)",
+        )
+        self.assertRegex(
+            tutorial,
+            _SECTION_COMPARE,
+            msg="TUTORIAL.md must have a 主能力对照表 section",
+        )
+        self.assertRegex(
+            tutorial,
+            _SECTION_STUCK,
+            msg="TUTORIAL.md must have a 常见卡住 section",
+        )
+        # 禁止旧「对话单线」作为唯一主结构标题
+        self.assertNotRegex(
+            tutorial,
+            r"(?m)^##\s*第一步：打开技能并说清目标\s*$",
+            msg="TUTORIAL.md must not use legacy dialogue-only first step as sole structure",
+        )
+
+    def test_readme_has_no_legacy_agent_howto_chapter(self) -> None:
+        readme = _read("README.md")
+        self.assertIsNone(
+            _README_HOWTO_AGENT.search(readme),
+            msg="README.md must not have '告诉 Agent' howto chapter (belongs in TUTORIAL)",
+        )
+        self.assertIsNone(
+            _README_ENTRY_CHAPTER.search(readme),
+            msg="README.md must not have 入口一/二/三 chapters (belongs in TUTORIAL)",
+        )
+
+    def test_business_skill_tutorial_aligns_with_actions(self) -> None:
+        if SKILL_SLUG == TEMPLATE_PLACEHOLDER_SLUG:
+            self.skipTest("template placeholder slug: skip actions alignment hard checks")
+
+        actions = _load_actions()
+        has_dm, has_agent, has_cron = _placement_sets(actions)
+        tutorial = _read("TUTORIAL.md")
+        readme = _read("README.md")
+
+        if has_dm:
+            self.assertRegex(
+                tutorial,
+                _SECTION_DATA_MGMT,
+                msg="business skill with data-management placements must document 数据管理 in TUTORIAL",
+            )
+            # 准备类若挂了 toolbar，教程不应把 skill-detail 当唯一主路径
+            self.assertNotRegex(
+                tutorial,
+                r"(?m)^\d+[\.、]\s*.*技能详情.{0,30}点击",
+                msg="TUTORIAL must not use 技能详情点击 as primary numbered path when DM exists",
+            )
+
+        if has_agent:
+            self.assertRegex(
+                tutorial,
+                _SECTION_DIALOG,
+                msg="business skill with agent placements must document 对话 in TUTORIAL",
+            )
+
+        if has_cron:
+            self.assertRegex(
+                tutorial,
+                _SECTION_CRON,
+                msg="with cron placements, TUTORIAL must have 定时任务 section",
+            )
+        else:
+            self.assertRegex(
+                tutorial,
+                _NO_CRON_HINT,
+                msg="without cron placements, TUTORIAL must declare 不需要/未提供定时",
+            )
+
+        # README 不应出现「数据管理 → … → 点击」式编号步骤
+        self.assertIsNone(
+            _README_NUMBERED_DM_PATH.search(readme),
+            msg="README.md must not contain numbered data-management click steps",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tools/README.md

@@ -51,6 +51,7 @@ python tools/scaffold_skill.py --slug my-new-skill --destination /path/to/my-new
 - **不**自动生成业务表名，**不**给 `health` / `version` / `config-path` 自动加 `toolbar`
 - **不**生成任何具体平台业务 Action
 - **不**自动 `git init`；打印后续 Git 与测试命令
+- 根目录同时复制 `release.ps1`（发布到服务器）和 `sync.ps1`（同步明文到本机宿主）
 
 目标目录若已存在且非空，需加 `-Force` / `--force`（且目标**不得**含 `.git`）。
 
@@ -58,6 +59,8 @@ python tools/scaffold_skill.py --slug my-new-skill --destination /path/to/my-new
 
 | 文件 | 说明 |
 |------|------|
+| `release.ps1` | 发布到服务器；保留 |
+| `sync.ps1` | 把明文同步到本机宿主；保留。用法见 `development/DEVELOPMENT.md` §14.6 |
 | `assets/actions.json` | 默认复制；不需要宿主 Action 入口时可删除 |
 | `references/ACTIONS.md` | 契约文档；无 `actions.json` 时可保留作参考或按需精简 |
 | `assets/schemas/skill-actions.schema.json` | manifest 规范；无 action 时可保留 |