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

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

@@ -0,0 +1,173 @@
+---
+name: qingflow-record-crud
+description: Browse, read, create, update, and delete Qingflow records after the MCP is already connected and authenticated. Use when the user wants schema-first record CRUD with SQL-like JSON DSL. Do not use this skill for task-center workflow actions or final statistical analysis.
+metadata:
+  short-description: Schema-first Qingflow record CRUD
+---
+
+# Qingflow Record CRUD
+
+## Overview
+
+This skill is for **record CRUD only** inside existing Qingflow apps.
+
+Use it for:
+
+- record browsing
+- record detail lookup
+- record create / update / delete
+- attachment preflight before a write
+- relation/member/department lookup that directly supports a write
+
+Do **not** use this skill for:
+
+- grouped analysis, ratios, rankings, trends, or final statistical conclusions  
+  Switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
+- task-center workflow actions, comments, or directory-driven operational workflows  
+  Switch to [$qingflow-task-ops](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-task-ops/SKILL.md)
+
+This skill assumes the MCP is already connected, authenticated, and bound to the correct workspace.  
+If not, switch to [$qingflow-mcp-setup](/Users/yanqidong/.codex/skills/qingflow-mcp-setup/SKILL.md) first.
+
+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
+
+Use exactly one of these default paths:
+
+1. Browse records  
+   `record_schema_get -> record_list`
+
+2. Read one record  
+   `record_schema_get -> record_get`
+
+3. Write records  
+   `record_schema_get -> record_write`
+
+4. Analysis  
+   Switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
+
+## Core Tools
+
+- `record_schema_get`
+- `record_list`
+- `record_get`
+- `record_write`
+
+## Supporting Tools
+
+- `directory_search`
+- `directory_list_internal_users`
+- `directory_list_internal_departments`
+- `directory_list_sub_departments`
+- `file_get_upload_info`
+- `file_upload_local`
+
+## Standard Operating Order
+
+1. Ensure auth exists
+2. Ensure workspace is selected
+3. Confirm target app and whether the task is browse / detail / write / analysis
+4. Run `record_schema_get` before any non-trivial record read or write
+5. If the request is analysis-like, switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
+6. If the request is write-like, decide `insert / update / delete` before building any payload
+7. If fields are still ambiguous after `record_schema_get`, ask the user to confirm from a short candidate list instead of guessing
+8. For high-risk writes or production changes, read the current state first whenever practical
+9. After actions, report the affected `record_id`, counts, or returned item count
+
+## Record Read Rules
+
+- Use `record_list` for browse/export/sample inspection only
+- Use `record_get` when `record_id` is known
+- `record_list` accepts:
+  - `columns`
+  - `where`
+  - `order_by`
+  - `limit`
+  - `page`
+- `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)
+
+## Record Write Rules
+
+Use `record_write` as the only default write tool.
+
+### Write workflow
+
+1. Run `record_schema_get`
+2. Decide whether the task is `insert`, `update`, or `delete`
+3. Build SQL-like JSON clauses
+4. Run `record_write`
+5. If `ok=false`, explain `field_errors` first, then summarize blockers; do not report a write as executed
+6. If `ok=true`, report the affected `record_id` or created resource
+7. For important writes, keep `verify_write=true`
+
+### SQL-like JSON DSL
+
+The DSL is clause-shaped like SQL, but it is **not raw SQL text**.
+
+#### Insert
+
+```json
+{
+  "operation": "insert",
+  "values": [
+    { "field_id": 12, "value": "测试客户" },
+    { "field_id": 18, "value": 1000 }
+  ],
+  "submit_type": "submit",
+  "verify_write": true
+}
+```
+
+#### Update
+
+```json
+{
+  "operation": "update",
+  "record_id": 123,
+  "set": [
+    { "field_id": 18, "value": 2000 }
+  ],
+  "verify_write": true
+}
+```
+
+#### Delete
+
+```json
+{
+  "operation": "delete",
+  "record_ids": [123, 124]
+}
+```
+
+### Write discipline
+
+- `insert` uses `values`
+- `update` uses `set`
+- `delete` uses `record_id` or `record_ids`
+- Do not send raw SQL text
+- Do not invent formulas or expressions
+- 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
+
+## Response Interpretation
+
+- `record_list` returns browse/sample data, not final analysis conclusions
+- `record_write` always performs internal static preflight before any apply
+- If `record_write` returns `ok=false`, the write was blocked and not executed
+- Prefer explaining `field_errors` before summarizing top-level blockers
+- If `record_write` returns `ok=true`, still check `verification` and `warnings` before claiming success
+- Treat `request_route` as the source of truth for live route debugging
+- Prefer canonical schema titles and aliases in your final wording
+- If only part of the requested work is completed, explicitly disclose which parts are done and which are not
+
+## Resources
+
+- 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/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Qingflow Record CRUD"
+  short_description: "Browse, read, and write Qingflow records with schema-first DSLs"
+  default_prompt: "Use $qingflow-record-crud for Qingflow record browsing, detail lookup, and record_write operations. Start with record_schema_get, choose record_list, record_get, or record_write, and keep analysis work in $qingflow-record-analysis."
+

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

@@ -0,0 +1,43 @@
+# Data Gotchas
+
+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-record-crud`.
+
+## Record Reads
+
+- `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
+
+## Write Preflight
+
+- `record_write` always performs internal static preflight before any apply
+- If `record_write` returns `ok=false`, the write was blocked and not executed
+- Explain `field_errors` before summarizing blockers
+- Use `record_schema_get` when field titles are uncertain instead of guessing ids
+- 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
+
+## Write Semantics
+
+- `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
+
+- Attachment fields are two-step: upload first, then write the returned URL object into the record
+- `file_upload_local` may report `effective_upload_kind=login` even when the requested kind was `attachment`; this is an implementation fallback, not necessarily an error
+- When debugging uploads, surface both `effective_upload_kind` and `upload_protocol`
+
+## Subtables
+
+- 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 row ids if the source record returns them
+- Nested subtable writes are still unsupported
+

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

@@ -0,0 +1,58 @@
+# Environment Switching
+
+Use this reference before any data creation, update, or delete.
+
+## Step 1: Resolve the active environment
+
+Decide explicitly whether the task targets:
+
+- `test`: demo, mock data, smoke usage validation, training scenarios
+- `prod`: real operational data and live record changes
+
+If the user did not specify an environment, default to `prod`.
+
+## Test Environment
+
+Use test for:
+
+- mock or smoke data entry
+- user acceptance demos
+- data correction rehearsals
+
+Test behavior:
+
+- creating demo data is acceptable
+- default to at least `5` records for mock or smoke datasets unless the user asks for fewer
+- destructive cleanup is acceptable only when the record scope is explicit
+
+## Production Environment
+
+Use production for:
+
+- live data entry
+- live business record updates
+- controlled data correction or deletion
+
+Production behavior:
+
+- prefer browse or detail reads before any write
+- restate the exact app and record scope before update or delete
+- do not create mock, smoke, or demo data unless the user explicitly asks for it
+- for bulk changes, summarize the target count before execution and the affected ids after execution
+- destructive actions need explicit confirmation in the conversation context
+
+Production guardrails:
+
+- never assume a record id, app id, or workspace id
+- treat `record_write(operation="delete")` as high risk
+- if the task can be answered read-only, do not write
+
+## Reporting Rule
+
+For record CRUD operations, always report:
+
+- active environment
+- target app
+- operation type: read, create, update, or delete
+- affected record count or ids
+

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

@@ -0,0 +1,109 @@
+# Record Patterns
+
+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).
+
+## Browse Pattern
+
+Use `record_schema_get -> record_list` when:
+
+- 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
+
+Keep the browse DSL simple:
+
+- `columns`: field ids only
+- `where`: flat AND filters only
+- `order_by`: field sorting only
+- `limit` and `page`: browsing intent only
+
+Do not use `record_list` for grouped conclusions, ratios, rankings, trends, or any final statistical claim.
+
+## Detail Pattern
+
+Use `record_schema_get -> record_get` when:
+
+- 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. 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`
+
+### Insert
+
+```json
+{
+  "operation": "insert",
+  "values": [
+    { "field_id": 12, "value": "测试客户" },
+    { "field_id": 18, "value": 1000 }
+  ],
+  "submit_type": "submit",
+  "verify_write": true
+}
+```
+
+### Update
+
+```json
+{
+  "operation": "update",
+  "record_id": 123,
+  "set": [
+    { "field_id": 18, "value": 2000 }
+  ],
+  "verify_write": true
+}
+```
+
+### Delete
+
+```json
+{
+  "operation": "delete",
+  "record_ids": [123, 124]
+}
+```
+
+## Write Anti-Patterns
+
+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 writes for these field types:
+
+- `14` time range
+- `34` image recognition
+- `35` image generation
+- `36` document parsing
+
+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, Attachment, and Subtable Rules
+
+- 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-task-ops/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: qingflow-task-ops
+description: Use Qingflow task center, workflow usage actions, comments, and directory lookup after the MCP is already connected and authenticated. Do not use this skill for record CRUD or final statistical analysis.
+metadata:
+  short-description: Qingflow task center and workflow operations
+---
+
+# Qingflow Task Ops
+
+## Overview
+
+This skill is for **task-center and workflow usage operations** inside existing Qingflow apps.
+
+Use it for:
+
+- task-center browsing
+- headline task counts
+- grouped worksheet or workflow-node workload views
+- approve / reject / rollback / transfer / urge
+- record comments
+- directory lookup that supports task or comment actions
+
+Do **not** use this skill for:
+
+- record create / update / delete  
+  Switch to [$qingflow-record-crud](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-crud/SKILL.md)
+- grouped analysis, ratios, rankings, trends, or final statistical conclusions  
+  Switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
+
+This skill assumes the MCP is already connected, authenticated, and bound to the correct workspace.  
+If not, switch to [$qingflow-mcp-setup](/Users/yanqidong/.codex/skills/qingflow-mcp-setup/SKILL.md) first.
+
+Before operating on live work, 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
+
+Use exactly one of these default paths:
+
+1. Task headline counts  
+   `task_summary`
+
+2. Flat task browsing  
+   `task_list`
+
+3. Grouped workload buckets  
+   `task_facets`
+
+4. Task or workflow action  
+   `task_list / task_facets -> exact target -> task_* action`
+
+5. Comments and directory support  
+   `record_get -> record_comment_*` or `directory_*`
+
+## Core Tools
+
+- `task_summary`
+- `task_list`
+- `task_facets`
+- `task_mark_read`
+- `task_mark_all_cc_read`
+- `task_urge`
+- `task_approve`
+- `task_reject`
+- `task_rollback_candidates`
+- `task_rollback`
+- `task_transfer_candidates`
+- `task_transfer`
+- `record_comment_write`
+- `record_comment_list`
+- `record_comment_mentions`
+- `record_comment_mark_read`
+
+## Supporting Tools
+
+- `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`
+- `record_get`
+
+## Standard Operating Order
+
+1. Ensure auth exists
+2. Ensure workspace is selected
+3. Confirm target app and whether the task is task browse / grouped workload / comment / workflow action
+4. Use `task_summary`, `task_list`, or `task_facets` to locate the exact target first
+5. If a workflow action is required, identify the exact `task_id`, `record_id`, and `workflow_node_id` whenever practical
+6. Use directory tools only when member/department lookup is needed to support the action
+7. For production actions, read current task or record state first whenever practical
+8. After actions, report the affected `task_id`, `record_id`, or returned item count
+
+## Task-Center Rules
+
+- Use `task_summary` for headline counts
+- Use `task_list` for flat browsing
+- Use `task_facets` for grouped worksheet or workflow-node buckets
+- `task_box` must be one of:
+  - `todo`
+  - `initiated`
+  - `cc`
+  - `done`
+- `flow_status` must be one of:
+  - `all`
+  - `in_progress`
+  - `approved`
+  - `rejected`
+  - `pending_fix`
+  - `urged`
+  - `overdue`
+  - `due_soon`
+  - `unread`
+  - `ended`
+- Task counts are task-center counts, not record counts
+- If the user asks for workload by worksheet or node, use `task_facets`
+- If a result set is truncated, describe it as `已返回分组中` or `主要分组`
+
+## Workflow Usage Actions
+
+- Find the exact target first
+- For approve or reject, identify the exact `workflow_node_id` first; prefer task-center results or current audit info
+- Avoid workflow actions on ambiguous tasks or records
+- For rollback or transfer, fetch candidates first
+- Summarize the final action and target task ids or record ids
+
+## Comments and Directory
+
+- Use `record_comment_write` only after the exact `record_id` is known
+- Use `record_comment_mentions` to resolve mention candidates before building complex comment payloads
+- Use `directory_search` for fuzzy member/department lookup
+- Use `directory_list_all_internal_users` and `directory_list_all_departments` only when the user explicitly wants a complete export
+
+## Response Interpretation
+
+- `task_summary` gives headline counts only
+- `task_list` returns flat task rows, not grouped workload conclusions
+- `task_facets` is the only default grouped workload path
+- Treat `request_route` as the source of truth for live route debugging
+- If only part of the requested work is completed, explicitly disclose which parts are done and which are not
+
+## Resources
+
+- Environment switching: [references/environments.md](references/environments.md)
+- Workflow and task usage actions: [references/workflow-usage.md](references/workflow-usage.md)
+

package/skills/qingflow-task-ops/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Qingflow Task Ops"
+  short_description: "Use Qingflow task center, comments, directory, and workflow actions"
+  default_prompt: "Use $qingflow-task-ops for Qingflow task-center browsing, workload facets, comments, directory lookup, and workflow usage actions. Locate the exact target first, then run the smallest explicit task or comment action."

package/skills/qingflow-task-ops/references/environments.md

@@ -0,0 +1,44 @@
+# Environment Switching
+
+Use this reference before any workflow usage action, comment, or task-center operation that might affect live work.
+
+## Step 1: Resolve the active environment
+
+Decide explicitly whether the task targets:
+
+- `test`: demo, mock data, smoke usage validation, training scenarios
+- `prod`: real operational tasks, comments, and workflow actions
+
+If the user did not specify an environment, default to `prod`.
+
+## Test Environment
+
+Use test for:
+
+- workflow walkthroughs
+- user acceptance demos
+- comment or transfer rehearsals
+
+## Production Environment
+
+Use production for:
+
+- live task-center operations
+- live comments on real business records
+- approve / reject / rollback / transfer / urge on real work
+
+Production guardrails:
+
+- never assume a task id, record id, or workflow node id
+- find the exact target first
+- if the task can be answered read-only, do not act
+
+## Reporting Rule
+
+For task ops, always report:
+
+- active environment
+- target app or task box
+- operation type: read, comment, approve, reject, rollback, transfer, urge, or mark_read
+- affected task ids or record ids
+

package/skills/qingflow-task-ops/references/workflow-usage.md

@@ -0,0 +1,27 @@
+# Workflow and Task Usage Actions
+
+Use these when the user is operating inside an existing process, not redesigning it.
+
+Examples:
+
+- add a comment to a record
+- approve or reject a workflow task
+- transfer a task
+- 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_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_get` 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/src/qingflow_mcp/__init__.py

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

package/src/qingflow_mcp/server.py

@@ -29,8 +29,9 @@ def build_server() -> FastMCP:
             "Use auth_login first, then workspace_list and workspace_select. "
             "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. For operational record reads, use record_schema_get first, then record_list or record_get. "
-            "For writes, use record_schema_get and then record_write with mode=plan or apply.\n\n"
+            "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. "
+            "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"
             "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,7 +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. "
-            "For analytics, switch to record_schema_get and record_analyze. "
+            "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."
         ),