@josephyan/qingflow-app-builder-mcp 0.2.0-beta.2 → 0.2.0-beta.4

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.2
+npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.4
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.2 qingflow-app-builder-mcp
+npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.4 qingflow-app-builder-mcp
 ```
 
 Environment:
@@ -19,3 +19,12 @@ Environment:
 - `QINGFLOW_MCP_HOME`
 
 This package bootstraps a local Python runtime on first install and then starts the `qingflow-app-builder-mcp` stdio MCP server.
+
+Bundled skill:
+
+- `skills/qingflow-app-builder`
+
+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).

package/npm/lib/runtime.mjs

@@ -29,6 +29,43 @@ export function getPackageRoot(metaUrl) {
   return path.resolve(path.dirname(fileURLToPath(metaUrl)), "..", "..");
 }
 
+export function getCodexHome() {
+  const configured = process.env.CODEX_HOME?.trim();
+  if (configured) {
+    return path.resolve(configured);
+  }
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (!home) {
+    throw new Error("Cannot resolve CODEX_HOME because HOME is not set.");
+  }
+  return path.join(home, ".codex");
+}
+
+export function installBundledSkills(packageRoot) {
+  const skillsSrc = path.join(packageRoot, "skills");
+  if (!fs.existsSync(skillsSrc)) {
+    return { installed: [], skipped: true, destination: null };
+  }
+
+  const codexHome = getCodexHome();
+  const skillsDestRoot = path.join(codexHome, "skills");
+  fs.mkdirSync(skillsDestRoot, { recursive: true });
+
+  const installed = [];
+  for (const entry of fs.readdirSync(skillsSrc, { withFileTypes: true })) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const src = path.join(skillsSrc, entry.name);
+    const dest = path.join(skillsDestRoot, entry.name);
+    fs.rmSync(dest, { recursive: true, force: true });
+    fs.cpSync(src, dest, { recursive: true });
+    installed.push(entry.name);
+  }
+
+  return { installed, skipped: false, destination: skillsDestRoot };
+}
+
 export function getVenvDir(packageRoot) {
   return path.join(packageRoot, ".npm-python");
 }

package/npm/scripts/postinstall.mjs

@@ -1,4 +1,4 @@
-import { ensurePythonEnv, getPackageRoot } from "../lib/runtime.mjs";
+import { ensurePythonEnv, getPackageRoot, installBundledSkills } from "../lib/runtime.mjs";
 
 const packageRoot = getPackageRoot(import.meta.url);
 
@@ -6,6 +6,10 @@ try {
   console.log("[qingflow-mcp] Bootstrapping Python runtime...");
   ensurePythonEnv(packageRoot, { commandName: "qingflow-app-builder-mcp" });
   console.log("[qingflow-mcp] Python runtime is ready.");
+  const skills = installBundledSkills(packageRoot);
+  if (!skills.skipped) {
+    console.log(`[qingflow-mcp] Installed skills to ${skills.destination}: ${skills.installed.join(", ")}`);
+  }
 } catch (error) {
   console.error(`[qingflow-mcp] postinstall failed: ${error.message}`);
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "0.2.0-beta.2",
+  "version": "0.2.0-beta.4",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",
@@ -18,7 +18,8 @@
     "src/qingflow_mcp/py.typed",
     "qingflow-app-builder-mcp",
     "npm/",
-    "docs/local-agent-install.md"
+    "docs/local-agent-install.md",
+    "skills/"
   ],
   "engines": {
     "node": ">=16.16.0"

package/pyproject.toml

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

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

@@ -0,0 +1,116 @@
+---
+name: qingflow-app-builder
+description: Build, configure, and modify Qingflow apps and systems after the MCP is already connected and authenticated. Use when the user wants to apply or repair an existing SolutionSpec, modify an existing package with app, view, workflow, portal, navigation, or reporting tools, verify builder-side results, or troubleshoot system-building behavior. Do not use this skill to install the MCP or to author a brand new SolutionSpec from scratch.
+metadata:
+  short-description: Build and modify Qingflow apps and systems
+---
+
+# Qingflow App Builder
+
+## Overview
+
+This skill helps a system builder use the AI-native Qingflow builder surface safely. It assumes the MCP is already connected and authenticated. If not, switch to `$qingflow-mcp-setup` first.
+
+Before any write or verification flow, identify whether the task targets `test` or `prod` and read [references/environments.md](references/environments.md). If the user did not specify one, default to `prod`.
+
+## Tool Selection
+
+Pick the smallest tool layer that can finish the task.
+
+- Authentication and workspace: `auth_*`, `workspace_*`
+- File upload: `file_upload_local`
+- Resource resolve/read: `package_list`, `package_resolve`, `app_resolve`, `app_read_summary`, `app_read_fields`, `app_read_layout_summary`, `app_read_views_summary`, `app_read_flow_summary`
+- Resource plan: `app_schema_plan`, `app_layout_plan`, `app_flow_plan`, `app_views_plan`
+- Resource patch: `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, `package_attach_app`
+- Publish and verify: `app_publish_verify`
+
+Note:
+- Do not try to handcraft raw Qingflow schema or internal solution payloads.
+- Do not rely on low-level `view_*`, `workflow_*`, or `qingbi_report_*` write payloads from public builder flows.
+- Public builder work should stay on the resource path: `resolve -> summary read -> plan -> apply -> attach -> publish_verify`.
+- `app_schema_apply` / `app_layout_apply` / `app_flow_apply` / `app_views_apply` publish by default; pass `publish=false` only when you intentionally want to leave changes in draft.
+
+Default policy:
+
+- Creating or updating one app inside an existing package: resolve the package/app, read compact state, plan patches on the server, then apply schema/layout/flow/views patches explicitly.
+- Do not create a new package unless the user explicitly asks for package separation.
+
+## Standard Operating Order
+
+Before any business tool:
+
+1. Ensure auth exists
+2. Ensure workspace is selected
+3. Confirm whether the task is read-only or write-impacting
+
+For builder work:
+
+1. Resolve the target package with `package_resolve` when the user gives a package name. If resolution is ambiguous or you need a read-only fallback, use `package_list`.
+2. Resolve the target app with `app_resolve` if the request is an update.
+3. Read only the smallest summary you need: `app_read_summary`, `app_read_fields`, `app_read_layout_summary`, `app_read_views_summary`, `app_read_flow_summary`.
+4. Use `app_schema_plan`, `app_layout_plan`, `app_flow_plan`, or `app_views_plan` before any non-trivial write.
+5. Use `app_schema_apply` for create/upsert/remove field work. It publishes by default after the patch lands.
+6. If the app must belong to a package, use `package_attach_app` explicitly after schema work unless readback already shows the target `tag_id`.
+7. Use `app_layout_apply` only when the user is explicitly changing layout. Prefer the default `mode=merge`; use `mode=replace` only when you intend to place every field explicitly. It publishes by default.
+8. Use `app_flow_apply` after schema exists. It publishes by default.
+9. Use `app_views_apply` when the user wants explicit list/card/board views. It publishes by default.
+10. Use `app_publish_verify` only when the user explicitly wants final publish/live verification or you need an explicit verification pass.
+
+In `prod`, keep `plan` and `apply` as separate phases unless the user explicitly asks for a direct live execution.
+
+For additive work on existing systems:
+
+1. Confirm the target package or existing apps
+2. Avoid creating a new package unless the user explicitly wants a separate solution
+3. Use ordinary low-level tools for incremental change
+4. Re-verify the affected apps, views, workflows, or portal after modification
+
+## Safe Usage Rules
+
+- When using `package_name`, expect deterministic resolution only on a unique exact package name match; if multiple packages match, stop and resolve the ambiguity instead of guessing
+- `app_schema_apply` is the only public patch tool allowed to create an app shell; `app_layout_apply`, `app_flow_apply`, and `app_views_apply` require an existing app.
+- Prefer `*_plan` before `*_apply`; the plan tools do server-side normalization and return the next executable call skeleton.
+- `app_schema_apply` does not treat package attachment as success criteria; if package ownership matters, verify `tag_ids_after` and call `package_attach_app` explicitly.
+- `package_attach_app` is the source of truth for package ownership; do not assume app creation or publish implicitly attaches the app.
+- `relation` and `subtable` must be explicit; do not infer them from vague natural language.
+- In `prod`, prefer explicit patch tools and avoid any speculative create flow.
+
+## Response Interpretation
+
+- low-level list totals from the backend may report `0` while rows are present; prefer summary or aggregate readbacks for final conclusions
+- `app_publish_verify` is the publish source of truth.
+- If readback mismatches the UI, compare `request_route` and do not assume the builder hit the same `qf_version` as the browser
+- Treat post-write readback as the source of truth, not just write status codes
+
+## Practical Patterns
+
+- List packages: `package_list`
+- Resolve one package: `package_resolve`
+- Resolve one app: `app_resolve`
+- Read one app summary: `app_read_summary`
+- Read fields only: `app_read_fields`
+- Read layout summary: `app_read_layout_summary`
+- Read views summary: `app_read_views_summary`
+- Read flow summary: `app_read_flow_summary`
+- Plan schema patch: `app_schema_plan`
+- Plan layout patch: `app_layout_plan`
+- Plan workflow patch: `app_flow_plan`
+- Plan view patch: `app_views_plan`
+- Add/update/remove fields: `app_schema_apply`
+- Merge or replace layout: `app_layout_apply`
+- Replace workflow: `app_flow_apply`
+- Upsert/remove views: `app_views_apply`
+- Attach one app to a package: `package_attach_app`
+- Publish and verify: `app_publish_verify` when you need a separate verification pass beyond the default auto-publish behavior in apply tools
+
+Detailed playbooks:
+
+- Environment switching: [references/environments.md](references/environments.md)
+- Tool choice and sequencing: [references/tool-selection.md](references/tool-selection.md)
+- Result semantics and gotchas: [references/gotchas.md](references/gotchas.md)
+- Create one app in an existing package: [references/create-app.md](references/create-app.md)
+- Update fields only: [references/update-schema.md](references/update-schema.md)
+- Update layout only: [references/update-layout.md](references/update-layout.md)
+- Update workflow only: [references/update-flow.md](references/update-flow.md)
+- 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)

package/skills/qingflow-app-builder/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Qingflow App Builder"
+  short_description: "Build and modify Qingflow apps and systems"
+  default_prompt: "Use $qingflow-app-builder to build or modify a Qingflow app or system safely, and verify environment routing and post-write readbacks when builder flows touch live data."

package/skills/qingflow-app-builder/references/create-app.md

@@ -0,0 +1,98 @@
+# Create App
+
+Use this when the user wants one new app inside an existing package.
+
+## Minimal sequence
+
+1. `package_resolve`
+2. `app_resolve`
+3. `app_schema_plan`
+4. `app_schema_apply`
+5. `package_attach_app`
+6. `app_publish_verify` only when the user asks for explicit final verification
+
+## Example
+
+Resolve the package:
+
+```json
+{
+  "tool_name": "package_resolve",
+  "arguments": {
+    "profile": "default",
+    "package_name": "测试应用包"
+  }
+}
+```
+
+Plan schema for a new app:
+
+```json
+{
+  "tool_name": "app_schema_plan",
+  "arguments": {
+    "profile": "default",
+    "app_name": "客户订单",
+    "package_tag_id": 1218950,
+    "create_if_missing": true,
+    "add_fields": [
+      {"name": "订单编号", "type": "text", "required": true},
+      {"name": "客户名称", "type": "text", "required": true},
+      {"name": "订单金额", "type": "amount"},
+      {"name": "状态", "type": "single_select", "options": ["草稿", "进行中", "已完成"], "required": true}
+    ],
+    "update_fields": [],
+    "remove_fields": []
+  }
+}
+```
+
+Apply schema. This publishes by default:
+
+```json
+{
+  "tool_name": "app_schema_apply",
+  "arguments": {
+    "profile": "default",
+    "app_name": "客户订单",
+    "package_tag_id": 1218950,
+    "create_if_missing": true,
+    "publish": true,
+    "add_fields": [
+      {"name": "订单编号", "type": "text", "required": true},
+      {"name": "客户名称", "type": "text", "required": true},
+      {"name": "订单金额", "type": "amount"},
+      {"name": "状态", "type": "single_select", "options": ["草稿", "进行中", "已完成"], "required": true}
+    ],
+    "update_fields": [],
+    "remove_fields": []
+  }
+}
+```
+
+Attach explicitly if `tag_ids_after` does not yet contain the package:
+
+```json
+{
+  "tool_name": "package_attach_app",
+  "arguments": {
+    "profile": "default",
+    "tag_id": 1218950,
+    "app_key": "APP_KEY_FROM_SCHEMA_APPLY"
+  }
+}
+```
+
+## Common failures
+
+### `APP_NOT_FOUND`
+
+Expected on create. Continue with `create_if_missing=true`.
+
+### `CREATE_APP_ROUTE_NOT_FOUND`
+
+The create route did not resolve in the current backend route context. Re-run `workspace_select`, then retry the same `app_schema_apply`.
+
+### `PACKAGE_ATTACH_FAILED`
+
+Do not retry schema creation. Re-run only `package_attach_app`, then verify with `app_read_summary`.

package/skills/qingflow-app-builder/references/environments.md

@@ -0,0 +1,63 @@
+# Environment Switching
+
+Use this reference before any builder-side write, repair, or verification flow.
+
+## Step 1: Resolve the active environment
+
+Decide explicitly whether the task targets:
+
+- `test`: build validation, mock data, trial package creation, safe iteration
+- `prod`: formal business system changes in the live environment
+
+If the user did not specify an environment, default to `prod`.
+
+## Test Environment
+
+Use test for:
+
+- first application of a new `SolutionSpec`
+- trying `solution_build_all(..., verify=true)`
+- package initialization and schema evolution experiments
+- mock data creation, with at least `5` records per relevant entity unless the user asks for fewer
+
+Builder behavior in test:
+
+- `preflight` or `plan` is still preferred, but fast `apply` is acceptable when the user explicitly wants an end-to-end smoke test
+- package creation is acceptable
+- verify should read back apps, views, portal, navigation, and sample records
+
+Known current test backend:
+
+- use an explicitly provided non-production backend
+
+## Production Environment
+
+Use production for:
+
+- changes to real business systems
+- additive modifications to live packages and apps
+- controlled rollout of approved solution specs
+
+Builder behavior in prod:
+
+- always identify the target package or app set before changing anything
+- default to `preflight` or `plan` before any `apply`
+- additive requirements should modify the existing package with ordinary tools by default
+- do not create a new package unless the user explicitly wants package separation
+- do not seed mock data unless the user explicitly approves it for production
+- verify is mandatory after writes
+
+Production guardrails:
+
+- restate the target workspace and target package before any write
+- call out whether the action creates, mutates, or deletes builder-side configuration
+- if a safer read-only inspection can answer the request, do that first
+
+## Reporting Rule
+
+For builder work, always report:
+
+- active environment
+- target workspace
+- whether the operation is `plan`, `apply`, `repair`, or `verify`
+- whether it touches an existing package or creates a new one

package/skills/qingflow-app-builder/references/gotchas.md

@@ -0,0 +1,37 @@
+# Builder Gotchas
+
+## Auth and workspace
+
+- `auth_*` success does not mean a workspace is selected
+- Re-run `workspace_select` after auth changes or route changes
+
+## Package ownership
+
+- App creation and publish do not guarantee package attachment
+- Treat `package_attach_app` as the source of truth for package ownership
+- Check `tag_ids_after` after schema writes
+
+## Auto publish
+
+- `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, and `app_views_apply` publish by default
+- Pass `publish=false` only when the user explicitly wants to leave changes in draft
+- `app_publish_verify` is for explicit final verification, not the default next step after every write
+
+## Readback scope
+
+- Prefer summary reads over large raw payloads
+- Use `app_read_fields` before schema or view work
+- Use `app_read_layout_summary` before layout work
+- Use `app_read_flow_summary` before workflow work
+
+## Workflow dependencies
+
+- Approval-style flows usually require an explicit status field
+- If `app_flow_plan` reports `FLOW_DEPENDENCY_MISSING`, fix schema first
+- Do not switch to hidden `solution_*` tools from public builder flows
+
+## Retry discipline
+
+- If a write returns `partial_success`, read back before retrying
+- Do not repeat create steps after `app_key` already exists
+- For backend rejects, keep the retry narrow: retry only the failed tool, not the whole chain

package/skills/qingflow-app-builder/references/solution-playbooks.md

@@ -0,0 +1,51 @@
+# Builder Playbooks
+
+Use these when you need a quick reminder of the standard v2 builder sequences.
+
+## Create a new app in an existing package
+
+1. `package_resolve`
+2. `app_resolve`
+3. `app_schema_plan`
+4. `app_schema_apply`
+5. `package_attach_app`
+6. `app_publish_verify` only if the user asks for explicit live verification
+
+## Update fields on an existing app
+
+1. `app_resolve`
+2. `app_read_fields`
+3. `app_schema_plan`
+4. `app_schema_apply`
+
+## Rework layout
+
+1. `app_read_layout_summary`
+2. `app_layout_plan`
+3. `app_layout_apply`
+
+Prefer `mode=merge`. Use `mode=replace` only when every field placement is intentional.
+
+## Add or update workflow
+
+1. `app_read_fields`
+2. `app_flow_plan`
+3. `app_flow_apply`
+
+If `app_flow_plan` reports `FLOW_DEPENDENCY_MISSING`, fix schema first.
+
+## Add or update views
+
+1. `app_read_fields`
+2. `app_views_plan`
+3. `app_views_apply`
+
+## Final readback
+
+Prefer these fields after writes:
+
+- `app_read_summary.tag_ids`
+- `app_read_summary.publish_status`
+- `app_read_layout_summary.unplaced_fields`
+- `app_read_views_summary.views`
+- `app_read_flow_summary.nodes`

package/skills/qingflow-app-builder/references/tool-selection.md

@@ -0,0 +1,65 @@
+# Tool Selection
+
+Use the smallest v2 builder tool chain that can finish the task.
+
+## Default path
+
+`resolve -> summary read -> plan -> apply -> attach -> publish_verify`
+
+Use `plan` before `apply` unless the patch is trivial and already normalized.
+
+## Resolve
+
+- `package_resolve`: exact package lookup by name
+- `package_list`: read-only fallback when package resolution is ambiguous
+- `app_resolve`: locate an existing app by `app_key` or `app_name`
+
+## Summary reads
+
+- `app_read_summary`: overall app health, publish state, counts
+- `app_read_fields`: field names, types, required flags, section ids
+- `app_read_layout_summary`: sections, rows, unplaced fields
+- `app_read_views_summary`: current view names, types, columns, group-by
+- `app_read_flow_summary`: workflow enabled state, nodes, transitions
+
+## Plan tools
+
+Use these when the patch is non-trivial or the model is likely to drift.
+
+- `app_schema_plan`: normalize field patches before add/update/remove
+- `app_layout_plan`: preview merge/replace layout changes or layout presets
+- `app_flow_plan`: validate workflow nodes, transitions, and dependencies
+- `app_views_plan`: normalize view aliases and validate referenced fields
+
+## Apply tools
+
+These execute normalized patches and publish by default unless `publish=false`.
+
+- `app_schema_apply`: create app shell or change fields
+- `app_layout_apply`: merge or replace layout
+- `app_flow_apply`: replace workflow
+- `app_views_apply`: upsert or remove views
+
+## Explicit post-apply tools
+
+- `package_attach_app`: attach an app to a package; do not assume create or publish attaches it
+- `app_publish_verify`: explicit final publish verification when the user asks for live confirmation
+
+## Decision shortcuts
+
+- Create one app inside an existing package:
+  `package_resolve -> app_resolve -> app_schema_plan -> app_schema_apply -> package_attach_app`
+- Update fields on an existing app:
+  `app_resolve -> app_read_fields -> app_schema_plan -> app_schema_apply`
+- Tidy layout:
+  `app_read_layout_summary -> app_layout_plan -> app_layout_apply`
+- Add workflow:
+  `app_read_fields -> app_flow_plan -> app_flow_apply`
+- Add views:
+  `app_read_fields -> app_views_plan -> app_views_apply`
+
+## Avoid
+
+- Do not handcraft raw Qingflow schema payloads
+- Do not rely on internal `solution_*` tools in public builder flows
+- Do not create a new package unless the user explicitly asks for package separation

package/skills/qingflow-app-builder/references/update-flow.md

@@ -0,0 +1,71 @@
+# Update Flow
+
+Use this when the app already exists and the task is only about workflow.
+
+## Minimal sequence
+
+1. `app_read_fields`
+2. `app_read_flow_summary`
+3. `app_flow_plan`
+4. `app_flow_apply`
+
+## Example
+
+Plan a simple approval flow:
+
+```json
+{
+  "tool_name": "app_flow_plan",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "preset": "basic_approval"
+  }
+}
+```
+
+Or use explicit nodes:
+
+```json
+{
+  "tool_name": "app_flow_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "mode": "replace",
+    "publish": true,
+    "nodes": [
+      {"id": "start", "type": "start", "name": "发起"},
+      {"id": "approve_1", "type": "approve", "name": "审批"},
+      {"id": "end", "type": "end", "name": "结束"}
+    ],
+    "transitions": [
+      {"from": "start", "to": "approve_1"},
+      {"from": "approve_1", "to": "end"}
+    ]
+  }
+}
+```
+
+## Common failures
+
+### `FLOW_DEPENDENCY_MISSING`
+
+The workflow depends on fields that do not exist yet, usually `status`. Fix schema first.
+
+### `INVALID_FLOW_EDGE`
+
+One or more transitions reference unknown nodes or create an invalid graph.
+
+### `STATUS_FIELD_REQUIRED`
+
+The app has no explicit status field recognized by the internal workflow compiler. Add one with `app_schema_apply`, then retry.
+
+### `FLOW_STAGE_CONTEXT_MISSING`
+
+Internal flow stage context was missing or invalid. Re-run `app_flow_plan`, then retry `app_flow_apply`. Do not switch to hidden `solution_*` tools.
+
+## Notes
+
+- `mode=replace` is the only supported flow apply mode
+- `app_flow_apply` publishes by default