@josephyan/qingflow-app-user-mcp 1.0.9 → 1.1.1

package/skills/qingflow-mcp-setup/scripts/check_local_server.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="${QINGFLOW_MCP_ROOT:-}"
+
+if [[ -z "$ROOT" ]]; then
+  if git_root="$(git rev-parse --show-toplevel 2>/dev/null)" && [[ -d "$git_root/qingflow-support/mcp-server" ]]; then
+    ROOT="$git_root/qingflow-support/mcp-server"
+  elif [[ -d "$PWD/qingflow-support/mcp-server" ]]; then
+    ROOT="$PWD/qingflow-support/mcp-server"
+  else
+    repo_root="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+    if [[ -d "$repo_root/qingflow-support/mcp-server" ]]; then
+      ROOT="$repo_root/qingflow-support/mcp-server"
+    fi
+  fi
+fi
+
+if [[ -z "$ROOT" ]]; then
+  echo "Unable to locate qingflow-support/mcp-server. Set QINGFLOW_MCP_ROOT to the repo copy of the MCP server." >&2
+  exit 1
+fi
+
+ENTRY="$ROOT/qingflow-mcp"
+PY="$ROOT/.venv/bin/python"
+
+echo "ROOT=$ROOT"
+test -d "$ROOT"
+echo "OK root exists"
+
+test -x "$ENTRY"
+echo "OK entrypoint exists and is executable"
+
+test -x "$PY"
+echo "OK virtualenv python exists"
+
+PYTHONPATH="$ROOT/src" "$PY" -c "import qingflow_mcp.server; print('OK import qingflow_mcp.server')"

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

@@ -1,68 +1,71 @@
 ---
 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.
+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, comparisons, or any final statistical conclusion across an existing app's data. Default to schema-first record_access CSV retrieval plus local Python/pandas; do not use export tools unless the user explicitly asks for a file download.
 metadata:
-  short-description: Analyze Qingflow record data with schema-first CSV access and Python
+  short-description: Analyze Qingflow record data with record_access CSV and Python
 ---
 
 # Qingflow Record Analysis
 
-This skill is for final statistical conclusions only.
-Assumes MCP is connected, authenticated, and on the correct workspace.
-Analysis tasks must start with `app_get`, then `record_browse_schema_get(view_id=...)`. `record_browse_schema_get.fields` is the selected Qingflow table view's readable header schema and is the same field source used by `record_access.fields` / `schema.json`. Read top-level `fields` and `suggested_*`, then choose field_id-based columns and filters only.
-If `app_get.accessible_views` marks a view with `analysis_supported=false`, do not use that view for `record_access`, `record_list`, or `record_analyze`. `boardView` and `ganttView` are special UI views, not data-access targets.
+Use this skill only for final statistical conclusions: counts, distributions, ratios, averages, rankings, trends, comparisons, and analysis reports.
 
-## Step 1: `app_get` → Step 2: `record_browse_schema_get(view_id=...)` → Step 3: `record_access` → Step 4: Python
+Default path, every time:
 
-This is the default execution order. Never skip `app_get` when the browse range is unclear. Never call `record_access` without a browse schema.
-
-Core tools: `app_get`, `record_browse_schema_get`, `record_access`, Python. Use field_id-based DSLs only for columns, filters, sort clauses, and any optional lightweight `record_analyze` helper. Use `record_list`/`record_get` only for browse samples. Use `record_analyze` only as a lightweight non-default statistics helper when a compact grouped result is enough. Task/comment work stays in [$qingflow-task-ops](../qingflow-task-ops/SKILL.md).
-For analysis-style tasks, prefer a concrete time range or business filter. If the user did not give one and the data could be large, ask for scope instead of trying an unbounded historical scan.
-
-## Execution Modes
-
-Choose the lightest mode that can still support a trustworthy conclusion:
-
-1. `client_python_from_record_access`
-   - Default and preferred path
-   - Use `record_access` directly after `app_get -> record_browse_schema_get`
-   - Read CSV shard files from `files[].local_path` with Python
-   - Treat `complete=true` and `safe_for_final_conclusion=true` as required before giving a full-scope final conclusion
-
-2. `lightweight_record_analyze`
-   - Optional helper for small grouped summaries or quick sanity checks
-   - Still requires `app_get -> record_browse_schema_get` first
-   - Do not make this the default agent path
-
-3. `cross_app_manual_reconcile`
-   - Use when the question depends on joining multiple apps, organization-history alias mapping, or other business logic that current public tools do not express directly
-   - Be explicit that the conclusion is based on manual reconciliation rules, not one single app's CSV access
-
-## Fallback Ladder
-
-Trigger a fallback when any of these are true:
-
-- `record_access` returns `complete=false`, `truncated=true`, or `safe_for_final_conclusion=false`
-- the target view is unsupported for data access
-- field semantics are ambiguous enough that local aggregation would be misleading
-- the question requires cross-app reconciliation
-- the question depends on organization-tree scope, historical department aliases, or other business rules that are not first-class MCP filters
-
-When you fall back:
-
-1. Keep the standard read order: `app_get -> record_browse_schema_get`
-2. State which fallback mode you chose
-3. State whether the result is still full-scope or only a verified subset
-4. State the time field, organization scope, and any alias mapping used
-5. Prefer concrete numbers plus a conservative conclusion over broad wording
-
----
+```text
+app_get -> record_browse_schema_get(view_id=...) -> record_access -> Python/pandas -> final answer
+```
 
-## DSL Contract
+`record_access` may appear either as an MCP tool or as a CLI subcommand. If the active client does not expose an MCP `record_access` tool, do not switch to aggregate helpers. Use the CLI entry instead:
 
-### `record_access` Contract
+```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
+```
 
-Use `record_access` to fetch detail rows into local CSV shards. It does not analyze, aggregate, or return large `items`.
+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_browse_schema_get`.
+- Use only field ids returned by `record_browse_schema_get.fields`.
+- 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 | `$qingflow-task-ops` |
+
+## Standard Procedure
+
+1. Run `app_get` and choose a table-style `view_id` from `accessible_views`.
+2. Run `record_browse_schema_get(app_key, 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 `record_access` through MCP if visible, otherwise through `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
 {
@@ -74,156 +77,61 @@ Use `record_access` to fetch detail rows into local CSV shards. It does not anal
 }
 ```
 
-Then run Python against every `files[].local_path`. CSV columns are stable: `record_id`, then `field_<field_id>`. Use `fields[]` plus `metadata_files.schema` / `metadata_files.readme` in the same output directory to map titles and types, especially when reusing the CSV later.
-
-- Never ask for `page`, `page_size`, `limit`, or `max_rows`; `record_access` owns paging internally and follows the backend's native paging capability.
-- Never treat backend `searchQueIds` as column selection; it is only a full-text search scope.
-- If multiple CSV files are returned, read them all.
-- If `status=needs_scope`, no CSV was written; use `scope.suggested_time_fields` / `scope.recommended_where_examples` to ask for or apply a time/business range, then call `record_access` again.
-- If `status=partial`, read the returned files only as a limited subset; state the limitation and do not present a full-population final conclusion.
-- If `complete=false` or `safe_for_final_conclusion=false`, downgrade the answer and disclose the limitation.
-- `record_export_direct` is only for explicit export/download/Excel requests, not default analysis.
-- QingBI/report reads are only for user-provided report URLs or `chart_id`; do not create or use reports as the default analysis path.
-
-### `record_analyze` Lightweight DSL
+Never pass `page`, `page_size`, `limit`, `max_rows`, `timeout`, or `profile` to `record_access`.
 
-### DSL FORMAT (CRITICAL — read this FIRST)
+CSV columns are already readable and field-id anchored, for example `项目状态__field_343283094`. Do not expect separate `schema.json` or `README.md` files.
 
-### ✅ Correct vs ❌ Wrong — learn from these before building ANY DSL
+For CLI use, write JSON argument files instead of embedding large JSON in shell text:
 
-**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
+```bash
+qingflow record access \
+  --app-key APP_KEY \
+  --view-id system:all \
+  --columns-file columns.json \
+  --where-file where.json \
+  --order-by-file order_by.json \
+  --json
 ```
 
-**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
-```
+## Status Handling
 
-**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"
-```
+Read `record_access.status` before reading files or writing conclusions.
 
-**sort item:**
-```
-✅ CORRECT:  { "by": "记录数", "order": "desc" }     ← "by" references an alias
-❌ WRONG:    { "by": 9500572, "order": "desc" }       ← field_id not allowed in sort
-```
+- `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.
 
-### Allowed keys per item (ANY other key = error)
+## Business Context
 
-| Item | Allowed keys only |
-|------|-------------------|
-| dimension | `field_id`, `alias`, `bucket` |
-| metric | `op`, `field_id`, `alias` |
-| filter | `field_id`, `op`, `value` |
-| sort | `by`, `order` |
+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.
 
-### `op` values
+Example: if `烈焰组` and `飓风组` are sub-departments of `北斗部门`, apply that mapping in Python and state it in the answer.
 
-- 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":"记录数"}]`.
+## Output Shape
 
----
+Default to:
 
-See [references/dsl-templates.md](references/dsl-templates.md) for complete copy-paste templates.
+1. `结论`
+2. `关键数据`
+3. `口径与范围`
+4. `可信度 / 限制`
 
-**Typical summary / distribution:**
-```json
-{
-  "dimensions": [{ "field_id": FIELD_ID_FROM_SCHEMA, "alias": "维度名" }],
-  "metrics": [{ "op": "count", "alias": "记录数" }],
-  "sort": [{ "by": "记录数", "order": "desc" }],
-  "limit": 50,
-  "strict_full": true
-}
-```
+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.
 
-**Typical time-filter / trend:**
-```json
-{
-  "dimensions": [{ "field_id": TIME_FIELD_ID, "alias": "月份", "bucket": "month" }],
-  "metrics": [{ "op": "count", "alias": "记录数" }],
-  "filters": [{ "field_id": TIME_FIELD_ID, "op": "between", "value": ["2024-03-01", "2024-03-31"] }],
-  "sort": [{ "by": "月份", "order": "asc" }],
-  "limit": 24,
-  "strict_full": true
-}
-```
+## References
 
-Top-level arguments:
+Load only what is needed:
 
-- `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_id`: the canonical browse selector. Prefer choosing it from `app_get.accessible_views`.
-- Prefer `view_id` entries where `analysis_supported=true`. If a view is `boardView` or `ganttView`, switch to a system or table-style custom view before calling `record_access` or `record_analyze`.
-- If a chosen `view_id` is `custom:*`, treat the output as analysis over an unverified saved-filter scope unless `verification.view_filter_verified=true`. For critical conclusions, prefer `system:all` plus explicit filters in the DSL.
-- `bucket` in dimensions: only for `suggested_time_fields`. Values: `day`/`week`/`month`/`quarter`/`year`/`null`.
-
----
-
-## RULES
-
-- 渗透率 / 转化率 / 占比类结论必须先定义分子和分母。
-- Do not claim a metric you did not query.
-- Derived ratios must be computed outside the DSL.
-- Before choosing a DSL shape, first decide whether the question needs `count`, `sum`, `avg`, `distinct_count`, `ratio`, or `ranking`.
-- Rankings must come from structured sorted results.
-- For partial answers, explicitly disclose which parts are complete and which parts remain unresolved.
-- Complex answers should default to `先结构、后解读`.
-- `between`: pass a two-item array.
-- Sort entries must reference an alias already defined in `dimensions` or `metrics`.
-- Final wording should stay as close as possible to schema titles.
-- Do not pass field titles, aliases, or guessed ids.
-- If `completeness.statement_scope=returned_groups_only` or `completeness.rows_truncated=true`, downgrade wording to returned groups only.
-- One data-access request per coherent dataset. Multiple small Python computations over the same CSV files are fine.
-- `record_list` is not the basis for final statistics. Use it only for browse/sample inspection and disclose that scope if quoted.
-- Set `alias` for any metric you will sort by, compare, or quote.
-
----
-
-## OUTPUT
-
-- Final answer must show concrete numbers.
-- Final answer must state which execution mode was used whenever the answer is not the default `client_python_from_record_access`
-- If `result.rows` exists, list each returned row; if there are more than 20 rows, show Top 20 and say so.
-- 占比 = 行指标值 / `result.totals.metric_totals` 总值；如 `metric_totals` 缺失，用各行之和作分母。
-- Prefer the structured `ranking` block when it exists.
-- `safe_for_final_conclusion=true` → `全量可信结论`
-- Otherwise → `初步观察`
-- `rows_truncated=true` → 用 `前 N 个分组`, 不用 `全部`/`所有`
-- If you used a fallback mode or `record_access.safe_for_final_conclusion=false`, explicitly disclose:
-  - whether this is full-scope or a manually curated subset
-  - which time field was used
-  - which organization scope was used
-  - whether any historical department aliases or cross-app joins were applied
+- Data access status machine: [references/data-access-playbook.md](references/data-access-playbook.md)
+- Python/pandas templates: [references/pandas-recipes.md](references/pandas-recipes.md)
+- Analysis patterns: [references/analysis-patterns.md](references/analysis-patterns.md)
+- Business mappings and scope: [references/business-context.md](references/business-context.md)
+- Confidence and final wording: [references/confidence-reporting.md](references/confidence-reporting.md)
+- Common mistakes: [references/analysis-gotchas.md](references/analysis-gotchas.md)
+- Report templates: [references/report-format.md](references/report-format.md)
 
 ## Feedback Escalation
 
-- If the desired analysis still cannot be completed because of missing capability, unsupported analysis shape, or an obviously awkward workflow after reasonable attempts, summarize the exact gap.
-- Ask whether the user wants you to submit product feedback.
-- Only after explicit user confirmation, call `feedback_submit`.
-
-## Resources
-
-- Shared public-surface baseline: [public-surface-sync.md](../qingflow-app-user/references/public-surface-sync.md)
-- DSL templates: [references/dsl-templates.md](references/dsl-templates.md)
-- 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)
+If the desired analysis cannot be completed because of missing capability, unsupported data shape, or an awkward workflow after reasonable attempts, summarize the exact gap and ask whether to submit product feedback. Only after explicit user confirmation, call `feedback_submit`.

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

@@ -1,4 +1,4 @@
 interface:
   display_name: "Qingflow Record Analysis"
-  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 app_get and record_browse_schema_get, run record_access with field_id-based columns/where/order_by, then analyze the returned CSV shard files with Python. Treat record_list as sample-only and record_analyze as a lightweight non-default helper."
+  short_description: "Analyze Qingflow record data with record_access CSV and Python"
+  default_prompt: "Use $qingflow-record-analysis for grouped distributions, ratios, rankings, trends, and final statistical conclusions in Qingflow apps. Start with app_get and record_browse_schema_get, run record_access with field_id-based columns/where/order_by, then analyze every returned CSV shard with Python. Always run field-quality checks before choosing final grouping dimensions, and downgrade sparse dimensions to filled-sample observations. If record_access is not visible as an MCP tool, discover and use the CLI path qingflow record --help -> qingflow record access --help. Treat record_list as sample-only."

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

@@ -1,150 +1,91 @@
 # Analysis Gotchas
 
-## Do not skip schema
+## Do Not Skip Schema
 
-If the task is analysis-style and you jump straight to `record_list`, `record_export_direct`, or `record_analyze`, you are already off the stable path.
-
-Correct recovery:
+Correct path:
 
 1. `app_get`
 2. `record_browse_schema_get`
-3. inspect the schema and choose fields
-4. run `record_access`
-5. use Python over the returned CSV shards
-
-The schema here is applicant-node visible-only. If a field is absent, treat it as not available to the current user rather than switching to guessed ids or builder-side memory.
-
-## Normalize relative time phrases before building the DSL.
-
-Examples:
-
-- `最近一个完整自然月` -> convert to an explicit full-month date range
-- `上个月` -> convert to a concrete month range
-- `最近30天` -> convert to exact start/end dates
-
-Do not pass vague time phrases or impossible dates into MCP.
-
-## Do not treat paged list output as full data
-
-`record_list` can hit:
-
-- `row_cap=200`
-- `row_cap_hit=true`
-- `sample_only=true`
-
-When this happens, it is sample-only evidence.
-
-It is not acceptable to use that result alone for:
-
-- 平均值
-- 占比
-- 排名
-- 趋势
-- 地域分布
-- “基于全部数据”的 business insight
+3. `record_access`
+4. Python
 
-## Do not mix full analyze totals with sample rows
+`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.
 
-If `record_access` or `record_analyze` gives full-population coverage, but list rows are capped, do not merge them into one final statement.
+## Do Not Use Export For Analysis
 
-Split them into:
+Export tools are for user-requested files. Analysis uses `record_access` because it returns structured completeness and compact field metadata.
 
-- `全量可信结论`
-- `样本观察`
+## Do Not Treat `record_list` As Full Data
 
-## Do not present truncated grouped rows as a full grouped list
+`record_list` is sample/browse only. It can be capped and should not justify:
 
-If `completeness.rows_truncated=true` or `completeness.statement_scope=returned_groups_only`:
+- average
+- share
+- ranking
+- trend
+- regional distribution
+- "all data" insights
 
-- do not say `各部门`
-- do not say `所有分组`
-- do not say `完整名单`
+## Do Not Control Paging
 
-Correct recovery:
+`record_access` owns paging internally.
 
-- do not describe the answer as complete grouped coverage
-- keep the wording inside the returned group scope
+Do not invent:
 
-## Do not guess fields under ambiguity
+- `page`
+- `page_size`
+- `limit`
+- `requested_pages`
+- `scan_max_pages`
+- `max_rows`
+- `timeout`
 
-If the field is uncertain:
+## Do Not Print Raw CSV
 
-- 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
+Read CSV files with pandas. Summarize computed results, not raw rows.
 
-Correct recovery:
+## Do Not Rename Source Files
 
-1. `record_browse_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
+CSV columns are directly readable and field-id anchored: `record_id`, `<字段标题>__field_<id>`. Use those columns directly in pandas.
 
-If the intended field is absent from the schema altogether, stop and explain that it is not visible in the current applicant-node permission scope.
+## Do Not Trust Sparse Dimensions
 
-Examples of the right recovery question:
+Before final grouping, run a field-quality profile. If the selected field is mostly blank, say so and downgrade the claim.
 
-- “我找到两个可能的字段：`线索来源`、`来源渠道`。你要按哪个字段统计？”
-- “目前最像‘来源’的字段有这三个：`来源`、`来源渠道`、`获客来源`。请确认你要按哪个字段分析。”
+Rules of thumb:
 
-## Do not try to control paging manually
+- Overall blank rate above 40%: not a primary conclusion dimension.
+- Any compared period blank rate above 80%: do not use that field for period comparison.
+- A sparse field can support only `已填写样本观察`.
 
-`record_access` hides paging and follows the backend's native paging capability. `record_analyze` hides paging and scan budget on purpose.
+If the user asks for a semantic field such as `板块`, test nearby candidates like product, platform, module, stage, source, owner, or department before concluding.
 
-- Do not invent `page_size`
-- Do not invent `requested_pages`
-- Do not invent `scan_max_pages`
-- Do not rename CSV columns before analysis; use `metadata_files.schema` / `metadata_files.readme` to interpret `field_<id>` columns.
-- Do not invent `auto_expand_pages`
-- Do not invent `max_rows`
+## Do Not Hide Incomplete Access
 
-When the result is incomplete:
+If `needs_scope`, no CSV exists. Ask for a time/business scope.
 
-1. narrow the scope with views or filters
-2. reduce the analysis problem into smaller field_id-based access requests
-3. keep the answer at `初步观察` or `部分结果` if completeness is still not enough
+If `partial`, use only subset wording and avoid full-population claims.
 
-## Do not guess metric semantics from loose business wording
+If field meaning is ambiguous, ask the user to confirm from a short list.
 
-Before building the DSL, first decide whether the question needs:
+## Do Not Guess Metrics
 
-- `count`
-- `sum`
-- `avg`
-- `distinct_count`
-- a ratio with numerator + denominator
-- a sorted ranking result
+Before fetching data, decide whether the request needs count, sum, average, distinct count, ratio, ranking, trend, or comparison.
 
-Do not jump straight from words like `数量`, `人数`, `单量`, or `金额` to one assumed metric.
+## Do Not Call A Ratio Without Denominator
 
-## Do not hide partial completion
+For penetration, conversion, or share:
 
-If the user asked for several outputs and only part of them is stable:
-
-- say which parts are complete
-- say which parts are still unresolved
-- do not present the answer as fully finished
-
-If `record_access.status=needs_scope`, stop and ask for a time/business range; no CSV was written. If `record_access.status=partial`, read the returned CSV only as a partial subset and name the limitation before any numbers.
-
-## Do not send unsupported formula or div-style metrics into `record_analyze`.
-
-Examples to avoid:
-
-- `{"op":"div", ...}`
-- metric items with `formula`, `expr`, `numerator`, or `denominator`
-
-Correct recovery:
-
-1. query the source metrics with separate DSLs
-2. confirm both sides are complete and compatible
-3. compute the derived ratio outside MCP in the reasoning layer
+1. define numerator
+2. define denominator
+3. query compatible source data
+4. compute in Python
+5. report numerator and denominator
 
-## Do not call something a ratio without the denominator
+## Normalize Relative Dates
 
-If the user asks for penetration / conversion / 占比:
+Convert relative phrases into exact ranges before `record_access`.
 
-1. define numerator
-2. define denominator
-3. query both sides explicitly
-4. only then compute and report the ratio
+- `今年5月` -> exact May 1 to May 31 in the current year
+- `去年同期` -> same date range in previous year
+- `最近30天` -> exact rolling start/end dates