Precipitate host contracts from task-plaza: visibleWhen equalsFrom, replaces gates, url openExternal, feishu data-sources (v1.0.128)

2026-11-01 16:30:46 +08:00
parent d911bd28cd
commit 90eefc8653
15 changed files with 412 additions and 32 deletions
--- a/references/ACTIONS.md
+++ b/references/ACTIONS.md
@@ -170,14 +170,25 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 "visibleWhen": { "field": "status", "in": ["pending_review", "skipped"] }
 ```

-也支持 `{ "field": "status", "equals": "approved" }`。规则缺失或无法解析时宿主视为始终可见（兼容旧技能）。
+也支持：
+
+| 形状 | 含义 |
+|------|------|
+| `{ "field": "status", "equals": "approved" }` | 等于常量 |
+| `{ "field": "status", "in": ["a", "b"] }` | 属于集合 |
+| `{ "field": "owner_user_id", "equalsFrom": "currentUser.userId" }` | 等于宿主当前用户（`userId` / `username`） |
+| `{ "field": "owner_user_id", "notEqualsFrom": "currentUser.userId" }` | 不等于当前用户 |
+| `{ "all": [ … ] }` / `{ "any": [ … ] }` | 组合 AND / OR |
+
+规则缺失或无法解析时宿主视为始终可见（兼容旧技能）。

 **要点：**

 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)。
+4. **宿主内置「编辑 / 删除」也会读同一套规则**：若本表声明了 `replaces: update` / `replaces: delete`，宿主行菜单的编辑/删除按钮按**该 replaces Action** 的 `bind.visibleWhen` 显隐（与技能 `row` 按钮同一求值器）。无 `visibleWhen` / 无 replaces → 行为与旧宿主一致（只看表级可否编辑/删除）。示例：[`assets/examples/replaces-delete-owner-visible.action.example.json`](../assets/examples/replaces-delete-owner-visible.action.example.json)。
+5. 示例（技能行按钮）：[`assets/examples/bind-visible-when-row.action.example.json`](../assets/examples/bind-visible-when-row.action.example.json)。

 ### 数据管理：勾选驱动模式 `bind.selectionMode`

@@ -453,6 +464,7 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 - `update` / `delete` 可用 `inputMapping`（`$row.$pk`、`$selection.ids`）预填主键。
 - `import` 约定：`filePath`（或 `file`）+ 可选 `onError`（`skip`/`abort` 或上例中文枚举）；技能自行解析文件与表头（须兼容宿主前缀 `*` 与 lookup `编号 · 名称`，见上文「导入表头与 lookup 单元格」）。
 - 整表 `_jiangchang_tables.readonly=1` 时仍隐藏宿主默认新增/编辑/导入与直写删除；**若声明了 `replaces: delete`，宿主仍显示「删除」并走技能 CLI**（不直写 SQLite）。
+- **按行显隐宿主编辑/删除**：`replaces: update` / `replaces: delete` 的 `bind.visibleWhen` 同时约束宿主行菜单「编辑」「删除」（见上文「行菜单显隐」第 4 点）。典型：仅本人可删 → `equalsFrom: currentUser.userId`；队列状态机表还常配合 Policy **`hostCapabilities` 不含 `edit`**，禁止裸改状态/结果链接（见 [`POLICY.md`](POLICY.md)「状态机表配方」）。
 - **列元数据复用**：Action 表单（含 toolbar/batch 弹窗与 create/update 抽屉）可将 `inputSchema` 字段对齐业务列，复用中文名与列上 **options**（静态枚举 `options_json` **数组**，或已解析的 lookup）：
  - 优先让属性名 = 物理列名（如 `carrier_code` / `platform_key`）；
  - 或 `bind.columnMapping`：`{ "carrierCode": "carrier_code" }`；
--- a/references/DATA_SOURCES.md
+++ b/references/DATA_SOURCES.md
@@ -1,12 +1,20 @@
-# 多数据源声明（SQLite / MySQL 云库）
+# 多数据源声明（SQLite / MySQL / 飞书多维表）

-本文说明技能如何向匠厂宿主**声明**业务数据库，以及技能 CLI / Action 如何与宿主读写**同一物理库**。
+本文说明技能如何向匠厂宿主**声明**业务数据库，以及技能 CLI / Action 如何与宿主读写**同一物理库**（或同一飞书表）。

-**产品定位：** 默认仍是本地 SQLite（`{skill_slug}.db`）。需要多用户共享、集中运维或云库时，可显式声明 **MySQL**。UI / API 契约不变；`_jiangchang_*` 展示元数据仍写在同一逻辑库中。
+**产品定位：** 默认仍是本地 SQLite（`{skill_slug}.db`）。需要多用户共享、集中运维或云库时，可显式声明 **MySQL**。需要以飞书多维表格为权威数据时，声明 **`feishu_bitable`**。UI / API 契约尽量一致；SQLite/MySQL 的 `_jiangchang_*` 展示元数据写在同一逻辑库中，飞书源用本文件的 **`columns` 覆盖**声明展示。

-**宿主版本：** 匠厂 Host **≥ 6.9.28** 才支持 `data-sources.json` 与 MySQL 连接器。
+**宿主版本：**

-**完整参考实现：** [`process-work-order`](https://git.jc2009.com/client-commons/process-work-order) @ v1.0.2（工单管理 + MySQL 云库试点）。
+| 能力 | 最低 Host |
+|------|-----------|
+| `data-sources.json` + MySQL | **≥ 6.9.28** |
+| `kind: feishu_bitable` + `columns` 展示覆盖 | 以当前匠厂 Host 为准（task-plaza 等已落地；发布说明见 Host changelog） |
+
+**完整参考实现：**
+
+- MySQL：[`process-work-order`](https://git.jc2009.com/client-commons/process-work-order) @ v1.0.2  
+- 飞书：业务技能 `task-plaza`（外包任务板）

 ---

@@ -16,8 +24,9 @@
 |------|------|
 | 单机、离线、小数据量、便携部署 | **SQLite**（默认，不配声明文件亦可） |
 | 多用户共享、运维集中管库、与外部系统共库 | **MySQL 云库**（显式 opt-in） |
+| 权威数据已在飞书多维表、多人在线协作 | **`feishu_bitable`**（显式 opt-in） |

-**硬规则：一个 `sourceId` 对应一个物理库。** 禁止双写、禁止 SQLite 与 MySQL 同步镜像。
+**硬规则：一个 `sourceId` 对应一个物理库 / 一张飞书业务表声明。** 禁止双写、禁止 SQLite 与 MySQL / 飞书同步镜像。

 ---

@@ -28,13 +37,13 @@
 ```
 {JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/{skill_slug}/
 ├── data-sources.json      # 声明式数据源（可选；见下）
-├── .env                   # MYSQL_DSN 等连接配置
+├── .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。
+模板默认示例为 **SQLite 显式声明**（与自动扫描 `{skill_slug}.db` 等价）。改走 MySQL / 飞书时，请参照 `assets/examples/` 下对应示例手工替换用户目录中的 `data-sources.json`，并在 `.env` 配置密钥。

 若不需要声明式接入，可删除用户目录中的 `data-sources.json`，宿主恢复自动扫描 `.db` 文件。

@@ -54,10 +63,13 @@
 | 字段 | 必填 | 说明 |
 |------|------|------|
 | `id` | 是 | 英文标识，如 `primary` |
-| `kind` | 是 | `sqlite` 或 `mysql` |
+| `kind` | 是 | `sqlite` \| `mysql` \| `feishu_bitable` |
 | `displayName` | 否 | 侧栏展示名；多库时建议填写 |
 | `path` | sqlite 必填 | 相对技能数据目录的路径；可用 `{skillSlug}` 占位 |
 | `connectionEnv` | mysql 必填 | `.env` 中 DSN 的环境变量名，如 `MYSQL_DSN` |
+| `appIdEnv` / `appSecretEnv` / `appTokenEnv` | feishu 必填 | `.env` 中飞书应用与多维表 app_token 的变量名 |
+| `tableIdEnv` | feishu 常用 | `.env` 中业务表 table_id 的变量名（或宿主约定的等价字段） |
+| `columns` | 否 | **列展示覆盖**（源无关；见下节） |

 ### SQLite 示例（模板默认）

@@ -67,20 +79,79 @@

 见 [`../assets/examples/data-sources.mysql.example.json`](../assets/examples/data-sources.mysql.example.json)。

+### 飞书多维表示例
+
+见 [`../assets/examples/data-sources.feishu_bitable.example.json`](../assets/examples/data-sources.feishu_bitable.example.json)。
+
 ---

-## `.env` 与 DSN
+## `columns` 展示覆盖（源无关）

-MySQL 连接串写在用户 `.env`（或进程环境变量），**不要**写进 `data-sources.json`：
+连接器先按后端生成列 schema（SQLite `_jiangchang_columns` / MySQL 元数据 / 飞书字段映射），再叠加 `sources[].columns`：
+
+```json
+"columns": {
+  "状态": { "editable": false, "searchable": true },
+  "结果链接": { "displayType": "url", "editable": false, "searchable": false },
+  "发单人": {
+    "displayType": "userId",
+    "editable": false,
+    "formVisible": false,
+    "defaultValueFrom": "currentUser.userId",
+    "searchable": true
+  },
+  "平台": {
+    "searchable": true,
+    "optionsWhen": {
+      "dependsOn": "任务类型",
+      "map": { "文章发布": ["头条号", "搜狐号"], "视频发布": ["抖音", "视频号"] }
+    }
+  }
+}
+```
+
+| 字段 | 类型 | 作用 |
+|------|------|------|
+| `displayType` | string | 覆盖展示类型（如 `url`、`textarea`、`userId`、`currency`） |
+| `displayName` | string | 覆盖列显示名 |
+| `defaultValue` | string/number/boolean/null | 新增表单默认值 |
+| `defaultValueFrom` | string | 从宿主会话预填：`currentUser.userId` / `currentUser.username` / `currentUser.usernameOrUserId` |
+| `optionsWhen` | object | 依赖另一字段当前值过滤下拉：`dependsOn` + `map` |
+| `createable` | boolean | `false` = 不进新增表单 / 不进 create payload |
+| `editable` | boolean | `false` = 不进编辑表单 / 不进 update payload（状态机字段常用） |
+| `formVisible` | boolean | `false` = 表单不展示但仍可按 createable/editable 写入（如静默 `defaultValueFrom`） |
+| `requiredOnCreate` | boolean | 新增必填 |
+| `searchable` | boolean | 是否进**列筛选**与**顶栏全局搜索**（覆盖连接器默认） |
+
+**与 `_jiangchang_columns` 的关系：**
+
+| 后端 | 主声明位置 |
+|------|------------|
+| SQLite / MySQL | `_jiangchang_columns`（`searchable` / `editable` / `display_type` 等）；`data-sources.columns` 可再覆盖 |
+| 飞书 | **无** `_jiangchang_*` 表；**以 `data-sources.json` 的 `columns` 为准**覆盖飞书字段映射默认值 |
+
+飞书连接器默认：明文与单选等常见字段可筛；技能用 `searchable: true/false` 收紧或放开筛选列（避免「全表可筛」噪音）。详见 [`SCHEMA.md`](SCHEMA.md)「列筛选与全局搜索」与「`display_type: url` 外开」。
+
+---
+
+## `.env` 与连接串
+
+密钥写在用户 `.env`（或进程环境变量），**不要**写进 `data-sources.json`：

 ```env
 # MySQL 云库连接（不配则走本地 SQLite）
 MYSQL_DSN=mysql://user:password@192.168.0.20:3306/your_database
+
+# 飞书多维表（变量名须与 data-sources.json 中 *Env 一致）
+FEISHU_APP_ID=cli_xxx
+FEISHU_APP_SECRET=xxx
+FEISHU_BITABLE_APP_TOKEN=bascnxxx
+FEISHU_TASK_TABLE_ID=tblxxx
 ```

-格式：`mysql://` 或 `mysql2://`，须含库名。注释写法须符合 [`../development/CONFIG.md`](../development/CONFIG.md)（配置管理会展示给用户）。
+MySQL 格式：`mysql://` 或 `mysql2://`，须含库名。注释写法须符合 [`../development/CONFIG.md`](../development/CONFIG.md)。

-技能 Python 侧：`scripts/db/backend.py` 读取同一 `MYSQL_DSN`；有值则 `resolve_backend()` 为 `mysql`，否则 `sqlite`。
+技能 Python 侧（SQLite/MySQL）：`scripts/db/backend.py` 读取同一 `MYSQL_DSN`；有值则 `resolve_backend()` 为 `mysql`，否则 `sqlite`。飞书读写由技能自备 SDK / HTTP，与宿主连接器并行遵守同一张表、同一凭证 env。

 ---

@@ -88,13 +159,13 @@ MYSQL_DSN=mysql://user:password@192.168.0.20:3306/your_database

 ### 宿主 UI（数据管理）

-宿主读取用户目录 `data-sources.json` + `.env`，经 Host 内置连接器访问库。**不依赖**技能 `connection.py`。
+宿主读取用户目录 `data-sources.json` + `.env`，经 Host 内置连接器访问库 / 飞书表。**不依赖**技能 `connection.py`。

 ### CLI / Action / `init-db`

 **必须**与宿主使用同一后端策略，否则会出现「UI 看云库、CLI 写本地 `.db`」的分裂。

-模板已提供：
+模板已提供（SQLite / MySQL）：

 | 模块 | 作用 |
 |------|------|
@@ -102,23 +173,31 @@ MYSQL_DSN=mysql://user:password@192.168.0.20:3306/your_database
 | `scripts/db/cursor_compat.py` | 统一 `?` 占位符与 `executescript` |
 | `scripts/db/connection.py` | `get_conn()` 双分支；`init_db()` 幂等建 `_jiangchang_*` |

-业务表 DDL / 迁移仍在技能自己的 `schema` / `init_db()` 中按 `conn.backend` 分支处理（见工单参考实现）。
+业务表 DDL / 迁移仍在技能自己的 `schema` / `init_db()` 中按 `conn.backend` 分支处理（见工单参考实现）。飞书技能无本地业务 DDL，但仍须提供 `health` / Action 与宿主同一表。

-可选：`describe_active_store()` 用于 health / 排障，输出当前连的是 sqlite 还是 mysql。
+可选：`describe_active_store()` 用于 health / 排障。

 ---

-## MySQL 当前限制（Host）
+## MySQL / 飞书 当前限制（Host）
+
+**MySQL：**

 - 不支持 `tableAdmin`（建表/改表 UI）
 - 不支持 `cellPresentation`
 - 元数据与 CRUD 与 SQLite 路径一致

-表结构变更仍由技能 `init-db` / 迁移脚本负责。
+**飞书：**
+
+- 不支持本地式 `tableAdmin` / 随意改物理 DDL（字段以飞书后台为准）
+- 筛选/排序能力受飞书 API 约束；用 `columns.searchable` 控制筛选项
+- 附件 / 人员等字段依赖宿主映射的 `displayType`（如 `attachment`、`userId`）
+
+表结构变更：SQLite/MySQL 由技能 `init-db` / 迁移负责；飞书在飞书后台改字段后，同步更新 `columns` 覆盖与技能读写字段名。

 ---

-## 开发 Checklist（云库）
+## 开发 Checklist（云库 / 飞书）

 复制新业务技能并选择 MySQL 时：

@@ -130,10 +209,18 @@ MYSQL_DSN=mysql://user:password@192.168.0.20:3306/your_database
 6. **抽测**：数据管理 UI 与 CLI（如 list / create）读写同一库
 7. 见 [`../development/CHECKLIST.md`](../development/CHECKLIST.md) A6-16

+选择飞书时：
+
+1. Host 已支持 `feishu_bitable`
+2. `data-sources.json` + `.env` 凭证齐全
+3. `columns` 收紧 `searchable` / `editable`，结果链接用 `displayType: url`
+4. CLI / Action 与数据管理抽测同一 `app_token` + `table_id`
+5. 见 CHECKLIST **A6-17**
+
 ---

 ## 与 SCHEMA / ACTIONS 的关系

- [`SCHEMA.md`](SCHEMA.md)：`_jiangchang_*` 契约适用于**已注册数据源**上的表，不限于本地文件。
- [`ACTIONS.md`](ACTIONS.md)：无 `replaces` 时宿主直写**已注册数据源**（默认本地 SQLite）。
- [`CLI.md`](CLI.md)：`init-db` 对当前 active backend 幂等初始化元数据。
+- [`SCHEMA.md`](SCHEMA.md)：`_jiangchang_*` 适用于 SQLite/MySQL 已注册表；飞书用本文件 `columns`。`url` 外开、列筛选语义两边对齐。
+- [`ACTIONS.md`](ACTIONS.md)：无 `replaces` 时宿主直写**已注册数据源**；状态机表常用 Policy 关裸编辑 + `replaces: delete` + `visibleWhen`。
+- [`CLI.md`](CLI.md)：`init-db` 对当前 active backend（sqlite/mysql）幂等初始化元数据。
--- a/references/POLICY.md
+++ b/references/POLICY.md
@@ -168,6 +168,26 @@

 未知字符串：忽略。**禁止**把「省略」解释成全禁。

+### 2.5 状态机 / 队列表配方（推荐）
+
+业务状态只能走领取、提交、验收、结算等 Action，**禁止**用户在数据管理里裸改状态 / 结果链接时：
+
+```json
+{
+  "schemaVersion": 1,
+  "skill": "your-skill-slug",
+  "actor": { "userId": "u1" },
+  "actions": { "mode": "open" },
+  "hostCapabilities": ["refresh", "view", "export", "import"]
+}
+```
+
+要点：
+
+1. **`hostCapabilities` 不含 `edit`（也不含直写 `delete`）** → 宿主隐藏裸「编辑」；状态机字段同时建议列级 `editable: false`（SQLite `_jiangchang_columns` 或飞书 `data-sources.columns`）。
+2. 删除仍要走技能校验时：声明 **`replaces: delete`**，并用 `bind.visibleWhen` + `equalsFrom: currentUser.userId` 控制「仅本人可见删除」（宿主行菜单与技能按钮同一规则；见 [`ACTIONS.md`](ACTIONS.md)）。
+3. `mode: open` 不挡业务 Action；需要收紧技能按钮时再改 `allowlist`。
+
 ---

 ## 3. L2：`data` 与 scope 语法白名单
--- a/references/SCHEMA.md
+++ b/references/SCHEMA.md
@@ -346,11 +346,24 @@ upsert_column_metadata(
 | `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`（薄层；校验从宽） | 原文 |
+| `url` | `TEXT` | **可点击链接**（见下） | 单行输入 `type=url`（薄层；校验从宽） | 原文 |
 | `email` | `TEXT` | 原文 | 单行输入 `type=email`（薄层；校验从宽） | 原文 |

 说明灰字与创建默认值见下一小节；与 Action 的对照写在 [`ACTIONS.md`](ACTIONS.md)「表单字段类型对照」。

+#### display_type: url 列表 / 详情外开（宿主契约）
+
+声明为 `url`（SQLite `_jiangchang_columns.display_type`，或 `data-sources.json` 的 `columns.*.displayType`）时：
+
+| 行为 | 约定 |
+|------|------|
+| 表格单元格 / 详情只读展示 | 合法 **`http://` / `https://`** 显示为可点击链接 |
+| 点击 | 用**系统默认浏览器**打开（Electron `openExternal`）；非 Electron 环境可降级为新标签页 |
+| 非法或非 http(s) | 按普通文本展示，不可点 |
+| 表单编辑 | 仍是单行 URL 输入；**不**在输入框内嵌浏览器 |
+
+技能只需声明类型；**不要**再为「外开链接」单独做 Action。飞书等多维表源同样认 `columns.*.displayType: "url"`。
+
 **明确不在本版稳定范围（勿在新技能宣传为已支持）：**

 - 文件 / 图片上传
@@ -359,7 +372,9 @@ upsert_column_metadata(

 > **Lookup 多选**已纳入本版契约（见下文 `multiple`），与「任意多选/标签数组」不是同一能力。

-`datetime_unix_milliseconds`：仅兼容**列表展示**旧数据；**新技能不要用**；可编辑时间一律 `datetime_unix_seconds`。
+`datetime_unix_milliseconds`：仅兼容**列表展示**旧数据（含部分飞书时间列映射）；**新 SQLite 技能不要用**；可编辑时间一律 `datetime_unix_seconds`。
+
+远程源（如飞书）还可能出现宿主映射的 `userId` / `currency` / `attachment` 等展示类型：用于列表/表单呈现；**新本地 SQLite 技能仍优先使用上表稳定类型**，勿把飞书专用类型抄进 DDL 当默认。

 #### 新增/编辑表单：字段说明与默认值（宿主支持）