@josephyan/qingflow-app-user-mcp 0.2.0-beta.16 → 0.2.0-beta.18

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.16",
+  "version": "0.2.0-beta.18",
   "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.0b16"
+version = "0.2.0b18"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-app-user/SKILL.md

@@ -21,8 +21,8 @@ When the task is in `prod`, browser parity matters, or the user says "the page h
 Primary record and data tools:
 
 - `record_query`
+- `record_schema_get`
 - `record_write_plan`
-- `record_field_resolve`
 - `record_create`
 - `record_get`
 - `record_update`
@@ -90,9 +90,10 @@ Do not use builder-side tools here:
 - Use `task_statistics` before `task_list` when the user only needs counts
 - Use `task_list_grouped` when worksheet or group buckets matter
 - Use `task_urge` only when the user clearly wants a reminder sent for a pending task
-- Use `record_field_resolve` when field selectors are ambiguous; if the task then turns into analysis, switch to `$qingflow-record-analysis`
+- Use `record_schema_get` when field selectors are ambiguous; if the task then turns into analysis, switch to `$qingflow-record-analysis`
 - For precise record lookup, use `record_get` when `apply_id` is known
-- Use `record_field_resolve` when the user gives field titles and you are not fully sure about the exact schema; do not guess ambiguous fields silently
+- Use `record_schema_get` when the user gives field titles and you are not fully sure about the exact schema; do not guess ambiguous fields silently
+- If the task has already shifted into analysis and `record_schema_get` still leaves multiple plausible fields, stop and ask the user to confirm the intended field instead of continuing to try read tools in a loop
 - Treat field selectors as schema-first and platform-generic. Prefer exact field titles, then neutral aliases such as `创建时间`, `新增时间`, `负责人`, `部门`, `时间`, or `阶段` only when the tool resolves them clearly. Do not assume CRM shorthand like `销售`, `商机阶段`, `客户全称`, or similar domain shortcuts apply across arbitrary Qingflow apps
 - For updates, inspect current data first unless the user already provided the exact target and patch
 - For deletes, confirm the exact record scope and report the deleted ids
@@ -124,9 +125,9 @@ When the user asks for demo data, seed, smoke data, or mock data:
 
 ## Response Interpretation
 
-- `record_query(summary)` and `record_aggregate` expose `completeness`; do not treat partial scans as final conclusions
-- `record_query(summary)` and `record_aggregate` now also expose `analysis_status`, `safe_for_final_conclusion`, and `analysis_counts`; if `status=partial_success` or `safe_for_final_conclusion=false`, do not present the result as final
-- For aggregate or summary answers, report both `backend_total_count` and `scanned_count` when coverage matters; for full analysis framing, switch to `$qingflow-record-analysis`
+- `record_query(query_mode="list")` is browse/sample output, not a final analysis result
+- If `record_query(query_mode="list")` reports `row_cap_hit`, `sample_only`, or capped rows, do not present it as full data
+- For grouped distributions, trends, or final statistical conclusions, switch to `$qingflow-record-analysis` and use `record_schema_get -> record_analyze`
 - `record_write_plan` is static preflight, not a guarantee that submit will pass runtime linkage or visibility checks
 - `record_create` now returns integer `apply_id`; you can pass that id directly into `record_get`, `record_update`, or `record_delete`
 - `verify_write=true` means the tool read the record back and compared the written fields; if it returns `status=verification_failed` or `ok=false`, do not report the create or update as successful

package/skills/qingflow-app-user/references/data-gotchas.md

@@ -5,14 +5,13 @@ For final statistics, grouped distributions, or insight-style analysis, use [$qi
 ## Counts
 
 - Prefer `effective_count`
-- For `record_query(summary)` and `record_aggregate`, inspect `completeness`, `analysis_status`, and `safe_for_final_conclusion` before concluding
-- If `status=partial_success`, treat the result as exploratory unless the user explicitly asked for a partial sample
+- For final analysis, inspect `record_analyze.data.completeness` and `safe_for_final_conclusion` before concluding
+- If `record_analyze.status!=success`, treat the result as exploratory unless the user explicitly asked for a partial sample
 - `record_query(list)` is for browsing and sample inspection. If it reports `row_cap_hit`, `sample_only`, or capped `returned_items`, do not present it as full data
 - When coverage matters, surface:
   - `backend_total_count`
   - `scanned_count`
-  - `unscanned_count`
-- Reuse `suggested_next_call` or `estimate.recommended_arguments` instead of inventing bigger scan settings by hand
+- Use narrower views, filters, or smaller analysis questions instead of inventing manual scan settings by hand
 - If the browser and MCP disagree, compare `request_route.base_url` and `request_route.qf_version` first
 - Do not mix a full aggregate total with sample-only list detail in one sentence like “基于全部数据分析”； split the answer into `全量结论` and `样本观察`
 
@@ -25,8 +24,8 @@ For final statistics, grouped distributions, or insight-style analysis, use [$qi
 
 - `record_write_plan` is static preflight only; linked visibility and runtime required rules can still reject writes
 - `record_write_plan` now exposes `write_format.support_level`; check `full / restricted / unsupported` before attempting non-trivial writes
-- Use `record_field_resolve` when field titles are uncertain instead of guessing ids
-- For analysis tasks, use the fixed preflight order `record_field_resolve -> record_query_plan -> summary/aggregate`; do not switch tools blindly after `FIELD_NOT_FOUND` or ambiguity
+- Use `record_schema_get` when field titles are uncertain instead of guessing ids
+- For analysis tasks, use the fixed path `record_schema_get -> record_analyze`; do not switch tools blindly after `FIELD_NOT_FOUND` or ambiguity
 - Prefer `strict_full=true` for final statistics or business conclusions
 - `record_create` and `record_update` can do post-write verification with `verify_write=true`; use that for complex, subtable, or production writes
 - `apply_id` is normalized to an integer; pass it directly into later record tools

package/skills/qingflow-app-user/references/record-patterns.md

@@ -9,9 +9,9 @@ Use `record_query` first when:
 - the user only gives a title or business key
 - the target record id is unknown
 - updates or deletes need confirmation
-- summary analysis or final counts are needed
+- ordinary list browsing or spot checks are needed
 
-Use `record_query_plan` first when:
+Use [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md) when:
 
 - field titles may be ambiguous
 - filters are still in natural-language shape
@@ -22,14 +22,13 @@ Use `record_query_plan` first when:
 
 ## Final analysis pattern
 
-1. Run `record_query_plan`
-2. If the plan exposes `estimate.recommended_arguments` or `suggested_next_call`, prefer those arguments directly
-3. Run `record_query(query_mode="summary", strict_full=true, auto_expand_pages=true)` to confirm the total scope
-4. Run `record_aggregate(strict_full=true, auto_expand_pages=true)` for grouped results
-5. Run `record_query(query_mode="list")` only if you still need sample rows or examples
-6. Report `backend_total_count`, `scanned_count`, and whether the result is safe for a final conclusion
-7. If `status=partial_success` or `safe_for_final_conclusion=false`, stop at “partial result” instead of presenting a final business conclusion
-8. If list rows are sample-only, separate the answer into:
+1. Run `record_schema_get`
+2. Generate one or more field_id-based DSLs
+3. Run `record_analyze(strict_full=true)` for summary/distribution/trend/cross analysis
+4. Run `record_query(query_mode="list")` only if you still need sample rows or examples
+5. Report `backend_total_count`, `scanned_count`, and whether the result is safe for a final conclusion
+6. If `status=error` or `safe_for_final_conclusion=false`, stop at “partial result” instead of presenting a final business conclusion
+7. If list rows are sample-only, separate the answer into:
    - `全量可信结论`
    - `样本观察（不作为最终结论）`
    - optional `待验证假设`
@@ -42,12 +41,12 @@ Do not do this:
 2. Get `200` rows back
 3. Report平均值、占比、地域分布 as if they were based on all records
 
-This is not acceptable because the list endpoint can be capped. Use `record_query_plan -> summary -> aggregate` first, then treat list rows as sample-only evidence.
+This is not acceptable because the list endpoint can be capped. Use `record_schema_get -> record_analyze` first, then treat list rows as sample-only evidence.
 
 ## Create pattern
 
 1. Confirm target app
-2. Resolve fields with `record_field_resolve` if needed. Prefer exact schema titles first; only rely on platform-neutral aliases such as `创建时间`, `负责人`, or `部门` when they resolve cleanly, and do not assume business-domain shorthand like `销售` is portable across apps
+2. Resolve fields with `record_schema_get` if needed. Prefer exact schema titles first; only rely on platform-neutral aliases such as `创建时间`, `负责人`, or `部门` when they resolve cleanly, and do not assume business-domain shorthand like `销售` is portable across apps
 3. Run `record_write_plan` for non-trivial payloads or any `fields`-based write
 4. For relation fields, query the target app first and resolve the referenced record `apply_id`
 5. For attachments, call `file_upload_local` first and reuse the returned `attachment_value`

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

@@ -2,7 +2,7 @@
 name: qingflow-record-analysis
 description: Analyze Qingflow record data safely after the MCP is already connected and authenticated. Use when the user wants grouped distributions, ratios, averages, rankings, trends, insights, or any final statistical conclusion across an existing app's data. Do not use this skill for schema changes, app design, or ordinary record CRUD unless they are strictly supporting an analysis flow.
 metadata:
-  short-description: Analyze Qingflow record data with plan-first, sample-safe reporting
+  short-description: Analyze Qingflow record data with schema-first DSL execution
 ---
 
 # Qingflow Record Analysis
@@ -19,47 +19,194 @@ Before running analysis in `prod`, confirm the intended environment and compare
 
 Use these tools as the core analysis surface:
 
-- `record_field_resolve`
-- `record_query_plan`
-- `record_query`
-- `record_aggregate`
+- `record_schema_get`
+- `record_analyze`
 
-Use `record_get` or ordinary `record_query(list)` only when you need sample rows or a specific supporting example after the main analysis path.
+Use `record_query(query_mode="list")` or `record_get` only when you need sample rows or a specific supporting example after the main analysis path.
 
 ## Hard Rules
 
-- Analysis tasks must start with `record_query_plan`
-- If fields are uncertain, the fixed order is:
-  1. `record_field_resolve`
-  2. `record_query_plan`
-  3. `record_query(summary)` and/or `record_aggregate`
+- 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
+- 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_query(list)` is never the basis for a final statistical conclusion
 - If `record_query(list)` reports `row_cap_hit`, `sample_only`, capped `returned_items`, or compact output, treat it as sample-only evidence
-- Do not mix full totals from `summary` or `aggregate` with sample-only list observations as one combined “全量结论”
-- Reuse `record_query_plan.estimate.recommended_arguments` or `suggested_next_call` instead of guessing scan parameters
-- For final conclusions, prefer `strict_full=true` and `auto_expand_pages=true`
+- 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`
 
 ## Standard Operating Order
 
 For analysis:
 
 1. Confirm target app and environment
-2. If field names are uncertain, run `record_field_resolve`
-3. Run `record_query_plan`
-4. Reuse MCP-recommended arguments from `suggested_next_call` or `estimate.recommended_arguments`
-5. Run `record_query(query_mode="summary", strict_full=true, auto_expand_pages=true)` to establish full scope
-6. Run `record_aggregate(strict_full=true, auto_expand_pages=true)` for grouped distributions, ranking, ratios, averages, or trends
-7. Run `record_query(query_mode="list")` only if you still need sample rows, examples, or manual inspection
-8. Before answering, separate:
+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_query(query_mode="list")` only if you still need sample rows, examples, or manual inspection
+7. Before answering, separate:
    - `全量可信结论`
    - `样本观察`
    - `待验证假设`
 
+## 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:
+
+```json
+{
+  "app_key": "APP_1",
+  "dimensions": [],
+  "metrics": [],
+  "filters": [],
+  "sort": [],
+  "limit": 50,
+  "strict_full": true,
+  "view_key": null,
+  "view_name": null,
+  "output_profile": "normal"
+}
+```
+
+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.
+
+## Minimal DSL Templates
+
+Summary:
+
+```json
+{
+  "dimensions": [],
+  "metrics": [
+    { "op": "count", "alias": "记录数" }
+  ],
+  "filters": [],
+  "sort": [],
+  "limit": 1,
+  "strict_full": true
+}
+```
+
+Single-dimension distribution:
+
+```json
+{
+  "dimensions": [
+    { "field_id": 2, "alias": "状态" }
+  ],
+  "metrics": [
+    { "op": "count", "alias": "记录数" }
+  ],
+  "filters": [],
+  "sort": [
+    { "by": "记录数", "order": "desc" }
+  ],
+  "limit": 50,
+  "strict_full": true
+}
+```
+
+Time trend:
+
+```json
+{
+  "dimensions": [
+    { "field_id": 3, "alias": "月份", "bucket": "month" }
+  ],
+  "metrics": [
+    { "op": "count", "alias": "记录数" }
+  ],
+  "filters": [],
+  "sort": [
+    { "by": "月份", "order": "asc" }
+  ],
+  "limit": 24,
+  "strict_full": true
+}
+```
+
+Two-dimensional cross analysis:
+
+```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
+}
+```
+
 ## Output Gate
 
-- If `record_query_plan` was not used, downgrade the answer to `初步观察`
-- If `safe_for_final_conclusion=false`, do not present the result as a final conclusion
-- If aggregate/summary is full but list evidence is sample-only, split the answer into:
+- 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 `部分结果`
+- If aggregate-style output is full but list evidence is sample-only, split the answer into:
   - `全量可信结论`
   - `样本观察（不作为最终结论）`
   - optional `待验证假设`

package/skills/qingflow-record-analysis/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Qingflow Record Analysis"
-  short_description: "Analyze Qingflow record data with plan-first, sample-safe reporting"
-  default_prompt: "Use $qingflow-record-analysis for grouped distributions, ratios, rankings, trends, and final statistical conclusions in Qingflow apps. Start with record_query_plan, treat record_query(list) as sample-only when capped, and separate full conclusions from sample observations."
+  short_description: "Analyze Qingflow record data with schema-first DSL execution"
+  default_prompt: "Use $qingflow-record-analysis for grouped distributions, ratios, rankings, trends, and final statistical conclusions in Qingflow apps. Start with record_schema_get, build one or more field_id-based DSLs, then run record_analyze. Treat record_query(query_mode=\"list\") as sample-only when capped, and separate full conclusions from sample observations."

package/skills/qingflow-record-analysis/references/analysis-gotchas.md

@@ -1,18 +1,19 @@
 # Analysis Gotchas
 
-## Do not skip plan
+## Do not skip schema
 
-If the task is analysis-style and you jump straight to `record_query(list)` or `record_aggregate`, you are already off the stable path.
+If the task is analysis-style and you jump straight to `record_query(query_mode="list")` or `record_analyze`, you are already off the stable path.
 
 Correct recovery:
 
-1. `record_field_resolve` if fields are uncertain
-2. `record_query_plan`
-3. follow the recommended chain
+1. `record_schema_get`
+2. inspect the schema and choose fields
+3. build one or more small DSLs
+4. run `record_analyze`
 
 ## Do not treat 200-row list output as full data
 
-`record_query(list)` can hit:
+`record_query(query_mode="list")` can hit:
 
 - `row_cap=200`
 - `row_cap_hit=true`
@@ -29,9 +30,9 @@ It is not acceptable to use that result alone for:
 - 地域分布
 - “基于全部数据”的 business insight
 
-## Do not mix full aggregate totals with sample rows
+## Do not mix full analyze totals with sample rows
 
-If summary or aggregate gives full-population coverage, but list rows are capped, do not merge them into one final statement.
+If `record_analyze` gives full-population coverage, but list rows are capped, do not merge them into one final statement.
 
 Split them into:
 
@@ -45,17 +46,30 @@ If the field is uncertain:
 - do not bounce across tools
 - do not guess ids
 - do not switch from one read tool to another by trial and error
+- do not keep retrying different guessed field names in a loop
 
 Correct recovery:
 
-1. `record_field_resolve`
-2. `record_query_plan`
+1. `record_schema_get`
+2. if several plausible candidates remain, ask the user to confirm from a short list
+3. build the DSL only after the field is clear
 
-## Do not override MCP scan recommendations casually
+Examples of the right recovery question:
 
-If `record_query_plan` returns:
+- “我找到两个可能的字段：`线索来源`、`来源渠道`。你要按哪个字段统计？”
+- “目前最像‘来源’的字段有这三个：`来源`、`来源渠道`、`获客来源`。请确认你要按哪个字段分析。”
 
-- `estimate.recommended_arguments`
-- `suggested_next_call`
+## Do not try to control paging manually
 
-reuse them first. These are safer than hand-tuning `page_size`, `requested_pages`, and `scan_max_pages` from memory.
+`record_analyze` hides paging and scan budget on purpose.
+
+- Do not invent `page_size`
+- Do not invent `requested_pages`
+- Do not invent `scan_max_pages`
+- Do not invent `auto_expand_pages`
+
+When the result is incomplete:
+
+1. narrow the scope with views or filters
+2. reduce the analysis problem into smaller DSLs
+3. keep the answer at `初步观察` or `部分结果` if completeness is still not enough

package/skills/qingflow-record-analysis/references/analysis-patterns.md

@@ -15,42 +15,47 @@ Use this skill when the user asks for:
 
 ## Canonical analysis sequence
 
-1. `record_query_plan`
-2. `record_query(query_mode="summary", strict_full=true, auto_expand_pages=true)`
-3. `record_aggregate(strict_full=true, auto_expand_pages=true)`
+1. `record_schema_get`
+2. build one or more field_id-based DSLs
+3. `record_analyze`
 4. `record_query(query_mode="list")` only for sample inspection
 
 ## Distribution / ratio pattern
 
-1. Resolve ambiguous fields with `record_field_resolve` if needed
-2. Run `record_query_plan`
-3. Confirm total scope with `record_query(summary)`
-4. Run `record_aggregate` with `group_by`
-5. Report:
+1. Run `record_schema_get`
+2. Inspect candidate fields and aliases
+3. If several plausible candidates remain, stop and ask the user to confirm the field from a short list
+4. Build a DSL with:
+   - one dimension
+   - `count`
+   - sort by the count alias
+5. Run `record_analyze`
+6. Report:
    - `backend_total_count`
    - `scanned_count`
    - `safe_for_final_conclusion`
 
 ## Average / ranking pattern
 
-1. Run `record_query_plan`
-2. Run `record_query(summary)` to confirm scan coverage
-3. Run `record_aggregate` with:
-   - `group_by`
-   - `amount_column`
-   - `metrics=["count","avg"]` or `["count","sum"]`
-4. Use list-mode only to inspect examples after the aggregate result is understood
+1. Run `record_schema_get`
+2. Choose one dimension field and one numeric metric field
+3. Build a DSL with:
+   - `dimensions=[...]`
+   - `metrics=[count,sum]` or `metrics=[count,avg,min,max]`
+4. Run `record_analyze`
+5. Use list mode only to inspect examples after the aggregate result is understood
 
 ## Trend pattern
 
-1. Run `record_query_plan`
-2. Run `record_query(summary)` with a clear `time_range`
-3. Run `record_aggregate` with `time_bucket`
-4. Treat the result as final only if `safe_for_final_conclusion=true`
+1. Run `record_schema_get`
+2. Choose a date/time field from `suggested_time_fields`
+3. Build a DSL with `bucket=day|week|month|quarter|year`
+4. Run `record_analyze`
+5. Treat the result as final only if `safe_for_final_conclusion=true`
 
 ## Sample inspection pattern
 
-Only use `record_query(list)` after plan/summary/aggregate when you need:
+Only use `record_query(query_mode="list")` after schema/analyze when you need:
 
 - example rows
 - spot checks
@@ -58,3 +63,14 @@ Only use `record_query(list)` after plan/summary/aggregate when you need:
 - manual inspection of records behind an aggregate bucket
 
 Never use list mode alone to justify final averages, shares, rankings, or regional distribution claims.
+
+## Ambiguous field recovery
+
+If the user asks for something like “来源分布” or “类型占比” and the exact field is unclear:
+
+1. run `record_schema_get`
+2. inspect titles, aliases, and suggested fields
+3. if one candidate is clearly dominant, proceed
+4. if multiple candidates are still plausible, ask the user to confirm which field they want
+
+Do not keep retrying different guessed field names in a loop.

package/skills/qingflow-record-analysis/references/confidence-reporting.md

@@ -12,30 +12,30 @@ When analysis is intended as a final answer, use this order:
 
 Only write `全量可信结论` when:
 
-- `record_query_plan` was used
-- the analysis path used `summary` and/or `aggregate`
-- `safe_for_final_conclusion=true`
+- `record_schema_get` was used
+- the analysis path used one or more `record_analyze` calls
+- every key analysis result has `safe_for_final_conclusion=true`
 - the result is not just a capped list sample
 
 ## Sample observation gate
 
 Put evidence into `样本观察` when:
 
-- it came from `record_query(list)`
+- it came from `record_query(query_mode="list")`
 - the tool reports `row_cap_hit`
 - the tool reports `sample_only`
 - the result is compact/capped and not complete
 
 ## Downgrade rule
 
-If `record_query_plan` was not used for an analysis task, downgrade the overall framing to `初步观察` instead of `洞察` or `结论`.
+If `record_schema_get` was not used for an analysis task, downgrade the overall framing to `初步观察` instead of `洞察` or `结论`.
 
 ## Anti-mixing rule
 
 Do not combine:
 
-- full totals from `record_query(summary)` or `record_aggregate`
-- sample-only details from `record_query(list)`
+- full totals from `record_analyze`
+- sample-only details from `record_query(query_mode="list")`
 
 into one sentence like “基于全部数据分析...”.
 

package/src/qingflow_mcp/__init__.py

@@ -2,4 +2,4 @@ from __future__ import annotations
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0b16"
+__version__ = "0.2.0b18"

package/src/qingflow_mcp/server.py

@@ -28,6 +28,8 @@ def build_server() -> FastMCP:
         instructions=(
             "Use auth_login first, then workspace_list and workspace_select. "
             "All resource tools operate with the logged-in user's Qingflow permissions.\n\n"
+            "For analytics, use record_schema_get first, let the model build field_id-based DSL, "
+            "then call record_analyze. Use record_query for list/detail browsing only.\n\n"
             "Task Center (待办/已办) handling:\n"
             "- Use task_statistics to get counts of pending tasks (todo_count), timeouts, urged, etc.\n"
             "- Use task_list to query tasks. Type values: 1=todo (待办), 2=initiated (我发起的), 3=cc (抄送), 5=done (已办).\n"

package/src/qingflow_mcp/server_app_user.py

@@ -18,8 +18,9 @@ def build_user_server() -> FastMCP:
     server = FastMCP(
         "Qingflow App User MCP",
         instructions=(
-            "Use this server for Qingflow record queries, record writes, task center operations, "
-            "directory lookups, and approval actions. Avoid builder-side app or schema changes here."
+            "Use this server for Qingflow record queries, schema-first analytics via record_schema_get and record_analyze, "
+            "record writes, task center operations, directory lookups, and approval actions. "
+            "Use record_query for list/detail reads only. Avoid builder-side app or schema changes here."
         ),
     )
     sessions = SessionStore()