@josephyan/qingflow-cli 1.1.4 → 1.1.5

package/skills/qingflow-cli/reference/builder/code-integrations/code-block.md

@@ -0,0 +1,66 @@
+# Code Block Builder Notes
+
+## What Builder Should Configure
+
+- code block field type
+- code content
+- inserted input fields inside code content
+- alias parsing
+- auto trigger
+- custom button text
+
+## Stable Writing Rules
+
+- Always emit `qf_output = {...}`
+- Never emit `const qf_output = {...}`
+- Never emit `let qf_output = {...}`
+
+## Useful CRM Pattern
+
+Inputs:
+- customer name
+- source
+- budget
+- timing
+- decision-maker flag
+
+Outputs:
+- score
+- level
+- priority
+- summary
+- next follow date
+
+## Target Field Rules
+
+Required:
+- every `outputs[*].target_field` must point to an existing field
+
+Allowed target field types:
+- text
+- long text
+- number
+- amount
+- date
+- datetime
+- single select
+- multi select
+- boolean
+
+Do not bind code block outputs to:
+- q_linker
+- code_block
+- relation
+- subtable
+- attachment
+- member
+- department
+- address
+
+## Safe Verification
+
+- `qingflow builder app get ... fields`
+- `qingflow record schema insert`
+- optional `record_code_block_run`
+
+Treat configuration verification and runtime verification as separate checks.

package/skills/qingflow-cli/reference/builder/code-integrations/q-linker.md

@@ -0,0 +1,77 @@
+# Q-Linker Builder Notes
+
+## What Builder Should Configure
+
+- `remoteLookupConfig`
+- alias parsing
+- target field binding
+- auto trigger
+- custom button text
+
+## Current Supported Scope
+
+- custom mode only
+- standard request fields
+- alias path parsing
+- target field binding to existing ordinary fields
+
+## Recommended Public APIs For Samples
+
+### Httpbin
+
+- URL: `https://httpbin.org/get`
+- Good for:
+  - query echo
+  - request URL echo
+
+Useful paths:
+- `$.args.keyword`
+- `$.url`
+
+### Open-Meteo Geocoding
+
+- URL: `https://geocoding-api.open-meteo.com/v1/search`
+- Good for:
+  - place normalization
+  - country
+  - lat/lng summary
+
+Useful paths:
+- `$.results[0].name`
+- `$.results[0].country`
+- `$.results[0].latitude`
+- `$.results[0].longitude`
+
+## Target Field Rules
+
+Required:
+- every `outputs[*].target_field` must point to an existing field
+
+Prefer:
+- text
+- long text
+- number
+- amount
+- date
+- datetime
+- single select
+- multi select
+- boolean
+
+Avoid:
+- q_linker
+- code_block
+- relation
+- subtable
+- attachment
+- member
+- department
+- address
+
+## Safe Verification
+
+- `qingflow builder app get ... fields`
+- `qingflow record schema insert`
+- `record_insert`
+
+This verifies that the configuration does not break the form page, even before runtime execution is tested.

package/skills/qingflow-cli/reference/{QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md → builder/reference/app-delivery-sop.md}

@@ -1,6 +1,6 @@
 # Builder 应用交付重流程 SOP：分组 → 应用定位 → 读场 → 改场 → 发布校验
 
-本文对齐 **MCP / AiBuilder** 工具链命名，并给出 **稳定 CLI**（`qingflow builder` / `qingflow build`）等价写法。编写前已 **阅读** `qingflow_mcp` 中 `builder_facade/service.py`、`cli/commands/builder.py`、`ai_builder_tools.py`，并对 **`ead8ims5i401`** **实跑**：`app resolve`、`app get fields|layout|flow`、`publish verify`。
+本文以 **稳定 CLI**（`qingflow builder` / `qingflow build`）为唯一公开入口。编写前已阅读实现中的 `builder_facade/service.py`、`cli/commands/builder.py`、`ai_builder_tools.py`，并对 **`ead8ims5i401`** 实跑：`app resolve`、`app get fields|layout|flow`、`publish verify`。
 
 > **权限**：应用基础信息（`app_name` / 图标 / 可见性）、表单、流程、自定义按钮本体、应用级关联资源池走 **应用搭建 / EditAppAuth**；视图更新/删除、按钮的视图位置配置（`view_configs`）和视图内关联资源展示配置走 **视图管理 / ViewManagementAuth**（后端 `beingViewManageStatus`；未开启高级应用权限时等价回落到 DataManageAuth）；**新建视图**额外需要 **DataManageAuth**；报表走 **数据管理 / DataManageAuth**。失败码常见 **40002 / 40161 / 编辑锁** 等，见主技能与 **ADMIN** 速查。
 
@@ -18,7 +18,7 @@
 
 ## 1. 推荐阶段顺序（与工具名对齐）
 
-| 阶段 | MCP / 编排常用名 | 稳定 CLI（有则列出） | 作用 |
+| 阶段 | 目标资源 | 稳定 CLI（有则列出） | 作用 |
 |------|------------------|----------------------|------|
 | A | **`package_list`** | `qingflow --json builder package list [--query <关键词>]` | 列出当前 Builder 权限可见的应用包，返回 **`package_id/package_name`**、包权限和应用数量 |
 | A′ | **`package_resolve`** | 不再作为 CLI 默认入口；用 `package list --query` 后人工/智能体确认 `package_id` | 同名包、空包都以 `package_list` 返回为准 |
@@ -34,7 +34,15 @@
 | G″ | **`app_associated_resources_apply`** | `qingflow builder associated-resource apply …` | 管理应用级关联视图/报表池，并配置视图详情侧边栏展示 |
 | H | **`app_publish_verify`** | `qingflow builder publish verify --app-key …` | 确认 **已发布**、包挂载、视图等校验位 |
 
-**说明**：**`app_charts_apply`**（CLI **`builder charts apply`**）不在上表骨架内，但同属交付闭环；详见 **[QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md)**；**视图**、**门户** 见同目录另文；其余另读 **`builder contract --tool-name …`**。`app_custom_buttons_apply` 与 `app_associated_resources_apply` 有成功写入时会自动发布，不暴露 draft-only `publish` 参数。
+**说明**：**`app_charts_apply`**（CLI **`builder charts apply`**）不在上表骨架内，但同属交付闭环；详见 **[60-charts.md](../60-charts.md)**；**视图**、**门户** 见同目录另文；其余另读 **`builder contract --tool-name …`**。`app_custom_buttons_apply` 与 `app_associated_resources_apply` 有成功写入时会自动发布，不暴露 draft-only `publish` 参数。
+
+### 1.1 批量读、批量写、局部改归位
+
+这些不是独立流程，而是读、写、改三个动作的多资源形态：
+
+- **批量读**：读多个应用时优先用 `--app-keys`，例如 `builder app get --app-keys a,b fields`、`builder app get --app-keys a,b views`、`builder button get --app-keys a,b`、`builder associated-resource get --app-keys a,b`、`builder publish verify --app-keys a,b`。读结果同时看成功项和 `errors[]`，不要因单个应用失败否定全批。
+- **批量写**：写多个应用时使用各资源自己的 `--apps-file`，例如 `schema/layout/views/button/associated-resource/charts apply --apps-file ...`。`apps[]` 每项都必须带自己的 `app_key` 或多应用 schema 的 `client_key/app_name`。
+- **局部改**：只改已存在资源的少量参数时用对应 patch 文件；`patch_*` 内只写目标定位字段和 `set/unset`，不要用不完整 `upsert_*` 伪装局部更新。
 
 ---
 
@@ -238,13 +246,13 @@ qingflow --json builder app get --app-key "<APP_KEY>" flow
 
 ### 5.1 字段：`builder schema apply`
 
-**一键可复制「仅新增字段」示例**（**`add_fields` 数组文件**）：[schema_add_fields_minimal.example.json](./schema_add_fields_minimal.example.json)
+**一键可复制「仅新增字段」示例**（**`add_fields` 数组文件**）：[schema_add_fields_minimal.example.json](../../examples/schema/schema_add_fields_minimal.example.json)
 
 ```bash
 qingflow builder schema apply \
   --app-key "<APP_KEY>" \
   --no-publish \
-  --add-fields-file ./reference/schema_add_fields_minimal.example.json
+  --add-fields-file ./reference/examples/schema/schema_add_fields_minimal.example.json
 ```
 （路径以 `qingflow-cli/` 技能根目录为基准；执行时可解析为该技能目录下的实际文件。）
 
@@ -263,7 +271,7 @@ qingflow builder schema apply \
 - **`--publish` / `--no-publish`**：默认发布；`--no-publish` 仅草稿/预检语义（见 `server_app_builder` 总述：**schema/layout/views/flow** 的 noop 与发布关系以契约为准）。
 - **文件体形状**：与 **`app_schema_apply`** 契约一致；顶层 **`add_fields` / `update_fields` / `remove_fields`** 数组。
 - **标题/封面**：只在字段 JSON 中直接标记，例如 `{"name":"项目名称","type":"text","required":true,"as_data_title":true}`、`{"name":"项目封面","type":"attachment","as_data_cover":true}`。
-- **本仓实测**（`ead8ims5i401`，`--no-publish`，`name` 改为未存在过的 **`CLI搭建探针字段_可删`**）：`field_diff.added` 成功；同一 **`name`** 不可重复添加，后续请改用 **[schema_add_fields_minimal.example.json](./schema_add_fields_minimal.example.json)** 内模板名或自改唯一名。
+- **本仓实测**（`ead8ims5i401`，`--no-publish`，`name` 改为未存在过的 **`CLI搭建探针字段_可删`**）：`field_diff.added` 成功；同一 **`name`** 不可重复添加，后续请改用 **[schema_add_fields_minimal.example.json](../../examples/schema/schema_add_fields_minimal.example.json)** 内模板名或自改唯一名。
 
 ### 5.2 布局：`builder layout apply`
 
@@ -345,7 +353,7 @@ qingflow builder flow apply \
 
 **`remove_fields` 项**：**`que_id` / `field_id` / `name`** 之一。
 
-**完整类型表、`schema apply` 场景矩阵、探针结论**：见 **[QINGFLOW_CLI_SCHEMA_APPLY_FIELD_TYPES_AND_SCENARIOS.md](./QINGFLOW_CLI_SCHEMA_APPLY_FIELD_TYPES_AND_SCENARIOS.md)**。**19 种搭建 `type` 单文件 `add_fields`（推荐新建应用一次成功）**：[schema_apply_add_fields_all_types.json](./schema_apply_add_fields_all_types.json)。
+**完整类型表、`schema apply` 场景矩阵、探针结论**：见 **[30-schema-fields.md](../30-schema-fields.md)**。**19 种搭建 `type` 单文件 `add_fields`（推荐新建应用一次成功）**：[schema_apply_add_fields_all_types.json](../../examples/schema/schema_apply_add_fields_all_types.json)。
 
 ---
 
@@ -357,8 +365,10 @@ qingflow builder flow apply \
 - 已有按钮：`builder button apply --patch-buttons-file`
 - 已有关联资源：`builder associated-resource apply --patch-resources-file`
 - 已有报表：`builder charts apply --patch-file`
+- 已有流程节点：`builder flow apply --patch-nodes-file`
+- 已有门户组件：`builder portal apply --patch-sections-file`
 
-`patch_*` 的语义是：你只写要替换的参数，工具内部读取当前配置、补齐后端必填字段，再整份保存。每个 patch 项直接使用对象真实定位字段 + `set` / 可选 `unset`，不要写字面量 `selector` key。示例：`{"view_key": "VIEW_KEY", "set": {"query_conditions": {...}}}`、`{"button_id": 1001, "set": {"button_text": "新名称"}}`、`{"associated_item_id": 123, "set": {"match_mappings": [...]}}`、`{"chart_id": 456, "set": {"name": "新报表名"}}`。
+`patch_*` 的语义是：你只写要替换的参数，工具内部读取当前配置、补齐后端必填字段，再整份保存。每个 patch 项直接使用对象真实定位字段 + `set` / 可选 `unset`，不要写字面量 `selector` key。示例：`{"view_key": "VIEW_KEY", "set": {"query_conditions": {...}}}`、`{"button_id": 1001, "set": {"button_text": "新名称"}}`、`{"associated_item_id": 123, "set": {"match_mappings": [...]}}`、`{"chart_id": 456, "set": {"name": "新报表名"}}`、`{"id": "node_1", "set": {"name": "主管审批"}}`、`{"chart_ref": {"chart_key": "xxx"}, "set": {"rows": 7}}`。
 
 `upsert_*` 用于创建或提供完整目标配置；不要只给 `name/type/query_conditions` 这类局部片段然后期待后端自动合并。
 
@@ -419,7 +429,7 @@ qingflow builder button apply \
 - `button_ref` 可以引用同次 `upsert_buttons[].client_key`，也可以引用已有 `button_id`。
 - `view_configs[].view_key` 使用 `builder app get --app-key APP_KEY` 返回的 raw `view_key`，不要加 `custom:`。
 - `view_configs[].mode` 默认 `merge`，merge 模式必须传 `buttons`；清空用 `mode="replace"` 或显式 `buttons: []`。
-- 字段兼容与 `数据ID` / `编号` 规则见 **[QINGFLOW_CLI_BUILDER_MATCH_RULES.md](./QINGFLOW_CLI_BUILDER_MATCH_RULES.md)**。
+- 字段兼容与 `数据ID` / `编号` 规则见 **[match-rules.md](./match-rules.md)**。
 - 删除按钮时优先传 **`button_id`**；若用 **`button_text`** 必须能唯一匹配。DELETE 发出后会按单个 **`button_id`** 回读验证，结果看 **`removed[].delete_executed/readback_status/safe_to_retry_delete`**。只要 **`delete_executed=true`**，就不要盲目重复删除；**`readback_status=unavailable|still_exists`** 表示回读待确认。
 - 该工具有成功写入时自动发布；全阻断、全失败或无变化不会额外发布。
 
@@ -453,7 +463,7 @@ qingflow builder associated-resource apply \
 - `client_key` 只用于同一次 apply 内给 `view_configs[].associated_item_refs` 引用，后端不会保存，不能用于后续去重。
 - 每个主应用都要生成自己的 upsert/view-config payload，不要复用其他应用的 tmp JSON；命令中 `--app-key` 只写一次，且必须与 payload 的主应用一致。
 - 成功后必须用 `builder app get --app-key ...` 回读：确认 `associated_resources[].associated_item_id` 已生成，并确认目标视图的详情配置中已绑定对应资源。若只看到资源池有记录、视图详情无绑定，继续补 `view_configs`，不能宣称完成。
-- 关联筛选优先用 `match_mappings`，不要手写 raw `match_rules`；字段兼容规则见 **[QINGFLOW_CLI_BUILDER_MATCH_RULES.md](./QINGFLOW_CLI_BUILDER_MATCH_RULES.md)**。
+- 关联筛选优先用 `match_mappings`，不要手写 raw `match_rules`；字段兼容规则见 **[match-rules.md](./match-rules.md)**。
 - 删除关联资源时传 **`associated_item_id`**，也可传已有资源的 `chart_id/chart_key/view_key` 让工具解析为内部 id。后端暂无确认可用的单项关联资源 GET，所以工具只做一次资源池回读验证；结果看 **`removed[].delete_executed/readback_status/safe_to_retry_delete`**。只要 **`delete_executed=true`**，就不要盲目重复删除；**`readback_status=unavailable|still_exists`** 表示回读待确认。
 - 该工具有成功写入时自动发布；不提供 `--no-publish`。
 
@@ -483,9 +493,9 @@ qingflow builder publish verify \
 
 ## 10. 交叉引用
 
-- **最小 `add_fields` 示例**：[schema_add_fields_minimal.example.json](./schema_add_fields_minimal.example.json)
-- **19 种搭建 type 一次性 `add_fields`**：[schema_apply_add_fields_all_types.json](./schema_apply_add_fields_all_types.json)
-- **类型与场景总表**：[QINGFLOW_CLI_SCHEMA_APPLY_FIELD_TYPES_AND_SCENARIOS.md](./QINGFLOW_CLI_SCHEMA_APPLY_FIELD_TYPES_AND_SCENARIOS.md)
-- [SKILL.md](../SKILL.md)：`builder` 命令边界、**ADMIN** 指向。
-- [QINGFLOW_CLI_FIELD_DATA_TYPES.md](./QINGFLOW_CLI_FIELD_DATA_TYPES.md)：成员侧 **记录读写** 的 `kind` / 值形态（与 **搭建 `type`** 名称不同系，但可对照理解业务）。
-- [QINGFLOW_CLI_ADMIN_CHEATSHEET.md](./QINGFLOW_CLI_ADMIN_CHEATSHEET.md)：`package apply`、权限类 **`IMPORT_*` / 40002**。
+- **最小 `add_fields` 示例**：[schema_add_fields_minimal.example.json](../../examples/schema/schema_add_fields_minimal.example.json)
+- **19 种搭建 type 一次性 `add_fields`**：[schema_apply_add_fields_all_types.json](../../examples/schema/schema_apply_add_fields_all_types.json)
+- **类型与场景总表**：[30-schema-fields.md](../30-schema-fields.md)
+- [SKILL.md](../../../SKILL.md)：`builder` 命令边界、**ADMIN** 指向。
+- [QINGFLOW_CLI_FIELD_DATA_TYPES.md](../../core/QINGFLOW_CLI_FIELD_DATA_TYPES.md)：成员侧 **记录读写** 的 `kind` / 值形态（与 **搭建 `type`** 名称不同系，但可对照理解业务）。
+- [QINGFLOW_CLI_ADMIN_CHEATSHEET.md](../../core/QINGFLOW_CLI_ADMIN_CHEATSHEET.md)：`package apply`、权限类 **`IMPORT_*` / 40002**。

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

@@ -0,0 +1,293 @@
+# 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`
+- 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
+  - 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:
+  - `app_custom_buttons_apply` is the public write path for custom button bodies and view placement
+  - use `patch_buttons` for changing a single existing button parameter such as URL, text, icon, style, or add-data mapping
+  - 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)
+  - bind 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
+- 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 custom buttons and bind them to header/detail view positions: `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`
+
+## Button Pattern
+
+Use `app_custom_buttons_apply` for the whole custom-button path: button body, add-data mapping, default values, and placement.
+
+> 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)