Pinvou/pinvou-agent / pinvou3-app/src-tauri/resources/common/bundle/dingtalk-skills/dws
dws
Unverified【何时用:仅当用户明确指向钉钉/DingTalk(钉钉文档、钉钉日程等)时使用;泛指做文档/表格/待办/审批默认走本地工具,不要误用钉钉】用 dws CLI 管理钉钉:AI表格/AI搜问(找人首选)/目标管理(Agoal)/组织大脑/日历/通讯录/群聊与机器人消息/待办/审批/智能合同/考勤/日志(日报周报)/DING消息/钉钉文档/云盘/Markdown文件/HTML文件/AI听记/邮箱/在线电子表格(axls)/知识库/白板/开放平台文档/个人IM与OA事件订阅。用户要求操作上述钉钉产品时使用。
references/products/aitable/aitable-psql.md
View on GitHub# AI 表格 PostgreSQL 只读查询
## 适用场景
仅当用户明确要求 SQL / PostgreSQL / `SELECT` 且目标需要以下任一 psql 专属能力,或需求本身包含以下任一复杂服务端分析时,使用 `dws aitable psql`:
- 查看 PostgreSQL 逻辑表清单或逻辑列类型
- 最多 8 张同 Base 数据表的 `INNER`、`LEFT`、`RIGHT`、`FULL OUTER JOIN`;`CROSS JOIN` 仅支持两张表
- 字段间算术、`CASE`、聚合后派生指标、汇总结果 Top N 或排名
- `ROW_NUMBER`、`RANK`、`DENSE_RANK` 等窗口函数,或必须依赖 PostgreSQL 类型语义的计算
原始记录筛选、排序和 Top N 使用 `record query`;单表直接标量、分组或去重统计使用 `record stats` / `record group-stats`。读取字段配置、选项、公式配置时仍使用 `field get`;只有用户关心 SQL 可查询列及 PostgreSQL 类型时才使用 `psql -t`。
## 查询路由与降级
| 查询需求 | 首选接口 | 原因 |
|---|---|---|
| 按 recordId、关键词或字段条件读取原始记录,或对原始记录筛选、排序、取 Top N | `record query` | 直接返回 `recordId`、`cells` 和 cursor 等记录模型。 |
| 单表直接标量、分组或去重统计 | `record stats` / `record group-stats` | 由原生统计接口完成,不需要 SQL。 |
| 已获用户明确许可的完整逐行明细或逐条业务操作(不做分析) | `dws aitable record query --all --page-limit 0` | 由 CLI 统一处理完整扫描;必须服务端过滤、只取必要字段并先取小样本。 |
| 完整数据导出 | `dws aitable export data` | 导出是文件交付,不得把记录拉到 Agent 上下文做分析。 |
| 同 Base 多表关联、字段间算术、CASE、聚合后派生、汇总结果 Top N 或排名、窗口函数 | `psql` | 先核对表和列,再用 SQL 在服务端完成原生接口无法直接表达的分析。 |
当需求需要 `psql` 的复杂分析能力时,即使用户没有明确说 SQL,也必须使用 `psql`。`psql` 执行失败后,先保留真实错误并从原始用户意图重新判定:仅当需求完全是单表原始记录筛选、排序、Top N 或逐条操作时,才可重新发起 `record query`;仅当需求完全是单表直接标量、分组或去重统计时,才可重新发起 `record stats` / `record group-stats`。切换时必须说明原因、丢弃 psql 的未完成结果,且不合并两类结果;不得用这些接口拆分或模拟 JOIN、字段计算、CASE、聚合后派生、汇总排名、窗口计算或本地分析。
### 正反边界案例
| 用户请求或结果需求 | 应选 | 不应选 / 原因 |
|---|---|---|
| “金额最高的 10 条记录”“按日期筛选原始记录” | `record query --sort ... --limit 10` | 排序对象是原始记录,不因 SQL 也支持 `ORDER BY` 改走 psql。 |
| “本月订单总金额”“各状态分别多少条”“唯一门店数” | `record stats` / `record group-stats` | 单表直接标量、分组或去重统计,不需要 SQL。 |
| “把两张表关联,找未匹配记录”“各门店销售额占总额比例” | `psql` | 需要 JOIN 或聚合后派生,不能分多次 `record query` 后拼接。 |
| “销售额最高的 10 个门店并排名” | `psql` | 排序对象是聚合结果,需要汇总后排序或窗口排名。 |
| “下载/交付完整原始数据文件” | `export data` | `psql` 不承担无界文件导出,`record query --all` 也不替代导出。 |
| “读取这几个 recordId 的 cells”“按字段条件查看一页记录”“需要 cursor、recordId 或原始字段类型” | `record query` | 这是结构化记录读取,不应为了少量详情改写成 SQL。 |
| “按条件找出记录后逐条更新/删除/分享” | `record query` | 仅用它定位有限的业务记录;范围依赖聚合后派生或关联时,先用 `psql` 确定范围。 |
## 服务端分析强制规则
- 已选用 `psql` 的 JOIN、字段间算术、CASE、聚合后派生、汇总排名和窗口计算,必须在服务端 SQL 中完成。禁止拉取明细后使用 Python、jq、JavaScript、电子表格或其他本地工具做等价加工。
- 全程固定使用一个已验证可执行的 DWS 二进制或包装脚本,不得混用内置 shim、本地版或其他版本。依次执行 `psql -l`、每张目标表的 `psql -t`、使用真实 `Name` 的 `LIMIT 3` 最小查询;最小查询成功后才执行正式 SQL。
- 按业务主题拆分 SQL;同一事实粒度、同一关联链的过滤、JOIN、聚合和派生指标应合并到一条 SQL。关键结论必须用独立 SQL 在服务端复核。
- 出现 `pending-post-tool-use`、`host-side execution`、`PostToolUse hook did not activate` 或 `real result was not produced`,属于客户端或宿主执行失败:切换到正确的同一 DWS 入口后重试原 psql 命令。网络、认证或权限失败也必须先修复后重试;这些故障不得以其他查询接口绕过。
- SQL 或 psql 能力失败时,先缩减为最小查询,再逐步加入 WHERE、JOIN、GROUP BY 和窗口计算;语法或函数不支持时先在服务端改写或拆成多条 SQL。仅当回看原始意图后完全符合单表原始记录,或单表直接统计时,才允许丢弃 psql 未完成结果并重新发起 `record query`,或 `record stats` / `record group-stats`;必须说明切换原因,禁止合并结果或本地补算。对 JOIN、字段间算术、CASE、聚合后派生、汇总结果 Top N 或排名、窗口计算,始终先修复或在服务端等价改写,禁止降级。已获用户明确许可的非分析完整逐行明细不依赖也不触发此 psql 门禁,按 `record query --all` 的规则执行;即使获准,也必须服务端过滤、只取必要字段、先取小样本;预计超过 5,000 条、20 个字段、20MB 或需要 `--all` 时,必须再次确认。
## 命令模式
`-l`、`-t`、`-c` 三种模式互斥。`-t` 仅用于查看表结构;执行 SQL 时表由 `FROM` / `JOIN` 自动解析,无需传 `-t`。
### 命令生成约束
- 必须按以下模板生成完整命令,不得省略 `-d` 及其值。
- `<BASE_ID>`、`<TABLE_ID>` 是文档占位符;实际执行前必须替换为上下文中的真实 ID,并用单引号包裹。
- 常规模式参数仅使用 `-d`、`-l`、`-t`、`-c`;查看全属性列可使用 `--all-properties`,执行约束可使用 `--limit`、`--timeout`;禁止改写为 `--base-id`、`--table-id`、`--sql` 或 `--base`。
- 查看表结构时,默认只查看与 AI 表格页面一致的基础字段(默认属性),不得因字段类型复杂而自动添加 `--all-properties`。仅当用户显式要求查看全部扩展属性时,才添加该参数。
- 不得使用不存在的 `dws aitable table list` 作为回退;表发现只能使用 `psql -d '<BASE_ID>' -l`。
- 本文已明确命令契约时,不得通过帮助输出重新猜测功能是否存在;以本文公开命令契约为准。
- 执行前向用户展示命令时,必须展示即将执行的完整命令,不能简写为 `dws aitable psql -l`。
- 命令失败时保留并依据真实错误处理;不得据此猜测“命令尚未实现”或“功能未发布”。
```bash
# 列出 Base 内可通过 PostgreSQL 查询的逻辑表
dws aitable psql -d <BASE_ID> -l
# 默认查看与页面一致的基础字段;仅用户显式要求全部扩展属性时增加 --all-properties
dws aitable psql -d <BASE_ID> -t <TABLE_ID>
dws aitable psql -d <BASE_ID> -t <TABLE_ID> --all-properties
# 执行只读 SQL
dws aitable psql -d <BASE_ID> \
-c 'SELECT * FROM "数据表1" LIMIT 10'
```
`psql` 输出是面向用户的 PostgreSQL 表格文本,不支持也不添加全局 `--format json`。这是 AI 表格 Skill 中“结构化读取使用 `--format json`”规则的明确例外。
## 返回模型与类型边界
- `psql` 的 `SELECT` 结果是 PostgreSQL 列/行投影后渲染出的表格文本;复杂值可能被展示为 JSON 文本。SQL 列名、别名、PostgreSQL 类型和输出行均不等同于 `record query` 的 `fieldId`、`recordId`、`cells`、`status` 或 `nextCursor`。
- `record query` 返回结构化记录模型及分页元数据,字段和值遵循 AI 表格字段类型和记录语义;它不是 PostgreSQL 行集,也不能直接作为 SQL 表名、列名、类型或 JOIN 条件。
- 同一次业务查询只能选择一个结果模型:禁止把 `psql` 的表格值、列名或别名拼入 `record query` 的参数或响应;也禁止把 `record query` 的记录、cells 或 cursor 当作 `psql` 的 SQL 输入或结果继续处理。
- 后续步骤确实需要另一种模型时,必须从原始用户意图重新发起对应查询,并明确说明切换原因和结果来源;不得合并两类结果后再做关联、聚合、类型推导或权限判断。需要 SQL 列和类型时先执行 `psql -t`;需要记录 ID、字段 ID、cells、status 或 cursor 时使用 `record query` / `field get`。
## 自然语言路由
| 用户意图 | 执行方式 |
|---|---|
| “这个 AI 表格里有哪些可查询的数据表” | `psql -d <baseId> -l` |
| “数据表1有哪些 SQL 字段和类型” | 先 `-l` 解析真实 `tableId`,再 `psql -d <baseId> -t <tableId>` |
| “查询数据表1前 10 条”,即使上下文明确要求 SQL | `record query --limit 10`;这是原始记录读取,SQL 表述不改变结果模型路由 |
| “把数据表1、数据表2和数据表3关联起来”或“分析不同表之间的关系” | 优先使用 psql:先列出表并查看每张表的结构,再生成一条多表 JOIN SQL;表由 SQL 自动解析 |
| “按业务状态统计数量” | `record group-stats`,单表直接分组统计不需要 SQL |
| 明确要求 SQL,且统计后还需派生、聚合结果 Top N 或排名、窗口计算 | 优先使用 psql:先查看逻辑结构,再生成对应 SQL;仅明确要求 SQL 的单表直接标量、分组或去重统计仍使用 `record stats` / `record group-stats`。 |
| “按分组排名/生成行号” | 先查看逻辑结构,再生成使用 `ROW_NUMBER/RANK/DENSE_RANK ... OVER (...)` 的 SQL |
用户只给表名时,必须先用 `psql -l` 获取真实 `tableId`;零命中或重名时要求用户消歧,禁止猜测。编写 SQL 前必须用 `psql -t` 核对实际逻辑列名和 PostgreSQL 类型。
## SQL 生成规则
- 仅允许一条标准 PostgreSQL / pgsql 语法的只读 `SELECT`;禁止 `INSERT`、`UPDATE`、`DELETE`、DDL 和多语句。
- 必须使用 PostgreSQL 方言:禁止 MySQL/SQLite/Oracle 等非 PostgreSQL 写法,例如反引号标识符、`LIMIT offset,count`、`IFNULL`、`DATE_FORMAT`、`NVL`、`DUAL` 等。
- SQL 生成完成后、执行前必须自检:所有来自 AI 表格元数据的逻辑表名、逻辑字段名和中文结果别名均使用双引号;SQL 关键字、函数名、表别名不加引号。禁止依赖未加引号的中文标识符“恰好可被解析”。
- 双引号仅用于 SQL 标识符,单引号仅用于字符串字面量。例如必须生成 `SELECT COUNT(*) AS "记录数" FROM "核销明细" LIMIT 200`,不得生成 `SELECT COUNT(*) AS 记录数 FROM 核销明细`,也不得将字符串写成双引号。
- 命令中的完整 SQL 使用 shell 单引号包裹,SQL 标识符使用双引号;不得用 shell 外层双引号代替 SQL 标识符的双引号。
- `-c` 传入的 SQL 末尾不得包含分号(`;`);服务会将 SQL 封装为子查询,尾部分号会导致 PostgreSQL 语法错误。
- JOIN 表必须属于同一个 Base;最多引用 8 张表,执行时由 SQL 的 `FROM` / `JOIN` 自动解析表。
- 支持 `INNER`、`LEFT`、`RIGHT`、`FULL OUTER JOIN`;`ON` 仅支持相同 PostgreSQL 标量类型的跨表字段等值比较及 `AND` 组合。
- `CROSS JOIN` 仅支持两张表,不能串联其他 JOIN,且不得携带 `ON` 或 `USING`。
- 支持聚合函数 `COUNT`、`SUM`、`AVG`、`MIN`、`MAX`;`GROUP BY` 仅支持列引用,`HAVING` 仅用于分组或聚合查询。
- 支持窗口函数 `ROW_NUMBER`、`RANK`、`DENSE_RANK`,以及上述聚合函数的 `OVER` 形式;不生成命名 `WINDOW`、窗口框架或窗口内 `DISTINCT`。
- 支持多列 `ORDER BY`、`ASC/DESC`、`NULLS FIRST/LAST`、`LIMIT` 和 `OFFSET`。
- `LIMIT` 生成规则:
- 用户明确限制条数、页大小或“前 N 条”时,必须把该限制写入 SQL 的 `LIMIT n`。
- 用户没有明确限制条数时,必须在 SQL 的合法位置主动添加 `LIMIT 200`;若同时使用 `OFFSET`,应生成 PostgreSQL 合法顺序 `LIMIT 200 OFFSET n`。
- 用户要求全量数据时,也必须说明实际执行仍受工具 `--limit 1..1000` 和 `--timeout 1..60` 上限约束,禁止生成无限制大结果查询。
## 查询结果返回规则
- 将原始 psql 表格结果返回用户,避免擅自改写为 JSON。
- 每次成功展示查询结果后,必须追加温馨提示:`温馨提示:请确认当前 AI 表格是否开启高级权限;开启后,返回的字段和数据均会受到高级权限影响。`
## 多表 JOIN 示例
```bash
dws aitable psql \
-d '<BASE_ID>' \
-c 'SELECT a."业务名称", COUNT(c."文本") AS "数量" FROM "数据表1" a LEFT JOIN "数据表2" b ON a."业务名称" = b."文本" LEFT JOIN "数据表3" c ON b."文本" = c."文本" GROUP BY a."业务名称" LIMIT 200'
```
## 执行流程
1. 固定一个已验证可执行的 DWS 二进制或包装脚本;从用户提供且已确认是 AI 表格的 URL 提取 `baseId`,没有 URL 或 ID 时按现有 Base 搜索流程定位。
2. 执行 `psql -d <baseId> -l`,获取真实表名与 `tableId`;SQL 的 `FROM`/`JOIN` 只能使用返回的 `Name`。
3. 对 SQL 涉及的每张表执行 `psql -d <baseId> -t <tableId>`,默认仅查看与页面一致的基础字段;仅当用户显式要求查看全部扩展属性时增加 `--all-properties`。
4. 先执行 `LIMIT 3` 的最小 PostgreSQL 只读查询;失败时按服务端分析强制规则分类并缩减 SQL。仅当从原始意图重新判定为单表原始记录或单表直接统计时,才可丢弃未完成的 psql 结果并重新发起对应原生接口;复杂分析禁止降级。
5. 最小查询成功后,根据用户自然语言生成正式 SQL;用户没有明确限制条数时必须添加 `LIMIT 200`,遇到重名或语义不明确先询问;同一事实粒度和关联链尽量合并为一条 SQL。
6. 执行 `psql -d ... -c ...`,由 SQL 中的 `FROM` / `JOIN` 确定目标表;关键结果使用独立 SQL 在服务端复核,并将原始 psql 表格结果返回用户。
7. 查询结果展示完成后,追加高级权限温馨提示,提醒用户开启高级权限后字段和数据均会受权限影响。
不得为了模拟真实用户而要求用户自己编写 SQL、提供 fieldId,或在每次对话中粘贴 dws 命令;Agent 应完成表和列发现、SQL 生成与执行。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |