@qingflow-tech/qingflow-cli 1.1.33 → 1.1.34

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/match-rules.md

@@ -1,114 +0,0 @@
-# Builder Match Rules
-
-Use this reference for builder-side field matching rules in custom buttons and associated view/report filters.
-
-This is not the same thing as `record_access` analysis filters or normal view `filters`.
-
-## Where These Rules Apply
-
-- `app_custom_buttons_apply.upsert_buttons[].trigger_add_data_config.field_mappings`
-- `app_custom_buttons_apply.patch_buttons[].set.trigger_add_data_config.field_mappings`
-- `app_associated_resources_apply.upsert_resources[].match_mappings`
-- `app_associated_resources_apply.patch_resources[].set.match_mappings`
-
-Prefer semantic mappings. Do not handwrite raw `que_relation` or `match_rules` unless you are preserving an existing backend config.
-
-## System Fields
-
-System fields can participate in mappings:
-
-- `数据ID`, `row_record_id`, `apply_id`, `_id` -> `field_id=-17`
-  This is the current record's real apply/record ID.
-- `编号`, `数据编号`, `record_number` -> `field_id=0`
-  This is the frontend-visible record number. It may be custom formatted and is not the same as `数据ID`.
-
-Explicit selectors such as `{"field_id": -17}` and `{"field_id": 0}` are allowed and remove ambiguity.
-
-## Custom Buttons
-
-Use `field_mappings` for dynamic values copied from the current source record:
-
-```json
-{
-  "target_app_key": "WORKLOG_APP",
-  "field_mappings": [
-    {"source_field": "数据ID", "target_field": "关联员工"},
-    {"source_field": "员工名称", "target_field": "员工姓名"}
-  ],
-  "default_values": {
-    "状态": "待提交"
-  }
-}
-```
-
-Use `default_values` only for static constants. Do not use `default_values` as the preferred way to pass the current record.
-
-For an existing button, put the same semantic config under `patch_buttons[].set`:
-
-```json
-{
-  "button_id": 3858041,
-  "set": {
-    "trigger_add_data_config": {
-      "target_app_key": "WORKLOG_APP",
-      "field_mappings": [
-        {"source_field": "数据ID", "target_field": "关联员工"}
-      ],
-      "default_values": {
-        "状态": "待提交"
-      }
-    }
-  }
-}
-```
-
-## Associated Resources
-
-Use `match_mappings` for associated view/report filters:
-
-```json
-{
-  "graph_type": "view",
-  "target_app_key": "WORKLOG_APP",
-  "view_key": "WORKLOG_VIEW",
-  "match_mappings": [
-    {"target_field": "关联员工", "source_field": "数据ID"},
-    {"target_field": "状态", "value": "待提交"}
-  ]
-}
-```
-
-Dynamic conditions use `source_field`; static conditions use `value`.
-
-For an existing associated resource, put the same filter mapping under `patch_resources[].set`:
-
-```json
-{
-  "associated_item_id": 3497587,
-  "set": {
-    "match_mappings": [
-      {"target_field": "关联员工", "source_field": "数据ID"}
-    ]
-  }
-}
-```
-
-## Type Compatibility
-
-- Relation fields: match another relation field with the same target app, or match `数据ID(-17)` when the target relation points to the current source app.
-- Record ID `数据ID(-17)`: can match relation fields that point to the current source app, or ID-compatible text/number fields.
-- Record number `编号(0)`: can match text, long text, number, amount, or another record-number field.
-- Member fields: only match member fields.
-- Department fields: only match department fields.
-- Option fields: single select, multi select, and boolean can match option-family fields or static option values.
-- Date fields: date and datetime can match each other.
-- Text fields: text, long text, phone, and email can match each other.
-- Number fields: number and amount can match each other.
-- Attachment, subtable, code block, Q-Linker, and address fields are not default match fields.
-
-## Error Interpretation
-
-- Field not found: re-read `app_get` or `app_get_fields` and retry with an exact title or `field_id`.
-- Type mismatch: choose a compatible source/target pair from the matrix above.
-- Reference source mismatch: the target relation field points to a different app; choose a relation field that points back to the current source app, or match a non-relation field.
-- Mixed raw and semantic modes: use either semantic `field_mappings/match_mappings` or raw `que_relation/match_rules`, never both in the same item.

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/public-surface-sync.md

@@ -1,75 +0,0 @@
-# Qingflow Core Public Surface Sync
-
-Use this file as the maintenance baseline for the core Qingflow skills.
-It is not a user-facing product spec. It exists to prevent skill drift.
-
-## Current Public Defaults
-
-### User data
-
-- Read range first with `app_get`, then `record_browse_schema_get(view_id=...)`
-- Treat `record_browse_schema_get.fields` as the selected Qingflow table view header schema; `record_access.fields` and `record_list` field selectors must stay aligned with it.
-- Standard flows:
-  - analyze: `app_get -> record_browse_schema_get -> record_access -> Python`
-  - browse detail: `app_get -> record_browse_schema_get -> record_list / record_get`
-  - explicit export/download/Excel: `app_get -> choose view_id -> view_get -> record_export_*` or `record_export_direct`; export tools require explicit `view_id`
-  - insert: `record_insert_schema_get -> record_insert(items)`
-  - update: `record_get -> record_update`; use `record_update_schema_get` only for failure diagnosis or ambiguous writable-field routing
-
-### Tasks
-
-- Discovery stays on `task_list`
-- `task_list --query` uses backend search first and only applies local fallback when backend returns zero rows
-- Public actions are:
-  - `approve`
-  - `reject`
-  - `rollback`
-  - `transfer`
-  - `urge`
-  - `save_only`
-- `reject` requires `payload.audit_feedback`
-- `save_only` requires non-empty `fields`
-- `TASK_RUNTIME_CONSUMED_AFTER_ACTION` is a normal post-success warning when the current node runtime is consumed and `46001` appears on re-read
-
-### Builder
-
-- Official package entry: `package_get`, `package_apply`
-- Official builder writes:
-  - `app_schema_apply`
-  - `app_layout_apply`
-  - `app_flow_apply`
-  - `app_views_apply`
-  - `app_custom_buttons_apply`
-  - `app_associated_resources_apply`
-  - `app_charts_apply`
-  - `portal_apply`
-  - `app_publish_verify`
-- `portal_apply` edit mode may omit `sections` for base-info-only updates
-- `app_charts_apply.visibility` is a public capability and should be treated as a base-only visibility update
-- Existing object parameter replacement should use `patch_views`, `patch_buttons`, `patch_resources`, and `patch_charts`; `upsert_*` is for creation or full target config
-- `app_get.editability` uses:
-  - `can_edit_app_base`
-  - `can_edit_form`
-  - `can_edit_flow`
-  - `can_edit_views`
-  - `can_edit_charts`
-
-## Known High-Drift Areas
-
-- Task actions, especially `save_only`, reject payload requirements, and `46001` post-action interpretation
-- Package public tools: do not regress to `package_create` / `package_attach_app` as the public default story
-- App editability: do not let `can_edit_form` imply app base-info writes
-- Portal and chart visibility: keep the public story on `portal_apply` / `app_charts_apply`, not low-level internal writes
-- Analysis path: standard path stays `record_access -> Python`
-
-## Release Checklist For Skill Maintenance
-
-After each beta that changes public behavior, re-check:
-
-1. `public_surface.py`
-2. `README.md`
-3. `server_app_builder.py` and `server.py` top-level guidance
-4. CLI help for `task`, `builder package`, `builder portal`, `builder charts`
-5. Whether new warnings or verification fields need to be explained in skills
-
-If a tool behavior changed but the public surface did not, prefer updating the relevant skill section instead of expanding this file.

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/single-app-development-guide.md

@@ -1,69 +0,0 @@
-# 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
-- 1-3 concrete business buttons on core operating views through `app_views_apply.action_buttons`, when the view has real actions
-- simple charts when the app has status, amount, date, or owner fields worth tracking
-- associated resources or advanced standalone 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
-
-Workflow schema prerequisites:
-
-- If the app will have approval/fill/copy workflow nodes, add one explicit business status `select` field first, such as `状态`, `处理状态`, `审批状态`, `工单状态`, or `流程阶段`.
-- Do not create platform workflow system fields: `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`.
-
-## 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; declare ordinary business buttons in `action_buttons` while designing the view.
-6. Apply charts/associated resources/advanced standalone buttons 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.
-
-## View Query Rules
-
-- `filters` are fixed saved filters; `query_conditions` only configures frontend query-panel fields.
-- Put only query-panel fields in `query_conditions.rows`: text, long text, number, amount, date/datetime, select, member, department, phone, email, or boolean.
-- Do not put relation, attachment, subtable/subfield, address, Q-Linker, or code-block fields in `query_conditions`; use fixed `filters` or associated-resource `match_mappings` instead.
-
-## Button Rules
-
-- Use `action_buttons` for ordinary buttons tied to one view.
-- Use `app_custom_buttons_apply` only for style/icon changes, cross-view reuse, deleting button bodies, bulk binding reorder, or exact qRobot/wings configs.
-- Use `add_data` when a current record creates a downstream/child record; configure `target_app_key + field_mappings`, usually mapping `source_field: "数据ID"` to the target relation/reference field.
-- Use `link` only for SOP, help, external system, or fixed URL navigation. Do not use it to fake approval, status transition, or data writeback.
-- Use `qRobot`/`wings` only when the user provides exact existing automation config.
-- Prefer `detail` for current-record add-data actions, `list` for row actions, and `header` for global actions with no current-row context. Do not use current-record `field_mappings` on `header`.
-- Approval, rejection, close-task, and status transition should be workflow/task behavior or existing automation; they are not generic custom-button types.
-
-## 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 `qingflow --json builder contract` instead of guessing.

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/solution-playbooks.md

@@ -1,52 +0,0 @@
-# Builder Playbooks
-
-Use these when you need a quick reminder of the standard v2 builder sequences.
-
-## Create a new app in an existing package
-
-1. `package_get`
-2. `app_resolve`
-3. `app_schema_apply`
-5. `app_publish_verify` only if the user asks for explicit live verification
-
-## Update fields on an existing app
-
-1. `app_resolve`
-2. `app_get_fields`
-3. `app_schema_apply`
-
-## Rework layout
-
-1. `app_get_layout`
-2. `app_layout_apply`
-
-Prefer `mode=merge`. Use `mode=replace` only when every field placement is intentional.
-
-## Add or update workflow
-
-1. `app_get_fields`
-2. `app_get_flow`
-3. `role_search` or `member_search`
-4. `role_create` if the business wants a reusable role and no good exact role exists
-5. `app_flow_apply`
-
-If `app_flow_apply` reports `FLOW_DEPENDENCY_MISSING`, fix schema first.
-If it reports `FLOW_ASSIGNEE_REQUIRED`, resolve roles or members first and retry with canonical `assignees.*`.
-
-## Add or update views
-
-1. `app_get_fields`
-2. `app_get_views`
-3. `app_views_apply`
-
-For both workflow and view work, prefer `suggested_next_call` over re-guessing arguments after a validation failure.
-
-## Final readback
-
-Prefer these fields after writes:
-
-- `app_get.tag_ids`
-- `app_get.publish_status`
-- `app_get_layout.unplaced_fields`
-- `app_get_views.views`
-- `app_get_flow.nodes`

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/tool-selection.md

@@ -1,113 +0,0 @@
-# Tool Selection
-
-Legacy reference only. For current single-app and complete-system builds, use
-`../../10-build-single-app.md` and `../../20-build-complete-system.md` first.
-Do not copy legacy `create_if_missing`, explicit `*_plan`, or preflight-first
-examples into the main path.
-
-## Default path
-
-`summary read -> apply -> publish_verify`
-
-Public builder `apply` tools submit after local contract normalization. Reuse,
-same-name handling, whether to ask the user, and other business decisions belong
-in the skills before apply. Do not route normal public builder work through
-explicit `*_plan` tools.
-
-## Hierarchy first
-
-Before picking tools, decide which layer the request targets:
-
-- `package`: a solution/app bundle like “研发项目管理” or “费控管理系统”
-- `app`: one form/app inside that package
-- `field`: one field inside one app
-- `relation`: a field that links two apps
-
-If the user asks for multiple forms/modules that relate to each other, this is a package-level multi-app task, not a single-app create.
-
-## Resolve
-
-- `package_get`: read one known package by `package_id`
-- `package_apply`: create or update one package by direct create/update intent; do not add `create_if_missing`
-- `member_search`: resolve named people from the directory
-- `role_search`: resolve reusable roles from the directory
-- `role_create`: create a reusable role when the business owner wants role-based routing
-- `app_resolve`: locate an existing app by exactly one selector mode: `app_key`, or `app_name + package_id`
-
-## Summary reads
-
-All `app_get_*` tools accept either `app_key` (single) or `app_keys[]` (batch). Batch returns `{status, apps[], errors[]}` — prefer batch when reading multiple apps in one step.
-
-- `app_get`: overall app config health, publish state, counts, and builder editability
-- `app_get_fields`: field names, types, required flags, section ids
-- `app_get_layout`: sections, rows, unplaced fields
-- `app_get_views`: current view names, types, columns, group-by
-- `app_get_flow`: workflow enabled state, full spec (nodes + transitions)
-- `app_get_charts`: current chart ids, names, types, order
-- `app_get_buttons`: current custom button list (draft state)
-- `app_get_associated_resources`: current associated resource pool (draft state)
-- `app_publish_verify`: publish state and package tag verification — accepts `app_keys[]` for multi-app batch
-- `portal_get`: current portal config detail and component inventory
-
-## Apply tools
-
-These execute normalized patches. Some app apply tools publish by default and still accept `publish=false`; custom button and associated-resource apply publish after at least one write succeeds and do not expose that switch.
-
-- `app_schema_apply`: create app shell or change fields
-- `app_layout_apply`: merge or replace layout; use `apps[]` (each item `{app_key, mode?, sections}`) for multi-app batch
-- `app_flow_apply`: replace full workflow spec; use `patch_nodes[]` (`{id, set, unset}`) to update specific nodes without rewriting the full spec
-- `app_views_apply`: use `patch_views` for existing-view parameter replacement; use `upsert_views` for creation or full target config; remove views by key; for normal view-specific business buttons, declare `action_buttons` in the view object or `patch_views[].set`; new views default associated report/view display to visible with `limit_type="all"`; use `apps[]` for multi-app batch
-- `app_custom_buttons_apply`: advanced custom-button maintenance only: style/icon changes, cross-view reuse, deleting button bodies, bulk reordering bindings, or exact qRobot/wings configs. Use `patch_buttons` for existing-button parameter replacement; use `upsert_buttons` for creation or full target config; bind buttons to header/detail/list view positions; `placement=list` maps to the backend `INSIDE` row/list button position; merge-mode view configs require `buttons`; use `view_configs[].mode="replace"` or `buttons=[]` to clear a view's custom button bindings. For child-record creation linked to the current source record, map `source_field: "数据ID"` to the target relation field; do not put current-record `field_mappings` on `header`. Approval/status transition/close task is not a generic custom-button action; use workflow/task behavior or exact user-provided automation config. Use `apps[]` for multi-app batch.
-- `app_associated_resources_apply`: attach existing BI reports/views to the Qingflow app associated-resource pool and per-view display area; it does not create or edit QingBI report bodies/configs. Use `patch_resources` for existing associated-resource parameter replacement; use `upsert_resources` for creation or full target config; `view_configs`, remove, and reorder may reference existing resources by internal `associated_item_id` or by `chart_id`/`chart_key`/`view_key`; use `match_mappings` for associated view/report filters; publishes after successful writes; omit raw `sourceType`, and use `report_source="dataset"` only to attach an existing BI dataset report. Before `upsert_resources`, read `app_get.associated_resources` and reuse an existing matching `target_app_key + view_key/chart_key`; repeated upsert can create duplicates because `client_key` is only valid inside one apply call. Use `apps[]` for multi-app batch.
-- `app_charts_apply`: create/edit/remove/reorder app-source QingBI report bodies/configs with `dataSourceType=qingflow`; it does not create/edit dataset BI reports and does not attach reports to Qingflow app associated-resource display. Use semantic `metric`, `metrics`, `group_by`, and `where`: `target/indicator` for one KPI, `bar/columnar/pie` for distribution, `line/area` for trend, `table/detail/summary` for tabular summaries, and `dualaxes` for two-metric comparison. Use `patch_charts` for existing-chart parameter replacement; use `upsert_charts` for creation or full target config; avoid raw `indicator_field_ids`, `selectedMetrics`, and QingBI filter matrices on the main path; charts are immediate-live and do not publish; use `chart_id` when names are not unique; use `apps[]` for multi-app batch
-- `portal_apply`: create or replace-update portal pages; use `dash_key` for update mode or `package_id + dash_name` for create mode; edit mode may omit `sections` for base-info-only updates; when sections are supplied they still use replace semantics; sections use a 24-column PC grid — all components in the same row (same `y`) must share the same `rows` value and their `cols` must sum to exactly 24; mismatched `rows` causes height misalignment, `cols` under 24 leaves trailing blank space; standard workbench heights are metric cards `rows=5`, BI charts `rows=7`, data views `rows=11`; business-entry grids must include real `config.items[]`; use `patch_sections[]` (`{chart_ref/view_ref/order, set, unset}`) to update individual sections without replacing all
-
-For object-level updates, the safe partial syntax is `patch_*` with the object's real selector field plus `set` and optional `unset`. `selector` is only a concept, not a literal key. Examples: `patch_views: [{"view_key": "VIEW_KEY", "set": {...}}]`, `patch_buttons: [{"button_id": 1001, "set": {...}}]`, `patch_resources: [{"associated_item_id": 123, "set": {...}}]`, `patch_charts: [{"chart_id": 456, "set": {...}}]`, `patch_nodes: [{"id": "approve_1", "set": {...}}]`, `patch_sections: [{"chart_ref": {"chart_key": "ck_001"}, "set": {"title": "新标题"}}]`. The tool reads the current backend config, merges the patch, then submits the full backend payload internally. Do not send a partial `upsert_*` and expect missing required fields to be preserved.
-
-## Explicit post-apply tools
-
-- `app_publish_verify`: explicit final publish verification when the user asks for live confirmation
-
-## Decision shortcuts
-
-- Create one app inside an existing package:
-  `package_get -> app_resolve -> app_schema_apply`
-- Create a brand new package, then create one app in it:
-  `package_apply(package_name + icon + color) -> app_schema_apply`
-- Create a brand new multi-app system/package:
-  `package_apply(package_name + icon + color) -> app_schema_apply(apps[])`
-- Update fields on an existing app:
-  `app_resolve -> app_get_fields -> app_schema_apply`
-- Tidy layout:
-  `app_get_fields -> app_get_layout -> qingflow --json builder contract (if shape is unclear) -> app_layout_apply`
-- Add workflow:
-  `qingflow --json builder contract -> app_get_fields -> app_get_flow -> role_search/member_search -> app_flow_apply -> app_get_flow`
-- Update specific flow nodes:
-  `app_get_flow -> app_flow_apply.patch_nodes[]`
-- Add views:
-  `qingflow --json builder contract -> app_get_fields -> app_get_views -> app_views_apply.patch_views/upsert_views -> app_get_views`
-- Add QingBI charts:
-  `qingflow --json builder contract -> app_get_fields -> app_get_charts -> app_charts_apply.patch_charts/upsert_charts -> app_get_charts`
-- Show an existing QingBI chart inside a Qingflow app/view:
-  `app_get -> app_associated_resources_apply.upsert_resources/patch_resources + view_configs -> app_get`
-- Create or update a portal:
-  `qingflow --json builder contract -> portal_get -> portal_apply -> portal_get`
-- Update portal section(s) without replacing all:
-  `portal_get -> portal_apply.patch_sections[]`
-
-## Avoid
-
-- Do not handcraft raw Qingflow schema payloads
-- Do not rely on internal `solution_*` tools in public builder flows
-- Do not create a new package without first asking the user to confirm package creation
-- Do not regress to `package_create` or `package_attach_app` as the public default story
-- Do not treat a package/system name as `app_name` when the user clearly wants multiple apps inside it
-- Do not compress multiple business objects into one app with several text fields
-- Do not skip summary reads before flow or view work
-- Do not emit `column_names`; always use `columns`
-- Do not model layout shape with `fields`, `field_ids`, or top-level `columns`; custom layout sections should be `title + rows`
-- Do not reuse internal flow keys such as `role_entries` or `editable_que_ids` in public builder calls
-- Do not pass natural-language preset guesses such as `default_approval`; map them to canonical preset values first
-- Do not omit assignees on approval/fill/copy nodes
-- Do not patch preset flows with brand new approval/fill node ids unless you are intentionally replacing the skeleton; reuse preset ids like `approve_1` and `fill_1`
-- Do not guess role ids, member ids, or editable field ids; resolve names first

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/update-flow.md

@@ -1,7 +0,0 @@
-# Legacy Redirect: Update Flow
-
-This historical playbook is no longer a main entry point.
-
-For current workflow creation, patching, and verification, read [../../90-workflow.md](../../90-workflow.md).
-
-Reason: update behavior belongs inside the resource document. Route by target resource first, not by the generic word "update".

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/update-layout.md

@@ -1,7 +0,0 @@
-# Legacy Redirect: Update Layout
-
-This historical playbook is no longer a main entry point.
-
-For current form layout creation and update work, read [../../40-layout.md](../../40-layout.md).
-
-Reason: update behavior belongs inside the resource document. Route by target resource first, not by the generic word "update".

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/update-schema.md

@@ -1,7 +0,0 @@
-# Legacy Redirect: Update Schema
-
-This historical playbook is no longer a main entry point.
-
-For current field creation and update work, read [../../30-schema-fields.md](../../30-schema-fields.md).
-
-Reason: update behavior belongs inside the resource document. Route by target resource first, not by the generic word "update".

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/update-views.md

@@ -1,7 +0,0 @@
-# Legacy Redirect: Update Views
-
-This historical playbook is no longer a main entry point.
-
-For current view creation, filtering, query panels, and patching, read [../../50-views.md](../../50-views.md).
-
-Reason: update behavior belongs inside the resource document. Route by target resource first, not by the generic word "update".