@qingflow-tech/qingflow-cli 1.1.57 → 1.1.59

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

@@ -1,5 +1,139 @@
-# Qingflow CLI：应用数据查询工作流
+# Qingflow CLI：获取数据工作流（应用记录）
 
-普通应用数据查询默认使用 `data query/get`。完整流程、JSON 形状、分页与分析边界见 [core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)。
+> **用途**：使用当前 CLI 会话，从「选定应用」到「读懂列含义 + 样本/模糊定位 / 单条详情」的**推荐闭环**；下表 **左列**可与常见 **编排/内部接口**命名对照，**右列**仅为本 CLI 命令。
+> **新版口径**：`record_list` 不是批量分析入口，而是样本浏览和模糊定位入口；`record_get` 是前端详情页首屏上下文入口；全量日志用 `record logs`；分析取数统一转 `qingflow-record-analysis` 的 `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](./QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**；**更新记录**见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**；最终统计结论统一使用 **`qingflow-record-analysis` 的 `record_access -> Python/pandas`**；主技能规则见 **[../SKILL.md](../SKILL.md)**。
 
-需要完整日志、附件和图片上下文时，使用 [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）
+```
+
+- **仅当你只需要「快速确认有无数据」**时，可以省略 `schema browse`，直接 `app get` → `record list`（与成员速查表「最短路径」一致）。  
+- **当你需要稳定映射列名、写过滤条件或对接自动化**时，应按上表**显式**走 `schema browse`，避免对着 `list` 里中文列名猜字段定义。  
+- **当用户只给出模糊信息定位单条数据**时，走 `record schema browse` 确认可搜索字段，再用 `record list --query ... --query-field ...` 返回候选；只有候选明确后才 `record get`。
+- **需要分组/聚合统计、最终统计结论、分析报告、趋势/排名/比例/分布**时，必须切换到 **`qingflow-record-analysis`**，按 `app_get -> record_browse_schema_get(view_id=...) -> record_access -> Python/pandas -> final answer` 执行。
+
+---
+
+## 命令模板（占位符替换即可）
+
+**1）应用与视图**
+
+```bash
+qingflow --json app get --app-key <APP_KEY> > tmp/qingflow_app_get.json
+```
+
+从 `tmp/qingflow_app_get.json` 解析：`$.data.accessible_views`（无 `data` 时再试顶层 `accessible_views`）。每个元素含 `view_id`、`name`、`kind` 等。
+
+若响应 `warnings[]` 含 `CUSTOM_VIEW_LIST_UNAVAILABLE`，表示 custom view 列表读取被权限或后端限制降级；这不是应用整体不可读。优先使用已返回的 `system:*` 视图继续 `schema browse` / `record list`，或从前端 URL 的 `viewgraphKey` 补充明确 `view_id`。
+
+**2）浏览视图表结构（= `record_schema_get` browse）**
+
+```bash
+qingflow --json record schema browse \
+  --app-key <APP_KEY> \
+  --view-id <VIEW_ID> \
+  > tmp/qingflow_schema_browse.json
+```
+
+实跑样例响应顶层键包含：`status`、`app_key`、`schema_scope`、`fields`、`suggested_dimensions` 等（**以实际 JSON 为准**）。
+
+**3）记录列表**
+
+```bash
+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`。
+
+`record_list.data.items[]` 是**字段平铺行对象**，不是 `fields[]` 数组。定位候选或做名称到记录 ID 映射时直接读字段标题键：
+
+```python
+rows = payload["data"]["items"]
+name_to_record_id = {row["客户名称"]: row["record_id"] for row in rows}
+```
+
+只有 `record_get` 详情使用 `fields[]` 来表示字段列表。
+
+**模糊定位示例**：
+
+```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
+```
+
+`--query-field` 对应 `record_browse_schema_get.fields[].field_id`，表示后端全文搜索范围；它不是输出列控制。
+
+**4）单条记录详情**
+
+```bash
+qingflow --json record get \
+  --app-key <APP_KEY> \
+  --record-id <RECORD_ID> \
+  --view-id <VIEW_ID> \
+  > tmp/qingflow_record_get.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**。
+
+**5）全量日志（仅在用户明确需要完整审计/日志历史时）**
+
+```bash
+qingflow --json record logs \
+  --app-key <APP_KEY> \
+  --record-id <RECORD_ID> \
+  --view-id <VIEW_ID> \
+  > tmp/qingflow_record_logs.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 全文直接塞进上下文，按需用脚本读取、筛选或汇总。
+
+---
+
+## `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**）。
+
+---
+
+## 落盘与解析
+
+- `schema browse`、`record list`、`record get`、`record logs` 体量大时，**必须**重定向到文件，勿将整段 JSON 直接塞进 LLM 上下文（规则见主技能「输出落盘规则」）。`record_get` 下载的本地图片/文件路径可以再交给图片理解、文档解析或 Python 读取；`record logs` 的全量日志读 `*.jsonl` 文件。
+- 解析前**先 unwrap `data`**：多数业务成功响应为 `{ "data": { ... } }`，与 `schema browse` 部分字段在顶层的形态可能不同，以每次响应为准。
+
+---
+
+*维护：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/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/README.md) 走 `data query --all --output csv -> Python/pandas`，不要寻找或使用其它聚合捷径。
+- 最终统计结论统一由 `qingflow-record-analysis` 走 `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/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](./QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**，更新流程见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**；**搭建侧** AppForm 的 `type` 见 **[builder/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](./QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**；更新流程见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**；只读见 **[QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**；**搭建侧** AppForm 的 `type`（与本文 `kind` 命名体系不同）及其 CLI 命令见 **[builder/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 写入值 |
 |------------|-----------------------------------|--------------------------------------------|----------------------------------|
@@ -63,7 +63,7 @@
 **选项联动（控制显隐、必填等）**  
 
 - 实现上来自 **题目关系 + 选项上的联动题 id**（如其它题因当前选项而被激活）。  
-- 直接数据写入使用 [data 操作说明](./data/README.md)；字段 id、可见范围和写入形状以当次 data schema 或字段错误为准，不要从旧 record schema 猜测。
+- **`record schema browse` 的 `--json`**：精简 `fields[]` 可能不展示完整 `linkage` / 联动明细；新建记录以 `qingflow-record-insert` 的 `record_insert_schema_get`（CLI `record schema insert`）为准，不要用兼容保留的 applicant schema 入口替代。
 - **写入时**：若更新返回提示 **上游未选、联动未激活、字段尚未显示**，应 **先写或改 payload 里处于上游的选项（或其它驱动题）**，再写下游；必要时用 **`record schema update --record-id …`** 诊断当前记录下 **`required_fields` / `optional_fields` / `payload_template`**。
 
 ### 3.2 关联字段（关联记录）
@@ -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/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. **数据分析**：最终统计结论、分析报告、趋势/排名/比例/分布必须走 **`qingflow-record-analysis` 的 `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/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 工具当次响应为准；最终统计结论统一使用 **`data query --all --output csv -> Python/pandas`**；批量导入阅读导入 SOP。
+- **只读拉取表单记录的最短链路**：见本节 **「最短路径：普通成员只读记录数据」**（可省略 `schema browse`）。**需先拉浏览视图表结构**时见 **[QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**；最终统计结论统一使用 **`qingflow-record-analysis` 的 `record_access -> Python/pandas`**；**字段 `kind` / 数据形态**见 **[QINGFLOW_CLI_FIELD_DATA_TYPES.md](./QINGFLOW_CLI_FIELD_DATA_TYPES.md)**；**新建记录默认批量 JSON 链路**请用 **`qingflow-record-insert`**（`record_insert_schema_get -> record_insert(items)`，CLI 为 `record insert --items-file`，成员/部门/关联优先自然语言）；**浏览视图下更新记录**见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./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/README.md) 的 `data query --all --output csv -> Python/pandas`：
+若你还要 **核对当前工作区** 或 **先看 browse 字段**，在 **§「最短路径」** 之外可增加（顺序仍建议 **先最短再扩展**）。注意：最终统计结论、分析报告、趋势/排名/比例/分布必须使用 `qingflow-record-analysis` 的 `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/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>`                             | 新建记录默认走 `qingflow-record-insert`；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/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` | 最终统计结论统一使用 `qingflow-record-analysis` 的 `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/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md

@@ -1,15 +1,20 @@
-# Qingflow CLI：新增应用数据
+# Qingflow CLI：创建记录 SOP（申请节点）
 
-直接新增记录统一切换到 [data 操作说明](./data/README.md)，使用 CLI `qingflow data insert`。
+---
 
-执行前先通过当前 MCP 工具 schema 或以下命令确认实时参数：
+**创建记录 SOP 见 skill：`qingflow-record-insert`。**
+
+CLI 对应主路径：
 
 ```bash
-qingflow data insert --help
+qingflow --json record schema insert --app-key <APP_KEY> > tmp/qingflow_insert_schema.json
+qingflow --json record insert --app-key <APP_KEY> --items-file tmp/records.json > tmp/qingflow_insert_result.json
 ```
 
-CLI 使用 `--items-file` 提交 JSON 文件。字段键、可写范围、字段类型、必填与联动约束均以 data 工具当次返回的 schema、字段错误和动态提示为准；不要从旧 record insert 示例复制字段形状。
+不要用 `record schema applicant` 代替 `record_insert_schema_get` 的主路径；新建记录需要 insert-ready schema 里的 `required_fields`、`optional_fields`、`payload_template`、`format_hint`、`expected_format`、`example_value` 和字段级 `options`。
+
+成员、部门、关联记录、选项、附件等特殊字段按 `qingflow-record-insert` 的 **Special Field Write Cheatsheet** 写：先读 insert schema；部门/成员不能自造候选；选项值必须来自 schema `options` 的文本或 id；关联记录批量写入优先 `record_id`，自然名称只在唯一匹配时使用；附件先上传再写返回值。
 
-新增会写入真实业务数据。执行前确认目标应用、记录数量和内容；返回后先检查是否已经执行、是否部分成功，再只修正明确失败项，不重放整个批次。
+追加样例数据时也必须 schema-first：按 `required_fields` 补齐必填；按 `expected_format/example_value` 选择数值、金额、日期等格式；按 `options` 生成选项值。不要按业务常识自造“正常/已完成/高优先级”等 schema 里不存在的选项。比例、完成率、评分、百分比等字段也按 schema 示例写；如果字段被建成金额/整数类而不接受小数，不要强塞 decimal，改用符合 schema 的整数值，或回到 builder 阶段把字段建模为 `number`。
 
-批量导入 Excel、模板校验、文件修复、导入启动和状态查询仍使用 [导入 SOP](./record/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md)，不要并入直接 data insert。
+录入数据时不要填写轻流系统字段：`数据ID`、`编号`、`申请人`、`申请时间`、`创建人`、`创建时间`、`提交人`、`提交时间`、`更新时间`、`更新人`、`当前流程状态`、`当前处理人`、`当前处理节点`、`流程标题`。这些字段由平台生成；需要确认时在创建成功后读取记录详情，不要把它们写进 `fields` / `items[].fields`。

package/skills/qingflow-cli/reference/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)；最终统计结论统一使用 **`data query --all --output csv -> Python/pandas`**；主技能 **[../SKILL.md](../SKILL.md)**。
+> **关联**：只读列表/详情见 **[QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**；**字段 `kind` 与写入值总表**见 **[QINGFLOW_CLI_FIELD_DATA_TYPES.md](./QINGFLOW_CLI_FIELD_DATA_TYPES.md)**；最终统计结论统一使用 **`qingflow-record-analysis` 的 `record_access -> Python/pandas`**；**成员 / 部门等** 的细颗粒写入见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**；主技能 **[../SKILL.md](../SKILL.md)**。
 
 ---
 

package/skills/qingflow-cli/reference/builder/20-build-complete-system.md

@@ -22,7 +22,7 @@ package apply/get -> AppForm schema/get/apply per app -> app readback -> workflo
 - Do not call the retired `builder schema apply` or `builder layout apply` routes, and do not use their `add_fields`, `apps-file`, or `form-file` payloads as the current path.
 - For relations, create relation-independent apps first, read back their published `appKey`s, then submit complete declarations using the canonical relation shape and known target app keys.
 - One app may contain multiple `relation` fields when the business model needs them.
-- Relation selectors use the AppForm camelCase shape, not bare strings: write ordered `config.displayFields: [{"field":{"name":"产品编码"},"auth":"visible"}]` (include hidden items) and `config.twoWayBoundField: {"queId":N}` when the binding is two-way (omit for one-way). `config.targetAppKey` must be a target app key confirmed by readback.
+- Relation selectors use the AppForm camelCase shape, not bare strings: write `config.displayField: {"name":"产品编码"}` and `config.visibleFields: [{"name":"产品名称"}]`. `config.targetAppKey` must be a target app key confirmed by readback.
 - If AppForm apply times out or returns uncertain write state, perform draft/published form readback before retrying. Do not recreate apps with `V2`, `测试`, or random suffixes.
 - If a same/similar package or app set already exists and the user did not say whether to extend, repair, replace, or create new, stop and ask. Do not start probing with new names.
 - If readback shows part of the requested system already exists, list existing apps/fields/views/charts/portal, identify gaps, and patch only the missing or incorrect slices.
@@ -73,7 +73,7 @@ A complete system is not just several created apps. Before reporting completion,
 
 - Package exists, and its `package_id` is known.
 - Every core business object is a separate app with `app_key`, `app_name`, `icon`, `color`, and exactly one readable data title field.
-- Cross-app relation fields are present where the business model needs them; each relation uses a confirmed `targetAppKey` and object selectors in `config.displayFields[].field` (+ `twoWayBoundField` for two-way bindings).
+- Cross-app relation fields are present where the business model needs them; each relation uses a confirmed `targetAppKey` and object selectors in `config.displayField` / `config.visibleFields`.
 - Core apps were created with complete AppForm declarations, so fields and readable form sections/rows were submitted together.
 - Core operating views exist and their `query_conditions` and `action_buttons` are verified; list-row buttons and detail-page buttons are both configured through the view.
 - Each new app has 5 realistic sample records unless the user explicitly skipped sample data.

package/skills/qingflow-cli/reference/builder/30-schema-fields.md

@@ -185,7 +185,7 @@ current CLI payload.
 | 负责人、审批人、参与人 | `member` | 不要创建“申请人/提交人”等平台系统字段 |
 | 部门、组织 | `department` | 可按需要补 `config.departmentScope` |
 | 图片、文件、附件 | `attachment` | 只有顶层 `attachment` 可被应用级 `dataCoverField` 选择 |
-| 跨应用业务对象关系 | `relation` | 使用已确认的 `targetAppKey`；展示字段写有序 `displayFields[]`（含 `auth`），双向绑定写 `twoWayBoundField`；旧 `displayField`/`visibleFields` 兼容窗口内仍可读 |
+| 跨应用业务对象关系 | `relation` | 使用已确认的 `targetAppKey`；`displayField` / `visibleFields` 必须写对象选择器 |
 
 禁止创建平台系统字段：`数据ID`、`编号`、`申请人`、`申请时间`、`创建人`、`创建时间`、`提交人`、`提交时间`、`更新时间`、`更新人`、`当前流程状态`、`当前处理人`、`当前处理节点`、`流程标题`。需要引用系统字段时，只在工具明确支持的位置引用，例如按钮 `source_field: "数据ID"`。
 
@@ -243,7 +243,7 @@ current CLI payload.
 |--------|----------|-----------------|
 | 标量与选择器 | `name` + `questionType`（+ 业务 `beingRequired` 等） | `questionDescription`、`beingRequired`；数据标题和封面在应用级 `dataTitleField/dataCoverField` 中选择；**`single_select` / `multi_select` 的 `config.options` 是非空字符串数组**，如 `["A", "B"]` |
 | `department` | 同左 | **`config.departmentScope`**：`mode: all \| custom`；`custom` 时 **`departments[]`**（含 `deptId` 等） |
-| `relation` | **`targetAppKey`**；另需 **`displayFields[]`**（含 `field`+`auth`；可为空列表——空 = 双向绑定未配展示字段的存量形态，round-trip 空↔空稳定；与旧形态不可混用、条目 queId 不可重复） | **`relationMode`**；双向绑定加 **`twoWayBoundField`**（省略 = 单向）；目标应用元数据不可读时先读已发布表单，不要猜目标 key |
+| `relation` | **`targetAppKey`**；另需 **`displayField`**、**`visibleFields[]`** | **`relationMode`**；目标应用元数据不可读时先读已发布表单，不要猜目标 key |
 | `subtable` | **`subfields[]` 非空** | 子列递归同父级规则；使用 Schema 返回的 camelCase 子字段配置 |
 | `q_linker` | **`config.qLinkerBinding`**：`inputs`、`request`、**`outputs[]` 每项须含 `targetField`**（能解析到本表单字段） | `request.url` 等须符合**租户/后端远程查询策略**；以字段类型 Schema 返回的配置为准 |
 | `code_block` | **`config.codeBlockBinding`**：`inputs`、`code`、**`outputs[]` + `targetField`**；配置 outputs 时，代码必须显式写 **`qf_output = {...}`**，仅 `return {...}` 不会产生可回写结果，且每个 `outputs[].path` 必须从 `qf_output` 取值 | 以字段类型 Schema 返回的 camelCase 配置为准 |
@@ -265,17 +265,13 @@ current CLI payload.
   "config": {
     "targetAppKey": "PRODUCT_APP_KEY",
     "relationMode": "single",
-    "twoWayBoundField": {"name": "产品编码"},
-    "displayFields": [
-      {"field": {"name": "产品编码"}, "auth": "visible"},
-      {"field": {"name": "产品名称"}, "auth": "hidden"},
-      {"field": {"name": "产品线"}, "auth": "visible"}
-    ]
+    "displayField": {"name": "产品编码"},
+    "visibleFields": [{"name": "产品名称"}, {"name": "产品线"}]
   }
 }
 ```
 
-只在目标应用已经创建并通过 readback 确认后填写 `targetAppKey`。如果返回选择器校验错误，修复 `config.displayFields[].field` / `config.twoWayBoundField`，不要重建应用或改 `appKey`。旧形态 `displayField`/`visibleFields` 在兼容窗口内仍可读（displayField 同时视为双向绑定目标），新声明一律用 `displayFields`。
+只在目标应用已经创建并通过 readback 确认后填写 `targetAppKey`。如果返回选择器校验错误，修复 `config.displayField` / `config.visibleFields`，不要重建应用或改 `appKey`。
 
 引用字段的公式默认值写在 `config.defaultValueFormula`，表达式必须符合固定版本 `relation` 字段详情中的 `FormulaExpression`。不要把后端 `referenceConfig` 字段名或其他 Schema 版本的公式写法直接放进声明。
 

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

@@ -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.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。
+- `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。
 - 一个应用可以包含多个 `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.twoWayBoundField`、`config.displayFields[]`。 |
+| **`relation`** | 旧载荷使用 `target_app_key` / `target_app_ref`；当前 AppForm 使用 `config.targetAppKey`、`config.relationMode`、`config.displayField`、`config.visibleFields`。 |
 | **`subtable`** | 当前 AppForm 使用 `subfields[]` 及 Schema 返回的 camelCase 配置；旧 `subfield_updates` 只作迁移线索。 |
 | **`q_linker`** | 当前 AppForm 使用 `config.qLinkerBinding`，其 `outputs[].targetField` 必须按字段 Schema 配置。 |
 | **`code_block`** | 当前 AppForm 使用 `config.codeBlockBinding`，其 `outputs[].targetField` 必须按字段 Schema 配置。 |

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)** 一致：直接数据操作使用 [data 操作说明](../data/README.md)；最终统计结论、分析报告、趋势/排名/比例/分布统一使用 **[record/analysis](../record/analysis/README.md) 的 `data query --all --output csv -> Python/pandas`**。
+与 **[成员速查](./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`**。
 
 ---