@qingflow-tech/qingflow-app-user-mcp 1.0.40 → 1.0.41

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @qingflow-tech/qingflow-app-user-mcp@1.0.40
+npm install @qingflow-tech/qingflow-app-user-mcp@1.0.41
 ```
 
 Run:
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-app-user-mcp@1.0.40 qingflow-app-user-mcp
+npx -y -p @qingflow-tech/qingflow-app-user-mcp@1.0.41 qingflow-app-user-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-app-user-mcp",
-  "version": "1.0.40",
+  "version": "1.0.41",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "1.0.40"
+version = "1.0.41"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-app-builder/SKILL.md

@@ -7,6 +7,8 @@ metadata:
 
 # Qingflow App Builder
 
+> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## Overview
 
 This skill is for the current **public builder surface**, not for legacy low-level builder writes.
@@ -15,6 +17,7 @@ In Wingent Momo runtime, trust the injected MCP session, credentials, workspace,
 Before any write or verification flow, identify whether the task targets `test` or `prod` and read [references/environments.md](references/environments.md). If the user did not specify one, default to `prod`.
 
 Before choosing a route, skim the shared maintenance baseline: [public-surface-sync.md](references/public-surface-sync.md).
+Then pick the matching development guide: [single-app-development-guide.md](references/single-app-development-guide.md) for one app, or [complete-system-development-guide.md](references/complete-system-development-guide.md) for app packages/systems.
 
 ## Current Public Mental Model
 
@@ -36,11 +39,13 @@ Default modeling rules:
 
 Before any builder write, classify the request:
 
-- **Complete system / app package**: the user asks for a system, package, workspace module set, or several related forms/apps. Use `package_apply` for the package, then one `app_schema_apply(package_id=..., apps=[...])` for the app shells and fields. Do not squeeze several business objects into one app.
+- **Complete system / app package**: the user asks for a system, package, workspace module set, or several related forms/apps. Use `package_apply` for the package, then one `app_schema_apply(package_id=..., apps=[...])` for the app shells and fields. This is the main path for complete systems, not a bulk shortcut to abandon after the first slow response. Do not squeeze several business objects into one app.
 - **Single app**: the user names one form/app or gives one `app_key`. Use `app_resolve`/`app_get`, then `app_schema_apply` and the app-scoped apply tools.
 - **Record/user operation**: the user wants to add, edit, delete, approve, or analyze data. Route to the record/task skills instead of builder tools.
 
-For complete systems, `apps[]` should use stable `client_key` values. Same-call relation fields may use `target_app_ref` for a client key or `target_app` for another app name. Prefer `target_app_ref` when names may collide. Create the related apps with one multi-app schema apply; do not create each app separately just to collect app keys and then patch relations afterward.
+For complete systems, `apps[]` should use stable `client_key` values. Same-call relation fields should use `target_app_ref` for another `apps[].client_key`; use `target_app_key` only when the target app already exists or has been confirmed by readback. Create the related apps with one multi-app schema apply; do not create each app separately just to collect app keys and then patch relations afterward.
+
+If a complete-system `app_schema_apply` times out, returns `partial_success`, returns `write_executed=true`, has `safe_to_retry=false`, or has incomplete readback, treat it as an uncertain write, not as a failed create. The next action is always `readback_before_retry`: read the package/app/fields first, compare intended `client_key`/`app_name`/relations against reality, and only then repair the missing slice. Do not retry the whole multi-app create, create `V2`/`测试`/random-suffix apps, or split the system into single-app rebuilds to bypass a duplicate/conflict.
 
 Builder schema inputs should follow agent-intuitive semantics:
 
@@ -69,7 +74,8 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - Multi-app schema work:
   - use one `app_schema_apply(package_id=..., apps=[...])` / CLI `builder schema apply --apps-file` when creating several apps in one package
   - every `apps[]` item should carry its own `client_key`, `app_name`, `icon`, `color`, and `add_fields`
-  - same-call relation fields may use `target_app_ref` to point at another `apps[].client_key`, or `target_app` to point at another `apps[].app_name`
+  - same-call relation fields should use `target_app_ref` to point at another `apps[].client_key`; use `target_app` only when the app name is unique and stable, and use `target_app_key` only after the target app already exists or readback has confirmed it
+  - timeout / `partial_success` / `write_executed=true` / `safe_to_retry=false` means `readback_before_retry`; do not directly downgrade to single-app creation
 - App base permissions:
   - trust `app_get.editability.can_edit_app_base` for app base-info writes like app name, icon, and visibility
   - `can_edit_form` only means schema/form-route capability; it no longer implies app base-info write capability
@@ -161,6 +167,8 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - Do not guess package identity from a loose name. Public package work assumes a known `package_id`, or an explicit create/update intent through `package_apply`.
 - Do not perform routine auth probes before every builder action in runtime contexts with injected MCP credentials; recover auth only after an actual auth/workspace failure.
 - If `package_id` is unknown, derive it from related app/portal readback when possible; otherwise ask the user instead of falling back to hidden package lookup tools.
+- Do not bypass package/app-name conflicts by inventing `V2`, `测试`, timestamp, or random suffix apps in a real business package. Read back and decide whether to update the existing app, create only a truly missing app, or ask the user.
+- After any uncertain schema write, do `readback_before_retry` with `package_get` / `app_resolve` / `app_get_fields`; retry only the verified missing or failed slice.
 - Do not use `package_create` or `package_attach_app` as a public default path. If they still appear in low-level code, treat them as internal/legacy implementation details.
 - Do not use raw `portal_*` writes or raw `qingbi_report_*` writes as the default builder strategy.
 - `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, and `app_views_apply` publish by default; `app_custom_buttons_apply` and `app_associated_resources_apply` publish after at least one write succeeds and do not accept a draft-only `publish` parameter; `app_charts_apply` is immediate-live without publish.
@@ -179,7 +187,7 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - For UI cards or quick narration, read `resources[]` first. Each resource has `resource_type`, `operation`, `status`, `id`, `key`, `name`, typed `ids`, and `parent`.
 - Use legacy fields such as `field_diff`, `views_diff`, `chart_results`, `created/updated/removed`, and `verification` only for compatibility and troubleshooting.
 - Treat post-write readback as the source of truth, not just write status codes.
-- `success` means write and verification completed; `partial_success` means the write landed but verification is incomplete.
+- `success` means write and verification completed; `partial_success` means the write landed or may have landed but verification is incomplete. If `write_executed=true`, `safe_to_retry=false`, or readback is unavailable, do `readback_before_retry` before any create retry.
 - For portals, distinguish clearly between:
   - base-info-only update with layout preserved
   - full sections replace
@@ -271,6 +279,8 @@ For add-data buttons that create a child record linked back to the current recor
 - Tool choice and sequencing: [references/tool-selection.md](references/tool-selection.md)
 - Field matching rules: [references/match-rules.md](references/match-rules.md)
 - Result semantics and gotchas: [references/gotchas.md](references/gotchas.md)
+- Single app development guide: [references/single-app-development-guide.md](references/single-app-development-guide.md)
+- Complete system development guide: [references/complete-system-development-guide.md](references/complete-system-development-guide.md)
 - Create one app in an existing package: [references/create-app.md](references/create-app.md)
 - Update fields only: [references/update-schema.md](references/update-schema.md)
 - Update layout only: [references/update-layout.md](references/update-layout.md)

package/skills/qingflow-app-builder/references/complete-system-development-guide.md

@@ -0,0 +1,59 @@
+# Complete System Development Guide
+
+Use this when the user asks for a system, app package, workspace module set, or several related apps/forms.
+Do not compress several business objects into one app.
+
+## Recommended Completeness
+
+Required:
+
+- package exists or is created through `package_apply`
+- core business objects are modeled as separate apps
+- all new apps are created in one multi-app `app_schema_apply(package_id=..., apps=[...])`
+- every app has stable `client_key`, `app_name`, `icon`, `color`, and one readable `as_data_title: true`
+- same-call relations use `target_app_ref` to point to another `apps[].client_key`
+- basic operating views exist for each core app
+- package/apps/fields/relations are read back before repair or retry
+
+Strongly recommended:
+
+- cross-app relation fields for the main business links
+- core metric charts and BI charts using semantic `metric`, `metrics`, `group_by`, and `where`
+- a standard portal: business entry area, core metrics, BI charts, then concrete data views
+- portal grid/business-entry sections contain real `config.items[]`, not empty containers
+
+Optional:
+
+- workflow, reminders, buttons, associated resources, sample data, roles, and permissions when the user asks for them or the business process clearly depends on them
+
+## Standard Path
+
+1. Resolve or create package: `package_get` / `package_apply`.
+2. Draft all apps and relations with stable `client_key` values.
+3. Run one multi-app `app_schema_apply` with `apps[]`.
+4. If write result is uncertain, run readback before retrying.
+5. For each app, apply layout and views.
+6. Create charts before portals when the portal needs metrics or BI sections.
+7. Create portal only after referenced apps, views, and charts are known.
+8. Add workflows/buttons/associated resources when they are part of the requested business process.
+
+## Recovery Rules
+
+- Timeout, `partial_success`, `write_executed=true`, `safe_to_retry=false`, or incomplete readback means `write_may_have_succeeded`.
+- Next action is always `readback_before_retry`: read package, resolve intended apps, then read fields/relations.
+- Retry only verified missing apps, fields, or relations.
+- Do not rebuild the system as separate single-app creates.
+- Do not create `V2`, `测试`, timestamp, or random-suffix apps to bypass duplicate names.
+
+## Portal Template
+
+- Top area: one business entry grid plus one todo/common/frequent component when useful.
+- Metrics: one row of 4-6 indicator/target cards with portal section `role: "metric"`; recommended height 5.
+- BI charts: one row of 2-3 charts, 1-2 rows; recommended height 7.
+- Data views: one row of 1-2 concrete views, 1-2 rows; recommended height 11.
+
+## Stop Conditions
+
+- If the user only asked for one app, switch to the single-app guide.
+- If required package/app/field/relation readback contradicts the intended model, repair the specific missing slice before building dependent resources.
+- If a public tool cannot express a needed business feature, state the gap and ask before using any fallback or submitting feedback.

package/skills/qingflow-app-builder/references/create-app.md

@@ -8,7 +8,7 @@ Do not use this playbook when the user is really asking for a system/package wit
 1. read or create the package through `package_get` / `package_apply`
 2. create the related apps in one `app_schema_apply(package_id=..., apps=[...])` call
 3. keep package ownership on the public `package_id` path instead of a separate attach step
-4. add same-call relation fields with `target_app_ref` when one new app references another new app
+4. add same-call relation fields with `target_app_ref` when one new app references another new app; use `target_app_key` only after the target app already exists or readback confirms it
 5. choose explicit non-template `icon + color` for each new package/app
 
 Hierarchy reminder:
@@ -41,6 +41,8 @@ Use this pattern instead:
 2. for a multi-app system, run one `app_schema_apply` with `package_id` and `apps[]`
 3. use `apps[].client_key` plus relation field `target_app_ref` when one new app references another new app
 
+If that multi-app call times out, returns `partial_success`, returns `write_executed=true`, has `safe_to_retry=false`, or has incomplete readback, do not decide that the create failed. Run `readback_before_retry`: read the package, resolve each intended app by package/name or returned app key, read fields, and retry only verified missing apps or fields. Do not rebuild the same complete system as separate single-app creates, and do not create `V2`, `测试`, timestamp, or random-suffix apps to bypass duplicate names.
+
 ## Example
 
 When designing fields, do not add platform system fields such as `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`. Qingflow provides them automatically; create only business fields.

package/skills/qingflow-app-builder/references/gotchas.md

@@ -17,6 +17,8 @@
 - Another app is not a field
 - If the user names multiple forms/modules that relate to each other, create multiple apps and connect them with relation fields
 - Do not use child app names like “项目/需求/任务/缺陷/团队” as plain text fields inside one app
+- For a complete system, the main creation path is one multi-app `app_schema_apply(package_id=..., apps=[...])` with stable `apps[].client_key` values and same-call relation fields using `target_app_ref`
+- Use `target_app_key` only for an app that already exists or has been confirmed by readback
 
 ## Auto publish
 
@@ -88,7 +90,11 @@
 ## Retry discipline
 
 - If a write returns `partial_success`, read back before retrying
+- If multi-app schema apply times out, returns `write_executed=true`, returns `safe_to_retry=false`, or has incomplete readback, treat it as `write_may_have_succeeded`; the next action is `readback_before_retry`
+- `readback_before_retry` means read package/app/fields first, classify which intended apps and relation fields actually exist, and retry only the verified missing slice
 - Do not repeat create steps after `app_key` already exists
+- Do not split a complete-system schema create into single-app rebuilds until readback proves exactly what is missing
+- Do not bypass duplicate/conflict states by inventing `V2`, `测试`, timestamp, or random-suffix app names in a real business package
 - For backend rejects, keep the retry narrow: retry only the failed tool, not the whole chain
 - For `VALIDATION_ERROR`, do not keep guessing. Reuse `suggested_next_call`, `canonical_arguments`, `allowed_keys`, and `allowed_values` first.
 - For layout `VALIDATION_ERROR`, also inspect `section_allowed_keys`, `section_aliases`, and `minimal_section_example`. If the same layout-shape error repeats twice, stop free-form retries and re-read `builder_tool_contract(app_layout_apply)`.

package/skills/qingflow-app-builder/references/single-app-development-guide.md

@@ -0,0 +1,47 @@
+# Single App Development Guide
+
+Use this when the user asks for one app/form, or gives one `app_key`.
+If the user asks for a package, system, or several related modules, use `complete-system-development-guide.md` instead.
+
+## Recommended Completeness
+
+Required:
+
+- target package/app resolved by `package_get`, `app_resolve`, or `app_get`
+- business fields created or updated through `app_schema_apply`
+- exactly one readable top-level `as_data_title: true`
+- no platform system fields in `add_fields`
+- layout places the important fields
+- at least one business view beyond platform default views when the task includes user-facing list work
+
+Strongly recommended:
+
+- saved filters and query panel fields for the main operating views
+- simple charts when the app has status, amount, date, or owner fields worth tracking
+- associated resources or buttons only when they support a concrete workflow
+
+Optional:
+
+- workflow, portal entry, sample data, roles, or visibility changes when requested by the user or clearly needed by the app's job
+
+## Standard Path
+
+1. Read current target: `app_resolve` or `app_get`.
+2. Read current fields: `app_get_fields`.
+3. Apply fields with `app_schema_apply`.
+4. Apply layout with `app_layout_apply`.
+5. Apply views with `app_views_apply` when list/table/card/gantt behavior is part of the request.
+6. Apply charts/buttons/associated resources only if they are part of the app's actual workflow.
+7. Use `app_publish_verify` only when explicit live verification is required.
+
+## Field Rules
+
+- Use agent-friendly field types where possible: `text`, `multiline`, `select`, `multi_select`, `number`, `amount`, `date`, `datetime`, `member`, `department`, `attachment`, `relation`.
+- Do not create `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`.
+- Do not create built-in default views such as `全部数据` or `我的数据`; Qingflow provides system views.
+
+## Stop Conditions
+
+- If the task actually needs multiple business objects, stop and switch to the complete-system guide.
+- If a write returns `partial_success`, `write_executed=true`, or `safe_to_retry=false`, read back before retrying.
+- If the same validation error repeats twice, re-read `builder_tool_contract` instead of guessing.

package/skills/qingflow-app-builder/references/solution-playbooks.md

@@ -2,6 +2,16 @@
 
 Use these when you need a quick reminder of the standard v2 builder sequences.
 
+## Create a complete system / app package
+
+1. `package_get` or `package_apply`
+2. one multi-app `app_schema_apply(package_id=..., apps=[...])`
+3. use stable `apps[].client_key` values and relation `target_app_ref` for same-call app references
+4. use returned/readback `app_key` values for layout, views, workflow, charts, buttons, associated resources, and portal work
+5. `app_publish_verify` only when the user asks for explicit live verification or a final verification pass is required
+
+If the multi-app schema write times out or returns `partial_success`, `write_executed=true`, `safe_to_retry=false`, or incomplete readback, the next action is `readback_before_retry`: read package/app/fields first, then retry only verified missing pieces. Do not repeat the whole apps payload, split into single-app rebuilds, or create `V2` / `测试` / random-suffix apps to dodge duplicate names.
+
 ## Create a new app in an existing package
 
 1. `package_get`

package/skills/qingflow-app-builder-code-integrations/SKILL.md

@@ -7,6 +7,8 @@ metadata:
 
 # Qingflow App Builder Code Integrations
 
+> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 Use this skill when the user wants to build or repair:
 - `code_block` fields
 - `q_linker` fields

package/skills/qingflow-app-user/SKILL.md

@@ -7,6 +7,8 @@ metadata:
 
 # Qingflow App User
 
+> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## Overview
 
 This skill is a lightweight router for operational Qingflow work.

package/skills/qingflow-mcp-setup/SKILL.md

@@ -7,6 +7,8 @@ metadata:
 
 # Qingflow MCP Setup
 
+> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## Overview
 
 This skill sets up the local Qingflow MCP server, connects it to a local AI client, and verifies authentication and workspace selection. Use it for installation, client configuration, token login, and connection troubleshooting.

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

@@ -7,6 +7,8 @@ metadata:
 
 # Qingflow Record Analysis
 
+> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 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:
@@ -37,7 +39,7 @@ 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. 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.

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

@@ -7,6 +7,8 @@ metadata:
 
 # Qingflow Record Delete
 
+> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## Default Path
 
 `record_list / record_get -> record_delete`

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

@@ -7,6 +7,8 @@ metadata:
 
 # Qingflow Record Import
 
+> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 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

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

@@ -8,6 +8,8 @@ metadata:
 
 # Qingflow Record Insert
 
+> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## Default Path
 
 `record_insert_schema_get -> record_insert(items) -> optional record_get/readback`
@@ -22,6 +24,26 @@ 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:
@@ -72,7 +94,7 @@ Without `record_id` / `workflow_node_id` / `fields-file`, the result is a static
 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
 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
@@ -123,6 +145,7 @@ qingflow --json record insert --app-key APP_KEY --items-file records.json
 - 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 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

@@ -7,6 +7,8 @@ metadata:
 
 # Qingflow Record Update
 
+> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## Default Path
 
 `record_get -> record_update`
@@ -33,6 +35,7 @@ metadata:
 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
 

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

@@ -7,6 +7,8 @@ metadata:
 
 # Qingflow Task Ops
 
+> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## Overview
 
 This skill is for task workflow operations only.