@qingflow-tech/qingflow-cli 1.1.2 → 1.1.34

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

@@ -10,11 +10,81 @@
       "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": {},
@@ -27,6 +97,17 @@
     "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": {},

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

@@ -0,0 +1,94 @@
+# Qingflow CLI 管理员命令速查表（Skill Reference）
+
+> **适用**：`qingflow --json auth whoami` 中具备 **租户/工作区级管理、应用检索、导入、搭建配置** 等权限的账号（如 **超级管理员、应用管理员** 等，`permission_level` 以服务端为准）。
+> **与普通成员对照**：权限较窄时请用 **[QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./QINGFLOW_CLI_MEMBER_CHEATSHEET.md)**；**主流程与落盘规则**以 **[SKILL.md](../../SKILL.md)** 为准。需要 **全子命令「一次可复制」逐项模板**时可参阅同目录 **[QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md](./QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md)**（任选，默认执行技能不必打开）。
+
+---
+
+## 1. 元与安装
+
+
+| 场景        | 命令                                               | 备注                                  |
+| --------- | ------------------------------------------------ | ----------------------------------- |
+| 查 CLI 包版本 | `qingflow --version`；需要 JSON 用 `qingflow --json version` | 不依赖登录，不需要先查 npm 安装路径 |
+| 帮助        | `qingflow -h`、`qingflow record schema browse -h` | 嵌套子命令勿整体加引号                         |
+
+
+---
+
+## 2. 会话与工作区
+
+
+| 场景            | 命令                                                              |
+| ------------- | --------------------------------------------------------------- |
+| 当前身份与租户       | `qingflow --json auth whoami` → `selected_ws_id`                |
+| 工作区详情         | `qingflow --json workspace get --ws-id <WS_ID>`                 |
+| 枚举工作区         | `qingflow --json workspace list --page 1 --page-size 40`        |
+| **切换租户**（改会话） | `qingflow workspace select --ws-id <WS_ID>`（可能 **59004** 流币/配额） |
+
+
+---
+
+## 3. 应用与门户（管理侧常用）
+
+
+| 场景                     | 命令                                                                 | 管理员说明                              |
+| ---------------------- | ------------------------------------------------------------------ | ---------------------------------- |
+| 列表 / 关键字搜索                     | `qingflow --json app list [--query <词>]`                                         | 通用；`--query` 只过滤当前用户可见应用                                 |
+| 详情（含 accessible_views） | `qingflow --json app get --app-key <APP_KEY>`                      | 正文常在 JSON 的 `**data**` 包裹内         |
+| 门户                     | `qingflow --json portal list`、`portal get --dash-key <DASH_KEY>`   | `dash_key` 多在 `data.items`         |
+
+
+---
+
+## 4. 记录数据
+
+与 **[成员速查](./QINGFLOW_CLI_MEMBER_CHEATSHEET.md)** 及 **[SKILL.md](../../SKILL.md)**「命令速查」一致：`record schema browse`、`record list`、`record access` **必须** `--view-id`。查询类遵守 **SKILL 落盘**：`record list`、`get`、`access`、`schema browse` 等。最终统计结论、分析报告、趋势/排名/比例/分布统一使用 **[record/analysis](../record/analysis/README.md) 的 `record access -> Python/pandas`**。
+
+---
+
+## 5. 待办
+
+同 SKILL：`task list`、`get`、`log`、`report` 查询输出 **必须落盘**。`task action` **无 `--dry-run`**。
+
+---
+
+## 6. 导入（偏应用管理员）
+
+
+| 步骤     | 命令                                                                           | 备注                                                                |
+| ------ | ---------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| 模板说明   | `qingflow --json import template --app-key <APP_KEY>`                        | **常需应用管理权限**（成员常为 UNAUTHORIZED）                                   |
+| 校验上传文件 | `qingflow --json import verify --app-key <APP_KEY> --file-path <FILE>`       | 文件须**服务端支持的模板格式**，否则 `**IMPORT_FILE_FORMAT_UNSUPPORTED`**         |
+| 状态     | `qingflow --json import status [--app-key | --import-id | --process-id-str]` | **三选一**；仅 `--app-key` 且无唯一「最新导入」时可能 `**IMPORT_STATUS_AMBIGUOUS`** |
+
+
+链路后续依赖 `verification-id`，见 `qingflow import -h`。
+
+---
+
+## 7. Builder
+
+**只读、管理会话下常见可用**：
+
+
+| 命令                                                           | 必填                                    |
+| ------------------------------------------------------------ | ------------------------------------- |
+| `qingflow --json builder member search --query <关键词>`        | `--query`                             |
+| `qingflow --json builder role search --keyword <关键词>`        | `--keyword`（成员常 `ROLE_SEARCH_FAILED`） |
+| `qingflow --json builder package list [--query <关键词>]`       | 直接读取应用包列表；看 `items[].package_id` |
+| `qingflow --json builder publish verify --app-key <APP_KEY>` | —                                     |
+| `qingflow --json builder package get --package-id <整数>`      | 整数，`package-id` 来自上下文                 |
+
+
+写路径：`role create`、`package apply`、`solution install`、`flow apply`、各类 `*-apply` — **无 universal dry-run**，慎用。
+
+---
+
+## 8. 必败反例
+
+与 **[QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./QINGFLOW_CLI_MEMBER_CHEATSHEET.md)** 常见踩雷、**[SKILL.md](../../SKILL.md)**「命令速查」末段「必败形态」一致；**逐条 CLI 形态表**另见 **[QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md](./QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md)** §9：`record list` 缺 `view-id`、子命令错引号、builder 缺 query/keyword、`import status` 多 selector。
+
+---
+
+*修订：以 `qingflow … -h` 与 **MEMBER**、[QINGFLOW_CLI_EXPLORATION_REPORT.md](./QINGFLOW_CLI_EXPLORATION_REPORT.md) 对齐。*

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

@@ -0,0 +1,139 @@
+# Qingflow CLI：获取数据工作流（应用记录）
+
+> **用途**：使用当前 CLI 会话，从「选定应用」到「读懂列含义 + 样本/模糊定位 / 单条详情」的**推荐闭环**；下表 **左列**可与常见 **编排/内部接口**命名对照，**右列**仅为本 CLI 命令。
+> **新版口径**：`record_list` 不是批量分析入口，而是样本浏览和模糊定位入口；`record_get` 是前端详情页首屏上下文入口；全量日志用 `record logs`；分析取数统一转 [record/analysis](../record/analysis/README.md) 的 `record access -> Python/pandas`。
+> **关联**：权限、`view_id` 选取雷区、成员最短路径速查见 **[QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./QINGFLOW_CLI_MEMBER_CHEATSHEET.md)**；**字段 `kind` / 数据类型**见 **[QINGFLOW_CLI_FIELD_DATA_TYPES.md](./QINGFLOW_CLI_FIELD_DATA_TYPES.md)**；**新建记录**见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](../record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**；**更新记录**见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](../record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**；最终统计结论统一使用 **[record/analysis](../record/analysis/README.md) 的 `record access -> Python/pandas`**；主技能规则见 **[../SKILL.md](../../SKILL.md)**。
+
+---
+
+## 概念步骤 → 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`。
+- **需要分组/聚合统计、最终统计结论、分析报告、趋势/排名/比例/分布**时，必须按 **[record/analysis](../record/analysis/README.md)** 执行 `app get -> record schema browse -> 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/core/QINGFLOW_CLI_EXPLORATION_REPORT.md

@@ -0,0 +1,84 @@
+# Qingflow CLI 当前版本审计备忘
+
+> 本文件只记录当前 CLI 与 skill 主路径容易混淆的事实。它不是执行 SOP；具体任务仍按 [SKILL.md](../../SKILL.md) 与对应专题 reference 执行。CLI 升级后优先重新跑 `qingflow ... --help` 复核。
+
+---
+
+## 1. 当前能力树摘要
+
+- 顶层：`qingflow {auth|workspace|app|portal|view|chart|record|import|export|task|builder|build} ...`
+- `builder` 与 `build` 等价；默认写法仍推荐 `builder`。
+- `record schema`：公开主路径为 `browse`、`insert`、`update`、`import`、`code-block`；`applicant` 仅为兼容保留入口，不作为推荐链路。
+- `record` 公开执行入口：`list`、`access`、`get`、`logs`、`insert`、`update`、`delete`、`code-block-run`。
+- 最终统计结论统一按 [record/analysis](../record/analysis/README.md) 走 `record access -> Python/pandas`，不要寻找或使用其它聚合捷径。
+
+---
+
+## 2. 不要被 `--help` 方括号误导
+
+部分参数在 argparse 帮助中看起来可选，但运行时由工具层或后端强制要求：
+
+| 命令 | 实际要求 |
+| --- | --- |
+| `app list` | 可选 `--query` / `--keyword`，只在当前用户可见应用中本地过滤 |
+| `builder package list` | 可选 `--query`，直接读取 Builder 应用包 `/tag` 列表并本地过滤 |
+| `record schema browse` | 必须 `--app-key` + `--view-id` |
+| `record list` | 必须 `--app-key`；业务记录读取应显式给 `--view-id` |
+| `record access` | 必须 `--app-key` + `--view-id` |
+| `builder member search` | 必须 `--query` |
+| `builder role search` | 必须 `--keyword` |
+
+自动化里读取命令优先使用根级 JSON 形态：`qingflow --json ...`；builder 写入/apply 命令默认只输出 JSON，不需要额外选择格式。builder apply 响应统一优先读 `operation + summary + resources[]`，其中 `resources[].id/key/name/ids/parent` 是 UI/智能体展示资源的稳定入口；旧字段只作兼容和排障。查 CLI 包版本直接用 `qingflow --version`；需要结构化输出时用 `qingflow --json version`。
+
+---
+
+## 3. Record 当前口径
+
+| 入口 | 当前定位 |
+| --- | --- |
+| `record list` | 样本浏览 / 模糊定位候选；默认最多返回 10 条，返回 `data.pagination.total_count`，带 `--query` 时看 `lookup.total_count` 与 `lookup.next_action` |
+| `record access` | 默认分析取数入口；自动分页写本地 CSV；不暴露 `page/page_size/limit/max_rows/profile` |
+| `record get` | 前端详情页首屏上下文；字段、引用、首屏数据日志、首屏流程日志、关联资源、`media_assets`、`file_assets` |
+| `record logs` | 单条记录全量可见数据日志 + 流程日志；自动分页写本地 JSONL，响应给路径和完整性 |
+| `record insert` | 批量 `items` JSON；单条也是 `items` 数组一行；CLI 用 `--items-file` |
+| `record update` | 单条 `--record-id + --fields-file` 或批量 `--items-file`；不要混用 |
+
+`record_get` 下载到本地的图片读 `media_assets.items[].local_path`；文档、表格、PDF 等读 `file_assets.items[].local_path` 与 `extraction.text_path`。不要直接访问远端 Qingflow 附件 URL。
+
+---
+
+## 4. Builder 当前口径
+
+| 入口 | 当前定位 |
+| --- | --- |
+| `builder app get` | 应用地图；轻量返回字段摘要、视图、图表、自定义按钮、关联资源池 |
+| `builder schema apply` | 字段/新建应用；多应用应用包用 `--apps-file`，同批 `relation` 用 `target_app_ref`；新建应用必须有且仅有一个 `as_data_title: true`；封面用顶层 `attachment` 字段 `as_data_cover: true` |
+| `builder views apply` | 业务视图；固定筛选写 `filters`，前端查询栏写 `query_conditions` |
+| `builder button apply` | 自定义按钮默认路径；新增数据按钮用 `field_mappings/default_values`，绑定位置用 `header/detail/list` |
+| `builder associated-resource apply` | 应用级关联视图/报表池 + 视图展示配置；报表来源用 `report_source`，不让智能体填写后端 raw source |
+| `builder charts apply` | QingBI 报表配置；报表变更 immediate-live，不等同于应用发布 |
+| `builder publish verify` | 发布后核验应用状态 |
+
+按钮和关联资源 apply 有成功写入时会自动发布；没有成功写入、全阻断或全失败时不应额外发布。
+
+---
+
+## 5. ID 口径
+
+| 名称 | 用途 |
+| --- | --- |
+| `view_id` | 用户态记录读取，形如 `system:all` 或 `custom:<viewKey>`；来自 `app get.accessible_views` |
+| `view_key` | Builder 视图配置；用于 `builder view get`、`builder views apply`、按钮/关联资源视图配置 |
+| `chart_id` / `chart_key` | 报表本体 ID/key；不可直接当作视图关联资源 ID |
+| `associated_item_id` | 应用级关联资源项 ID，即后端 `form_asos_chart.id`；视图展示关联资源时必须用它 |
+
+普通成员读数时，`custom:` 后仅数字的视图（如 `custom:1`、`custom:12`）常见 40038，应跳过并换 `system:all` 或其它表格类 `custom:*`。
+
+---
+
+## 6. 错误判断
+
+- `59004` 多与额度/流币/AI 配额相关，不等同于未登录。
+- `40002` 常是成员权限不足，尤其是角色检索、部分管理向操作；按关键词找应用优先用 `app list --query`。
+- `record list/access requires view_id` 不是数据为空，是缺少视图上下文。
+- 大 JSON 记录/任务查询仍建议落盘到 `tmp/...json` 后再读，不要直接塞入模型上下文；builder 写入/apply 工具默认直接 stdout，前端展示时优先解析 `resources[]`，需要留档时使用 `tee`。builder 读取命令仍显式加 `--json`。

package/skills/qingflow-cli/reference/core/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](../record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**；更新流程见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](../record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**；只读见 **[QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](./QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**；**搭建侧** **`app_schema_apply` 的 `type`（与本文 `kind` 命名体系不同）**见 **[30-schema-fields.md](../builder/30-schema-fields.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](../record/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`，**具体校验以后端与预检为准**。数字/金额能否写小数以 insert/update schema 的 `expected_format`、`example_value` 和实际错误为准；不要仅凭字段标题或 builder `number` 推断可写 decimal。
+- **`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` / 联动明细；新建记录以 [record/insert](../record/insert/README.md) 的 `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. **数据分析**：最终统计结论、分析报告、趋势/排名/比例/分布必须走 **[record/analysis](../record/analysis/README.md) 的 `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`** 桶。*