@qingflow-tech/qingflow-app-user-mcp 1.0.11 → 1.0.12

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

@@ -1,8 +1,9 @@
 ---
 name: qingflow-record-insert
-description: Create Qingflow records with a schema-first insert workflow after the MCP is already connected and authenticated.
+description: Create Qingflow records with a schema-first insert workflow.
 metadata:
   short-description: Schema-first Qingflow record insert
+
 ---
 
 # Qingflow Record Insert
@@ -21,6 +22,43 @@ Default to batch-shaped insert. A single new record is `items` with one row.
 - `record_department_candidates`
 - `file_upload_local`
 
+## Candidate Lookup
+
+Do not pre-query member or department ids by default. Use candidate commands only when:
+
+- the user explicitly asks to see candidates
+- insert returns `needs_confirmation`
+- member / department names are likely duplicated
+- a natural value is outside the field's candidate scope
+
+```bash
+qingflow --json record member-candidates \
+  --app-key APP_KEY \
+  --field-id FIELD_ID \
+  --keyword "张三"
+```
+
+```bash
+qingflow --json record department-candidates \
+  --app-key APP_KEY \
+  --field-id FIELD_ID \
+  --keyword "直销部"
+```
+
+If the candidate scope must match an existing runtime context, pass the current record or pending fields:
+
+```bash
+qingflow --json record member-candidates \
+  --app-key APP_KEY \
+  --field-id FIELD_ID \
+  --record-id RECORD_ID \
+  --workflow-node-id WORKFLOW_NODE_ID \
+  --fields-file pending_fields.json \
+  --keyword "张三"
+```
+
+Without `record_id` / `workflow_node_id` / `fields-file`, the result is a static applicant-node preview. It is useful for explicit browsing, but not proof that every candidate is valid in a later workflow-specific write.
+
 ## Working Rules
 
 1. Start with `record_insert_schema_get`
@@ -32,13 +70,13 @@ Default to batch-shaped insert. A single new record is `items` with one row.
 7. For `linkage.kind=logic_visibility`, read `sources` as upstream trigger fields and treat `role=manual_input_after_activation` as "fill this only after the upstream condition is satisfied"
 8. For `linkage.kind=reference_fill`, prefer filling the source field first; treat target fields with `role=auto_fill_preferred` or `auto_fill_only` as reference-driven outputs rather than blind manual inputs
 9. For `linkage.kind=formula_fill`, treat the field as formula/default-auto-fill driven unless the user explicitly asks to override it and the field is still writable
-10. If insert succeeds and single-record detail/readback matters, prefer `record_get`; use `record_list(..., output_profile="normalized")` only for batch row-shaped normalized readback
+10. If insert succeeds and single-record detail/readback matters, prefer `record_get`; for batch verification, rely on returned `created_record_ids` first, then use `record_get` for selected rows or `record_access -> Python` when a row-shaped bulk check is truly needed
 11. Keep subtable payloads under the parent field as a row array
 12. Member / department / relation fields may accept natural strings directly, such as `"张三"`, `"直销部"`, or `"海军军医大学"`; do not pre-query ids by default
 13. If the write returns `status="needs_confirmation"`, stop and surface the candidates
 14. Retry failed rows only with explicit ids / objects after the user confirms
 15. Keep `verify_write=true` for production inserts
-16. If post-write detail context matters, read `record_get.fields[]`, `media_assets.items[].local_path`, `file_assets.items[].local_path`, `file_assets.items[].extraction.text_path`, and `semantic_context`; `record_get` follows the frontend storage cookie redirect path for Qingflow attachments, so prefer local paths over remote URLs and do not expect legacy `data.normalized_record`
+16. If post-write detail context matters, read `record_get.fields[]`, `media_assets.items[].local_path`, `file_assets.items[].local_path`, `file_assets.items[].extraction.text_path`, and `semantic_context`; `record_get` follows the frontend storage cookie redirect path for Qingflow attachments, so prefer local paths over remote URLs and do not expect legacy flat record shapes
 17. Treat nested schema shape as guidance, not a brittle contract; do not hard-code transient implementation details like optional nested `field_id` shape when composing inserts
 18. For `partial_success`, read `created_record_ids`, then repair only the failed `items[].row_number` using `failed_fields`; never retry the whole batch after any row has `write_executed=true`
 
@@ -58,10 +96,16 @@ Default to batch-shaped insert. A single new record is `items` with one row.
 
 ## CLI Pattern
 
+CLI fallback for the schema step:
+
+```bash
+qingflow --json record schema insert --app-key APP_KEY > tmp/qingflow_insert_schema.json
+```
+
 Use a JSON array file:
 
 ```bash
-qingflow record insert --app-key APP_KEY --items-file records.json --json
+qingflow --json record insert --app-key APP_KEY --items-file records.json
 ```
 
 `records.json`:

package/skills/qingflow-record-insert/manifest.yaml

@@ -0,0 +1,6 @@
+identity: qingflow-record-insert
+type: skill
+description: Create Qingflow records. Default to record_insert_schema_get -> record_insert(items); one row is still an items array. Member, department, and relation fields prefer natural language, and failures are recovered from created_record_ids plus failed_fields.
+tags:
+  - cli
+  - qingflow

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

@@ -1,15 +1,15 @@
 ---
 name: qingflow-record-update
-description: Update Qingflow records with a schema-first record-specific workflow after the MCP is already connected and authenticated.
+description: Update Qingflow records through the current record detail context using the Wingent Momo runtime MCP session; recover auth/workspace only after a tool error.
 metadata:
-  short-description: Schema-first Qingflow record update
+  short-description: Detail-first Qingflow record update
 ---
 
 # Qingflow Record Update
 
 ## Default Path
 
-`record_update_schema_get -> record_update`
+`record_get -> record_update`
 
 ## Core Tools
 
@@ -20,28 +20,40 @@ metadata:
 
 ## Working Rules
 
-1. Start with `record_update_schema_get(app_key, record_id)`
-2. Use only `writable_fields` and `payload_template` from that response
-3. Read field-level `linkage` before composing updates; it is the static hint for whether a field is a linked source, linked target, reference-driven auto fill field, or formula-driven field
-4. Build `fields` as a field-title keyed map
-5. Build `fields` only from that returned field set; MCP will choose the first matched accessible view that can execute the payload
-6. If a field has `linkage.affects_fields`, treat it as a source field; changing it may also change how other fields are interpreted or auto-filled
-7. If a field has `linkage.sources`, treat those titles as upstream dependencies that explain why the field matters or why its validation can change
-8. For `linkage.kind=reference_fill`, prefer updating the source reference field first and treat `role=auto_fill_preferred` or `auto_fill_only` targets as outputs of that reference relationship
-9. For `linkage.kind=formula_fill`, treat the field as formula/default-auto-fill driven unless the field is still clearly writable and the user explicitly wants to override it
-10. Keep `verify_write=true` for production updates
-11. If the write returns `status="needs_confirmation"`, stop and surface the candidates
-12. Do not assume any arbitrary combination of writable fields will succeed; one single matched accessible view still has to cover the payload
-13. Do not look for any extra context bucket in update schema; lookup behavior stays inline on the field definitions themselves
-14. When update context feels unstable, trust `record_update_schema_get`'s route-aware matched-view result over guessed `view_id` or remembered UI scope
-15. If single-record detail/readback matters, prefer `record_get` after the write and read top-level `fields[]`, `media_assets.items[].local_path`, `file_assets.items[].local_path`, `file_assets.items[].extraction.text_path`, and `semantic_context`; `record_get` follows the frontend storage cookie redirect path for Qingflow attachments, so prefer local paths over remote URLs; use `record_list(..., output_profile="normalized")` only for batch row-shaped normalized readback
-16. For batch updates, read top-level `mode`, `dry_run`, `total`, `succeeded`, `failed`, `needs_confirmation`, `updated_record_ids`, `write_executed`, `safe_to_retry`, `verification_status`, and `items[].row_number/status/record_id`
-17. If `write_executed=true`, do not blindly retry the whole batch; use `items[]` and `updated_record_ids` to decide whether only failed rows need repair
+1. Start with `record_get(app_key, record_id, view_id when known)` to read the current detail-page context; if the frontend/custom view is known, keep that same `view_id` through the update
+2. Use `record_get.fields[]` for field titles, `field_id`, `kind`, and current values
+3. Build `fields` as a field-title keyed map containing only the user-requested changes
+4. Run `record_update` directly with that key/value map; pass the same `view_id` when it is known so the tool tries that frontend view first, then let the tool fall back to other executable routes if needed
+5. Keep `verify_write=true` for production updates
+6. If the write returns `status="needs_confirmation"`, stop and surface the candidates
+7. On success, read only the final status, `update_route`, `write_executed`, and verification result; do not surface intermediate route failures as the outcome
+8. On failure, surface the failed reason and field/path diagnostics returned by `record_update`
+9. Use `record_update_schema_get` only after an update failure, field ambiguity, or explicit request to diagnose writable fields/routes
+10. Treat app-level `viewList` or applicant/insert schema 40002 as auxiliary-context loss, not as final record permission denial, when `record_get` or `record_update` succeeds through the selected `custom:*` view or `system:all`/type=8 route
+11. If single-record readback matters, prefer `record_get` after the write and read top-level `fields[]`, `media_assets.items[].local_path`, `file_assets.items[].local_path`, `file_assets.items[].extraction.text_path`, and `semantic_context`; `record_get` follows the frontend storage cookie redirect path for Qingflow attachments, so prefer local paths over remote URLs; use `record_list(..., output_profile="normalized")` only for batch row-shaped normalized readback
+12. For batch updates, read top-level `mode`, `dry_run`, `total`, `succeeded`, `failed`, `needs_confirmation`, `updated_record_ids`, `write_executed`, `safe_to_retry`, `verification_status`, and `items[].row_number/status/record_id`
+13. If `write_executed=true`, do not blindly retry the whole batch; use `items[]` and `updated_record_ids` to decide whether only failed rows need repair
+
+## Special Field Values
+
+Use the field `kind` from `record_get.fields[]` when shaping values:
+
+- `member`: start with a natural-language name such as `"周颖"`. If `record_update` returns `status="needs_confirmation"`, no write happened; retry with one candidate object, for example `{"uid":1048599,"name":"沈嘉慧Seth","email":"shenjiahui@exiao.tech"}`.
+- `department`: start with a department name such as `"客户成功部"`. The record tool resolves names through the member-visible directory path first; do not pre-query ContactAuth-only contact management APIs for ids. On `needs_confirmation`, retry with the explicit candidate object/id returned by the tool.
+- `relation`: prefer a unique human-readable target value or `{"apply_id":"..."}`. On multiple matches, stop and retry only after choosing one `confirmation_requests[].candidates[]` item.
+- `select`: single select uses one option string; multi select uses an array of option strings.
+- `attachment`: use a supported uploaded/file object from the returned format hints; do not invent remote URLs when the tool asks for upload.
+- Reference, formula, auto-fill, readonly, and system fields are not independent writable kinds. Do not force-write the filled target field; update the upstream driving field instead, or surface the blocker.
+
+`needs_confirmation` means `write_executed=false`: the tool found candidates but did not have enough certainty to write. Do not report it as success or failure. Surface the candidate list if user choice is needed; if the intended candidate is obvious from the user request or prior context, retry with the explicit object and then verify the final value.
+
+For member or department ambiguity, use the record candidate tools (`record_member_candidates` / `record_department_candidates`, or CLI `qingflow record member-candidates` / `department-candidates`). These follow the same field-scope candidate route as the frontend selector; do not replace them with contact-directory management queries.
 
 ## Do Not
 
-- Do not pass any `view_*` selector
-- Do not update fields missing from `writable_fields`
+- Do not pass legacy `view_key` / `view_name` selectors; use `view_id` only when the frontend/detail view is known
+- Do not call `record_update_schema_get` as the normal pre-step for every update
+- Do not use applicant/insert schema to decide record update fields
+- Do not update fields that were absent from `record_get.fields[]` unless the user explicitly provided a raw field id and you can justify it
 - Do not resolve lookup fields against a guessed record context
-- Do not ignore `linkage.affects_fields` when changing source-like fields on complex forms
-- Do not fall back to guessed browse scopes when `record_update_schema_get` already tells you which matched route can or cannot execute the payload
+- Do not treat a denied intermediate route as final failure when `record_update` later succeeds through another route

package/skills/qingflow-task-ops/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qingflow-task-ops
-description: Use Qingflow todo discovery, workflow task context, associated approval context, workflow logs, and unified task actions after the MCP is already connected and authenticated. Do not use this skill for record CRUD or final statistical analysis.
+description: Use Qingflow todo discovery, workflow task context, associated approval context, workflow logs, and unified task actions with the current Wingent Momo runtime MCP session. Do not use this skill for record CRUD or final statistical analysis.
 metadata:
   short-description: Qingflow task workflow context and actions
 ---
@@ -10,23 +10,23 @@ metadata:
 ## Overview
 
 This skill is for task workflow operations only.
-Assumes MCP is connected, authenticated, and on the correct workspace.
+In Wingent Momo runtime, trust injected MCP credentials, workspace, and route context until a business tool explicitly reports otherwise.
 Before executing, skim the shared maintenance baseline: [public-surface-sync.md](../qingflow-app-user/references/public-surface-sync.md).
 
 ## Default Paths
 
 Use exactly one of these default paths:
 
-1. Find target todos  
+1. Find target todos
    `task_list`
 
-2. Read one task context  
+2. Read one task context
    `task_list -> exact target -> task_get`
 
-3. Read associated approval context  
-   `task_get -> task_associated_report_detail_get` or `task_workflow_log_get`
+3. Read associated approval context when material to a high-impact recommendation
+   `task_get -> task_workflow_log_get` and/or material `task_associated_report_detail_get`
 
-4. Execute workflow action  
+4. Execute workflow action
    `task_list -> exact target -> task_get -> task_action_execute`
 
 5. Execute a user-specified action on an already-clear target
@@ -43,29 +43,26 @@ Use exactly one of these default paths:
 ## Supporting Tools
 
 - `app_list`
-- `app_search`
 
 ## Standard Operating Order
 
 Use one of these two modes:
 
 1. Recommendation mode
-   1. Ensure auth exists
-   2. Ensure workspace is selected
-   3. Discover the exact target with `task_list`
-   4. Read node context with `task_get`
-   5. Before giving any approval recommendation, read `task_workflow_log_get`
-   6. If `task_get` returns any `associated_reports`, read every visible report through `task_associated_report_detail_get`
-   7. Give a recommendation only after reviewing node context, workflow log, and associated reports
-   8. Wait for explicit user confirmation before `task_action_execute`
+   1. Trust the current MCP/session when the runtime has already injected credentials; recover auth/workspace only after an actual tool error
+   2. Discover the exact target with `task_list`
+   3. Read node context with `task_get`
+   4. Before giving a high-impact approve/reject/rollback/transfer recommendation, read `task_workflow_log_get`
+   5. If `task_get` returns visible `associated_reports`, read the reports that are material to the decision; if a report cannot be read, disclose the gap instead of blocking indefinitely
+   6. Give a recommendation only after reviewing the available node context, workflow log when visible, and material associated reports
+   7. Wait for explicit user confirmation before `task_action_execute`
 
 2. User-directed execution mode
-   1. Ensure auth exists
-   2. Ensure workspace is selected
-   3. Discover the exact target with `task_list`
-   4. If the target or action requirements are ambiguous, read `task_get`; otherwise go straight to `task_action_execute`
-   5. Execute through `task_action_execute`
-   6. After actions, report the exact `app_key`, `record_id`, `workflow_node_id`, executed action, and any warnings
+   1. Trust the current MCP/session when the runtime has already injected credentials; recover auth/workspace only after an actual tool error
+   2. Discover the exact target with `task_list`
+   3. If the target or action requirements are ambiguous, read `task_get`; otherwise go straight to `task_action_execute`
+   4. Execute through `task_action_execute`
+   5. After actions, report the exact `app_key`, `record_id`, `workflow_node_id`, executed action, and any warnings
 
 ## Task-Center Rules
 
@@ -106,15 +103,18 @@ Use one of these two modes:
   - `transfer`
   - `urge`
   - `save_only`
-- Before any approve/reject/rollback/transfer recommendation, always review `task_workflow_log_get` when `task_get.visibility.audit_record_visible=true`
-- If `task_get` returns visible `associated_reports`, review each one with `task_associated_report_detail_get`; do not rely on report summary alone
-- Do not give an approval recommendation based only on `task_get`
+- Before high-impact approve/reject/rollback/transfer recommendations, review `task_workflow_log_get` when `task_get.visibility.audit_record_visible=true`
+- If `task_get` returns visible `associated_reports`, review material reports with `task_associated_report_detail_get`; for unreadable or irrelevant reports, disclose the limitation instead of blocking the whole task
+- QingBI associated report detail follows the frontend/qflow visible chart-data route first; a middle `CHART_SEE` / `40002` from legacy BI data reads is not by itself proof that the task-associated report is invisible.
+- Do not give a high-impact approval recommendation based only on `task_get` unless workflow log/report visibility is unavailable and you explicitly state that limitation
 - Do not execute `task_action_execute` until the user explicitly confirms the chosen action
 - Exception: if the user has already explicitly authorized a concrete action on exact targets, you may execute directly after exact target resolution
 - Avoid actions on ambiguous tasks or records
 - Summarize the final action and the exact `app_key / record_id / workflow_node_id`
 - `reject` requires `payload.audit_feedback`
+- For approve/reject, trust the current task detail or an explicit frontend-provided `formId`; app baseInfo is only a fallback. A baseInfo `40002` is not final task-action denial when `formId` is already known.
 - `save_only` requires non-empty `fields` and is only available when the backend exposes editable fields for the current node
+- For `save_only`, trust `task_get.editable_fields` / `editableQueIds` from the current task node. An app applicant-schema `40002` is not final task denial when the task detail already exposes the editable field.
 - `task_action_execute` now distinguishes action execution from workflow continuation. Read `verification.runtime_continuation_verified` before claiming the workflow actually moved on.
 - If `task_action_execute` returns `partial_success` with `WORKFLOW_CONTINUATION_UNVERIFIED`, report the action as sent but the downstream continuation as unverified.
 - If `task_action_execute` returns `TASK_CONTEXT_VISIBILITY_UNVERIFIED` after a `46001`-style context loss, do not claim the task was already processed unless the workflow log or record state proves it.

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

@@ -41,4 +41,3 @@ For task ops, always report:
 - 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

@@ -14,14 +14,12 @@ Examples:
 
 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
+- if the user starts from inbox, todo, workload, cc, or bottleneck language, use the public task tools first
+- use `task_list` for headline counts and flat browsing; group locally by app or workflow node when buckets matter
+- use `task_get`, `task_workflow_log_get`, and `task_associated_report_detail_get` only after locating the exact task
 - 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`
+- for approve or reject, identify the exact target first; prefer `task_id` from task-center results, then use `task_action_execute` with action `approve` or `reject`
 - avoid usage-side workflow actions on ambiguous records
 - summarize the final action and target task ids or record ids
-

package/src/qingflow_mcp/__main__.py

@@ -1,5 +1,9 @@
-"""Entry point for running qingflow_mcp as a module."""
-from qingflow_mcp.server import main
+"""Entry point for running qingflow_mcp as a module.
+
+Default to the curated user-facing MCP surface. Split package and console
+entrypoints can still start the builder server explicitly.
+"""
+from qingflow_mcp.server_app_user import main
 
 if __name__ == "__main__":
     main()