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

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

@@ -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:
    - `全量可信结论`
    - `样本观察`

package/skills/qingflow-record-analysis/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Qingflow Record Analysis"
   short_description: "Analyze Qingflow record data with schema-first DSL execution"
-  default_prompt: "Use $qingflow-record-analysis for grouped distributions, ratios, rankings, trends, and final statistical conclusions in Qingflow apps. Start with record_schema_get, build one or more field_id-based DSLs, then run record_analyze. Treat record_query(query_mode=\"list\") as sample-only when capped, and separate full conclusions from sample observations."
+  default_prompt: "Use $qingflow-record-analysis for grouped distributions, ratios, rankings, trends, and final statistical conclusions in Qingflow apps. Start with record_schema_get, build one or more field_id-based DSLs, then run record_analyze. Treat record_list as sample-only when capped or paged, and separate full conclusions from sample observations."

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

@@ -2,7 +2,7 @@
 
 ## Do not skip schema
 
-If the task is analysis-style and you jump straight to `record_query(query_mode="list")` or `record_analyze`, you are already off the stable path.
+If the task is analysis-style and you jump straight to `record_list` or `record_analyze`, you are already off the stable path.
 
 Correct recovery:
 
@@ -23,7 +23,7 @@ Do not pass vague time phrases or impossible dates into MCP.
 
 ## Do not treat 200-row list output as full data
 
-`record_query(query_mode="list")` can hit:
+`record_list` can hit:
 
 - `row_cap=200`
 - `row_cap_hit=true`

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

@@ -19,7 +19,7 @@ Use this skill when the user asks for:
 2. decide whether the question needs `count`, `sum`, `avg`, `distinct_count`, `ratio`, or `ranking`
 3. build one or more field_id-based DSLs
 4. `record_analyze`
-5. `record_query(query_mode="list")` only for sample inspection
+5. `record_list` only for sample inspection
 
 ## Distribution / ratio pattern
 
@@ -73,7 +73,7 @@ Use this skill when the user asks for:
 
 ## Sample inspection pattern
 
-Only use `record_query(query_mode="list")` after schema/analyze when you need:
+Only use `record_list` after schema/analyze when you need:
 
 - example rows
 - spot checks

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

@@ -23,7 +23,7 @@ Only write `全量可信结论` when:
 
 Put evidence into `样本观察` when:
 
-- it came from `record_query(query_mode="list")`
+- it came from `record_list`
 - the tool reports `row_cap_hit`
 - the tool reports `sample_only`
 - the result is compact/capped and not complete
@@ -37,7 +37,7 @@ If `record_schema_get` was not used for an analysis task, downgrade the overall
 Do not combine:
 
 - full totals from `record_analyze`
-- sample-only details from `record_query(query_mode="list")`
+- sample-only details from `record_list`
 
 into one sentence like “基于全部数据分析...”.
 

package/src/qingflow_mcp/__init__.py

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

package/src/qingflow_mcp/server.py

@@ -29,15 +29,15 @@ 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. Use record_query for list/detail browsing only.\n\n"
+            "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"
             "Task Center (待办/已办) handling:\n"
-            "- Use task_statistics to get counts of pending tasks (todo_count), timeouts, urged, etc.\n"
-            "- Use task_list to query tasks. Type values: 1=todo (待办), 2=initiated (我发起的), 3=cc (抄送), 5=done (已办).\n"
-            "- Use task_list_grouped to get tasks grouped by form/worksheet.\n"
+            "- Use task_summary to get headline counts.\n"
+            "- Use task_list for flat task browsing with task_box and flow_status.\n"
+            "- Use task_facets when worksheet or workflow-node buckets matter.\n"
             "- Use task_mark_read to mark a specific task as read.\n"
             "- Use task_urge to send an urgent reminder for a pending task.\n"
-            "- Process status values: 1=all, 2=processing, 3=passed, 4=refused, 5=need_supply, 6=urged, 7=timeout, 8=pre_timeout, 9=unread.\n"
-            "- After identifying the exact task node and record, use record_approve, record_reject, record_rollback, record_transfer, record_reassign, or record_countersign as needed."
+            "- After identifying the exact task node and record, use task_approve, task_reject, task_rollback, or task_transfer as needed."
         ),
     )
     sessions = SessionStore()

package/src/qingflow_mcp/server_app_user.py

@@ -18,9 +18,11 @@ def build_user_server() -> FastMCP:
     server = FastMCP(
         "Qingflow App User MCP",
         instructions=(
-            "Use this server for Qingflow record queries, schema-first analytics via record_schema_get and record_analyze, "
-            "record writes, task center operations, directory lookups, and approval actions. "
-            "Use record_query for list/detail reads only. Avoid builder-side app or schema changes here."
+            "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 task center, use task_summary, task_list, and task_facets before any explicit task action. "
+            "Avoid builder-side app or schema changes here."
         ),
     )
     sessions = SessionStore()
@@ -137,189 +139,12 @@ def build_user_server() -> FastMCP:
             bucket_type=bucket_type,
             path_id=path_id,
             file_related_url=file_related_url,
-        )
+    )
 
     RecordTools(sessions, backend).register(server)
     DirectoryTools(sessions, backend).register(server)
-
-    @server.tool()
-    def record_comment_add(
-        profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        apply_id: int = 0,
-        payload: dict | None = None,
-    ) -> dict:
-        return approvals.record_comment_add(profile=profile, app_key=app_key, apply_id=apply_id, payload=payload or {})
-
-    @server.tool()
-    def record_comment_list(
-        profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        apply_id: int = 0,
-        page_size: int = 20,
-        list_type: int | None = None,
-        page_num: int | None = 1,
-    ) -> dict:
-        return approvals.record_comment_list(
-            profile=profile,
-            app_key=app_key,
-            apply_id=apply_id,
-            page_size=page_size,
-            list_type=list_type,
-            page_num=page_num,
-        )
-
-    @server.tool()
-    def record_comment_mention_candidates(
-        profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        apply_id: int = 0,
-        page_size: int = 20,
-        page_num: int = 1,
-        list_type: int | None = None,
-        keyword: str | None = None,
-    ) -> dict:
-        return approvals.record_comment_mention_candidates(
-            profile=profile,
-            app_key=app_key,
-            apply_id=apply_id,
-            page_size=page_size,
-            page_num=page_num,
-            list_type=list_type,
-            keyword=keyword,
-        )
-
-    @server.tool()
-    def record_comment_mark_read(profile: str = DEFAULT_PROFILE, app_key: str = "", apply_id: int = 0) -> dict:
-        return approvals.record_comment_mark_read(profile=profile, app_key=app_key, apply_id=apply_id)
-
-    @server.tool()
-    def record_comment_stats(profile: str = DEFAULT_PROFILE, app_key: str = "", apply_id: int = 0) -> dict:
-        return approvals.record_comment_stats(profile=profile, app_key=app_key, apply_id=apply_id)
-
-    @server.tool()
-    def task_list(
-        profile: str = DEFAULT_PROFILE,
-        type: int = 1,
-        process_status: int = 1,
-        app_key: str | None = None,
-        node_id: int | None = None,
-        search_key: str | None = None,
-        page_num: int = 1,
-        page_size: int = 20,
-        create_time_asc: bool | None = None,
-    ) -> dict:
-        return tasks.task_list(
-            profile=profile,
-            type=type,
-            process_status=process_status,
-            app_key=app_key,
-            node_id=node_id,
-            search_key=search_key,
-            page_num=page_num,
-            page_size=page_size,
-            create_time_asc=create_time_asc,
-        )
-
-    @server.tool()
-    def task_list_grouped(
-        profile: str = DEFAULT_PROFILE,
-        type: int = 1,
-        process_status: int = 1,
-        app_key: str | None = None,
-        node_id: int | None = None,
-        search_key: str | None = None,
-        page_num: int = 1,
-        page_size: int = 20,
-    ) -> dict:
-        return tasks.task_list_grouped(
-            profile=profile,
-            type=type,
-            process_status=process_status,
-            app_key=app_key,
-            node_id=node_id,
-            search_key=search_key,
-            page_num=page_num,
-            page_size=page_size,
-        )
-
-    @server.tool()
-    def task_statistics(profile: str = DEFAULT_PROFILE, app_key: str | None = None) -> dict:
-        return tasks.task_statistics(profile=profile, app_key=app_key)
-
-    @server.tool()
-    def task_urge(profile: str = DEFAULT_PROFILE, app_key: str = "", row_record_id: int = 0) -> dict:
-        return tasks.task_urge(profile=profile, app_key=app_key, row_record_id=row_record_id)
-
-    @server.tool(description=approvals._high_risk_tool_description(operation="approve", target="workflow task"))
-    def task_approve(
-        profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        apply_id: int = 0,
-        payload: dict | None = None,
-    ) -> dict:
-        return approvals.record_approve(profile=profile, app_key=app_key, apply_id=apply_id, payload=payload or {})
-
-    @server.tool(description=approvals._high_risk_tool_description(operation="reject", target="workflow task"))
-    def task_reject(
-        profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        apply_id: int = 0,
-        payload: dict | None = None,
-    ) -> dict:
-        return approvals.record_reject(profile=profile, app_key=app_key, apply_id=apply_id, payload=payload or {})
-
-    @server.tool()
-    def task_rollback_candidates(
-        profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        apply_id: int = 0,
-        audit_node_id: int = 0,
-    ) -> dict:
-        return approvals.record_rollback_candidates(
-            profile=profile,
-            app_key=app_key,
-            apply_id=apply_id,
-            audit_node_id=audit_node_id,
-        )
-
-    @server.tool()
-    def task_rollback(
-        profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        apply_id: int = 0,
-        payload: dict | None = None,
-    ) -> dict:
-        return approvals.record_rollback(profile=profile, app_key=app_key, apply_id=apply_id, payload=payload or {})
-
-    @server.tool()
-    def task_transfer_candidates(
-        profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        apply_id: int = 0,
-        page_size: int = 20,
-        page_num: int = 1,
-        audit_node_id: int = 0,
-        keyword: str | None = None,
-    ) -> dict:
-        return approvals.record_transfer_candidates(
-            profile=profile,
-            app_key=app_key,
-            apply_id=apply_id,
-            page_size=page_size,
-            page_num=page_num,
-            audit_node_id=audit_node_id,
-            keyword=keyword,
-        )
-
-    @server.tool()
-    def task_transfer(
-        profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        apply_id: int = 0,
-        payload: dict | None = None,
-    ) -> dict:
-        return approvals.record_transfer(profile=profile, app_key=app_key, apply_id=apply_id, payload=payload or {})
+    approvals.register(server)
+    tasks.register(server)
 
     return server