@josephyan/qingflow-app-builder-mcp 1.1.26 → 1.1.27

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-builder-mcp@1.1.26
+npm install @josephyan/qingflow-app-builder-mcp@1.1.27
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-builder-mcp@1.1.26 qingflow-app-builder-mcp
+npx -y -p @josephyan/qingflow-app-builder-mcp@1.1.27 qingflow-app-builder-mcp
 ```
 
 Environment:
@@ -30,5 +30,6 @@ Bundled skills:
 Note:
 
 - The skill files are included in the npm package.
-- On install, the package copies them to `$CODEX_HOME/skills` (or `~/.codex/skills` if `CODEX_HOME` is unset).
+- On install, the package installs bundled skills into `$CODEX_HOME/skills` (or `~/.codex/skills` if `CODEX_HOME` is unset) by symlink and refreshes them on package updates.
+- You can also run `qingflow-app-builder-mcp skills list` or `qingflow-app-builder-mcp skills install --agent codex|claude-code|cursor|generic --scope user|project [--copy] [--force]`.
 - If a stdio MCP client reports `Transport closed`, delete `.npm-python`, reinstall the package, and make sure CLI/user/builder packages are on the same version. The stdio entrypoints refuse runtime bootstrap so install logs never corrupt MCP stdout.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "1.1.26",
+  "version": "1.1.27",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

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

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

@@ -7,6 +7,8 @@ metadata:
 
 # Qingflow App Builder
 
+> **Skill 版本**：`qingflow-skills-2026.06.30.1`
+
 ## Overview
 
 This skill is for the current **public builder surface**, not for legacy low-level builder writes.
@@ -35,10 +37,10 @@ Default modeling rules:
 ## Public Tools You Should Think In
 
 - Package: `package_get`, `package_apply`
-- App reads: `app_resolve`, `app_get`, `app_get_fields`, `app_get_layout`, `app_get_views`, `app_get_flow`, `app_get_charts`, `app_get_buttons`, `app_get_associated_resources`
+- App reads: `app_resolve`, `app_get`, `app_get_fields`, `app_get_layout`, `app_get_views`, `app_get_flow`, `app_get_charts`, `app_get_associated_resources`
 - Builder reads: `portal_list`, `portal_get`, `view_get`, `chart_get`, `builder_tool_contract`
 - Directory: `member_search`, `role_search`, `role_create`
-- Writes: `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, `app_custom_buttons_apply`, `app_associated_resources_apply`, `app_charts_apply`, `portal_apply`, `app_release_edit_lock_if_mine`
+- Writes: `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, `app_associated_resources_apply`, `app_charts_apply`, `portal_apply`, `app_release_edit_lock_if_mine`
 - Verification: `app_publish_verify`
 - Cross-cutting escalation: `feedback_submit` after explicit user confirmation when the public builder surface still cannot satisfy the user's need
 
@@ -51,40 +53,35 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - use `package_apply(...)` for package creation, rename, icon, visibility, grouping, ordering, and app/portal layout
 - Multi-app schema work:
   - use one `app_schema_apply(apps=[...])` / CLI `builder schema apply --apps-file` when creating several apps in one package
+  - put form layout directly in `apps[].form.sections`; the CLI writes it in the same schema save as fields and relations
   - same-call relation fields may use `target_app_ref` to point at another `apps[].client_key`
 - 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`
-  - 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
+  - for existing views, associated resources, and charts, prefer `patch_views` / `patch_resources` / `patch_charts`
+  - each patch item uses the object's real selector field (`view_key` / `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
+  - complete-system portals create QingBI charts inline through `sections[].chart`; do not pre-create charts as the standard route
   - 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:
+- Standalone chart maintenance:
   - `app_charts_apply` is the public write path for app-source QingBI report bodies/configs; it creates/updates reports with `dataSourceType=qingflow`
+  - do not use it as the standard complete-system route; complete-system portals should inline QingBI charts through `portal_apply sections[].chart`
   - 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
+- View action work:
+  - declare button configuration only inside `app_views_apply` view items with `action_buttons`
+  - design the view and its available actions together
+  - use `field_mappings` for dynamic current-record values, including system fields such as `数据ID` and `编号`
   - if field type compatibility is unclear, read [references/match-rules.md](references/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`
@@ -98,6 +95,8 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - if field type compatibility is unclear, read [references/match-rules.md](references/match-rules.md)
 - Views and flows:
   - stay on `app_views_apply` / `app_flow_apply`
+  - new views use top-level `views[]`; the same batch may mix same-app and cross-app views
+  - buttons belong in view `action_buttons`
   - 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 `builder_tool_contract` whenever the minimal legal shape is unclear
@@ -116,7 +115,7 @@ Treat these as the official surface. Do not default to `package_create`, `packag
    - 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)
+   - app map -> `app_get` (default entry; includes compact views, charts, 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
@@ -125,11 +124,10 @@ Treat these as the official surface. Do not default to `package_create`, `packag
    - portal -> `portal_get`
 6. If the public shape is unclear, call `builder_tool_contract`
 7. Apply the smallest patch tool that fits:
-   - fields -> `app_schema_apply`
-   - layout -> `app_layout_apply`
+   - fields and form layout -> `app_schema_apply`
+   - layout-only maintenance -> `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`
@@ -142,7 +140,7 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - 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.
+- Always pass `publish: true` (or CLI `--publish`) explicitly on `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, and `portal_apply` when those tools are used directly. `app_associated_resources_apply` publishes automatically after at least one write succeeds and does 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 `builder_tool_contract`.
@@ -185,72 +183,23 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - 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`
+- Merge or replace layout-only changes on an existing app: `app_layout_apply`
 - Replace workflow: `app_flow_apply`
 - Upsert/patch/remove views: `app_views_apply`
-- Upsert/patch/remove custom buttons and bind them to header/detail view positions: `app_custom_buttons_apply`
 - Upsert/patch/remove app associated reports/views and per-view display: `app_associated_resources_apply`
 - Upsert/patch/remove/reorder charts: `app_charts_apply`
 - Create or update 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.
-
-```json
-{
-  "tool_name": "app_custom_buttons_apply",
-  "arguments": {
-    "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.
-
 ## Playbook Selection
 
 Before starting any build or create task, route to the right reference first:
 
 | User intent | Signal phrases | Playbook |
 |-------------|---------------|---------|
-| Multi-app business system with cross-app relations, shared workflow, and a portal dashboard | "建一套系统"、"包含 N 个模块"、"这几个表单之间建立关联"、"完整的业务系统" | [build-complete-system.md](references/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的应用" | [build-single-app.md](references/build-single-app.md) |
+| Multi-app business system with cross-app relations and a portal workbench | "建一套系统"、"包含 N 个模块"、"这几个表单之间建立关联"、"完整的业务系统" | [build-complete-system.md](references/build-complete-system.md) |
+| Single app end-to-end: schema, form layout, views, view actions, optional workflow, and verification | "建一个应用"、"帮我搭一个XX管理"、"从零开始建一个XX"、"我需要一个管理XX的应用" | [build-single-app.md](references/build-single-app.md) |
 | Add one new app inside an existing package | "在这个包里加一个表单"、"现有系统里新增一个模块" | [create-app.md](references/create-app.md) |
 | Update fields or schema only | "加一个字段"、"改字段名"、"删除字段" | [update-schema.md](references/update-schema.md) |
 | Update layout only | "调整分组"、"改排列顺序" | [update-layout.md](references/update-layout.md) |
@@ -274,4 +223,4 @@ Decision rule: if the user mentions **multiple related apps or a portal**, use `
 - Update views only: [references/update-views.md](references/update-views.md)
 - Standard end-to-end builder sequences: [references/solution-playbooks.md](references/solution-playbooks.md)
 - Build a complete multi-app system from scratch: [references/build-complete-system.md](references/build-complete-system.md)
-- Build a single app end-to-end (schema + layout + flow + views + buttons + charts + associated resources + data): [references/build-single-app.md](references/build-single-app.md)
+- Build a single app end-to-end (schema + form layout + views + view actions + optional workflow + verification): [references/build-single-app.md](references/build-single-app.md)