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

package/README.md

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

package/package.json

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

package/pyproject.toml

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

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

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

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

@@ -11,6 +11,8 @@ Correct recovery:
 3. build one or more small DSLs
 4. run `record_analyze`
 
+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:
@@ -77,6 +79,8 @@ Correct recovery:
 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
 
+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.
+
 Examples of the right recovery question:
 
 - “我找到两个可能的字段：`线索来源`、`来源渠道`。你要按哪个字段统计？”

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

@@ -30,6 +30,8 @@ Result reading order:
 5. `completeness`
 6. `presentation`
 
+Treat `record_schema_get` as applicant-node visible-only schema. Missing fields are permission boundaries, not invitations to guess hidden ids.
+
 ## Distribution / ratio pattern
 
 1. Run `record_schema_get`

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

@@ -55,6 +55,12 @@ Use exactly one of these default paths:
 - `record_get`
 - `record_write`
 
+`record_schema_get` now returns the **current user's applicant-node schema only**:
+
+- only fields visible to the current user at the applicant node are returned
+- hidden fields are omitted entirely
+- missing fields should be treated as `当前用户在申请人节点下不可见/不可用`, not as a reason to guess a different field
+
 ## Supporting Tools
 
 - `directory_search`
@@ -80,12 +86,14 @@ Use exactly one of these default paths:
 
 - Use `record_list` for browse/export/sample inspection only
 - Use `record_get` when `record_id` is known
+- `record_get` without explicit `columns` still returns only applicant-node visible fields; do not assume it exposes the full builder-side record
 - `record_list` accepts:
   - `columns`
   - `where`
   - `order_by`
   - `limit`
   - `page`
+- `record_list` and `record_get` may reject hidden-field `field_id`s because record tools now validate against the applicant-node visible schema only
 - `record_list` is **not** an analysis tool
 - If a request turns into grouped distributions, ratios, rankings, trends, or final statistical conclusions, switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
 
@@ -153,6 +161,7 @@ The DSL is clause-shaped like SQL, but it is **not raw SQL text**.
 - Do not use free-form `WHERE` updates or deletes
 - Do not auto-fill missing fields
 - Do not auto-resolve relation targets without first querying them
+- Do not assume `record_schema_get` is a builder/full-field schema. It is the current user's applicant-node visible schema only.
 
 ## Response Interpretation
 
@@ -170,4 +179,3 @@ The DSL is clause-shaped like SQL, but it is **not raw SQL text**.
 - Environment switching: [references/environments.md](references/environments.md)
 - Record operation patterns: [references/record-patterns.md](references/record-patterns.md)
 - Data gotchas: [references/data-gotchas.md](references/data-gotchas.md)
-

package/skills/qingflow-record-crud/references/data-gotchas.md

@@ -6,6 +6,8 @@ For final statistics, grouped distributions, rankings, trends, or insight-style
 
 - `record_list` is for browsing, export, and sample inspection only
 - `record_get` is for one exact record
+- `record_schema_get` is applicant-node visible-only schema, not a builder/full-field schema
+- if a field is absent from `record_schema_get`, treat it as not visible or not usable for the current user at the applicant node
 - Do not present paged browse output as if it were a grouped or full-population conclusion
 - If the browser and MCP disagree, compare `request_route.base_url` and `request_route.qf_version` first
 
@@ -40,4 +42,3 @@ For final statistics, grouped distributions, rankings, trends, or insight-style
 - Use the current form schema's subfield titles; do not guess nested ids
 - When updating existing subtable rows, preserve row ids if the source record returns them
 - Nested subtable writes are still unsupported
-

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

@@ -11,6 +11,8 @@ Use `record_schema_get -> record_list` when:
 - a delete or update target still needs confirmation
 - the user needs sample rows or a small export
 
+Remember that `record_schema_get` only exposes the current user's applicant-node visible fields. If a field is missing from that schema, treat it as unavailable in the current permission scope instead of trying to guess another `field_id`.
+
 Keep the browse DSL simple:
 
 - `columns`: field ids only
@@ -29,6 +31,7 @@ Use `record_schema_get -> record_get` when:
 - a write target needs verification before action
 
 Prefer passing explicit `columns` when the user only needs a subset of fields.
+Without `columns`, `record_get` still returns only applicant-node visible fields, not the full builder-side record payload.
 
 ## Write Pattern
 
@@ -88,6 +91,7 @@ Do not do this:
 - do not invent formulas or expressions
 - do not auto-fill missing required fields
 - do not guess relation targets without first resolving them
+- do not guess hidden or missing fields from prior builder knowledge; if the field is absent from applicant-node schema, stop and explain the permission boundary
 - do not claim a blocked `record_write` was executed
 
 ## Unsupported Direct Writes
@@ -106,4 +110,3 @@ If the payload includes them, stop after the blocked `record_write` response and
 - Relation fields are record-id based. Resolve the referenced target first, then write the relation field with the real `record_id`.
 - Attachment fields are two-step: upload first with `file_upload_local`, then reuse the returned attachment payload in `record_write`.
 - Subtable writes require the current schema shape; when updating existing subtable rows, preserve row ids if the current record exposes them.
-

package/src/qingflow_mcp/__init__.py

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

package/src/qingflow_mcp/server.py

@@ -30,8 +30,9 @@ def build_server() -> FastMCP:
             "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. record_analyze returns compact business-first output as query/result/ranking/ratios/completeness/presentation; use verbose only for route/debug details. "
+            "record_schema_get returns the current user's applicant-node visible schema only; hidden fields are omitted and missing fields should be treated as not visible in the current permission scope. "
             "For operational record reads, use record_schema_get first, then record_list or record_get. "
-            "For writes, use record_schema_get and then call record_write once; it performs internal preflight before any apply.\n\n"
+            "For writes, use record_schema_get and then call record_write once; it performs internal preflight before any apply and refuses fields outside the applicant-node writable schema.\n\n"
             "Task Center (待办/已办) handling:\n"
             "- Use task_summary to get headline counts.\n"
             "- Use task_list for flat task browsing with task_box and flow_status.\n"

package/src/qingflow_mcp/server_app_user.py

@@ -20,6 +20,7 @@ def build_user_server() -> FastMCP:
         instructions=(
             "Use this server for Qingflow operational workflows with a schema-first path. "
             "For records, start with record_schema_get, then choose record_list, record_get, or record_write. "
+            "record_schema_get returns the current user's applicant-node visible schema only; hidden fields are omitted and missing fields should be treated as not visible in the current permission scope. "
             "For analytics, switch to record_schema_get and record_analyze; its default output is compact query/result/ranking/ratios/completeness/presentation, with route/debug only in verbose mode. "
             "For task center, use task_summary, task_list, and task_facets before any explicit task action. "
             "Avoid builder-side app or schema changes here."

package/src/qingflow_mcp/tools/record_tools.py

@@ -38,6 +38,7 @@ ATTACHMENT_QUE_TYPES = {13}
 RELATION_QUE_TYPES = {25}
 SUBTABLE_QUE_TYPES = {18}
 VERIFY_UNSUPPORTED_WRITE_QUE_TYPES = {14, 34, 35, 36}
+LAYOUT_ONLY_QUE_TYPES = {24}
 DEPARTMENT_MEMBER_JUDGE_PREFIX = "deptId_"
 JUDGE_EQUAL = 0
 JUDGE_UNEQUAL = 1
@@ -90,6 +91,14 @@ class ViewSelection:
     conditions: list[list[ViewFilterCondition]]
 
 
+@dataclass(slots=True)
+class WorkflowNodeRef:
+    workflow_node_id: int
+    name: str
+    type: str
+    raw: JSONObject
+
+
 @dataclass(slots=True)
 class RecordInputError(Exception):
     message: str
@@ -134,7 +143,8 @@ FIELD_LOOKUP_STRIP_RE = re.compile(r"[\s_()（）\[\]【】{}<>·/\\:：-]+")
 class RecordTools(ToolBase):
     def __init__(self, sessions, backend) -> None:  # type: ignore[no-untyped-def]
         super().__init__(sessions, backend)
-        self._form_cache: dict[tuple[str, str], JSONObject] = {}
+        self._form_cache: dict[tuple[str, str, str, int], JSONObject] = {}
+        self._applicant_node_cache: dict[tuple[str, str], WorkflowNodeRef] = {}
         self._view_list_cache: dict[tuple[str, str], list[JSONObject]] = {}
         self._view_config_cache: dict[tuple[str, str], JSONObject] = {}
 
@@ -286,9 +296,10 @@ class RecordTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
 
         def runner(session_profile, context):
+            applicant_node = self._resolve_applicant_node(profile, context, app_key, force_refresh=False)
             index = self._get_field_index(profile, context, app_key, force_refresh=False)
             view_selection = self._resolve_view_selection(profile, context, app_key, view_key=view_key, view_name=view_name)
-            fields = [self._schema_field_payload(field) for field in index.by_id.values()]
+            fields = [self._schema_field_payload(field, workflow_node_id=applicant_node.workflow_node_id) for field in index.by_id.values()]
             suggested_dimensions = [
                 {"field_id": item["field_id"], "title": item["title"]}
                 for item in fields
@@ -312,6 +323,12 @@ class RecordTools(ToolBase):
                 "request_route": self._request_route_payload(context),
                 "data": {
                     "app_key": app_key,
+                    "schema_scope": "applicant_node",
+                    "workflow_node": {
+                        "workflow_node_id": applicant_node.workflow_node_id,
+                        "name": applicant_node.name,
+                        "type": applicant_node.type,
+                    },
                     "view_resolution": _view_selection_payload(view_selection),
                     "fields": fields,
                     "suggested_dimensions": suggested_dimensions,
@@ -531,31 +548,39 @@ class RecordTools(ToolBase):
                 }
             return response
 
-        raw = self.record_get(
-            profile=profile,
-            app_key=app_key,
-            apply_id=record_id,
-            role=1,
-            list_type=None,
-            audit_node_id=workflow_node_id,
-        )
-        return {
-            "profile": profile,
-            "ws_id": raw.get("ws_id"),
-            "ok": bool(raw.get("ok", True)),
-            "request_route": raw.get("request_route"),
-            "warnings": [],
-            "output_profile": normalized_output_profile,
-            "data": {
-                "app_key": app_key,
-                "record_id": record_id,
-                "record": raw.get("result"),
-                "selection": {
-                    "columns": columns,
-                    "workflow_node_id": workflow_node_id,
+        def runner(session_profile, context):
+            index = self._get_field_index(profile, context, app_key, force_refresh=False)
+            selected_fields = list(index.by_id.values())
+            result = self.backend.request(
+                "GET",
+                context,
+                f"/app/{app_key}/apply/{record_id}",
+                params={"role": 1},
+            )
+            answer_list = result.get("answers") if isinstance(result, dict) and isinstance(result.get("answers"), list) else []
+            row = _build_flat_row(cast(list[JSONValue], answer_list), selected_fields, apply_id=record_id)
+            response: JSONObject = {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "ok": True,
+                "request_route": self._request_route_payload(context),
+                "warnings": [],
+                "output_profile": normalized_output_profile,
+                "data": {
+                    "app_key": app_key,
+                    "record_id": record_id,
+                    "record": row,
+                    "selection": {
+                        "columns": columns,
+                        "workflow_node_id": workflow_node_id,
+                    },
                 },
-            },
-        }
+            }
+            if normalized_output_profile == "verbose":
+                response["data"]["debug"] = {"raw_record": result}
+            return response
+
+        return self._run_record_tool(profile, runner)
 
     def record_write(
         self,
@@ -712,7 +737,7 @@ class RecordTools(ToolBase):
             preflight=None,
         )
 
-    def _schema_field_payload(self, field: FormField) -> JSONObject:
+    def _schema_field_payload(self, field: FormField, *, workflow_node_id: int) -> JSONObject:
         write_hints = self._schema_write_hints(field)
         return {
             "field_id": field.que_id,
@@ -725,6 +750,8 @@ class RecordTools(ToolBase):
             "role_hints": self._schema_role_hints(field),
             "readable": True,
             "writable": write_hints["writable"],
+            "permission_scope": "applicant_node",
+            "workflow_node_id": workflow_node_id,
             "write_kind": write_hints["write_kind"],
             "supported_read_ops": write_hints["supported_read_ops"],
             "supported_write_ops": write_hints["supported_write_ops"],
@@ -1105,10 +1132,12 @@ class RecordTools(ToolBase):
             self._ensure_allowed_analyze_keys(
                 item,
                 location=f"metrics[{idx}]",
-                allowed_keys={"op", "field_id", "fieldId", "alias"},
+                allowed_keys={"op", "type", "agg", "aggregation", "field_id", "fieldId", "alias"},
                 example="{'op': 'sum', 'field_id': 7, 'alias': '总金额'}",
             )
-            op = _normalize_optional_text(item.get("op"))
+            op = _normalize_optional_text(
+                item.get("op") or item.get("type") or item.get("agg") or item.get("aggregation")
+            )
             if op not in supported_ops:
                 raise RecordInputError(
                     message=f"metrics[{idx}] uses unsupported op '{op}'",
@@ -1127,12 +1156,8 @@ class RecordTools(ToolBase):
                         details={"location": f"metrics[{idx}]", "field": _field_ref_payload(field), "op": op},
                     )
             elif item.get("field_id", item.get("fieldId")) is not None:
-                raise RecordInputError(
-                    message=f"metrics[{idx}] with op 'count' must not include field_id",
-                    error_code="INVALID_ANALYZE_METRIC",
-                    fix_hint="Remove field_id from count metrics.",
-                    details={"location": f"metrics[{idx}]", "op": op},
-                )
+                # LLM 经常给 count 传 field_id，静默忽略而非报错
+                pass
             alias = _normalize_optional_text(item.get("alias"))
             if alias is None:
                 if op == "count":
@@ -2390,10 +2415,16 @@ class RecordTools(ToolBase):
         return self._run_record_tool(profile, runner)
 
     def _get_form_schema(self, profile: str, context, app_key: str, *, force_refresh: bool) -> JSONObject:  # type: ignore[no-untyped-def]
-        cache_key = (profile, app_key)
+        applicant_node = self._resolve_applicant_node(profile, context, app_key, force_refresh=force_refresh)
+        cache_key = (profile, app_key, "applicant_node", applicant_node.workflow_node_id)
         if not force_refresh and cache_key in self._form_cache:
             return self._form_cache[cache_key]
-        schema = self.backend.request("GET", context, f"/app/{app_key}/form", params={"type": 1})
+        schema = self.backend.request(
+            "GET",
+            context,
+            f"/app/{app_key}/form",
+            params={"type": 1, "beingApply": True, "auditNodeId": applicant_node.workflow_node_id},
+        )
         normalized = _normalize_form_schema(schema)
         self._form_cache[cache_key] = normalized
         return normalized
@@ -2401,6 +2432,26 @@ class RecordTools(ToolBase):
     def _get_field_index(self, profile: str, context, app_key: str, *, force_refresh: bool) -> FieldIndex:  # type: ignore[no-untyped-def]
         return _build_field_index(self._get_form_schema(profile, context, app_key, force_refresh=force_refresh))
 
+    def _resolve_applicant_node(self, profile: str, context, app_key: str, *, force_refresh: bool) -> WorkflowNodeRef:  # type: ignore[no-untyped-def]
+        cache_key = (profile, app_key)
+        if not force_refresh and cache_key in self._applicant_node_cache:
+            return self._applicant_node_cache[cache_key]
+        payload = self.backend.request("GET", context, f"/app/{app_key}/auditNodes")
+        applicant_node = _extract_applicant_node(payload)
+        if applicant_node is None:
+            raise_tool_error(
+                QingflowApiError(
+                    category="config",
+                    message=f"cannot resolve applicant node for app {app_key}",
+                    details={
+                        "error_code": "APPLICANT_NODE_NOT_FOUND",
+                        "fix_hint": "Ensure the app has a workflow applicant node before using user-side record tools.",
+                    },
+                )
+            )
+        self._applicant_node_cache[cache_key] = applicant_node
+        return applicant_node
+
     def _get_view_list(self, profile: str, context, app_key: str) -> list[JSONObject]:  # type: ignore[no-untyped-def]
         cache_key = (profile, app_key)
         if cache_key in self._view_list_cache:
@@ -3883,6 +3934,30 @@ def _normalize_view_list(payload: JSONValue) -> list[JSONObject]:
     return flattened
 
 
+def _normalize_audit_nodes(payload: JSONValue) -> list[JSONObject]:
+    if isinstance(payload, list):
+        return [item for item in payload if isinstance(item, dict)]
+    if isinstance(payload, dict):
+        return [item for item in payload.values() if isinstance(item, dict)]
+    return []
+
+
+def _extract_applicant_node(payload: JSONValue) -> WorkflowNodeRef | None:
+    for item in _normalize_audit_nodes(payload):
+        node_type = _coerce_count(item.get("type"))
+        deal_type = _coerce_count(item.get("dealType"))
+        workflow_node_id = _coerce_count(item.get("auditNodeId"))
+        if workflow_node_id is None or node_type != 0 or deal_type != 3:
+            continue
+        return WorkflowNodeRef(
+            workflow_node_id=workflow_node_id,
+            name=_normalize_optional_text(item.get("auditNodeName")) or str(workflow_node_id),
+            type="applicant",
+            raw=item,
+        )
+    return None
+
+
 def _compile_view_conditions(config: JSONObject) -> list[list[ViewFilterCondition]]:
     raw_limit = config.get("viewgraphLimit")
     if not isinstance(raw_limit, list):
@@ -3919,16 +3994,19 @@ def _build_field_index(schema: JSONObject) -> FieldIndex:
         *[(question, False) for question in _flatten_questions(schema.get("formQues"))],
     ]
     for question, is_base_question in all_questions:
+        if not _should_index_question(question):
+            continue
         que_id = _coerce_count(question.get("queId"))
         title = _stringify_json(question.get("queTitle")).strip()
         if que_id is None or que_id < 0 or not title:
             continue
+        can_edit = question.get("canEdit")
         field = FormField(
             que_id=que_id,
             que_title=title,
             que_type=_coerce_count(question.get("queType")),
             required=bool(question.get("required") or question.get("beingRequired")),
-            readonly=bool(question.get("readonly") or question.get("beingReadonly") or is_base_question),
+            readonly=bool(question.get("readonly") or question.get("beingReadonly") or is_base_question or can_edit is False),
             system=bool(question.get("system") or question.get("beingSystem") or is_base_question),
             options=_extract_question_options(question),
             aliases=[],
@@ -3947,16 +4025,35 @@ def _build_field_index(schema: JSONObject) -> FieldIndex:
 def _flatten_questions(payload: JSONValue) -> list[JSONObject]:
     flattened: list[JSONObject] = []
     if isinstance(payload, dict):
-        if "queId" in payload or "queTitle" in payload:
+        is_question = "queId" in payload or "queTitle" in payload
+        if is_question:
             flattened.append(payload)
-        for value in payload.values():
-            flattened.extend(_flatten_questions(value))
+        for key in ("subQuestions", "innerQuestions", "subQues"):
+            value = payload.get(key)
+            if isinstance(value, list):
+                flattened.extend(_flatten_questions(value))
+        if not is_question:
+            for key in ("baseQues", "formQues"):
+                value = payload.get(key)
+                if isinstance(value, list):
+                    flattened.extend(_flatten_questions(value))
     elif isinstance(payload, list):
         for item in payload:
             flattened.extend(_flatten_questions(item))
     return flattened
 
 
+def _should_index_question(question: JSONObject) -> bool:
+    if bool(question.get("beingHide") or question.get("hidden")):
+        return False
+    if _coerce_count(question.get("quoteId")) is not None:
+        return False
+    que_type = _coerce_count(question.get("queType"))
+    if que_type in LAYOUT_ONLY_QUE_TYPES:
+        return False
+    return True
+
+
 def _extract_question_options(question: JSONObject) -> list[str]:
     options = question.get("options")
     if not isinstance(options, list):