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

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-cli/reference/views_upsert_table_minimal.example.json

@@ -0,0 +1,42 @@
+{
+  "views": [
+    {
+      "operation": "upsert",
+      "app_key": "APP_KEY",
+      "name": "示例业务操作视图_CLI模板",
+      "type": "table",
+      "columns": ["主记录编号", "主记录名称", "状态", "负责人"],
+      "filters": [
+        {"field_name": "状态", "operator": "neq", "value": "已关闭"}
+      ],
+      "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-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/__init__.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 __all__ = ["__version__"]
 
-_FALLBACK_VERSION = "0.2.0b1099"
+_FALLBACK_VERSION = "0.2.0b1101"
 
 
 def _resolve_local_pyproject_version() -> str | None:

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",

package/src/qingflow_mcp/app_form_validator.py

@@ -11,15 +11,9 @@ from .app_form_compat import normalize_app_form_declaration
 from .builder_facade.app_form_schema import AppFormContractError, compact_schema_errors, schema_error_message
 
 
-#: code_block / q_linker 输出目标字段类型。后端写链无类型白名单(FormSvcImpl
-#: 原样落库),运行时 DataSvcImpl.getAnswerValueByString:选项/数字/日期有专门
-#: 分支;attachment 按拆分 URL 写入(专门分支);subtable 整表组装(专门分支);
-#: rich_text/data_relation 走 Question.canImport 兜底按字符串写入(不报错)。
-#: 四者为存量合法配置(提取读得出、apply 必须写回,两闸门同口径)。
 _INTEGRATION_OUTPUT_TARGET_FIELD_TYPES = {
     "text",
     "long_text",
-    "rich_text",
     "number",
     "amount",
     "date",
@@ -27,9 +21,6 @@ _INTEGRATION_OUTPUT_TARGET_FIELD_TYPES = {
     "single_choice",
     "single_select",
     "multi_select",
-    "attachment",
-    "data_relation",
-    "subtable",
 }
 _Q_LINKER_TEMPLATE_RE = re.compile(r"\{\{(?P<key>[^{}\s]+)\}\}")
 _FORMULA_IDENTIFIER_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
@@ -227,32 +218,19 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
             widths = ["width" in field for field in fields if isinstance(field, dict)]
             if widths and any(widths) and not all(widths):
                 errors.append((row_path, "width must be present on every field in the row or omitted from all"))
-            # 行宽契约(与后端语义对齐):任意 1-100 整数 + 全有或全无。
-            # 后端 html_width 无取值/总和校验,存量存在 33/34 三等分与字段删除后
-            # 留白(如 3×25=75)的行;get 读出的原布局必须能原样过校验
-            # (apply(get(S)) ≡ S 命题的必要条件)。
-            if widths and all(widths):
-                bad = [f.get("width") for f in fields if isinstance(f, dict) and not (isinstance(f.get("width"), int) and 1 <= f["width"] <= 100)]
-                if bad:
-                    errors.append((row_path, "field widths must be an integer between 1 and 100"))
+            if widths and all(widths) and sum(field.get("width", 0) for field in fields if isinstance(field, dict)) != 100:
+                errors.append((row_path, "field widths must total 100"))
             for field_index, field in enumerate(fields):
                 if isinstance(field, dict):
                     top_fields.append((f"{row_path}/{field_index}", field))
     def resolve_local_selector(selector: Any) -> tuple[str, tuple[str, dict[str, Any]] | None]:
-        """Resolve against the declared body, preserving backend-dependent ID-only cases.
-
-        返回态:resolved(唯一定位)/ invalid(定位失败)/ ambiguous(方案 A:name-only
-        命中多个同名字段,调用方须报 AMBIGUOUS_FIELD_SELECTOR)/ unknown(存在未命名
-        字段,后端侧再判)/ schema(结构不完整,交给 Schema 校验)。
-        """
+        """Resolve against the declared body, preserving backend-dependent ID-only cases."""
         if not isinstance(selector, dict):
             return "schema", None
         raw_que_id = selector.get("queId")
         que_id = raw_que_id if isinstance(raw_que_id, int) and not isinstance(raw_que_id, bool) else None
         raw_name = selector.get("name")
-        # name 两侧 strip:存量字段名带前导/尾随空格,queId 已同时给出不构成歧义
-        # (与 compiler 侧三个 resolve 函数同口径)。
-        name = raw_name.strip() if isinstance(raw_name, str) and raw_name.strip() else ""
+        name = raw_name if isinstance(raw_name, str) and raw_name else ""
         if raw_que_id is not None and que_id is None:
             return "schema", None
         if raw_name is not None and not name:
@@ -261,52 +239,26 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
             matches = [(path, field) for path, field in top_fields if field.get("queId") == que_id]
             if len(matches) != 1:
                 return "invalid", None
-            declared_name = str(matches[0][1].get("name") or "").strip()
+            declared_name = str(matches[0][1].get("name") or "")
             if name and declared_name and name != declared_name:
                 return "invalid", None
             return "resolved", matches[0]
         if name:
-            matches = [(path, field) for path, field in top_fields if str(field.get("name") or "").strip() == name]
+            matches = [(path, field) for path, field in top_fields if str(field.get("name") or "") == name]
             if len(matches) == 1:
                 return "resolved", matches[0]
             if len(matches) > 1:
-                return "ambiguous", None
+                return "invalid", None
             if any(not str(field.get("name") or "") for _, field in top_fields):
                 return "unknown", None
             return "invalid", None
         return "schema", None
 
-    def ambiguity_message(selector: Any, subject: str) -> str:
-        name = str((selector or {}).get("name") or "").strip()
-        candidate_ids = sorted(
-            {
-                field.get("queId")
-                for _, field in top_fields
-                if str(field.get("name") or "").strip() == name
-                and isinstance(field.get("queId"), int)
-                and not isinstance(field.get("queId"), bool)
-            }
-        )
-        return (
-            f"AMBIGUOUS_FIELD_SELECTOR: {subject} name {name!r} matches multiple fields "
-            f"(candidate queIds: {candidate_ids}); duplicate names are allowed but "
-            "selectors must use queId to disambiguate"
-        )
-
     title_selector = spec.get("dataTitleField")
     if top_fields:
         if "dataTitleField" not in spec and "appKey" in payload:
             pass
-        elif title_selector is None:
-            # dataTitleField=null 仅在带 appKey 的更新/round-trip 场景放行:后端写链
-            # FormSvcImpl.normalizeDataTitleQueId 对 null 自动 fallback 到第一个可用
-            # 字段,get 读面在后端未设置时原样输出 null。创建场景(无 appKey)仍需
-            # 显式 selector。
-            if "appKey" not in payload:
-                errors.append(("/spec/dataTitleField", "dataTitleField must resolve to exactly one top-level field"))
-        elif resolve_local_selector(title_selector)[0] == "ambiguous":
-            errors.append(("/spec/dataTitleField", ambiguity_message(title_selector, "dataTitleField")))
-        elif resolve_local_selector(title_selector)[0] == "invalid":
+        elif title_selector is None or resolve_local_selector(title_selector)[0] == "invalid":
             errors.append(("/spec/dataTitleField", "dataTitleField must resolve to exactly one top-level field"))
     elif title_selector is not None:
         errors.append(("/spec/dataTitleField", "dataTitleField must be null when body is empty"))
@@ -314,15 +266,11 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
     cover_selector = spec.get("dataCoverField")
     if cover_selector is not None:
         cover_resolution, cover = resolve_local_selector(cover_selector)
-        if cover_resolution == "ambiguous":
-            errors.append(("/spec/dataCoverField", ambiguity_message(cover_selector, "dataCoverField")))
-        elif cover_resolution == "invalid":
+        if cover_resolution == "invalid":
             errors.append(("/spec/dataCoverField", "dataCoverField must resolve to exactly one top-level field"))
         elif cover_resolution == "resolved" and cover is not None and _field_type(cover[1]) != "attachment":
             errors.append(("/spec/dataCoverField", "dataCoverField must select a top-level attachment field"))
-    # 方案 A(duplicate-field-name):同父级允许同名(后端以 queId 为身份,40013
-    # 实测 1624 组),不再报 duplicate name;歧义在 selector 解析处以
-    # AMBIGUOUS_FIELD_SELECTOR 显式拒绝。
+    names: dict[str, str] = {}
     fields_by_id = {
         field.get("queId"): field
         for _, field in top_fields
@@ -330,6 +278,12 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
     }
     output_targets: dict[str, tuple[str, str]] = {}
     for path, field in top_fields:
+        name = str(field.get("name") or "")
+        if name:
+            if name in names:
+                errors.append((f"{path}/name", f"duplicate top-level field name; first declared at {names[name]}"))
+            else:
+                names[name] = f"{path}/name"
         field_type = _field_type(field)
         if field_type == "data_relation":
             config = field.get("config") if isinstance(field.get("config"), dict) else {}
@@ -375,9 +329,6 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
             selector = item.get("field") if isinstance(item.get("field"), dict) else {}
             input_path = f"{path}/config/{binding_name}/inputs/{index}"
             resolution, selected = resolve_local_selector(selector)
-            if resolution == "ambiguous":
-                errors.append((f"{input_path}/field", ambiguity_message(selector, f"{binding_name}.inputs[{index}].field")))
-                continue
             if resolution == "invalid":
                 errors.append((f"{input_path}/field", "input field must resolve to exactly one top-level field"))
                 continue
@@ -429,16 +380,13 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
                         )
                     )
 
-        producer = str(field.get("name") or "") or str(field.get("queId") or field_type)
+        producer = name or str(field.get("queId") or field_type)
         for index, item in enumerate(binding.get("outputs") or []):
             if not isinstance(item, dict):
                 continue
             selector = item.get("targetField")
             target_path = f"{path}/config/{binding_name}/outputs/{index}/targetField"
             resolution, selected = resolve_local_selector(selector)
-            if resolution == "ambiguous":
-                errors.append((target_path, ambiguity_message(selector, f"{binding_name}.outputs[{index}].targetField")))
-                continue
             if resolution == "invalid":
                 errors.append((target_path, "targetField must resolve to exactly one top-level field"))
                 continue