@qingflow-tech/qingflow-cli 1.1.57 → 1.1.59

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
 

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

@@ -1,78 +1,106 @@
-# data CSV 取数状态机
+# Data Access Playbook
 
-## 必须路径
+This file is the operational state machine for `record_access`.
 
-1. 明确 `app_key` 与指标意图。
-2. 从当前 data schema 或已确认上下文选择字段 id。
-3. 构造 columns、where、sort JSON 文件。
-4. 执行 `data query --all --output csv`。
-5. 读取全部 `files[].local_path` 并在 Python/pandas 中合并。
+## Required Sequence
 
-CLI 发现与调用：
+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:
 
 ```bash
-qingflow data --help
-qingflow data query --help
-qingflow --json data query \
+qingflow record access \
   --app-key APP_KEY \
+  --view-id VIEW_ID \
   --columns-file columns.json \
   --where-file where.json \
-  --sort-file sort.json \
-  --all --output csv
+  --order-by-file order_by.json \
+  --json
 ```
 
-columns 是字段 id 数组，例如 `[2, 18]`；where 和 sort 是带 `field_id` 的对象数组。`--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
 
-## 真实输出字段
+### Count or distribution
 
-分析前先读取：
+Fetch the grouping field and any time/business filter field.
 
-- `status`
-- `files[].local_path`、`files[].row_count`、`files[].part`
-- `row_count`
-- `complete`
-- `truncated`
-- `safe_for_final_conclusion`
-- `fetched_pages`
-- `stopped_reason`
-- `fields`
+```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": []
+}
+```
 
-输出还可能包含 `local_dir`、访问上下文和动态提示；这些内容保持原样解释，不在本地补造。
+### Trend
 
-## 状态决策
+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` 且完整性三项满足 | 请求范围完整可用 | 读取所有分片后形成总体结论 |
-| `needs_scope` | 无范围大查询被拒绝，未写 CSV | 读取 `scope.reported_total` 与 `scope.row_threshold`，请求时间或业务范围 |
-| `partial` | 已写部分 CSV，但未完成 | 只给局部观察，说明 `row_count` 与 `stopped_reason` |
-| `complete=false` | 未取完请求范围 | 不给总体结论 |
-| `truncated=true` | 提前停止 | 收窄范围后重试 |
-| `safe_for_final_conclusion=false` | 不适合最终总体结论 | 降级或重试 |
+| `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` 时 `files=[]`、`row_count=0`；不要寻找不存在的 CSV。partial 时保留的文件可用于局部观察，但不能使用“全部”“整体”“全量”等措辞。
+## `needs_scope` Recovery
 
-## 请求示例
+Use the returned `scope` object:
 
-`columns.json`：
+- `reported_total`: explain why scope is needed
+- `suggested_time_fields`: choose likely date fields
+- `recommended_where_examples`: reuse if they match the user request
 
-```json
-[2, 18]
-```
+If the user already provided a concrete month/quarter/year, retry with that period. If no business boundary is available, ask one short clarification.
 
-`where.json`（同一字段的范围使用两个公开操作符并按 AND 组合）：
+## `partial` Recovery
 
-```json
-[
-  {"field_id": 2, "op": "gte", "value": "2026-05-01"},
-  {"field_id": 2, "op": "lte", "value": "2026-05-31"}
-]
-```
+You may read the files, but must label output as partial:
 
-`sort.json`：
+- say which files/rows were analyzed
+- do not use `全部`, `所有`, `整体`, or `全量`
+- suggest narrowing time or business scope before final conclusion
 
-```json
-[{"field_id": 2, "direction": "asc"}]
-```
+## View Scope
+
+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.
 
-若分子和分母使用不同筛选，分别执行兼容范围的 data query；两侧都满足完整性门禁后再计算比例。
+For board/gantt views, switch to a table-style view or `system:all` plus explicit filters.

package/skills/qingflow-cli/reference/record/analysis/pandas-recipes.md

@@ -9,14 +9,14 @@ import pandas as pd
 
 files = [
     "/absolute/path/records-0001.csv",
-    # 包含 data query 返回的每个 files[].local_path
+    # include every record_access.files[].local_path
 ]
 
 frames = [pd.read_csv(path, dtype=str, keep_default_na=False) for path in files]
 df = pd.concat(frames, ignore_index=True) if frames else pd.DataFrame()
 
 # Columns are readable and field-id anchored, e.g. 项目状态__field_343283094.
-fields = []  # 需要字段 id 元数据时使用 data query 返回的 fields
+fields = []  # optionally paste record_access.fields here if you need field-id metadata
 field_by_id = {int(item["field_id"]): item for item in fields if "field_id" in item}
 title_by_col = {item["column_name"]: item["title"] for item in fields if item.get("column_name")}
 ```

package/skills/qingflow-common/SKILL.md

@@ -19,8 +19,7 @@ Do not require both surfaces. If only one is installed, complete the workflow on
 ## Shared Concepts
 
 - **AppForm** is the versioned declarative definition for an application form: app metadata, fields, sections, layout, settings, and field configuration. The same JSON declaration is used by CLI and Qingflow MCP.
-- **Data** 是既有应用中的普通业务数据。查询、单条读取和直接增删改默认使用视图无关的 data 入口，并以当次 schema、字段能力和访问范围为准。
-- **Record** 用于详情页附件／图片、完整日志、导入、代码块，以及用户明确指定的 record 命令；不要把普通应用数据工作路由到 record。
+- **Record** is runtime data written to an existing app. Use the record schema before an insert, update, import, or analysis workflow.
 - **Task** is a workflow work item. Prefer task operations for approval, transfer, rollback, and assignee actions.
 - **Builder resource** is package, app, view, chart, portal, navigation, or workflow configuration. It is separate from record data.
 - **Schema version** is part of the public contract. Pin it for one AppForm or workflow operation and do not combine values from different versions.
@@ -31,13 +30,11 @@ Do not require both surfaces. If only one is installed, complete the workflow on
 | --- | --- | --- |
 | Form schema/read/apply/delete | `qingflow --json builder app-form ...` / `builder app delete` | `app_form_schema`, `app_form_get`, `app_form_apply`, `app_delete` |
 | AppForm static validation | `qingflow --json builder app-form validate --file ...` | Performed inside `app_form_apply`; no separate tool |
-| 普通应用数据查询与直接增删改 | `qingflow --json data ...` | Qingflow MCP `data_query/get/insert/update/delete` |
-| 日志、附件、导入、代码块或用户指定的 record 命令 | `qingflow --json record ...` / `import ...` | Qingflow MCP 对应 record/import 专项工具 |
-| 待办与流程动作 | `qingflow --json task ...` | Qingflow MCP task tools |
-| 免登录打开网页或指定业务页面 | `qingflow --json auth login-link [--redirect-path PATH]` | `get_login_link` |
+| Record and task work | `qingflow --json record ...` / `task ...` | Qingflow MCP record and task tools |
+| Open a workspace or confirmed business page | `qingflow --json auth login-link [--redirect-path PATH]` | `get_login_link` |
 | Package, view, portal, chart, workflow | `qingflow --json builder ...` | Qingflow MCP configuration tools |
 
-The operation names and payload schemas are defined by the public surface. Use the current Schema or tool input schema as the source of truth, not another command's shape or a backend payload.
+The operation names and payload schemas are defined by the public surface. Use the current Schema or tool input schema as the source of truth, not a legacy command name or backend payload.
 
 ## Package Boundaries
 

package/src/qingflow_mcp/app_form_compat.py

@@ -10,9 +10,6 @@ from .json_types import JSONObject
 TYPE_ALIASES = {
     "multiline": "long_text",
     "textarea": "long_text",
-    "richtext": "rich_text",
-    "rich-text": "rich_text",
-    "rich_text": "rich_text",
     "radio": "single_choice",
     "boolean": "single_choice",
     "select": "single_select",