@josephyan/qingflow-app-builder-mcp 0.2.0-beta.9 → 0.2.0-beta.91

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.9
+npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.91
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.9 qingflow-app-builder-mcp
+npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.91 qingflow-app-builder-mcp
 ```
 
 Environment:
@@ -20,11 +20,13 @@ Environment:
 
 This package bootstraps a local Python runtime on first install and then starts the `qingflow-app-builder-mcp` stdio MCP server.
 
-Bundled skill:
+Bundled skills:
 
 - `skills/qingflow-app-builder`
+- `skills/qingflow-app-builder-code-integrations`
 
 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).
+- 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/docs/local-agent-install.md

@@ -1,9 +1,10 @@
 # 本地智能体安装
 
-这个目录下现在只保留两个本地命令入口：
+这个目录下现在有三个本地命令入口：
 
-1. 记录/待办优先的 `qingflow-app-user-mcp`
-2. 精简 builder 的 `qingflow-app-builder-mcp`
+1. 统一 CLI：`qingflow`
+2. 记录/待办优先的 `qingflow-app-user-mcp`
+3. 精简 builder 的 `qingflow-app-builder-mcp`
 
 ## npm 安装器适用场景
 
@@ -62,6 +63,7 @@ npm run pack:npm
 会生成：
 
 ```bash
+dist/npm/josephyan-qingflow-cli-<version>.tgz
 dist/npm/josephyan-qingflow-app-user-mcp-<version>.tgz
 dist/npm/josephyan-qingflow-app-builder-mcp-<version>.tgz
 ```
@@ -69,6 +71,7 @@ dist/npm/josephyan-qingflow-app-builder-mcp-<version>.tgz
 然后在目标机器安装：
 
 ```bash
+npm install /absolute/path/to/dist/npm/josephyan-qingflow-cli-<version>.tgz
 npm install /absolute/path/to/dist/npm/josephyan-qingflow-app-user-mcp-<version>.tgz
 npm install /absolute/path/to/dist/npm/josephyan-qingflow-app-builder-mcp-<version>.tgz
 ```
@@ -78,7 +81,7 @@ npm install /absolute/path/to/dist/npm/josephyan-qingflow-app-builder-mcp-<versi
 1. 创建 `.npm-python/`
 2. 在其中建立 Python 虚拟环境
 3. 执行 `pip install .`
-4. 在安装位置暴露 `qingflow-app-user-mcp`、`qingflow-app-builder-mcp` 命令
+4. 在安装位置暴露 `qingflow`、`qingflow-app-user-mcp`、`qingflow-app-builder-mcp` 命令
 
 ## 本地验证
 
@@ -86,6 +89,7 @@ npm install /absolute/path/to/dist/npm/josephyan-qingflow-app-builder-mcp-<versi
 
 ```bash
 cd qingflow-support/mcp-server
+node ./npm/bin/qingflow.mjs --help
 node ./npm/bin/qingflow-app-user-mcp.mjs
 node ./npm/bin/qingflow-app-builder-mcp.mjs
 ```
@@ -93,6 +97,7 @@ node ./npm/bin/qingflow-app-builder-mcp.mjs
 如果你是全局安装：
 
 ```bash
+qingflow --help
 qingflow-app-user-mcp
 qingflow-app-builder-mcp
 ```
@@ -100,6 +105,7 @@ qingflow-app-builder-mcp
 如果你是把包安装到了某个本地 agent workspace，命令通常位于：
 
 ```bash
+/absolute/path/to/agent-workspace/node_modules/.bin/qingflow
 /absolute/path/to/agent-workspace/node_modules/.bin/qingflow-app-user-mcp
 /absolute/path/to/agent-workspace/node_modules/.bin/qingflow-app-builder-mcp
 ```
@@ -107,6 +113,7 @@ qingflow-app-builder-mcp
 如果你是从 tgz 安装到某个空目录，命令通常位于：
 
 ```bash
+/absolute/path/to/install-dir/node_modules/.bin/qingflow
 /absolute/path/to/install-dir/node_modules/.bin/qingflow-app-user-mcp
 /absolute/path/to/install-dir/node_modules/.bin/qingflow-app-builder-mcp
 ```
@@ -202,7 +209,7 @@ qingflow-app-builder-mcp
 ```
 
 说明：
-- 源码目录 `npm install` 不会把命令加到全局 PATH；这种模式请用 `node ./npm/bin/qingflow-app-user-mcp.mjs` 或 `node ./npm/bin/qingflow-app-builder-mcp.mjs`
+- 源码目录 `npm install` 不会把命令加到全局 PATH；这种模式请用 `node ./npm/bin/qingflow.mjs`、`node ./npm/bin/qingflow-app-user-mcp.mjs` 或 `node ./npm/bin/qingflow-app-builder-mcp.mjs`
 - `npx` 方式适合临时安装或容器化本地 agent
 - 全局安装方式更适合长期固定使用的本机开发环境
 
@@ -226,3 +233,12 @@ rm -rf .npm-python
 ```bash
 npm install
 ```
+
+如果 MCP 客户端一调用工具就报 `Transport closed`，优先检查这几件事：
+
+1. 不要混用不同版本的 `@josephyan/qingflow-cli`、`@josephyan/qingflow-app-user-mcp`、`@josephyan/qingflow-app-builder-mcp`
+2. 删除安装目录下的 `.npm-python`
+3. 重新执行 `npm install` 或重新安装对应 tgz/npm 包
+4. 再启动 MCP 客户端
+
+现在 stdio MCP 入口会拒绝在启动瞬间“边启动边重建 Python 运行时”，因为安装日志一旦写进 stdout，就会破坏 MCP 握手并表现成 `Transport closed`。如果运行时缺失或版本不一致，入口会直接报错并提示重装，而不是静默自修复。

package/npm/bin/qingflow-app-builder-mcp.mjs

@@ -4,4 +4,4 @@ import { getPackageRoot, spawnServer } from "../lib/runtime.mjs";
 
 const packageRoot = getPackageRoot(import.meta.url);
 
-spawnServer(packageRoot, process.argv.slice(2), "qingflow-app-builder-mcp");
+spawnServer(packageRoot, process.argv.slice(2), "qingflow-app-builder-mcp", { allowRuntimeBootstrap: false });

package/npm/lib/runtime.mjs

@@ -7,14 +7,16 @@ const WINDOWS = process.platform === "win32";
 
 function runChecked(command, args, options = {}) {
   const result = spawnSync(command, args, {
-    stdio: "inherit",
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
     ...options,
   });
   if (result.error) {
     throw result.error;
   }
   if (result.status !== 0) {
-    throw new Error(`Command failed: ${command} ${args.join(" ")}`);
+    const details = [result.stderr, result.stdout].filter((value) => typeof value === "string" && value.trim()).join("\n");
+    throw new Error(details ? `Command failed: ${command} ${args.join(" ")}\n${details}` : `Command failed: ${command} ${args.join(" ")}`);
   }
 }
 
@@ -82,6 +84,105 @@ export function getVenvServerCommand(packageRoot, commandName = "qingflow-mcp")
     : path.join(getVenvDir(packageRoot), "bin", commandName);
 }
 
+function readPackageVersion(packageRoot) {
+  const packageJsonPath = path.join(packageRoot, "package.json");
+  try {
+    const payload = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    return typeof payload.version === "string" && payload.version.trim() ? payload.version.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+function readBootstrapStamp(stampPath) {
+  if (!fs.existsSync(stampPath)) {
+    return { exists: false, version: null };
+  }
+  try {
+    const payload = JSON.parse(fs.readFileSync(stampPath, "utf8"));
+    const version = typeof payload.package_version === "string" && payload.package_version.trim() ? payload.package_version.trim() : null;
+    return { exists: true, version };
+  } catch {
+    return { exists: true, version: null };
+  }
+}
+
+export function inspectPythonEnv(packageRoot, commandName = "qingflow-mcp") {
+  const venvDir = getVenvDir(packageRoot);
+  const serverCommand = getVenvServerCommand(packageRoot, commandName);
+  const stampPath = path.join(venvDir, ".bootstrap.json");
+  const packageVersion = readPackageVersion(packageRoot);
+  const stamp = readBootstrapStamp(stampPath);
+  const problems = [];
+
+  if (!packageVersion) {
+    problems.push("package-version-missing");
+  }
+  if (!fs.existsSync(serverCommand)) {
+    problems.push("server-command-missing");
+  }
+  if (!stamp.exists) {
+    problems.push("bootstrap-stamp-missing");
+  } else if (!stamp.version) {
+    problems.push("bootstrap-stamp-invalid");
+  } else if (packageVersion && stamp.version !== packageVersion) {
+    problems.push("bootstrap-version-mismatch");
+  }
+
+  return {
+    ready: problems.length === 0,
+    packageVersion,
+    stampVersion: stamp.version,
+    stampExists: stamp.exists,
+    stampPath,
+    serverCommand,
+    venvDir,
+    problems,
+  };
+}
+
+function formatRuntimeProblem(runtime, commandName, { allowRuntimeBootstrap = false } = {}) {
+  const problemLines = [];
+  for (const problem of runtime.problems) {
+    switch (problem) {
+      case "package-version-missing":
+        problemLines.push("- package.json is missing a valid version field");
+        break;
+      case "server-command-missing":
+        problemLines.push(`- missing Python entrypoint: ${runtime.serverCommand}`);
+        break;
+      case "bootstrap-stamp-missing":
+        problemLines.push(`- missing bootstrap stamp: ${runtime.stampPath}`);
+        break;
+      case "bootstrap-stamp-invalid":
+        problemLines.push(`- bootstrap stamp is unreadable or invalid: ${runtime.stampPath}`);
+        break;
+      case "bootstrap-version-mismatch":
+        problemLines.push(
+          `- bootstrap version mismatch: package=${runtime.packageVersion ?? "unknown"}, runtime=${runtime.stampVersion ?? "unknown"}`
+        );
+        break;
+      default:
+        problemLines.push(`- ${problem}`);
+        break;
+    }
+  }
+
+  const action = allowRuntimeBootstrap
+    ? "Delete .npm-python and retry, or rerun npm install to rebuild the embedded Python runtime."
+    : "Delete .npm-python and rerun npm install, or reinstall the npm package before starting the MCP server.";
+
+  const bootstrapNote = allowRuntimeBootstrap
+    ? ""
+    : "\nRuntime bootstrap is disabled for stdio MCP entrypoints so install logs can never corrupt the MCP stdout transport.";
+
+  return [
+    `[qingflow-mcp] Python runtime for ${commandName} is not ready.`,
+    ...problemLines,
+    action + bootstrapNote,
+  ].join("\n");
+}
+
 function getVenvPip(packageRoot) {
   return WINDOWS
     ? path.join(getVenvDir(packageRoot), "Scripts", "pip.exe")
@@ -119,12 +220,11 @@ export function findPython() {
 
 export function ensurePythonEnv(packageRoot, { force = false, commandName = "qingflow-mcp" } = {}) {
   const python = findPython();
-  const venvDir = getVenvDir(packageRoot);
+  const runtime = inspectPythonEnv(packageRoot, commandName);
   const venvPython = getVenvPython(packageRoot);
-  const serverCommand = getVenvServerCommand(packageRoot, commandName);
-  const stampPath = path.join(venvDir, ".bootstrap.json");
+  const { packageVersion, serverCommand, stampPath, venvDir, stampVersion } = runtime;
 
-  if (!force && fs.existsSync(serverCommand) && fs.existsSync(stampPath)) {
+  if (!force && fs.existsSync(serverCommand) && fs.existsSync(stampPath) && stampVersion && stampVersion === packageVersion) {
     return serverCommand;
   }
 
@@ -145,6 +245,7 @@ export function ensurePythonEnv(packageRoot, { force = false, commandName = "qin
       {
         installed_at: new Date().toISOString(),
         installer: "npm",
+        package_version: packageVersion,
       },
       null,
       2
@@ -158,17 +259,72 @@ export function ensurePythonEnv(packageRoot, { force = false, commandName = "qin
   return serverCommand;
 }
 
-export function spawnServer(packageRoot, args, commandName = "qingflow-mcp") {
-  const serverCommand = fs.existsSync(getVenvServerCommand(packageRoot, commandName))
-    ? getVenvServerCommand(packageRoot, commandName)
-    : ensurePythonEnv(packageRoot, { commandName });
+function proxyStreams(child) {
+  if (process.stdin.readable && child.stdin) {
+    process.stdin.pipe(child.stdin);
+    child.stdin.on("error", (error) => {
+      if (error.code !== "EPIPE") {
+        console.error(`[qingflow-mcp] Failed to forward stdin: ${error.message}`);
+      }
+    });
+  } else if (child.stdin) {
+    child.stdin.end();
+  }
+
+  if (child.stdout) {
+    child.stdout.pipe(process.stdout);
+  }
+  if (child.stderr) {
+    child.stderr.pipe(process.stderr);
+  }
+}
+
+function forwardSignal(child, signal) {
+  process.on(signal, () => {
+    if (!child.killed) {
+      child.kill(signal);
+    }
+  });
+}
+
+export function spawnServer(packageRoot, args, commandName = "qingflow-mcp", { allowRuntimeBootstrap = false } = {}) {
+  let runtime = inspectPythonEnv(packageRoot, commandName);
+  let serverCommand = runtime.serverCommand;
+
+  if (!runtime.ready) {
+    if (!allowRuntimeBootstrap) {
+      console.error(formatRuntimeProblem(runtime, commandName, { allowRuntimeBootstrap }));
+      process.exit(1);
+      return;
+    }
+
+    try {
+      serverCommand = ensurePythonEnv(packageRoot, { commandName });
+      runtime = inspectPythonEnv(packageRoot, commandName);
+    } catch (error) {
+      console.error(`[qingflow-mcp] Failed to prepare Python runtime for ${commandName}: ${error.message}`);
+      process.exit(1);
+      return;
+    }
+
+    if (!runtime.ready) {
+      console.error(formatRuntimeProblem(runtime, commandName, { allowRuntimeBootstrap }));
+      process.exit(1);
+      return;
+    }
+  }
 
   const child = spawn(serverCommand, args, {
-    stdio: "inherit",
+    stdio: ["pipe", "pipe", "pipe"],
     env: process.env,
+    windowsHide: true,
   });
 
-  child.on("exit", (code, signal) => {
+  proxyStreams(child);
+  forwardSignal(child, "SIGINT");
+  forwardSignal(child, "SIGTERM");
+
+  child.on("close", (code, signal) => {
     if (signal) {
       process.kill(process.pid, signal);
       return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "0.2.0-beta.9",
+  "version": "0.2.0-beta.91",
   "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 = "0.2.0b9"
+version = "0.2.0b91"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"
@@ -26,8 +26,10 @@ dependencies = [
   "mcp>=1.9.4,<2.0.0",
   "httpx>=0.27,<1.0",
   "keyring>=25.5,<26.0",
+  "openpyxl>=3.1,<4.0",
   "pydantic>=2.8,<3.0",
   "pycryptodome>=3.20,<4.0",
+  "python-socketio[client]>=5.11,<6.0",
 ]
 
 [project.optional-dependencies]
@@ -44,6 +46,7 @@ build = [
 [project.scripts]
 qingflow-app-user-mcp = "qingflow_mcp.server_app_user:main"
 qingflow-app-builder-mcp = "qingflow_mcp.server_app_builder:main"
+qingflow = "qingflow_mcp.cli.main:main"
 
 [project.urls]
 Homepage = "https://github.com/qingflow/qingflow-mcp"

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

@@ -17,23 +17,80 @@ Before any write or verification flow, identify whether the task targets `test`
 
 Pick the smallest tool layer that can finish the task.
 
+## Shared Helper
+
+- `feedback_submit` is a cross-cutting helper for product feedback submission
+- It does not require Qingflow login or workspace selection
+- If builder capability is unsupported or still cannot satisfy the need after reasonable use, summarize the gap, ask whether to submit feedback, and call `feedback_submit` only after explicit user confirmation.
+
+## Mental Model
+
+Model builder requests in four layers. Do not flatten them.
+
+- `package`: the solution container or app bundle, for example “研发项目管理” or “费控管理系统”
+- `app`: one form/app inside that package, for example “项目”, “需求”, “任务”, “缺陷”, “团队”
+- `field`: one field inside one app
+- `relation`: a field that links one app to another app
+
+Interpret user intent with this hierarchy:
+
+- If the user says “应用包”, “系统”, “包含多个表单”, “多个模块”, or asks for several named forms that relate to each other, treat it as a `package` with multiple `apps`
+- Do not compress a multi-app system into one app with several text fields
+- Names like “项目/需求/任务/缺陷/团队” or “费用申请/预算管理/报销审批” are usually separate apps, not text fields
+- Build the apps first, then add `relation` fields to connect them
+
+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
+
 - 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`, `app_release_edit_lock_if_mine`
+- Resource resolve/read: `package_list`, `package_resolve`, `package_create`, `builder_tool_contract`, `member_search`, `role_search`, `app_resolve`, `app_get`, `app_get_fields`, `app_get_layout`, `app_get_views`, `app_get_flow`, `app_get_charts`, `portal_list`, `portal_get`, `view_get`, `chart_get`
+- Resource patch: `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, `app_charts_apply`, `portal_apply`, `package_attach_app`, `app_release_edit_lock_if_mine`, `role_create`
 - 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`.
+- Do not rely on low-level `view_*`, `workflow_*`, `qingbi_report_*`, or `portal_*` write payloads from public builder flows.
+- Public builder work should stay on the resource path: `resolve -> summary read -> 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.
+- `app_charts_apply` is immediate-live and does not publish; it resolves targets by `chart_id` first and then exact unique chart name.
+- `portal_apply` uses replace semantics for sections; remove a section by omitting it from the next full sections list. `publish=false` only guarantees draft/base-info updates, and `chart_ref/view_ref` resolve by `id/key` first and exact unique name second.
+- `app_get_charts` is the compact discovery path for current chart inventory; use it before `app_charts_apply` when you need exact `chart_id` values.
+- `chart_get` returns one chart's base info and config only; public builder flows should treat data reads as user-side access, not builder config access.
+- `portal_list` is the discovery path for builder-configurable portals.
+- `portal_get` returns portal-level config detail plus a component inventory; it does not inline chart/view detail or user-side chart/view data.
+- `view_get` returns one view's definition detail only; use `record_list` separately when you need rows from that view.
+- `app_schema_apply` / `app_layout_apply` / `app_flow_apply` / `app_views_apply` now perform planning, normalization, and dependency checks internally; when prechecks block, read the returned blocking issues and `suggested_next_call` directly from the apply result.
+- If you are unsure about a public builder tool's keys, aliases, presets, or minimal legal shape, call `builder_tool_contract` instead of guessing.
+- For views, always write the canonical key `columns`. Do not emit `column_names`; treat `fields` only as a tolerated legacy alias, not the preferred shape.
+- For flow presets, map natural language to canonical values before calling MCP:
+  - “默认审批/基础审批/普通审批” -> `basic_approval`
+  - “先填报再审批/提交后审批” -> `basic_fill_then_approve`
+- Public flow building is intentionally limited to linear workflows:
+  - `start`
+  - `approve`
+  - `fill`
+  - `copy`
+  - `webhook`
+  - `end`
+  Do not generate `branch` or `condition` nodes in the public builder surface. The backend workflow route is not front-end stable for those node types.
+- For first-time flow or view work in a session, read `builder_tool_contract` before planning so keys, aliases, presets, and minimal examples come from MCP instead of memory.
+- For workflow assignees, prefer roles over explicit members:
+  - use `role_search` first
+  - use `member_search` only when the user explicitly names members or no stable role exists
+  - use `role_create` when the business owner wants a reusable directory role instead of hard-coded members
+- On any `VALIDATION_ERROR`, inspect `suggested_next_call` first and prefer reusing the MCP-normalized arguments over re-guessing from the original natural language.
+- If the current MCP capability is unsupported, the workflow is awkward, or the user's need still cannot be satisfied after reasonable use, summarize the gap, ask whether to submit feedback, and call `feedback_submit` only after explicit user confirmation.
 
 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.
+- Creating or updating one app inside an existing package: resolve the package/app, read compact state, then apply schema/layout/flow/views patches explicitly.
+- If package creation looks necessary or beneficial, ask the user to confirm before calling `package_create`.
+- If the user describes a system/package with multiple forms or modules, do not start with `app_schema_apply` on the package name. Resolve or create the package first, then create each app separately.
 
 ## Standard Operating Order
 
@@ -45,19 +102,51 @@ Before any business tool:
 
 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.
+1. Resolve the target package with `package_resolve`; if resolution is ambiguous or you need a read-only fallback, use `package_list`. If you believe a new package should be created, ask the user to confirm before calling `package_create`.
+2. Decide whether the target is one app or a multi-app package:
+   - one app: continue with `app_resolve`
+   - multi-app package/system: create or resolve the package, then create each app separately before adding relations
+3. Resolve the target app with `app_resolve` if the request is an update. Use exactly one selector mode: `app_key`, or `app_name + package_tag_id`.
+4. Read only the smallest config slice you need: `app_get`, `app_get_fields`, `app_get_layout`, `app_get_views`, `app_get_flow`, `app_get_charts`, `portal_get`.
+5. Use `app_schema_apply` for create/upsert/remove field work. It publishes by default after the patch lands; noop schema requests do not publish.
+6. If the app must belong to a package, use `package_attach_app` explicitly after schema work with `tag_id + app_key` 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 after the patch lands; noop layout requests do not publish.
+8. Use `app_flow_apply` after schema exists. It publishes by default; pass `publish=false` when you only want draft/precheck behavior.
+9. Use `app_views_apply` when the user wants explicit table/card/board/gantt views. It publishes by default after the patch lands; noop view requests do not publish.
 10. Use `app_publish_verify` only when the user explicitly wants final publish/live verification or you need an explicit verification pass.
 11. If a write fails with `APP_EDIT_LOCKED`, stop normal writes. Only use `app_release_edit_lock_if_mine` when the failed result shows the lock owner is the current logged-in user.
 
-In `prod`, keep `plan` and `apply` as separate phases unless the user explicitly asks for a direct live execution.
+For view work, keep the order strict:
+
+1. `builder_tool_contract`
+2. `app_get_fields`
+3. `app_get_views`
+4. `app_views_apply`
+5. `app_get_views` again whenever `app_views_apply` returns `failed` or `partial_success`
+
+For flow work, keep the order strict:
+
+1. `builder_tool_contract`
+2. `app_get_fields`
+3. `app_get_flow`
+4. `role_search` or `member_search` if assignees need to come from the directory
+5. `role_create` if the user wants a reusable role and no suitable role exists yet
+6. Start from a canonical preset when possible
+7. Use patch-style edits to that skeleton instead of freehand full-graph generation
+8. When patching a preset skeleton, reuse the preset node ids:
+   - `basic_approval` -> patch `approve_1`
+   - `basic_fill_then_approve` -> patch `fill_1` and `approve_1`
+   Do not invent a second approval/fill node id unless you are intentionally replacing the skeleton and removing the preset node.
+9. Declare approver/fill/copy assignees explicitly:
+   - prefer `assignees.role_names`
+   - support `assignees.member_names` / `assignees.member_emails` / `assignees.member_uids`
+10. When a node must edit specific fields, declare `permissions.editable_fields`
+11. `app_flow_apply`
+12. `app_get_flow` after apply whenever the user asked for verification or apply returns `partial_success`
+13. Use `app_get_charts` before chart work whenever exact current `chart_id` values matter
+14. Use `app_charts_apply` for QingBI chart creation and updates, not raw `qingbi_report_*` writes
+15. Use `portal_get` before portal work whenever exact current portal config and section inventory matter
+16. Use `portal_apply` for builder-side portal work; treat sections as a full replacement list
 
 For additive work on existing systems:
 
@@ -70,10 +159,29 @@ For additive work on existing systems:
 
 - 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.
+- Prefer reading compact state plus `builder_tool_contract` before `*_apply`; apply already performs server-side normalization and returns blocking issues or the next executable call shape when needed.
+- For abstract requests like “默认视图”, “基础审批流”, “灵活流程”, or “美观布局”, first translate the intent into a stable preset or explicit patch. Do not send those phrases to MCP unchanged.
+- If the user asks for a business system or package that contains several forms, do not use the system/package name as `app_name` and do not try to store the child app names as text fields.
+- For flexible workflow requests, split the work into two steps:
+  1. create a base skeleton with a preset
+  2. apply explicit business-specific changes as patchable nodes/transitions
+- For preset-based flows, treat preset node ids as part of the public contract. Patch the skeleton nodes by the same ids instead of creating a parallel node with a new id and leaving the preset node unassigned.
+- Approval, fill, and copy nodes must declare at least one assignee. Treat this as a hard requirement, not an optional detail.
+- For workflow nodes, use the canonical public shape:
+  - `assignees.role_names`
+  - `assignees.member_names`
+  - `permissions.editable_fields`
+- For layout work, keep the public section shape canonical:
+  - `title`
+  - `rows`
+  Do not invent top-level layout `columns`, and do not prefer `fields` or `field_ids` once `rows` is known.
+- Translate natural language like “一行四个字段 / 四列布局 / 每行放四个” into `rows` matrices, not guessed layout parameters.
+- If the same layout-shape `VALIDATION_ERROR` repeats twice, stop guessing and re-read `builder_tool_contract(app_layout_apply)` or the layout reference before trying again.
+- Do not guess role ids or member ids. Resolve them from the directory first.
 - `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.
+- Another app is not a field. If two business objects should both have their own records, build two apps and connect them with relation fields.
 - In `prod`, prefer explicit patch tools and avoid any speculative create flow.
 - Never try to bypass collaborative edit locks. `app_release_edit_lock_if_mine` is only for the case where the lock owner is the current authenticated user.
 
@@ -81,27 +189,50 @@ For additive work on existing systems:
 
 - 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.
+- All public builder tools expose top-level `warnings`, `verification`, and `verified`. Read them before deciding whether a run is fully done.
+- For read tools, `status=success` can still pair with `verified=false` when some optional readback is unavailable; in that case prefer `warnings` and `verification` over the bare status code.
+- For `app_charts_apply`, `portal_apply`, and `app_publish_verify`, treat `success` as “write and verification completed” and `partial_success` as “write executed but verification is incomplete”.
+- For `app_schema_apply`, multiple relation fields are a known high-risk backend area. If you see `RELATION_FIELD_LIMIT_RISK` or `verification.relation_field_limit_verified=false`, do not describe the schema as fully safe.
+- For `app_layout_apply`, trust `verification.layout_verified` first and `verification.layout_summary_verified` second. `LAYOUT_SUMMARY_UNVERIFIED` means the raw form readback is more trustworthy than the compact summary.
+- For `app_views_apply`, treat `verification.views_verified` and `verification.view_filters_verified` separately. A created view with unverified filters is not a finished business view.
+- For `app_flow_apply`, treat only linear node structure as publicly supported. If you see `FLOW_NODE_TYPE_UNSUPPORTED`, redesign the workflow as a stable linear flow instead of retrying branch/condition nodes.
 - 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
+- For views, a top-level `VIEW_APPLY_FAILED` does not prove all requested views failed. Read back the view list and verify which views actually landed.
+- For views, “view exists” is not the same as “filters are active”. If `app_views_apply` returns `partial_success`, `views_verified=false`, or `details.filter_mismatches`, report the view as created but the filters as unverified until readback confirms them.
+- If multiple views share the same name, do not guess which one to update. Read `view_key` from `app_get_views` and pass it explicitly in `upsert_views[]`.
+- In final user-facing summaries, distinguish clearly between:
+  - contract is visible / canonical shape is known
+  - apply precheck succeeded
+  - apply landed and readback verified it
+  - base template/skeleton applied
+  - business-specific rules completed
+  - remaining gaps or follow-up patches
+- Do not report “流程已满足业务需求” when only a preset skeleton has landed.
 
 ## Practical Patterns
 
 - List packages: `package_list`
 - Resolve one package: `package_resolve`
+- Create one package: `package_create`
+- Read one public tool contract: `builder_tool_contract`
 - 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`
+- Read one app summary: `app_get`
+- 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 for workflow assignees: `member_search`
+- Search roles for workflow assignees: `role_search`
+- Create reusable workflow role: `role_create`
 - 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`
+- Upsert/remove/reorder QingBI charts: `app_charts_apply`
+- Create or replace-update portal pages: `portal_apply`
 - Attach one app to a package: `package_attach_app`
 - Release your own stale edit lock: `app_release_edit_lock_if_mine`
 - Publish and verify: `app_publish_verify` when you need a separate verification pass beyond the default auto-publish behavior in apply tools
@@ -115,5 +246,6 @@ Detailed playbooks:
 - 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)
+- Workflow assignees and node permissions: [references/flow-actors-and-permissions.md](references/flow-actors-and-permissions.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)