@qingflow-tech/qingflow-cli 1.1.2 → 1.1.34

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

@@ -0,0 +1,62 @@
+# 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), [associated resources](./80-buttons-associated-resources.md), or [workflow](./90-workflow.md) |
+
+## Decision gate before writing
+
+| Evidence | Action |
+|----------|--------|
+| User gives an `app_key`, `view_key`, `chart_id`, `dash_key`, or exact existing package id | Treat the task as an update to that existing target unless the user explicitly asks for a new one |
+| User names several business objects/forms/modules, or asks for a “系统 / 应用包” | Use the complete-system path; do not compress them into one app |
+| Same or very similar package/app already exists and user did not say extend or replace | Stop and ask whether to extend existing, repair missing parts, or create a new package/app |
+| Existing readback already contains part of the requested system | List the verified existing resources, identify gaps, and patch only missing/incorrect slices |
+| Write timed out, returned `partial_success`, `write_executed=true`, or `safe_to_retry=false` | Read back before retrying; do not create `V2`, `测试`, timestamp, or random-suffix resources |
+
+## Default build order
+
+```text
+package -> schema/apps with form -> workflow if requested/needed -> views -> portal with chart -> publish/readback verify
+```
+
+Rules:
+
+- Complete systems create app shells, fields, relation fields, and form layout with one `builder schema apply --apps-file` call.
+- Complete systems use exactly one main schema shape: `{package_id, apps}`, with each app carrying `client_key + app_name + icon + color + form`.
+- Same-batch relations use `relation.target_app_ref` pointing to another `apps[].client_key`; do not create apps first just to get `target_app_key`.
+- Complete systems and new single apps define fields through `form`; fields and form sections/rows are one creation intent.
+- Do not use `add_fields`, separate `layout` payloads, or `builder layout apply` for new app creation. Use them only for existing-app maintenance.
+- Single-app builds use one app path; do not add relation fields unless the user asks for cross-app modeling.
+- Workflow is conditional: build it only when the user asks for approval, fill/copy, reminders, process routing, task handling, or the business process clearly cannot work without it.
+- Portal chart sections use one `chart` field: `{"chart_id":"..."}` to reuse an existing QingBI chart, or `{"app_key":"...","name":"...","chart_type":"...",...}` to create/update the needed chart inline.
+- Buttons are part of the view design: declare them in the target view with `action_buttons`.
+- 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) | Existing-app form layout maintenance only; new app creation uses `form` in schema apply |
+| [50-views.md](./50-views.md) | Table/card/board/gantt views, filters, query panel, view patches, ordinary view action buttons |
+| [60-charts.md](./60-charts.md) | Standalone QingBI chart maintenance; portal dashboards normally use section `chart` for missing reports |
+| [70-portal.md](./70-portal.md) | Portal apply/delete, standard workbench layout, component config, section `chart` |
+| [80-buttons-associated-resources.md](./80-buttons-associated-resources.md) | Associated views/reports and context mappings; standalone button maintenance only when the user explicitly asks to maintain existing button bodies outside view design |
+| [90-workflow.md](./90-workflow.md) | WorkflowSpec, patch_nodes, workflow verification |
+| [99-publish-verify.md](./99-publish-verify.md) | Publish verification, partial success, readback-before-retry |
+
+## Example files
+
+Use [../examples/README.md](../examples/README.md) as the example index. Main build documents stay concise; full JSON bases live under `reference/examples/<resource>/`.
+
+Low-level historical notes start from [reference/app-delivery-sop.md](./reference/app-delivery-sop.md). Do not use them to choose the app/relation/layout creation path; the current creation path is this index plus [20-build-complete-system.md](./20-build-complete-system.md) and [30-schema-fields.md](./30-schema-fields.md).

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)

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.