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

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.20
+npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.22
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.20 qingflow-app-user-mcp
+npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.22 qingflow-app-user-mcp
 ```
 
 Environment:
@@ -23,6 +23,8 @@ This package bootstraps a local Python runtime on first install and then starts
 Bundled skills:
 
 - `skills/qingflow-app-user`
+- `skills/qingflow-record-crud`
+- `skills/qingflow-task-ops`
 - `skills/qingflow-record-analysis`
 
 Note:

package/package.json

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

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

@@ -1,160 +1,63 @@
 ---
 name: qingflow-app-user
-description: Use Qingflow apps as an operational end user after the MCP is already connected and authenticated. Use when the user wants to create, search, read, update, or delete business records, inspect or manage task-center work, add comments, or perform workflow usage actions inside an existing app. Do not use this skill to design apps, modify schemas, or build a brand new SolutionSpec.
+description: Route Qingflow end-user requests to the right specialized operational skill after the MCP is already connected and authenticated. Use when the task is operational but it is not yet clear whether it is record CRUD, task-center workflow work, or final analysis.
 metadata:
-  short-description: Use Qingflow apps for business data and task operations
+  short-description: Router for Qingflow operational skills
 ---
 
 # Qingflow App User
 
 ## Overview
 
-This skill is for business-user operations inside existing Qingflow apps. It focuses on records, task-center usage, comments, and usage-side workflow actions, not app design or system configuration. If the task is about building or changing app structure, switch to `$qingflow-app-builder`.
-
-If the user is asking for analysis, grouped distributions, ranking, trend, averages, business insights, or any final statistical conclusion, switch to `$qingflow-record-analysis` instead of keeping that logic inside this skill.
-
-Before operating on data, identify whether the task targets `test` or `prod` and read [references/environments.md](references/environments.md). If the user did not specify one, default to `prod`.
-When the task is in `prod`, browser parity matters, or the user says "the page has data but MCP does not", restate the expected `base_url` and `qf_version`, then prefer tools that expose `request_route` so you can confirm the live route before concluding.
-
-## Tool Scope
-
-Primary record and data tools:
-
-- `record_query`
-- `record_schema_get`
-- `record_write_plan`
-- `record_create`
-- `record_get`
-- `record_update`
-- `record_delete`
-
-Directory and organization lookup tools when the user is asking about internal members, departments, org structure, ownership, approver candidates, or wants full contact exports:
-
-- `directory_search`
-- `directory_list_internal_users`
-- `directory_list_all_internal_users`
-- `directory_list_internal_departments`
-- `directory_list_all_departments`
-- `directory_list_sub_departments`
-- `directory_list_external_members`
-
-Usage-side collaboration and flow tools when needed:
-
-- `record_comment_*`
-- `task_approve`
-- `task_reject`
-- `task_rollback*`
-- `task_transfer*`
-
-Task-center and inbox tools when the user is asking about pending work, processed work, cc, or workflow workload:
-
-- `task_list`
-- `task_list_grouped`
-- `task_statistics`
-- `task_urge`
-
-Do not use builder-side tools here:
-
-- `app_*`
-- `view_*`
-- `workflow_*`
-- `portal_*`
-- `navigation_*`
-- `package_*`
-- `solution_*`
-
-## Standard Operating Order
-
-1. Ensure auth exists
-2. Ensure workspace is selected
-3. Confirm target app, task scope, and operation type
-4. For org, member, department, approver, or ownership questions, start with `directory_*`
-5. For inbox, pending, processed, cc, or workload questions, start with `task_statistics`, `task_list`, or `task_list_grouped`
-6. When a task query identifies the target record, switch to `record_get` or `record_query` for business data details
-7. For non-trivial record reads, start with `record_query`
-8. For non-trivial writes, start with `record_write_plan`, especially when using `fields`
-9. Prefer read-first when changing existing records
-10. Report the affected task ids, record ids, member ids, department ids, or counts after actions
-11. For `prod`, complex forms, attachments, or any unfamiliar schema, prefer `record_create(..., verify_write=true)` or read back immediately after create/update
-
-## Data Rules
-
-- Prefer `record_query` as the default read entry
-- Treat `record_query(list)` as the default wide-table browse and export endpoint; pass explicit `select_columns`, do not expect raw answer arrays there, and let the tool auto-batch columns when the backend per-request field cap is hit
-- For analysis, grouped distributions, trends, or final statistical conclusions, switch to `$qingflow-record-analysis`
-- Use `request_route` from tool responses to verify the active `base_url` and `qf_version` whenever route mismatches are plausible
-- Use `directory_search` for fuzzy internal lookup across both members and departments
-- Use `directory_list_all_internal_users` when the user explicitly wants a complete internal member list within the current workspace or within a specific department or role
-- Use `directory_list_all_departments` when the user explicitly wants the full department tree or all departments under a root
-- Use `directory_list_internal_departments` for keyword-based department search, not full exports
-- Use `task_statistics` before `task_list` when the user only needs counts
-- Use `task_list_grouped` when worksheet or group buckets matter
-- Use `task_urge` only when the user clearly wants a reminder sent for a pending task
-- Use `record_schema_get` when field selectors are ambiguous; if the task then turns into analysis, switch to `$qingflow-record-analysis`
-- For precise record lookup, use `record_get` when `apply_id` is known
-- Use `record_schema_get` when the user gives field titles and you are not fully sure about the exact schema; do not guess ambiguous fields silently
-- If the task has already shifted into analysis and `record_schema_get` still leaves multiple plausible fields, stop and ask the user to confirm the intended field instead of continuing to try read tools in a loop
-- Treat field selectors as schema-first and platform-generic. Prefer exact field titles, then neutral aliases such as `创建时间`, `新增时间`, `负责人`, `部门`, `时间`, or `阶段` only when the tool resolves them clearly. Do not assume CRM shorthand like `销售`, `商机阶段`, `客户全称`, or similar domain shortcuts apply across arbitrary Qingflow apps
-- For updates, inspect current data first unless the user already provided the exact target and patch
-- For deletes, confirm the exact record scope and report the deleted ids
-- When validating business data volume, use `effective_count` over raw backend totals
-- In `prod`, prefer read-first even more strictly and avoid deletes unless the record scope is explicit in the conversation
-- For attachments, first run `file_upload_local`, then pass the returned `attachment_value` into `record_create` or `record_update`; do not try to write local file paths directly into attachment fields
-- For relation fields, first query the target app and resolve the referenced record `apply_id`; do not assume titles, numbers, or business keys can be written directly into a relation field
-- For subtable fields, write a list of row objects keyed by the subfield titles. When updating existing rows, include `rowId` / `row_id` / `__row_id__` only if the source record already exposes it
-- Treat `14/34/35/36` as unsupported direct-write field types in app-user flows:
-  - `14`: time range
-  - `34`: image recognition
-  - `35`: image generation
-  - `36`: document parsing
-- For those unsupported types, stop and explain the limitation instead of inventing payloads
-- Use `record_write_plan` to inspect `write_format.support_level` before non-trivial writes:
-  - `full`: generic scalar/select/date writes are directly supported
-  - `restricted`: member/department/attachment/relation/subtable writes need the documented presteps
-  - `unsupported`: stop and explain the limitation
-- For relation-heavy, attachment, subtable, or production writes, default to `verify_write=true` so field drops are surfaced immediately instead of being reported as success
-
-## Mock and Demo Data
-
-When the user asks for demo data, seed, smoke data, or mock data:
-
-- default to at least `5` records for the relevant entity unless the user asks for fewer
-- keep titles realistic and business-like
-- vary statuses, dates, and categories enough to make views and charts useful
-- if the task is `prod`, do not create mock or smoke data unless the user explicitly asks for it
-
-## Response Interpretation
-
-- `record_query(query_mode="list")` is browse/sample output, not a final analysis result
-- If `record_query(query_mode="list")` reports `row_cap_hit`, `sample_only`, or capped rows, do not present it as full data
-- For grouped distributions, trends, or final statistical conclusions, switch to `$qingflow-record-analysis` and use `record_schema_get -> record_analyze`
-- `record_write_plan` is static preflight, not a guarantee that submit will pass runtime linkage or visibility checks
-- `record_create` now returns integer `apply_id`; you can pass that id directly into `record_get`, `record_update`, or `record_delete`
-- `verify_write=true` means the tool read the record back and compared the written fields; if it returns `status=verification_failed` or `ok=false`, do not report the create or update as successful
-- Relation writes are `apply_id`-based; if the user only gives a title, number, or business key, query the target app first and resolve the real record id before writing
-- Task counts and record counts are not interchangeable; a task query reflects task-center workload, not the underlying record total
-- When reporting task results, include the task dimension that was used, such as pending, processed, cc, node, or worksheet
-- Prefer summarizing titles and counts instead of dumping raw answer arrays
-- When records reference other entities, verify references are coherent before reporting success
-- `file_upload_local` may transparently change `effective_upload_kind` and `upload_protocol`; surface those fields when debugging production upload behavior instead of assuming all uploads are direct `PUT`
-
-## Practical Patterns
-
-- Bulk mock data creation: query current data first, run `record_write_plan`, then create missing records
-- Data correction: query, inspect, preflight, update, and re-read
-- Inbox triage: use `task_statistics` first, then `task_list` or `task_list_grouped`, then switch to `record_*` for the underlying record when needed
-- Bottleneck analysis: start with `task_statistics` and `task_list_grouped` before drilling into specific records
-- Workflow collaboration: comment, transfer, or reassign only after identifying the exact record
-- Approval actions: identify the exact record and current node first, then use `task_approve` or `task_reject`; do not guess `nodeId`
-- Demo validation: create at least `5` rows and confirm they are queryable
-- Org export: use `directory_list_all_internal_users` for full member exports and `directory_list_all_departments` for full org-tree exports before mapping owners or departments into record operations
-- Attachment write: upload first, write the returned URL object second, and prefer `verify_write=true`
-- Relation write: query the target app first, capture the referenced record `apply_id`, then write the relation field and verify the readback
-- Production discrepancy triage: compare the response `request_route` with the browser environment before assuming the data query is wrong
+This skill is a **router skill** for operational usage inside existing Qingflow apps.
+
+Use it when the request is operational, but you first need to decide which specialized skill should own it.
+
+This skill does **not** try to teach every detailed workflow itself.  
+It routes to:
+
+- [$qingflow-record-crud](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-crud/SKILL.md) for record browsing, detail lookup, create, update, and delete
+- [$qingflow-task-ops](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-task-ops/SKILL.md) for task-center usage, comments, approvals, rollback, transfer, urge, and directory lookup
+- [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md) for grouped analysis, ratios, rankings, trends, and final statistical conclusions
+
+Before operating on data, identify whether the task targets `test` or `prod` and read [references/environments.md](references/environments.md).  
+If the user did not specify one, default to `prod`.
+
+## Default Paths
+
+Route to exactly one of these specialized paths:
+
+1. Record CRUD  
+   Switch to [$qingflow-record-crud](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-crud/SKILL.md)
+
+2. Task center / comments / workflow usage / directory  
+   Switch to [$qingflow-task-ops](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-task-ops/SKILL.md)
+
+3. Analysis  
+   Switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
+
+4. MCP connection / auth / workspace selection  
+   Switch to [$qingflow-mcp-setup](/Users/yanqidong/.codex/skills/qingflow-mcp-setup/SKILL.md)
+
+## Routing Rules
+
+- If the task is about browsing, reading, creating, updating, deleting, attachments, relations, or subtable writes, switch to `$qingflow-record-crud`
+- If the task is about inbox, todo, cc, task-center workload, comments, approval, reject, rollback, transfer, urge, or directory lookup, switch to `$qingflow-task-ops`
+- If the task is about grouped distributions, ratios, rankings, trends, insights, or any final statistical conclusion, switch to `$qingflow-record-analysis`
+- If the MCP is not connected, authenticated, or bound to the right workspace, switch to `$qingflow-mcp-setup`
+
+## Shared Preconditions
+
+- confirm environment first
+- ensure auth exists
+- ensure workspace is selected
+- prefer canonical app ids, record ids, task ids, and workflow node ids over guessed names
+- if a field or target is still ambiguous after schema/task lookup, ask the user to confirm from a short candidate list instead of guessing
+- if the task can stay read-only, do not write or act
+
 ## Resources
 
 - Environment switching: [references/environments.md](references/environments.md)
-- Record operation patterns: [references/record-patterns.md](references/record-patterns.md)
-- Workflow usage actions: [references/workflow-usage.md](references/workflow-usage.md)
-- Data gotchas: [references/data-gotchas.md](references/data-gotchas.md)
-- Dedicated analysis workflow: [qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
+- Record CRUD: [$qingflow-record-crud](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-crud/SKILL.md)
+- Task center and workflow usage: [$qingflow-task-ops](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-task-ops/SKILL.md)
+- Dedicated analysis workflow: [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)

package/skills/qingflow-app-user/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Qingflow App User"
-  short_description: "Use Qingflow apps for business data and task operations"
-  default_prompt: "Use $qingflow-app-user for ordinary Qingflow record, task, comment, and directory operations. If the task shifts into grouped analysis, insight generation, ranking, trend, or final statistical conclusions, switch to $qingflow-record-analysis instead of keeping the logic here."
+  short_description: "Route Qingflow operational tasks to CRUD, task ops, or analysis"
+  default_prompt: "Use $qingflow-app-user as a router: switch to $qingflow-record-crud for record browse/read/write, switch to $qingflow-task-ops for task-center, comments, directory, and workflow usage actions, and switch to $qingflow-record-analysis for grouped analysis or final statistical conclusions."

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

@@ -1,40 +1,31 @@
 # Data Gotchas
 
-For final statistics, grouped distributions, or insight-style analysis, use [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md) instead of keeping that reasoning inside `$qingflow-app-user`.
-
-## Counts
-
-- Prefer `effective_count`
-- For final analysis, inspect `record_analyze.data.completeness` and `safe_for_final_conclusion` before concluding
-- If `record_analyze.status!=success`, treat the result as exploratory unless the user explicitly asked for a partial sample
-- `record_query(list)` is for browsing and sample inspection. If it reports `row_cap_hit`, `sample_only`, or capped `returned_items`, do not present it as full data
-- When coverage matters, surface:
-  - `scanned_count`
-  - `presentation.statement_scope`
-- Use narrower views, filters, or smaller analysis questions instead of inventing manual scan settings by hand
-- If the browser and MCP disagree, compare `request_route.base_url` and `request_route.qf_version` first
-- Do not mix a full aggregate total with sample-only list detail in one sentence like “基于全部数据分析”； split the answer into `全量结论` and `样本观察`
+For final statistics, grouped distributions, rankings, trends, or insight-style conclusions, use [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md) instead of keeping that reasoning inside `$qingflow-app-user`.
 
-## Record titles
+## Record Reads
 
-- Do not dump raw answer arrays to the user unless needed
-- Prefer concise business titles and counts
+- `record_list` is for browsing, export, and sample inspection only
+- `record_get` is for one exact record
+- 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
 
-## Preflight
+## Write Preflight
 
-- `record_write_plan` is static preflight only; linked visibility and runtime required rules can still reject writes
-- `record_write_plan` now exposes `write_format.support_level`; check `full / restricted / unsupported` before attempting non-trivial writes
+- `record_write` always performs internal static preflight before any apply
+- If `record_write` returns `ok=false`, the write was blocked and not executed
 - Use `record_schema_get` when field titles are uncertain instead of guessing ids
-- For analysis tasks, use the fixed path `record_schema_get -> record_analyze`; do not switch tools blindly after `FIELD_NOT_FOUND` or ambiguity
-- Prefer `strict_full=true` for final statistics or business conclusions
-- `record_create` and `record_update` can do post-write verification with `verify_write=true`; use that for complex, subtable, or production writes
-- `apply_id` is normalized to an integer; pass it directly into later record tools
+- Prefer `verify_write=true` for complex, relation-heavy, subtable, or production writes
+- Even when `record_write` returns `ok=true`, it may still surface verification failures; do not report success before checking them
 
-## Mock data
+## Write Semantics
 
-- Default to at least `5` rows per relevant entity unless the user asked for fewer
-- Avoid identical titles and identical statuses across all rows
-- Keep relation references valid
+- `insert` uses `values`
+- `update` uses `set`
+- `delete` uses `record_id` or `record_ids`
+- Do not send raw SQL strings
+- Do not fake formula or expression fields
+- Do not perform free-form bulk updates or deletes
+- Do not guess relation targets from display text; resolve the real `record_id` first
 
 ## Attachments
 
@@ -46,10 +37,10 @@ For final statistics, grouped distributions, or insight-style analysis, use [$qi
 
 - Subtable fields accept row objects keyed by subfield title, or native `tableValues`
 - Use the current form schema's subfield titles; do not guess nested ids
-- When updating existing subtable rows, preserve `rowId` if the source record returns it
+- When updating existing subtable rows, preserve row ids if the source record returns them
 - Nested subtable writes are still unsupported
 
-## Unsupported direct-write fields
+## Unsupported Direct-Write Fields
 
 - `14` time range
 - `34` image recognition

package/skills/qingflow-app-user/references/environments.md

@@ -50,7 +50,7 @@ Production behavior:
 Production guardrails:
 
 - never assume a record id, app id, or workspace id
-- treat `record_delete` as high risk
+- treat `record_write(operation="delete")` as high risk
 - if the task can be answered read-only, do not write
 
 ## Reporting Rule

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

@@ -1,81 +1,96 @@
 # Record Patterns
 
-If the task shifts into grouped analysis, ratio, ranking, trend, or final statistical conclusions, switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md).
+If the task shifts into grouped analysis, ratio, ranking, trend, or any final statistical conclusion, switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md).
 
-## Query first
+## Browse Pattern
 
-Use `record_query` first when:
+Use `record_schema_get -> record_list` when:
 
-- the user only gives a title or business key
-- the target record id is unknown
-- updates or deletes need confirmation
-- ordinary list browsing or spot checks are needed
+- the user wants to browse records
+- the target `record_id` is unknown
+- a delete or update target still needs confirmation
+- the user needs sample rows or a small export
 
-Use [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md) when:
+Keep the browse DSL simple:
 
-- field titles may be ambiguous
-- filters are still in natural-language shape
-- the result may be used as a final conclusion
-- scan scope or completeness is unclear
-- the user asks for a distribution, ratio, ranking, top-N, or any grouped aggregate
-- the user asks for `分析 / 洞察 / 分布 / 占比 / 平均 / 排名 / 趋势 / 所有 / 全部 / 全国 / 高价值`
+- `columns`: field ids only
+- `where`: flat AND filters only
+- `order_by`: field sorting only
+- `limit` and `page`: browsing intent only
 
-## Final analysis pattern
+Do not use `record_list` for grouped conclusions, ratios, rankings, trends, or any final statistical claim.
 
-1. Run `record_schema_get`
-2. Generate one or more field_id-based DSLs
-3. Run `record_analyze(strict_full=true)` for summary/distribution/trend/cross analysis
-4. Run `record_query(query_mode="list")` only if you still need sample rows or examples
-5. Report `scanned_count`, `presentation.statement_scope`, and whether the result is safe for a final conclusion
-6. If `status=error` or `safe_for_final_conclusion=false`, stop at “partial result” instead of presenting a final business conclusion
-7. If list rows are sample-only, separate the answer into:
-   - `全量可信结论`
-   - `样本观察（不作为最终结论）`
-   - optional `待验证假设`
+## Detail Pattern
 
-## Analysis anti-pattern
+Use `record_schema_get -> record_get` when:
 
-Do not do this:
+- the exact `record_id` is known
+- the user needs one record in detail
+- a write target needs verification before action
+
+Prefer passing explicit `columns` when the user only needs a subset of fields.
+
+## Write Pattern
+
+Use `record_schema_get -> record_write`.
 
-1. Run only `record_query(query_mode="list")`
-2. Get `200` rows back
-3. Report平均值、占比、地域分布 as if they were based on all records
+1. Confirm the target app
+2. Resolve fields with `record_schema_get`
+3. Decide whether the task is `insert`, `update`, or `delete`
+4. Build SQL-like JSON clauses
+5. Run `record_write`
+6. If `ok=false`, explain `field_errors` first, then summarize blockers; stop because the write was not executed
+7. If `ok=true`, report the affected resource and any verification outcome
+8. For important writes, keep `verify_write=true`
 
-This is not acceptable because the list endpoint can be capped. Use `record_schema_get -> record_analyze` first, then treat list rows as sample-only evidence.
+### Insert
 
-## Create pattern
+```json
+{
+  "operation": "insert",
+  "values": [
+    { "field_id": 12, "value": "测试客户" },
+    { "field_id": 18, "value": 1000 }
+  ],
+  "submit_type": "submit",
+  "verify_write": true
+}
+```
 
-1. Confirm target app
-2. Resolve fields with `record_schema_get` if needed. Prefer exact schema titles first; only rely on platform-neutral aliases such as `创建时间`, `负责人`, or `部门` when they resolve cleanly, and do not assume business-domain shorthand like `销售` is portable across apps
-3. Run `record_write_plan` for non-trivial payloads or any `fields`-based write
-4. For relation fields, query the target app first and resolve the referenced record `apply_id`
-5. For attachments, call `file_upload_local` first and reuse the returned `attachment_value`
-6. For subtable fields, pass a list of row objects keyed by subfield title. When updating existing rows, include `rowId` / `row_id` / `__row_id__` only if the current record already exposes it
-7. Inspect `record_write_plan.data.support_matrix` or each field's `write_format.support_level` before submit:
-   - `full`: direct write is supported
-   - `restricted`: follow the documented presteps first
-   - `unsupported`: stop and explain the limitation
-8. For complex forms, production writes, attachments, relation-heavy payloads, or subtables, create with `verify_write=true`
-9. If verification fails, treat the write as not yet successful and inspect the missing or empty fields before reporting back
-10. Re-query or fetch the record when validation matters
+### Update
 
-## Update pattern
+```json
+{
+  "operation": "update",
+  "record_id": 123,
+  "set": [
+    { "field_id": 18, "value": 2000 }
+  ],
+  "verify_write": true
+}
+```
 
-1. Query the target records
-2. Resolve exact `apply_id`
-3. Run `record_write_plan`
-4. Update only the intended fields
-5. Prefer `verify_write=true` for attachment, relation, subtable, or production updates
-6. Re-read the record if the change is important, attachment-related, subtable-related, or the form has linkage
+### Delete
 
-## Delete pattern
+```json
+{
+  "operation": "delete",
+  "record_ids": [123, 124]
+}
+```
 
-1. Query or fetch the exact record first
-2. Confirm the target ids
-3. Delete
-4. Report affected ids and remaining count when relevant
+## Write Anti-Patterns
 
-## Unsupported direct writes
+Do not do this:
+
+- do not send raw SQL text
+- do not build free-form `WHERE` updates or deletes
+- do not invent formulas or expressions
+- do not auto-fill missing required fields
+- do not guess relation targets without first resolving them
+- do not claim a blocked `record_write` was executed
+
+## Unsupported Direct Writes
 
 Do not attempt direct app-user writes for these field types:
 
@@ -84,13 +99,10 @@ Do not attempt direct app-user writes for these field types:
 - `35` image generation
 - `36` document parsing
 
-If the payload includes them, stop at `record_write_plan` and explain that the tool does not build a reliable native payload for those fields yet.
-
-## Relation fields
+If the payload includes them, stop after the blocked `record_write` response and explain that the tool does not support a reliable direct write for those fields yet.
 
-Relation fields are record-id based.
+## Relation, Attachment, and Subtable Rules
 
-- Query the referenced app first
-- Resolve the target record `apply_id`
-- Write the relation field with that id
-- Do not write relation fields with display titles, business keys, or guessed identifiers unless they have already been resolved to the real record id
+- 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/skills/qingflow-app-user/references/workflow-usage.md

@@ -7,18 +7,20 @@ Examples:
 - add a comment to a record
 - approve or reject a workflow task
 - transfer a task
-- roll back a record
-- list pending, processed, or cc tasks
+- roll back a task
+- list todo, initiated, done, or cc tasks
+- inspect workload by worksheet or workflow node
 - urge a pending task
 
 Rules:
 
 - if the user starts from inbox, todo, workload, cc, or bottleneck language, use `task_*` first
-- use `task_statistics` for counts and `task_list` or `task_list_grouped` for browsing
-- use `task_list_grouped` when grouped workload browsing matters
+- use `task_summary` for headline counts
+- use `task_list` for flat browsing
+- use `task_facets` when worksheet or workflow-node buckets matter
 - treat task counts as task-center counts, not record counts
-- switch to `record_*` after locating the exact business record behind a task
-- identify the exact record first
-- for approve or reject, identify the exact `nodeId` first; prefer task-center results or audit info, then use `task_approve` or `task_reject`
-- avoid usage-side flow actions on ambiguous records
+- switch to `record_*` only after locating the exact business record behind a task
+- identify the exact target first
+- for approve or reject, identify the exact `workflow_node_id` first; prefer task-center results or current audit info, then use `task_approve` or `task_reject`
+- avoid usage-side workflow actions on ambiguous records
 - summarize the final action and target task ids or record ids

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

@@ -11,9 +11,9 @@ metadata:
 
 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, deleting, or approving records rather than analyzing them, switch back to `$qingflow-app-user`.
+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 and compare `request_route` with the browser route if browser parity matters.
+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
 
@@ -22,7 +22,7 @@ Use these tools as the core analysis surface:
 - `record_schema_get`
 - `record_analyze`
 
-Use `record_query(query_mode="list")` or `record_get` only when you need sample rows or a specific supporting example after the main analysis path.
+Use `record_list` or `record_get` only when you need sample rows or a specific supporting example after the main analysis path.
 
 ## Hard Rules
 
@@ -34,8 +34,8 @@ Use `record_query(query_mode="list")` or `record_get` only when you need sample
 - 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
-- If `record_query(list)` reports `row_cap_hit`, `sample_only`, capped `returned_items`, or compact output, treat it as sample-only evidence
+- `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`
@@ -57,7 +57,7 @@ For analysis:
 3. Inspect fields, aliases, suggested dimensions, suggested metrics, and suggested time fields
 4. Generate one or more field_id-based DSLs
 5. Run `record_analyze` once per DSL
-6. Run `record_query(query_mode="list")` only if you still need sample rows, examples, or manual inspection
+6. Run `record_list` only if you still need sample rows, examples, or manual inspection
 7. Before answering, separate:
    - `全量可信结论`
    - `样本观察`
@@ -78,7 +78,7 @@ For analysis:
 - 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 `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
@@ -236,10 +236,17 @@ Two-dimensional cross analysis:
 
 ## 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 `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 `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:
   - `全量可信结论`
   - `样本观察（不作为最终结论）`