@josephyan/qingflow-cli 1.1.4 → 1.1.6

package/skills/qingflow-cli/reference/{QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md → builder/50-views.md}

@@ -1,13 +1,36 @@
-# Builder 视图创建与变更 SOP：`qingflow builder views apply`
+# Builder Views
 
-稳定命令：**`qingflow builder views apply`**（别名 **`qingflow build views apply`**）。编写前已结合 **builder 契约**与实现要点整理；**最小可用 `upsert` 文件**见 **[views_upsert_table_minimal.example.json](./views_upsert_table_minimal.example.json)**（与门户/报表 **`.example.json`** 同风格）。已对应用 **`ead8ims5i401`** **实跑**该文件。
+Read this when the task is about table/card/board/gantt views, fixed filters, query panels, view sorting, associated report/view display on a view, or repairing existing views.
+
+## Scope
+
+Responsible for: `builder views apply`, `upsert_views`, `patch_views`, `remove_views`, `columns`, `filters`, `query_conditions`, and view readback.
+
+Not responsible for: creating associated report resources or buttons. Use [80-buttons-associated-resources.md](./80-buttons-associated-resources.md) after the target views/charts exist.
+
+## Main chain
+
+```text
+app get -> app get fields/views -> views apply -> associated-resource apply when needed -> app get/views readback
+```
+
+## Update existing views
+
+- Prefer `patch_views` for small changes to an existing view.
+- Use raw `view_key` from `app_get.views[].view_key`; do not use record-data `custom:<view_key>` prefixes.
+- Do not send a partial `upsert_views` object to update a complex existing view unless the contract says that shape is complete.
+- Verify filters, query conditions, and associated resources separately before reporting success.
+
+## Detailed contract notes
+
+稳定命令：**`qingflow builder views apply`**（别名 **`qingflow build views apply`**）。编写前已结合 **builder 契约**与实现要点整理；**最小可用 `upsert` 文件**见 **[views_upsert_table_minimal.example.json](../examples/views/views_upsert_table_minimal.example.json)**（与门户/报表 **`.example.json`** 同风格）。已对应用 **`ead8ims5i401`** **实跑**该文件。
 
 > **权限**：视图**新建**走后端 `createViewgraphConfig`，需要同时满足 **视图管理 / ViewManagementAuth**（`beingViewManageStatus`）和 **数据管理 / DataManageAuth**；视图**更新/删除**只走 **ViewManagementAuth**。未开启高级应用权限时 `beingViewManageStatus` 等价回落到 **DataManageAuth**。失败时常见 **40002 / 40161 / 编辑锁**，参见主技能与 **ADMIN** 速查。
 
 > **默认系统视图**：`全部数据`、`我的数据`、`我发起的`、`待办`、`已办`、`抄送` 等由轻流自带，**不要新建同名业务视图**。新建视图必须用业务名，例如 `项目台账视图`、`客户跟进视图`、`逾期任务看板`。如果确实要调整默认系统视图，只能从 `app get views` 取已存在的 raw **`view_key`** 后用 `patch_views` 或带 `view_key` 的 `upsert_views` 更新。
 
-> **契约**（权威键名、枚举、`execution_notes`、示例）：  
-> `qingflow --json builder contract --tool-name app_views_apply`  
+> **契约**（权威键名、枚举、`execution_notes`、示例）：
+> `qingflow --json builder contract --tool-name app_views_apply`
 > （`--tool-name` 为契约索引，用于拉取 **`allowed_keys` / 别名 / 示例**。）
 > 契约示例若带 `"profile"`，不要复制到 `--upsert-views-file`；CLI 指定 profile 用根级 `qingflow --profile …`。
 
@@ -24,7 +47,7 @@
 | ⑤ 涉及关联/按钮 | 用专项 apply，不把它们塞进 view patch | `builder associated-resource apply` / `builder button apply` |
 | ⑥ 需要上线时 | 发布侧校验 | `qingflow builder publish verify --app-key …` |
 
-**说明**：`views apply` 的 **`--publish`** 对应契约里的 **`publish`**；自动化可先 **`--no-publish`**，与 schema/layout 改完再 **`publish verify`** 的节奏一致，见 **[QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)** 的发布校验章节。
+**说明**：`views apply` 的 **`--publish`** 对应契约里的 **`publish`**；自动化可先 **`--no-publish`**，与 schema/layout 改完再 **`publish verify`** 的节奏一致，见 **[99-publish-verify.md](./99-publish-verify.md)**。
 
 ---
 
@@ -47,7 +70,7 @@ qingflow builder views apply \
 
 | 文件 | 用途 |
 |------|------|
-| [views_upsert_table_minimal.example.json](./views_upsert_table_minimal.example.json) | **新建 table 视图**最小 **`upsert_views` 数组**：`name` + `type` + **`columns`**（字段 **显示名**，须来自 **`builder app get --app-key … fields`**） |
+| [views_upsert_table_minimal.example.json](../examples/views/views_upsert_table_minimal.example.json) | **新建 table 视图**最小 **`upsert_views` 数组**：`name` + `type` + **`columns`**（字段 **显示名**，须来自 **`builder app get --app-key … fields`**） |
 
 **本仓实测**（`ead8ims5i401`，`--no-publish`）：使用文件内 **`columns`**（`单行文字`、`多行文字`）与视图 **`name`** **`示例表视图_CLI模板`** 可 **`status: success` 创建**。复制到其他应用前务必 **`app get fields`** 替换 **`columns`**；**`name`** 重名时会 **更新** 已有同名视图而非新建（见 **§4**）。
 
@@ -96,7 +119,7 @@ CLI 将参数与文件内容拼装为服务层载荷，**顶层键**如下：
 | **`board`**（看板） | 列；且须 **`group_by`**（分组字段名） | **`group_by`** |
 | **`gantt`** | 列；须 **`start_field`**、**`end_field`**（通常为日期类字段名） | 可选 **`title_field`** |
 
-实现侧校验：对 **table/card**，若声明了 **`columns`**，在 **过滤系统列**后须 **至少保留一个**真实应用字段，否则报错——**不能**只用系统列名凑一列（系统列集合见 **[QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md) §7.1**）。
+实现侧校验：对 **table/card**，若声明了 **`columns`**，在 **过滤系统列**后须 **至少保留一个**真实应用字段，否则报错——**不能**只用系统列名凑一列（系统列集合见 **[reference/app-delivery-sop.md](./reference/app-delivery-sop.md)**）。
 
 ---
 
@@ -181,7 +204,7 @@ CLI 将参数与文件内容拼装为服务层载荷，**顶层键**如下：
 - 已有资源的最终口径是 `app_get.associated_resources[].associated_item_id`；它不是 `chart_id`、`chart_key` 或 `view_key`。
 - 新版 CLI 在关联报表时可先传 `chart_id` / `chart_key`，内部会解析为轻流后端需要的 id；创建前先检查是否已有相同 `target_app_key + view_key/chart_key`，已存在时用 `patch_resources`；`client_key` 只在同一次 apply 中可被 `associated_item_refs` 引用，不会持久化。
 - 数据集 BI 报表只能关联已有报表，使用 `report_source: "dataset"`；应用源报表可先用 `builder charts apply` 创建/更新。
-- 关联筛选优先用 `match_mappings`；字段匹配规则见 **[QINGFLOW_CLI_BUILDER_MATCH_RULES.md](./QINGFLOW_CLI_BUILDER_MATCH_RULES.md)**。
+- 关联筛选优先用 `match_mappings`；字段匹配规则见 **[reference/match-rules.md](./reference/match-rules.md)**。
 
 ---
 
@@ -260,7 +283,7 @@ CLI 将参数与文件内容拼装为服务层载荷，**顶层键**如下：
 
 ## 9. 实测记录（`ead8ims5i401`，`--no-publish`）
 
-内容与仓库 **[views_upsert_table_minimal.example.json](./views_upsert_table_minimal.example.json)** 一致（或历史探针名 **`CLI探针视图_可删`**）。
+内容与仓库 **[views_upsert_table_minimal.example.json](../examples/views/views_upsert_table_minimal.example.json)** 一致（或历史探针名 **`CLI探针视图_可删`**）。
 
 **读视图**：
 
@@ -274,7 +297,7 @@ qingflow --json builder app get --app-key ead8ims5i401 views
 qingflow builder views apply \
   --app-key ead8ims5i401 \
   --no-publish \
-  --upsert-views-file ./reference/views_upsert_table_minimal.example.json
+  --upsert-views-file ./reference/examples/views/views_upsert_table_minimal.example.json
 ```
 
 **结果摘要**（示例视图名 **`示例表视图_CLI模板`**）：`status: success`，`verification.by_view[0].status: created`，返回 **`view_key`**（如 **`ecdk22v65c02`**），`published: false`。
@@ -292,13 +315,14 @@ qingflow builder views apply \
 | 后端 **40038 / Object not exist** | 先读失败项 **`details.per_view_results[].details.field_level_diagnostics`** 与 **`recommended_minimal_retry`**。不要删除字段、不要重建应用；先按最小列重试，再逐步加非关键列/筛选。 |
 | 按钮/关联资源配置 | 按钮走 **`builder button apply`**；关联视图/报表走 **`builder associated-resource apply`** |
 | 部分失败 | 读 **`views_diff.failed`** 与契约 **execution_notes** 中 **partial_success** |
-| 权限/锁 | 同 [交付 SOP](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)（**`publish verify`**、编辑锁） |
+| 权限/锁 | 同 [publish verify](./99-publish-verify.md) 与 [app delivery reference](./reference/app-delivery-sop.md) |
 
 ---
 
 ## 11. 交叉引用
 
-- [views_upsert_table_minimal.example.json](./views_upsert_table_minimal.example.json)（**table** 视图最小 **`upsert`**）
-- [SKILL.md](../SKILL.md)：builder 直接输出、鉴权顺序。
-- [QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)：系统列、**`publish verify`**、整体交付阶段。
-- [QINGFLOW_CLI_EXPLORATION_REPORT.md](./QINGFLOW_CLI_EXPLORATION_REPORT.md)：CLI 覆盖与 **`view_id` vs `view_key`** 备忘。
+- [views_upsert_table_minimal.example.json](../examples/views/views_upsert_table_minimal.example.json)（**table** 视图最小 **`upsert`**）
+- [SKILL.md](../../SKILL.md)：builder 直接输出、鉴权顺序。
+- [99-publish-verify.md](./99-publish-verify.md)：发布与回读。
+- [reference/app-delivery-sop.md](./reference/app-delivery-sop.md)：系统列与历史交付细节。
+- [QINGFLOW_CLI_EXPLORATION_REPORT.md](../core/QINGFLOW_CLI_EXPLORATION_REPORT.md)：CLI 覆盖与 **`view_id` vs `view_key`** 备忘。

package/skills/qingflow-cli/reference/{QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md → builder/60-charts.md}

@@ -1,4 +1,27 @@
-# Builder 报表（QingBI）创建与变更 SOP：`qingflow builder charts apply`
+# Builder Charts
+
+Read this when the task is about QingBI charts, indicator cards, chart filters, chart ordering, chart update, or chart removal.
+
+## Scope
+
+Responsible for: `builder charts apply`, `upsert_charts`, `patch_charts`, remove/reorder, semantic metrics such as `count(*)` or `sum(金额)`, `group_by`, `where`/`filters`, and chart readback.
+
+Not responsible for: portal placement of charts. Use [70-portal.md](./70-portal.md) after charts exist.
+
+## Main chain
+
+```text
+app get fields -> app get charts -> charts apply -> app get charts/chart get readback -> portal reference if needed
+```
+
+## Update existing charts
+
+- Use `chart_id` for exact updates when names may be duplicated.
+- Use `patch_charts` for small changes and `reorder_chart_ids` for ordering.
+- Prefer semantic metrics and filters; do not handwrite QingBI raw matrices unless the contract requires raw diagnosis.
+- Chart writes are immediate-live and are not the same as app `publish verify`.
+
+## Detailed contract notes
 
 稳定命令：**`qingflow builder charts apply`**（子命令 **`builder charts apply`**；**`qingflow build charts apply`** 等价）。
 
@@ -8,7 +31,7 @@
 
 > **读取链路**：`builder chart get` / `chart_get` 读取基础信息时优先走前端同源的 **`/qingbi/charts/qflow/baseinfo/{chartId}`** 可见性链路；仅当该 qflow 路由明确不存在/不适用时才退回 BI 管理详情 **`/qingbi/charts/baseinfo/{chartId}`**。配置详情 **`/qingbi/charts/{chartId}/configs`** 仍可能需要 **`CHART_SEE`**，不可用时会尝试从 qflow 数据接口返回的 embedded config 降级。不要把中间 **`CHART_SEE` / 40002** 直接当成“用户看不到报表”。
 
-> **契约**：`qingflow --json builder contract --tool-name app_charts_apply`  
+> **契约**：`qingflow --json builder contract --tool-name app_charts_apply`
 > （`--tool-name` 为契约索引。）
 
 > **与「应用发布」的关系**：契约 **execution_notes** 写明 **`app_charts_apply` 为 immediate-live，不走 `app_publish`**。改报表不等价于 **`builder publish verify`**。
@@ -165,15 +188,15 @@ CLI 对外推荐使用 **`group_by` + `metric(s)`**；旧的 **`dimension_field_
 ## 4. 创建流程（实现摘要）
 
 1. **读** 应用表单 **`fields`** + QingBI datasource **`chart_fields`**；报表维度/指标/筛选/查询条件字段以 **`chart_fields`** 为权威，表单字段只用于补充显示名/类型。
-2. **无 `chart_id` 且无名或名未命中**：**`qingbi_report_create`**（临时 **`chartId`** 形如 **`mcp_<hex>`**），再以 **`chartName`/`chartType`** 做 **读回确认**，得到 **最终 `chart_id`**。  
-3. **有名唯一命中** 或 **`chart_id` 命中**：必要时 **`qingbi_report_update_base`**（改名、类型、**`visibleAuth`**）。  
+2. **无 `chart_id` 且无名或名未命中**：**`qingbi_report_create`**（临时 **`chartId`** 形如 **`mcp_<hex>`**），再以 **`chartName`/`chartType`** 做 **读回确认**，得到 **最终 `chart_id`**。
+3. **有名唯一命中** 或 **`chart_id` 命中**：必要时 **`qingbi_report_update_base`**（改名、类型、**`visibleAuth`**）。
 4. **新建或 config 有变**：**`qingbi_report_update_config`**（**`_build_public_chart_config_payload`**）；特殊 BI 类型会按上文转换后端字段。
 
 ---
 
 ## 5. **remove** / **reorder**
 
-- **`--remove-chart-ids-file`**：字符串 id 数组 → **`qingbi_report_delete`**。  
+- **`--remove-chart-ids-file`**：字符串 id 数组 → **`qingbi_report_delete`**。
 - 删除成功后工具会用单个 **`chart_id`** 回读验证是否已不存在；**纯删除不会再读全量报表列表**。若返回 **`readback_status: unavailable`** 或 **`still_exists`**，表示删除请求已发出但回读未确认，**不要盲目重复删除**，可稍后用 **`builder chart get --chart-id …`** 确认。
 - **`--reorder-chart-ids-file`**：期望的 **展示顺序前缀**；实现会 **反转** 后调 **`qingbi_report_reorder`**；验证时要求列表 **`chart_list_source == "sorted"`** 且前缀与请求一致。
 
@@ -210,10 +233,10 @@ CLI 对外推荐使用 **`group_by` + `metric(s)`**；旧的 **`dimension_field_
 
 ## 7. 示例文件（可复制）
 
-- **目标图（契约极简）**：[charts_upsert_minimal.example.json](./charts_upsert_minimal.example.json)  
-- **柱状（须替换 `field_id`）**：[charts_upsert_bar.example.json](./charts_upsert_bar.example.json)  
-- **重排**：[charts_reorder.example.json](./charts_reorder.example.json)  
-- **删除**：[charts_remove.example.json](./charts_remove.example.json)
+- **目标图（契约极简）**：[charts_upsert_minimal.example.json](../examples/charts/charts_upsert_minimal.example.json)
+- **柱状（须替换 `field_id`）**：[charts_upsert_bar.example.json](../examples/charts/charts_upsert_bar.example.json)
+- **重排**：[charts_reorder.example.json](../examples/charts/charts_reorder.example.json)
+- **删除**：[charts_remove.example.json](../examples/charts/charts_remove.example.json)
 
 ---
 
@@ -231,7 +254,7 @@ CLI 对外推荐使用 **`group_by` + `metric(s)`**；旧的 **`dimension_field_
 
 ## 9. 交叉引用
 
-- [SKILL.md](../SKILL.md)  
-- [QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)  
-- [QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md)（**`chart_ref`**）  
-- [QINGFLOW_CLI_FIELD_DATA_TYPES.md](./QINGFLOW_CLI_FIELD_DATA_TYPES.md)（成员侧 **`kind`** 与搭建 **`type`** 对照理解业务）
+- [SKILL.md](../../SKILL.md)
+- [reference/app-delivery-sop.md](./reference/app-delivery-sop.md)
+- [70-portal.md](./70-portal.md)（**`chart_ref`**）
+- [QINGFLOW_CLI_FIELD_DATA_TYPES.md](../core/QINGFLOW_CLI_FIELD_DATA_TYPES.md)（成员侧 **`kind`** 与搭建 **`type`** 对照理解业务）

package/skills/qingflow-cli/reference/{QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md → builder/70-portal.md}

@@ -1,6 +1,29 @@
-# Builder 门户创建与变更 SOP：`qingflow builder portal`
+# Builder Portal
 
-搭建侧稳定入口：**`qingflow builder portal`**：`list` / `get` / **`apply`** / **`delete`**（与根命令 **`qingflow portal`** 的「成员可读列表/详情」不同，见 **[QINGFLOW_CLI_EXPLORATION_REPORT.md](./QINGFLOW_CLI_EXPLORATION_REPORT.md) §4.6**）。
+Read this when the task is about creating, updating, deleting, publishing, or validating a portal/workbench/dashboard page.
+
+## Scope
+
+Responsible for: `builder portal list/get/apply/delete`, portal sections, standard workbench layout, business entry grid items, chart/view references, publish, and portal readback.
+
+Not responsible for: creating the apps, views, or charts referenced by the portal. Create or verify them first through [20-build-complete-system.md](./20-build-complete-system.md), [50-views.md](./50-views.md), and [60-charts.md](./60-charts.md).
+
+## Main chain
+
+```text
+portal list/get if updating -> verify apps/views/charts -> portal apply -> portal get readback -> publish state
+```
+
+## Update existing portal
+
+- Use `--dash-key` for updates and do not send `package_id`.
+- Use `patch_sections[]` for targeted section changes when possible.
+- If using a business-entry grid, include real `items`; do not submit an empty entry container.
+- Validate referenced `chart_key`, `chart_id`, `view_key`, or `app_key` before claiming the portal is complete.
+
+## Detailed contract notes
+
+搭建侧稳定入口：**`qingflow builder portal`**：`list` / `get` / **`apply`** / **`delete`**（与根命令 **`qingflow portal`** 的「成员可读列表/详情」不同，见 **[QINGFLOW_CLI_EXPLORATION_REPORT.md](../core/QINGFLOW_CLI_EXPLORATION_REPORT.md) §4.6**）。
 
 实现要点来自 CLI 打包内的 `builder_facade/models.py`（`PortalApplyRequest`、`PortalSectionPatch`）、`builder_facade/service.py`（`portal_apply` / `portal_delete`）、`cli/commands/builder.py`。已对 **`package_id=2030703`**、应用 **`ead8ims5i401`** **实跑**：**新建**（`--no-publish`）、**`--publish` 更新**（网关 **503** 恢复后已重试成功）、**五类区块可稳定落库**；**`filter`（`type:6`）经 CLI 直传未落库** 见 **§3.4 / §8**。另已对测试包 **`1414907`** 实跑 **`portal delete`**：临时门户 **`etcivtmv5402`** 删除后回读 **`readback_status=deleted`**。
 
@@ -115,7 +138,7 @@ mobile 固定按 **6 栅格** 从上到下堆叠：通常所有组件 `x=0, cols
 
 - 公开 `sections-file` 稳定支持：**`grid` / `chart` / `view` / `text` / `link`**；`filter` 仍按 **§3.4** 的 raw `filterConfig` 边界处理，不作为主路径。
 - **待办 `task` / 常用 `favorite`** 是前端/后端 raw 组件形状，不在当前公开 `source_type` 合约里。智能体不要在 `sections-file` 中写 `source_type: "task"`；只有工具后续显式支持 `task`，或维护者走 raw 门户写入链路时，才使用待办槽位。
-- 推荐门户的可直接 apply 示例见 **[portal_sections_standard_workbench.example.json](./portal_sections_standard_workbench.example.json)**。该示例使用当前公开 CLI 可稳定写入的组件，顶部先用一个业务入口 `grid` 占满 24 栅格；如果工具已支持待办组件，再把顶部拆成 `grid cols=12 + task cols=12`。
+- 推荐门户的可直接 apply 示例见 **[portal_sections_standard_workbench.example.json](../examples/portal/portal_sections_standard_workbench.example.json)**。该示例使用当前公开 CLI 可稳定写入的组件，顶部先用一个业务入口 `grid` 占满 24 栅格；如果工具已支持待办组件，再把顶部拆成 `grid cols=12 + task cols=12`。
 - `grid` 必须写 **`config.items[]`**；只写 `gridTitle` / `beingShowTitle` 会生成空入口容器，工具会返回 **`PORTAL_GRID_ITEMS_EMPTY`**。
 
 **待办组件 raw 形状参考**（仅用于工具实现对齐，当前不要作为 `--sections-file` 输入）：
@@ -165,7 +188,7 @@ CLI 校验（`PortalSectionPatch`）：**chart** 须 **`chart_ref`**；**view**
 实现：组件为 **`{"type": 6, "filterConfig": deepcopy(section.config)}`**。
 
 - **理论上**与 solution 编译器一致：外层 **`{"filterConfig": [ … ], "graphList": [ … ]}`**；**`graphList`** 常含 **`graphType`**（如 **`CHART`**）、**`graphKey`** 或 **`graphRef`（`entity_id` / `chart_id`）** 等。
-- **本环境 CLI 直写实测（多次 `--publish`）**：在已验证 **chart / view / grid / text / link** 均可落库的前提下，**`source_type: filter` 始终未出现在 `draft_result.components` 中**；尝试过：**空数组**、**仅 `graphList` + QingBI `chart_id`**、**`graphKey` 为门户 `dashChartId`**、**`chart` 排在 **`filter` 前**、**仅 2 块（chart+filter）** 等，回读仍 **只有 chart（`count: 1`）** 或 **五类缺 `type: 6`**。  
+- **本环境 CLI 直写实测（多次 `--publish`）**：在已验证 **chart / view / grid / text / link** 均可落库的前提下，**`source_type: filter` 始终未出现在 `draft_result.components` 中**；尝试过：**空数组**、**仅 `graphList` + QingBI `chart_id`**、**`graphKey` 为门户 `dashChartId`**、**`chart` 排在 **`filter` 前**、**仅 2 块（chart+filter）** 等，回读仍 **只有 chart（`count: 1`）** 或 **五类缺 `type: 6`**。
   **结论**：当前宜 **在搭建界面创建筛选条**，再 **`builder portal get` 反抓** 原始 `filterConfig` 形状；或向后端确认 **POST `/dash/{dashKey}`** 对 **`type: 6`** 的必填字段。**自动化不要默认认为 `filter` 已写入。**
 - portal `filter` 组件仍按 raw `filterConfig` 处理，不纳入视图 / 报表 / 关联资源的统一筛选 DSL 主链路。
 
@@ -231,12 +254,12 @@ qingflow --json builder portal delete --dash-key "<DASH_KEY>" > tmp/builder_port
 | 补报表 | **`builder charts apply`**，`name: 门户探针_目标图`，**`target`** | **`chart_id`: `mcp_fb104267c5c249ca`** |
 | 503 后重试 | **`--dash-key ecdcell64s02`、`--publish`** + 含 **filter** 的六类 **`sections-file`** | **`published: true`**；**`filter` 仍不落库** → **`partial_success`**，**`components expected 6, got 5`**（与 **§3.4** 一致） |
 | **filter 专项** | 仅 **chart + filter** 两块的多种 **`graphList`/`graphRef`/`dashChartId`/`filterGroupConfig`** 组合 | **回读恒为 1 块（仅 `type: 9`）** |
-| **稳定可复现** | **`--publish`** + **[portal_sections_five_types.example.json](./portal_sections_five_types.example.json)**（**grid / text / link / view / chart**） | **`status: success`**，**`types: [2,4,5,9,10]`**，**`published: true`** |
+| **稳定可复现** | **`--publish`** + **[portal_sections_five_types.example.json](../examples/portal/portal_sections_five_types.example.json)**（**grid / text / link / view / chart**） | **`status: success`**，**`types: [2,4,5,9,10]`**，**`published: true`** |
 | 删除门户 | `builder portal delete --dash-key etcivtmv5402` | **`status: success`**，**`delete_executed: true`**，**`readback_status: deleted`**，**`summary.removed: 1`** |
 
-**推荐工作台模板示例**：[portal_sections_standard_workbench.example.json](./portal_sections_standard_workbench.example.json)
+**推荐工作台模板示例**：[portal_sections_standard_workbench.example.json](../examples/portal/portal_sections_standard_workbench.example.json)
 
-**含 `filter` 的六类示例（`filter` 是否落库视环境/后端而定）**：[portal_sections_all_types.example.json](./portal_sections_all_types.example.json)
+**含 `filter` 的六类示例（`filter` 是否落库视环境/后端而定）**：[portal_sections_all_types.example.json](../examples/portal/portal_sections_all_types.example.json)
 
 ---
 
@@ -248,7 +271,7 @@ qingflow --json builder portal delete --dash-key "<DASH_KEY>" > tmp/builder_port
 | `PORTAL_READBACK_PENDING` / **`components expected N, got M`** | **`portal get`** 数组件；若多写了 **`filter`** 而回读少一块，见 **§3.4**（**CLI 写 filter 可能整体不生效**）；也可能是 **异步回读**，可再 **`get`** 一次。 |
 | **`published: true` 但 `verified: false`** | 读 **§7**；用 **`get` 草稿+线上**对照。 |
 | **503** | 网关/运维；稍后重试。 |
-| 缺 **chart** | **[QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md)**：`builder charts apply`；或换有报表的应用。 |
+| 缺 **chart** | **[60-charts.md](./60-charts.md)**：`builder charts apply`；或换有报表的应用。 |
 | **VISIBILITY_CONFLICT** | 只用 **`--visibility-file`**。 |
 | `delete_executed=true` 但 `readback_status=unavailable|still_exists` | DELETE 已发出，回读未确认；不要重复删除，稍后 `builder portal get/list` 复核。 |
 
@@ -256,8 +279,8 @@ qingflow --json builder portal delete --dash-key "<DASH_KEY>" > tmp/builder_port
 
 ## 11. 交叉引用
 
-- [SKILL.md](../SKILL.md)
-- [QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)
-- [QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md)
-- [QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md)
-- [QINGFLOW_CLI_EXPLORATION_REPORT.md](./QINGFLOW_CLI_EXPLORATION_REPORT.md)
+- [SKILL.md](../../SKILL.md)
+- [reference/app-delivery-sop.md](./reference/app-delivery-sop.md)
+- [50-views.md](./50-views.md)
+- [60-charts.md](./60-charts.md)
+- [QINGFLOW_CLI_EXPLORATION_REPORT.md](../core/QINGFLOW_CLI_EXPLORATION_REPORT.md)

package/skills/qingflow-cli/reference/builder/80-buttons-associated-resources.md

@@ -0,0 +1,41 @@
+# Builder Buttons And Associated Resources
+
+Read this when the task mentions custom buttons, button visibility, add-data button mappings, associated views, associated reports, or current-record context matching.
+
+## Scope
+
+Responsible for: `builder button apply`, `builder associated-resource apply`, view button placement, associated view/report display config, `match_mappings`, and button add-data mappings.
+
+Not responsible for: creating the target views or charts themselves. Create or verify them first through [50-views.md](./50-views.md) and [60-charts.md](./60-charts.md).
+
+## Main chain
+
+```text
+app get -> app get views/charts/buttons/associated resources -> apply button or associated-resource -> readback
+```
+
+## Custom buttons
+
+- Use `upsert_buttons` for create/update and `patch_buttons` for small changes.
+- Use `view_configs` only after reading target `view_key`.
+- Use semantic conditions: `field_name + operator + value/values`. Do not handwrite raw `judgeType` or backend match matrices.
+- For add-data button field mappings, use target/source semantics, not raw backend ids, unless a contract explicitly requires ids.
+
+## Associated views and reports
+
+- Manage the app-level resource pool and view detail display through `associated-resource apply`.
+- For current-record filtering, use `match_mappings`:
+
+```json
+{
+  "target_field": "关联客户",
+  "operator": "eq",
+  "source_field": "数据ID"
+}
+```
+
+- Static filters can use `target_field + operator + value`.
+- Do not mix semantic `match_mappings` with raw `match_rules` in the same resource.
+- Dataset BI reports can only be associated after they already exist; `charts apply` creates application-source QingBI reports.
+
+Detailed compatibility rules are in [reference/match-rules.md](./reference/match-rules.md). The older full delivery notes are in [reference/app-delivery-sop.md](./reference/app-delivery-sop.md).

package/skills/qingflow-cli/reference/builder/90-workflow.md

@@ -0,0 +1,34 @@
+# Builder Workflow
+
+Read this when the task is about approval/fill/copy/webhook workflow configuration or workflow repair.
+
+## Scope
+
+Responsible for: `builder flow apply`, flow presets, `patch_nodes`, assignees, editable fields, and workflow readback.
+
+Not responsible for: unsupported arbitrary backend workflow graphs. Public flow building is intentionally limited to stable linear workflows.
+
+## Main chain
+
+```text
+contract -> app get fields -> app get flow -> member/role lookup -> flow apply -> readback if partial
+```
+
+## Recommended write path
+
+- Start from a preset when possible: `basic_approval` or `basic_fill_then_approve`.
+- Patch preset node ids instead of adding duplicate nodes:
+  - `basic_approval` -> `approve_1`
+  - `basic_fill_then_approve` -> `fill_1`, `approve_1`
+- Use `patch_nodes[]` for targeted updates to an existing flow.
+- Do not mix `patch_nodes` and full `spec` in the same call.
+
+## Supported public node types
+
+Use only `start`, `approve`, `fill`, `copy`, `webhook`, and `end`.
+
+Do not generate `branch` or `condition` nodes through `app_flow_apply`; the public CLI should return an unsupported-node error rather than write a visually broken flow.
+
+## Detailed workflow docs
+
+Use [workflow/README.md](./workflow/README.md) for full staged workflow modeling and [workflow/workflow-schema.json](./workflow/workflow-schema.json) for schema validation.

package/skills/qingflow-cli/reference/builder/99-publish-verify.md

@@ -0,0 +1,46 @@
+# Builder Publish And Readback Verification
+
+Read this before reporting a builder task as finished.
+
+## Scope
+
+Responsible for: `builder publish verify`, readback-before-retry, partial success interpretation, and final user-facing completion wording.
+
+Not responsible for: replacing resource-specific verification. Views, charts, portal, workflow, buttons, and associated resources still need their own apply/readback checks.
+
+## Main chain
+
+```text
+apply result -> resource readback -> publish verify when app resources changed -> final status
+```
+
+## Readback-before-retry rule
+
+If a write returns any of these, do not immediately replay the same write:
+
+- timeout
+- `partial_success`
+- `write_executed=true`
+- `safe_to_retry=false`
+- readback unavailable
+- backend readback 40002 after a write
+
+Next action:
+
+```text
+package get / app resolve / app get fields|layout|views|charts / portal get / publish verify
+```
+
+Then patch only the missing or mismatched resources.
+
+## Final report requirements
+
+Always state:
+
+- whether the intended write appears successful;
+- which path made it successful;
+- what is verified as front-end visible or published;
+- what remains unverified or incomplete;
+- whether further repair is needed.
+
+Do not report "全部完成" when required workflows, charts, relations, portal references, or readback checks are missing.

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

@@ -0,0 +1,41 @@
+# Builder Index
+
+This directory is for Qingflow system-building work through `qingflow builder ...`.
+
+## Choose the main path
+
+| Situation | Read |
+|-----------|------|
+| User asks for one app only | [10-build-single-app.md](./10-build-single-app.md) |
+| User asks for a complete system, app package, or several related apps | [20-build-complete-system.md](./20-build-complete-system.md) |
+| User asks to change one existing resource | Read that resource document directly: [fields](./30-schema-fields.md), [layout](./40-layout.md), [views](./50-views.md), [charts](./60-charts.md), [portal](./70-portal.md), [buttons/resources](./80-buttons-associated-resources.md), or [workflow](./90-workflow.md) |
+
+## Default build order
+
+```text
+package -> schema/apps -> layout -> workflow -> views -> charts -> buttons/resources -> portal -> publish/readback verify
+```
+
+Rules:
+
+- Complete systems create all app shells and relation fields with `builder schema apply --apps-file`; use `apps[].client_key` and `relation.target_app_ref`.
+- Single-app builds use one app path; do not add relation fields unless the user asks for cross-app modeling.
+- Update instructions live inside the resource document. Do not use `update-*` as a separate main route.
+- Batch read, batch write, and patch are resource-specific variants, not separate workflows.
+
+## File responsibilities
+
+| File | Responsibility |
+|------|----------------|
+| [10-build-single-app.md](./10-build-single-app.md) | One-app delivery order and completion standard |
+| [20-build-complete-system.md](./20-build-complete-system.md) | Multi-app package delivery order and relation strategy |
+| [30-schema-fields.md](./30-schema-fields.md) | Field types, schema apply, data title/cover, schema updates |
+| [40-layout.md](./40-layout.md) | Form grouping, rows matrix, layout updates |
+| [50-views.md](./50-views.md) | Table/card/board/gantt views, filters, query panel, view patches |
+| [60-charts.md](./60-charts.md) | QingBI chart create/update/remove/reorder, metrics, filters |
+| [70-portal.md](./70-portal.md) | Portal apply/delete, standard workbench layout, component config |
+| [80-buttons-associated-resources.md](./80-buttons-associated-resources.md) | Custom buttons, associated views/reports, context mappings |
+| [90-workflow.md](./90-workflow.md) | Flow presets, patch_nodes, workflow verification |
+| [99-publish-verify.md](./99-publish-verify.md) | Publish verification, partial success, readback-before-retry |
+
+Detailed historical playbooks and low-level notes start from [reference/app-delivery-sop.md](./reference/app-delivery-sop.md). Load them only when a main document points there or the main document is insufficient.

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

@@ -0,0 +1,130 @@
+# Qingflow CLI Code Block / Q-Linker Builder
+
+Use this section when the user wants to build or repair:
+- `code_block` fields
+- `q_linker` fields
+- output alias parsing
+- target field binding
+- form configurations that depend on code block or Q-Linker relations
+
+Do not use this section for generic field CRUD or runtime execution debugging unless those are strictly supporting code block or Q-Linker configuration work.
+
+## Core Rule
+
+Treat code blocks and Q-Linkers as **integration fields**, not ordinary fields.
+
+For both of them, the public builder request may look like one step, but the real backend form structure has multiple layers. Never invent a new backend meaning. Only compile into the backend structures that already exist.
+
+## Mental Model
+
+### Code block
+
+There are three conceptual layers:
+
+1. Code block field itself
+2. Parsed output aliases
+3. Target field bindings
+
+Current builder support:
+- configure the code block field itself
+- configure input insertion into code content
+- configure alias parsing
+
+Important:
+- keep `qf_output = {...}` as a plain assignment
+- do not emit `const qf_output =` or `let qf_output =`
+
+### Q-Linker
+
+There are two conceptual layers:
+
+1. Q-Linker field itself via `remoteLookupConfig`
+2. Target field bindings via relation-default + `questionRelations(relationType=Q_LINKER)`
+
+Current builder support:
+- one-step high-level config through `q_linker_binding`
+- internal compilation into existing backend payloads
+
+## Operating Order
+
+For code block or Q-Linker work, use this order:
+
+1. Resolve the app and read fields:
+   - `qingflow builder app resolve`
+   - `qingflow builder app get fields`
+2. Confirm the target field set already exists.
+3. Apply schema updates with `qingflow builder schema apply`.
+4. Read fields again and verify:
+   - field type
+   - alias config
+   - target field binding shape
+5. For page-safety checks, use user-side schema or insert checks:
+   - `qingflow record schema insert`
+   - optional safe `qingflow record insert`
+
+Do not treat raw apply success as enough. Always re-read the field config.
+
+## Code Block Rules
+
+Read [code-block.md](./code-block.md) before changing a code block field.
+
+Use builder high-level config only for:
+- input field insertion
+- code content
+- alias parsing
+- auto trigger
+- custom button text
+
+When binding outputs to target fields, do not guess payload shape from memory. Follow the current builder implementation and the readback shape.
+
+Hard rules:
+- target fields must already exist
+- keep target field types business-compatible
+- if a page starts hanging on “关联中”, inspect whether the target field default type or relation config was written incorrectly
+
+## Q-Linker Rules
+
+Read [q-linker.md](./q-linker.md) before changing a Q-Linker field.
+
+First-stage stable support is only:
+- custom mode
+- request config
+- alias parsing
+- target field binding
+- auto trigger / button text
+
+Do not generate:
+- template mode
+- openApp/light-wing branches
+- subtable table-match bindings
+
+Hard rules:
+- `outputs[*].target_field` is required
+- use only supported target field types
+- on rebinding, old target fields must be restored from relation-default to safe default type
+- `resultFormatPath` must preserve backend-required alias metadata
+
+## Verification Checklist
+
+After each code block or Q-Linker change, verify all of these:
+
+- `qingflow builder app get ... fields` shows the intended field type
+- the high-level config is readable and stable
+- target fields still have valid types
+- insert schema can be opened
+- record insert does not get blocked by malformed integration config
+
+If the task explicitly includes runtime verification, keep it separate from configuration verification.
+
+## Common Pitfalls
+
+- Writing code block code with `const qf_output =`
+- Treating a Q-Linker or code block binding as a plain field default
+- Forgetting to restore old target fields after unbinding
+- Using unsupported target field types
+- Assuming apply success means the form page can open
+
+## References
+
+- Code block details: [references/code-block.md](./code-block.md)
+- Q-Linker details: [references/q-linker.md](./q-linker.md)