@qingflow-tech/qingflow-cli 1.1.57 → 1.1.59

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

@@ -1,120 +1,139 @@
-# Qingflow CLI：应用数据查询工作流
+# Qingflow CLI：获取数据工作流（应用记录）
 
-> **用途**：使用视图无关的 `data query/get` 完成普通应用数据查询、筛选、排序、分页和单条读取。
-> **边界**：本文只给流程与 JSON 形状；操作符、字段类型、权限范围和动态限制以当前 `--help`、`schema`、`field_capabilities`、`access` 与 `hints` 为准。
-> **record 专项**：需要完整日志、附件／图片上下文时，阅读 [record 专项参考](../record/QINGFLOW_CLI_RECORD_SPECIALIZED_WORKFLOW.md)。
+> **用途**：使用当前 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)**。
 
-## 推荐顺序
+---
+
+## 概念步骤 → 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
-data query（默认带 schema）
-  → 从 schema / field_capabilities 定位 field_id 与能力
-  → 按需追加 columns / where / sort
-  → 根据 records.has_more 与 hints 继续分页或收窄范围
-  → 已知 record_id 时按需 data get
+app get（解析 accessible_views，选定 VIEW_ID）
+  → record schema browse（对齐字段 id/类型/展示名；也是 list/access/get 的视图字段口径）
+  → record list（样本浏览或 query 模糊定位候选）
+  → （可选）record get（对单条 record_id 拉详情页首屏上下文）
+  → （可选）record logs（需要完整审计日志时再拉全量日志 JSONL）
 ```
 
-已知 `app_key` 时直接 query；未知时只做必要的 `app list --query`。不要先执行 `app get → record schema browse`，普通数据查询也不需要 `view_id`。
+- **仅当你只需要「快速确认有无数据」**时，可以省略 `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`。
 
-## 1. 首次查询与字段能力
+---
+
+## 命令模板（占位符替换即可）
+
+**1）应用与视图**
 
 ```bash
-mkdir -p tmp
-qingflow --json data query --app-key APP_KEY \
-  > tmp/qingflow_data_query.json
+qingflow --json app get --app-key <APP_KEY> > tmp/qingflow_app_get.json
 ```
 
-首次查询保留默认 schema。响应重点读取：
+从 `tmp/qingflow_app_get.json` 解析：`$.data.accessible_views`（无 `data` 时再试顶层 `accessible_views`）。每个元素含 `view_id`、`name`、`kind` 等。
 
-- `records.items[]`：当前页记录；
-- `records.page/page_size/has_more`：分页状态；
-- `schema`：字段 id、标题与结构；
-- `field_capabilities`：筛选、排序和写入能力；
-- `access`：本次实际访问范围；
-- `hints`：需要收窄、继续、停止或调整参数的动态提示。
+若响应 `warnings[]` 含 `CUSTOM_VIEW_LIST_UNAVAILABLE`，表示 custom view 列表读取被权限或后端限制降级；这不是应用整体不可读。优先使用已返回的 `system:*` 视图继续 `schema browse` / `record list`，或从前端 URL 的 `viewgraphKey` 补充明确 `view_id`。
 
-不要用 insert/update 探测字段能力，也不要从 record schema 推断 data 能力。
+**2）浏览视图表结构（= `record_schema_get` browse）**
 
-## 2. 字段筛选
+```bash
+qingflow --json record schema browse \
+  --app-key <APP_KEY> \
+  --view-id <VIEW_ID> \
+  > tmp/qingflow_schema_browse.json
+```
 
-从首次响应中准确定位目标 `field_id`，并确认该字段 `filter_operators` 中存在所需 `op`、值符合 `value_shape`。例如：
+实跑样例响应顶层键包含：`status`、`app_key`、`schema_scope`、`fields`、`suggested_dimensions` 等（**以实际 JSON 为准**）。
 
-```json
-[
-  {"field_id": 101, "op": "eq", "value": "已完成"}
-]
-```
+**3）记录列表**
 
 ```bash
-qingflow --json data query \
-  --app-key APP_KEY \
-  --where-file tmp/where.json \
-  > tmp/qingflow_data_filtered.json
+qingflow --json record list \
+  --app-key <APP_KEY> \
+  --view-id <VIEW_ID> \
+  > tmp/qingflow_records.json
 ```
 
-本文示例不代表完整操作符矩阵；真实能力只认当前响应。
+列表默认最多返回 10 条，行数据常见于 `$.data.items`；每条一般有 `record_id`（及业务字段键值）。需要调整样本量时加 `--page-size <N>`；它只影响浏览/候选定位样本，不替代分析取数。响应会给出总数/下一步建议；如果是模糊定位，优先看 `lookup.total_count`、`lookup.next_action`。
 
-## 3. 排序
+`record_list.data.items[]` 是**字段平铺行对象**，不是 `fields[]` 数组。定位候选或做名称到记录 ID 映射时直接读字段标题键：
 
-只对 `sort_supported=true` 的字段构造排序：
-
-```json
-[
-  {"field_id": 102, "direction": "desc"}
-]
+```python
+rows = payload["data"]["items"]
+name_to_record_id = {row["客户名称"]: row["record_id"] for row in rows}
 ```
 
-```bash
-qingflow --json data query \
-  --app-key APP_KEY \
-  --sort-file tmp/sort.json \
-  > tmp/qingflow_data_sorted.json
-```
+只有 `record_get` 详情使用 `fields[]` 来表示字段列表。
 
-## 4. 分页
+**模糊定位示例**：
 
 ```bash
-qingflow --json data query --app-key APP_KEY --page 1 --page-size 100 \
-  > tmp/qingflow_data_page_1.json
+qingflow --json record list \
+  --app-key <APP_KEY> \
+  --view-id <VIEW_ID> \
+  --query "北京和路元" \
+  --page-size 20 \
+  --query-field 6299262 \
+  > tmp/qingflow_record_lookup.json
 ```
 
-仅当 `records.has_more=true` 时请求下一页，并继续读取 `hints`：
+`--query-field` 对应 `record_browse_schema_get.fields[].field_id`，表示后端全文搜索范围；它不是输出列控制。
+
+**4）单条记录详情**
 
 ```bash
-qingflow --json data query --app-key APP_KEY --page 2 --page-size 100 \
-  > tmp/qingflow_data_page_2.json
+qingflow --json record get \
+  --app-key <APP_KEY> \
+  --record-id <RECORD_ID> \
+  --view-id <VIEW_ID> \
+  > tmp/qingflow_record_get.json
 ```
 
-不要只按 `total/page_size` 猜测完整性；若 hints 要求收窄范围或响应说明结果不完整，先按提示处理。
-
-## 5. 单条读取
+已知前端视图时必须传同一个 `--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**。
 
-从 query 得到明确 `record_id` 后，按需读取单条：
+**5）全量日志（仅在用户明确需要完整审计/日志历史时）**
 
 ```bash
-qingflow --json data get --app-key APP_KEY --record-id RECORD_ID \
-  > tmp/qingflow_data_get.json
+qingflow --json record logs \
+  --app-key <APP_KEY> \
+  --record-id <RECORD_ID> \
+  --view-id <VIEW_ID> \
+  > tmp/qingflow_record_logs.json
 ```
 
-`data get` 用于普通单条业务数据。若用户需要详情页附件、图片或完整数据／流程日志，切换到 record 专项，不要把它们误写成 data get 的默认合同。
+响应重点看：`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 全文直接塞进上下文，按需用脚本读取、筛选或汇总。
 
-## 6. 统计分析
+---
 
-最终统计结论、分布、比例、排名和趋势使用：
+## `view_id` 选取（成员侧必读摘要）
 
-```bash
-qingflow --json data query \
-  --app-key APP_KEY \
-  --where-file tmp/where.json \
-  --all --output csv \
-  > tmp/qingflow_data_analysis.json
-```
+- **`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**）。
+
+---
+
+## 落盘与解析
 
-读取全部 `files[].local_path` 后再用 Python/pandas 分析。只有 `complete=true`、`truncated=false`、`safe_for_final_conclusion=true` 时，才能形成完整总体结论；详见 [数据分析说明](../record/analysis/README.md)。
+- `schema browse`、`record list`、`record get`、`record logs` 体量大时，**必须**重定向到文件，勿将整段 JSON 直接塞进 LLM 上下文（规则见主技能「输出落盘规则」）。`record_get` 下载的本地图片/文件路径可以再交给图片理解、文档解析或 Python 读取；`record logs` 的全量日志读 `*.jsonl` 文件。
+- 解析前**先 unwrap `data`**：多数业务成功响应为 `{ "data": { ... } }`，与 `schema browse` 部分字段在顶层的形态可能不同，以每次响应为准。
 
-## 落盘与错误处理
+---
 
-- query/get 的 JSON 与分析摘要必须落盘，只解析所需键；CSV 读取本地文件路径，不打印全文。
-- 参数错误按当前 `qingflow data ... --help` 修正。
-- 权限、范围和字段错误按响应说明处理；data 失败时不得自动改用 record 查询绕过限制。
-- CLI 升级后用 `qingflow data --help`、`qingflow data query --help`、`qingflow data get --help` 复核。
+*维护：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`。*

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

@@ -6,11 +6,11 @@
 
 ## 1. 当前能力树摘要
 
-- 顶层数据操作目标入口为 `data query/get/insert/update/delete`；发布前必须以当前真实 package 的 `qingflow data --help` 复核可用性。
+- 顶层：`qingflow {auth|workspace|app|portal|view|chart|record|import|export|task|builder|build} ...`
 - `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) 走 `data query --all --output csv -> Python/pandas`，不要寻找或使用其它聚合捷径。
+- 最终统计结论统一按 [record/analysis](../record/analysis/README.md) 走 `record access -> Python/pandas`，不要寻找或使用其它聚合捷径。
 
 ---
 
@@ -37,15 +37,13 @@
 | 入口 | 当前定位 |
 | --- | --- |
 | `record list` | 样本浏览 / 模糊定位候选；默认最多返回 10 条，返回 `data.pagination.total_count`，带 `--query` 时看 `lookup.total_count` 与 `lookup.next_action` |
-| `record access` | 旧 CLI 非默认兼容入口；不得作为分析默认链或 data query 失败后的自动回退 |
+| `record access` | 默认分析取数入口；自动分页写本地 CSV；不暴露 `page/page_size/limit/max_rows/profile` |
 | `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`；不要混用 |
 
-直接 query/get/insert/update/delete 统一阅读 [data 操作说明](../data/README.md) 并使用对应 data 工具。最终分析使用 `data query --all --output csv`，按真实响应的 `files[].local_path` 读取全部 CSV 分片。
-
-`record_get` 下载本地附件的规则仅适用于用户明确要求旧 CLI 兼容入口的场景。
+`record_get` 下载到本地的图片读 `media_assets.items[].local_path`；文档、表格、PDF 等读 `file_assets.items[].local_path` 与 `extraction.text_path`。不要直接访问远端 Qingflow 附件 URL。
 
 ---
 

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

@@ -1,16 +1,16 @@
 # Qingflow CLI：字段数据类型（Schema / 列表 / 写入）
 
-> **用途**：普通数据查询、读取和写入默认使用 **[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)**。
+> **用途**：说明 **`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)**。
 
 ---
 
-## 1. 旧 record `fields[]` 兼容结构（`--json` 精简后）
+## 1. `fields[]` 通用结构（`--json` 精简后）
 
 | 字段 | 含义 |
 |------|------|
-| **`field_id`** | 内部题 id（数字）；data query 的 `columns` / `where` / `sort` 以此引用列。 |
+| **`field_id`** | 内部题 id（数字）；**`record_access.columns` / `where-file` / `order-by-file` 等 DSL** 常以此引用列。 |
 | **`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` 产出视图表头的精简 **`fields[]`**，旧 `record get` 产出记录详情字段，一般 **不含** 完整 **`que_type`/`writable`** 元数据。普通数据操作不要据此猜测字段能力；应读取 data 返回的 `schema + field_capabilities`。
+**browse 与 detail**：`browse` 产出视图表头的精简 **`fields[]`**；`record get` 产出当前记录详情字段。一般 **不含** 完整 **`que_type`/`writable`** 元数据。更新主链路先用 **`record get`** 的字段信息组 payload，再执行 **`record update`**；只有更新失败、字段歧义或需要诊断可写范围时，再结合 **`record schema update`**（按记录）或写入返回判断。
 
 ---
 
 ## 2. `kind` 枚举（CLI 对外）
 
-旧 record 内部写入类别经归并后形成下表 **`kind`**；本表仅用于显式兼容旧命令，不是普通 data 操作的能力事实源：
+内部写入类别经归并后形成下表 **`kind`**（与 `qingflow` 当前实现一致；升级后请以 **`record schema … --json` 实跑** 为准）：
 
 | CLI `kind` | 维护侧常见内部类别（参考） | 在 `record list` / `record get` / `record access` 中（常见） | insert/update 写入值 |
 |------------|-----------------------------------|--------------------------------------------|----------------------------------|
@@ -110,20 +110,20 @@
 ## 4. 与 `field_id` / 列选择
 
 
-- **`data query --columns-file`**：列投影使用数字 `field_id`，并与 `schema`、`field_capabilities` 对照。
-- **`data get`**：按记录 id 读取普通数据详情；需要日志、引用或资产等旧专用上下文时，才显式使用相应 record 命令。
+- **`record list --column`**：参数为 **数字列 id**，用于样本/候选列表展示列，须与 **`fields[].field_id`** 一致。
+- **`record get`**：默认读取前端详情页首屏上下文；不要把 `--column` 当成详情字段投影主路径，单条字段、首屏日志、引用、图片/文件资产以 `record_get` 的结构化上下文为准。若用户要完整数据日志/流程日志历史，用 `record logs`。
 - **标题重复**：同一 `title` 可能对应多个 `field_id`（极少见）；列表 DSL 应用 **`field_id`** 消歧。
 
 ---
 
 ## 5. 读者操作建议
 
-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`**。
+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`**。
 3. **看 `kind` + `options` / `row_fields` / `target_app_key`**，并对照 **§3 特殊字段** 判断是否存在联动、引用或只读带出。
 4. **选项联动 / 引用带出**：先写 **驱动题**，再写 **被带出的题**；只读带出列 **不要强写**。
-5. **写入前缩小 payload**；`data insert --items-file` 的单条输入也是数组中的一个 item。根据 **`write_executed` / `retry_safe` / `field_errors` / `hints`** 迭代（`--json` 保持无损）。
+5. **写入前缩小 payload**；insert 默认用 `record insert --items-file`，单条也是 `items` 数组一行。根据 **`status` / `blockers` / `field_errors` / `failed_fields` / `created_record_ids`** 迭代（`--json` 在 stdout）。
 
 ---
 
-*维护：普通数据操作以 data 返回的字段能力为准；旧 record 的 `kind` 与内部 `que_type` 仅作兼容参考。*
+*维护：`kind` 集合与精简字段以当前 CLI 的 `record schema … --json` 实跑为准；内部 `que_type` 枚举随轻流版本变化，文档只稳定描述对外 **`kind`** 桶。*

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

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

@@ -4,13 +4,12 @@
 
 > **本文档目的**：按**场景**给出**形态正确、参数闭合**时的命令模板，便于复制后替换占位符即跑，减少「缺参 / 引号 / 根级选项」类返工。
 > **不是**「任何账号、任何租户、任何时刻都 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` / `data` 的大 JSON 查询类输出，按团队规范**落盘**（例如 `> tmp/qingflow_*.json`），本表为简洁只写核心参数。
+- `task` / `record` 的大 JSON 查询类输出，按团队规范**落盘**（例如 `> tmp/qingflow_*.json`），本表为简洁只写核心参数。
 
 ---
 
@@ -67,26 +66,23 @@
 
 ---
 
-## 5. 应用数据：`data` 默认，旧 `record` 仅兼容
+## 5. 记录：`record`（区分「仅需 app-key」与「必须 view-id」）
 
-普通数据操作使用 [data 操作说明](../data/README.md)。下面旧 `record` 行只说明兼容命令形态，不得作为 data 命令失败后的自动回退；服务端仍可能因权限返回错误 JSON。
+下面「一次成功」指 **CLI 不会因缺参报错**；服务端仍可能因权限返回错误 JSON。
 
 
 | 场景                      | 一次成功写法                                                                                    | 必填/注意                                                         |
 | ----------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| 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>`               | 删除前确认精确目标与影响范围。 |
+| 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`。 |
 | Import / code-block schema | `qingflow --json record schema import --app-key <APP_KEY>` / `qingflow --json record schema code-block --app-key <APP_KEY>` | 仅在导入或代码块任务明确需要时使用。 |
-| 旧 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。 |
+| 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。 |
 
 
-**高风险写操作**：`data insert/update/delete` 按 [data 操作说明](../data/README.md) 做确认与结果恢复；旧 `record code-block-run` 仅在明确代码块任务时按 `-h` 执行。
+**高风险写操作**（本表不保「业务上你希望的一次成功」，只列形态）：`record insert/update/delete`、`record code-block-run`（可能写回）需按 `-h` 逐项带齐文件类参数与安全开关。
 
 ---
 
@@ -152,11 +148,11 @@
 
 在满足账号权限的前提下：
 
-1. `qingflow --json app list [--query <关键词>]` → 选一个 `app_key`
-2. `qingflow data query --help` → 按当前帮助确认 JSON 文件形状
-3. `qingflow --json data query --app-key <APP_KEY>`
+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>`
 
-若要落盘再给第 3 步加 `> tmp/qingflow_data.json`。只有业务命令明确返回会话不可用、账号不确定或工作区异常时，才回到第 2 节做会话恢复。
+若要落盘再给第 3 步加 `> tmp/qingflow_records.json`。只有业务命令明确返回会话不可用、账号不确定或工作区异常时，才回到第 2 节做会话恢复。
 
 ---
 

package/skills/qingflow-cli/reference/record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md

@@ -1,8 +1,7 @@
 # Qingflow CLI：更新记录工作流（详情后直接写入）
 
-> **兼容范围**：本文仅限用户明确要求旧 CLI `record` 兼容入口时使用。默认更新必须切换到 [data 操作说明](../data/README.md) 的 `data get` → `data update`；禁止在 data update 失败后自动回退本文链路。
 > **用途**：使用当前 CLI 会话读取目标记录详情后，用 **`record update`** 直接提交差异字段。主链路是 `record get -> record update`；字段范围不清、候选歧义或失败排查时，才追加 **`record schema update`**。
-> **关联**：直接数据操作统一使用 [data 操作说明](../data/README.md)；最终统计结论统一使用 **[record/analysis](./analysis/README.md) 的 `data query --all --output csv -> Python/pandas`**；主技能 **[../SKILL.md](../../SKILL.md)**。
+> **关联**：只读列表/详情见 **[QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](../core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**；**字段 `kind` 与写入值总表**见 **[QINGFLOW_CLI_FIELD_DATA_TYPES.md](../core/QINGFLOW_CLI_FIELD_DATA_TYPES.md)**；最终统计结论统一使用 **[record/analysis](./analysis/README.md) 的 `record access -> Python/pandas`**；**成员 / 部门等** 的细颗粒写入见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**；主技能 **[../SKILL.md](../../SKILL.md)**。
 
 ---