@josephyan/qingflow-app-user-mcp 1.1.25 → 1.1.26

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

@@ -1,14 +1,12 @@
 ---
 name: qingflow-record-import
-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.
+description: Explain and operate Qingflow file-based bulk import after the MCP is already connected and authenticated.
 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`
@@ -23,33 +21,6 @@ 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
@@ -57,8 +28,4 @@ Mapped template row concept:
 3. Keep official headers unchanged
 4. Verify before start
 5. Only repair a file after explicit user authorization
-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`.
+6. Read back one imported sample after success

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

@@ -1,15 +1,12 @@
 ---
 name: qingflow-record-insert
-description: Create Qingflow records with a schema-first insert workflow.
+description: Create Qingflow records with a schema-first insert workflow after the MCP is already connected and authenticated.
 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`
@@ -24,67 +21,10 @@ 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`, `payload_template`, field-level `expected_format`, `example_value`, and `options`
+2. Read `required_fields`, `optional_fields`, `runtime_linked_required_fields`, and `payload_template`
 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
@@ -92,18 +32,15 @@ Without `record_id` / `workflow_node_id` / `fields-file`, the result is a static
 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`; 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
+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
 11. Keep subtable payloads under the parent field as a row array
-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
+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 flat record shapes
+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`
 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
 
@@ -121,16 +58,10 @@ Without `record_id` / `workflow_node_id` / `fields-file`, the result is a static
 
 ## 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 --json record insert --app-key APP_KEY --items-file records.json
+qingflow record insert --app-key APP_KEY --items-file records.json --json
 ```
 
 `records.json`:
@@ -145,10 +76,7 @@ qingflow --json record insert --app-key APP_KEY --items-file records.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-update/SKILL.md

@@ -1,17 +1,15 @@
 ---
 name: qingflow-record-update
-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.
+description: Update Qingflow records with a schema-first record-specific workflow after the MCP is already connected and authenticated.
 metadata:
-  short-description: Detail-first Qingflow record update
+  short-description: Schema-first Qingflow record update
 ---
 
 # Qingflow Record Update
 
-> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
-
 ## Default Path
 
-`record_get -> record_update`
+`record_update_schema_get -> record_update`
 
 ## Core Tools
 
@@ -22,41 +20,28 @@ metadata:
 
 ## Working Rules
 
-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.
+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
 
 ## Do Not
 
-- 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 pass any `view_*` selector
+- Do not update fields missing from `writable_fields`
 - Do not resolve lookup fields against a guessed record context
-- Do not treat a denied intermediate route as final failure when `record_update` later succeeds through another route
+- 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

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

@@ -1,34 +1,32 @@
 ---
 name: qingflow-task-ops
-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.
+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.
 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.
-In Wingent Momo runtime, trust injected MCP credentials, workspace, and route context until a business tool explicitly reports otherwise.
+Assumes MCP is connected, authenticated, and on the correct workspace.
 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 when material to a high-impact recommendation
-   `task_get -> task_workflow_log_get` and/or material `task_associated_report_detail_get`
+3. Read associated approval context  
+   `task_get -> task_associated_report_detail_get` or `task_workflow_log_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
@@ -45,26 +43,29 @@ 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. 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`
+   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`
 
 2. User-directed execution mode
-   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
+   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
 
 ## Task-Center Rules
 
@@ -87,8 +88,7 @@ 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`
-- `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
+- Treat `task_id` as a locator only; the action primary key is `app_key + record_id + workflow_node_id`
 - 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,18 +106,15 @@ Use one of these two modes:
   - `transfer`
   - `urge`
   - `save_only`
-- 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
+- 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`
 - 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 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
+- 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,3 +41,4 @@ 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,12 +14,14 @@ Examples:
 
 Rules:
 
-- 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
+- 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 target first; prefer `task_id` from task-center results, then use `task_action_execute` with action `approve` or `reject`
+- 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-workflow-builder/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: qingflow-workflow-builder
+description: |
+  在已有的轻流应用中，根据业务建模使用 qingflow CLI 声明式搭建工作流。
+  适用场景：应用已存在、字段已就绪，需要创建或更新审批/填写/网关/自动化/抄送流程。
+  不适用场景：应用不存在或字段缺失——应先完成应用搭建（schema apply）再使用本 Skill。
+---
+
+# 轻流工作流搭建 Skill
+
+## 快速索引
+
+| 主题 | 文件 |
+|------|------|
+| 依赖命令、能力边界 | [references/01-overview.md](references/01-overview.md) |
+| 更新模式与最小修改原则 | [references/02-update-mode.md](references/02-update-mode.md) |
+| 流程模式速查（线性/分支/回退） | [references/03-flow-patterns.md](references/03-flow-patterns.md) |
+| 阶段 1：业务建模与自检 | [references/04-stage1-business-modeling.md](references/04-stage1-business-modeling.md) |
+| 阶段 2：成员/角色搜索 | [references/05-stage2-members-roles.md](references/05-stage2-members-roles.md) |
+| 阶段 3：Schema + 构建 Spec | [references/06-stage3-build-spec.md](references/06-stage3-build-spec.md) |
+| 阶段 4：验证 Spec | [references/07-stage4-validate-spec.md](references/07-stage4-validate-spec.md) |
+| 阶段 5：Apply + 验证循环 | [references/08-stage5-apply-verify.md](references/08-stage5-apply-verify.md) |
+| 阶段 6：总结报告与回退 | [references/09-stage6-summary.md](references/09-stage6-summary.md) |
+| 节点配置参考 | [references/10-node-config-reference.md](references/10-node-config-reference.md) |
+| 常见问题与排障 | [references/11-troubleshooting.md](references/11-troubleshooting.md) |
+
+---
+
+## 一、思考（Thought）：何时启用与前置条件
+
+### 触发条件
+
+当用户要求**在轻流应用中搭建工作流**时启用本 Skill，典型触发语：
+
+- "帮我搭建审批流程"
+- "在这个应用里创建工作流"
+- "按照这张流程图实现工作流"
+- "配置流程分支条件"
+- "给这个应用加一个审批节点"
+
+### 前提检查（进入行动前必须完成）
+
+在开始任何搭建操作前，按顺序确认以下条件：
+
+1. **应用存在性**：`qingflow --json app get --app-key <APP_KEY>` 成功返回
+2. **字段就绪**：`qingflow --json builder app get --app-key <APP_KEY> fields` 返回字段列表，确认业务建模所需字段（如单选框、成员、部门字段）均已存在
+3. **未启用已有流程**（新建场景）：`qingflow --json builder app get --app-key <APP_KEY> flow` 查看 `enabled` 状态，若已有流程则为**更新模式**
+
+**不满足时的处理**：
+- 应用不存在 → 先完成应用搭建和字段配置，再继续工作流搭建
+- 字段缺失 → 先补充缺失的字段定义，再继续工作流搭建
+- 应用已启用流程 → 进入更新模式（读取现有 spec 再修改）
+
+### 能力边界
+
+| 在范围内 | 超出范围 |
+|----------|----------|
+| 基于已有应用搭建工作流 | 从零创建应用 |
+| 声明式 WorkflowSpec 生成与 apply | 操作复杂命令拼接 |
+| 分支条件（gateway + autoJudges）配置 | 后端不支持的高级特性 |
+| 审批/填写/抄送/自动化节点配置 | 修改字段定义 |
+| 成员/角色搜索用于节点负责人 | 组织架构管理 |
+| 验证 → apply → 校验循环 | 前端 UI 拖拽操作 |
+
+完整命令与依赖说明见 [references/01-overview.md](references/01-overview.md)。
+本 Skill 中的 `scripts/...` 路径均以 `qingflow-workflow-builder/` 技能根目录为基准；执行脚本时先解析为该技能目录下的实际文件。
+
+---
+
+## 二、行动（Action）：核心 SOP
+
+按顺序执行以下阶段，每个阶段详见对应 reference 文件：
+
+| 阶段 | 任务 | 参考文件 |
+|------|------|----------|
+| 阶段 0 | 判断是否为更新模式，确认最小修改原则 | [references/02-update-mode.md](references/02-update-mode.md) |
+| 阶段 1 | 提取业务建模，完成七维度业务自检 | [references/04-stage1-business-modeling.md](references/04-stage1-business-modeling.md) |
+| 阶段 2 | 搜索成员/角色，用于节点负责人配置 | [references/05-stage2-members-roles.md](references/05-stage2-members-roles.md) |
+| 阶段 3 | 获取 Schema、读取现有 Spec、构建新 Spec | [references/06-stage3-build-spec.md](references/06-stage3-build-spec.md) |
+| 阶段 4 | 验证 Spec（JSON Schema + 自定义约束） | [references/07-stage4-validate-spec.md](references/07-stage4-validate-spec.md) |
+| 阶段 5 | Apply 工作流并验证部署结果 | [references/08-stage5-apply-verify.md](references/08-stage5-apply-verify.md) |
+
+构建 Spec 前，若对流程模式有疑问，先查阅 [references/03-flow-patterns.md](references/03-flow-patterns.md)。
+
+---
+
+## 三、反思（Reflection）：验证与总结
+
+| 阶段 | 任务 | 参考文件 |
+|------|------|----------|
+| 阶段 6 | 输出结构化搭建报告，回顾业务完整性 | [references/09-stage6-summary.md](references/09-stage6-summary.md) |
+
+搭建失败时的回退策略、节点配置细节、常见问题排障分别见：
+- [references/09-stage6-summary.md](references/09-stage6-summary.md)
+- [references/10-node-config-reference.md](references/10-node-config-reference.md)
+- [references/11-troubleshooting.md](references/11-troubleshooting.md)

package/skills/qingflow-workflow-builder/manifest.yaml

@@ -0,0 +1,8 @@
+identity: qingflow_workflow_builder
+type: skill
+description: 在轻流应用中搭建工作流。从业务建模提取流程结构（含业务完整性自检：规模分级、组织层级、异常路径、状态闭环、角色分离），映射为声明式 WorkflowSpec，通过 qingflow CLI 的 schema/get/apply 三步部署工作流，并验证分支条件与自动化节点配置一致性。
+tags:
+  - qingflow
+  - workflow
+  - builder
+  - flow

package/skills/qingflow-workflow-builder/references/01-overview.md

@@ -0,0 +1,45 @@
+# 轻流工作流搭建：概览与依赖
+
+## 关联文件
+
+| 文件 | 说明 |
+|------|------|
+| `manifest.yaml` | 技能清单 |
+| `SKILL.md` | 主流程入口 |
+| `scripts/validate_flow_spec.py` | 工作流 Spec 验证脚本，基于 JSON Schema + 自定义约束 |
+| `scripts/diff_flow_spec.py` | 新旧 Spec 差异分析脚本，辅助更新模式下最小修改原则判断 |
+
+---
+
+## 依赖声明
+
+本 Skill 关键依赖 **qingflow CLI**（已安装于 PATH，详见 `qingflow_cli` Skill）。以下 qingflow 命令为核心操作：
+
+| 命令 | 用途 |
+|------|------|
+| `qingflow builder flow schema --json` | 获取最新 WorkflowSpecDTO JSON Schema |
+| `qingflow builder flow get --app-key <KEY>` | 读取当前工作流 spec |
+| `qingflow builder flow apply --app-key <KEY> --spec-file <FILE>` | 部署/更新工作流 |
+| `qingflow builder member search --query <关键词>` | 搜索成员 |
+| `qingflow builder role search --keyword <关键词>` | 搜索角色 |
+| `qingflow --json app get --app-key <KEY>` | 获取应用信息（字段列表等） |
+| `qingflow --json builder app get --app-key <KEY> fields` | 获取应用可搭建字段详情 |
+| `qingflow --json builder app get --app-key <KEY> flow` | 获取流程摘要（是否启用等） |
+
+---
+
+## 能力边界
+
+| 在范围内 | 超出范围 |
+|----------|----------|
+| 基于已有应用搭建工作流 | 从零创建应用 |
+| 声明式 WorkflowSpec 生成与 apply | 操作复杂命令拼接 |
+| 分支条件（gateway + autoJudges）配置 | 后端不支持的高级特性 |
+| 审批/填写/抄送/自动化节点配置 | 修改字段定义 |
+| 成员/角色搜索用于节点负责人 | 组织架构管理 |
+| 验证 → apply → 校验循环 | 前端 UI 拖拽操作 |
+
+---
+
+← 返回主流程：[../SKILL.md](../SKILL.md)
+→ 下一步：[02-update-mode.md](02-update-mode.md)