@josephyan/qingflow-cli 1.0.11 → 1.1.2

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

@@ -0,0 +1,304 @@
+# Builder 视图创建与变更 SOP：`qingflow builder views apply`
+
+稳定命令：**`qingflow builder views apply`**（别名 **`qingflow build views apply`**）。编写前已结合 **builder 契约**与实现要点整理；**最小可用 `upsert` 文件**见 **[views_upsert_table_minimal.example.json](./views_upsert_table_minimal.example.json)**（与门户/报表 **`.example.json`** 同风格）。已对应用 **`ead8ims5i401`** **实跑**该文件。
+
+> **权限**：视图**新建**走后端 `createViewgraphConfig`，需要同时满足 **视图管理 / ViewManagementAuth**（`beingViewManageStatus`）和 **数据管理 / DataManageAuth**；视图**更新/删除**只走 **ViewManagementAuth**。未开启高级应用权限时 `beingViewManageStatus` 等价回落到 **DataManageAuth**。失败时常见 **40002 / 40161 / 编辑锁**，参见主技能与 **ADMIN** 速查。
+
+> **默认系统视图**：`全部数据`、`我的数据`、`我发起的`、`待办`、`已办`、`抄送` 等由轻流自带，**不要新建同名业务视图**。新建视图必须用业务名，例如 `项目台账视图`、`客户跟进视图`、`逾期任务看板`。如果确实要调整默认系统视图，只能从 `app get views` 取已存在的 raw **`view_key`** 后用 `patch_views` 或带 `view_key` 的 `upsert_views` 更新。
+
+> **契约**（权威键名、枚举、`execution_notes`、示例）：  
+> `qingflow --json builder contract --tool-name app_views_apply`  
+> （`--tool-name` 为契约索引，用于拉取 **`allowed_keys` / 别名 / 示例**。）
+> 契约示例若带 `"profile"`，不要复制到 `--upsert-views-file`；CLI 指定 profile 用根级 `qingflow --profile …`。
+
+---
+
+## 1. 推荐操作顺序（读 → 写 → 校验）
+
+| 步骤 | 动作 | CLI |
+|------|------|-----|
+| ① 读应用地图 | 先看 compact views/charts/buttons/associated resources | `qingflow --json builder app get --app-key <APP_KEY>` |
+| ② 读字段/视图 | 确认 **`columns`** / `query_conditions` 可用字段、核对 **`view_key`** | `qingflow --json builder app get --app-key <APP_KEY> fields` / `qingflow --json builder app get --app-key <APP_KEY> views` |
+| ③ 准备补丁 JSON | 写入 **`upsert_views` / `remove_views`** 数组文件（见 §3） | — |
+| ④ 应用视图补丁 | 执行 apply | `qingflow builder views apply …`（写入命令自动 JSON，默认直接 stdout；需要留档时用 `tee`） |
+| ⑤ 涉及关联/按钮 | 用专项 apply，不把它们塞进 view patch | `builder associated-resource apply` / `builder button apply` |
+| ⑥ 需要上线时 | 发布侧校验 | `qingflow builder publish verify --app-key …` |
+
+**说明**：`views apply` 的 **`--publish`** 对应契约里的 **`publish`**；自动化可先 **`--no-publish`**，与 schema/layout 改完再 **`publish verify`** 的节奏一致，见 **[QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)** 的发布校验章节。
+
+---
+
+## 2. CLI 形态
+
+```bash
+qingflow builder views apply \
+  --app-key "<APP_KEY>" \
+  [--publish | --no-publish] \
+  [--upsert-views-file PATH] \
+  [--remove-views-file PATH]
+```
+
+- **`--upsert-views-file`** / **`--remove-views-file`**：各为 **JSON 数组**文件，与实现里 `load_list_arg` 一致；可只传其一或两者兼有。
+- 输出默认直接给 stdout，前端可直接读取；需要留档时用 `qingflow builder views apply … | tee tmp/builder_views_apply.json`。
+
+---
+
+## 2.1 参考示例文件（与门户 / 报表同风格）
+
+| 文件 | 用途 |
+|------|------|
+| [views_upsert_table_minimal.example.json](./views_upsert_table_minimal.example.json) | **新建 table 视图**最小 **`upsert_views` 数组**：`name` + `type` + **`columns`**（字段 **显示名**，须来自 **`builder app get --app-key … fields`**） |
+
+**本仓实测**（`ead8ims5i401`，`--no-publish`）：使用文件内 **`columns`**（`单行文字`、`多行文字`）与视图 **`name`** **`示例表视图_CLI模板`** 可 **`status: success` 创建**。复制到其他应用前务必 **`app get fields`** 替换 **`columns`**；**`name`** 重名时会 **更新** 已有同名视图而非新建（见 **§4**）。
+
+---
+
+## 3. 请求体形状（与契约对齐）
+
+CLI 将参数与文件内容拼装为服务层载荷，**顶层键**如下：
+
+| 键 | 说明 |
+|----|------|
+| **`app_key`** | 必填 |
+| **`publish`** | 是否顺带发布语义（与 **`--publish` / `--no-publish`** 一致） |
+| **`upsert_views`** | 补丁对象数组（见 §4～§6） |
+| **`remove_views`** | 删除项数组（见 §7） |
+
+**别名**（契约 `aliases` 节选）：**`fields` / `column_names` → `columns`**；**`view_key` / `viewKey`**；**`tableView`→`table`**、**`kanban`→`board`** 等；**`filter_rules`→`filters`**；**`startField`→`start_field`** 等。
+
+---
+
+## 4. 创建 vs 更新（`view_key` 与 `name`）
+
+服务逻辑概要：
+
+- **`remove_views`**：可传 raw **`view_key`** 或视图 **显示名 `name`**；显示名重名则 **`AMBIGUOUS_VIEW`**，须改用 `view_key`。
+- **`upsert_views`**：
+  - 若提供 **`view_key`**：对该视图做 **更新**（含类型变更等，仍受后端约束）。
+  - 未提供 **`view_key`**：若 **`name` 唯一** 匹配已有视图 → **更新**；否则 → **创建**。
+
+响应中的 **`verification.by_view[].status`** 会出现 **`created` / `updated`** 等；**`views_diff`** 汇总创建/更新/失败名单。
+
+**`partial_success`**：部分视图成功、部分失败时整体仍可能带成功信封，务必读 **`failed`** 与 **`execution_notes`**。
+
+**系统默认名禁止新建**：未提供 `view_key` 的 `upsert_views` 不要使用 `全部数据`、`我的数据`、`我发起的`、`待办`、`已办`、`抄送` 这类默认系统视图名。它们不是业务视图模板，而是平台默认对象；新业务视图用具体业务名。
+
+---
+
+## 5. `type` 与各类型必填
+
+契约 **`view.type`**：**`table`** | **`card`** | **`board`** | **`gantt`**。
+
+| `type` | 列/字段要点 | 类型专属键 |
+|--------|----------------|------------|
+| **`table`** | **`columns`**（业务字段 **显示名**，须能在 **`app get fields`** 里找到） | — |
+| **`card`** | 同 table | — |
+| **`board`**（看板） | 列；且须 **`group_by`**（分组字段名） | **`group_by`** |
+| **`gantt`** | 列；须 **`start_field`**、**`end_field`**（通常为日期类字段名） | 可选 **`title_field`** |
+
+实现侧校验：对 **table/card**，若声明了 **`columns`**，在 **过滤系统列**后须 **至少保留一个**真实应用字段，否则报错——**不能**只用系统列名凑一列（系统列集合见 **[QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md) §7.1**）。
+
+---
+
+## 6. `filters` / `query_conditions` / `visibility` / `buttons`
+
+### 6.1 `filters`
+
+- 项形状：**`field_name`**、**`operator`**、**`values`**（或契约允许的 **`value`** 别名）。
+- **`operator`**：统一公共语义，推荐 `eq` / `neq` / `in` / `contains` / `gte` / `lte` / `is_empty` / `not_empty`；兼容 `equal` / `equals` / `=` / `!=` / `any_of` / `one_of` / `empty` 等别名（以契约为准）。
+- **`in` 等多值**：传 **列表**；**`value`** 为列表时可作别名。
+- **语义**：固定筛选条件，打开视图即生效。不要把前端查询栏字段写进 `filters`。
+- **内部编译**：视图、按钮显示条件、工作流条件会由 CLI 自动编译成 Qingflow 数字 `judgeType`，智能体不要手写 `judgeType` / `judgeValues`。
+
+示例：
+
+```json
+{"field_name": "状态", "operator": "eq", "value": "进行中"}
+```
+
+### 6.2 `query_conditions`
+
+`query_conditions` 是前端“查询条件/查询栏”配置，和 `filters` 是两套语义：
+
+- `filters`：固定筛选，打开视图即生效。
+- `query_conditions`：只配置前端查询面板可输入哪些字段；用户输入查询值后才生效。
+- `rows` 是字段布局矩阵，不表示 OR 条件。
+- `rows` 只放前端查询面板支持的字段：文本、长文本、数字、金额、日期/时间、单选/多选、成员、部门、手机号、邮箱、布尔。
+- 不要把 relation、attachment、subtable/subfield、address、Q-Linker 或 code-block 字段放进 `query_conditions`。
+- 需要固定筛选时用 `filters`；需要关联报表/关联视图按当前记录匹配时用 `builder associated-resource apply` 的 `match_mappings`。
+
+示例：
+
+```json
+{
+  "name": "客户查询视图",
+  "type": "table",
+  "columns": ["客户名称", "负责人", "客户状态", "创建时间"],
+  "filters": [
+    {"field_name": "客户状态", "operator": "eq", "value": "有效"}
+  ],
+  "query_conditions": {
+    "enabled": true,
+    "exact": false,
+    "hide_before_query": false,
+    "rows": [["客户名称", "负责人"], ["创建时间"]]
+  }
+}
+```
+
+读回验证时，不要只看视图是否存在；要看 `verification.view_query_conditions_verified=true`。若返回 query condition mismatch，只能说视图已创建/更新，但查询条件未完全验证。
+
+### 6.3 `visibility`
+
+与包/应用/视图等 **授权形态一致**（契约 **`visibility.mode`**：`workspace` | `everyone` | `specific`；**`external_mode`**：`not` | `workspace` | `specific`；**`selectors` / `external_selectors`** 键集合见契约）。
+
+- **更新已存在视图**：省略 **`visibility`** 可 **保留**当前后端权限。
+- **名称类 selector**：须 **唯一解析**，否则失败（不猜测）。
+
+### 6.4 `buttons`（兼容路径）
+
+新版默认不要通过 `app_views_apply.buttons` 配置自定义按钮。按钮本体、字段映射、默认值和头部/详情/列表位置统一走 **`app_custom_buttons_apply`** / CLI **`builder button apply`**。
+
+- `button_ref` 可以是同次按钮的 `client_key`，也可以是已有 `button_id`。
+- `view_configs[].view_key` 使用 raw `view_key`，不要加 `custom:`。
+- `view_configs[].mode` 默认 `merge`；merge 模式必须带 `buttons`，不要只传 `view_key`。清空绑定用 `mode: "replace"` 或显式 `buttons: []`。
+- 对外入参仍写 `placement=list`；CLI 会映射为后端 `INSIDE` 行内/列表按钮。
+- 按钮显示条件 `button_limit` 使用统一条件写法：`field_name + operator + value/values`。不要手写后端 `judgeType` / `judgeValues`。
+- 权限分界：按钮本体增删改需要 **EditAppAuth**；只要同次包含 `view_configs` 写视图按钮位置，还需要 **ViewManagementAuth**（未开启高级应用权限时回落到 **DataManageAuth**）。
+
+`app_views_apply.buttons` 仅作为旧配置维护兼容：
+
+- **省略**：保留现有按钮配置。
+- **`buttons: []`**：清空旧按钮配置。
+- **非空数组**：对旧按钮配置做全量替换。
+
+### 6.5 关联视图/报表
+
+新版默认不要通过 `app_views_apply.associated_resources` 配置关联资源。应用级关联资源池和视图展示开关统一走 **`app_associated_resources_apply`** / CLI **`builder associated-resource apply`**。
+
+- `builder views apply` **新建视图时默认开启详情页关联查看**：等价于 `asosChartVisible=true`、`limit_type=all`，会展示当前应用级关联资源池里的全部关联视图/报表。
+- **更新已有视图**：未显式传 `associated_resources` 时保留原关联查看状态；需要关闭或改成指定资源时，用 **`builder associated-resource apply --view-configs-file`**，或维护旧配置时显式 patch `associated_resources`。
+- 已有资源的最终口径是 `app_get.associated_resources[].associated_item_id`；它不是 `chart_id`、`chart_key` 或 `view_key`。
+- 新版 CLI 在关联报表时可先传 `chart_id` / `chart_key`，内部会解析为轻流后端需要的 id；创建前先检查是否已有相同 `target_app_key + view_key/chart_key`，已存在时用 `patch_resources`；`client_key` 只在同一次 apply 中可被 `associated_item_refs` 引用，不会持久化。
+- 数据集 BI 报表只能关联已有报表，使用 `report_source: "dataset"`；应用源报表可先用 `builder charts apply` 创建/更新。
+- 关联筛选优先用 `match_mappings`；字段匹配规则见 **[QINGFLOW_CLI_BUILDER_MATCH_RULES.md](./QINGFLOW_CLI_BUILDER_MATCH_RULES.md)**。
+
+---
+
+## 7. `remove_views`
+
+- 文件内容为 **JSON 数组**；元素可以是 raw **`view_key`**，也可以是唯一视图显示名。
+- 优先用 **`view_key`** 删除；显示名重名会导致 **`AMBIGUOUS_VIEW`**，需先在 **`app get views`** 里确认。
+- DELETE 发出后，工具会用单个 **`view_key`** 回读验证，而不是再读全量视图列表判断删除结果。
+- 删除结果看 **`verification.by_view[].delete_executed`**、**`readback_status`**、**`safe_to_retry_delete`**：
+  - **`readback_status=deleted`**：删除已验证。
+  - **`readback_status=unavailable`** 或 **`still_exists`**：删除请求已发出但回读未完全确认，**不要盲目重复删除**；稍后用 `builder app get views` 或对应视图详情确认。
+
+---
+
+## 8. 契约示例（可复制为文件基底）
+
+**Table + `visibility`（`minimal_example` 节选）**：
+
+```json
+[
+  {
+    "name": "项目台账视图",
+    "type": "table",
+    "columns": ["项目名称"],
+    "visibility": {
+      "mode": "workspace",
+      "selectors": {},
+      "external_mode": "not",
+      "external_selectors": {}
+    }
+  }
+]
+```
+
+**Gantt（`gantt_example` 节选）**：
+
+```json
+[
+  {
+    "name": "项目甘特图",
+    "type": "gantt",
+    "columns": ["项目名称", "开始日期", "结束日期"],
+    "start_field": "开始日期",
+    "end_field": "结束日期",
+    "title_field": "项目名称",
+    "filters": [
+      {
+        "field_name": "状态",
+        "operator": "eq",
+        "value": "进行中"
+      }
+    ]
+  }
+]
+```
+
+**Table + 查询条件（节选）**：
+
+```json
+[
+  {
+    "name": "客户查询视图",
+    "type": "table",
+    "columns": ["客户名称", "负责人", "客户状态", "创建时间"],
+    "query_conditions": {
+      "enabled": true,
+      "exact": false,
+      "hide_before_query": false,
+      "rows": [["客户名称", "负责人"], ["创建时间"]]
+    }
+  }
+]
+```
+
+---
+
+## 9. 实测记录（`ead8ims5i401`，`--no-publish`）
+
+内容与仓库 **[views_upsert_table_minimal.example.json](./views_upsert_table_minimal.example.json)** 一致（或历史探针名 **`CLI探针视图_可删`**）。
+
+**读视图**：
+
+```bash
+qingflow --json builder app get --app-key ead8ims5i401 views
+```
+
+**应用**：
+
+```bash
+qingflow builder views apply \
+  --app-key ead8ims5i401 \
+  --no-publish \
+  --upsert-views-file ./reference/views_upsert_table_minimal.example.json
+```
+
+**结果摘要**（示例视图名 **`示例表视图_CLI模板`**）：`status: success`，`verification.by_view[0].status: created`，返回 **`view_key`**（如 **`ecdk22v65c02`**），`published: false`。
+
+---
+
+## 10. 排障要点
+
+| 现象 | 处理 |
+|------|------|
+| 列校验失败 / 无有效业务列 | **`app get fields`** 核对 **`name`**；避免 `columns` 仅含 **§7.1 系统列** |
+| 重名视图 / 删错 | **`app get views`**；更新时带 **`view_key`** |
+| 过滤器未生效疑虑 | 看响应 **`verification.view_filters_verified`**；必要时再 **`app get views`** |
+| 查询条件未生效疑虑 | 看响应 **`verification.view_query_conditions_verified`**；不要把 `query_conditions` 当 `filters` |
+| 后端 **40038 / Object not exist** | 先读失败项 **`details.per_view_results[].details.field_level_diagnostics`** 与 **`recommended_minimal_retry`**。不要删除字段、不要重建应用；先按最小列重试，再逐步加非关键列/筛选。 |
+| 按钮/关联资源配置 | 按钮走 **`builder button apply`**；关联视图/报表走 **`builder associated-resource apply`** |
+| 部分失败 | 读 **`views_diff.failed`** 与契约 **execution_notes** 中 **partial_success** |
+| 权限/锁 | 同 [交付 SOP](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)（**`publish verify`**、编辑锁） |
+
+---
+
+## 11. 交叉引用
+
+- [views_upsert_table_minimal.example.json](./views_upsert_table_minimal.example.json)（**table** 视图最小 **`upsert`**）
+- [SKILL.md](../SKILL.md)：builder 直接输出、鉴权顺序。
+- [QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)：系统列、**`publish verify`**、整体交付阶段。
+- [QINGFLOW_CLI_EXPLORATION_REPORT.md](./QINGFLOW_CLI_EXPLORATION_REPORT.md)：CLI 覆盖与 **`view_id` vs `view_key`** 备忘。

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

@@ -0,0 +1,41 @@
+# Builder 工作区图标规则
+
+用于应用包、应用、门户的新建与改名改图标场景。
+
+## 默认链路
+
+1. 先读取候选目录：
+
+```bash
+qingflow --json builder icon catalog
+```
+
+2. 新建应用包、应用、门户时，显式填写 `icon` 和 `color`。
+
+3. 不要使用 `template`；这是通用图标，新建资源会被 CLI 阻断。
+
+## 关键规则
+
+- CLI 不会根据业务名称自动猜图标。
+- 智能体必须自己选择业务贴合的图标和颜色；主写法只有 `icon + color`，例如 `"icon": "table", "color": "blue"`。
+- CLI/MCP 继续兼容 `icon_name + icon_color`、`icon_config` 或 `icon: {name, color}`，但这些只用于历史载荷和读回适配，不作为新提示词示例。
+- 创建应用包、应用、门户时缺少 `icon` 或 `color` 会失败。
+- 同批多应用创建时，每个新应用应使用不同 `icon`。
+- 编辑已有资源时，不传 `icon/color` 会保留现状；显式传入时仍会校验合法性。
+- 读取结果里的 `icon_config` 是给 UI/agent 展示用的解构结果，包含 `icon_name`、`icon_color`、`icon_text`、`raw`。
+
+## 示例选择
+
+这些只是候选思路，不是 CLI 默认映射：
+
+| 场景 | 可选 icon |
+|---|---|
+| 员工 / 花名册 | `business-personalcard`、`user-group` |
+| 任务 / 待办 | `clipboard-check`、`action-work` |
+| 工时 / 时间 | `clock`、`action-hourglass-full` |
+| 商机 / 增长 | `business-graph`、`business-trend-up` |
+| 订单 / 交付 | `delivery-box-1`、`shopping-bag` |
+| 回款 / 收款 | `money-receipt-2-1`、`money-wallet-1` |
+| 门户 / 数据大屏 | `view-grid`、`chart-square-bar` |
+
+颜色候选以 `builder icon catalog` 返回为准，例如 `emerald`、`blue`、`azure`、`orange`、`red`。

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

@@ -0,0 +1,139 @@
+# Qingflow CLI：获取数据工作流（应用记录）
+
+> **用途**：使用当前 CLI 会话，从「选定应用」到「读懂列含义 + 样本/模糊定位 / 单条详情」的**推荐闭环**；下表 **左列**可与常见 **编排/内部接口**命名对照，**右列**仅为本 CLI 命令。
+> **新版口径**：`record_list` 不是批量分析入口，而是样本浏览和模糊定位入口；`record_get` 是前端详情页首屏上下文入口；全量日志用 `record logs`；分析取数统一转 `qingflow-record-analysis` 的 `record_access -> Python/pandas`。
+> **关联**：权限、`view_id` 选取雷区、成员最短路径速查见 **[QINGFLOW_CLI_MEMBER_CHEATSHEET.md](./QINGFLOW_CLI_MEMBER_CHEATSHEET.md)**；**字段 `kind` / 数据类型**见 **[QINGFLOW_CLI_FIELD_DATA_TYPES.md](./QINGFLOW_CLI_FIELD_DATA_TYPES.md)**；**新建记录**见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**；**更新记录**见 **[QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)**；最终统计结论统一使用 **`qingflow-record-analysis` 的 `record_access -> Python/pandas`**；主技能规则见 **[../SKILL.md](../SKILL.md)**。
+
+---
+
+## 概念步骤 → CLI 映射
+
+| 习惯概念名（编排/文档） | CLI 等价命令 | 必填要点 |
+| --- | --- | --- |
+| `app_get`（列应用内可访问视图） | `qingflow --json app get --app-key <APP_KEY>` | 从返回体的 **`data`（若存在）** 内取 `accessible_views[]` |
+| `record_schema_get`，`schema_mode=browse` | `qingflow --json record schema browse --app-key <APP_KEY> --view-id <VIEW_ID>` | 子命令 **`browse`** 即「浏览视图」表结构 |
+| `record_list` | `qingflow --json record list --app-key <APP_KEY> --view-id <VIEW_ID> [--query 文本] [--query-field FIELD_ID] [--page-size N]` | 样本浏览 / 模糊定位，默认最多返回 10 条；`query_fields` 是全文搜索字段范围 |
+| `record_get` | `qingflow --json record get --app-key <APP_KEY> --record-id <RECORD_ID> [--view-id <VIEW_ID>]` | 前端详情页首屏上下文：字段、首屏日志、引用、关联资源、图片与文件资产 |
+| `record_logs_get` | `qingflow --json record logs --app-key <APP_KEY> --record-id <RECORD_ID> [--view-id <VIEW_ID>]` | 单条记录全量可见数据日志 + 流程日志；自动分页写本地 JSONL，响应只返回摘要和文件路径 |
+
+**补充**：若尚未持有 `APP_KEY`，先做 `qingflow --json app list [--query <关键词>]`，在 `items[].app_key` 里选应用；带 `--query` 时读取 `matched_count` / `unfiltered_count` 判断是否命中。
+
+---
+
+## 推荐执行顺序
+
+```text
+app get（解析 accessible_views，选定 VIEW_ID）
+  → record schema browse（对齐字段 id/类型/展示名；也是 list/access/get 的视图字段口径）
+  → record list（样本浏览或 query 模糊定位候选）
+  → （可选）record get（对单条 record_id 拉详情页首屏上下文）
+  → （可选）record logs（需要完整审计日志时再拉全量日志 JSONL）
+```
+
+- **仅当你只需要「快速确认有无数据」**时，可以省略 `schema browse`，直接 `app get` → `record list`（与成员速查表「最短路径」一致）。  
+- **当你需要稳定映射列名、写过滤条件或对接自动化**时，应按上表**显式**走 `schema browse`，避免对着 `list` 里中文列名猜字段定义。  
+- **当用户只给出模糊信息定位单条数据**时，走 `record schema browse` 确认可搜索字段，再用 `record list --query ... --query-field ...` 返回候选；只有候选明确后才 `record get`。
+- **需要分组/聚合统计、最终统计结论、分析报告、趋势/排名/比例/分布**时，必须切换到 **`qingflow-record-analysis`**，按 `app_get -> record_browse_schema_get(view_id=...) -> record_access -> Python/pandas -> final answer` 执行。
+
+---
+
+## 命令模板（占位符替换即可）
+
+**1）应用与视图**
+
+```bash
+qingflow --json app get --app-key <APP_KEY> > tmp/qingflow_app_get.json
+```
+
+从 `tmp/qingflow_app_get.json` 解析：`$.data.accessible_views`（无 `data` 时再试顶层 `accessible_views`）。每个元素含 `view_id`、`name`、`kind` 等。
+
+若响应 `warnings[]` 含 `CUSTOM_VIEW_LIST_UNAVAILABLE`，表示 custom view 列表读取被权限或后端限制降级；这不是应用整体不可读。优先使用已返回的 `system:*` 视图继续 `schema browse` / `record list`，或从前端 URL 的 `viewgraphKey` 补充明确 `view_id`。
+
+**2）浏览视图表结构（= `record_schema_get` browse）**
+
+```bash
+qingflow --json record schema browse \
+  --app-key <APP_KEY> \
+  --view-id <VIEW_ID> \
+  > tmp/qingflow_schema_browse.json
+```
+
+实跑样例响应顶层键包含：`status`、`app_key`、`schema_scope`、`fields`、`suggested_dimensions` 等（**以实际 JSON 为准**）。
+
+**3）记录列表**
+
+```bash
+qingflow --json record list \
+  --app-key <APP_KEY> \
+  --view-id <VIEW_ID> \
+  > tmp/qingflow_records.json
+```
+
+列表默认最多返回 10 条，行数据常见于 `$.data.items`；每条一般有 `record_id`（及业务字段键值）。需要调整样本量时加 `--page-size <N>`；它只影响浏览/候选定位样本，不替代分析取数。响应会给出总数/下一步建议；如果是模糊定位，优先看 `lookup.total_count`、`lookup.next_action`。
+
+`record_list.data.items[]` 是**字段平铺行对象**，不是 `fields[]` 数组。定位候选或做名称到记录 ID 映射时直接读字段标题键：
+
+```python
+rows = payload["data"]["items"]
+name_to_record_id = {row["客户名称"]: row["record_id"] for row in rows}
+```
+
+只有 `record_get` 详情使用 `fields[]` 来表示字段列表。
+
+**模糊定位示例**：
+
+```bash
+qingflow --json record list \
+  --app-key <APP_KEY> \
+  --view-id <VIEW_ID> \
+  --query "北京和路元" \
+  --page-size 20 \
+  --query-field 6299262 \
+  > tmp/qingflow_record_lookup.json
+```
+
+`--query-field` 对应 `record_browse_schema_get.fields[].field_id`，表示后端全文搜索范围；它不是输出列控制。
+
+**4）单条记录详情**
+
+```bash
+qingflow --json record get \
+  --app-key <APP_KEY> \
+  --record-id <RECORD_ID> \
+  --view-id <VIEW_ID> \
+  > tmp/qingflow_record_get.json
+```
+
+已知前端视图时必须传同一个 `--view-id`；未知时 CLI 会先试默认详情 route，再在权限/不可见类错误下尝试可访问视图。`record_get` 现在返回详情页首屏上下文，重点看：`fields[]`、`references[]`、`data_logs`、`workflow_logs`、`associated_resources`、`media_assets`、`file_assets`、`semantic_context`。其中 `data_logs` / `workflow_logs` 只表示详情页首屏日志，不是全量审计历史。若 `unavailable_context[]` 中出现 `detail_schema`、`audit_info`、`data_logs`、`workflow_logs` 等，只说明这些辅助详情上下文读取受限；只要顶层 `status=ok` 且 `fields[]` 有目标字段，就不要把辅助 40002 当作记录不可读。图片读 `media_assets.items[].local_path`；文档/表格/PDF 等附件读 `file_assets.items[].local_path` 和 `file_assets.items[].extraction.text_path`。**不要直接访问远端 Qingflow 附件 URL**。
+
+**5）全量日志（仅在用户明确需要完整审计/日志历史时）**
+
+```bash
+qingflow --json record logs \
+  --app-key <APP_KEY> \
+  --record-id <RECORD_ID> \
+  --view-id <VIEW_ID> \
+  > tmp/qingflow_record_logs.json
+```
+
+响应重点看：`data_logs.local_path`、`workflow_logs.local_path`、`items_count`、`pages_fetched`、`complete`、`context_integrity.safe_for_full_log_conclusion`。完整日志在本地 JSONL 文件中，默认目录为 `~/.qingflow-mcp/record-logs/<run_id>/`；不要把 JSONL 全文直接塞进上下文，按需用脚本读取、筛选或汇总。
+
+---
+
+## `view_id` 选取（成员侧必读摘要）
+
+- **`system:all` 等业务系统视图**：实跑可用于 `schema browse` + `record list`（具体以租户配置为准）。显式传入的 `view_id` 必须按前端当前视图忠实执行；`system:all` 报 40002 / 40027 / 404 / 500 时，不要自动换成 `system:initiated`、`system:todo` 等其它系统视图，除非用户或前端 URL / `app get.accessible_views` 重新指定了那个视图。  
+- **`CUSTOM_VIEW_LIST_UNAVAILABLE`**：只说明 `app get` 没能列出 custom view；若已有 `system:*` 可用，不要把它当作应用或记录读取失败。
+- **`custom:` 后仅数字**（如 `custom:1`）：成员侧常见 **`schema browse` / `list` / `access` 均 40038**，应**跳过**，改选 **`custom:` 带字母后缀**或其它可用视图（详见成员速查表「先有通路、再要有数据」）。
+- **待办 / 已办 / 抄送「任务箱」**：不要用旧文档里的 `system:todo` 等视图充当任务中心；应使用 **`task list --task-box …`**（见主技能 **待办 SOP**）。
+
+---
+
+## 落盘与解析
+
+- `schema browse`、`record list`、`record get`、`record logs` 体量大时，**必须**重定向到文件，勿将整段 JSON 直接塞进 LLM 上下文（规则见主技能「输出落盘规则」）。`record_get` 下载的本地图片/文件路径可以再交给图片理解、文档解析或 Python 读取；`record logs` 的全量日志读 `*.jsonl` 文件。
+- 解析前**先 unwrap `data`**：多数业务成功响应为 `{ "data": { ... } }`，与 `schema browse` 部分字段在顶层的形态可能不同，以每次响应为准。
+
+---
+
+*维护：CLI 升级后请用 `qingflow record schema browse -h`、`qingflow record list -h`、`qingflow record get -h`、`qingflow record logs -h` 复核选项名；概念名 `record_schema_get` / `schema_mode=browse` 在 CLI 中固定对应子命令 `record schema browse`。*

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

@@ -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`。
+- 最终统计结论统一由 `qingflow-record-analysis` 走 `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`。