@lark-base-open/base-database-cli 1.0.0

package/skills/lark-base-database/references/base-capability-routing.md

@@ -0,0 +1,81 @@
+# 原生 Base 能力发现与路由
+
+当 `lark-base-database` 无法确认某项功能时，使用本流程查询飞书多维表格本体能力。不要从 数据库应用开发文档未提及、Catalog 未展示或记忆中的旧版 CLI 推导“不支持”。
+
+## 触发条件
+
+能力归属无法确认时，在以下动作之前强制执行能力发现：
+
+- 选择 Page、SQL Function、FaaS 或原生 Base 的实现归属；
+- 删除、简化或降级一项用户需求；
+- 声称多维表格、数据库应用开发链路或 `lark-cli` 不支持某项能力；
+- 用 FaaS 模拟定时触发、记录变化触发、提醒、通知、权限控制等 Base 本体行为。
+
+## 查询顺序
+
+1. 把需求改写成一个能力动词和目标资源，例如“记录创建后通知人员字段中的用户”“按角色限制字段编辑”“提交公开表单”。
+2. 运行 `lark-cli base --help`，从当前安装版本的 shortcut 列表查找相关资源；不要依赖旧版命令记忆。
+3. 对候选命令运行 `lark-cli base +<shortcut> --help`，确认它支持 list/get/create/update/enable 等哪些动作、需要哪些 ID 和 JSON。
+4. 已有 Base 先解析真实 `base_token`，再用只读命令确认资源和现状。优先从 `+base-block-list` 看 Base 内资源，再进入对应的 list/get；表、字段、视图和其他资源 ID 必须来自真实返回。
+5. 当前环境提供 `lark-base` Skill 时，读取其快速路由和对应 reference 后再构造复杂 JSON。不得猜 workflow steps、dashboard data config、role config、字段或记录 CellValue。
+
+最小发现命令：
+
+```bash
+lark-cli base --help
+lark-cli base +base-block-list --help
+lark-cli base +<candidate-shortcut> --help
+```
+
+已有 Base 的只读查询显式使用用户身份：
+
+```bash
+lark-cli base +url-resolve --url '<base-url>' --as user
+lark-cli base +base-block-list --base-token '<base-token>' --as user
+lark-cli base +<resource-list-or-get> ... --as user
+```
+
+## 能力路由
+
+| 需求类别 | 优先检查的原生 Base 路由 |
+| --- | --- |
+| Base、表、字段、记录 | `+base-*`、`+table-*`、`+field-*`、`+record-*` |
+| 查询、统计、派生值 | `+record-list`、`+record-search`、`+data-query`、`+field-create` / `+field-update` 的 formula 或 lookup |
+| 视图与筛选展示 | `+view-*` |
+| 表单与题目 | `+form-*`、`+form-questions-*` |
+| 图表与仪表盘 | `+dashboard-*`、`+dashboard-block-*` |
+| 定时、记录触发、提醒、通知 | `+workflow-*` |
+| 角色与数据权限 | `+role-*`、`+advperm-*` |
+
+这张表只用于定位候选命令，不代替当前 CLI 的 `--help`、目标资源的真实返回或 `lark-base` reference。
+
+## 决策与实施
+
+查询完成后只选择以下一种结论：
+
+1. **原生 Base 实现**：能力由多维表格本体提供。通过 `lark-cli base +...` 配置，应用只提供需要的交互页面。
+2. **数据库应用实现**：能力属于页面交互、SQL 读取或由 Page 主动发起的即时业务写入，按 Page/SQL/FaaS 边界实现。
+3. **组合实现**：例如 Page/FaaS 创建记录，原生 workflow 监听记录并通知；分别配置并独立验收两段链路。
+4. **已证实的缺口或阻塞**：找不到当前 CLI 入口、命令明确不支持，或遇到权限或环境阻塞。准确描述为“当前 `lark-cli` 未暴露”“原生能力明确不支持”或“当前身份无权限”，不要互相替代。
+
+组合实现中的通知必须保持入口意图一致。创建 workflow 前逐个把 `LarkMessageAction` 归入以下一种策略：
+
+| 入口策略 | 适用场景 | 必须满足 |
+| --- | --- | --- |
+| `site_action` | 除下列两个明确授权场景外，所有与应用业务对象关联的通知 | Page 先实现真实功能路由；通知提供显式 `openLink`，使用发布返回的 `baseAppUrl`、功能定位参数和最小稳定对象标识 |
+| `informational` | 用户明确要求通知纯展示、无需任何点击入口 | `btn_list=[]`；记录用户原文，并披露原生通知仍可能沿平台默认行为跳转 Base |
+| `base_action` | 用户明确要求从通知进入多维表格 | 只在该明确要求下使用 Base `recordLink` 或 Base URL，不得描述成应用入口 |
+
+不得因为通知正文已经包含业务信息或用户未指定跳转目标，就推断为 `informational`。访客登记后通知被访人固定属于 `site_action`：Page 必须提供当前登记详情路由，消息按钮必须进入该路由；即使通知正文已包含访客姓名、公司和来访事由也不例外。`lark-base` workflow 文档里的 `$.<trigger>.recordLink` 是通用 Base 记录链接示例，不适用于 `site_action`。此类 `LarkMessageAction.data.btn_list[].btn_action=openLink` 必须进入与通知动作对应、由 Page 已实现的站内功能，并通过查询参数携带直接定位目标业务对象所需的最小稳定标识。例如考试发布通知应进入该考试的详情或答题状态，而不是应用首页。`base-database-cli deploy` 返回的 `baseAppUrl` 是当前环境唯一可信的用户入口；不得使用内部静态资源 `staticUrl`、`recordLink`、Base URL、应用 `managementUrl`，也不得根据应用 token 自行拼接 Preview/Prod 地址。
+
+`btn_list=[]` 只说明没有显式按钮，不代表原生通知不可点击，也不能证明通知整卡不会沿平台默认行为跳转 Base。当前暴露的 workflow 配置没有关闭该默认入口的字段。用户要求任何点击都不得进入 Base 时，原生 `LarkMessageAction` 不能直接视为满足要求；继续执行能力发现，若找不到可完全控制链接的通知方案，则记录为平台阻塞，不能用 `informational` 绕过要求。
+
+新 `site_action` workflow 在 Preview 发布前不创建。Preview 发布后基于命令返回的顶层 `baseAppUrl`、代码中已经存在的功能定位参数和 workflow 上下文中的对象标识，一次性构造最终按钮链接，直接执行 `+workflow-create`、`+workflow-enable` 和 `+workflow-get`。只有修改已有 workflow 时才先读取完整定义，只替换按钮链接，再执行全量 `+workflow-update` 和回读。不得发明页面未实现的功能，也不得使用内部静态资源 `staticUrl`。Prod 发布不会触发 Base workflow 自动迁移；发布后必须按记录逐个更新已有 workflow，只替换为 Prod 命令返回的顶层 `baseAppUrl`，保留功能定位参数、动态对象参数、其他步骤和启用状态。
+
+能力发现默认只读。新建系统中，用户要求的非破坏性原生 Base 配置属于应用开发范围，可在 `init` 返回真实 Base token 后执行；基于已有 Base 时，创建或修改原生配置前先确认它在用户授权的修改范围内。删除资源、关闭 workflow、关闭高级权限或改变已有角色权限时，必须按[危险操作确认](../SKILL.md#危险操作确认)先用当前 turn 的文字说明对象和影响，结束本轮，并在用户后续明确回复后再执行。
+
+复杂 create/update 必须遵守对应 shortcut 的 `--help` 和 `lark-base` reference。更新要求完整配置时先 get，再 read-modify-write；支持 delta update 时提交最小合法 payload。完成写入后使用 list/get 回读，workflow 等有启停状态的资源还要核对实际状态。应用通知要逐个回读 `LarkMessageAction`：`site_action` 核对每个业务 `openLink` 最终使用当前发布环境返回的 `baseAppUrl`，并指向通知对应的真实功能及目标对象，而不是应用首页、Base 或管理后台；`informational` 和 `base_action` 分别核对存在用户明确要求纯展示或进入多维表格的原文。任一链接、对象标识、入口策略或回读不一致时立即执行 `+workflow-disable`，并把交付标记为 partial 或 blocked；不得把应用发布成功等同于整体交付完成。Prod 阶段还要确认应用链接不再包含 `mode=edit`。
+
+## 交付证据
+
+交付时把原生 Base 配置纳入资源和验收清单，至少报告资源类型、名称、真实 ID、启用状态和它与应用的衔接点。若记录缺口，附上实际查询过的命令、当前 CLI 版本或帮助输出结论，以及阻塞属于平台、CLI 覆盖还是权限；不得只写“Skill 没提到”或“没找到”。

package/skills/lark-base-database/references/base-sql-unsupported.md

@@ -0,0 +1,42 @@
+# Base SQL 不支持能力
+
+仅在判断支持集之外的 SQL 语法、评审或排查 SQL，或者处理 SQL 编译与运行兼容失败时读取。以下能力不写入 `main.sql`：
+
+## Stored Query 与分页
+
+- 参数 kind 不使用 `OPTION`；SingleSelect 选项名使用 `TEXT` 参数，并在 Page/FaaS 按 Catalog 选项白名单约束输入后用于 `=`、`!=`、`IN`、`NOT IN`。
+- 不把 `USER`、`GROUP`、`FILE`、数组或集合声明为正常业务参数；也不传 null 参数。
+- 不通过移除服务端筛选、读取固定前 N 条后在 Page 分页来声称完整分页或全量导出。业务确实需要任意翻页、完整搜索或全量导出时记录平台限制。
+
+## 查询结构与引用
+
+- 查询结构：`SELECT *`、`table.*`、`UNION`、`INTERSECT`、`EXCEPT`、`INSERT`、`UPDATE`、`DELETE`、`MERGE`、递归 CTE、嵌套 CTE，以及右侧会展开为多个 FROM item 的右深嵌套 JOIN。
+- 无真实表依赖查询：`SELECT 1`、`SELECT $1`、仅 `FROM (SELECT 1) AS x`、仅常量 CTE 或仅 `UNNEST(...)` 的查询。绑定 Base 的 SQL Function 必须直接或经由派生表/CTE 引用至少一个 Catalog 真实表，否则 Project 执行可能报“BaseSQL 上下文路由失败：SQL 未引用可路由表”。与 Base 数据无关的常量在 Page/FaaS 中用代码返回。
+- 分组：`GROUP BY` 超过 5 项；需要更多展示列时拆成聚合 SQL 与明细 SQL 后在 Page/FaaS 合并。
+- JOIN：`RIGHT JOIN`、`FULL JOIN`、`NATURAL JOIN`、`JOIN ... USING`、JOIN group alias、`LEFT JOIN UNNEST(...)`、`INNER JOIN UNNEST(...)`、含 `GROUP BY` 或聚合函数的派生表 JOIN，以及单条查询超过 16 个 JOIN。
+- 列引用：`table_alias.user_field.userId` 等三段引用；标量对象子字段只使用 `"人员字段".userId` 或 `UNNEST` 后的 `u.userId` 两段形式。
+- 派生对象：把 `USER`、`GROUP`、`FILE` 完整对象投影到派生表后再 JOIN。frontend 可能接受该形态，online backend 仍可能统一返回 `SQL is not supported`。
+
+## 类型、表达式与字段操作
+
+- 类型与表达式：`CURRENT_DATE`、`COALESCE`、`CASE expr WHEN value THEN ... END`、显式 `CAST` / Coerce，以及固定支持集之外的函数调用。
+- CASE：应该写 `CASE WHEN expr = value THEN ... ELSE ... END`；不要写 `CASE expr WHEN value THEN ... END`。
+- 条件聚合：不要写 `SUM/AVG(CASE WHEN ... THEN 1 ELSE 0 END)`；改用 `SUM(CASE WHEN ... THEN 1.0 ELSE 0.0 END)`。
+- `ILIKE`、`NOT ILIKE`：字段支持不统一，正常查询使用 `LIKE`、`NOT LIKE`。
+- 子查询表达式：投影、`WHERE` 或 `ORDER BY` 表达式里的标量子查询。用单独 SQL Function 查询聚合或明细，再在 Page/FaaS 合并。
+- 聚合与窗口函数：`STDDEV`、`VARIANCE`、`PERCENTILE`、`MEDIAN`、`ROW_NUMBER()`、`RANK()`。
+- 字符串函数：`SPLIT`、`SUBSTRING`、`REPLACE`、`POSITION`、`REGEXP` / `RLIKE`。
+- 数字函数：`POWER`、`SQRT`、`LOG`、`EXP`。
+- 日期函数：`DATEDIFF` 及其他未列入支持集的 DURATION 函数。
+- `rec_id`、`TEXT`、Phone：顺序比较、`BETWEEN`、`NOT BETWEEN`。文本日期字符串不能用 `<`、`<=`、`>`、`>=` 做范围筛选；需要日期范围时把字段建成 DateTime/TIMESTAMP，或改用 Text 支持的 `=`、`IN`、`LIKE` 后在 Page/FaaS 中判断范围。
+- Checkbox：`IN`、顺序比较、`BETWEEN`、`NOT BETWEEN`。
+- DateTime：`IN`、`NOT IN`、`LIKE`、`ILIKE`。
+- SingleSelect：顺序比较、`BETWEEN`、`NOT BETWEEN`、`LIKE`、`ILIKE`，以及与 `''` 空字符串比较；动态选项名筛选使用 `TEXT` 参数，不使用 `OPTION` 参数 kind。
+- MultiSelect：`LIKE`。
+
+## 不要误判为整体不支持
+
+- `LIKE $1` 本身可用，参数携带 `%`；历史复合查询失败主要来自 `OPTION` 参数 kind 或其他不支持节点，不要把参数化 `LIMIT/OFFSET` 误判为 backend 不支持。
+- OPTION 字段可以与 Catalog 中合法的固定选项名或 `TEXT` 参数使用 `=`、`!=`、`IN`、`NOT IN` 比较；不支持的是 Stored Query 的 `OPTION` 参数 kind。
+- 参数化 `LIMIT $n` / `OFFSET $n` 可用；页面输入不能直接决定返回规模，确需动态条数时由 Page/FaaS 先校验为非负整数并限制最大值。
+- 支持集内的 `CASE WHEN ... THEN ... END`、`INNER JOIN`、`LEFT JOIN`、`CROSS JOIN`、非递归顶层 CTE、派生标量列、`FROM` 子查询、逗号连接或 `CROSS JOIN` 形态的 `UNNEST`、`TIMESTAMP` 字面量、`INTERVAL`、`EXTRACT`、DURATION 运算、`ARRAY_AGG`、`CEIL` 和 `FLOOR` 可以使用；某个复合查询失败时先按错误节点缩小，不把这些能力整体降级。

package/skills/lark-base-database/references/database-capability-skill.md

@@ -0,0 +1,24 @@
+# 应用能力 Skill
+
+能力 Skill 使用 `base-database-<hash>` 名称和 `base-database-managed-skill` 管理标记。
+命令统一使用 `database-skill`；同一应用和环境使用固定目录，安装或部署时更新本工具管理的 `SKILL.md`，保留附加文件。
+目标目录的管理标记不匹配或存在符号链接冲突时停止并报告，不覆盖冲突内容。
+
+部署成功时 CLI 自动安装/更新本应用 Skill，结果在 `agentGuide.skill`。模板由 CLI 包维护，生成文件只包含应用和环境定位、发现及调用流程，不缓存 Function 列表或参数 Schema，不包含凭证、源码或工程绝对路径。
+
+安装失败、需要重新生成或要安装到另一 Agent 的用户技能目录时，使用发布结果中的真实应用 token，以及已确认的应用名称：
+
+```bash
+npx @lark-base-open/base-database-cli database-skill install --app-token <app-token> --title '<应用名称>'
+```
+
+默认安装到 `$CODEX_HOME/skills`，未配置时使用 `~/.codex/skills`。`--dir <skills-root>` 可指定其他 Agent 的技能目录。此操作只安装本地 Skill，不发布应用、不调用远端、不更改授权。安装器仅更新带有相同应用/环境管理标记的 `SKILL.md`；无管理标记的文件、同名目录或符号链接冲突会报错，先向用户说明，不删除冲突内容。
+
+后续使用不需要应用开发工程目录。已安装的 Skill 会通过以下独立入口实时发现正式版能力，并根据 Schema 调用；环境由当前 CLI 固定，不支持在调用参数里覆盖环境或用户身份：
+
+```bash
+npx @lark-base-open/base-database-cli database-skill discover --app-token <app-token> --page-size 20
+npx @lark-base-open/base-database-cli database-skill invoke --app-token <app-token> --function-id <发现的-id> --params '<业务参数JSON>'
+```
+
+`invoke --params` 是业务值本身（SQL 为数组），CLI 只包一层 `params` 并固定使用 `env=prod`。写操作需要用户明确授权对应业务动作；自动安装不构成写入授权。跨设备使用必须在目标设备安装对应 CLI 和 Skill，并完成该环境的用户登录，不能拷贝凭证。