@josephyan/qingflow-app-user-mcp 0.2.0-beta.23 → 0.2.0-beta.24

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.23
+npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.24
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.23 qingflow-app-user-mcp
+npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.24 qingflow-app-user-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.23",
+  "version": "0.2.0-beta.24",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "0.2.0b23"
+version = "0.2.0b24"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-record-analysis/SKILL.md

@@ -7,192 +7,81 @@ metadata:
 
 # Qingflow Record Analysis
 
-## Overview
-
-This skill is for record analysis inside existing Qingflow apps. Use it when the task is about `分析 / 洞察 / 分布 / 占比 / 平均 / 排名 / 趋势 / 所有 / 全部 / 全国 / 高价值` or any final statistical conclusion.
-
-This skill assumes the MCP is already connected and authenticated. If not, switch to `$qingflow-mcp-setup` first. If the task is about creating, updating, or deleting records rather than analyzing them, switch to `$qingflow-record-crud`. If it is about task-center actions, comments, approvals, rollback, transfer, or directory-driven workflow work, switch to `$qingflow-task-ops`.
-
-Before running analysis in `prod`, confirm the intended environment. If browser parity or live route debugging matters, call `record_analyze` with `output_profile=\"verbose\"` and compare `debug.request_route` with the browser route.
-
-## Tool Scope
-
-Use these tools as the core analysis surface:
-
-- `record_schema_get`
-- `record_analyze`
-
-Use `record_list` or `record_get` only when you need sample rows or a specific supporting example after the main analysis path.
-
-`record_schema_get` now returns the **current user's applicant-node visible schema only**:
-
-- hidden fields are omitted entirely
-- absent fields should be interpreted as `当前用户在申请人节点下不可见/不可用`
-- do not treat the schema as a builder/full-field metadata dump
-
-## Hard Rules
-
-- Analysis tasks must start with `record_schema_get`
-- Build one or more small DSLs, then run `record_analyze` separately for each question
-- DSL field references must use `field_id` only
-- Normalize relative time phrases into explicit legal date ranges before building the DSL
-- If the user asks for `最近一个完整自然月 / 上个月 / 最近30天 / 本季度 / 去年同期`, first convert that phrase into concrete dates, then verify the dates are legal before calling MCP
-- Never send impossible dates such as `2026-02-29`; if the intended month is February 2026, the legal upper bound is `2026-02-28`
-- If the schema still leaves multiple plausible fields, stop and ask the user to confirm from a short candidate list instead of guessing
-- Do not keep retrying different guessed field names in a loop
-- `record_list` is never the basis for a final statistical conclusion
-- If `record_list` is capped or paged, treat it as sample-only evidence
-- Do not mix full totals from `record_analyze` with sample-only list observations as one combined `全量结论`
-- Do not manually tune paging or scan-budget parameters for analysis; `record_analyze` hides them
-- For final conclusions, prefer `strict_full=true`
-- Before choosing a DSL shape, first decide whether the question needs `count`, `sum`, `avg`, `distinct_count`, `ratio`, or `ranking`
-- Do not guess a metric just because the user said `数量`, `单量`, `人数`, or `金额`
-- If one business question depends on multiple metrics, split it into smaller structured questions and build multiple focused DSLs
-- `渗透率 / 转化率 / 占比类结论必须先定义分子和分母`
-- Do not claim a metric you did not query.
-- Derived ratios must be computed outside the DSL after trusted numerator and denominator queries complete; do not invent `div`, `formula`, or expression metrics inside `record_analyze`
-- If the requested business question requires unsupported derived math, split it into multiple DSLs and compute the final ratio only in the reasoning layer after the source metrics are confirmed
-- If the user asks for multiple conclusions and only part of them is completed reliably, explicitly disclose which parts are complete and which parts remain unresolved
-
-## Standard Operating Order
-
-For analysis:
-
-1. Confirm target app and environment
-2. Run `record_schema_get`
-3. Inspect fields, aliases, suggested dimensions, suggested metrics, and suggested time fields
-4. Generate one or more field_id-based DSLs
-5. Run `record_analyze` once per DSL
-6. Run `record_list` only if you still need sample rows, examples, or manual inspection
-7. Before answering, separate:
-   - `全量可信结论`
-   - `样本观察`
-   - `待验证假设`
-
-## Semantic Guardrails
-
-- If the user asks for penetration, conversion, share-of-total, win rate, non-standard ratio, or any `%` metric, first write down:
-  - numerator definition
-  - denominator definition
-  - whether each side needs its own DSL
-- If you cannot name the denominator from real schema fields and filters, do not use words like `渗透率`, `转化率`, `占比`, `比例`, or `%`
-- If a field is still ambiguous after `record_schema_get`, do not guess; either select one unique `field_id` from the schema or ask the user to confirm from a short candidate list
-- If a business field is absent from `record_schema_get`, do not infer or guess a hidden `field_id`; explain that the field is not visible in the current applicant-node permission scope
-- If a statement depends on `count`, query `count`
-- If a statement depends on total amount, query `sum`
-- If a statement depends on average level, query `avg` or derive it from trusted `sum + count`
-- If a statement depends on trend, query a time dimension with `bucket`
-- If a statement depends on a ratio that the DSL cannot express directly, run the numerator and denominator separately, then compute the ratio outside MCP only after both sides are complete and compatible
-- Rankings must come from structured sorted results, not from loose natural-language restatement
-- When grouped rows are truncated, describe them as `已返回分组中` or `主要分组`
-- If `completeness.rows_truncated=true` or `completeness.statement_scope=returned_groups_only`, do not use words like `各部门`、`所有分组`、`完整名单`、`全部渠道`
-- If grouped rows are truncated, explicitly downgrade the wording to `前 N 个分组` or `主要分组`, never `全部`
-- Complex answers should default to `先结构、后解读`: present the table / metrics / ordering first, then add concise interpretation
-- Final wording should stay as close as possible to schema titles, dimension aliases, and metric aliases; do not rename the business object or field title unless the user asked for a rewrite
-
-## DSL Contract
-
-Use `record_schema_get` as the source of truth for every DSL field reference:
-
-- Use `fields[].field_id` in `dimensions[].field_id`, `metrics[].field_id`, and `filters[].field_id`
-- Treat `suggested_dimensions`, `suggested_metrics`, and `suggested_time_fields` as hints, not as executable DSL by themselves
-- Do not pass field titles, aliases, or guessed ids where `field_id` is required
-
-The `record_analyze` call should be built from this argument shape:
+## Step 1: `record_schema_get` → Step 2: build DSL → Step 3: `record_analyze`
 
-```json
-{
-  "app_key": "APP_1",
-  "dimensions": [],
-  "metrics": [],
-  "filters": [],
-  "sort": [],
-  "limit": 50,
-  "strict_full": true,
-  "view_key": null,
-  "view_name": null,
-  "output_profile": "normal"
-}
+This is the ONLY execution order. Never skip step 1. Never call `record_analyze` without a schema.
+
+Tools: `record_schema_get`, `record_analyze`. Use `record_list`/`record_get` only for sample rows AFTER analysis.
+
+---
+
+## DSL FORMAT (CRITICAL — read this FIRST)
+
+### ✅ Correct vs ❌ Wrong — learn from these before building ANY DSL
+
+**dimension item:**
+```
+✅ CORRECT:  { "field_id": 9500572, "alias": "报价类型" }
+❌ WRONG:    9500572                          ← bare integer, not a dict
+❌ WRONG:    "报价类型"                        ← string, not a dict
+❌ WRONG:    { "field_id": 9500572, "title": "报价类型" }  ← "title" is forbidden
 ```
 
-Top-level argument rules:
-
-- `app_key`: required. The target Qingflow app.
-- `dimensions`: required list. Use `[]` for whole-table summary. Use one item per grouping dimension for grouped analysis.
-- `metrics`: optional list. If omitted or empty, `record_analyze` defaults to a single `count` metric.
-- `filters`: optional list. Filters restrict the analyzed dataset before results are interpreted.
-- `sort`: optional list. Sorting applies to result rows, not raw source rows.
-- `limit`: positive integer. It only limits returned result rows; it does not reduce the internal scan scope.
-- `strict_full`: boolean. Prefer `true` for final conclusions. If `true`, incomplete scans return an error; if `false`, incomplete scans return partial results.
-- `view_key` / `view_name`: optional. Use a view to narrow scope before analysis. Prefer `view_key` when both are available.
-- `output_profile`: `normal` or `verbose`. Prefer `normal` unless you are debugging completeness or route issues.
-
-Item contracts:
-
-- `dimensions` item:
-  - shape: `{ "field_id": 2, "alias": "状态", "bucket": null }`
-  - `field_id`: required integer from `record_schema_get`
-  - `alias`: optional but recommended; if omitted, the field title becomes the alias
-  - `bucket`: optional; allowed values are `day`, `week`, `month`, `quarter`, `year`, or omitted / `null`
-  - `bucket` may only be used on fields from `suggested_time_fields`
-- `metrics` item:
-  - shape: `{ "op": "sum", "field_id": 7, "alias": "总金额" }`
-  - `op`: one of `count`, `sum`, `avg`, `min`, `max`, `distinct_count`
-  - `field_id`: required for `sum`, `avg`, `min`, `max`, `distinct_count`; do not pass it for `count`
-  - `alias`: optional but strongly recommended because `sort.by` must reference aliases
-- `filters` item:
-  - shape: `{ "field_id": 2, "op": "eq", "value": "进行中" }`
-  - `field_id`: required integer from `record_schema_get`
-  - `op`: optional; defaults to `eq`
-  - supported ops: `eq`, `neq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between`, `contains`, `is_null`, `not_null`
-  - value rules:
-    - `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`: pass a single scalar value
-    - `in`, `not_in`: pass an array
-    - `between`: pass a two-item array like `[min, max]`
-    - `is_null`, `not_null`: omit `value`
-- `sort` item:
-  - shape: `{ "by": "记录数", "order": "desc" }`
-  - `by`: required and must reference an alias already defined in `dimensions` or `metrics`
-  - `order`: optional; use `asc` or `desc`; default is `asc`
-  - do not sort by raw field title or `field_id`
-
-Practical rules:
-
-- Keep one DSL focused on one question. Prefer multiple small DSLs over one overloaded request.
-- Always set explicit aliases for metrics you may sort by, compare, or quote in the final answer.
-- For trend analysis, use one time dimension with `bucket`, then sort by that time alias ascending.
-- For cross analysis, use multiple `dimensions` and a small set of metrics.
-- Do not attempt formulas, joins, having clauses, cohort analysis, or manual paging controls in this DSL.
-- Do not pass unsupported keys such as `formula`, `expr`, `numerator`, `denominator`, `left`, `right`, or `operator` inside metric items.
-
-## Minimal DSL Templates
-
-Summary:
+**metric item — the key is `op`, NOT `type`/`agg`/`aggregation`:**
+```
+✅ CORRECT:  { "op": "count", "alias": "记录数" }
+✅ CORRECT:  { "op": "sum", "field_id": 7, "alias": "总金额" }
+❌ WRONG:    { "type": "count" }               ← "type" is NOT a valid key
+❌ WRONG:    { "agg": "count" }                ← "agg" is NOT a valid key
+❌ WRONG:    { "aggregation": "count" }         ← "aggregation" is NOT a valid key
+```
 
-```json
-{
-  "dimensions": [],
-  "metrics": [
-    { "op": "count", "alias": "记录数" }
-  ],
-  "filters": [],
-  "sort": [],
-  "limit": 1,
-  "strict_full": true
-}
+**filter item — the key is `op`, NOT `operator`:**
+```
+✅ CORRECT:  { "field_id": 2, "op": "between", "value": ["2024-03-01", "2024-03-31"] }
+✅ CORRECT:  { "field_id": 5, "op": "eq", "value": "已完成" }
+❌ WRONG:    { "field_id": 2, "operator": "between", "value": [...] }  ← "operator" is forbidden
+❌ WRONG:    { "field_id": 2, "op": ">=", "value": "2024-03-01" }      ← ">=" is not valid, use "gte"
 ```
 
-Single-dimension distribution:
+**sort item:**
+```
+✅ CORRECT:  { "by": "记录数", "order": "desc" }     ← "by" references an alias
+❌ WRONG:    { "by": 9500572, "order": "desc" }       ← field_id not allowed in sort
+```
+
+### Allowed keys per item (ANY other key = error)
+
+| Item | Allowed keys only |
+|------|-------------------|
+| dimension | `field_id`, `alias`, `bucket` |
+| metric | `op`, `field_id`, `alias` |
+| filter | `field_id`, `op`, `value` |
+| sort | `by`, `order` |
+
+### `op` values
+
+- metrics: `count`, `sum`, `avg`, `min`, `max`, `distinct_count`
+- filters: `eq`, `neq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between`, `contains`, `is_null`, `not_null`
+- For `count` metric: do NOT pass `field_id`. For all others: `field_id` is required.
+- If `metrics` is omitted or `[]`, defaults to `[{"op":"count","alias":"记录数"}]`.
+
+---
+
+## COMPLETE DSL TEMPLATE — copy, replace field_id, done
 
 ```json
 {
+  "app_key": "YOUR_APP_KEY",
   "dimensions": [
-    { "field_id": 2, "alias": "状态" }
+    { "field_id": FIELD_ID_FROM_SCHEMA, "alias": "维度名" }
   ],
   "metrics": [
     { "op": "count", "alias": "记录数" }
   ],
-  "filters": [],
+  "filters": [
+    { "field_id": TIME_FIELD_ID, "op": "between", "value": ["2024-03-01", "2024-03-31"] }
+  ],
   "sort": [
     { "by": "记录数", "order": "desc" }
   ],
@@ -201,67 +90,73 @@ Single-dimension distribution:
 }
 ```
 
-Time trend:
+More templates:
 
+**Whole-table count (no grouping):**
+```json
+{ "dimensions": [], "metrics": [{"op":"count","alias":"记录数"}], "strict_full": true }
+```
+
+**Monthly trend:**
 ```json
 {
-  "dimensions": [
-    { "field_id": 3, "alias": "月份", "bucket": "month" }
-  ],
-  "metrics": [
-    { "op": "count", "alias": "记录数" }
-  ],
-  "filters": [],
-  "sort": [
-    { "by": "月份", "order": "asc" }
-  ],
-  "limit": 24,
-  "strict_full": true
+  "dimensions": [{"field_id": 3, "alias": "月份", "bucket":"month"}],
+  "metrics": [{"op":"count","alias":"记录数"}],
+  "sort": [{"by":"月份","order":"asc"}],
+  "limit": 24, "strict_full": true
 }
 ```
 
-Two-dimensional cross analysis:
-
+**Cross analysis with sum:**
 ```json
 {
-  "dimensions": [
-    { "field_id": 2, "alias": "状态" },
-    { "field_id": 5, "alias": "负责人" }
-  ],
-  "metrics": [
-    { "op": "count", "alias": "记录数" },
-    { "op": "sum", "field_id": 7, "alias": "总金额" }
-  ],
-  "filters": [],
-  "sort": [
-    { "by": "记录数", "order": "desc" }
-  ],
-  "limit": 100,
-  "strict_full": true
+  "dimensions": [{"field_id": 2, "alias": "状态"}, {"field_id": 5, "alias": "负责人"}],
+  "metrics": [{"op":"count","alias":"记录数"}, {"op":"sum","field_id": 7, "alias":"总金额"}],
+  "sort": [{"by":"记录数","order":"desc"}],
+  "limit": 100, "strict_full": true
 }
 ```
 
-## Output Gate
-
-- Read aggregate rows from `result.rows`
-- Read overall totals from `result.totals.metric_totals`
-- Read sort intent from `query.sort`
-- Read ranked output from `ranking` when it is not `null`
-- Read ratio output from `ratios` when it is not `null`; `ratios=null` is normal when MCP did not produce a native ratio block
-- Read warning codes from `completeness.warnings`
-
-- Only write `全量可信结论` when the supporting `record_analyze` calls report `completeness.status=complete` and `safe_for_final_conclusion=true`
-- If any key analysis call is incomplete, downgrade the answer to `初步观察` or `部分结果`
-- Treat `safe_for_final_conclusion=true` as necessary but not sufficient when the metric definition is incomplete or grouped rows are truncated
-- If `completeness.statement_scope=returned_groups_only`, you may still give full-population conclusions about totals or ratios, but not a full grouped enumeration claim
-- If aggregate-style output is full but list evidence is sample-only, split the answer into:
-  - `全量可信结论`
-  - `样本观察（不作为最终结论）`
-  - optional `待验证假设`
-
-## Resources
-
-- Analysis patterns: [references/analysis-patterns.md](references/analysis-patterns.md)
-- Confidence reporting: [references/confidence-reporting.md](references/confidence-reporting.md)
-- Analysis gotchas: [references/analysis-gotchas.md](references/analysis-gotchas.md)
-- Shared environment guidance: [/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-app-user/references/environments.md](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-app-user/references/environments.md)
+### Top-level arguments
+
+- `app_key`: required.
+- `dimensions`: `[]` = whole-table summary; `[{...}]` = grouped.
+- `strict_full`: `true` for final conclusions. `false` allows partial results.
+- `limit`: limits returned rows only, not scan scope.
+- `view_key`/`view_name`: optional scope narrowing.
+- `bucket` in dimensions: only for `suggested_time_fields`. Values: `day`/`week`/`month`/`quarter`/`year`/`null`.
+
+---
+
+## RULES
+
+- All `field_id` MUST come from `record_schema_get`. Never guess or use field titles.
+- One DSL per question. Multiple small DSLs > one overloaded request.
+- Normalize relative dates to concrete ranges BEFORE building DSL. Never send impossible dates (e.g. `2026-02-29`).
+- If schema has ambiguous fields, ask user to pick from a short list. Do not guess.
+- `record_list` is NEVER the basis for final statistics.
+- Derived ratios: run numerator and denominator as separate DSLs, compute ratio in your reasoning.
+- Set `alias` for any metric you will sort by, compare, or quote.
+
+---
+
+## OUTPUT (CRITICAL — final answer must show concrete numbers)
+
+### 必须逐行列出数据（硬性要求）
+
+final_answer MUST include a table with every row from `result.rows`:
+
+| {维度别名} | {指标别名} | 占比 |
+|------------|-----------|------|
+| {row.dimensions.X} | {row.metrics.Y} | {Y / total * 100}% |
+
+- 占比 = 行指标值 / `result.totals.metric_totals` 总值, 保留一位小数
+- 如 `metric_totals` 不存在, 用各行之和作分母
+- 超过 20 行展示 Top 20 并注明
+- 不得只写"共 N 种类型"而省略明细
+
+### 结论分级
+
+- `safe_for_final_conclusion=true` → `全量可信结论`
+- 不完整 → `初步观察`
+- `rows_truncated=true` → 用 `前 N 个分组`, 不用 `全部`/`所有`

package/src/qingflow_mcp/tools/record_tools.py

@@ -38,6 +38,7 @@ ATTACHMENT_QUE_TYPES = {13}
 RELATION_QUE_TYPES = {25}
 SUBTABLE_QUE_TYPES = {18}
 VERIFY_UNSUPPORTED_WRITE_QUE_TYPES = {14, 34, 35, 36}
+LAYOUT_ONLY_QUE_TYPES = {24}
 DEPARTMENT_MEMBER_JUDGE_PREFIX = "deptId_"
 JUDGE_EQUAL = 0
 JUDGE_UNEQUAL = 1
@@ -1131,10 +1132,12 @@ class RecordTools(ToolBase):
             self._ensure_allowed_analyze_keys(
                 item,
                 location=f"metrics[{idx}]",
-                allowed_keys={"op", "field_id", "fieldId", "alias"},
+                allowed_keys={"op", "type", "agg", "aggregation", "field_id", "fieldId", "alias"},
                 example="{'op': 'sum', 'field_id': 7, 'alias': '总金额'}",
             )
-            op = _normalize_optional_text(item.get("op"))
+            op = _normalize_optional_text(
+                item.get("op") or item.get("type") or item.get("agg") or item.get("aggregation")
+            )
             if op not in supported_ops:
                 raise RecordInputError(
                     message=f"metrics[{idx}] uses unsupported op '{op}'",
@@ -1153,12 +1156,8 @@ class RecordTools(ToolBase):
                         details={"location": f"metrics[{idx}]", "field": _field_ref_payload(field), "op": op},
                     )
             elif item.get("field_id", item.get("fieldId")) is not None:
-                raise RecordInputError(
-                    message=f"metrics[{idx}] with op 'count' must not include field_id",
-                    error_code="INVALID_ANALYZE_METRIC",
-                    fix_hint="Remove field_id from count metrics.",
-                    details={"location": f"metrics[{idx}]", "op": op},
-                )
+                # LLM 经常给 count 传 field_id，静默忽略而非报错
+                pass
             alias = _normalize_optional_text(item.get("alias"))
             if alias is None:
                 if op == "count":
@@ -3995,16 +3994,19 @@ def _build_field_index(schema: JSONObject) -> FieldIndex:
         *[(question, False) for question in _flatten_questions(schema.get("formQues"))],
     ]
     for question, is_base_question in all_questions:
+        if not _should_index_question(question):
+            continue
         que_id = _coerce_count(question.get("queId"))
         title = _stringify_json(question.get("queTitle")).strip()
         if que_id is None or que_id < 0 or not title:
             continue
+        can_edit = question.get("canEdit")
         field = FormField(
             que_id=que_id,
             que_title=title,
             que_type=_coerce_count(question.get("queType")),
             required=bool(question.get("required") or question.get("beingRequired")),
-            readonly=bool(question.get("readonly") or question.get("beingReadonly") or is_base_question),
+            readonly=bool(question.get("readonly") or question.get("beingReadonly") or is_base_question or can_edit is False),
             system=bool(question.get("system") or question.get("beingSystem") or is_base_question),
             options=_extract_question_options(question),
             aliases=[],
@@ -4023,16 +4025,35 @@ def _build_field_index(schema: JSONObject) -> FieldIndex:
 def _flatten_questions(payload: JSONValue) -> list[JSONObject]:
     flattened: list[JSONObject] = []
     if isinstance(payload, dict):
-        if "queId" in payload or "queTitle" in payload:
+        is_question = "queId" in payload or "queTitle" in payload
+        if is_question:
             flattened.append(payload)
-        for value in payload.values():
-            flattened.extend(_flatten_questions(value))
+        for key in ("subQuestions", "innerQuestions", "subQues"):
+            value = payload.get(key)
+            if isinstance(value, list):
+                flattened.extend(_flatten_questions(value))
+        if not is_question:
+            for key in ("baseQues", "formQues"):
+                value = payload.get(key)
+                if isinstance(value, list):
+                    flattened.extend(_flatten_questions(value))
     elif isinstance(payload, list):
         for item in payload:
             flattened.extend(_flatten_questions(item))
     return flattened
 
 
+def _should_index_question(question: JSONObject) -> bool:
+    if bool(question.get("beingHide") or question.get("hidden")):
+        return False
+    if _coerce_count(question.get("quoteId")) is not None:
+        return False
+    que_type = _coerce_count(question.get("queType"))
+    if que_type in LAYOUT_ONLY_QUE_TYPES:
+        return False
+    return True
+
+
 def _extract_question_options(question: JSONObject) -> list[str]:
     options = question.get("options")
     if not isinstance(options, list):