@josephyan/qingflow-app-builder-mcp 1.1.4 → 1.1.5

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-builder-mcp@1.1.4
+npm install @josephyan/qingflow-app-builder-mcp@1.1.5
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-builder-mcp@1.1.4 qingflow-app-builder-mcp
+npx -y -p @josephyan/qingflow-app-builder-mcp@1.1.5 qingflow-app-builder-mcp
 ```
 
 Environment:
@@ -24,11 +24,12 @@ Bundled skills:
 
 - `skills/qingflow-app-builder`
 - `skills/qingflow-app-builder-code-integrations`
-- `skills/qingflow-workflow-builder`
-- `skills/qingflow-mcp-setup`
 
 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).
+- Installing the npm package does not overwrite agent skills automatically.
+- To mount bundled skills from an installed package, run `qingflow-app-builder-mcp-skills install --agent codex --scope user`.
+- For one-shot `npx -p` installs, prefer `--copy` because symlinks would point into the npm execution cache.
+- Use `qingflow-app-builder-mcp-skills list` to inspect bundled skills. The installer defaults to symlinks for stable package installs and refuses to overwrite existing skills unless `--force` is provided.
 - 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

@@ -101,7 +101,51 @@ npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-app-builder-mcp-<v
 1. 创建 `.npm-python/`
 2. 在其中建立 Python 虚拟环境
 3. 执行 `pip install .`
-4. 在安装位置暴露 `qingflow`、`qingflow-app-user-mcp`、`qingflow-app-builder-mcp` 命令
+4. 在安装位置暴露对应入口：CLI 包暴露 `qingflow` / `qingflow-skills`；app-user 包暴露 `qingflow-app-user-mcp` / `qingflow-app-user-mcp-skills`；app-builder 包暴露 `qingflow-app-builder-mcp` / `qingflow-app-builder-mcp-skills`
+5. 携带 `skills/<skill-name>/SKILL.md`，但不在 `postinstall` 阶段自动覆盖本机 agent skills
+
+## Skills 挂载
+
+显式查看包内 skills：
+
+```bash
+qingflow-skills list
+```
+
+独立 MCP split 包使用包专属 skills 命令，避免全局安装多个包时发生 bin 覆盖：
+
+```bash
+qingflow-app-user-mcp-skills list
+qingflow-app-builder-mcp-skills list
+```
+
+显式挂载到 Codex 用户目录：
+
+```bash
+qingflow-skills install --agent codex --scope user
+```
+
+如果通过一次性 `npx -p <package>` 执行安装，请加 `--copy`，避免 symlink 指向 npm 临时执行缓存：
+
+```bash
+npx -y -p @qingflow-tech/qingflow-cli qingflow-skills install --agent codex --scope user --copy
+```
+
+也可以挂载到项目级 agent 目录：
+
+```bash
+qingflow-skills install --agent claude-code --scope project
+qingflow-skills install --agent cursor --scope project --copy
+qingflow-skills install --agent all --scope project
+```
+
+默认行为：
+
+- `--mode symlink`：使用 symlink，让 npm 包版本成为单一来源
+- `--scope user`：安装到用户级 agent skills 目录
+- `--agent codex`：目标 agent 为 Codex
+- 不覆盖已有同名 skill；需要替换时显式加 `--force`
+- 每次安装会在目标 skills 目录下写入 `.qingflow-skill-sources/<skill>.json`，记录 package、version、source、destination、agent、scope、mode
 
 ## 本地验证
 
@@ -110,24 +154,31 @@ npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-app-builder-mcp-<v
 ```bash
 cd qingflow-support/mcp-server
 node ./npm/bin/qingflow.mjs --help
+node ./npm/bin/qingflow-skills.mjs list
 node ./npm/bin/qingflow-app-user-mcp.mjs
 node ./npm/bin/qingflow-app-builder-mcp.mjs
 ```
 
-如果你是全局安装：
+如果你是全局安装对应包：
 
 ```bash
 qingflow --help
+qingflow-skills list
 qingflow-app-user-mcp
+qingflow-app-user-mcp-skills list
 qingflow-app-builder-mcp
+qingflow-app-builder-mcp-skills list
 ```
 
-如果你是把包安装到了某个本地 agent workspace，命令通常位于：
+如果你是把包安装到了某个本地 agent workspace，安装对应包后命令通常位于：
 
 ```bash
 /absolute/path/to/agent-workspace/node_modules/.bin/qingflow
+/absolute/path/to/agent-workspace/node_modules/.bin/qingflow-skills
 /absolute/path/to/agent-workspace/node_modules/.bin/qingflow-app-user-mcp
+/absolute/path/to/agent-workspace/node_modules/.bin/qingflow-app-user-mcp-skills
 /absolute/path/to/agent-workspace/node_modules/.bin/qingflow-app-builder-mcp
+/absolute/path/to/agent-workspace/node_modules/.bin/qingflow-app-builder-mcp-skills
 ```
 
 如果你是从 tgz 安装到某个空目录，命令通常位于：
@@ -217,7 +268,7 @@ qingflow-app-builder-mcp
       "command": "npx",
       "args": [
         "-y",
-        "@josephyan/qingflow-app-user-mcp"
+        "@qingflow-tech/qingflow-app-user-mcp"
       ],
       "env": {
         "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
@@ -230,7 +281,7 @@ qingflow-app-builder-mcp
       "command": "npx",
       "args": [
         "-y",
-        "@josephyan/qingflow-app-builder-mcp"
+        "@qingflow-tech/qingflow-app-builder-mcp"
       ],
       "env": {
         "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
@@ -272,7 +323,7 @@ npm install
 
 如果 MCP 客户端一调用工具就报 `Transport closed`，优先检查这几件事：
 
-1. 不要混用不同版本的 `@josephyan/qingflow-cli`、`@josephyan/qingflow-app-user-mcp`、`@josephyan/qingflow-app-builder-mcp`
+1. 不要混用不同版本的 `@qingflow-tech/qingflow-cli`、`@qingflow-tech/qingflow-app-user-mcp`、`@qingflow-tech/qingflow-app-builder-mcp`
 2. 删除安装目录下的 `.npm-python`
 3. 重新执行 `npm install` 或重新安装对应 tgz/npm 包
 4. 再启动 MCP 客户端

package/entry_point.py

@@ -7,7 +7,7 @@ src_path = os.path.abspath(os.path.join(os.path.dirname(__file__), "src"))
 if src_path not in sys.path:
     sys.path.insert(0, src_path)
 
-from qingflow_mcp.server import main
+from qingflow_mcp.server_app_user import main
 
 if __name__ == "__main__":
     main()

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

@@ -1,38 +1,7 @@
 #!/usr/bin/env node
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
 
-const PKG_BY_BIN = {
-  qingflow: "qingflow-cli",
-  "qingflow-app-user-mcp": "qingflow-app-user-mcp",
-  "qingflow-app-builder-mcp": "qingflow-app-builder-mcp",
-};
+import { getPackageRoot, spawnServer } from "../lib/runtime.mjs";
 
-function resolvePackageModule(metaUrl, ...segments) {
-  const scriptPath = fileURLToPath(metaUrl);
-  const scriptDir = path.dirname(scriptPath);
-  // bin files live in <pkg>/npm/bin/, runtime.mjs lives in the sibling <pkg>/npm/lib/,
-  // so step up one level before joining the requested segments.
-  const direct = path.join(scriptDir, "..", ...segments);
-  if (fs.existsSync(direct)) {
-    return pathToFileURL(direct).href;
-  }
-  if (path.basename(scriptDir) === ".bin") {
-    const binName = path.basename(scriptPath);
-    const pkgName = PKG_BY_BIN[binName];
-    if (!pkgName) {
-      throw new Error(`Unknown qingflow command: ${binName}`);
-    }
-    const scope = process.env.QINGFLOW_NPM_SCOPE || "@josephyan";
-    const fromBin = path.join(scriptDir, "..", scope, pkgName, "npm", ...segments);
-    if (fs.existsSync(fromBin)) {
-      return pathToFileURL(fromBin).href;
-    }
-  }
-  throw new Error(`Cannot locate ${segments.join("/")} from ${scriptPath}`);
-}
-
-const { getPackageRoot, spawnServer } = await import(resolvePackageModule(import.meta.url, "lib", "runtime.mjs"));
 const packageRoot = getPackageRoot(import.meta.url);
+
 spawnServer(packageRoot, process.argv.slice(2), "qingflow-app-builder-mcp", { allowRuntimeBootstrap: false });

package/npm/bin/qingflow-skills.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { getPackageRoot, runSkillsCli } from "../lib/runtime.mjs";
+
+const packageRoot = getPackageRoot(import.meta.url);
+runSkillsCli(packageRoot, process.argv.slice(2));

package/npm/lib/runtime.mjs

@@ -5,12 +5,6 @@ import { fileURLToPath } from "node:url";
 
 const WINDOWS = process.platform === "win32";
 
-const PKG_BY_BIN = {
-  qingflow: "qingflow-cli",
-  "qingflow-app-user-mcp": "qingflow-app-user-mcp",
-  "qingflow-app-builder-mcp": "qingflow-app-builder-mcp",
-};
-
 function runChecked(command, args, options = {}) {
   const result = spawnSync(command, args, {
     encoding: "utf8",
@@ -34,18 +28,7 @@ function commandWorks(command, args) {
 }
 
 export function getPackageRoot(metaUrl) {
-  const scriptPath = fileURLToPath(metaUrl);
-  const scriptDir = path.dirname(scriptPath);
-  if (path.basename(scriptDir) === ".bin") {
-    const binName = path.basename(scriptPath);
-    const pkgName = PKG_BY_BIN[binName];
-    if (!pkgName) {
-      throw new Error(`Unknown qingflow command: ${binName}`);
-    }
-    const scope = process.env.QINGFLOW_NPM_SCOPE || "@josephyan";
-    return path.join(scriptDir, "..", scope, pkgName);
-  }
-  return path.resolve(scriptDir, "..", "..");
+  return path.resolve(path.dirname(fileURLToPath(metaUrl)), "..", "..");
 }
 
 export function getCodexHome() {
@@ -154,43 +137,6 @@ function writeSkillProvenance(skillsDestRoot, skillName, payload) {
   fs.writeFileSync(path.join(provenanceRoot, `${skillName}.json`), `${JSON.stringify(payload, null, 2)}\n`);
 }
 
-function sleepMs(ms) {
-  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-
-function withSkillInstallLock(skillsDestRoot, callback) {
-  const lockDir = path.join(skillsDestRoot, ".qingflow-skill-install.lock");
-  const startedAt = Date.now();
-  while (true) {
-    try {
-      fs.mkdirSync(lockDir);
-      break;
-    } catch (error) {
-      if (error.code !== "EEXIST") {
-        throw error;
-      }
-      try {
-        const stat = fs.statSync(lockDir);
-        if (Date.now() - stat.mtimeMs > 300_000) {
-          fs.rmSync(lockDir, { recursive: true, force: true });
-          continue;
-        }
-      } catch {
-        continue;
-      }
-      if (Date.now() - startedAt > 30_000) {
-        throw new Error(`Timed out waiting for skill install lock: ${lockDir}`);
-      }
-      sleepMs(100);
-    }
-  }
-  try {
-    return callback();
-  } finally {
-    fs.rmSync(lockDir, { recursive: true, force: true });
-  }
-}
-
 export function installBundledSkills(
   packageRoot,
   {
@@ -234,29 +180,27 @@ export function installBundledSkills(
     mode,
   };
 
-  return withSkillInstallLock(skillsDestRoot, () => {
-    for (const skillName of wanted) {
-      const src = path.join(skillsSrc, skillName);
-      const dest = path.join(skillsDestRoot, skillName);
-      const installResult = installOneSkill(src, dest, { force, mode });
-      result[installResult.status === "conflict" ? "conflicts" : installResult.status].push(skillName);
-      if (installResult.status !== "conflict") {
-        writeSkillProvenance(skillsDestRoot, skillName, {
-          package: packageJson.name ?? null,
-          version: packageJson.version ?? null,
-          skill: skillName,
-          source: src,
-          destination: dest,
-          agent,
-          scope,
-          mode,
-          installed_at: new Date().toISOString(),
-        });
-      }
+  for (const skillName of wanted) {
+    const src = path.join(skillsSrc, skillName);
+    const dest = path.join(skillsDestRoot, skillName);
+    const installResult = installOneSkill(src, dest, { force, mode });
+    result[installResult.status === "conflict" ? "conflicts" : installResult.status].push(skillName);
+    if (installResult.status !== "conflict") {
+      writeSkillProvenance(skillsDestRoot, skillName, {
+        package: packageJson.name ?? null,
+        version: packageJson.version ?? null,
+        skill: skillName,
+        source: src,
+        destination: dest,
+        agent,
+        scope,
+        mode,
+        installed_at: new Date().toISOString(),
+      });
     }
+  }
 
-    return result;
-  });
+  return result;
 }
 
 function parseSkillsCliArgs(args) {
@@ -536,17 +480,6 @@ function getVenvPip(packageRoot) {
     : path.join(getVenvDir(packageRoot), "bin", "pip");
 }
 
-function findOfflineProjectWheel(findLinksDir) {
-  const wheels = fs
-    .readdirSync(findLinksDir)
-    .filter((name) => /^qingflow_mcp-.*\.whl$/i.test(name))
-    .sort();
-  if (wheels.length === 0) {
-    throw new Error(`Offline install expected a qingflow_mcp wheel in ${findLinksDir}`);
-  }
-  return path.join(findLinksDir, wheels[wheels.length - 1]);
-}
-
 export function findPython() {
   const preferred = process.env.QINGFLOW_MCP_PYTHON?.trim();
   const candidates = preferred
@@ -595,20 +528,7 @@ export function ensurePythonEnv(packageRoot, { force = false, commandName = "qin
   }
 
   const pip = getVenvPip(packageRoot);
-  const pipArgs = ["install", "--disable-pip-version-check"];
-  const offlineFindLinks = process.env.QINGFLOW_MCP_PIP_FIND_LINKS?.trim();
-  if (process.env.QINGFLOW_MCP_PIP_NO_INDEX === "1") {
-    pipArgs.push("--no-index");
-  }
-  if (offlineFindLinks) {
-    pipArgs.push("--find-links", offlineFindLinks);
-  }
-  if (process.env.QINGFLOW_MCP_PIP_NO_INDEX === "1" && offlineFindLinks) {
-    pipArgs.push(findOfflineProjectWheel(offlineFindLinks));
-  } else {
-    pipArgs.push(".");
-  }
-  runChecked(pip, pipArgs, { cwd: packageRoot });
+  runChecked(pip, ["install", "--disable-pip-version-check", "."], { cwd: packageRoot });
 
   fs.writeFileSync(
     stampPath,

package/npm/scripts/postinstall.mjs

@@ -1,4 +1,4 @@
-import { ensurePythonEnv, getPackageRoot, installBundledSkills } from "../lib/runtime.mjs";
+import { ensurePythonEnv, getPackageRoot } from "../lib/runtime.mjs";
 
 const packageRoot = getPackageRoot(import.meta.url);
 
@@ -6,15 +6,6 @@ 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, { force: true });
-  if (!skills.skipped) {
-    const changed = [
-      skills.installed.length ? `installed=${skills.installed.join(",")}` : "",
-      skills.unchanged.length ? `unchanged=${skills.unchanged.join(",")}` : "",
-      skills.conflicts.length ? `conflicts=${skills.conflicts.join(",")}` : "",
-    ].filter(Boolean).join(" ");
-    console.log(`[qingflow-mcp] Installed skills to ${skills.destination}: ${changed || "none"}`);
-  }
 } catch (error) {
   console.error(`[qingflow-mcp] postinstall failed: ${error.message}`);
   process.exit(1);

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "qingflow-app-builder-mcp": "./npm/bin/qingflow-app-builder-mcp.mjs"
+    "qingflow-app-builder-mcp": "./npm/bin/qingflow-app-builder-mcp.mjs",
+    "qingflow-app-builder-mcp-skills": "./npm/bin/qingflow-skills.mjs"
   },
   "scripts": {
     "postinstall": "node ./npm/scripts/postinstall.mjs"

package/pyproject.toml

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

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

@@ -1,20 +1,23 @@
 ---
 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.
+description: Build, configure, and modify Qingflow apps and systems using the current Wingent Momo runtime MCP session. 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
 
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## Overview
 
 This skill is for the current **public builder surface**, not for legacy low-level builder writes.
-Assumes MCP is already connected, authenticated, and on the correct workspace.
+In Wingent Momo runtime, trust the injected MCP session, credentials, workspace, and route context until a tool explicitly reports otherwise.
 
 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`.
 
 Before choosing a route, skim the shared maintenance baseline: [public-surface-sync.md](references/public-surface-sync.md).
+Then pick the matching development guide: [single-app-development-guide.md](references/single-app-development-guide.md) for one app, or [complete-system-development-guide.md](references/complete-system-development-guide.md) for app packages/systems.
 
 ## Current Public Mental Model
 
@@ -32,10 +35,29 @@ Default modeling rules:
 - Another business object -> a separate app, not a text field
 - Cross-object links -> relation fields, not text fields
 
+## Route First
+
+Before any builder write, classify the request:
+
+- **Complete system / app package**: the user asks for a system, package, workspace module set, or several related forms/apps. Use `package_apply` for the package, then one `app_schema_apply(package_id=..., apps=[...])` for the app shells and fields. This is the main path for complete systems, not a bulk shortcut to abandon after the first slow response. Do not squeeze several business objects into one app.
+- **Single app**: the user names one form/app or gives one `app_key`. Use `app_resolve`/`app_get`, then `app_schema_apply` and the app-scoped apply tools.
+- **Record/user operation**: the user wants to add, edit, delete, approve, or analyze data. Route to the record/task skills instead of builder tools.
+
+For complete systems, `apps[]` should use stable `client_key` values. Same-call relation fields should use `target_app_ref` for another `apps[].client_key`; use `target_app_key` only when the target app already exists or has been confirmed by readback. Create the related apps with one multi-app schema apply; do not create each app separately just to collect app keys and then patch relations afterward.
+
+If a complete-system `app_schema_apply` times out, returns `partial_success`, returns `write_executed=true`, has `safe_to_retry=false`, or has incomplete readback, treat it as an uncertain write, not as a failed create. The next action is always `readback_before_retry`: read the package/app/fields first, compare intended `client_key`/`app_name`/relations against reality, and only then repair the missing slice. Do not retry the whole multi-app create, create `V2`/`测试`/random-suffix apps, or split the system into single-app rebuilds to bypass a duplicate/conflict.
+
+Builder schema inputs should follow agent-intuitive semantics:
+
+- primary icon syntax is `icon + color`, for example `icon: "table", color: "blue"`; `icon_name/icon_color`, `icon_config`, and `icon: {name, color}` are compatibility aliases only
+- `single_select` / `multi_select` options may be strings or objects such as `{label, value}`; tools normalize to option labels
+- relation fields need a target plus `display_field` and `visible_fields`
+- do not create built-in system fields as form fields: `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, `流程标题`. They are platform-generated; only reference supported system fields where a tool explicitly says so, such as button `source_field: "数据ID"`
+
 ## 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`
 - 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`
@@ -50,8 +72,10 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - use `package_get(package_id=...)` to read one known package
   - 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
-  - same-call relation fields may use `target_app_ref` to point at another `apps[].client_key`
+  - use one `app_schema_apply(package_id=..., apps=[...])` / CLI `builder schema apply --apps-file` when creating several apps in one package
+  - every `apps[]` item should carry its own `client_key`, `app_name`, `icon`, `color`, and `add_fields`
+  - same-call relation fields should use `target_app_ref` to point at another `apps[].client_key`; use `target_app` only when the app name is unique and stable, and use `target_app_key` only after the target app already exists or readback has confirmed it
+  - timeout / `partial_success` / `write_executed=true` / `safe_to_retry=false` means `readback_before_retry`; do not directly downgrade to single-app creation
 - 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
@@ -63,12 +87,13 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - `portal_apply` is the public write path
   - 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:
   - `app_charts_apply` is the public write path for app-source QingBI report bodies/configs; it creates/updates reports with `dataSourceType=qingflow`
   - 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`
+  - chart `filters` use the unified fixed-filter DSL: `field_name + operator + value/values`; the tool compiles them to QingBI string judge types
+  - for complete systems, submit `upsert_charts` in batches of 4-8. More than 8 upserts is blocked before write with `CHART_UPSERT_BATCH_TOO_LARGE`; execute `details.suggested_batch_payloads[]` one batch at a time.
   - 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
@@ -87,30 +112,34 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - 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`
   - it attaches existing BI reports/views for in-app display; it does not create or edit QingBI report bodies/configs, including dataset reports
   - use `patch_resources` for changing match rules or other existing associated-resource parameters; the tool preserves backend-required raw fields internally
   - `associated_item_id` is the backend internal associated-resource id; for `view_configs`, `remove_associated_item_ids`, and `reorder_associated_item_ids`, you may pass `associated_item_id` or an existing resource's `chart_id`/`chart_key`/`view_key`, and the tool resolves it to the internal id
   - before creating a resource, check `app_get.associated_resources` for the same `target_app_key + view_key/chart_key`; if it already exists, use `patch_resources` with that `associated_item_id`
   - `client_key` is only a same-call reference for `view_configs[].associated_item_refs`; it is not saved and cannot deduplicate later calls
   - do not pass backend raw `sourceType`; view resources infer the internal Qingflow view source, report/chart resources default to BI app reports, and existing dataset reports use `report_source="dataset"`
-  - use `match_mappings` for associated view/report filters; dynamic conditions use `source_field`, static conditions use `value`
+  - use `match_mappings` for associated view/report filters; dynamic context matches use `source_field`, static filters use `value`; do not handwrite raw `matchRules`
   - 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`
+  - before building approval/fill/copy flows, make sure the app schema has an explicit business status `select` field such as `状态` / `处理状态` / `审批状态`; do not create platform workflow system fields such as `当前流程状态`
   - 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`
+  - do not create platform default/system views named `全部数据`, `我的数据`, `我发起的`, `待办`, `已办`, or `抄送`; they are built in. New views must use business-specific names. To change a built-in view, patch by its existing raw `view_key`
   - use `builder_tool_contract` whenever the minimal legal shape is unclear
-  - keep view `filters` and `query_conditions` separate: `filters` are fixed saved filters; `query_conditions` configure the frontend query panel fields and only take effect after users enter query values
-  - when creating any new table or card view, always include `query_conditions` with `enabled: true`; populate `rows` with the fields most useful for searching — typically the data-title field, any status/type select fields, date fields, and member fields; do not omit `query_conditions` or leave `rows` empty on a new view
+  - keep view `filters` and `query_conditions` separate: `filters` use `field_name + operator + value/values` and are fixed saved filters; `query_conditions` configure the frontend query panel fields and only take effect after users enter query values
+  - keep relation/attachment/subtable/address/Q-Linker/code-block fields out of `query_conditions`; member/department fields may be used as query-panel fields when readback supports them. Use `filters` for fixed filters or associated-resource `match_mappings` for current-record related report/view matching
   - new views default the associated report/view display area to visible with `limit_type="all"`; existing views preserve their current associated-resource display unless `associated_resources` is explicitly patched
   - configure associated reports/views through `app_associated_resources_apply`, not through `app_views_apply`
 
 ## Standard Operating Order
 
-1. Ensure auth exists
-2. Ensure workspace is selected
-3. Confirm whether the task is read-only or write-impacting
+1. Trust the current MCP/session when it is already injected by the runtime; only run auth/workspace recovery after a tool explicitly reports an auth, credential, or workspace error
+2. Confirm whether the task is read-only or write-impacting
+3. Classify the build scope:
+   - complete system/package -> `package_apply` or `package_get`, then one `app_schema_apply(package_id=..., apps=[...])`
+   - single app -> `app_resolve` / `app_get`, then app-scoped apply tools
+   - record/task/data request -> leave builder and use the matching record/task skill
 4. Resolve the smallest stable target:
    - app-scoped work -> `app_resolve`
    - package-scoped work with known id -> `package_get`
@@ -135,16 +164,20 @@ Treat these as the official surface. Do not default to `package_create`, `packag
    - portal -> `portal_apply`
    - package metadata/layout -> `package_apply`
 8. Use `app_publish_verify` only when the user explicitly wants final publish/live verification or you need a dedicated verification pass
+9. For complete-system builds, write `tmp/qingflow_system_build_summary.json` before the final response and make the final report match that file
 
 ## Safe Usage Rules
 
 - Do not guess package identity from a loose name. Public package work assumes a known `package_id`, or an explicit create/update intent through `package_apply`.
+- Do not perform routine auth probes before every builder action in runtime contexts with injected MCP credentials; recover auth only after an actual auth/workspace failure.
 - 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 bypass package/app-name conflicts by inventing `V2`, `测试`, timestamp, or random suffix apps in a real business package. Read back and decide whether to update the existing app, create only a truly missing app, or ask the user.
+- After any uncertain schema write, do `readback_before_retry` with `package_get` / `app_resolve` / `app_get_fields`; retry only the verified missing or failed slice.
 - 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.
+- `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, and `app_views_apply` publish by default; `app_custom_buttons_apply` and `app_associated_resources_apply` publish after at least one write succeeds and do not accept a draft-only `publish` parameter; `app_charts_apply` is immediate-live without publish.
 - 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.
+- Do not add platform system fields to `add_fields`; if the user asks for record id, number, applicant, creation/update time, or workflow status, use the built-in data/list/readback fields instead of creating duplicate controls.
 - If the same validation error repeats twice, stop guessing and re-read `builder_tool_contract`.
 - For workflow assignees, prefer `role_search` over explicit members unless the user explicitly wants named members.
 - Public flow building is still intentionally limited to stable linear workflows. If a requirement sounds like branches/conditions, explain the limitation instead of freehanding unsupported graph shapes.
@@ -158,7 +191,7 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - For UI cards or quick narration, read `resources[]` first. Each resource has `resource_type`, `operation`, `status`, `id`, `key`, `name`, typed `ids`, and `parent`.
 - Use legacy fields such as `field_diff`, `views_diff`, `chart_results`, `created/updated/removed`, and `verification` only for compatibility and troubleshooting.
 - Treat post-write readback as the source of truth, not just write status codes.
-- `success` means write and verification completed; `partial_success` means the write landed but verification is incomplete.
+- `success` means write and verification completed; `partial_success` means the write landed or may have landed but verification is incomplete. If `write_executed=true`, `safe_to_retry=false`, or readback is unavailable, do `readback_before_retry` before any create retry.
 - For portals, distinguish clearly between:
   - base-info-only update with layout preserved
   - full sections replace
@@ -243,22 +276,6 @@ Use `app_custom_buttons_apply` for the whole custom-button path: button body, ad
 
 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) |
-| 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) |
-| Update workflow only | "修改审批流"、"加一个审批节点" | [update-flow.md](references/update-flow.md) |
-| Update views only | "加一个看板"、"改筛选条件"、"新增视图" | [update-views.md](references/update-views.md) |
-
-Decision rule: if the user mentions **multiple related apps or a portal**, use `build-complete-system.md`. If it is **one app** with a from-scratch setup request, use `build-single-app.md`. If the target app already exists and the user only wants to change one layer, use the matching single-layer playbook.
-
 ## Resources
 
 - Shared public-surface baseline: [public-surface-sync.md](references/public-surface-sync.md)
@@ -266,6 +283,8 @@ Decision rule: if the user mentions **multiple related apps or a portal**, use `
 - Tool choice and sequencing: [references/tool-selection.md](references/tool-selection.md)
 - Field matching rules: [references/match-rules.md](references/match-rules.md)
 - Result semantics and gotchas: [references/gotchas.md](references/gotchas.md)
+- Single app development guide: [references/single-app-development-guide.md](references/single-app-development-guide.md)
+- Complete system development guide: [references/complete-system-development-guide.md](references/complete-system-development-guide.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)
@@ -273,5 +292,3 @@ Decision rule: if the user mentions **multiple related apps or a portal**, use `
 - 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)
-- 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)