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

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

@@ -1,151 +1,112 @@
 # Analysis Patterns
 
-## When to use this skill
-
-Use this skill when the user asks for:
-
-- 分布
-- 占比
-- 平均值
-- 排名 / top-N
-- 趋势
-- 洞察
-- 最终统计结论
-- 全量范围内的 business summary
-
-## Canonical analysis sequence
+## Canonical Sequence
 
 1. `app_get`
 2. `record_browse_schema_get`
-3. decide whether the question needs `count`, `sum`, `avg`, `distinct_count`, `ratio`, or `ranking`
-4. choose field_id-based `columns`, `where`, and `order_by`
+3. decide metric intent
+4. choose `record_access.columns / where / order_by`
 5. `record_access`
 6. Python over every returned CSV shard
-7. `record_list` only for sample inspection
+7. optional `record_list` or `record_get` only for sample/detail verification
 
-Result reading order:
+Metric intent must be one of:
 
-1. `record_access.status`
-2. `record_access.complete`
-3. `record_access.safe_for_final_conclusion`
-4. `record_access.files[].local_path`
-5. `record_access.metadata_files.schema`
-6. Python outputs
-7. `record_access.fields`
-8. `record_access.warnings`
-9. `record_access.scope`
+- `count`
+- `sum`
+- `avg`
+- `distinct_count`
+- ratio with numerator and denominator
+- sorted ranking
+- time trend
+- period comparison
 
-If `record_access.status=needs_scope`, no CSV was written; ask for a time/business range or retry with a user-provided period from `scope.suggested_time_fields`. If `status=partial`, use the CSV files only as a limited subset and do not make a full-population conclusion.
+## Distribution
 
-Treat `record_browse_schema_get` as the browse-schema source of truth. It matches the selected Qingflow table view header and is the same schema source used by `record_access.fields` and `schema.json`. Missing fields are permission boundaries, not invitations to guess hidden ids.
+1. Fetch grouping field and filter fields.
+2. Run the field-quality profile for the grouping field.
+3. If the field passes quality gates, group by the readable field-id anchored column such as `项目状态__field_343283094`.
+4. Count rows and calculate share from the sum of counts.
+5. Report top groups plus total row count.
 
-## Lightweight `record_analyze` helper sequence
+If the grouping field is ambiguous, ask the user to choose from a short candidate list.
 
-1. `app_get`
-2. `record_browse_schema_get`
-3. decide whether the question needs `count`, `sum`, `avg`, `distinct_count`, `ratio`, or `ranking`
-4. build one or more field_id-based DSLs
-5. `record_analyze`
-6. `record_list` only for sample inspection
-
-Result reading order:
-
-1. `result.rows`
-2. `result.totals.metric_totals`
-3. `ranking`
-4. `ratios`
-5. `completeness`
-6. `presentation`
-
-Use this only when a compact grouped result is enough; it is not the default path.
-
-## Distribution / ratio pattern
-
-1. Run `record_browse_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_access`
-6. Use Python to group the CSV rows
-6. Report:
-   - `result.totals.metric_totals`
-   - `safe_for_final_conclusion`
-   - `completeness.statement_scope`
-   - `completeness.warnings`
-7. If grouped rows are truncated, describe the answer as `主要分组` or `已返回分组中`, not `各部门` or `全部`
-
-## penetration / conversion / share-of-total pattern
-
-1. Run `record_browse_schema_get`
-2. Write down the business definition in plain language:
-   - numerator
-   - denominator
-   - grouping dimension, if any
-3. Build separate `record_access` requests when numerator and denominator are not the same filtered population
-4. Query the numerator first
-5. Query the denominator second
-6. Only compute the ratio in Python after both source results are complete and use compatible scopes
-7. If the denominator is missing, do not call the output `渗透率`, `转化率`, `占比`, or `%`
-
-## Average / ranking pattern
-
-1. Run `record_browse_schema_get`
-2. Choose one dimension field and one numeric metric field
-3. Fetch the dimension and numeric metric fields with `record_access`
-4. Use Python for grouped `count/sum/avg/min/max`
-5. If the answer uses ranking language, make the ranking come from structured sorted results
-6. Prefer the structured `ranking` block when it exists instead of inferring order from loose text
-7. Use list mode only to inspect examples after the aggregate result is understood
-
-## Trend pattern
-
-1. Run `record_browse_schema_get`
-2. Choose a date/time field from `suggested_time_fields`
-3. Fetch the date/time field and needed metric fields with `record_access`
-4. Use Python to bucket by day/week/month/quarter/year
-5. Treat the result as final only if `safe_for_final_conclusion=true`
-6. If the user asked for a relative time phrase such as `最近一个完整自然月`, translate it into an explicit legal date range before building the DSL
-
-## Sample inspection pattern
-
-Only use `record_list` after schema/access when you need:
-
-- example rows
-- spot checks
-- representative samples
-- manual inspection of records behind an aggregate bucket
-
-Never use list mode alone to justify final averages, shares, rankings, or regional distribution claims.
-
-## Statement-to-query discipline
-
-- If you want to say `单量低` or `volume low`, query `count`
-- If you want to say `金额高`, query `sum`
-- If you want to say `客单价高`, query `avg` or trusted `sum + count`
-- If you want to say `增长` or `下降`, query a time bucket
-- If you want to say `渗透率` or `占比`, query both numerator and denominator
-- If you want to say `各部门` / `全部渠道` / `完整名单`, make sure `completeness.statement_scope=full_population` and `completeness.rows_truncated=false`
-- If you want to say `Top N` or `排名`, make sure the result is explicitly sorted and the conclusion follows that returned order
-- If the task is complex, default to `先结构、后解读`
-
-## Ambiguous field recovery
-
-If the user asks for something like “来源分布” or “类型占比” and the exact field is unclear:
-
-1. run `record_browse_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
+## Dimension Selection
+
+When the user asks for a semantic bucket such as `板块`, `模块`, `业务线`, or `来源`, inspect candidate fields and choose the most reliable one:
+
+1. Match schema titles to the user's wording.
+2. Fetch candidate fields together if they are cheap.
+3. Profile `blank_rate`, period coverage, and distinct count.
+4. Prefer the candidate with clear semantics and usable coverage.
+5. If the literal field is sparse, downgrade it to `已填写样本观察` and use the nearest reliable fallback for the main conclusion.
+
+Example: if `缺陷所属模块` is mostly empty but `缺陷所属平台` and `所属产品` are complete, use platform/product for the main conclusion and state that module-level analysis is limited.
+
+Quality gates:
+
+- Overall `blank_rate > 0.4`: not a primary conclusion dimension.
+- Any compared period `blank_rate > 0.8`: not valid for period comparison.
+- High-cardinality description/id fields are not dimensions unless the user explicitly asks for record-level ranking.
+
+## Ratio / Conversion / Penetration
+
+1. Define numerator and denominator in plain language.
+2. Fetch both populations with compatible scope.
+3. Compute ratio in Python.
+4. Report `numerator / denominator = percentage`.
+
+If denominator is missing or scope differs, do not call the result a rate.
 
-Do not keep retrying different guessed field names in a loop.
+## Average / Sum
 
-## Partial completion discipline
+1. Fetch grouping field and numeric metric field.
+2. Convert the metric column with `pd.to_numeric(errors="coerce")`.
+3. Report count, sum, and average together when useful.
+4. State how blanks/non-numeric values were handled if material.
 
-If the user asked for several conclusions and only some of them are fully supported:
+## Ranking
+
+1. Build the metric in Python.
+2. Sort explicitly.
+3. Report Top N with metric values.
+4. Do not infer ranking from unsorted sample rows.
+
+## Trend
+
+1. Choose a date/time field from `suggested_time_fields`.
+2. Convert relative phrases into exact date ranges.
+3. Fetch the date field and metrics.
+4. Bucket in pandas by day/week/month/quarter/year.
+5. Report both absolute values and changes.
+
+## Same-Period Comparison
+
+For `今年5月 vs 去年5月`:
+
+1. Use the same date field for both periods.
+2. Fetch the full combined date range or two separate compatible ranges.
+3. Apply identical business filters.
+4. Compute absolute delta and percentage delta.
+5. State both periods explicitly.
+
+## Sample Inspection
+
+Use `record_list` only after the aggregate result is complete, and only for:
+
+- representative examples
+- checking surprising categories
+- manually inspecting records behind a bucket
+
+Never use `record_list` alone for final averages, shares, rankings, trends, or distributions.
+
+## Ambiguous Field Recovery
+
+If the exact field is unclear:
+
+1. inspect `record_browse_schema_get.fields`
+2. use titles and suggested fields
+3. if one candidate is clearly dominant, proceed
+4. otherwise ask the user to confirm
 
-1. state which parts are complete
-2. state which parts are still unresolved
-3. do not present the answer as fully complete
+Do not retry tools with guessed field names.

package/skills/qingflow-record-analysis/references/business-context.md

@@ -0,0 +1,74 @@
+# Business Context
+
+Use this when analysis depends on organization, aliases, ownership, stage semantics, or user-provided business definitions.
+
+## When To Check Context
+
+Check for business context when the request mentions:
+
+- department / team / group / region
+- owner / assignee / sales rep / partner
+- stage / status / funnel / conversion
+- product line / business line
+- same-period comparison
+- "北斗部门", "SMB", "伙伴", or any named internal scope
+
+## Mapping Rules
+
+Use explicit mappings in this order:
+
+1. the user's message in the current thread
+2. attached or local business context files
+3. schema-visible fields and sample records
+4. short clarification to the user
+
+Do not infer hidden org hierarchy from memory. If the mapping changes the denominator or grouping, state it in the final answer.
+
+Example:
+
+```python
+dept_map = {
+    "烈焰组": "北斗部门",
+    "飓风组": "北斗部门",
+}
+df["部门口径"] = df["field_40"].replace(dept_map)
+```
+
+Final wording:
+
+```text
+部门口径：将「烈焰组」「飓风组」合并计入「北斗部门」。
+```
+
+## Ratio Definitions
+
+Before computing rates, define:
+
+- numerator
+- denominator
+- time range
+- grouping dimension
+- exclusions
+
+If any part is ambiguous, ask. Do not rename a count as a rate.
+
+## Time Scope
+
+Normalize relative dates to exact dates before calling `record_access`.
+
+Examples:
+
+- `今年5月` -> `2026-05-01` to `2026-05-31` when current year is 2026
+- `去年同期` -> same month range in the previous year
+- `最近一个完整自然月` -> previous calendar month, not the last 30 days
+
+## Cross-App Reconciliation
+
+If the analysis needs multiple apps:
+
+1. run the standard sequence per app
+2. keep each dataset's scope and completeness separately
+3. join in Python only on explicit ids or trusted business keys
+4. disclose join keys and unmatched records
+
+If no reliable key exists, report the gap instead of forcing a join.

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

@@ -1,96 +1,69 @@
 # Confidence Reporting
 
-## Required output structure
+## Full Conclusion Gate
 
-When analysis is intended as a final answer, use this order:
-
-1. `全量可信结论`
-2. `样本观察`
-3. `待验证假设`
-
-## Full conclusion gate
-
-Only write `全量可信结论` when:
+Use `全量可信结论` only when:
 
 - `record_browse_schema_get` was used
-- the analysis path used `record_access` and Python, or an explicitly chosen lightweight `record_analyze` helper
-- every key analysis result has `safe_for_final_conclusion=true`
-- `safe_for_final_conclusion=true is necessary but not sufficient`
-- no key result depends on an invalid time phrase, an undefined denominator, or an unsupported derived metric
-- the result is not just a capped list sample
+- data came from `record_access`
+- all returned CSV shards were read in Python
+- `record_access.complete=true`
+- `record_access.truncated=false`
+- `record_access.safe_for_final_conclusion=true`
+- metric definitions are complete
+- denominator exists for every ratio
+- time fields and date ranges are explicit
+- primary grouping dimensions pass field-quality gates
 
-## Sample observation gate
+## Initial Observation Gate
 
-Put evidence into `样本观察` when:
+Use `初步观察` when:
 
-- it came from `record_list`
-- the tool reports `row_cap_hit`
-- the tool reports `sample_only`
-- the result is compact/capped and not complete
 - `record_access.status=needs_scope`
 - `record_access.status=partial`
-- `record_access.complete=false` or `record_access.truncated=true`
-
-## Downgrade rule
-
-If `record_browse_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_analyze`
-- full CSV-derived conclusions from `record_access`
-- sample-only details from `record_list`
-
-into one sentence like “基于全部数据分析...”.
-
-Instead:
-
-- full totals and distributions go into `全量可信结论`
-- illustrative rows go into `样本观察`
-
-## Semantic gate
-
-Even when `safe_for_final_conclusion=true`, do not overstate the answer if:
-
-- the metric definition is incomplete
-- the denominator was not queried
-- the conclusion mentions trend but no time bucket was queried
-- the conclusion mentions单量/volume but no `count` metric was queried
-- the conclusion depends on a derived metric the DSL cannot natively express
-- `completeness.statement_scope=returned_groups_only`
-- `completeness.rows_truncated=true`
-
-## Grouped enumeration gate
+- `record_access.complete=false`
+- `record_access.truncated=true`
+- `record_access.safe_for_final_conclusion=false`
+- evidence came from `record_list`
+- scope or saved view filter is unverified
 
-If grouped rows were truncated:
+## Anti-Mixing Rule
 
-- do not call the grouped output `各部门`, `全部渠道`, `完整名单`, or `所有分组`
-- use `已返回分组中`, `主要分组`, or `前 N 个分组`
-- keep full-population statements only for metrics that still cover the full analyzed population
+Do not combine full CSV-derived totals and sample-only rows in one sentence.
 
-## Partial completion disclosure
+Correct split:
 
-If the user asked for multiple conclusions but only some are complete:
+- full totals/distributions: `全量可信结论`
+- illustrative examples: `样本观察`
 
-- explicitly disclose which parts are complete
-- explicitly disclose which parts are not yet complete
-- do not collapse the answer into one all-clear conclusion
+## Semantic Gate
 
-## Example skeleton
+Even with `safe_for_final_conclusion=true`, downgrade if:
 
-### 全量可信结论
+- metric definition is incomplete
+- denominator was not queried
+- conclusion mentions trend but no time field was used
+- conclusion mentions volume but no count was computed
+- grouping depends on unconfirmed business aliases
+- custom view scope is not verified
+- primary grouping field has high missingness or poor period coverage
 
-- `result.totals.metric_totals=...`
-- `safe_for_final_conclusion=true`
-- 这里写最终业务结论
+## Partial Disclosure
 
-### 样本观察
+If only part of the user request is complete:
 
-- 以下来自样本明细浏览，不作为最终统计结论
-- 这里写代表性样本现象
+- say which parts are complete
+- say which parts are unresolved
+- do not collapse into one all-clear conclusion
 
-### 待验证假设
+## Compact Disclosure Template
 
-- 这里写还需要进一步验证的推测
+```text
+可信度：全量可信 / 初步观察
+数据完整性：complete=..., truncated=..., safe_for_final_conclusion=...
+字段质量：primary dimension blank_rate=..., period coverage=...
+取数字段：...
+时间范围：...
+业务口径：...
+限制：...
+```

package/skills/qingflow-record-analysis/references/data-access-playbook.md

@@ -0,0 +1,106 @@
+# Data Access Playbook
+
+This file is the operational state machine for `record_access`.
+
+## Required Sequence
+
+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 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
+```
+
+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.
+
+```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": []
+}
+```
+
+### 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` + `safe_for_final_conclusion=true` | Full retrieved scope is reliable | Give final conclusion |
+| `needs_scope` | Tool refused large unbounded scan, no CSV | Ask for scope or retry with explicit period/business filter |
+| `partial` | Some CSV files written, but not full data | Give only subset observation |
+| `complete=false` | Not all requested data is available | Do not present full-population conclusion |
+| `truncated=true` | Tool had to stop before full scope | Disclose and narrow scope |
+
+## `needs_scope` Recovery
+
+Use the returned `scope` object:
+
+- `reported_total`: explain why scope is needed
+- `suggested_time_fields`: choose likely date fields
+- `recommended_where_examples`: reuse if they match the user request
+
+If the user already provided a concrete month/quarter/year, retry with that period. If no business boundary is available, ask one short clarification.
+
+## `partial` Recovery
+
+You may read the files, but must label output as partial:
+
+- say which files/rows were analyzed
+- do not use `全部`, `所有`, `整体`, or `全量`
+- suggest narrowing time or business scope before final conclusion
+
+## 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.
+
+For board/gantt views, switch to a table-style view or `system:all` plus explicit filters.