@qingflow-tech/qingflow-cli 1.1.50-beta.5 → 1.1.51

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

@@ -0,0 +1,159 @@
+{
+  "views": [
+    {
+      "operation": "upsert",
+      "app_key": "WORK_ORDER_APP_KEY",
+      "name": "生产工单执行视图",
+      "type": "table",
+      "columns": ["工单编号", "产品", "工单状态", "负责人", "计划完成日期"],
+      "filters": [
+        {"field_name": "工单状态", "operator": "in", "values": ["待排产", "生产中"]},
+        {"field_name": "产品", "operator": "contains", "value": "标准"},
+        {"field_name": "计划完成日期", "operator": "lte", "value": "2026-07-31"}
+      ],
+      "query_conditions": {
+        "enabled": true,
+        "exact": false,
+        "hide_before_query": false,
+        "rows": [["工单编号", "工单状态"], ["负责人", "计划完成日期"]]
+      },
+      "visibility": {
+        "mode": "workspace",
+        "selectors": {},
+        "external_mode": "not",
+        "external_selectors": {}
+      },
+      "action_buttons": [
+        {
+          "client_key": "create_quality_from_list",
+          "text": "行内创建质检",
+          "action": "add_data",
+          "target_app_key": "QUALITY_APP_KEY",
+          "field_mappings": [
+            {"source_field": "数据ID", "target_field": "关联工单"}
+          ],
+          "default_values": {"处理状态": "待处理"},
+          "placement": "list",
+          "primary": true,
+          "style_preset": "primary_blue",
+          "visible_when": [
+            {"field_name": "工单状态", "operator": "eq", "value": "生产中"}
+          ]
+        },
+        {
+          "client_key": "create_quality_from_detail",
+          "text": "详情创建质检",
+          "action": "add_data",
+          "target_app_key": "QUALITY_APP_KEY",
+          "field_mappings": [
+            {"source_field": "数据ID", "target_field": "关联工单"}
+          ],
+          "default_values": {"处理状态": "待处理"},
+          "placement": "detail",
+          "style_preset": "neutral_outline"
+        },
+        {
+          "client_key": "open_work_order_sop",
+          "text": "打开SOP",
+          "action": "link",
+          "url": "https://example.com/sop/work-order",
+          "placement": "header",
+          "style_preset": "text_blue"
+        }
+      ]
+    },
+    {
+      "operation": "upsert",
+      "app_key": "WORK_ORDER_APP_KEY",
+      "name": "工单状态看板",
+      "type": "board",
+      "columns": ["工单编号", "产品", "负责人", "计划完成日期"],
+      "group_by": "工单状态",
+      "filters": [
+        {"field_name": "工单状态", "operator": "not_empty"},
+        {"field_name": "关闭日期", "operator": "is_empty"}
+      ],
+      "query_conditions": {
+        "enabled": true,
+        "rows": [["工单编号", "负责人"], ["计划完成日期"]]
+      },
+      "action_buttons": [
+        {
+          "text": "看板行内创建质检",
+          "action": "add_data",
+          "target_app_key": "QUALITY_APP_KEY",
+          "field_mappings": [
+            {"source_field": "数据ID", "target_field": "关联工单"}
+          ],
+          "placement": "list",
+          "visible_when": [
+            {"field_name": "工单状态", "operator": "eq", "value": "已完工"}
+          ]
+        },
+        {
+          "text": "看板详情创建质检",
+          "action": "add_data",
+          "target_app_key": "QUALITY_APP_KEY",
+          "field_mappings": [
+            {"source_field": "数据ID", "target_field": "关联工单"}
+          ],
+          "placement": "detail"
+        }
+      ]
+    },
+    {
+      "operation": "upsert",
+      "app_key": "WORK_ORDER_APP_KEY",
+      "name": "工单计划甘特图",
+      "type": "gantt",
+      "columns": ["工单编号", "产品", "工单状态", "计划开始日期", "计划完成日期"],
+      "start_field": "计划开始日期",
+      "end_field": "计划完成日期",
+      "title_field": "工单编号",
+      "filters": [
+        {"field_name": "计划开始日期", "operator": "gte", "value": "2026-07-01"}
+      ],
+      "query_conditions": {
+        "enabled": true,
+        "rows": [["工单编号", "工单状态"], ["计划开始日期", "计划完成日期"]]
+      },
+      "action_buttons": [
+        {
+          "text": "详情查看排产说明",
+          "action": "link",
+          "url": "https://example.com/sop/schedule",
+          "placement": "detail"
+        }
+      ]
+    },
+    {
+      "operation": "patch",
+      "app_key": "WORK_ORDER_APP_KEY",
+      "view_key": "RAW_VIEW_KEY_TO_PATCH",
+      "set": {
+        "columns": ["工单编号", "工单状态", "负责人"],
+        "filters": [
+          {"field_name": "工单状态", "operator": "neq", "value": "已关闭"}
+        ],
+        "query_conditions": {
+          "enabled": true,
+          "rows": [["工单编号", "工单状态"], ["负责人"]]
+        },
+        "action_buttons": [
+          {
+            "text": "补充详情按钮",
+            "action": "link",
+            "url": "https://example.com/detail-help",
+            "placement": "detail"
+          }
+        ],
+        "action_buttons_mode": "merge"
+      }
+    },
+    {
+      "operation": "remove",
+      "app_key": "WORK_ORDER_APP_KEY",
+      "view_key": "RAW_VIEW_KEY_TO_REMOVE"
+    }
+  ]
+}

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

@@ -1,36 +1,42 @@
 {
-  "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": [
+  "views": [
     {
-      "text": "行内创建子记录",
-      "action": "add_data",
-      "target_app_key": "TARGET_APP_KEY",
-      "field_mappings": [
-        {"source_field": "数据ID", "target_field": "关联主记录"}
+      "operation": "upsert",
+      "app_key": "APP_KEY",
+      "name": "示例业务操作视图_CLI模板",
+      "type": "table",
+      "columns": ["主记录编号", "主记录名称", "状态", "负责人"],
+      "filters": [
+        {"field_name": "状态", "operator": "neq", "value": "已关闭"}
       ],
-      "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"
+      "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"
+        }
+      ]
     }
   ]
 }

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

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

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

@@ -1,38 +1,130 @@
-# 轻流记录数据分析
+# 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
-qingflow data query --all --output csv -> 读取全部 CSV 分片 -> Python/pandas
+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" }]
+}
 ```
 
-先用当前 CLI 帮助确认参数：
+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:
 
 ```bash
-qingflow data --help
-qingflow data query --help
-qingflow --json data query \
+qingflow record access \
   --app-key APP_KEY \
+  --view-id system:all \
   --columns-file columns.json \
   --where-file where.json \
-  --sort-file sort.json \
-  --all --output csv
+  --order-by-file order_by.json \
+  --json
 ```
 
-`--all` 与 `--output csv` 必须同时使用。columns 使用字段 id 数组；where 与 sort 使用包含 `field_id` 的对象数组。字段 id 来自当前 data schema 或已确认上下文，不得猜测。
+## 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.
 
-## 分析门禁
+## References
 
-- 读取返回摘要的 `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；导出工具只用于用户明确要求下载文件的场景。
+Load only what is needed:
 
-## 输出要求
+- 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)
 
-默认输出结论、关键数据、口径与范围、可信度／限制。比例必须包含分子与分母，趋势必须说明时间字段与日期范围，排名必须来自 pandas 显式排序。
+## 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`.

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

@@ -1,19 +1,19 @@
 # Analysis Gotchas
 
-## 不要猜字段 schema
+## Do Not Skip Schema
 
-正确路径：
+Correct path:
 
-1. 从当前 data schema 或已确认上下文选择字段 id
-2. `data query --all --output csv`
-3. 读取全部 `files[].local_path`
-4. Python/pandas
+1. `app_get`
+2. `record_browse_schema_get`
+3. `record_access`
+4. Python
 
-data 工具返回的 schema、字段错误与访问范围是事实源；缺失字段不是猜测隐藏 id 的理由。
+`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.
 
 ## Do Not Use Export For Analysis
 
-导出工具只用于用户明确要求下载文件。分析使用 `data query --all --output csv`，因为它返回本地 CSV 分片与结构化完整性字段。
+Export tools are for user-requested files. Analysis uses `record_access` because it returns structured completeness and compact field metadata.
 
 ## Do Not Treat `record_list` As Full Data
 
@@ -28,7 +28,7 @@ data 工具返回的 schema、字段错误与访问范围是事实源；缺失
 
 ## Do Not Control Paging
 
-`data query --all --output csv` 内部处理分页。
+`record_access` owns paging internally.
 
 Do not invent:
 
@@ -84,7 +84,7 @@ For penetration, conversion, or share:
 
 ## Normalize Relative Dates
 
-在 data query 前把相对日期转换为精确范围。
+Convert relative phrases into exact ranges before `record_access`.
 
 - `今年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_key`
-2. 从当前 data schema 或已确认上下文选择字段 id
-3. 决定指标意图
-4. 选择 data query 的 columns / where / sort
-5. `data query --all --output csv`
-6. Python 读取每个 `files[].local_path`
+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
 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. 从 data schema 或查询响应的 `fields` 中选择日期／时间字段，并核对其 id、标题与类型。
+1. Choose a date/time field from `suggested_time_fields`.
 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. 检查 data schema 或返回的 `fields`
-2. 按 `fields` 中的标题、字段 id 与类型筛选候选字段
+1. inspect `record_browse_schema_get.fields`
+2. use titles and suggested fields
 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
 
-调用 data query 前把相对日期转换为精确日期。
+Normalize relative dates to exact dates before calling `record_access`.
 
 Examples:
 

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

@@ -4,12 +4,12 @@
 
 Use `全量可信结论` only when:
 
-- 字段 id 来自当前 data schema 或已确认上下文
-- 数据来自 `data query --all --output csv`
+- `record_browse_schema_get` was used
+- data came from `record_access`
 - all returned CSV shards were read in Python
-- `complete=true`
-- `truncated=false`
-- `safe_for_final_conclusion=true`
+- `record_access.complete=true`
+- `record_access.truncated=false`
+- `record_access.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:
 
-- `status=needs_scope`
-- `status=partial`
-- `complete=false`
-- `truncated=true`
-- `safe_for_final_conclusion=false`
+- `record_access.status=needs_scope`
+- `record_access.status=partial`
+- `record_access.complete=false`
+- `record_access.truncated=true`
+- `record_access.safe_for_final_conclusion=false`
 - evidence came from `record_list`
 - scope or saved view filter is unverified