@josephyan/qingflow-app-user-mcp 1.1.4 → 1.1.5

package/skills/qingflow-mcp-setup/references/claude-desktop.md

@@ -31,4 +31,4 @@ Keep separate snippets for `test` and `prod` so switching environments does not
 - Replace `<ABSOLUTE_PATH_TO_REPO>` with the real checkout path on the current machine
 - If the server path changes, update the `command` field
 - The server is local stdio MCP, so no remote URL is required
-- Do not store Qingflow token in Claude Desktop config; pass it through `auth_use_token` inside the chat
+- Do not store Qingflow credentials in Claude Desktop config; pass the createClaw credential through `auth_use_credential` inside the chat, or use `auth_login` when credential exchange is unavailable

package/skills/qingflow-mcp-setup/references/environments.md

@@ -28,7 +28,8 @@ Known values in the current workspace:
 Setup behavior:
 
 - prefer this environment for Claude Desktop or local MCP client onboarding
-- use `auth_use_token` or `auth_login`, then `workspace_list`, then `workspace_select`
+- for Wingent Momo runtime, use the injected session and skip auth/workspace preflight
+- for standalone MCP client setup, use `auth_use_credential` or `auth_login`, then `workspace_list`, then `workspace_select`
 - if the user asks to verify installation, a real read-only smoke path is acceptable
 
 ## Production Environment

package/skills/qingflow-mcp-setup/references/generic-stdio.md

@@ -19,13 +19,14 @@ Keep separate client entries or separate config snippets for `test` and `prod`.
 
 1. Start the client
 2. Confirm the `qingflow` MCP server is visible
-3. Run `auth_use_token`
-4. Run `workspace_list`
-5. Run `workspace_select`
-6. Run a read-only tool such as `app_list`
+3. In Wingent Momo runtime, skip auth/workspace preflight and run a read-only tool such as `app_list`
+4. In a standalone client without injected credentials, run `auth_use_credential` or `auth_login`
+5. Then run `workspace_list`
+6. Then run `workspace_select`
+7. Run a read-only tool such as `app_list`
 
 ## Common failures
 
 - Launch failure: bad `command` path or missing `.venv`
-- Auth failure: invalid or expired token
+- Auth failure: invalid or expired credential/token
 - Business tool failure before setup: workspace not selected

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

@@ -1,12 +1,14 @@
 ---
 name: qingflow-record-analysis
-description: Analyze Qingflow record data safely after the MCP is already connected and authenticated. Use when the user wants grouped distributions, ratios, averages, rankings, trends, insights, comparisons, or any final statistical conclusion across an existing app's data. Default to schema-first record_access CSV retrieval plus local Python/pandas; do not use export tools unless the user explicitly asks for a file download.
+description: Analyze Qingflow record data safely. Use when the user wants grouped distributions, ratios, averages, rankings, trends, insights, comparisons, or any final statistical conclusion across an existing app's data. Default to schema-first record_access CSV retrieval plus local Python/pandas; do not use export tools unless the user explicitly asks for a file download.
 metadata:
   short-description: Analyze Qingflow record data with record_access CSV and Python
 ---
 
 # Qingflow Record Analysis
 
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 Use this skill only for final statistical conclusions: counts, distributions, ratios, averages, rankings, trends, comparisons, and analysis reports.
 
 Default path, every time:
@@ -20,7 +22,7 @@ app_get -> record_browse_schema_get(view_id=...) -> record_access -> Python/pand
 ```bash
 qingflow record --help
 qingflow record access --help
-qingflow record access --app-key APP_KEY --view-id VIEW_ID --columns-file columns.json --where-file where.json --order-by-file order_by.json --json
+qingflow --json record access --app-key APP_KEY --view-id VIEW_ID --columns-file columns.json --where-file where.json --order-by-file order_by.json
 ```
 
 The CLI command is under the `record` command group, so the discovery path is: first inspect `qingflow record --help`, then inspect `qingflow record access --help`.
@@ -37,10 +39,10 @@ The CLI command is under the `record` command group, so the discovery path is: f
 - Before final analysis, run a field-quality profile in pandas: row count, null rate, distinct count, and period coverage for candidate grouping fields.
 - Do not use a high-missing field as the main conclusion dimension. If a candidate dimension is sparse, downgrade it to an `已填写样本观察` and choose a cleaner semantic fallback when available.
 - Full final conclusions require `record_access.complete=true` and `record_access.safe_for_final_conclusion=true`.
-- `record_list` is only for sample inspection after the aggregate result is understood.
+- `record_list` is only for sample inspection after the aggregate result is understood; its `data.items[]` rows are flat field-title keyed objects, not nested `fields[]`.
 - `record_get` is only for single-record detail verification, logs, references, images, or readable attachments. Read images from `media_assets.items[].local_path`; read documents/tables from `file_assets.items[].local_path` and `extraction.text_path`.
 - `record_export_direct` is only for explicit export/download/Excel requests.
-- `chart_get` / QingBI is only for user-provided report URLs or chart ids.
+- `chart_get` / QingBI is only for user-provided report URLs or chart ids. If it reports `CHART_BASE_INFO_UNAVAILABLE` but `chart_data_loaded=true`, treat the chart data as readable and only the metadata/base info as degraded.
 
 ## Tool Selection
 
@@ -49,7 +51,7 @@ The CLI command is under the `record` command group, so the discovery path is: f
 | Batch analysis, statistics, comparison, report | `record_access -> Python` |
 | Browse a few example rows | `record_list` |
 | Inspect one record, logs, references, images, attachments | `record_get` |
-| User asks to export/download/Excel | `record_export_direct` |
+| User asks to export/download/Excel | `record_export_direct` with explicit `view_id` |
 | User gives report URL or chart id | `chart_get` |
 | Todo/workflow task actions | `$qingflow-task-ops` |
 
@@ -84,13 +86,12 @@ CSV columns are already readable and field-id anchored, for example `项目状
 For CLI use, write JSON argument files instead of embedding large JSON in shell text:
 
 ```bash
-qingflow record access \
+qingflow --json record access \
   --app-key APP_KEY \
   --view-id system:all \
   --columns-file columns.json \
   --where-file where.json \
-  --order-by-file order_by.json \
-  --json
+  --order-by-file order_by.json
 ```
 
 ## Status Handling

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

@@ -0,0 +1,10 @@
+identity: qingflow-record-analysis
+type: skill
+description: Analyze Qingflow record data safely. Use when the user wants grouped distributions, ratios, averages, rankings, trends, insights, comparisons, or any final statistical conclusion across an existing app's data. Default to schema-first record_access CSV retrieval plus local Python/pandas; do not use export tools unless the user explicitly asks for a file download.
+tags:
+  - cli
+  - qingflow
+  - task-management
+  - data-analysis
+  - security
+  - validated

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

@@ -1,12 +1,14 @@
 ---
 name: qingflow-record-delete
-description: Delete Qingflow records safely after the MCP is already connected and authenticated.
+description: Delete Qingflow records safely using the current Wingent Momo runtime MCP session; recover auth/workspace only after a tool error.
 metadata:
   short-description: Qingflow record delete
 ---
 
 # Qingflow Record Delete
 
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## Default Path
 
 `record_list / record_get -> record_delete`
@@ -21,9 +23,11 @@ metadata:
 
 1. Resolve the exact target `record_id` first
 2. Prefer reading the current state before delete when the request is high risk
-3. Call `record_delete` with `record_id` or `record_ids`
+3. Choose an accessible system `view_id` from `app_get.accessible_views`; custom views can locate records but cannot be used as the delete route
+4. Call `record_delete` with `record_id` or `record_ids` and the system `view_id` so the backend uses the matching listType delete route
 
 ## Do Not
 
-- Do not pass any `view_*` selector
+- Do not pass `custom:*` view selectors to `record_delete`; custom views can locate records, but delete currently supports only system listType routes
+- Do not omit `view_id`; a delete without frontend list context is ambiguous and should return `RECORD_DELETE_VIEW_REQUIRED`
 - Do not infer the target record id from a vague title if `record_list` can disambiguate it

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

@@ -1,12 +1,14 @@
 ---
 name: qingflow-record-import
-description: Explain and operate Qingflow file-based bulk import after the MCP is already connected and authenticated.
+description: Explain and operate Qingflow file-based bulk import using the current Wingent Momo runtime MCP session; recover auth/workspace only after a tool error.
 metadata:
   short-description: Qingflow bulk import workflow and troubleshooting
 ---
 
 # Qingflow Record Import
 
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## Default Path
 
 `app_get -> record_import_schema_get -> record_import_template_get -> record_import_verify -> (optional authorized repair) -> record_import_start -> record_import_status_get`
@@ -21,6 +23,33 @@ metadata:
 - `record_import_start`
 - `record_import_status_get`
 
+## File Shape And Field Mapping
+
+- Official template headers are the target contract. Do not rename them in the import file.
+- CSV can be used as a source format for planning or local transformation, but the current verify/start path expects the official Excel template (`.xlsx` / `.xls`).
+- When the user gives CSV-like data, map each source column to the official template header first, then write the mapped rows into a copy of the template after explicit user authorization.
+- Relation fields: prefer stable target `record_id` or another unique searchable value already accepted by the import schema. Do not rely on duplicated display names.
+- Member / department fields: use values inside the schema/candidate scope; do not invent departments or names that are not resolvable.
+- Select fields: use option labels from the schema/template; option ids are acceptable only when the import schema or prior readback proves they are supported.
+
+Example source CSV for planning only:
+
+```csv
+客户名称,关联客户,状态,负责人
+上海示例客户,CUST_RECORD_ID_001,有效,张三
+```
+
+Mapped template row concept:
+
+```json
+{
+  "客户名称": "上海示例客户",
+  "关联客户": "CUST_RECORD_ID_001",
+  "状态": "有效",
+  "负责人": "张三"
+}
+```
+
 ## Working Rules
 
 1. Inspect `app_get.data.import_capability` first
@@ -28,4 +57,8 @@ metadata:
 3. Keep official headers unchanged
 4. Verify before start
 5. Only repair a file after explicit user authorization
-6. Read back one imported sample after success
+6. After success, report the import status and tracking identifiers; read back one imported sample only when the user asks for row-level confirmation or when the import result does not already prove completion
+
+## Template Fallback
+
+`record_import_template_get` may return `status: partial_success` with a locally generated applicant template when the official template endpoint is permission-restricted but applicant fields are readable. If the warning is `IMPORT_TEMPLATE_LOCAL_FALLBACK_AUTH_UNKNOWN` or `verification.import_auth_prechecked` is false, treat the result only as "template file prepared"; actual import permission is still decided by `record_import_verify` and `record_import_start`.

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

@@ -1,12 +1,15 @@
 ---
 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
 
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## Default Path
 
 `record_insert_schema_get -> record_insert(items) -> optional record_get/readback`
@@ -21,10 +24,67 @@ Default to batch-shaped insert. A single new record is `items` with one row.
 - `record_department_candidates`
 - `file_upload_local`
 
+## Special Field Write Cheatsheet
+
+Always read the insert schema first, then use field titles as `items[].fields` keys. For special fields:
+
+- `member`: write a unique name, email, or resolved member id. If candidates are duplicated or the tool returns `needs_confirmation`, stop and surface candidates.
+- `department`: do not invent department names. Use a value inside the schema/candidate scope: unique department name, returned id/key, or returned object shape such as `{"key":"DEPT_ID","label":"部门名"}` / `{"id":"DEPT_ID","value":"部门名"}`.
+- `relation`: known target record id is most stable for batch inserts. Natural display text is allowed only when it uniquely resolves through the field's `searchable_fields`; duplicates require confirmation.
+- `single_select` / `multi_select`: option label and option id are both acceptable when present in schema/options. Prefer labels for readability; let the tool compile to the path-specific value.
+- `attachment`: upload the local file first with `file_upload_local`, then write the returned file value. Do not write only a filename or arbitrary URL.
+- System fields are read-only: `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, `流程标题`.
+
+## Failure Repair Contract
+
+When insert returns `blocked`, `partial_success`, or `needs_confirmation`, do not retry the whole batch blindly.
+
+- Read `items[].failed_fields[]` first.
+- Each failed field exposes `error_code`, `expected_format`, `example_value`, and `next_action`.
+- For `member`, `department`, `relation`, `attachment`, and `select` fields, `next_action` is field-type specific: candidate lookup, upload first, use record/apply id, or use schema option label/id.
+- Retry only the failed `row_number` with corrected values. If any row has `write_executed=true` or `created_record_ids` is non-empty, never replay the original batch.
+
+## 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`
-2. Read `required_fields`, `optional_fields`, `runtime_linked_required_fields`, and `payload_template`
+2. Read `required_fields`, `optional_fields`, `runtime_linked_required_fields`, `payload_template`, field-level `expected_format`, `example_value`, and `options`
 3. Inside every field bucket, read field-level `linkage` first when present; it is the canonical static hint for linked visibility, reference-driven auto fill, or formula-driven fields
 4. Inside `optional_fields`, pay special attention to any field with `may_become_required=true`; these are writable fields that can become required when linked visibility or option-driven rules activate
 5. Build `items` as `[{"fields": {...}}]`, where each `fields` map uses field titles from the insert schema
@@ -32,15 +92,18 @@ 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
+12. Follow the Special Field Write Cheatsheet for member, department, relation, select, and attachment values; do not pre-query ids by default when a natural value is unique enough
 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`
+19. Do not put Qingflow system fields in `fields`: `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, `流程标题`. They are generated by the platform and can be read after creation, not manually inserted.
+20. When the user asks to add sample records after system setup, still generate values from schema: required fields first, select values from `options`, scalar/date/amount values from `expected_format` and `example_value`; do not invent values outside the insert schema.
+21. For ratio, completion-rate, score, and percentage-like fields, obey the schema's `expected_format/example_value`. If the field was modeled as money/amount or otherwise only accepts integers, do not invent decimal percentages; either use an integer value that matches the schema or report that the field should be modeled as `number` for decimal ratios.
 
 ## Field Notes
 
@@ -58,10 +121,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`:
@@ -76,7 +145,10 @@ qingflow record insert --app-key APP_KEY --items-file records.json --json
 
 - Do not skip `record_insert_schema_get`
 - Do not invent missing required fields
+- Do not fill platform system fields such as `数据ID`, `编号`, `申请人`, `创建时间`, or `更新时间`
 - Do not flatten subtable leaf fields to the top level
+- Do not invent member / department / relation candidates outside schema or candidate scope
+- Do not invent select option labels outside schema `options`
 - Do not pre-query or silently guess member / department / relation ids when a natural string is enough
 - Do not retry a whole batch after `created_record_ids` is non-empty
 - Do not bind logic to a transient nested schema serialization detail when the field title and parent table already identify the legal payload shape

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,17 @@
 ---
 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
 
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## Default Path
 
-`record_update_schema_get -> record_update`
+`record_get -> record_update`
 
 ## Core Tools
 
@@ -20,28 +22,41 @@ 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
+14. If you use `record_list` to locate candidates, parse `data.items[]` as flat row objects such as `row["客户名称"]` + `row["record_id"]`; do not expect a nested `fields[]` array in list rows
+
+## 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,32 +1,34 @@
 ---
 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
 ---
 
 # Qingflow Task Ops
 
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## 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 +45,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 whether it succeeded, the `task_id`, the executed action, the final route/status, and any warnings
 
 ## Task-Center Rules
 
@@ -88,7 +87,8 @@ Use one of these two modes:
   - `ended`
 - `task_list` is the only public task discovery path in this MCP surface
 - `task_list --query` uses backend `searchKey` first; only when backend returns zero rows does MCP apply a local fallback match on normalized `app_name / workflow_node_name / app_key / record_id`
-- Treat `task_id` as a locator only; the action primary key is `app_key + record_id + workflow_node_id`
+- `task_id` must be copied from `task_list.data.items[].task_id`; it is not a row number, list index, record id, or workflow node id
+- Use `task_id` directly with `task_get`, `task_workflow_log_get`, `task_associated_report_detail_get`, and `task_action_execute`; do not reconstruct actions from `app_key + record_id + workflow_node_id` unless the user explicitly provided that full locator for troubleshooting
 - Default box usage:
   - `todo`: `task_list -> task_get -> task_workflow_log_get / task_associated_report_detail_get -> recommendation -> explicit user confirmation -> task_action_execute`
   - `initiated`: `task_list -> record_get`
@@ -106,15 +106,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`
+- Summarize the final action by `task_id`; include `app_key`, `record_id`, or `workflow_node_id` only as read-only context when the tool returns them, not as the action locator
 - `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/__init__.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 __all__ = ["__version__"]
 
-_FALLBACK_VERSION = "0.2.0b1099"
+_FALLBACK_VERSION = "0.2.0b1017"
 
 
 def _resolve_local_pyproject_version() -> str | None:

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()