@qingflow-tech/qingflow-cli 1.1.51 → 1.1.53

package/skills/qingflow-cli/reference/builder/README.md

@@ -38,7 +38,7 @@ Rules:
 - Portal chart sections use one `chart` field: `{"chart_id":"..."}` to reuse an existing QingBI chart, or `{"app_key":"...","name":"...","chart_type":"...",...}` to create/update the needed chart inline.
 - Buttons are part of the view design: declare them in the target view with `action_buttons`.
 - Update instructions live inside the resource document. Do not use `update-*` as a separate main route.
-- Batch read, batch write, and patch are resource-specific variants, not separate workflows.
+- Batch read, batch write, and patch are resource-specific variants, not separate workflows. View writes are single-operation: `builder views apply` handles one view per call; consult [50-views.md](./50-views.md) before preparing multiple view changes.
 
 ## File responsibilities
 

package/skills/qingflow-cli/reference/builder/reference/app-delivery-sop.md

@@ -41,7 +41,7 @@
 这些不是独立流程，而是读、写、改三个动作的多资源形态：
 
 - **批量读**：读多个应用时优先用 `--app-keys`，例如 `builder app get --app-keys a,b fields`、`builder app get --app-keys a,b views`、`builder button get --app-keys a,b`、`builder associated-resource get --app-keys a,b`、`builder publish verify --app-keys a,b`。读结果同时看成功项和 `errors[]`，不要因单个应用失败否定全批。
-- **批量写**：视图、按钮、关联资源和报表按各自资源契约使用对应的批量文件；应用表单不走 `apps-file`，而是每个应用独立提交完整 AppForm 声明。
+- **批量写**：仅在资源契约明确支持时使用批量文件；视图例外，`builder views apply` 每次只提交一个视图的一种操作，不支持多视图批量创建或把 upsert/patch/remove 混在一次调用中。应用表单不走 `apps-file`，而是每个应用独立提交完整 AppForm 声明。
 - **局部改**：只改已存在资源的少量参数时用对应 patch 文件；`patch_*` 内只写目标定位字段和 `set/unset`，不要用不完整 `upsert_*` 伪装局部更新。
 
 ---
@@ -201,8 +201,8 @@ qingflow builder schema apply \
 - 如果返回 `MULTI_APP_STATIC_VALIDATION_FAILED`，读取 `details.issues[]` 的 `path/error_code/fix_hint` 修 payload；这是写入前失败，通常可以修正后重试，不需要 readback。
 - 多应用 schema apply 不做事务回滚；如果部分失败，只补失败的 `apps[].row_number`，不要整批重复提交。
 - 这个模式只负责应用壳与字段；视图、按钮、关联资源、报表仍拿返回的 `app_key` 继续走各自 apply 工具。
-- `target_app_ref`、`as_data_title`、`display_field` 等只属于旧载荷。迁移时将关系改写为 AppForm `config.targetAppKey`、`config.displayField`、`config.visibleFields`，并使用已确认的真实 app key。
-- 历史 schema adapter 写入后可读 `details.relation_readback_matrix[]`：逐项核对旧 `target_app_key`、`relation_mode`、`display_field`、`visible_fields`。迁移到当前 AppForm 后，改为读取 draft/published form 的 `config.targetAppKey`、`config.relationMode`、`config.displayField`、`config.visibleFields`，不要提交旧 `update_fields` patch。
+- `target_app_ref`、`as_data_title`、`display_field` 等只属于旧载荷。迁移时将关系改写为 AppForm `config.targetAppKey`、`config.displayFields[]`（含 `auth`）、`config.twoWayBoundField`，并使用已确认的真实 app key。
+- 历史 schema adapter 写入后可读 `details.relation_readback_matrix[]`：逐项核对旧 `target_app_key`、`relation_mode`、`display_field`、`visible_fields`。迁移到当前 AppForm 后，改为读取 draft/published form 的 `config.targetAppKey`、`config.relationMode`、`config.twoWayBoundField`、`config.displayFields[]`，不要提交旧 `update_fields` patch。
 - 一个应用可以包含多个 `relation` 字段；不要因为 relation 数量超过 1 就降级成文本。若真实写入失败或 relation readback mismatch，只按实际错误和 `details.relation_repair_plan[]` 做最小修复。
 - 完整系统遇到超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或 readback 不完整时，先按 §3.4 读回，不要直接拆成单应用创建。
 
@@ -349,7 +349,7 @@ qingflow builder flow apply \
 | **`address`** | 地址复合字段。 |
 | **`attachment`** | 附件。 |
 | **`boolean`** | 是否。 |
-| **`relation`** | 旧载荷使用 `target_app_key` / `target_app_ref`；当前 AppForm 使用 `config.targetAppKey`、`config.relationMode`、`config.displayField`、`config.visibleFields`。 |
+| **`relation`** | 旧载荷使用 `target_app_key` / `target_app_ref`；当前 AppForm 使用 `config.targetAppKey`、`config.relationMode`、`config.twoWayBoundField`、`config.displayFields[]`。 |
 | **`subtable`** | 当前 AppForm 使用 `subfields[]` 及 Schema 返回的 camelCase 配置；旧 `subfield_updates` 只作迁移线索。 |
 | **`q_linker`** | 当前 AppForm 使用 `config.qLinkerBinding`，其 `outputs[].targetField` 必须按字段 Schema 配置。 |
 | **`code_block`** | 当前 AppForm 使用 `config.codeBlockBinding`，其 `outputs[].targetField` 必须按字段 Schema 配置。 |
@@ -374,14 +374,14 @@ qingflow builder flow apply \
 
 后端很多保存接口仍是整份配置保存，但新版 CLI/MCP 对外提供 **public partial patch**：
 
-- 已有视图：`builder views apply --views-file`，其中对应项写 `operation: "patch"`
+- 已有视图：`builder views apply --app-key APP_KEY --patch-views-file PATH`，文件只放一项，写 `view_key`/`name` 与 `set`/`unset`
 - 已有按钮：`builder button apply --patch-buttons-file`
 - 已有关联资源：`builder associated-resource apply --patch-resources-file`
 - 已有报表：`builder charts apply --patch-file`
 - 已有流程节点：`builder flow apply --patch-nodes-file`
 - 已有门户组件：`builder portal apply --patch-sections-file`
 
-局部更新的语义是：你只写要替换的参数，工具内部读取当前配置、补齐后端必填字段，再整份保存。每个 patch 项直接使用对象真实定位字段 + `set` / 可选 `unset`，不要写字面量 `selector` key。示例：`{"operation":"patch","app_key":"APP_KEY","view_key":"VIEW_KEY","set":{"query_conditions":{...}}}`、`{"button_id": 1001, "set": {"button_text": "新名称"}}`、`{"associated_item_id": 123, "set": {"match_mappings": [...]}}`、`{"chart_id": 456, "set": {"name": "新报表名"}}`、`{"id": "node_1", "set": {"name": "主管审批"}}`、`{"chart": {"chart_key": "xxx"}, "set": {"rows": 7}}`。
+局部更新的语义是：你只写要替换的参数，工具内部读取当前配置、补齐后端必填字段，再整份保存。每个 patch 项直接使用对象真实定位字段 + `set` / 可选 `unset`，不要写字面量 `selector` key。示例：`{"view_key":"VIEW_KEY","set":{"query_conditions":{...}}}`、`{"button_id": 1001, "set": {"button_text": "新名称"}}`、`{"associated_item_id": 123, "set": {"match_mappings": [...]}}`、`{"chart_id": 456, "set": {"name": "新报表名"}}`、`{"id": "node_1", "set": {"name": "主管审批"}}`、`{"chart": {"chart_key": "xxx"}, "set": {"rows": 7}}`。
 
 `upsert_*` 用于创建或提供完整目标配置；不要只给 `name/type/query_conditions` 这类局部片段然后期待后端自动合并。
 

package/skills/qingflow-cli/reference/core/QINGFLOW_CLI_ADMIN_CHEATSHEET.md

@@ -43,7 +43,7 @@
 
 ## 4. 记录数据
 
-与 **[成员速查](./QINGFLOW_CLI_MEMBER_CHEATSHEET.md)** 及 **[SKILL.md](../../SKILL.md)**「命令速查」一致：`record schema browse`、`record list`、`record access` **必须** `--view-id`。查询类遵守 **SKILL 落盘**：`record list`、`get`、`access`、`schema browse` 等。最终统计结论、分析报告、趋势/排名/比例/分布统一使用 **[record/analysis](../record/analysis/README.md) 的 `record access -> Python/pandas`**。
+与 **[成员速查](./QINGFLOW_CLI_MEMBER_CHEATSHEET.md)** 及 **[SKILL.md](../../SKILL.md)** 一致：直接数据操作使用 [data 操作说明](../data/README.md)；最终统计结论、分析报告、趋势/排名/比例/分布统一使用 **[record/analysis](../record/analysis/README.md) 的 `data query --all --output csv -> Python/pandas`**。
 
 ---
 

package/skills/qingflow-cli/reference/core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md

@@ -1,139 +1,120 @@
-# Qingflow CLI：获取数据工作流（应用记录）
+# Qingflow CLI：应用数据查询工作流
 
-> **用途**：使用当前 CLI 会话，从「选定应用」到「读懂列含义 + 样本/模糊定位 / 单条详情」的**推荐闭环**；下表 **左列**可与常见 **编排/内部接口**命名对照，**右列**仅为本 CLI 命令。
-> **新版口径**：`record_list` 不是批量分析入口，而是样本浏览和模糊定位入口；`record_get` 是前端详情页首屏上下文入口；全量日志用 `record logs`；分析取数统一转 [record/analysis](../record/analysis/README.md) 的 `record access -> Python/pandas`。
-> **关联**：权限、`view_id` 选取雷区、成员最短路径速查见 **[QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./QINGFLOW_CLI_MEMBER_CHEATSHEET.md)**；**字段 `kind` / 数据类型**见 **[QINGFLOW_CLI_FIELD_DATA_TYPES.md](./QINGFLOW_CLI_FIELD_DATA_TYPES.md)**；**新建记录**见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](../record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**；**更新记录**见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](../record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**；最终统计结论统一使用 **[record/analysis](../record/analysis/README.md) 的 `record access -> Python/pandas`**；主技能规则见 **[../SKILL.md](../../SKILL.md)**。
+> **用途**：使用视图无关的 `data query/get` 完成普通应用数据查询、筛选、排序、分页和单条读取。
+> **边界**：本文只给流程与 JSON 形状；操作符、字段类型、权限范围和动态限制以当前 `--help`、`schema`、`field_capabilities`、`access` 与 `hints` 为准。
+> **record 专项**：需要完整日志、附件／图片上下文时，阅读 [record 专项参考](../record/QINGFLOW_CLI_RECORD_SPECIALIZED_WORKFLOW.md)。
 
----
-
-## 概念步骤 → CLI 映射
-
-| 习惯概念名（编排/文档） | CLI 等价命令 | 必填要点 |
-| --- | --- | --- |
-| `app_get`（列应用内可访问视图） | `qingflow --json app get --app-key <APP_KEY>` | 从返回体的 **`data`（若存在）** 内取 `accessible_views[]` |
-| `record_schema_get`，`schema_mode=browse` | `qingflow --json record schema browse --app-key <APP_KEY> --view-id <VIEW_ID>` | 子命令 **`browse`** 即「浏览视图」表结构 |
-| `record_list` | `qingflow --json record list --app-key <APP_KEY> --view-id <VIEW_ID> [--query 文本] [--query-field FIELD_ID] [--page-size N]` | 样本浏览 / 模糊定位，默认最多返回 10 条；`query_fields` 是全文搜索字段范围 |
-| `record_get` | `qingflow --json record get --app-key <APP_KEY> --record-id <RECORD_ID> [--view-id <VIEW_ID>]` | 前端详情页首屏上下文：字段、首屏日志、引用、关联资源、图片与文件资产 |
-| `record_logs_get` | `qingflow --json record logs --app-key <APP_KEY> --record-id <RECORD_ID> [--view-id <VIEW_ID>]` | 单条记录全量可见数据日志 + 流程日志；自动分页写本地 JSONL，响应只返回摘要和文件路径 |
-
-**补充**：若尚未持有 `APP_KEY`，先做 `qingflow --json app list [--query <关键词>]`，在 `items[].app_key` 里选应用；带 `--query` 时读取 `matched_count` / `unfiltered_count` 判断是否命中。
-
----
-
-## 推荐执行顺序
+## 推荐顺序
 
 ```text
-app get（解析 accessible_views，选定 VIEW_ID）
-  → record schema browse（对齐字段 id/类型/展示名；也是 list/access/get 的视图字段口径）
-  → record list（样本浏览或 query 模糊定位候选）
-  → （可选）record get（对单条 record_id 拉详情页首屏上下文）
-  → （可选）record logs（需要完整审计日志时再拉全量日志 JSONL）
+data query（默认带 schema）
+  → 从 schema / field_capabilities 定位 field_id 与能力
+  → 按需追加 columns / where / sort
+  → 根据 records.has_more 与 hints 继续分页或收窄范围
+  → 已知 record_id 时按需 data get
 ```
 
-- **仅当你只需要「快速确认有无数据」**时，可以省略 `schema browse`，直接 `app get` → `record list`（与成员速查表「最短路径」一致）。
-- **当你需要稳定映射列名、写过滤条件或对接自动化**时，应按上表**显式**走 `schema browse`，避免对着 `list` 里中文列名猜字段定义。
-- **当用户只给出模糊信息定位单条数据**时，走 `record schema browse` 确认可搜索字段，再用 `record list --query ... --query-field ...` 返回候选；只有候选明确后才 `record get`。
-- **需要分组/聚合统计、最终统计结论、分析报告、趋势/排名/比例/分布**时，必须按 **[record/analysis](../record/analysis/README.md)** 执行 `app get -> record schema browse -> record access -> Python/pandas -> final answer`。
+已知 `app_key` 时直接 query；未知时只做必要的 `app list --query`。不要先执行 `app get → record schema browse`，普通数据查询也不需要 `view_id`。
 
----
-
-## 命令模板（占位符替换即可）
-
-**1）应用与视图**
+## 1. 首次查询与字段能力
 
 ```bash
-qingflow --json app get --app-key <APP_KEY> > tmp/qingflow_app_get.json
+mkdir -p tmp
+qingflow --json data query --app-key APP_KEY \
+  > tmp/qingflow_data_query.json
 ```
 
-从 `tmp/qingflow_app_get.json` 解析：`$.data.accessible_views`（无 `data` 时再试顶层 `accessible_views`）。每个元素含 `view_id`、`name`、`kind` 等。
+首次查询保留默认 schema。响应重点读取：
 
-若响应 `warnings[]` 含 `CUSTOM_VIEW_LIST_UNAVAILABLE`，表示 custom view 列表读取被权限或后端限制降级；这不是应用整体不可读。优先使用已返回的 `system:*` 视图继续 `schema browse` / `record list`，或从前端 URL 的 `viewgraphKey` 补充明确 `view_id`。
+- `records.items[]`：当前页记录；
+- `records.page/page_size/has_more`：分页状态；
+- `schema`：字段 id、标题与结构；
+- `field_capabilities`：筛选、排序和写入能力；
+- `access`：本次实际访问范围；
+- `hints`：需要收窄、继续、停止或调整参数的动态提示。
 
-**2）浏览视图表结构（= `record_schema_get` browse）**
+不要用 insert/update 探测字段能力，也不要从 record schema 推断 data 能力。
 
-```bash
-qingflow --json record schema browse \
-  --app-key <APP_KEY> \
-  --view-id <VIEW_ID> \
-  > tmp/qingflow_schema_browse.json
-```
+## 2. 字段筛选
 
-实跑样例响应顶层键包含：`status`、`app_key`、`schema_scope`、`fields`、`suggested_dimensions` 等（**以实际 JSON 为准**）。
+从首次响应中准确定位目标 `field_id`，并确认该字段 `filter_operators` 中存在所需 `op`、值符合 `value_shape`。例如：
 
-**3）记录列表**
+```json
+[
+  {"field_id": 101, "op": "eq", "value": "已完成"}
+]
+```
 
 ```bash
-qingflow --json record list \
-  --app-key <APP_KEY> \
-  --view-id <VIEW_ID> \
-  > tmp/qingflow_records.json
+qingflow --json data query \
+  --app-key APP_KEY \
+  --where-file tmp/where.json \
+  > tmp/qingflow_data_filtered.json
 ```
 
-列表默认最多返回 10 条，行数据常见于 `$.data.items`；每条一般有 `record_id`（及业务字段键值）。需要调整样本量时加 `--page-size <N>`；它只影响浏览/候选定位样本，不替代分析取数。响应会给出总数/下一步建议；如果是模糊定位，优先看 `lookup.total_count`、`lookup.next_action`。
+本文示例不代表完整操作符矩阵；真实能力只认当前响应。
 
-`record_list.data.items[]` 是**字段平铺行对象**，不是 `fields[]` 数组。定位候选或做名称到记录 ID 映射时直接读字段标题键：
+## 3. 排序
 
-```python
-rows = payload["data"]["items"]
-name_to_record_id = {row["客户名称"]: row["record_id"] for row in rows}
+只对 `sort_supported=true` 的字段构造排序：
+
+```json
+[
+  {"field_id": 102, "direction": "desc"}
+]
 ```
 
-只有 `record_get` 详情使用 `fields[]` 来表示字段列表。
+```bash
+qingflow --json data query \
+  --app-key APP_KEY \
+  --sort-file tmp/sort.json \
+  > tmp/qingflow_data_sorted.json
+```
 
-**模糊定位示例**：
+## 4. 分页
 
 ```bash
-qingflow --json record list \
-  --app-key <APP_KEY> \
-  --view-id <VIEW_ID> \
-  --query "北京和路元" \
-  --page-size 20 \
-  --query-field 6299262 \
-  > tmp/qingflow_record_lookup.json
+qingflow --json data query --app-key APP_KEY --page 1 --page-size 100 \
+  > tmp/qingflow_data_page_1.json
 ```
 
-`--query-field` 对应 `record_browse_schema_get.fields[].field_id`，表示后端全文搜索范围；它不是输出列控制。
-
-**4）单条记录详情**
+仅当 `records.has_more=true` 时请求下一页，并继续读取 `hints`：
 
 ```bash
-qingflow --json record get \
-  --app-key <APP_KEY> \
-  --record-id <RECORD_ID> \
-  --view-id <VIEW_ID> \
-  > tmp/qingflow_record_get.json
+qingflow --json data query --app-key APP_KEY --page 2 --page-size 100 \
+  > tmp/qingflow_data_page_2.json
 ```
 
-已知前端视图时必须传同一个 `--view-id`；未知时 CLI 会先试默认详情 route，再在权限/不可见类错误下尝试可访问视图。`record_get` 现在返回详情页首屏上下文，重点看：`fields[]`、`references[]`、`data_logs`、`workflow_logs`、`associated_resources`、`media_assets`、`file_assets`、`semantic_context`。其中 `data_logs` / `workflow_logs` 只表示详情页首屏日志，不是全量审计历史。若 `unavailable_context[]` 中出现 `detail_schema`、`audit_info`、`data_logs`、`workflow_logs` 等，只说明这些辅助详情上下文读取受限；只要顶层 `status=ok` 且 `fields[]` 有目标字段，就不要把辅助 40002 当作记录不可读。图片读 `media_assets.items[].local_path`；文档/表格/PDF 等附件读 `file_assets.items[].local_path` 和 `file_assets.items[].extraction.text_path`。**不要直接访问远端 Qingflow 附件 URL**。
+不要只按 `total/page_size` 猜测完整性；若 hints 要求收窄范围或响应说明结果不完整，先按提示处理。
+
+## 5. 单条读取
 
-**5）全量日志（仅在用户明确需要完整审计/日志历史时）**
+从 query 得到明确 `record_id` 后，按需读取单条：
 
 ```bash
-qingflow --json record logs \
-  --app-key <APP_KEY> \
-  --record-id <RECORD_ID> \
-  --view-id <VIEW_ID> \
-  > tmp/qingflow_record_logs.json
+qingflow --json data get --app-key APP_KEY --record-id RECORD_ID \
+  > tmp/qingflow_data_get.json
 ```
 
-响应重点看：`data_logs.local_path`、`workflow_logs.local_path`、`items_count`、`pages_fetched`、`complete`、`context_integrity.safe_for_full_log_conclusion`。完整日志在本地 JSONL 文件中，默认目录为 `~/.qingflow-mcp/record-logs/<run_id>/`；不要把 JSONL 全文直接塞进上下文，按需用脚本读取、筛选或汇总。
+`data get` 用于普通单条业务数据。若用户需要详情页附件、图片或完整数据／流程日志，切换到 record 专项，不要把它们误写成 data get 的默认合同。
 
----
+## 6. 统计分析
 
-## `view_id` 选取（成员侧必读摘要）
+最终统计结论、分布、比例、排名和趋势使用：
 
-- **`system:all` 等业务系统视图**：实跑可用于 `schema browse` + `record list`（具体以租户配置为准）。显式传入的 `view_id` 必须按前端当前视图忠实执行；`system:all` 报 40002 / 40027 / 404 / 500 时，不要自动换成 `system:initiated`、`system:todo` 等其它系统视图，除非用户或前端 URL / `app get.accessible_views` 重新指定了那个视图。
-- **`CUSTOM_VIEW_LIST_UNAVAILABLE`**：只说明 `app get` 没能列出 custom view；若已有 `system:*` 可用，不要把它当作应用或记录读取失败。
-- **`custom:` 后仅数字**（如 `custom:1`）：成员侧常见 **`schema browse` / `list` / `access` 均 40038**，应**跳过**，改选 **`custom:` 带字母后缀**或其它可用视图（详见成员速查表「先有通路、再要有数据」）。
-- **待办 / 已办 / 抄送「任务箱」**：不要用旧文档里的 `system:todo` 等视图充当任务中心；应使用 **`task list --task-box …`**（见主技能 **待办 SOP**）。
-
----
-
-## 落盘与解析
+```bash
+qingflow --json data query \
+  --app-key APP_KEY \
+  --where-file tmp/where.json \
+  --all --output csv \
+  > tmp/qingflow_data_analysis.json
+```
 
-- `schema browse`、`record list`、`record get`、`record logs` 体量大时，**必须**重定向到文件，勿将整段 JSON 直接塞进 LLM 上下文（规则见主技能「输出落盘规则」）。`record_get` 下载的本地图片/文件路径可以再交给图片理解、文档解析或 Python 读取；`record logs` 的全量日志读 `*.jsonl` 文件。
-- 解析前**先 unwrap `data`**：多数业务成功响应为 `{ "data": { ... } }`，与 `schema browse` 部分字段在顶层的形态可能不同，以每次响应为准。
+读取全部 `files[].local_path` 后再用 Python/pandas 分析。只有 `complete=true`、`truncated=false`、`safe_for_final_conclusion=true` 时，才能形成完整总体结论；详见 [数据分析说明](../record/analysis/README.md)。
 
----
+## 落盘与错误处理
 
-*维护：CLI 升级后请用 `qingflow record schema browse -h`、`qingflow record list -h`、`qingflow record get -h`、`qingflow record logs -h` 复核选项名；概念名 `record_schema_get` / `schema_mode=browse` 在 CLI 中固定对应子命令 `record schema browse`。*
+- query/get 的 JSON 与分析摘要必须落盘，只解析所需键；CSV 读取本地文件路径，不打印全文。
+- 参数错误按当前 `qingflow data ... --help` 修正。
+- 权限、范围和字段错误按响应说明处理；data 失败时不得自动改用 record 查询绕过限制。
+- CLI 升级后用 `qingflow data --help`、`qingflow data query --help`、`qingflow data get --help` 复核。

package/skills/qingflow-cli/reference/core/QINGFLOW_CLI_EXPLORATION_REPORT.md

@@ -6,11 +6,11 @@
 
 ## 1. 当前能力树摘要
 
-- 顶层：`qingflow {auth|workspace|app|portal|view|chart|record|import|export|task|builder|build} ...`
+- 顶层数据操作目标入口为 `data query/get/insert/update/delete`；发布前必须以当前真实 package 的 `qingflow data --help` 复核可用性。
 - `builder` 与 `build` 等价；默认写法仍推荐 `builder`。
 - `record schema`：公开主路径为 `browse`、`insert`、`update`、`import`、`code-block`；`applicant` 仅为兼容保留入口，不作为推荐链路。
 - `record` 公开执行入口：`list`、`access`、`get`、`logs`、`insert`、`update`、`delete`、`code-block-run`。
-- 最终统计结论统一按 [record/analysis](../record/analysis/README.md) 走 `record access -> Python/pandas`，不要寻找或使用其它聚合捷径。
+- 最终统计结论统一按 [record/analysis](../record/analysis/README.md) 走 `data query --all --output csv -> Python/pandas`，不要寻找或使用其它聚合捷径。
 
 ---
 
@@ -37,13 +37,15 @@
 | 入口 | 当前定位 |
 | --- | --- |
 | `record list` | 样本浏览 / 模糊定位候选；默认最多返回 10 条，返回 `data.pagination.total_count`，带 `--query` 时看 `lookup.total_count` 与 `lookup.next_action` |
-| `record access` | 默认分析取数入口；自动分页写本地 CSV；不暴露 `page/page_size/limit/max_rows/profile` |
+| `record access` | 旧 CLI 非默认兼容入口；不得作为分析默认链或 data query 失败后的自动回退 |
 | `record get` | 前端详情页首屏上下文；字段、引用、首屏数据日志、首屏流程日志、关联资源、`media_assets`、`file_assets` |
 | `record logs` | 单条记录全量可见数据日志 + 流程日志；自动分页写本地 JSONL，响应给路径和完整性 |
 | `record insert` | 批量 `items` JSON；单条也是 `items` 数组一行；CLI 用 `--items-file` |
 | `record update` | 单条 `--record-id + --fields-file` 或批量 `--items-file`；不要混用 |
 
-`record_get` 下载到本地的图片读 `media_assets.items[].local_path`；文档、表格、PDF 等读 `file_assets.items[].local_path` 与 `extraction.text_path`。不要直接访问远端 Qingflow 附件 URL。
+直接 query/get/insert/update/delete 统一阅读 [data 操作说明](../data/README.md) 并使用对应 data 工具。最终分析使用 `data query --all --output csv`，按真实响应的 `files[].local_path` 读取全部 CSV 分片。
+
+`record_get` 下载本地附件的规则仅适用于用户明确要求旧 CLI 兼容入口的场景。
 
 ---
 

package/skills/qingflow-cli/reference/core/QINGFLOW_CLI_FIELD_DATA_TYPES.md

@@ -1,16 +1,16 @@
 # Qingflow CLI：字段数据类型（Schema / 列表 / 写入）
 
-> **用途**：说明 **`record schema …`** 的 **`fields[]`**、**`record list` / `record get` / `record access`** 行内值、以及 **insert/update 写入 payload** 的常见对应关系；并单独说明 **选项联动、关联记录、引用填充、公式/系统题、AI 与受限类型** 等在 CLI 下的表现与处置。
-> **依据**：当前 CLI 在 **`--json`** 下会对 **schema** 响应做 **裁剪**：通常只保留本节列出的键；**`kind`** 由内部写入类别归并而来（见下表）。**`que_type` 等若未出现在输出中**，以 **`kind` + 实跑预检** 为准。
-> **关联**：写入值细节与成员/部门见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](../record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**；更新流程见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](../record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**；只读见 **[QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**；**搭建侧** AppForm 的 `type`（与本文 `kind` 命名体系不同）及其 CLI 命令见 **[30-schema-fields.md](../builder/30-schema-fields.md)**；主技能 **[../SKILL.md](../../SKILL.md)**。
+> **用途**：普通数据查询、读取和写入默认使用 **[data 操作说明](../data/README.md)**，先读取 `data query/get` 返回的 **`schema + field_capabilities`**，再按 `data insert/update` 的字段能力构造值。本文保留旧 `record` 字段形态，供用户明确要求兼容旧命令时参考。
+> **依据**：当前 data 合同以 `field_id`、`filter_operators`、`value_shape`、`write_kind`、`insertable` 和 `updatable` 为事实源；运行时字段错误仍是最终结果。旧 `record schema` 的精简 `kind` 不得代替该合同。
+> **关联**：默认数据操作见 **[data 操作说明](../data/README.md)**；旧 record 写入值细节与成员/部门见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](../record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**，更新流程见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](../record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**；**搭建侧** AppForm 的 `type` 见 **[30-schema-fields.md](../builder/30-schema-fields.md)**；主技能 **[../SKILL.md](../../SKILL.md)**。
 
 ---
 
-## 1. `fields[]` 通用结构（`--json` 精简后）
+## 1. 旧 record `fields[]` 兼容结构（`--json` 精简后）
 
 | 字段 | 含义 |
 |------|------|
-| **`field_id`** | 内部题 id（数字）；**`record_access.columns` / `where-file` / `order-by-file` 等 DSL** 常以此引用列。 |
+| **`field_id`** | 内部题 id（数字）；data query 的 `columns` / `where` / `sort` 以此引用列。 |
 | **`title`** | 题目标题；insert/update 的 `fields` map 键通常与之一致。 |
 | **`kind`** | 见 **§2 `kind` 枚举**；决定读写时值的形态。 |
 | **`options`** | 可选；**`kind=select`** 时常为允许选项的字符串列表。 |
@@ -20,13 +20,13 @@
 | **`required`** | 部分场景（如 **`record schema update`** 拆出的 `required_fields` / `optional_fields`）出现。 |
 | **`template`** | 少数响应里与 **`payload_template`** 联动出现，供生成初稿。 |
 
-**browse 与 detail**：`browse` 产出视图表头的精简 **`fields[]`**；`record get` 产出当前记录详情字段。一般 **不含** 完整 **`que_type`/`writable`** 元数据。更新主链路先用 **`record get`** 的字段信息组 payload，再执行 **`record update`**；只有更新失败、字段歧义或需要诊断可写范围时，再结合 **`record schema update`**（按记录）或写入返回判断。
+**兼容说明**：旧 `browse` 产出视图表头的精简 **`fields[]`**，旧 `record get` 产出记录详情字段，一般 **不含** 完整 **`que_type`/`writable`** 元数据。普通数据操作不要据此猜测字段能力；应读取 data 返回的 `schema + field_capabilities`。
 
 ---
 
 ## 2. `kind` 枚举（CLI 对外）
 
-内部写入类别经归并后形成下表 **`kind`**（与 `qingflow` 当前实现一致；升级后请以 **`record schema … --json` 实跑** 为准）：
+旧 record 内部写入类别经归并后形成下表 **`kind`**；本表仅用于显式兼容旧命令，不是普通 data 操作的能力事实源：
 
 | CLI `kind` | 维护侧常见内部类别（参考） | 在 `record list` / `record get` / `record access` 中（常见） | insert/update 写入值 |
 |------------|-----------------------------------|--------------------------------------------|----------------------------------|
@@ -110,20 +110,20 @@
 ## 4. 与 `field_id` / 列选择
 
 
-- **`record list --column`**：参数为 **数字列 id**，用于样本/候选列表展示列，须与 **`fields[].field_id`** 一致。
-- **`record get`**：默认读取前端详情页首屏上下文；不要把 `--column` 当成详情字段投影主路径，单条字段、首屏日志、引用、图片/文件资产以 `record_get` 的结构化上下文为准。若用户要完整数据日志/流程日志历史，用 `record logs`。
+- **`data query --columns-file`**：列投影使用数字 `field_id`，并与 `schema`、`field_capabilities` 对照。
+- **`data get`**：按记录 id 读取普通数据详情；需要日志、引用或资产等旧专用上下文时，才显式使用相应 record 命令。
 - **标题重复**：同一 `title` 可能对应多个 `field_id`（极少见）；列表 DSL 应用 **`field_id`** 消歧。
 
 ---
 
 ## 5. 读者操作建议
 
-1. **按场景取上下文**：只读/定位视图列用 `record schema browse --view-id …`；新建用 `record schema insert --app-key …`；更新用 `record get --record-id …` 先读当前记录详情，再用 `record update` 写入；`record schema update --record-id …` 只在失败、字段歧义或显式诊断时使用。
-2. **数据分析**：最终统计结论、分析报告、趋势/排名/比例/分布必须走 **[record/analysis](../record/analysis/README.md) 的 `record access -> Python/pandas`**。
+1. **按场景取上下文**：普通查询和读取用 `data query/get`，新建和更新用 `data insert/update`；先检查返回的 `access` 与 `field_capabilities`。旧 record 命令只在用户明确要求兼容能力时使用。
+2. **数据分析**：最终统计结论、分析报告、趋势/排名/比例/分布必须走 **[record/analysis](../record/analysis/README.md) 的 `data query --all --output csv -> Python/pandas`**。
 3. **看 `kind` + `options` / `row_fields` / `target_app_key`**，并对照 **§3 特殊字段** 判断是否存在联动、引用或只读带出。
 4. **选项联动 / 引用带出**：先写 **驱动题**，再写 **被带出的题**；只读带出列 **不要强写**。
-5. **写入前缩小 payload**；insert 默认用 `record insert --items-file`，单条也是 `items` 数组一行。根据 **`status` / `blockers` / `field_errors` / `failed_fields` / `created_record_ids`** 迭代（`--json` 在 stdout）。
+5. **写入前缩小 payload**；`data insert --items-file` 的单条输入也是数组中的一个 item。根据 **`write_executed` / `retry_safe` / `field_errors` / `hints`** 迭代（`--json` 保持无损）。
 
 ---
 
-*维护：`kind` 集合与精简字段以当前 CLI 的 `record schema … --json` 实跑为准；内部 `que_type` 枚举随轻流版本变化，文档只稳定描述对外 **`kind`** 桶。*
+*维护：普通数据操作以 data 返回的字段能力为准；旧 record 的 `kind` 与内部 `que_type` 仅作兼容参考。*

package/skills/qingflow-cli/reference/core/QINGFLOW_CLI_MEMBER_CHEATSHEET.md

@@ -1,31 +1,31 @@
 # Qingflow CLI 普通成员命令速查表
 
 > **适用对象**：当前会话为 **普通/基本成员**（`permission_level` 非租户/应用管理员、`import_capability` 常为无导入权等）。Wingent Momo runtime 下不要先跑 `auth whoami`；只有业务失败、账号不确定或排障时才核对身份。
-> **与主技能关系**：请以 **[SKILL.md](../../SKILL.md)**（本目录上一级）的规则与命令速查表为准。**本表**：成员侧最短读数与高概率通路；**租户/管理员向差异**请参阅同目录 **[QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./QINGFLOW_CLI_ADMIN_CHEATSHEET.md)**。
+> **与主技能关系**：请以 **[SKILL.md](../../SKILL.md)**（本目录上一级）的规则与命令速查表为准。普通查询、读取和写入默认阅读 [data 操作说明](../data/README.md)；本文保留的旧 `record` 命令只供用户明确要求兼容入口时查阅。**租户/管理员向差异**请参阅同目录 **[QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./QINGFLOW_CLI_ADMIN_CHEATSHEET.md)**。
 > **可选补充**：同一目录 **[QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md](./QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md)** 收录 **全体角色通用**的子命令逐项模板（与本文分工：本文偏「成员能跑通的策略」，ONE_SHOT 偏「参数逐项闭合示例」）。
 
 > **实证**：以下结论以会话内 `qingflow …` 为准；换账号/环境请以 `qingflow … -h` 与必要的身份核对结果为准。
 
 **统一习惯**
 
-- **只读拉取表单记录的最短链路**：见本节 **「最短路径：普通成员只读记录数据」**（可省略 `schema browse`）。**需先拉浏览视图表结构**时见 **[QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**；最终统计结论统一使用 **[record/analysis](../record/analysis/README.md) 的 `record access -> Python/pandas`**；**字段 `kind` / 数据形态**见 **[QINGFLOW_CLI_FIELD_DATA_TYPES.md](./QINGFLOW_CLI_FIELD_DATA_TYPES.md)**；**新建记录默认批量 JSON 链路**见 **[record/insert](../record/insert/README.md)**（CLI 为 `record insert --items-file`，成员/部门/关联优先自然语言）；**浏览视图下更新记录**见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](../record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**。
+- 直接查询、读取、新增、更新或删除使用 [data 操作说明](../data/README.md)，权限范围、字段 schema 和写入结果以 data 工具当次响应为准；最终统计结论统一使用 **[record/analysis](../record/analysis/README.md) 的 `data query --all --output csv -> Python/pandas`**；批量导入阅读导入 SOP。
 - 避免无必要地先绕 `workspace`、`view get`。
 - 加 `--json`，便于区分 **CONFIG_ERROR**（少参）与 **backend**（权限/业务）。
 - `app get` / `portal list` 等业务体常在 `**{ "data": { ... } }`** 里：取 `accessible_views`、`items` 前先 unwrap `data`。
 
 ---
 
-## 最短路径：普通成员「只读记录数据」
+## 最短路径：普通成员使用 data 查询
 
-> **目标**：直接使用当前 CLI 会话，用**最少 RPC、无多余子命令**，走到 `**record list` 成功返回样本/候选 JSON**；找应用用 `**app list [--query 关键词]`**，在读数前**不必**调用 `auth whoami` / `workspace get` / `view get` / `record schema browse`（除非你另需结构、query field 或排障）。
+> **目标**：直接使用当前 CLI 会话，用**最少 RPC、无多余子命令**执行 `data query`；找应用用 `app list [--query 关键词]`，字段结构与能力读取同一次 data 响应的 `schema + field_capabilities`。
 
 ### 调用次数
 
 
 | 前置           | 命令数    | 说明                                       |
 | ------------ | ------ | ---------------------------------------- |
-| 从零选应用        | **3**  | `app list` → `app get` → `record list`   |
-| 已知 `APP_KEY` | **2**  | `app get` → `record list`                |
+| 从零选应用        | **2**  | `app list` → `data query`   |
+| 已知 `APP_KEY` | **1**  | `data query`                |
 | 排障           | **+1** | 业务命令明确提示会话不可用、账号不确定时，再追加 `auth whoami` |
 
 
@@ -37,12 +37,9 @@ qingflow --json app list
 qingflow --json app list --query <关键词>
 # 在 items 中取 app_key → APP_KEY
 
-qingflow --json app get --app-key <APP_KEY>
-# 从返回 JSON 中取出应用对象（若存在顶层 .data 则先用 .data）；在 accessible_views 里选 view_id，见下文「先有通路、再要有数据」
-
-qingflow --json record list \
-  --app-key <APP_KEY> \
-  --view-id <VIEW_ID>
+qingflow data query --help
+qingflow --json data query --app-key <APP_KEY>
+# 首次读取保留 include_schema=true，并从同一响应读取 schema + field_capabilities。
 ```
 
 大 JSON 按规范 **重定向落盘**（`> tmp/qingflow_records.json`）。
@@ -52,9 +49,9 @@ qingflow --json record list \
 
 | 关注点         | 说明                                                                                                                                                                       |
 | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **连通性优先**   | 从 `app get.accessible_views` 选择表格类业务视图，优先 `system:all` 或明确可读的 `custom:*`。`record list` 默认最多 10 条，只用于样本/候选。 |
-| **不一定有明细行** | 业务视图可能因视图筛选为空；`items` 为空不等于 CLI 坏了。若目标是任务中心待办/已办/抄送，应换 `task list --task-box …`。 |
-| **读不到数据时**  | 在同一应用的 `accessible_views` 里切换其它表格类视图，跳过 **纯数字后缀** `custom:*`；不要用 `system:todo/done/cc` 当业务记录入口。 |
+| **连通性优先**   | 直接执行 `data query`；访问范围、字段投影和提示以当次响应为准，不预先选择 `view_id`。 |
+| **不一定有明细行** | `items` 为空不等于 CLI 坏了，先检查响应的 `access`、`hints` 与筛选条件。若目标是任务中心待办/已办/抄送，应换 `task list --task-box …`。 |
+| **读不到数据时**  | 按 [data 操作说明](../data/README.md) 处理权限、筛选或字段错误，不切换旧 record 视图绕过。 |
 
 
 **普通成员不要使用「自定义 + 纯数字 id」去读数：** 形如 `**custom:1`、`custom:2`、`custom:12`**（`custom:` 后**仅数字**）。此类在实测中 `**record schema browse` / `list` / `access` 一致 40038**（`Object not exist`），**不可用其作为换源备选**——应直接跳过并在 **其它视图 id** 上取样。
@@ -65,12 +62,16 @@ qingflow --json record list \
 | 不先调                                | 原因                                                       |
 | ---------------------------------- | -------------------------------------------------------- |
 | `workspace get` / `workspace list` | 读应用记录**不依赖**；徒增一次往返，且 list 在部分环境受 **59004** 等影响。         |
-| `view get`                         | `**record list` 不前置要求**；读后仍要看 `app get` 给的 `view_id` 才稳。 |
-| `record schema browse`             | 只读「有哪些列」才需要；纯拉数据 **list 足够**。                            |
+| `view get`                         | data query 不依赖视图；仅在用户明确查询视图配置时调用。 |
+| `record schema browse`             | data 默认路径从同一次响应读取 `schema + field_capabilities`。 |
 
 
 ---
 
+## 旧 record 兼容参考
+
+以下旧 `record` 规则只在用户明确要求兼容入口时使用，不得作为 data query/get/insert/update/delete 失败后的自动回退。
+
 ## 1. 优先使用（成员场景下实测高概率 exit 0）
 
 
@@ -145,7 +146,7 @@ qingflow --json record list \
 
 ## 5. 扩展链路（含 workspace / schema）
 
-若你还要 **核对当前工作区** 或 **先看 browse 字段**，在 **§「最短路径」** 之外可增加（顺序仍建议 **先最短再扩展**）。注意：最终统计结论、分析报告、趋势/排名/比例/分布必须使用 [record/analysis](../record/analysis/README.md) 的 `record access -> Python/pandas`：
+若你还要 **核对当前工作区** 或 **先看字段**，在 **§「最短路径」** 之外可增加（顺序仍建议 **先最短再扩展**）。注意：最终统计结论、分析报告、趋势/排名/比例/分布必须使用 [record/analysis](../record/analysis/README.md) 的 `data query --all --output csv -> Python/pandas`：
 
 ```bash
 qingflow --json auth whoami  # 仅业务失败、账号不确定或需要写清当前租户上下文时
@@ -191,5 +192,5 @@ qingflow --json record list --app-key <APP_KEY> --view-id <VIEW_ID>
 | §1 表内多数「高概率 exit 0」命令                                                                                             | 在典型成员会话下过 help/试跑对齐；仍以当前 CLI 与服务端为准。                                                               |
 | `custom:*` 与 `system:*` 在 browse/list/access 上差异                                                                 | 同上；`custom:+纯数字` 读数常 40038 已在上文单列。                                                                  |
 | `workspace select` 可能 59004                                                                                       | 流币等配额与其它失败区分；非每次必现。                                                                                                                               |
-| **§「最短路径」**（app list→get→record list；优先表格类业务视图；空数据则换其它可读表格视图；**勿用 `custom:<仅数字>`**） | 不包含多余 `workspace get`/`schema browse`，除非另行需要。 |
+| **旧 record 兼容路径**（app list→get→record list；优先表格类业务视图；空数据则换其它可读表格视图；**勿用 `custom:<仅数字>`**） | 仅用于用户明确要求旧入口时的兼容核对。 |
 | 本文未逐条自动化验证的项                                                                                                      | `task get`/`log`/`report`（缺 id）、`chart get`（缺真实 id）、**写路径** `record insert` 等 — 按通用表与业务策略，需有数据/权限时再测                                              |

package/skills/qingflow-cli/reference/core/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md

@@ -4,12 +4,13 @@
 
 > **本文档目的**：按**场景**给出**形态正确、参数闭合**时的命令模板，便于复制后替换占位符即跑，减少「缺参 / 引号 / 根级选项」类返工。
 > **不是**「任何账号、任何租户、任何时刻都 100% HTTP 200」——若遇 `59004`（流币/AI 配额）、401、或目标资源不存在，仍可能失败；那种情况属于**环境与权限**，不是本表要解决的「命令写对一次成」问题。
+> **数据默认入口**：普通 query/get/insert/update/delete 统一阅读 [data 操作说明](../data/README.md) 并使用 `qingflow data ...`；本文保留的旧 `record` 命令只供用户明确要求兼容入口时查阅。
 
 **统一建议**
 
 - 自动化读取命令优先加 `**--json`**；builder 写入/apply 命令默认只输出 JSON，不需要额外选择格式；展示写入结果时优先读 `operation + summary + resources[]`，不要按不同工具分别解析旧字段。
 - 需要稳定 profile 时加 `**--profile default`**（或与你的会话一致的名字）。
-- `task` / `record` 的大 JSON 查询类输出，按团队规范**落盘**（例如 `> tmp/qingflow_*.json`），本表为简洁只写核心参数。
+- `task` / `data` 的大 JSON 查询类输出，按团队规范**落盘**（例如 `> tmp/qingflow_*.json`），本表为简洁只写核心参数。
 
 ---
 
@@ -66,23 +67,26 @@
 
 ---
 
-## 5. 记录：`record`（区分「仅需 app-key」与「必须 view-id」）
+## 5. 应用数据：`data` 默认，旧 `record` 仅兼容
 
-下面「一次成功」指 **CLI 不会因缺参报错**；服务端仍可能因权限返回错误 JSON。
+普通数据操作使用 [data 操作说明](../data/README.md)。下面旧 `record` 行只说明兼容命令形态，不得作为 data 命令失败后的自动回退；服务端仍可能因权限返回错误 JSON。
 
 
 | 场景                      | 一次成功写法                                                                                    | 必填/注意                                                         |
 | ----------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| Insert schema              | `qingflow --json record schema insert --app-key <APP_KEY>`                             | 新建记录默认走 [record/insert](../record/insert/README.md)；CLI 用 insert-ready schema + `record insert --items-file`。 |
+| Data query                | `qingflow --json data query --app-key <APP_KEY>`                                         | 首次读取保留 schema，并从同一响应读取 `schema + field_capabilities`。 |
+| Data get                  | `qingflow --json data get --app-key <APP_KEY> --record-id <RECORD_ID>`                    | 单条读取默认入口；记录 id 必须来自已确认上下文。 |
+| Data insert               | `qingflow --json data insert --app-key <APP_KEY> --items-file items.json`               | 新建记录按 data 操作说明执行；字段键与值以 data schema 和当次工具响应为准。 |
+| Data update               | `qingflow --json data update --app-key <APP_KEY> --record-id <RECORD_ID> --fields-file fields.json` | 写入前检查 access 与字段能力；结果不明或已执行时不得重放。 |
+| Data delete               | `qingflow --json data delete --app-key <APP_KEY> --record-ids <RECORD_ID>`               | 删除前确认精确目标与影响范围。 |
 | Import / code-block schema | `qingflow --json record schema import --app-key <APP_KEY>` / `qingflow --json record schema code-block --app-key <APP_KEY>` | 仅在导入或代码块任务明确需要时使用。 |
-| Schema：browse（浏览态字段）    | `qingflow --json record schema browse --app-key <APP_KEY> --view-id <VIEW_ID>`            | **必须 `--view-id`**；不要用引号包住 `record schema browse` 整段。         |
-| 列表/候选定位（运行时强校验）           | `qingflow --json record list --app-key <APP_KEY> --view-id <VIEW_ID>` | **必须 `--view-id`**；默认最多返回 10 条，适合样本/模糊定位；可加 `--query` / `--query-field`。 |
-| 分析取数                    | `qingflow --json record access --app-key <APP_KEY> --view-id <VIEW_ID> --columns-file columns.json --where-file where.json` | 最终统计结论统一使用 [record/analysis](../record/analysis/README.md) 的 `record access -> Python/pandas`。 |
-| 单条读取                    | `qingflow --json record get --app-key <APP_KEY> --record-id <RECORD_ID>`                  | **必须** `--record-id`；返回前端详情页首屏上下文、引用、图片/文件资产。 |
-| 全量记录日志                | `qingflow --json record logs --app-key <APP_KEY> --record-id <RECORD_ID> [--view-id <VIEW_ID>]` | 仅在需要完整审计/日志历史时使用；全量数据日志和流程日志写本地 JSONL。 |
+| 旧 record schema browse    | `qingflow --json record schema browse --app-key <APP_KEY> --view-id <VIEW_ID>`            | 仅兼容入口；必须 `--view-id`。         |
+| 旧 record 列表           | `qingflow --json record list --app-key <APP_KEY> --view-id <VIEW_ID>` | 仅兼容入口；通常最多返回 10 条，适合样本/模糊定位。 |
+| 分析取数                    | `qingflow --json data query --app-key <APP_KEY> --columns-file columns.json --where-file where.json --all --output csv` | 最终统计结论统一使用 [record/analysis](../record/analysis/README.md) 的 `data query --all --output csv -> Python/pandas`。 |
+| 旧 record 日志                | `qingflow --json record logs --app-key <APP_KEY> --record-id <RECORD_ID> [--view-id <VIEW_ID>]` | 仅在用户明确需要完整审计/日志历史时使用；不替代 data get。 |
 
 
-**高风险写操作**（本表不保「业务上你希望的一次成功」，只列形态）：`record insert/update/delete`、`record code-block-run`（可能写回）需按 `-h` 逐项带齐文件类参数与安全开关。
+**高风险写操作**：`data insert/update/delete` 按 [data 操作说明](../data/README.md) 做确认与结果恢复；旧 `record code-block-run` 仅在明确代码块任务时按 `-h` 执行。
 
 ---
 
@@ -148,11 +152,11 @@
 
 在满足账号权限的前提下：
 
-1. `qingflow --json app list [--query <关键词>]` → 选一个 `**app_key`**
-2. `qingflow --json app get --app-key <APP_KEY>` → 选一个 `**view_id`**
-3. `qingflow --json record list --app-key <APP_KEY> --view-id <VIEW_ID>`
+1. `qingflow --json app list [--query <关键词>]` → 选一个 `app_key`
+2. `qingflow data query --help` → 按当前帮助确认 JSON 文件形状
+3. `qingflow --json data query --app-key <APP_KEY>`
 
-若要落盘再给第 3 步加 `> tmp/qingflow_records.json`。只有业务命令明确返回会话不可用、账号不确定或工作区异常时，才回到第 2 节做会话恢复。
+若要落盘再给第 3 步加 `> tmp/qingflow_data.json`。只有业务命令明确返回会话不可用、账号不确定或工作区异常时，才回到第 2 节做会话恢复。
 
 ---