@qingflow-tech/qingflow-cli 1.1.51 → 1.1.54

package/skills/qingflow-cli/reference/data/README.md

@@ -0,0 +1,32 @@
+# Qingflow CLI 直接数据操作
+
+直接查询、读取、新增、更新和删除分别使用：
+
+- `qingflow data query`
+- `qingflow data get`
+- `qingflow data insert`
+- `qingflow data update`
+- `qingflow data delete`
+
+参数、JSON 文件形状和可选项必须来自当前工具 schema、当次 `--help` 或响应字段能力，不得从其他命令推测。
+
+## 字段能力合同
+
+1. 首次操作当前应用时，只通过只读 `data query/get` 请求 `include_schema=true`，读取同一次响应中的 `schema` 与递归 `field_capabilities`；不得用 insert/update 探测能力。
+2. 构造 `where` 时，只使用目标字段 `filter_operators` 实际暴露的 `op`，并匹配对应 `value_shape`；不要在本文复制操作符矩阵。
+3. 写入前优先执行不设置 `columns` 的只读 `data query` 并请求 schema，检查响应中的 `access`，再检查 `insertable`、`updatable` 与 `required_on_insert`。
+4. `write_kind`、schema 与当次 `--help` 共同决定 payload 形状；运行时字段错误和权限结果优先于预检。
+
+## 执行与恢复
+
+- 已知 `app_key` 时直接执行目标业务命令；只有应用名称时先用 `app list --query` 查找并核对 `app_name/title`，目标明确且唯一时取其 `app_key`，否则请用户确认。不能把名称传给 `--app-key`。只有业务命令明确报告会话或工作区错误后才恢复认证上下文。
+- 定位目标记录时先 query，再按需 get。字段只使用当前 schema 与字段能力允许的 id、能力和形状。
+- insert、update、delete 会改变真实业务数据。删除、覆盖已有值或批量写入前，必须确认目标和影响范围。
+- 返回后先检查 `write_executed`、`retry_safe`、字段错误和 hints。已执行、部分成功或状态不明时不得重放原请求。
+- data 命令失败时只修正响应明确指出的问题，不得切换其他数据入口绕过权限或校验。
+
+## 任务分流
+
+- 批量导入：阅读 [批量导入 SOP](../record/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md)。
+- 统计分析：阅读 [数据分析说明](../record/analysis/README.md)，使用 `data query --all --output csv` 并读取全部 CSV 分片。
+- 待办和流程动作：阅读 [任务上下文 SOP](../task/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md)。

package/skills/qingflow-cli/reference/examples/README.md

@@ -7,7 +7,7 @@ Use these files as copyable bases after reading the matching resource document.
 | Historical single-app schema probe | [schema/schema_single_app_form_standard.example.json](./schema/schema_single_app_form_standard.example.json) | Retired `--form-file` shape; use `builder app-form schema/get/validate/apply` for current declarations. |
 | Historical multi-app schema probe | [schema/schema_multi_app_form_relation_layout.example.json](./schema/schema_multi_app_form_relation_layout.example.json) | Retired `--apps-file` shape; current systems create independent AppForms and then bind confirmed app keys. |
 | Existing-app layout probe | [layout/layout_sections_full.example.json](./layout/layout_sections_full.example.json) | Historical layout-patch shape; current new and existing forms use the complete AppForm `spec.body`. |
-| 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. |
+| Views | [views/views_upsert_table_minimal.example.json](./views/views_upsert_table_minimal.example.json), [views/views_apply_v1alpha1.example.json](./views/views_apply_v1alpha1.example.json) | 单视图 JSON 对象，包含筛选、查询面板和视图绑定按钮；通过 `--app-key` 指定应用。 |
 | 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`. |

package/skills/qingflow-cli/reference/examples/views/views_apply_v1alpha1.example.json

@@ -0,0 +1,14 @@
+{
+  "name": "项目台账视图",
+  "type": "table",
+  "columns": [100, 101, 102, 103],
+  "data_permission": {"type": "custom", "scope": "dept"},
+  "sort": [{"que_id": 100, "ascending": false}],
+  "display": {"row_height": "compact", "pin_navigate": true},
+  "query_conditions": {
+    "enabled": true,
+    "exact": false,
+    "hide_before_query": false,
+    "rows": [["项目名称", "负责人"], ["创建时间"]]
+  }
+}

package/skills/qingflow-cli/reference/examples/views/views_upsert_table_minimal.example.json

@@ -1,42 +1,36 @@
 {
-  "views": [
+  "name": "示例业务操作视图_CLI模板",
+  "type": "table",
+  "columns": [100, 101, 102, 103],
+  "filters": [
+    {"que_id": 100, "operator": "neq", "value": "已关闭"}
+  ],
+  "query_conditions": {
+    "enabled": true,
+    "exact": false,
+    "hide_before_query": false,
+    "rows": [["主记录编号", "主记录名称"], ["状态", "负责人"]]
+  },
+  "action_buttons": [
     {
-      "operation": "upsert",
-      "app_key": "APP_KEY",
-      "name": "示例业务操作视图_CLI模板",
-      "type": "table",
-      "columns": ["主记录编号", "主记录名称", "状态", "负责人"],
-      "filters": [
-        {"field_name": "状态", "operator": "neq", "value": "已关闭"}
+      "text": "行内创建子记录",
+      "action": "add_data",
+      "target_app_key": "TARGET_APP_KEY",
+      "field_mappings": [
+        {"source_field": "数据ID", "target_field": "关联主记录"}
       ],
-      "query_conditions": {
-        "enabled": true,
-        "exact": false,
-        "hide_before_query": false,
-        "rows": [["主记录编号", "主记录名称"], ["状态", "负责人"]]
-      },
-      "action_buttons": [
-        {
-          "text": "行内创建子记录",
-          "action": "add_data",
-          "target_app_key": "TARGET_APP_KEY",
-          "field_mappings": [
-            {"source_field": "数据ID", "target_field": "关联主记录"}
-          ],
-          "default_values": {"目标状态字段": "REPLACE_WITH_TARGET_OPTION_LABEL"},
-          "placement": "list"
-        },
-        {
-          "text": "详情创建子记录",
-          "action": "add_data",
-          "target_app_key": "TARGET_APP_KEY",
-          "field_mappings": [
-            {"source_field": "数据ID", "target_field": "关联主记录"}
-          ],
-          "default_values": {"目标状态字段": "REPLACE_WITH_TARGET_OPTION_LABEL"},
-          "placement": "detail"
-        }
-      ]
+      "default_values": {"目标状态字段": "REPLACE_WITH_TARGET_OPTION_LABEL"},
+      "placement": "list"
+    },
+    {
+      "text": "详情创建子记录",
+      "action": "add_data",
+      "target_app_key": "TARGET_APP_KEY",
+      "field_mappings": [
+        {"source_field": "数据ID", "target_field": "关联主记录"}
+      ],
+      "default_values": {"目标状态字段": "REPLACE_WITH_TARGET_OPTION_LABEL"},
+      "placement": "detail"
     }
   ]
 }

package/skills/qingflow-cli/reference/record/QINGFLOW_CLI_RECORD_SPECIALIZED_WORKFLOW.md

@@ -0,0 +1,50 @@
+# Qingflow CLI：record 日志与附件参考
+
+> **适用范围**：任务需要完整数据／流程日志、附件或图片上下文时使用。普通应用数据查询使用 [`data query/get`](../core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)。
+
+## record 查询链
+
+```text
+app get（解析 accessible_views，选定 VIEW_ID）
+  → record schema browse（读取该视图字段口径）
+  → record list（样本浏览或模糊定位候选）
+  → record get（可选：详情页首屏、附件与图片上下文）
+  → record logs（可选：完整数据日志与流程日志）
+```
+
+## 命令形状
+
+```bash
+qingflow --json app get --app-key APP_KEY > tmp/qingflow_app_get.json
+
+qingflow --json record schema browse \
+  --app-key APP_KEY --view-id VIEW_ID \
+  > tmp/qingflow_record_schema.json
+
+qingflow --json record list \
+  --app-key APP_KEY --view-id VIEW_ID \
+  > tmp/qingflow_record_list.json
+
+qingflow --json record get \
+  --app-key APP_KEY --record-id RECORD_ID --view-id VIEW_ID \
+  > tmp/qingflow_record_get.json
+
+qingflow --json record logs \
+  --app-key APP_KEY --record-id RECORD_ID --view-id VIEW_ID \
+  > tmp/qingflow_record_logs.json
+```
+
+`VIEW_ID` 只能来自 `app get.accessible_views`、已经确认的前端 URL 或用户明确提供的上下文。显式视图失败时不要自动换成另一系统视图。
+
+## 专有结果
+
+- `record get`：用于详情页字段、首屏日志、引用、关联资源、`media_assets` 和 `file_assets`。附件与图片优先使用返回的本地路径，不直接访问远端附件 URL。
+- `record logs`：用于完整可见数据日志和流程日志。响应只读取摘要与 JSONL 文件路径，按需筛选本地文件，不把全文放入上下文。
+- `record list`：只在用户明确指定该命令时用于样本浏览／模糊定位，不用于完整统计结论。
+
+## 边界
+
+- 统计分析仍转 `data query --all --output csv -> Python/pandas`。
+- `CUSTOM_VIEW_LIST_UNAVAILABLE` 只说明自定义视图列表读取受限；不要据此断言应用整体不可读。
+- 待办、已办和抄送属于 `task list --task-box ...`，不使用 `record list --view-id system:todo/done/cc`。
+- 所有大 JSON、附件清单和日志摘要必须落盘。

package/skills/qingflow-cli/reference/record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md

@@ -1,7 +1,8 @@
 # Qingflow CLI：更新记录工作流（详情后直接写入）
 
+> **兼容范围**：本文仅限用户明确要求旧 CLI `record` 兼容入口时使用。默认更新必须切换到 [data 操作说明](../data/README.md) 的 `data get` → `data update`；禁止在 data update 失败后自动回退本文链路。
 > **用途**：使用当前 CLI 会话读取目标记录详情后，用 **`record update`** 直接提交差异字段。主链路是 `record get -> record update`；字段范围不清、候选歧义或失败排查时，才追加 **`record schema update`**。
-> **关联**：只读列表/详情见 **[QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](../core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)**；**字段 `kind` 与写入值总表**见 **[QINGFLOW_CLI_FIELD_DATA_TYPES.md](../core/QINGFLOW_CLI_FIELD_DATA_TYPES.md)**；最终统计结论统一使用 **[record/analysis](./analysis/README.md) 的 `record access -> Python/pandas`**；**成员 / 部门等** 的细颗粒写入见 **[QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md](./QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)**；主技能 **[../SKILL.md](../../SKILL.md)**。
+> **关联**：直接数据操作统一使用 [data 操作说明](../data/README.md)；最终统计结论统一使用 **[record/analysis](./analysis/README.md) 的 `data query --all --output csv -> Python/pandas`**；主技能 **[../SKILL.md](../../SKILL.md)**。
 
 ---
 

package/skills/qingflow-cli/reference/record/analysis/README.md

@@ -1,130 +1,38 @@
-# Qingflow CLI Record Analysis
+# 轻流记录数据分析
 
-Use this section for final statistical conclusions: counts, distributions, ratios, averages, rankings, trends, comparisons, and analysis reports.
-
-Default path, every time:
+最终统计结论、分析报告、趋势、排名、比例和分布统一使用以下路径：
 
 ```text
-app get -> record schema browse(view_id=...) -> record access -> Python/pandas -> final answer
-```
-
-Use the CLI entry:
-
-```bash
-qingflow record --help
-qingflow record access --help
-qingflow record access --app-key APP_KEY --view-id VIEW_ID --columns-file columns.json --where-file where.json --order-by-file order_by.json --json
-```
-
-The CLI command is under the `record` command group, so the discovery path is: first inspect `qingflow record --help`, then inspect `qingflow record access --help`.
-
-## Hard Rules
-
-- Never start analysis from `record_list`, export, QingBI, or guessed field ids.
-- Never conclude `record_access` is unavailable just because it is not visible as a top-level MCP tool; check the CLI path `qingflow record access`.
-- Never call `record access` before `record schema browse`.
-- Use only field ids returned by `record schema browse`.
-- If `app_get.accessible_views[].analysis_supported=false`, do not use that view for `record_access`.
-- Prefer an explicit time range or business filter. If the user gives none and the table may be large, ask for scope or use a clearly provided month/quarter/year.
-- Read every CSV shard in `record_access.files[].local_path` with Python. Do not print raw CSV or load raw rows into model context.
-- Before final analysis, run a field-quality profile in pandas: row count, null rate, distinct count, and period coverage for candidate grouping fields.
-- Do not use a high-missing field as the main conclusion dimension. If a candidate dimension is sparse, downgrade it to an `已填写样本观察` and choose a cleaner semantic fallback when available.
-- Full final conclusions require `record_access.complete=true` and `record_access.safe_for_final_conclusion=true`.
-- `record_list` is only for sample inspection after the aggregate result is understood.
-- `record_get` is only for single-record detail verification, logs, references, images, or readable attachments. Read images from `media_assets.items[].local_path`; read documents/tables from `file_assets.items[].local_path` and `extraction.text_path`.
-- `record_export_direct` is only for explicit export/download/Excel requests.
-- `chart_get` / QingBI is only for user-provided report URLs or chart ids.
-
-## Tool Selection
-
-| Need | Tool |
-|---|---|
-| Batch analysis, statistics, comparison, report | `record access -> Python` |
-| Browse a few example rows | `record_list` |
-| Inspect one record, logs, references, images, attachments | `record_get` |
-| User asks to export/download/Excel | `record_export_direct` |
-| User gives report URL or chart id | `chart_get` |
-| Todo/workflow task actions | `reference/task/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md` |
-
-## Standard Procedure
-
-1. Run `app get` and choose a table-style `view_id` from `accessible_views`.
-2. Run `record schema browse --app-key APP_KEY --view-id VIEW_ID`.
-3. Decide metric intent before fetching data: `count`, `sum`, `avg`, `distinct_count`, ratio, ranking, trend, or comparison.
-4. Choose minimal `record_access.columns`, plus `where` and `order_by`.
-5. Run `qingflow record access`.
-6. Read all returned CSV files in Python; use `fields[]` only when field-id metadata is needed.
-7. Run field-quality checks for all candidate dimensions.
-8. Compute results in pandas.
-9. Report numbers with scope, field choices, field-quality caveats, completeness, and business assumptions.
-
-Use field-id DSLs only:
-
-```json
-{
-  "app_key": "APP_KEY",
-  "view_id": "system:all",
-  "columns": [{ "field_id": 2 }, { "field_id": 18 }],
-  "where": [{ "field_id": 2, "op": "between", "value": ["2026-05-01", "2026-05-31"] }],
-  "order_by": [{ "field_id": 2, "direction": "asc" }]
-}
+qingflow data query --all --output csv -> 读取全部 CSV 分片 -> Python/pandas
 ```
 
-Never pass `page`, `page_size`, `limit`, `max_rows`, `timeout`, or `profile` to `record_access`.
-
-CSV columns are already readable and field-id anchored, for example `项目状态__field_343283094`. Do not expect separate `schema.json` or `README.md` files.
-
-For CLI use, write JSON argument files instead of embedding large JSON in shell text:
+先用当前 CLI 帮助确认参数：
 
 ```bash
-qingflow record access \
+qingflow data --help
+qingflow data query --help
+qingflow --json data query \
   --app-key APP_KEY \
-  --view-id system:all \
   --columns-file columns.json \
   --where-file where.json \
-  --order-by-file order_by.json \
-  --json
+  --sort-file sort.json \
+  --all --output csv
 ```
 
-## Status Handling
-
-Read `record_access.status` before reading files or writing conclusions.
-
-- `status=success`, `complete=true`, `safe_for_final_conclusion=true`: full-scope answer is allowed.
-- `status=needs_scope`: no CSV was written. Ask for a time/business range or retry with a user-provided period using `scope.suggested_time_fields`.
-- `status=partial`: read returned files only as a subset. Do not give a full-population conclusion.
-- `complete=false`, `truncated=true`, or `safe_for_final_conclusion=false`: answer as `初步观察` or ask for a narrower scope.
-
-## Business Context
-
-If the question mentions department, team, region, owner group, stage, product line, or a named business scope, check whether aliases or child scopes matter before concluding. Use explicit mappings provided by the user or local context; otherwise ask a short clarification.
-
-Example: if `烈焰组` and `飓风组` are sub-departments of `北斗部门`, apply that mapping in Python and state it in the answer.
-
-## Output Shape
-
-Default to:
-
-1. `结论`
-2. `关键数据`
-3. `口径与范围`
-4. `可信度 / 限制`
-
-Concrete numbers are mandatory. Ratios require both numerator and denominator. Trends require a time field and explicit date range. Rankings must come from a sorted pandas result.
-If a requested dimension has poor quality, say so explicitly and provide the nearest reliable fallback dimension, for example platform or product instead of a mostly empty module field.
+`--all` 与 `--output csv` 必须同时使用。columns 使用字段 id 数组；where 与 sort 使用包含 `field_id` 的对象数组。字段 id 来自当前 data schema 或已确认上下文，不得猜测。
 
-## References
+## 分析门禁
 
-Load only what is needed:
+- 读取返回摘要的 `status`、`row_count`、`complete`、`truncated`、`safe_for_final_conclusion`、`files` 和 `stopped_reason`。
+- 用 Python/pandas 读取全部 `files[].local_path`，不要把原始 CSV 行打印到模型上下文。
+- 完整总体结论必须同时满足 `complete=true`、`truncated=false`、`safe_for_final_conclusion=true`。
+- `status=needs_scope` 时 `files` 为空；读取 `scope.reported_total` 与 `scope.row_threshold`，请求时间或业务范围后重试。
+- `status=partial` 或任一完整性条件不满足时，只能给出局部观察，或收窄范围后重试。
+- 最终分组前检查行数、空值率、唯一值数量与时间覆盖；高缺失维度只能作为“已填写样本观察”。
+- `record list` 仅用于样本核查，不能代替全量 CSV；导出工具只用于用户明确要求下载文件的场景。
 
-- Data access status machine: [references/data-access-playbook.md](./data-access-playbook.md)
-- Python/pandas templates: [references/pandas-recipes.md](./pandas-recipes.md)
-- Analysis patterns: [references/analysis-patterns.md](./analysis-patterns.md)
-- Business mappings and scope: [references/business-context.md](./business-context.md)
-- Confidence and final wording: [references/confidence-reporting.md](./confidence-reporting.md)
-- Common mistakes: [references/analysis-gotchas.md](./analysis-gotchas.md)
-- Report templates: [references/report-format.md](./report-format.md)
+## 输出要求
 
-## Feedback Escalation
+默认输出结论、关键数据、口径与范围、可信度／限制。比例必须包含分子与分母，趋势必须说明时间字段与日期范围，排名必须来自 pandas 显式排序。
 
-If the desired analysis cannot be completed because of missing capability, unsupported data shape, or an awkward workflow after reasonable attempts, summarize the exact gap and ask whether to submit product feedback. Only after explicit user confirmation, call `feedback_submit`.
+进一步细节见同目录的取数状态机、pandas 模板、分析模式、业务上下文、可信度和报告模板。

package/skills/qingflow-cli/reference/record/analysis/analysis-gotchas.md

@@ -1,19 +1,19 @@
 # Analysis Gotchas
 
-## Do Not Skip Schema
+## 不要猜字段 schema
 
-Correct path:
+正确路径：
 
-1. `app_get`
-2. `record_browse_schema_get`
-3. `record_access`
-4. Python
+1. 从当前 data schema 或已确认上下文选择字段 id
+2. `data query --all --output csv`
+3. 读取全部 `files[].local_path`
+4. Python/pandas
 
-`record_browse_schema_get` returns readable fields for the selected view. Missing fields are permission or view-scope boundaries, not invitations to guess hidden ids.
+data 工具返回的 schema、字段错误与访问范围是事实源；缺失字段不是猜测隐藏 id 的理由。
 
 ## Do Not Use Export For Analysis
 
-Export tools are for user-requested files. Analysis uses `record_access` because it returns structured completeness and compact field metadata.
+导出工具只用于用户明确要求下载文件。分析使用 `data query --all --output csv`，因为它返回本地 CSV 分片与结构化完整性字段。
 
 ## Do Not Treat `record_list` As Full Data
 
@@ -28,7 +28,7 @@ Export tools are for user-requested files. Analysis uses `record_access` because
 
 ## Do Not Control Paging
 
-`record_access` owns paging internally.
+`data query --all --output csv` 内部处理分页。
 
 Do not invent:
 
@@ -84,7 +84,7 @@ For penetration, conversion, or share:
 
 ## Normalize Relative Dates
 
-Convert relative phrases into exact ranges before `record_access`.
+在 data query 前把相对日期转换为精确范围。
 
 - `今年5月` -> exact May 1 to May 31 in the current year
 - `去年同期` -> same date range in previous year

package/skills/qingflow-cli/reference/record/analysis/analysis-patterns.md

@@ -2,12 +2,12 @@
 
 ## Canonical Sequence
 
-1. `app_get`
-2. `record_browse_schema_get`
-3. decide metric intent
-4. choose `record_access.columns / where / order_by`
-5. `record_access`
-6. Python over every returned CSV shard
+1. 明确 `app_key`
+2. 从当前 data schema 或已确认上下文选择字段 id
+3. 决定指标意图
+4. 选择 data query 的 columns / where / sort
+5. `data query --all --output csv`
+6. Python 读取每个 `files[].local_path`
 7. optional `record_list` or `record_get` only for sample/detail verification
 
 Metric intent must be one of:
@@ -74,7 +74,7 @@ If denominator is missing or scope differs, do not call the result a rate.
 
 ## Trend
 
-1. Choose a date/time field from `suggested_time_fields`.
+1. 从 data schema 或查询响应的 `fields` 中选择日期／时间字段，并核对其 id、标题与类型。
 2. Convert relative phrases into exact date ranges.
 3. Fetch the date field and metrics.
 4. Bucket in pandas by day/week/month/quarter/year.
@@ -104,8 +104,8 @@ Never use `record_list` alone for final averages, shares, rankings, trends, or d
 
 If the exact field is unclear:
 
-1. inspect `record_browse_schema_get.fields`
-2. use titles and suggested fields
+1. 检查 data schema 或返回的 `fields`
+2. 按 `fields` 中的标题、字段 id 与类型筛选候选字段
 3. if one candidate is clearly dominant, proceed
 4. otherwise ask the user to confirm
 

package/skills/qingflow-cli/reference/record/analysis/business-context.md

@@ -54,7 +54,7 @@ If any part is ambiguous, ask. Do not rename a count as a rate.
 
 ## Time Scope
 
-Normalize relative dates to exact dates before calling `record_access`.
+调用 data query 前把相对日期转换为精确日期。
 
 Examples:
 

package/skills/qingflow-cli/reference/record/analysis/confidence-reporting.md

@@ -4,12 +4,12 @@
 
 Use `全量可信结论` only when:
 
-- `record_browse_schema_get` was used
-- data came from `record_access`
+- 字段 id 来自当前 data schema 或已确认上下文
+- 数据来自 `data query --all --output csv`
 - all returned CSV shards were read in Python
-- `record_access.complete=true`
-- `record_access.truncated=false`
-- `record_access.safe_for_final_conclusion=true`
+- `complete=true`
+- `truncated=false`
+- `safe_for_final_conclusion=true`
 - metric definitions are complete
 - denominator exists for every ratio
 - time fields and date ranges are explicit
@@ -19,11 +19,11 @@ Use `全量可信结论` only when:
 
 Use `初步观察` when:
 
-- `record_access.status=needs_scope`
-- `record_access.status=partial`
-- `record_access.complete=false`
-- `record_access.truncated=true`
-- `record_access.safe_for_final_conclusion=false`
+- `status=needs_scope`
+- `status=partial`
+- `complete=false`
+- `truncated=true`
+- `safe_for_final_conclusion=false`
 - evidence came from `record_list`
 - scope or saved view filter is unverified
 

package/skills/qingflow-cli/reference/record/analysis/data-access-playbook.md

@@ -1,106 +1,78 @@
-# Data Access Playbook
+# data CSV 取数状态机
 
-This file is the operational state machine for `record_access`.
+## 必须路径
 
-## Required Sequence
+1. 明确 `app_key` 与指标意图。
+2. 从当前 data schema 或已确认上下文选择字段 id。
+3. 构造 columns、where、sort JSON 文件。
+4. 执行 `data query --all --output csv`。
+5. 读取全部 `files[].local_path` 并在 Python/pandas 中合并。
 
-1. `app_get`
-2. choose `view_id` from `accessible_views`
-3. `record_browse_schema_get(app_key, view_id)`
-4. build `record_access.columns / where / order_by` from field ids
-5. run `record_access`
-6. read every CSV shard with Python
-
-Do not call `record_access` with field titles, guessed ids, page controls, row limits, or profile.
-CSV columns are readable and field-id anchored, for example `项目状态__field_343283094`; do not look for extra `schema.json` or README files.
-
-## Finding `record_access`
-
-`record_access` can be available as an MCP tool or as a CLI subcommand. If the MCP surface does not show a top-level `record_access` tool, look under the Qingflow CLI record group before choosing any other path:
-
-```bash
-qingflow record --help
-qingflow record access --help
-```
-
-The CLI call is:
+CLI 发现与调用：
 
 ```bash
-qingflow record access \
+qingflow data --help
+qingflow data query --help
+qingflow --json data query \
   --app-key APP_KEY \
-  --view-id VIEW_ID \
   --columns-file columns.json \
   --where-file where.json \
-  --order-by-file order_by.json \
-  --json
+  --sort-file sort.json \
+  --all --output csv
 ```
 
-This is the same analysis path: it writes CSV shards and metadata for Python. Do not replace it with list browsing, export, QingBI, or aggregate helpers just because the MCP tool is not visible.
-
-## Request Patterns
+columns 是字段 id 数组，例如 `[2, 18]`；where 和 sort 是带 `field_id` 的对象数组。`--all` 与 `--output csv` 必须同时出现。
 
-### Count or distribution
+## 真实输出字段
 
-Fetch the grouping field and any time/business filter field.
+分析前先读取：
 
-```json
-{
-  "app_key": "APP_KEY",
-  "view_id": "system:all",
-  "columns": [{ "field_id": 18 }],
-  "where": [{ "field_id": 2, "op": "between", "value": ["2026-05-01", "2026-05-31"] }],
-  "order_by": []
-}
-```
+- `status`
+- `files[].local_path`、`files[].row_count`、`files[].part`
+- `row_count`
+- `complete`
+- `truncated`
+- `safe_for_final_conclusion`
+- `fetched_pages`
+- `stopped_reason`
+- `fields`
 
-### Trend
+输出还可能包含 `local_dir`、访问上下文和动态提示；这些内容保持原样解释，不在本地补造。
 
-Fetch the date/time field plus metric fields.
+## 状态决策
 
-```json
-{
-  "app_key": "APP_KEY",
-  "view_id": "system:all",
-  "columns": [{ "field_id": 2 }, { "field_id": 18 }],
-  "where": [{ "field_id": 2, "op": "between", "value": ["2026-01-01", "2026-12-31"] }],
-  "order_by": [{ "field_id": 2, "direction": "asc" }]
-}
-```
-
-### Ratio
-
-If numerator and denominator use different filters, run separate `record_access` calls. Only compute the ratio after both source datasets are complete and compatible.
-
-## Status Decisions
-
-| Status | Meaning | Agent action |
+| 状态 | 含义 | 动作 |
 |---|---|---|
-| `success` + `safe_for_final_conclusion=true` | Full retrieved scope is reliable | Give final conclusion |
-| `needs_scope` | Tool refused large unbounded scan, no CSV | Ask for scope or retry with explicit period/business filter |
-| `partial` | Some CSV files written, but not full data | Give only subset observation |
-| `complete=false` | Not all requested data is available | Do not present full-population conclusion |
-| `truncated=true` | Tool had to stop before full scope | Disclose and narrow scope |
-
-## `needs_scope` Recovery
+| `success` 且完整性三项满足 | 请求范围完整可用 | 读取所有分片后形成总体结论 |
+| `needs_scope` | 无范围大查询被拒绝，未写 CSV | 读取 `scope.reported_total` 与 `scope.row_threshold`，请求时间或业务范围 |
+| `partial` | 已写部分 CSV，但未完成 | 只给局部观察，说明 `row_count` 与 `stopped_reason` |
+| `complete=false` | 未取完请求范围 | 不给总体结论 |
+| `truncated=true` | 提前停止 | 收窄范围后重试 |
+| `safe_for_final_conclusion=false` | 不适合最终总体结论 | 降级或重试 |
 
-Use the returned `scope` object:
+`needs_scope` 时 `files=[]`、`row_count=0`；不要寻找不存在的 CSV。partial 时保留的文件可用于局部观察，但不能使用“全部”“整体”“全量”等措辞。
 
-- `reported_total`: explain why scope is needed
-- `suggested_time_fields`: choose likely date fields
-- `recommended_where_examples`: reuse if they match the user request
+## 请求示例
 
-If the user already provided a concrete month/quarter/year, retry with that period. If no business boundary is available, ask one short clarification.
+`columns.json`：
 
-## `partial` Recovery
+```json
+[2, 18]
+```
 
-You may read the files, but must label output as partial:
+`where.json`（同一字段的范围使用两个公开操作符并按 AND 组合）：
 
-- say which files/rows were analyzed
-- do not use `全部`, `所有`, `整体`, or `全量`
-- suggest narrowing time or business scope before final conclusion
+```json
+[
+  {"field_id": 2, "op": "gte", "value": "2026-05-01"},
+  {"field_id": 2, "op": "lte", "value": "2026-05-31"}
+]
+```
 
-## View Scope
+`sort.json`：
 
-For custom views, the result is scoped to that saved view. If `verification.view_filter_verified=false`, disclose that the saved-filter scope could not be fully verified.
+```json
+[{"field_id": 2, "direction": "asc"}]
+```
 
-For board/gantt views, switch to a table-style view or `system:all` plus explicit filters.
+若分子和分母使用不同筛选，分别执行兼容范围的 data query；两侧都满足完整性门禁后再计算比例。