@qingflow-tech/qingflow-cli 1.1.59 → 1.1.61-beta.1

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

@@ -0,0 +1,56 @@
+# Qingflow CLI：record 日志与附件参考
+
+> **适用范围**：任务需要完整数据／流程日志、详情页引用和关联资源上下文，或用户指定 record 兼容入口时使用。普通应用数据查询使用 [`data query/get`](../core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)，附件下载使用 [data 附件下载](../data/README.md#附件下载与读取)。
+
+## record 查询链
+
+```text
+app get（解析 accessible_views，选定 VIEW_ID）
+  → record schema browse（读取该视图字段口径）
+  → record list（样本浏览或模糊定位候选）
+  → record get（可选：详情页首屏、附件与图片上下文）
+  → record logs（可选：完整数据日志与流程日志）
+```
+
+## 命令形状
+
+普通记录附件下载使用 `data get --download-attachments`。以下 record 命令只用于详情页专项上下文或用户明确指定的兼容入口；不要把它们当作 data 权限错误的回退。
+
+```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 get --download-attachments` 中完成，参数、状态与预算见 [data 附件下载](../data/README.md#附件下载与读取)。如果用户明确使用 record 详情页兼容入口，继续使用其返回的本地资产；`extraction.status=unsupported` 不代表下载失败。
+
+## 边界
+
+- 统计分析仍转 `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；两侧都满足完整性门禁后再计算比例。

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

@@ -9,14 +9,14 @@ import pandas as pd
 
 files = [
     "/absolute/path/records-0001.csv",
-    # include every record_access.files[].local_path
+    # 包含 data query 返回的每个 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 = []  # optionally paste record_access.fields here if you need field-id metadata
+fields = []  # 需要字段 id 元数据时使用 data query 返回的 fields
 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,7 +19,8 @@ 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.
-- **Record** is runtime data written to an existing app. Use the record schema before an insert, update, import, or analysis workflow.
+- **Data** 是既有应用中的普通业务数据。查询、单条读取和直接增删改默认使用视图无关的 data 入口，并以当次 schema、字段能力和访问范围为准。
+- **Record** 用于详情页专项上下文、完整日志、导入、代码块，以及用户明确指定的 record 命令；普通应用数据与记录附件下载使用 data。
 - **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.
@@ -30,11 +31,16 @@ 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 |
-| 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` |
+| 普通应用数据查询与直接增删改 | `qingflow --json data ...` | Qingflow MCP `data_query/get/insert/update/delete` |
+| 记录附件下载 | `qingflow --json data get --download-attachments` | `data_get(download_attachments=true)` |
+| 日志、详情页专项上下文、导入、代码块或用户指定的 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` |
 | 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 a legacy command name or 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 another command's shape or a backend payload.
+
+用户需要下载或读取附件时，先用 data 定位记录，保持相同身份与工作区，对同一 `app_key`、`record_id` 调用 CLI `data get --download-attachments` 或 MCP `data_get(download_attachments=true)`，保留 schema，使用 `file_assets.items[].local_path`。附件图片与视频同样适用；新入口只下载原文件，不做文本提取。以 `access_status=downloaded` 和非空本地路径判断成功，部分失败看 `file_assets.warnings`。无需 view_id 或 record_get，也不要为下载而读取认证配置、打印 token 或用 Python/curl 直接请求远端 URL。
 
 ## Package Boundaries
 

package/src/qingflow_mcp/app_form_compat.py

@@ -10,6 +10,9 @@ 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",