@qingflow-tech/qingflow-cli 1.1.2 → 1.1.34

package/skills/qingflow-cli/reference/core/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)**；最终统计结论统一使用 **[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`。
+
+---
+
+## 最短路径：普通成员「只读记录数据」
+
+> **目标**：直接使用当前 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 字段**，在 **§「最短路径」** 之外可增加（顺序仍建议 **先最短再扩展**）。注意：最终统计结论、分析报告、趋势/排名/比例/分布必须使用 [record/analysis](../record/analysis/README.md) 的 `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/core/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>`                             | 新建记录默认走 [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>` | 仅在导入或代码块任务明确需要时使用。 |
+| Schema：browse（浏览态字段）    | `qingflow --json record schema browse --app-key <APP_KEY> --view-id <VIEW_ID>`            | **必须 `--view-id`**；不要用引号包住 `record schema browse` 整段。         |
+| 列表/候选定位（运行时强校验）           | `qingflow --json record list --app-key <APP_KEY> --view-id <VIEW_ID>` | **必须 `--view-id`**；默认最多返回 10 条，适合样本/模糊定位；可加 `--query` / `--query-field`。 |
+| 分析取数                    | `qingflow --json record access --app-key <APP_KEY> --view-id <VIEW_ID> --columns-file columns.json --where-file where.json` | 最终统计结论统一使用 [record/analysis](../record/analysis/README.md) 的 `record access -> Python/pandas`。 |
+| 单条读取                    | `qingflow --json record get --app-key <APP_KEY> --record-id <RECORD_ID>`                  | **必须** `--record-id`；返回前端详情页首屏上下文、引用、图片/文件资产。 |
+| 全量记录日志                | `qingflow --json record logs --app-key <APP_KEY> --record-id <RECORD_ID> [--view-id <VIEW_ID>]` | 仅在需要完整审计/日志历史时使用；全量数据日志和流程日志写本地 JSONL。 |
+
+
+**高风险写操作**（本表不保「业务上你希望的一次成功」，只列形态）：`record 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/examples/README.md

@@ -0,0 +1,17 @@
+# Builder Example Files
+
+Use these files as copyable bases after reading the matching resource document. Replace placeholder ids, app keys, field names, and chart/view ids before applying.
+
+| Resource | Main example | Notes |
+|----------|--------------|-------|
+| Single app schema | [schema/schema_single_app_form_standard.example.json](./schema/schema_single_app_form_standard.example.json) | `--form-file` shape; fields and form rows together. |
+| Multi-app schema | [schema/schema_multi_app_form_relation_layout.example.json](./schema/schema_multi_app_form_relation_layout.example.json) | `--apps-file` shape; same-batch relation and layout. |
+| Existing-app layout | [layout/layout_sections_full.example.json](./layout/layout_sections_full.example.json) | Existing-app maintenance only. New apps use `form`. |
+| Views | [views/views_upsert_table_minimal.example.json](./views/views_upsert_table_minimal.example.json), [views/views_batch_full.example.json](./views/views_batch_full.example.json) | `views[]` shape with filters, query panel, view-bound buttons, batch upsert/patch/remove. |
+| Charts | [charts/charts_upsert_dashboard_starter.example.json](./charts/charts_upsert_dashboard_starter.example.json) | Standalone chart apply; portal usually creates missing charts inline. |
+| Portal | [portal/portal_sections_standard_workbench.example.json](./portal/portal_sections_standard_workbench.example.json) | Standard workbench with inline QingBI charts and data views. |
+| Associated resources | [associated/associated_resources_semantic_full.example.json](./associated/associated_resources_semantic_full.example.json) | Current-record matching through `match_mappings`. |
+| Record insert | [record/record_insert_all_field_types.example.json](./record/record_insert_all_field_types.example.json) | `record insert --items-file` shape for common field kinds; replace all titles/options/ids from `record schema insert`. |
+| Advanced standalone buttons | [buttons/custom_buttons_advanced.example.json](./buttons/custom_buttons_advanced.example.json) | For maintenance only; normal business buttons are declared in views. |
+
+Probe files such as `portal_sections_all_types.example.json` and `schema_apply_add_fields_all_types.json` are for capability testing, not default business delivery.

package/skills/qingflow-cli/reference/examples/associated/associated_resources_semantic_full.example.json

@@ -0,0 +1,50 @@
+{
+  "upsert_resources": [
+    {
+      "client_key": "customer_orders",
+      "graph_type": "view",
+      "target_app_key": "ORDER_APP_KEY",
+      "view_key": "ORDER_VIEW_KEY",
+      "title": "当前客户订单",
+      "match_mappings": [
+        {
+          "target_field": "关联客户",
+          "operator": "eq",
+          "source_field": "数据ID"
+        },
+        {
+          "target_field": "订单状态",
+          "operator": "in",
+          "values": ["执行中", "待回款"]
+        }
+      ]
+    },
+    {
+      "client_key": "customer_payment_chart",
+      "graph_type": "chart",
+      "target_app_key": "PAYMENT_APP_KEY",
+      "chart_id": "PAYMENT_CHART_ID",
+      "title": "当前客户回款统计",
+      "match_mappings": [
+        {
+          "target_field": "关联客户",
+          "operator": "eq",
+          "source_field": "数据ID"
+        },
+        {
+          "target_field": "回款状态",
+          "operator": "neq",
+          "value": "作废"
+        }
+      ]
+    }
+  ],
+  "view_configs": [
+    {
+      "view_key": "CUSTOMER_DETAIL_VIEW_KEY",
+      "mode": "merge",
+      "associated_item_refs": ["customer_orders", "customer_payment_chart"],
+      "limit_type": "custom"
+    }
+  ]
+}

package/skills/qingflow-cli/reference/examples/buttons/custom_buttons_advanced.example.json

@@ -0,0 +1,56 @@
+{
+  "upsert_buttons": [
+    {
+      "client_key": "open_sop",
+      "button_text": "打开SOP",
+      "style_preset": "text_blue",
+      "trigger_action": "link",
+      "trigger_link_url": "https://example.com/sop"
+    },
+    {
+      "client_key": "create_acceptance",
+      "button_text": "创建验收单",
+      "style_preset": "primary_blue",
+      "trigger_action": "addData",
+      "trigger_add_data_config": {
+        "target_app_key": "ACCEPTANCE_APP_KEY",
+        "field_mappings": [
+          {
+            "source_field": "数据ID",
+            "target_field": "关联工单"
+          }
+        ],
+        "default_values": {
+          "验收状态": "待验收"
+        }
+      }
+    }
+  ],
+  "view_configs": [
+    {
+      "view_key": "WORK_ORDER_VIEW_KEY",
+      "mode": "merge",
+      "buttons": [
+        {
+          "button_ref": "open_sop",
+          "placement": "header",
+          "primary": false
+        },
+        {
+          "button_ref": "create_acceptance",
+          "placement": "detail",
+          "primary": true,
+          "button_limit": [
+            [
+              {
+                "field_name": "工单状态",
+                "operator": "eq",
+                "value": "已完工"
+              }
+            ]
+          ]
+        }
+      ]
+    }
+  ]
+}

package/skills/qingflow-cli/reference/examples/charts/charts_remove.example.json

@@ -0,0 +1 @@
+["CHART_ID_TO_DELETE"]

package/skills/qingflow-cli/reference/examples/charts/charts_reorder.example.json

@@ -0,0 +1 @@
+["CHART_ID_FIRST", "CHART_ID_SECOND"]

package/skills/qingflow-cli/reference/examples/charts/charts_upsert_bar.example.json

@@ -0,0 +1,8 @@
+[
+  {
+    "name": "示例柱状图",
+    "chart_type": "bar",
+    "group_by": ["REPLACE_WITH_DIMENSION_FIELD_NAME"],
+    "metric": "sum(REPLACE_WITH_NUMERIC_FIELD_NAME)"
+  }
+]

package/skills/qingflow-cli/reference/examples/charts/charts_upsert_dashboard_starter.example.json

@@ -0,0 +1,118 @@
+[
+  {
+    "name": "数据总量",
+    "chart_type": "target",
+    "metric": "count(*)",
+    "visibility": {
+      "mode": "workspace",
+      "selectors": {},
+      "external_mode": "not",
+      "external_selectors": {}
+    }
+  },
+  {
+    "name": "进行中数量",
+    "chart_type": "target",
+    "metric": "count(*)",
+    "filters": [
+      {
+        "field_name": "REPLACE_WITH_STATUS_FIELD_NAME",
+        "operator": "eq",
+        "value": "进行中"
+      }
+    ],
+    "visibility": {
+      "mode": "workspace",
+      "selectors": {},
+      "external_mode": "not",
+      "external_selectors": {}
+    }
+  },
+  {
+    "name": "重点类型数量",
+    "chart_type": "target",
+    "metric": "count(*)",
+    "filters": [
+      {
+        "field_name": "REPLACE_WITH_TYPE_FIELD_NAME",
+        "operator": "in",
+        "values": ["重点", "高优先级"]
+      }
+    ],
+    "visibility": {
+      "mode": "workspace",
+      "selectors": {},
+      "external_mode": "not",
+      "external_selectors": {}
+    }
+  },
+  {
+    "name": "本月金额合计",
+    "chart_type": "target",
+    "metric": "sum(REPLACE_WITH_AMOUNT_FIELD_NAME)",
+    "filters": [
+      {
+        "field_name": "REPLACE_WITH_DATE_FIELD_NAME",
+        "operator": "gte",
+        "value": "2026-07-01"
+      },
+      {
+        "field_name": "REPLACE_WITH_DATE_FIELD_NAME",
+        "operator": "lte",
+        "value": "2026-07-31"
+      }
+    ],
+    "visibility": {
+      "mode": "workspace",
+      "selectors": {},
+      "external_mode": "not",
+      "external_selectors": {}
+    }
+  },
+  {
+    "name": "按状态分布",
+    "chart_type": "bar",
+    "group_by": ["REPLACE_WITH_STATUS_FIELD_NAME"],
+    "metric": "count(*)",
+    "filters": [
+      {
+        "field_name": "REPLACE_WITH_STATUS_FIELD_NAME",
+        "operator": "not_empty"
+      },
+      {
+        "field_name": "REPLACE_WITH_STATUS_FIELD_NAME",
+        "operator": "neq",
+        "value": "已作废"
+      }
+    ],
+    "visibility": {
+      "mode": "workspace",
+      "selectors": {},
+      "external_mode": "not",
+      "external_selectors": {}
+    }
+  },
+  {
+    "name": "按时间趋势",
+    "chart_type": "line",
+    "group_by": ["REPLACE_WITH_DATE_FIELD_NAME"],
+    "metric": "count(*)",
+    "filters": [
+      {
+        "field_name": "REPLACE_WITH_NAME_FIELD_NAME",
+        "operator": "contains",
+        "value": "示例关键词"
+      },
+      {
+        "field_name": "REPLACE_WITH_CLOSE_DATE_FIELD_NAME",
+        "operator": "is_empty"
+      }
+    ],
+    "visibility": {
+      "mode": "workspace",
+      "selectors": {},
+      "external_mode": "not",
+      "external_selectors": {}
+    }
+  }
+]