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

package/README.md

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

package/package.json

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

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

@@ -29,6 +29,9 @@ Use `record_query(query_mode="list")` or `record_get` only when you need sample
 - 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_query(list)` is never the basis for a final statistical conclusion
@@ -36,6 +39,14 @@ Use `record_query(query_mode="list")` or `record_get` only when you need sample
 - 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
 
@@ -52,6 +63,26 @@ For analysis:
    - `样本观察`
    - `待验证假设`
 
+## 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 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 `presentation.rows_truncated=true` or `presentation.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:
@@ -125,6 +156,7 @@ Practical rules:
 - 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
 
@@ -206,6 +238,8 @@ Two-dimensional cross analysis:
 
 - 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 `presentation.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:
   - `全量可信结论`
   - `样本观察（不作为最终结论）`

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

@@ -11,6 +11,16 @@ Correct recovery:
 3. build one or more small DSLs
 4. run `record_analyze`
 
+## 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 200-row list output as full data
 
 `record_query(query_mode="list")` can hit:
@@ -39,6 +49,19 @@ Split them into:
 - `全量可信结论`
 - `样本观察`
 
+## Do not present truncated grouped rows as a full grouped list
+
+If `presentation.rows_truncated=true` or `presentation.statement_scope=returned_groups_only`:
+
+- do not say `各部门`
+- do not say `所有分组`
+- do not say `完整名单`
+
+Correct recovery:
+
+- do not describe the answer as complete grouped coverage
+- keep the wording inside the returned group scope
+
 ## Do not guess fields under ambiguity
 
 If the field is uncertain:
@@ -73,3 +96,46 @@ 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
+
+## Do not guess metric semantics from loose business wording
+
+Before building the DSL, first decide whether the question needs:
+
+- `count`
+- `sum`
+- `avg`
+- `distinct_count`
+- a ratio with numerator + denominator
+- a sorted ranking result
+
+Do not jump straight from words like `数量`, `人数`, `单量`, or `金额` to one assumed metric.
+
+## Do not hide partial completion
+
+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
+
+## 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
+
+## Do not call something a ratio without the denominator
+
+If the user asks for penetration / conversion / 占比:
+
+1. define numerator
+2. define denominator
+3. query both sides explicitly
+4. only then compute and report the ratio

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

@@ -16,9 +16,10 @@ Use this skill when the user asks for:
 ## Canonical analysis sequence
 
 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
+2. decide whether the question needs `count`, `sum`, `avg`, `distinct_count`, `ratio`, or `ranking`
+3. build one or more field_id-based DSLs
+4. `record_analyze`
+5. `record_query(query_mode="list")` only for sample inspection
 
 ## Distribution / ratio pattern
 
@@ -34,6 +35,21 @@ Use this skill when the user asks for:
    - `backend_total_count`
    - `scanned_count`
    - `safe_for_final_conclusion`
+   - `presentation.statement_scope`
+7. If grouped rows are truncated, describe the answer as `主要分组` or `已返回分组中`, not `各部门` or `全部`
+
+## penetration / conversion / share-of-total pattern
+
+1. Run `record_schema_get`
+2. Write down the business definition in plain language:
+   - numerator
+   - denominator
+   - grouping dimension, if any
+3. Build separate DSLs 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 outside MCP 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
 
@@ -43,7 +59,8 @@ Use this skill when the user asks for:
    - `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
+5. If the answer uses ranking language, make the ranking come from structured sorted results
+6. Use list mode only to inspect examples after the aggregate result is understood
 
 ## Trend pattern
 
@@ -52,6 +69,7 @@ Use this skill when the user asks for:
 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`
+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
 
@@ -64,6 +82,17 @@ Only use `record_query(query_mode="list")` after schema/analyze when you need:
 
 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 `presentation.statement_scope=full_population` and `presentation.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:
@@ -74,3 +103,11 @@ If the user asks for something like “来源分布” or “类型占比” and
 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.
+
+## Partial completion discipline
+
+If the user asked for several conclusions and only some of them are fully supported:
+
+1. state which parts are complete
+2. state which parts are still unresolved
+3. do not present the answer as fully complete

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

@@ -15,6 +15,8 @@ Only write `全量可信结论` when:
 - `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`
+- `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
 
 ## Sample observation gate
@@ -44,6 +46,34 @@ 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
+- `presentation.statement_scope=returned_groups_only`
+- `presentation.rows_truncated=true`
+
+## Grouped enumeration gate
+
+If grouped rows were truncated:
+
+- do not call the grouped output `各部门`, `全部渠道`, `完整名单`, or `所有分组`
+- use `已返回分组中`, `主要分组`, or `前 N 个分组`
+- keep full-population statements only for metrics that still cover the full analyzed population
+
+## Partial completion disclosure
+
+If the user asked for multiple conclusions but only some are complete:
+
+- explicitly disclose which parts are complete
+- explicitly disclose which parts are not yet complete
+- do not collapse the answer into one all-clear conclusion
+
 ## Example skeleton
 
 ### 全量可信结论

package/src/qingflow_mcp/__init__.py

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