@qingflow-tech/qingflow-cli 1.1.33 → 1.1.34

package/src/qingflow_mcp/cli/commands/builder.py

@@ -255,10 +255,10 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     flow_apply_apply = flow_apply_subparsers.add_parser("apply", help="执行流程变更")
     flow_apply_apply.add_argument("--app-key", required=True)
-    flow_apply_apply.add_argument("--mode", choices=["replace"], default="replace")
+    flow_apply_apply.add_argument("--mode", choices=["replace"], default="replace", help=argparse.SUPPRESS)
     flow_apply_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
-    flow_apply_apply.add_argument("--nodes-file")
-    flow_apply_apply.add_argument("--transitions-file")
+    flow_apply_apply.add_argument("--nodes-file", help=argparse.SUPPRESS)
+    flow_apply_apply.add_argument("--transitions-file", help=argparse.SUPPRESS)
     flow_apply_apply.add_argument("--spec-file")
     flow_apply_apply.add_argument("--patch-nodes-file", help="节点局部更新 JSON 数组，每项含 id + set/unset")
     flow_apply_apply.add_argument("--idempotency-key", default="")
@@ -855,11 +855,18 @@ def _handle_flow_apply(args: argparse.Namespace, context: CliContext) -> dict:
     patch_nodes = load_list_arg(getattr(args, "patch_nodes_file", None), option_name="--patch-nodes-file")
     spec = load_object_arg(getattr(args, "spec_file", None), option_name="--spec-file")
     has_legacy_nodes = bool(getattr(args, "nodes_file", None) or getattr(args, "transitions_file", None))
+    if has_legacy_nodes:
+        raise_config_error(
+            "builder flow apply no longer exposes legacy --nodes-file/--transitions-file input.",
+            fix_hint="Use --spec-file for a complete WorkflowSpec, or --patch-nodes-file for targeted edits after builder flow get.",
+            error_code="FLOW_LEGACY_INPUT_DISABLED",
+            details={"allowed_input_modes": ["--spec-file", "--patch-nodes-file"]},
+        )
     selected_modes = sum(1 for selected in (bool(patch_nodes), bool(spec), has_legacy_nodes) if selected)
     if selected_modes != 1:
         raise_config_error(
-            "builder flow apply requires exactly one input mode: --spec-file, --patch-nodes-file, or --nodes-file with --transitions-file.",
-            fix_hint="Use --patch-nodes-file for local edits, --spec-file for full WorkflowSpec, or legacy --nodes-file plus --transitions-file.",
+            "builder flow apply requires exactly one input mode: --spec-file or --patch-nodes-file.",
+            fix_hint="Use --spec-file for a complete WorkflowSpec, or --patch-nodes-file for targeted edits after builder flow get.",
         )
     if patch_nodes:
         return context.builder.app_flow_apply(
@@ -879,18 +886,9 @@ def _handle_flow_apply(args: argparse.Namespace, context: CliContext) -> dict:
             idempotency_key=args.idempotency_key,
             schema_version=args.schema_version,
         )
-    if not getattr(args, "nodes_file", None) or not getattr(args, "transitions_file", None):
-        raise_config_error(
-            "legacy builder flow apply requires both --nodes-file and --transitions-file.",
-            fix_hint="Pass both files, or use --spec-file / --patch-nodes-file.",
-        )
-    return context.builder.app_flow_apply(
-        profile=args.profile,
-        app_key=args.app_key,
-        mode=args.mode,
-        publish=bool(args.publish),
-        nodes=require_list_arg(args.nodes_file, option_name="--nodes-file"),
-        transitions=require_list_arg(args.transitions_file, option_name="--transitions-file"),
+    raise_config_error(
+        "builder flow apply requires --spec-file or --patch-nodes-file.",
+        fix_hint="Use --spec-file for a complete WorkflowSpec, or --patch-nodes-file for targeted edits after builder flow get.",
     )
 
 

package/src/qingflow_mcp/server_app_builder.py

@@ -52,7 +52,7 @@ def build_builder_server() -> FastMCP:
             "For associated reports/views, use app_associated_resources_apply for both the app-level associated_resources pool and per-view display config; associated_item_id is the app-level form_asos_chart.id, and view_configs/remove/reorder may also pass an existing resource's chart_id/chart_key/view_key because the tool resolves those to the internal id. Before creating an associated resource, read app_get.associated_resources and reuse an existing matching target_app_key + view_key/chart_key through patch_resources; client_key only works inside one apply call and is not persisted. Do not ask agents to pass backend raw sourceType: views infer the internal Qingflow view source, reports default to BI app reports, and dataset reports use report_source=dataset. "
             "For code_block fields with output bindings, always use qf_output assignment rather than const/let qf_output, and use app_repair_code_blocks when an existing form hangs because output-bound fields stay loading. "
             "Use package_apply to manage package metadata, visibility, grouping, and ordering, and app_publish_verify for explicit final publish verification. "
-            "For workflow edits, use app_flow_get_schema/app_flow_get when raw WorkflowSpec shape is needed, then app_flow_apply with spec for full replacement or patch_nodes for targeted node edits; the legacy nodes/transitions path is only for simple linear start/approve/fill/copy/webhook/end flows. Declare node assignees and editable fields explicitly. "
+            "For workflow edits, use app_flow_get_schema/app_flow_get when raw WorkflowSpec shape is needed, then app_flow_apply with spec for full replacement or patch_nodes for targeted node edits. Declare node assignees and editable fields explicitly. "
             "If builder writes are blocked by the current user's own edit lock, use app_release_edit_lock_if_mine with the lock owner details from the failed result. "
             "Do not handcraft internal solution payloads or rely on build_id/stage/repair. "
             "If the current MCP capability is unsupported, the workflow is awkward, or the user's need still cannot be satisfied after reasonable use, first summarize the gap, ask whether to submit feedback, and call feedback_submit only after explicit user confirmation."
@@ -513,10 +513,7 @@ def build_builder_server() -> FastMCP:
     def app_flow_apply(
         profile: str = DEFAULT_PROFILE,
         app_key: str = "",
-        mode: str = "replace",
         publish: bool = True,
-        nodes: list[dict] | None = None,
-        transitions: list[dict] | None = None,
         spec: dict | None = None,
         idempotency_key: str = "",
         schema_version: str = "",
@@ -525,10 +522,7 @@ def build_builder_server() -> FastMCP:
         return ai_builder.app_flow_apply(
             profile=profile,
             app_key=app_key,
-            mode=mode,
             publish=publish,
-            nodes=nodes or [],
-            transitions=transitions or [],
             spec=spec,
             idempotency_key=idempotency_key or None,
             schema_version=schema_version or None,

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -720,10 +720,7 @@ class AiBuilderTools(ToolBase):
         def app_flow_apply(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            mode: str = "replace",
             publish: bool = True,
-            nodes: list[JSONObject] | None = None,
-            transitions: list[JSONObject] | None = None,
             spec: JSONObject | None = None,
             idempotency_key: str = "",
             schema_version: str = "",
@@ -732,10 +729,7 @@ class AiBuilderTools(ToolBase):
             return self.app_flow_apply(
                 profile=profile,
                 app_key=app_key,
-                mode=mode,
                 publish=publish,
-                nodes=nodes or [],
-                transitions=transitions or [],
                 spec=spec,
                 idempotency_key=idempotency_key or None,
                 schema_version=schema_version or None,
@@ -3573,7 +3567,7 @@ class AiBuilderTools(ToolBase):
         *,
         profile: str,
         app_key: str,
-        mode: str = "replace",
+        mode: str | None = None,
         publish: bool = True,
         nodes: list[JSONObject] | None = None,
         transitions: list[JSONObject] | None = None,
@@ -3625,29 +3619,37 @@ class AiBuilderTools(ToolBase):
                 normalized_args=normalized_args,
                 suggested_next_call={"tool_name": "app_flow_get", "arguments": {"profile": profile, "app_key": app_key}},
             ))
-        effective_nodes = nodes or []
-        effective_transitions = transitions or []
-        result = self._app_flow_apply_once(
-            profile=profile,
-            app_key=app_key,
-            mode=mode,
-            publish=publish,
-            nodes=effective_nodes,
-            transitions=effective_transitions,
-        )
-        result = self._retry_after_self_lock_release(
-            profile=profile,
-            result=result,
-            retry_call=lambda: self._app_flow_apply_once(
+        if nodes or transitions:
+            effective_nodes = nodes or []
+            effective_transitions = transitions or []
+            result = self._app_flow_apply_once(
                 profile=profile,
                 app_key=app_key,
-                mode=mode,
+                mode=mode or "replace",
                 publish=publish,
                 nodes=effective_nodes,
                 transitions=effective_transitions,
-            ),
-        )
-        return _attach_builder_apply_envelope("app_flow_apply", result)
+            )
+            result = self._retry_after_self_lock_release(
+                profile=profile,
+                result=result,
+                retry_call=lambda: self._app_flow_apply_once(
+                    profile=profile,
+                    app_key=app_key,
+                    mode=mode or "replace",
+                    publish=publish,
+                    nodes=effective_nodes,
+                    transitions=effective_transitions,
+                ),
+            )
+            return _attach_builder_apply_envelope("app_flow_apply", result)
+        normalized_args = {"app_key": app_key, "publish": publish}
+        return _attach_builder_apply_envelope("app_flow_apply", _failed(
+            "FLOW_SPEC_OR_PATCH_REQUIRED",
+            "app_flow_apply requires spec for a complete WorkflowSpec write or patch_nodes for targeted edits.",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_flow_get_schema", "arguments": {"profile": profile}},
+        ))
 
     def _app_flow_apply_once(
         self,
@@ -7731,7 +7733,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "approve/fill/copy nodes require at least one assignee",
         ],
         "execution_notes": [
-            "app_flow_plan is a legacy helper for linear public node aliases; use app_flow_get/app_flow_get_schema plus app_flow_apply spec or patch_nodes for the full WorkflowSpec path",
+            "app_flow_plan is private compatibility plumbing, not an agent-facing workflow path; use app_flow_get/app_flow_get_schema plus app_flow_apply spec or patch_nodes",
             "do not create platform system workflow fields such as 当前流程状态 / 当前处理人 / 当前处理节点 / 流程标题; use an explicit business status field instead",
         ],
         "minimal_example": {
@@ -7759,35 +7761,22 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "patch_nodes",
             "idempotency_key",
             "schema_version",
-            "mode",
-            "nodes",
-            "transitions",
         ],
         "aliases": {
-            "overwrite": "replace",
             "patchNodes": "patch_nodes",
             "idempotencyKey": "idempotency_key",
             "schemaVersion": "schema_version",
-            "node.role_names": "node.assignees.role_names",
-            "node.role_ids": "node.assignees.role_ids",
-            "node.member_names": "node.assignees.member_names",
-            "node.member_emails": "node.assignees.member_emails",
-            "node.member_uids": "node.assignees.member_uids",
-            "node.editable_fields": "node.permissions.editable_fields",
-        },
-        "allowed_values": {
-            "mode": ["replace"],
-            "node.type": PUBLIC_STABLE_FLOW_NODE_TYPES,
         },
+        "allowed_values": {},
         "dependency_hints": [
             "approval-style workflows require an explicit business status select field before app_flow_apply, such as 状态 / 处理状态 / 审批状态 / 工单状态",
-            "approve/fill/copy nodes require at least one assignee",
+            "WorkflowSpec nodes should declare sync=true for routing nodes and explicit assignees for approval/filling/cc nodes",
         ],
         "execution_notes": [
             "preferred full workflow path is app_flow_get_schema/app_flow_get -> app_flow_apply with spec",
             "use patch_nodes for targeted existing-node edits; each item uses id plus set/unset",
-            "legacy nodes/transitions remains available for simple linear start/approve/fill/copy/webhook/end flows only",
-            "do not mix spec, patch_nodes, and legacy nodes/transitions in one call",
+            "public workflow writes use only spec or patch_nodes",
+            "do not mix spec and patch_nodes in one call",
             "do not create platform system workflow fields such as 当前流程状态 / 当前处理人 / 当前处理节点 / 流程标题; use an explicit business status field instead",
             "workflow readback is app_flow_get; use app_flow_get_schema when raw spec shape is unclear",
         ],
@@ -7803,14 +7792,6 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "publish": True,
             "patch_nodes": [{"id": "approve_1", "set": {"name": "主管审批"}}],
         },
-        "legacy_linear_example": {
-            "profile": "default",
-            "app_key": "APP_KEY",
-            "mode": "replace",
-            "publish": True,
-            "nodes": [{"id": "start", "type": "start", "name": "发起"}, {"id": "end", "type": "end", "name": "结束"}],
-            "transitions": [{"from": "start", "to": "end"}],
-        },
     },
     "app_views_plan": {
         "allowed_keys": [

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

@@ -1,308 +0,0 @@
-# Qingflow CLI App Builder Playbooks
-
-## Overview
-
-This section is for the current **public builder surface** through `qingflow builder ...`, not for legacy low-level builder writes.
-
-Before any write or verification flow, identify whether the task targets `test` or `prod` and read [environments.md](./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](./public-surface-sync.md).
-
-## CLI-only Execution Rule
-
-Examples in this directory are CLI payload examples and workflow notes. Execute through the matching `qingflow` command from [SKILL.md](../../../../SKILL.md), the command index, or the canonical builder reference files; do not call internal tool JSON.
-
-## Current Public Mental Model
-
-Model builder requests in four layers and keep them separate:
-
-- `package`: the app bundle or solution container
-- `app`: one form/app inside that package
-- `field`: one field inside one app
-- `relation`: a field that links one app to another app
-
-Default modeling rules:
-
-- One business object -> one app
-- Attributes of that object -> fields inside that app
-- Another business object -> a separate app, not a text field
-- Cross-object links -> relation fields, not text fields
-
-## Public Tools You Should Think In
-
-- Package: `qingflow builder package get/apply`
-- App reads: `qingflow builder app resolve/get`, including batch `--app-keys`
-- Builder reads: `qingflow builder portal/view/chart/contract`
-- Directory: `qingflow builder member/role`
-- Writes: `qingflow builder schema/layout/flow/views/button/associated-resource/charts/portal apply`
-- Verification: `qingflow builder publish verify`
-
-Treat these as the official surface. Do not default to `package_create`, `package_attach_app`, raw `portal_*` writes, or raw `qingbi_report_*` writes.
-
-## Current Public Defaults
-
-- Package work:
-  - use `package_get(package_id=...)` to read one known package
-  - use `package_apply(...)` for package creation, rename, icon, visibility, grouping, ordering, and app/portal layout
-- Multi-app schema work:
-  - use one CLI `builder schema apply --apps-file` when creating several apps in one package
-  - same-call relation fields may use `target_app_ref` to point at another `apps[].client_key`
-- Batch reads:
-  - `builder app get`, `button get`, `associated-resource get`, and `publish verify` accept `--app-keys`
-  - when reading several apps, prefer one batch read and inspect both `apps[]` and `errors[]`
-- Batch writes:
-  - `builder layout/views/button/associated-resource/charts apply --apps-file` accepts multi-app batch writes
-  - each `apps[]` item carries its own `app_key` plus that tool's normal single-app payload
-- 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
-- Partial update rule:
-  - for existing views, custom buttons, associated resources, and charts, prefer `patch_views` / `patch_buttons` / `patch_resources` / `patch_charts`
-  - for existing workflow nodes, use `builder flow apply --patch-nodes-file` instead of rewriting the full `spec`
-  - for existing portal sections, use `builder portal apply --patch-sections-file` instead of replacing all `sections`
-  - each patch item uses the object's real selector field (`view_key` / `button_id` / `associated_item_id` / `chart_id`, or unique name where supported) plus `set` and optional `unset`; do not send a literal `selector` key for these tools
-  - use `upsert_*` for creation or full target configuration; do not send a partial `upsert_*` and expect the backend to merge missing required fields
-- Portal work:
-  - `portal_apply` is the public write path
-  - in edit mode, omitting `sections` means “preserve existing layout and update base info only”
-  - supplying `sections` means full replace semantics for sections
-  - portal sections use a 24-column PC grid; all components sharing the same `y` coordinate must have identical `rows` values and their `cols` must sum to exactly 24; mixing `rows` in the same row causes height misalignment, and a `cols` sum under 24 leaves blank space at the row end; the next row's `y` must equal the previous row's `y` + `rows`
-  - standard workbench heights: metric cards `rows=5`, BI charts `rows=7`, data views `rows=11`
-  - business-entry grid sections must include real `config.items[]`; do not submit an empty grid container
-- Chart work:
-  - `app_charts_apply` is the public write path for app-source QingBI report bodies/configs; it creates/updates reports with `dataSourceType=qingflow`
-  - dataset BI reports are not created or edited by `app_charts_apply` yet; create them in QingBI first, then attach the existing report with `app_associated_resources_apply` and `report_source="dataset"`
-  - it does not attach the report to the Qingflow app associated-resource display; use `app_associated_resources_apply` for that
-  - choose chart type by goal: `target/indicator` for one KPI, `bar/columnar/pie` for distribution, `line/area` for trend, `table/detail/summary` for tabular summaries, `dualaxes` for two-metric comparison
-  - use semantic metrics: `count(*)`, `sum(金额)`, `avg(工时)`, `group_by`, `where`; do not handwrite raw `indicator_field_ids`, `selectedMetrics`, or QingBI filter matrices on the main path
-  - supported `chart_type` values include legacy public aliases `target`, `table` and QingBI types such as `summary`, `columnar`, `area`, `stacked_area`, `funnel`, `waterfall`, `gauge`, `heatmap`, `histogram`, `treemap`, `radar`, `stacked_bar`, `stacked_column`, `scatter`, `ring`, `rose`, `dualaxes`, `map`, and `timeline`
-  - use `patch_charts` for changing a chart name, visibility, filters, or one config fragment on an existing chart
-  - `visibility` is a public capability and should be treated as a base-only permission update
-  - do not model chart visibility changes as raw config rewrites
-- Button work:
-  - ordinary view-specific buttons should be declared through `app_views_apply.action_buttons`
-  - `app_custom_buttons_apply` is for advanced button maintenance: style/icon changes, cross-view reuse, deleting button bodies, bulk binding reorder, or exact qRobot/wings configs
-  - use `patch_buttons` for changing a single existing button parameter such as URL, text, icon, style, or add-data mapping
-  - action choice:
-    - current record -> downstream/child record: use `add_data` in view `action_buttons`, or `addData` in standalone buttons, with `target_app_key + field_mappings`
-    - global independent create: use `add_data`/`addData` on `header` without current-record `source_field`
-    - SOP/external/fixed page: use `link` with `url`
-    - existing automation only: use `qRobot`/`wings` only when the user provides exact config
-    - approval/status transition/close task is not a generic button action; model workflow/task action first, or use existing automation. Do not fake it with `link`
-  - for add-data buttons, use `trigger_add_data_config.target_app_key + field_mappings/default_values`; do not handwrite raw `que_relation`
-  - use `field_mappings` for dynamic current-record values, including system fields such as `数据ID` (`field_id=-17`) and `编号` (`field_id=0`)
-  - to prefill a target relation field with the current source record, map `{"source_field": "数据ID", "target_field": "目标引用字段"}`; use `default_values` only for static constants
-  - if field type compatibility is unclear, read [match-rules.md](./match-rules.md)
-  - placement choice: `header` is global and has no current-row context; `list` is row/list action and maps to backend `INSIDE`; `detail` is the safest current-record context action. Do not use current-record `field_mappings` on `header`
-  - bind advanced standalone buttons to views through `view_configs[].buttons[]`; default to `placement`: `header` or `detail`
-  - builder `view_configs[].view_key` uses the raw key from `app_get.views[].view_key`, without a `custom:` prefix
-  - `buttons` is required in merge mode; do not send a view config with only `view_key`
-  - `view_configs[].mode` defaults to `merge`; use `mode: "replace"` or an explicit empty `buttons: []` to clear a view's custom button bindings
-  - `placement=list` configures row/list buttons and maps to the backend `INSIDE` button position
-  - advanced bindings may use `button_limit`, `button_formula`, `button_formula_type`, and `print_tpls` only when visibility or print-template behavior is required
-- Associated resources:
-  - `app_associated_resources_apply` is the public write path for the Qingflow app-level associated report/view pool and per-view display config
-  - for multi-app systems, use `apps[]` to batch associated-resource writes; each item carries its own `app_key` plus `upsert_resources` / `patch_resources` / `view_configs`
-  - it attaches existing BI reports/views for in-app display; it does not create or edit QingBI report bodies/configs, including dataset reports
-  - use `patch_resources` for changing match rules or other existing associated-resource parameters; the tool preserves backend-required raw fields internally
-  - `associated_item_id` is the backend internal associated-resource id; for `view_configs`, `remove_associated_item_ids`, and `reorder_associated_item_ids`, you may pass `associated_item_id` or an existing resource's `chart_id`/`chart_key`/`view_key`, and the tool resolves it to the internal id
-  - before creating a resource, check `app_get.associated_resources` for the same `target_app_key + view_key/chart_key`; if it already exists, use `patch_resources` with that `associated_item_id`
-  - `client_key` is only a same-call reference for `view_configs[].associated_item_refs`; it is not saved and cannot deduplicate later calls
-  - do not pass backend raw `sourceType`; view resources infer the internal Qingflow view source, report/chart resources default to BI app reports, and existing dataset reports use `report_source="dataset"`
-  - use `match_mappings` for associated view/report filters; dynamic conditions use `source_field`, static conditions use `value`
-  - if field type compatibility is unclear, read [references/match-rules.md](./match-rules.md)
-- Views and flows:
-  - stay on `app_views_apply` / `app_flow_apply`
-  - use `patch_views` for existing-view parameter changes such as `query_conditions`, `filters`, `columns`, or visibility
-  - builder view writes use raw `view_key` values from `app_get.views`; `custom:<viewKey>` is a record-data `view_id` form, not a builder `view_key`
-  - use `qingflow --json builder contract` whenever the minimal legal shape is unclear
-  - keep view `filters` and `query_conditions` separate: `filters` are fixed saved filters; `query_conditions` configure the frontend query panel fields and only take effect after users enter query values
-  - when creating any new table or card view, always include `query_conditions` with `enabled: true`; populate `rows` with the fields most useful for searching — typically the data-title field, any status/type select fields, date fields, and member fields; do not omit `query_conditions` or leave `rows` empty on a new view
-  - new views default the associated report/view display area to visible with `limit_type="all"`; existing views preserve their current associated-resource display unless `associated_resources` is explicitly patched
-  - configure associated reports/views through `app_associated_resources_apply`, not through `app_views_apply`
-
-## Standard Operating Order
-
-1. Ensure auth exists
-2. Ensure workspace is selected
-3. Confirm whether the task is read-only or write-impacting
-4. Resolve the smallest stable target:
-   - app-scoped work -> `app_resolve`
-   - package-scoped work with known id -> `package_get`
-   - portal inventory -> `portal_list`
-5. Read only the smallest config slice needed:
-   - app map -> `app_get` (default entry; includes compact views, charts, custom buttons, and associated resource pool)
-   - fields -> `app_get_fields`
-   - layout -> `app_get_layout`
-   - views -> `app_get_views` only when the app_get compact list is not enough
-   - flow -> `app_get_flow`
-   - charts -> `app_get_charts` only when the app_get compact list is not enough
-   - portal -> `portal_get`
-6. If the public shape is unclear, call `qingflow --json builder contract`
-7. Apply the smallest patch tool that fits:
-   - fields -> `app_schema_apply`
-   - layout -> `app_layout_apply`
-   - flow -> `app_flow_apply`
-   - existing views -> `app_views_apply.patch_views`; new/full views -> `app_views_apply.upsert_views`
-   - existing buttons -> `app_custom_buttons_apply.patch_buttons`; new/full buttons -> `app_custom_buttons_apply.upsert_buttons`
-   - existing associated resources -> `app_associated_resources_apply.patch_resources`; new/full resources -> `app_associated_resources_apply.upsert_resources`
-   - existing charts -> `app_charts_apply.patch_charts`; new/full charts -> `app_charts_apply.upsert_charts`
-   - portal -> `portal_apply`
-   - package metadata/layout -> `package_apply`
-8. Use `app_publish_verify` only when the user explicitly wants final publish/live verification or you need a dedicated verification pass
-
-## Safe Usage Rules
-
-- 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`.
-- 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 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.
-- Always pass `publish: true` (or CLI `--publish`) explicitly on `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, and `portal_apply` — do not rely on the default. `app_custom_buttons_apply` and `app_associated_resources_apply` publish automatically after at least one write succeeds and do not accept a `publish` parameter. `app_charts_apply` is immediate-live without a publish step.
-- When creating or updating fields, configure the app data title/cover directly in field JSON: `as_data_title: true` is required on exactly one readable top-level title field; `as_data_cover: true` is optional and only valid on one top-level `attachment` field.
-- When any tool returns `error_code` or `VALIDATION_ERROR`, read the `message` field verbatim first before guessing at parameter or CLI parsing issues. A clear `message` like "relation field requires visible_fields" is the root cause — do not redirect to unrelated hypotheses such as `create_if_missing` parsing or flag conflicts.
-- If the same validation error repeats twice, stop guessing and re-read `qingflow --json builder contract`.
-- For workflow assignees, prefer `role_search` over explicit members unless the user explicitly wants named members.
-- Public flow building is still intentionally limited to stable linear workflows. If a requirement sounds like branches/conditions, explain the limitation instead of freehanding unsupported graph shapes.
-- Respect collaborative edit locks. Only use `app_release_edit_lock_if_mine` when the lock owner is the current authenticated user.
-- If the supported builder surface is still awkward or blocked after reasonable use, summarize the gap, ask whether to submit feedback, and call `feedback_submit` only after explicit user confirmation.
-
-## Response Interpretation
-
-- All builder apply/write tools return a standard UI envelope in addition to legacy fields:
-  `schema_version`, `operation`, `summary`, and `resources[]`.
-- 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.
-- For portals, distinguish clearly between:
-  - base-info-only update with layout preserved
-  - full sections replace
-  - patching one section with `patch_sections[]`
-  - layout validity: same-row `rows`, same-row `cols` sum, and non-empty grid `items`
-- For object apply tools, distinguish clearly between:
-  - `patch_*`: public partial parameter replacement; the tool hydrates current config and full-saves internally
-  - `upsert_*`: create or full target configuration; omitted fields may mean default/clear depending on that object
-- For charts, distinguish clearly between:
-  - base / visibility change
-  - real chart-config change
-- For app permissions, report `can_edit_app_base` separately from `can_edit_form / can_edit_flow / can_edit_views / can_edit_charts`.
-
-## Practical Patterns
-
-- Read one package: `package_get`
-- Create or update one package: `package_apply`
-- Resolve one app: `app_resolve`
-- Read one app map: `app_get`
-- Batch read app maps/slices: `app_get_*` with `app_keys[]`
-- Read fields only: `app_get_fields`
-- Read layout summary: `app_get_layout`
-- Read views summary: `app_get_views`
-- Read flow summary: `app_get_flow`
-- Read chart summary: `app_get_charts`
-- Read portal config: `portal_get`
-- Search members or roles: `member_search`, `role_search`
-- Create reusable role: `role_create`
-- Add/update/remove fields: `app_schema_apply`
-- Merge or replace layout: `app_layout_apply` (single app) or `apps[]` batch
-- Replace workflow or patch nodes: `app_flow_apply`
-- Upsert/patch/remove views: `app_views_apply` (single app) or `apps[]` batch
-- Upsert/patch/remove views, including ordinary view-specific buttons: `app_views_apply`
-- Advanced custom button maintenance and cross-view binding: `app_custom_buttons_apply` (single app) or `apps[]` batch
-- Upsert/patch/remove app associated reports/views and per-view display: `app_associated_resources_apply`
-- Upsert/patch/remove/reorder charts: `app_charts_apply` (single app) or `apps[]` batch
-- Create, update, or patch portal pages: `portal_apply`
-- Release your own stale edit lock: `app_release_edit_lock_if_mine`
-- Final publish verification: `app_publish_verify`
-
-## Advanced Button Pattern
-
-For ordinary view-specific buttons, prefer `app_views_apply.action_buttons`. Use `app_custom_buttons_apply` only for standalone/advanced maintenance: custom style or icon, cross-view reuse, deleting button bodies, bulk binding reorder, or exact qRobot/wings config.
-
-> CLI-only note: this is the payload from former internal surface `app_custom_buttons_apply`. Execute it through the matching `qingflow` CLI command and `--*-file` flags from SKILL.md / builder reference; do not call internal tool JSON.
-
-```json
-{
-  "app_key": "EMPLOYEE_APP",
-  "upsert_buttons": [
-    {
-      "client_key": "add_worklog",
-      "button_text": "快捷添加工时",
-      "style_preset": "primary_blue",
-      "button_icon": "ex-plus-circle",
-      "trigger_action": "addData",
-      "trigger_add_data_config": {
-        "target_app_key": "WORKLOG_APP",
-        "field_mappings": [
-          {
-            "source_field": "数据ID",
-            "target_field": "关联员工"
-          },
-          {
-            "source_field": "员工名称",
-            "target_field": "员工姓名"
-          },
-          {
-            "source_field": "所属部门",
-            "target_field": "部门名称"
-          }
-        ],
-        "default_values": {
-          "工时类型": "日常工作",
-          "状态": "待提交"
-        }
-      }
-    }
-  ],
-  "remove_buttons": [],
-  "view_configs": [
-    {
-      "view_key": "EMPLOYEE_VIEW",
-      "mode": "merge",
-      "buttons": [
-        {
-          "button_ref": "add_worklog",
-          "placement": "detail",
-          "primary": true
-        }
-      ]
-    }
-  ]
-}
-```
-
-`button_ref` may be a same-call `client_key` or an existing `button_id`. Supported placements are `header`, `detail`, and `list`; `list` maps to the backend `INSIDE` row/list button position.
-
-For add-data buttons that create a child record linked back to the current record, map `source_field: "数据ID"` to the target relation field. Do not use raw `que_relation` unless maintaining an existing backend config.
-
-## Historical Playbook Selection
-
-This file is historical supporting material. For the current main route, start from [../../README.md](../../README.md). If you still use this page, route to the current resource document first:
-
-| User intent | Signal phrases | Playbook |
-|-------------|---------------|---------|
-| Multi-app business system with cross-app relations, shared workflow, and a portal dashboard | "建一套系统"、"包含 N 个模块"、"这几个表单之间建立关联"、"完整的业务系统" | [20-build-complete-system.md](../../20-build-complete-system.md) |
-| Single app end-to-end: rich schema, layout, flow, multiple view types, custom buttons, in-app charts, associated resources, and sample data | "建一个应用"、"帮我搭一个XX管理"、"从零开始建一个XX"、"我需要一个管理XX的应用" | [10-build-single-app.md](../../10-build-single-app.md) |
-| Add one new app inside an existing package | "在这个包里加一个表单"、"现有系统里新增一个模块" | [create-app.md](./create-app.md) |
-| Update fields or schema only | "加一个字段"、"改字段名"、"删除字段" | [30-schema-fields.md](../../30-schema-fields.md) |
-| Update layout only | "调整分组"、"改排列顺序" | [40-layout.md](../../40-layout.md) |
-| Update workflow only | "修改审批流"、"加一个审批节点" | [90-workflow.md](../../90-workflow.md) |
-| Update views only | "加一个看板"、"改筛选条件"、"新增视图" | [50-views.md](../../50-views.md) |
-
-Decision rule: if the user mentions **multiple related apps or a portal**, use [20-build-complete-system.md](../../20-build-complete-system.md). If it is **one app** with a from-scratch setup request, use [10-build-single-app.md](../../10-build-single-app.md). If the target app already exists and the user only wants to change one layer, use the matching resource document.
-
-## Resources
-
-- Shared public-surface baseline: [public-surface-sync.md](./public-surface-sync.md)
-- Environment switching: [environments.md](./environments.md)
-- Tool choice and sequencing: [tool-selection.md](./tool-selection.md)
-- Field matching rules: [../match-rules.md](../match-rules.md)
-- Result semantics and gotchas: [gotchas.md](./gotchas.md)
-- Create one app in an existing package: [create-app.md](./create-app.md)
-- Update fields only: [../../30-schema-fields.md](../../30-schema-fields.md)
-- Update layout only: [../../40-layout.md](../../40-layout.md)
-- Update workflow only: [../../90-workflow.md](../../90-workflow.md)
-- Workflow assignees and node permissions: [flow-actors-and-permissions.md](./flow-actors-and-permissions.md)
-- Update views only: [../../50-views.md](../../50-views.md)
-- Standard end-to-end builder sequences: [solution-playbooks.md](./solution-playbooks.md)
-- Build a complete multi-app system from scratch: [../../20-build-complete-system.md](../../20-build-complete-system.md)
-- Build a single app end-to-end: [../../10-build-single-app.md](../../10-build-single-app.md)