Menú
用 hap 命令行查询/筛选/统计 HAP 工作表里的业务数据时用本 skill——尤其当筛选条件复杂、需要多条件 AND/OR、嵌套分组，或要做透视表聚合统计（求和/计数/平均/分组维度）。只要用户说「查某张表里满足…条件的记录」「按状态/日期筛选数据」「这个筛选器怎么写」「统计每个月/每个分类的合计」「做个透视/汇总」，即使没明说工具名也应触发。不用于：写入数据（增删改记录用 record 命令）。
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
| name | hap-cli-data-query |
| description | 用 hap 命令行查询/筛选/统计 HAP 工作表里的业务数据时用本 skill——尤其当筛选条件复杂、需要多条件 AND/OR、嵌套分组，或要做透视表聚合统计（求和/计数/平均/分组维度）。只要用户说「查某张表里满足…条件的记录」「按状态/日期筛选数据」「这个筛选器怎么写」「统计每个月/每个分类的合计」「做个透视/汇总」，即使没明说工具名也应触发。不用于：写入数据（增删改记录用 record 命令）。 |
帮用户用 hap 命令行从 HAP 工作表里把想要的数据查出来。难点不在命令本身，而在参数 JSON 怎么写对——筛选器结构、运算符词表、透视的维度与聚合。本 skill 把这些易错点讲清楚，并给可直接套用的模板。
本 skill 只管"查/筛/统计"（只读）。定位到目标行后要写回数据（改备注、改状态等）用
hap worksheet record update——注意它不接受--app-id，先hap app select <appID>， 写操作细节见hap-cli主 skill。增删改记录也直接用hap worksheet record相关命令。
| 命令 | 用途 | 筛选器格式 |
|---|---|---|
worksheet record list | 按条件查记录（筛选/排序/分页） | filter-json（builder DSL） |
worksheet record pivot | 透视聚合（分组维度 + 求和/计数等） | filter-json（同上） |
worksheet record bottom-stats | 视图底部那条汇总（单行统计） | filter-controls（主站 wire，不同） |
worksheet chart | 在工作表上建统计图表 | spec-json |
关键认知：
record list和record pivot共用同一套 filter-json；bottom-stats用的是另一套老格式，别混。绝大多数"查数据"诉求用前两个就够。
筛选/透视里的 field 用的是字段 ID（controlId）或别名，不是中文字段名。先查出来：
hap worksheet fields WORKSHEET_ID # 列出每个字段的 controlId / 名称 / 类型
记下要筛选/分组/聚合的那几个字段的 controlId，后面 JSON 里直接用。
筛选器是一棵树，由两种节点组成，可嵌套以表达复杂的 AND/OR：
// 分组节点：用 logic 把若干子条件组合起来
{ "type": "group", "logic": "AND", // AND | OR（不区分大小写）
"children": [ <条件或子分组>, ... ] }
// 条件节点：一个具体的过滤条件
{ "type": "condition",
"field": "<controlId 或别名>",
"operator": "<运算符>",
"value": <标量 或 数组> } // 为空类运算符不需要 value
最外层通常是一个 group。要表达「(A 且 B) 或 (C 且 D)」就嵌套 group。
比较类
| operator | 含义 | value |
|---|---|---|
eq / ne | 等于 / 不等于 | 标量或数组 |
gt / ge / lt / le | > / >= / < / <= | 数值或时间戳 |
in / notin | 是其中一个 / 不是任意一个 | 数组 |
contains / notcontains | 包含 / 不包含 | 标量或数组 |
concurrent | 同时包含（多选/关联同时含多个值） | 数组 |
belongsto / notbelongsto | 属于 / 不属于（部门） | 部门 ID 数组 |
startswith / notstartswith | 开头是 / 开头不是 | 标量 |
endswith / notendswith | 结尾是 / 结尾不是 | 标量 |
between / notbetween | 在范围内 / 不在范围内 | [起, 止] 数组 |
为空类（不要带 value 字段）
| operator | 含义 |
|---|---|
isempty | 为空 |
isnotempty | 不为空 |
⚠️ 易错点：这是 V3 的运算符拼写，和工作流/视图里那套（
gte/lte/empty/not_contains…）不一样。写 filter-json 一律以上表为准。
- 大于等于是
ge、le（不是gte/lte）- 否定式无下划线：
notin/notcontains/notbetween（不是not_in）- 为空是
isempty/isnotempty（不是empty）
worksheet fields 的字段 options 里查到。in 或 eq。⚠️ 必须用 rowid，不能用关联显示的标题文本（如版本名）去匹配。怎么拿这个 rowid 见下方「关联字段筛选」。子表的反向关联字段同理：value 填父记录的 rowid，即可筛出该父记录的全部子行。in/eq。belongsto / notbelongsto。contains / startswith / eq 等，value 直接给文本。between 给 ["2025-01-01","2025-01-31"]，或 gt/lt 给单个日期/时间戳。关联字段（如「任务」表里的「版本」「项目」「客户」）在返回数据里长这样——一个数组，每项带 sid（关联记录的 rowid）和 name（显示标题）：
"版本字段": [ { "sid": "ITERATION_ROW_ID", "name": "迭代A" } ]
筛选时 value 要用那个 sid。两种拿到它的办法：
record list --search "迭代A"，拿到目标记录的 rowid。注意关联显示的 name 来自该表的标题字段，可能和你以为的不一样（比如标题其实是 "2.3" 而非 "迭代A 2.3"），所以以实际查到的为准。record list 拉几条本表记录，看那个关联字段里已出现的 {sid, name}，挑出 name 匹配的 sid。拿到 sid 后这样筛（任务表里「版本」关联到「迭代A」）：
hap worksheet record list TASK_WS_ID --filter-json '{
"type":"group","logic":"AND",
"children":[{"type":"condition","field":"<版本字段ID>","operator":"in","value":["ITERATION_ROW_ID"]}]
}' -p 1 -n 100
子表数据不在父记录里，存在一张独立工作表（父 SubTable 字段的 dataSource），
子行通过反向 Relation 字段（父 SubTable 字段的 sourceField）挂回父行。
所以查某父记录的子行 = 在子表工作表上，按这个反向关联字段筛 = 父记录 rowid：
hap worksheet record list <子表WS_ID> --use-field-id-as-key -p 1 -n 100 \
--filter-json '{"type":"group","logic":"AND","children":[
{"type":"condition","field":"<反向关联字段ID>","operator":"in","value":["<父记录rowid>"]}]}' \
--sorts-json '[{"field":"<明细编号等排序字段ID>","isAsc":true}]'
<反向关联字段ID>：在父表 worksheet fields 里，找 SubTable 字段的 sourceField。in。--sorts-json，否则默认顺序不保证稳定，"数第 N 行"会数错。「姓张、且 1 月入职」或「在销售/市场部、或属于华北区」：
hap worksheet record list WORKSHEET_ID --filter-json '{
"type": "group", "logic": "OR",
"children": [
{ "type": "group", "logic": "AND", "children": [
{ "type": "condition", "field": "name", "operator": "startswith", "value": "张" },
{ "type": "condition", "field": "onboard_date", "operator": "between", "value": ["2025-01-01","2025-01-31"] }
]},
{ "type": "group", "logic": "OR", "children": [
{ "type": "condition", "field": "dept_option", "operator": "in", "value": ["k_sales","k_mkt"] },
{ "type": "condition", "field": "dept_id", "operator": "belongsto", "value": ["DEPT_HUABEI_ID"] }
]}
]
}'
简单单条件（状态为空的记录）——注意 isempty 不带 value：
hap worksheet record list WORKSHEET_ID --filter-json '{
"type":"group","logic":"AND",
"children":[{"type":"condition","field":"status","operator":"isempty"}]
}'
hap worksheet record list WORKSHEET_ID \
--filter-json '<见上>' \
--sorts-json '[{"field":"onboard_date","isAsc":false}]' \
--fields '["name","status","amount"]' \ # 只返回这几个字段，省 token
--page-size 50 --page-index 1 \
--include-total-count # 想要总行数时加
--page-size / --page-index 都是必填。--search 关键字模糊搜索（跨字段），可与 filter 叠加。--view-id 套用某视图的内置筛选/排序。--filter-json 就是查全部（按分页）。mingcheng、fuzeren、ssdd），不是 controlId。所以解析结果时按别名取值，或加 --use-field-id-as-key 让 key 变成 controlId。别名可在 worksheet fields 里看到。--fields 传字段 ID 或别名都行；只想要某几列时用它省 token。[{accountId, fullname, avatar, status}]，取 fullname 显示人名。任何「按 X 分组，算 Y 的合计/计数/平均」都用它。--values-json 和 --view-id 都必填（视图 id 用 hap worksheet view list WORKSHEET_ID 查，挑一个"全部"类视图即可）。
hap worksheet record pivot WORKSHEET_ID \
--view-id VIEW_ID \ # 必填
--rows-json '[{"field":"status"}]' \ # 行维度（分组）
--columns-json '[{"field":"create_date","granularity":3}]' \ # 列维度，可选
--values-json '[{"field":"amount","aggregation":"SUM"}]' \ # 值（聚合），必填
--filter-json '<同 list 的 filter 格式>' \ # 可选
--include-summary # 要总计行加
返回结构是 data.pivot（一个数组），每项形如：
{ "rows": { "<行维度字段ID>": "进行中" },
"columns": { },
"values": { "<值字段ID>": 190000.0 } }
解析时按字段 ID 从 rows/values 里取值；要排名就把 pivot 数组按某个 value 排序后取前 N（透视本身不保证按值排序）。
每项 {"field":"<controlId>", "displayName":"可选", "granularity":<整数>, "includeEmpty":false}：
granularity 仅对日期/地区字段有意义：
1=日，2=周，3=月1=省，2=省/市，3=省/市/县includeEmpty：是否把空值也作为一组，默认 false。每项 {"field":"<controlId>", "aggregation":"<聚合>", "displayName":"可选"}：
aggregation（不区分大小写）：COUNT 计数、DISTINCTCOUNT 去重计数、SUM 求和、MIN 最小、MAX 最大、AVG 平均。field 填特殊值 record_count，配 COUNT。示例——按月统计每个状态的订单数和金额合计：
hap worksheet record pivot WORKSHEET_ID \
--rows-json '[{"field":"create_date","granularity":3}]' \
--columns-json '[{"field":"status"}]' \
--values-json '[
{"field":"record_count","aggregation":"COUNT"},
{"field":"amount","aggregation":"SUM"}
]' --include-summary
record bottom-stats：只返回视图底部那一行汇总（不是多维透视）。它走的是另一套老格式：--column-rpts '[{"controlId":"amount","rptType":1}]'（rptType 是整数，按 --help 确认对应关系），--filter-controls 用主站 wire 结构而非 filter-json。需要真正的分组统计时优先用 record pivot。worksheet chart：在工作表上建一个图表配置（不是即时取数）。用 --report-type（整数图表类型）+ --spec-json（含 xaxes/yaxisList/filter 等）。建图表多数时候属于"改应用"，可交给 hap-cli-app-editor；纯取数分析用 record pivot 更直接。先看 hap worksheet record bottom-stats --help / hap worksheet chart --help 再用。
照这些规则写，绝大多数查询一次就成：
field 用 controlId 或别名，不用中文字段名（用 worksheet fields 查）。ge/le/isempty/notin…），不要套用工作流/视图那套拼写。isempty/isnotempty）不带 value。record list / record pivot 的分页 -p、-n 都必填；record pivot 还必须带 --view-id。--use-field-id-as-key；成员/关联字段是对象数组，取其中的 fullname / name。--filter-json "$(cat f.json)"。hap config log on 后再跑命令，可在日志里看到真正发出的请求体。HAP 应用物理搭建调度器。读取 hap-plan.json，逐步调度 steps/*.md 完成所有 HAP 对象的创建与配置。支持 subagent 委派和内联执行双模式。
全自动一站式 HAP 应用构建器。从业务方案设计（Plan）开始，确认后自动物理搭建（Build）。若已存在方案，可直接一键继续/恢复物理搭建。用户输入 /hap-builder 或直接用对话描述您的系统诉求（如"帮我搭建一个客户管理应用"）触发。
用 hap 命令行工具（CLI）修改一个已存在的 HAP 应用里的某个具体元素时用本 skill。只要用户说「在某表加个字段」「把这个视图改名」「修改工作流」「给某角色加权限」之类、针对已有应用做单点局部修改，就触发。不触发：增删改业务记录、查询数据、写调 hap 的代码；从零搭整个新应用请改用 hap-mcp-app-builder。
用 hap-cli 命令行工具操作 HAP 企业平台，是 hap-cli skills 的主入口。覆盖通讯录、聊天消息、发动态、管日程，以及应用与数据操作（工作表记录增删改查、工作流、审批待办、自定义页面、角色权限、文件上传等）。只要用户想在 HAP 里查人、发消息、发动态、看/建日程、读写某张表的记录、处理审批，即使没明说工具名也应触发。
HAP 应用方案设计。根据用户业务需求生成完整的方案总览与结构化 JSON，确认后自动触发物理搭建。由根 SKILL.md 路由调用。
**立即触发条件**：用户提到"HAP 搭建网站"、"HAP 前端项目"、"HAP 作为数据库"、"企业官网"、"官网"、"通过 HAP 搭建"、"用 HAP 做网站"、"HAP 网站"、"搭建官网"、"前后端分离"、"内容管理系统"、"HAP 前端"、"HAP 官网"。提供完整的 HAP + 前端项目搭建指南，包括 HAP 后台配置、前端项目结构、API 集成和数据渲染。