@josephyan/qingflow-cli 1.0.11 → 1.1.2

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

@@ -0,0 +1,129 @@
+# 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](./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)**；**搭建侧** **`app_schema_apply` 的 `type`（与本文 `kind` 命名体系不同）**见 **[QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)**；主技能 **[../SKILL.md](../SKILL.md)**。
+
+---
+
+## 1. `fields[]` 通用结构（`--json` 精简后）
+
+| 字段 | 含义 |
+|------|------|
+| **`field_id`** | 内部题 id（数字）；**`record_access.columns` / `where-file` / `order-by-file` 等 DSL** 常以此引用列。 |
+| **`title`** | 题目标题；insert/update 的 `fields` map 键通常与之一致。 |
+| **`kind`** | 见 **§2 `kind` 枚举**；决定读写时值的形态。 |
+| **`options`** | 可选；**`kind=select`** 时常为允许选项的字符串列表。 |
+| **`target_app_key`** | 可选；**`kind=relation`** 时关联目标应用。 |
+| **`searchable_fields`** | 可选；**`kind=relation`** 时在关联侧可用来检索的字段说明。 |
+| **`row_fields`** | 可选；**`kind=subtable`** 时子表列的子 schema（递归同类结构）。 |
+| **`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`**（按记录）或写入返回判断。
+
+---
+
+## 2. `kind` 枚举（CLI 对外）
+
+内部写入类别经归并后形成下表 **`kind`**（与 `qingflow` 当前实现一致；升级后请以 **`record schema … --json` 实跑** 为准）：
+
+| CLI `kind` | 维护侧常见内部类别（参考） | 在 `record list` / `record get` / `record access` 中（常见） | insert/update 写入值 |
+|------------|-----------------------------------|--------------------------------------------|----------------------------------|
+| **`scalar`** | `scalar_text`、`boolean_label`、`date_string` 及未映射类型默认归此 | 多为 **字符串或数字** JSON 标量；布尔/日期常以 **展示字符串** 出现；**地址**题在精简里常仍归 **scalar**，写入时按 **地址对象/分段**（见创建记录文档） | **字符串 / 数字 / 布尔** 等；具体以后端预检为准 |
+| **`select`** | `single_select`、`multi_select` 合并为同一 kind（**§3.1**） | **单选**：与选项同文案的字符串；**多选**：字符串数组或实现可识别的列表 | **单选**：**`options` 中某一元素的字符串**（或实现接受的选项对象）；**多选**：**数组** |
+| **`member`** | `member_list` | 常为人类可读名；或对象（含 id、邮箱等，随租户配置） | 优先自然语言字符串，如 `"张三"`；`needs_confirmation` 时按候选改显式对象，如 `{"uid":1048599,"name":"沈嘉慧Seth","email":"..."}` |
+| **`department`** | `department_list` | 部门名或 id 形态 | 优先自然语言字符串，如 `"直销部"`；`needs_confirmation` 时按候选改显式对象/id |
+| **`relation`** | `relation_record`（**§3.2**） | 常为关联展示字段或 `apply_id` 相关信息 | **`apply_id`**、可解析对象或自然语言；多匹配会返回 `needs_confirmation`，需选候选后重试 |
+| **`attachment`** | `attachment_list` | URL、文件名或结构化附件对象 | **`{"value"或"url", "name"?}`**；常需 **`builder file upload-local` 先上传** |
+| **`address`** | `address_parts`（**对外 `kind` 常被映射进 `scalar`**，以实跑为准） | 对象或分段地址 | **省/市/区/detail 对象** 或 **有序片段数组**（见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**） |
+| **`subtable`** | `subtable_rows` | **行数组**；行内键为子列 title | **行数组**；行内 **`title → 值`**；更新行可带 **`row_id`/`__row_id__`**（见实现） |
+| **`unsupported`** | `unsupported_direct_write`（**§3.4、§3.5**） | 只读/仅流程内填写等 | **勿直接写入**；预检会 `UNSUPPORTED_WRITE` / 类似 blockers |
+
+说明：
+
+- **单选/多选**在对外 `kind` 上 **同是 `select`**；以 **`options` 是否存在 + 业务语义** 区分；多选写入用 **数组**。  
+- **`scalar`** 是 **桶类型**：文本、数字、金额、日期、布尔等在对外展示上常同为 `scalar`，**具体校验以后端与预检为准**。  
+- **`field_id=0`** 等系统列可能为 **`system`+只读**；不要写入 insert/update payload（见创建文档「系统维护字段」）。
+
+---
+
+## 3. 特殊字段详解（选项联动、关联、引用、受限类型）
+
+本节对应轻流里常见的 **「选项」「选项联动」「关联记录」「引用/数据联动」** 等；CLI 侧大多仍落在 **`kind=select` / `relation` / `scalar` + 只读** 等组合上，需结合 **预检** 理解。
+
+### 3.1 选项字段（单选 / 多选）
+
+| 概念 | CLI 表现 | 读写注意 |
+|------|----------|----------|
+| **单选** | 内部题类型常为 **10、11**；对外 **`kind=select`**，多带 **`options` 字符串列表** | **列表/详情**：常为与选项 **完全一致** 的展示文案。写入：传 **`options` 中某项字符串**（或预检接受的选项对象） |
+| **多选** | 内部题类型常为 **12、15**；对外仍为 **`kind=select`**（与单选 **同名 kind**） | **列表/详情**：常为 **字符串数组** 或可解析的多值结构。写入：传 **JSON 数组**（每个元素对应一个选项值） |
+| **区分单多选** | 精简 schema **仅有 `kind`+`options`** | 以 **表单配置 / 同一 `title` 在别处的表现 / 写入预检** 为准；**唯一写入层面**的硬规则是：**多选必须按数组传** |
+
+**选项联动（控制显隐、必填等）**  
+
+- 实现上来自 **题目关系 + 选项上的联动题 id**（如其它题因当前选项而被激活）。  
+- **`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 关联字段（关联记录）
+
+| 概念 | CLI 表现 | 读写注意 |
+|------|----------|----------|
+| **关联记录** | 内部题类型 **25**；对外 **`kind=relation`** | Schema 常含 **`target_app_key`**，以及可选 **`searchable_fields`**（在 **被关联应用** 侧参与检索的字段线索） |
+| **列表/详情** | 多为 **展示用字符串** 或结构化片段（以租户配置为准） | 不要猜测 `apply_id`；从 **关联列表 / 人工指定 / 预检返回的候选** 取得 |
+| **写入 payload** | 「选中一条被关联记录」 | 优先传可被唯一解析的自然语言（如客户名/项目名）或 `{"apply_id":"..."}`；**多匹配** 时易出现 **待确认候选** 或 **阻断**（按返回 `confirmation_requests` / `blockers` 处理） |
+
+**`needs_confirmation`**：表示工具没有写入（`write_executed=false`），只是返回候选。成员、部门、关联字段都可能触发；应从 `confirmation_requests[].candidates[]` 选一个候选对象/id 重试，成功后再报告最终结果。
+
+### 3.3 「引用」与数据填充（非独立 `kind`）
+
+产品里的 **「引用」** 常指：**本题由其它题（选项、关联、成员等）通过规则自动带出**，对应表单元数据中的 **引用/填充配置**。
+
+| 现象 | 建议 |
+|------|------|
+| 目标列 **只读** 或预检判定 **只能通过上游带出** | **不要**在 payload 里强行赋值；改 **上游题**（选项、关联、`relation`、`member` 等），让服务端重算 |
+| 目标列 **`kind` 仍是 `scalar` / `select`** | **「引用」不是单独对外 `kind`**；是否可手填以 **`writable` / 预检 / `record schema update`** 为准 |
+| 需要联动说明 | 非精简 schema 中可能出现 **`linkage`** 类结构（如引用链角色）；**当前 CLI `--json` 精简常去掉 `linkage`**，以 **实跑预检错误信息** 与 **表单设计** 为准 |
+
+**公式、默认值**：若题目由 **公式或默认规则** 计算，常与 **只读 / 系统题** 同类处理，以 **`UNSUPPORTED_WRITE`、`READONLY_OR_SYSTEM_FIELD`** 等预检结果为准。
+
+### 3.4 受限或禁止直写的类型（实现约定）
+
+下列为 **当前 CLI 写入规范化实现** 中的典型 **`unsupported_direct_write`**（对外 **`kind=unsupported`**），**不要依赖 CLI 直接构造复杂载荷**：
+
+| 内部 `que_type`（维护参考） | 含义（简述） |
+|-----------------------------|--------------|
+| **14** | **时间区间** 等：需要后端原生结构，CLI 侧不承诺拼装正确 |
+| **34** | **图像识别**（运行时 AI） |
+| **35** | **AI 生图**（运行时 AI） |
+| **36** | **文档解析**（运行时 AI） |
+
+**处置**：改在 **轻流界面 / 流程节点** 中产生这些值；或缩小 payload 仅写 **不受支持的题之外** 的字段。
+
+### 3.5 其它 layout / 展示类
+
+内部 **24** 等为 **布局/说明** 类题，通常 **不出现在可写字段** 中；若误入 payload，以预检 **`unsupported`** / **`readonly`** 为准剔除即可。
+
+---
+
+## 4. 与 `field_id` / 列选择
+
+
+- **`record list --column`**：参数为 **数字列 id**，用于样本/候选列表展示列，须与 **`fields[].field_id`** 一致。
+- **`record get`**：默认读取前端详情页首屏上下文；不要把 `--column` 当成详情字段投影主路径，单条字段、首屏日志、引用、图片/文件资产以 `record_get` 的结构化上下文为准。若用户要完整数据日志/流程日志历史，用 `record logs`。
+- **标题重复**：同一 `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. **数据分析**：最终统计结论、分析报告、趋势/排名/比例/分布必须走 **`qingflow-record-analysis` 的 `record_access -> 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）。
+
+---
+
+*维护：`kind` 集合与精简字段以当前 CLI 的 `record schema … --json` 实跑为准；内部 `que_type` 枚举随轻流版本变化，文档只稳定描述对外 **`kind`** 桶。*

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

@@ -0,0 +1,195 @@
+# 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)**。
+> **可选补充**：同一目录 **[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)**；最终统计结论统一使用 **`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`。
+
+---
+
+## 最短路径：普通成员「只读记录数据」
+
+> **目标**：直接使用当前 CLI 会话，用**最少 RPC、无多余子命令**，走到 `**record list` 成功返回样本/候选 JSON**；找应用用 `**app list [--query 关键词]`**，在读数前**不必**调用 `auth whoami` / `workspace get` / `view get` / `record schema browse`（除非你另需结构、query field 或排障）。
+
+### 调用次数
+
+
+| 前置           | 命令数    | 说明                                       |
+| ------------ | ------ | ---------------------------------------- |
+| 从零选应用        | **3**  | `app list` → `app get` → `record list`   |
+| 已知 `APP_KEY` | **2**  | `app get` → `record list`                |
+| 排障           | **+1** | 业务命令明确提示会话不可用、账号不确定时，再追加 `auth whoami` |
+
+
+### 固定写法（复制后只换占位符）
+
+```bash
+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>
+```
+
+大 JSON 按规范 **重定向落盘**（`> tmp/qingflow_records.json`）。
+
+### 先有通路、再要有数据
+
+
+| 关注点         | 说明                                                                                                                                                                       |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **连通性优先**   | 从 `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** 上取样。
+
+### 为何不再多调这些
+
+
+| 不先调                                | 原因                                                       |
+| ---------------------------------- | -------------------------------------------------------- |
+| `workspace get` / `workspace list` | 读应用记录**不依赖**；徒增一次往返，且 list 在部分环境受 **59004** 等影响。         |
+| `view get`                         | `**record list` 不前置要求**；读后仍要看 `app get` 给的 `view_id` 才稳。 |
+| `record schema browse`             | 只读「有哪些列」才需要；纯拉数据 **list 足够**。                            |
+
+
+---
+
+## 1. 优先使用（成员场景下实测高概率 exit 0）
+
+
+| 场景                      | 命令                                                                               | 说明                                                                                                                             |
+| ----------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| CLI 版本                  | `qingflow --version`；需要 JSON 用 `qingflow --json version`                         | 不依赖登录，不需要先查 npm 安装路径。                                                                                                     |
+| 帮助                      | `qingflow -h`、`qingflow record schema browse -h`                                 | 嵌套子命令勿整体加引号。                                                                                                                   |
+| 身份与租户                   | `qingflow --json auth whoami`                                                    | 用 `selected_ws_id` / `selectedWsId` 当作当前工作区。                                                                                   |
+| 工作区只读                   | `qingflow --json workspace get --ws-id <WS_ID>`                                  | `WS_ID` 与 whoami 一致最稳。                                                                                                         |
+| 工作区枚举                   | `qingflow --json workspace list --page 1 --page-size 40`                         | 若遇 59004（流币等），仍可依赖 whoami + `workspace get`。                                                                                   |
+| 应用发现                    | `qingflow --json app list [--query <关键词>]`                                                       | 成员通常可看「有权限的应用」列表；`--query` 只在可见应用中本地过滤。                                                                                                              |
+| 应用详情                    | `qingflow --json app get --app-key <APP_KEY>`                                    | 从 `data.accessible_views`（或顶层兼容结构）取 `**view_id`**；同源可取 `**package_id` / `package**`，供 `builder package get`。                   |
+| 用户侧视图只读                 | `qingflow --json view get --view-id <VIEW_ID>`                                   | 用于补充视图配置，不是 `record list` 前置；业务记录读取仍以 `app get.accessible_views` 中的可读表格类视图为准；解析 app 只看同源 view/form 与可见应用树，不走旧应用搜索。                                    |
+| 门户                      | `qingflow --json portal list`、`qingflow --json portal get --dash-key <DASH_KEY>` | `items` 常在 `data.items` 中取 `dash_key`。                                                                                         |
+| Record 元数据（多只需 app-key） | `qingflow --json record schema insert --app-key <APP_KEY>` 等                  | 新建记录用 `insert` schema；`import` / `code-block` 仅在对应专项场景使用；`applicant` 仅兼容保留，不作为推荐入口。                                                                                         |
+| Record 带视图              | 见下节 **「view-id 选取」**                                                             | `browse` / `list` / `access` 必须 `--view-id`。                                                                                  |
+| 待办列表                    | `qingflow --json task list --app-key <APP_KEY> --page 1 --page-size 50`          | 无待办时也可能 **0 条但 exit 0**；`task get` / `task log` / `task report` 需有效 `**task_id`**（及必要的 `report_id`），**无待办则无 id 可测**（非 CLI 错误）。 |
+| Builder（只读且成员常可用）       | `qingflow --json builder member search --query <关键词>`                            | `**--query` 必填**（服务端）。                                                                                                         |
+| Builder 发布自检            | `qingflow builder publish verify --app-key <APP_KEY>`                     | builder 校验命令自动 JSON，相对安全。                                                                                                                     |
+| 应用包读取                   | `qingflow --json builder package get --package-id <整数>`                          | `**package_id` 必须以 `app get`（等）返回为准**；偶发占位 id 在某环境可读**不可依赖**，换应用/包即可能失败。                                                       |
+
+
+---
+
+## 2. `view-id` 选取（成员必读）
+
+`app get` 返回的 `accessible_views` **顺序上第一个**未必有数据读权限：**部分** `custom:*` 在基本成员下对 `schema browse` / `record list` 会返回 `**backend_code=40038`（如 `Object not exist`）**；**另有部分** `custom:*`（例如名称「我的数据」类）可与系统视图一样 **exit 0**，须按 **具体 `view_id`** 判断（见下「按视图探测」）。待办/已办/抄送属于任务中心语义，不再作为业务记录读取首选。
+
+**特例（务必区分）：** `**custom:` 后仅为数字**（`custom:1`、`custom:12` 等）在普通成员会话下 **不适合作为读数备选**（三命令实测 **一致 40038**）；可读业务数据时请加用 **非纯数字后缀的 `custom:…`**（如 `custom:ebdl…`）或 `**system:*` / 本节策略**切换，勿与「部分 custom 不可用」泛泛混为一谈。
+
+建议策略：
+
+1. 优先选择 `system:all` 或名称明确的表格类 `custom:*` 业务视图来确认 `record list` 能通；若 `items` 为空，先判断当前视图筛选是否导致为空，再换其它表格类视图。若某个显式 `view_id` 返回权限或服务端错误，不要在同一次调用里把它自动改成其它系统视图；需要换视图时重新从 `app get.accessible_views` 或前端 URL 选。
+2. `**custom:` 后仅数字**的 id（如 `**custom:1`、`custom:12`**）：**普通成员不可用其读数**，与策略 1 并行时**直接跳过**，不要在「换视图」时误选。
+3. `view get` 只用于补充视图配置/导出能力，不是 `record list` 的前置条件；拉数以 `app get.accessible_views` 选出的 `view_id` 为准。
+
+**按视图探测**：对同一 `app_key` 下 `**custom:<纯数字>` 之外**的 `view_id` 按需跑 `**record schema browse` / `list`** 筛通路。实测：`custom:1/2/12` 均 **40038**；`custom:ebdl…`「我的数据」可用；系统视图可用。
+
+---
+
+## 3. 成员常见「命令写对仍失败」（不要当 CLI 坏了）
+
+
+| 命令/场景                                  | 典型现象                                                          | 含义（成员）                                                                                         |
+| -------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| 旧应用搜索入口                           | `backend_code=40002`                                          | 工作区级搜索常无权限；改用 `**app list --query`** 或 `**app list`** 选应用。                                                           |
+| `import template` / `import verify`    | `IMPORT_TEMPLATE_UNAUTHORIZED`、`IMPORT_AUTH_PRECHECK_FAILED`  | 非应用导入管理员。                                                                                      |
+| `import status` 仅 `--app-key`          | `IMPORT_STATUS_AMBIGUOUS`                                     | 无最新唯一导入记录或无权解析。                                                                                |
+| `builder role search`                  | `ROLE_SEARCH_FAILED` / `backend_code=40002`                   | 搭建侧角色检索对成员常关闭。                                                                                 |
+| `chart get` 随意 id                      | `network` / 报表类错误                                             | 需**真实且有权**的 `chart-id`（从应用/门户配置取）。                                                             |
+| `**custom:1`、`custom:2`…（冒号后仅数字）** 上读数 | 基本成员 **不可用**上述 id 作主数据源；实测 **browse/list/access→40038**（见上文） | **不要**把它们当作「换一个 custom 试试」；应换同一应用下其它表格类业务视图，如 `system:all` 或 `custom:` 后缀含字母等（如 ebdl…）的视图；任务箱请走 `task list --task-box` |
+| 某非标 `custom:*` 上 `record …`            | `40038` / `Object not exist`（exit 4）                          | 该成员对该视图无权限；换**同一应用**下其它 `**view_id`**（见上文排除规则）。                                                |
+| `record get`                           | 需 list 里出现 `record_id`                                        | 若当前视图下列表无数据，则**无 id 可测**（与权限无关时的空结果）。                                                          |
+| `workspace select`                     | `59004`                                                       | 流币/AI 配额与操作类型相关，与其他失败区分。                                                                       |
+| 本会话未展开                                 | `auth login` / `use-credential`、写操作                           | 与角色无关的**命令形态**见通用表；成员仍可能因业务策略无法写。                                                              |
+
+
+---
+
+## 4. 仍建议避免的写法（与通用表一致）
+
+
+| 错误                                                            | 原因                                                            |
+| ------------------------------------------------------------- | ------------------------------------------------------------- |
+| `record list` 无 `--view-id`                                   | `CONFIG_ERROR` / `requires view_id`。                          |
+| **用 `custom:1`、`custom:12`** 等（`custom:` 后**仅数字**）作普通成员的主读数视图 | 实测 **browse/list/access 一律 40038**，与业务空数据不同，**换源时请跳过**该类 id。 |
+| `builder member search` 无 `--query`                           | `MEMBER_QUERY_REQUIRED`。                                      |
+| `builder role search` 无 `--keyword`                           | `ROLE_QUERY_REQUIRED`（有参数也可能因权限仍失败）。                          |
+
+
+---
+
+## 5. 扩展链路（含 workspace / schema）
+
+若你还要 **核对当前工作区** 或 **先看 browse 字段**，在 **§「最短路径」** 之外可增加（顺序仍建议 **先最短再扩展**）。注意：最终统计结论、分析报告、趋势/排名/比例/分布必须使用 `qingflow-record-analysis` 的 `record_access -> Python/pandas`：
+
+```bash
+qingflow --json auth whoami  # 仅业务失败、账号不确定或需要写清当前租户上下文时
+# 记下 selected_ws_id → WS_ID
+
+qingflow --json workspace get --ws-id <WS_ID>   # 仅当需要写清「当前租户上下文」时
+
+qingflow --json app list
+qingflow --json app get --app-key <APP_KEY>
+# accessible_views：优先表格类业务视图；若无业务行再换其它 view（勿用 custom:+纯数字，见前文）
+
+qingflow --json record schema browse --app-key <APP_KEY> --view-id <VIEW_ID>   # 需要字段结构时
+qingflow --json record list --app-key <APP_KEY> --view-id <VIEW_ID>
+```
+
+大数据请按团队规范 **重定向落盘**。
+
+---
+
+## 6. 与其它文档的关系
+
+
+| 文档                                                                               | 用途                                                                             |
+| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| [SKILL.md](../SKILL.md)                                                          | **主文档**：认证、落盘规则、正文「命令速查」与高危操作节选。                                                                     |
+| [QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./QINGFLOW_CLI_ADMIN_CHEATSHEET.md)        | **导入 / `builder role search` 等**管理向差异与成员侧失败对照。                                                        |
+| [QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md](./QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md)     | 可选：全角色通用；各节「一次可复制」命令块与附录必败清单。                                                                     |
+
+
+---
+
+*修订时请同步：若服务端权限枚举或 CLI 改名，以 `qingflow … -h` 与实测为准。*
+
+---
+
+## 7. 验证清单（维护者）
+
+以下结论来自 **基本成员** 会话与 help/实测归纳；配额、权限与数据为空等属环境差异：**换账号时请自行复验**。
+
+
+| 主张                                                                                                                | 说明                                                                                                                                                |
+| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| §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`，除非另行需要。 |
+| 本文未逐条自动化验证的项                                                                                                      | `task get`/`log`/`report`（缺 id）、`chart get`（缺真实 id）、**写路径** `record insert` 等 — 按通用表与业务策略，需有数据/权限时再测                                              |

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

@@ -0,0 +1,159 @@
+# Qingflow CLI 各场景「一次即可跑通」命令速查表
+
+> **面向普通/基本成员账号时**：更易踩 **应用搜索/import/角色检索** 等权限类失败，请先读 **[QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./QINGFLOW_CLI_MEMBER_CHEATSHEET.md)**（策略与最短读数路径）；**管理向差异**参阅 **[QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./QINGFLOW_CLI_ADMIN_CHEATSHEET.md)**。
+
+> **本文档目的**：按**场景**给出**形态正确、参数闭合**时的命令模板，便于复制后替换占位符即跑，减少「缺参 / 引号 / 根级选项」类返工。  
+> **不是**「任何账号、任何租户、任何时刻都 100% HTTP 200」——若遇 `59004`（流币/AI 配额）、401、或目标资源不存在，仍可能失败；那种情况属于**环境与权限**，不是本表要解决的「命令写对一次成」问题。
+
+**统一建议**
+
+- 自动化读取命令优先加 `**--json`**；builder 写入/apply 命令默认只输出 JSON，不需要额外选择格式；展示写入结果时优先读 `operation + summary + resources[]`，不要按不同工具分别解析旧字段。
+- 需要稳定 profile 时加 `**--profile default`**（或与你的会话一致的名字）。
+- `task` / `record` 的大 JSON 查询类输出，按团队规范**落盘**（例如 `> tmp/qingflow_*.json`），本表为简洁只写核心参数。
+
+---
+
+## 1. 元：版本与帮助（不依赖登录）
+
+
+| 场景        | 一次成功写法                                                   | 说明                                           |
+| --------- | -------------------------------------------------------- | -------------------------------------------- |
+| 查 CLI 包版本 | `qingflow --version` | 不依赖登录；只输出版本号。 |
+| 查 CLI 包版本（JSON） | `qingflow --json version` | 不依赖登录；返回 `version` 与 `package`。 |
+| 看顶层能力     | `qingflow -h`                                            | 确认子命令集合。                                     |
+| 看某子命令帮助   | `qingflow <子命令> -h` 或 `qingflow record schema browse -h` | 嵌套子命令**不要**整体加引号。                            |
+
+
+---
+
+## 2. 会话恢复（仅业务命令失败后使用）
+
+
+| 场景                 | 一次成功写法                                    | 必填/注意                                                                                                        |
+| ------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| 查看当前会话             | `qingflow --json auth whoami`             | 仅在业务命令提示会话不可用、账号不确定或需要排障时使用；不要作为每个任务的首步。                                                       |
+| Credential 登录（自动化） | `echo "$QINGFLOW_CREDENTIAL"              | qingflow --profile default auth use-credential --base-url "$QINGFLOW_BASE_URL" --credential-stdin --persist` |
+| 安全退出               | `qingflow auth logout --forget-persisted` | 需要清本机持久化凭证时用。                                                                                                |
+
+
+---
+
+## 3. 工作区（只读优先，避免误切租户）
+
+
+| 场景          | 一次成功写法                                                   | 必填/注意                                                                                 |
+| ----------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| 当前会话工作区详情   | `qingflow --json workspace get --ws-id <WS_ID>`          | `**<WS_ID>`** 与 `auth whoami` 中选中租户一致最稳；**不依赖**先 `workspace list`（list 在部分环境会因配额等失败）。 |
+| 枚举工作区（可选）   | `qingflow --json workspace list --page 1 --page-size 40` | 可能因配额等失败；失败时仍以 **whoami + workspace get** 为基准。                                        |
+| 切换工作区（会改会话） | `qingflow workspace select --ws-id <WS_ID>`              | **必填** `--ws-id`；可能触发 **59004**；自动化探针若不想改租户应**不调用**。                                  |
+
+
+---
+
+## 4. 应用与门户/视图/报表（只读）
+
+
+| 场景           | 一次成功写法                                                               | 必填/注意                                                             |
+| ------------ | -------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| 列出应用         | `qingflow --json app list`                                           | 通常仅需有效会话。                                                         |
+| 成员侧按关键字找应用 | `qingflow --json app list --query <关键词>` | 只读取当前用户可见应用并本地过滤；看 `matched_count` / `unfiltered_count` / `items[].app_key`。 |
+| 应用详情（含可访问视图） | `qingflow --json app get --app-key <APP_KEY>`                        | **必填** `--app-key`；后续 **view-id** 多从返回的 `accessible_views` 等字段选取。 |
+| 门户列表         | `qingflow --json portal list`                                        | 一般只读。                                                             |
+| 单个门户         | `qingflow --json portal get --dash-key <DASH_KEY>`                   | **必填** `--dash-key`。                                              |
+| 用户侧视图        | `qingflow --json view get --view-id <VIEW_ID>`                       | **必填** `--view-id`（与用户态 id 一致，勿与 builder 的 `view-key` 混用）。        |
+| 用户侧图表        | `qingflow --json chart get --chart-id <CHART_ID>`                    | **必填** `**chart-id` 合法且有权访问**。                                    |
+
+
+---
+
+## 5. 记录：`record`（区分「仅需 app-key」与「必须 view-id」）
+
+下面「一次成功」指 **CLI 不会因缺参报错**；服务端仍可能因权限返回错误 JSON。
+
+
+| 场景                      | 一次成功写法                                                                                    | 必填/注意                                                         |
+| ----------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| 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>` | 仅在导入或代码块任务明确需要时使用。 |
+| 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。 |
+
+
+**高风险写操作**（本表不保「业务上你希望的一次成功」，只列形态）：`record insert/update/delete`、`record code-block-run`（可能写回）需按 `-h` 逐项带齐文件类参数与安全开关。
+
+---
+
+## 6. 待办 `task`（查询类建议落盘）
+
+
+| 场景   | 一次成功写法                                                                    | 必填/注意                                                                                   |
+| ---- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| 待办列表 | `qingflow --json task list --task-box todo --flow-status all --page 1 --page-size 50` | 不限定应用时不要硬塞 `--app-key`；已知应用后再追加 `--app-key <APP_KEY>` 收窄。 |
+| 待办详情 | `qingflow --json task get --task-id <TASK_ID>`                            | `<TASK_ID>` 必须来自 `task list` 的 `data.items[].task_id`；不要使用列表序号、record_id、workflow_node_id 或自行拼三键。 |
+| 流程日志 | `qingflow --json task log --task-id <TASK_ID>`                            | 需有效 `**task-id`** 或等价组合。                                                                |
+| 关联报表 | `qingflow --json task report --task-id <TASK_ID> --report-id <REPORT_ID>` | `**report-id`** 需有效。                                                                    |
+| 执行动作 | `qingflow task action --task-id <TASK_ID> --action <ACTION> ...`          | **无 `--dry-run`**；属写操作，慎跑。                                                              |
+
+
+---
+
+## 7. 导入 `import`（链式；单步「一次成」条件）
+
+
+| 场景     | 一次成功写法                                                                       | 必填/注意                                                                                                                                                                   |
+| ------ | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 拉模板说明等 | `qingflow --json import template --app-key <APP_KEY>`                        | 常需应用管理类权限。                                                                                                                                                              |
+| 校验文件   | `qingflow --json import verify --app-key <APP_KEY> --file-path <LOCAL_FILE>` | **必须** `--file-path`，且文件须为服务端**支持的导入模板格式**；随意占位文件可能被 `IMPORT_FILE_FORMAT_UNSUPPORTED`。                                                                                  |
+| 导入状态查询 | `qingflow --json import status --app-key <APP_KEY>`                          | **仅能三选一**：`--process-id-str` / `--import-id` / `**--app-key`**（独自表示读该应用**最新导入**）；混搭多个选择器易被拒。**仅 `--app-key` 且无唯一「最新导入」时**可出现 `IMPORT_STATUS_AMBIGUOUS`（与是否管理员无关，属数据状态）。 |
+
+
+更后序的 `repair` / `start` 依赖前置返回的 `**verification-id`** 等，按 `import -h` 逐级带参。
+
+---
+
+## 8. Builder（只列「必填闭合即过 CLI」的常用只读）
+
+
+| 场景    | 一次成功写法                                                       | 必填/注意                             |
+| ----- | ------------------------------------------------------------ | --------------------------------- |
+| 成员搜索  | `qingflow --json builder member search --query <关键词>`        | `**--query` 服务端必填**（帮助里可能看起来像可选）。 |
+| 角色搜索  | `qingflow --json builder role search --keyword <关键词>`        | `**--keyword` 必填**。               |
+| 应用包列表 | `qingflow --json builder package list --query <关键词>`          | 直接走 `/tag`；返回 `items[].package_id/package_name/permissions`。 |
+| 应用包读取 | `qingflow --json builder package get --package-id <整数>`      | `**package-id` 须为整数**。            |
+| 发布自检  | `qingflow builder publish verify --app-key <APP_KEY>` | builder 写入/校验类命令自动 JSON。                       |
+
+
+`builder * apply` / `role create` / `package apply` / `solution install` 等为写路径，成功与否强依赖配置文件与租户策略，**不放入「默认一次必成」表**。
+
+---
+
+## 9. 必败反例（避免浪费时间）
+
+
+| 错误写法                                                | 原因                                              |
+| --------------------------------------------------- | ----------------------------------------------- |
+| `qingflow record list --app-key xxx`（无 `--view-id`） | 运行时常报错：`requires view_id`。                      |
+| `"qingflow record schema browse" --app-key ...`     | 子命令被整体加引号，解析器不认。                                |
+| `builder member search`（无 `--query`）                | 常见：`MEMBER_QUERY_REQUIRED` / query is required。 |
+| `builder role search`（无 `--keyword`）                | 常见：`ROLE_QUERY_REQUIRED`。                       |
+| `import status` 同时丢多个互斥 selector                    | 见上文「三选一」。                                       |
+
+
+---
+
+## 10. 最小业务链路示例（Wingent Momo runtime 下不做登录前置）
+
+在满足账号权限的前提下：
+
+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_records.json`。只有业务命令明确返回会话不可用、账号不确定或工作区异常时，才回到第 2 节做会话恢复。
+
+---
+
+*文档生成说明：与 **[../SKILL.md](../SKILL.md)**、[QINGFLOW_CLI_EXPLORATION_REPORT.md](./QINGFLOW_CLI_EXPLORATION_REPORT.md) 对齐；若 CLI 版本升级，请以 `qingflow … -h` 为准做小步修订。*

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

@@ -0,0 +1,20 @@
+# Qingflow CLI：创建记录 SOP（申请节点）
+
+---
+
+**创建记录 SOP 见 skill：`qingflow-record-insert`。**
+
+CLI 对应主路径：
+
+```bash
+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
+```
+
+不要用 `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`。
+
+录入数据时不要填写轻流系统字段：`数据ID`、`编号`、`申请人`、`申请时间`、`创建人`、`创建时间`、`提交人`、`提交时间`、`更新时间`、`更新人`、`当前流程状态`、`当前处理人`、`当前处理节点`、`流程标题`。这些字段由平台生成；需要确认时在创建成功后读取记录详情，不要把它们写进 `fields` / `items[].fields`。