@josephyan/qingflow-app-builder-mcp 1.1.1 → 1.1.3

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-builder-mcp@1.1.1
+npm install @josephyan/qingflow-app-builder-mcp@1.1.3
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-builder-mcp@1.1.1 qingflow-app-builder-mcp
+npx -y -p @josephyan/qingflow-app-builder-mcp@1.1.3 qingflow-app-builder-mcp
 ```
 
 Environment:

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

@@ -12,7 +12,9 @@ const PKG_BY_BIN = {
 function resolvePackageModule(metaUrl, ...segments) {
   const scriptPath = fileURLToPath(metaUrl);
   const scriptDir = path.dirname(scriptPath);
-  const direct = path.join(scriptDir, ...segments);
+  // 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;
   }

package/npm/lib/runtime.mjs

@@ -60,29 +60,359 @@ export function getCodexHome() {
   return path.join(home, ".codex");
 }
 
-export function installBundledSkills(packageRoot) {
+function getHomeDir() {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (!home) {
+    throw new Error("Cannot resolve user home because HOME is not set.");
+  }
+  return home;
+}
+
+function getAgentSkillDest(agent, scope, cwd = process.cwd()) {
+  const normalizedAgent = agent.trim().toLowerCase();
+  const normalizedScope = scope.trim().toLowerCase();
+  const home = getHomeDir();
+  if (!["user", "project"].includes(normalizedScope)) {
+    throw new Error(`Unsupported skills scope '${scope}'. Expected 'user' or 'project'.`);
+  }
+
+  const projectRoots = {
+    codex: [cwd, ".codex", "skills"],
+    claude: [cwd, ".claude", "skills"],
+    "claude-code": [cwd, ".claude", "skills"],
+    cursor: [cwd, ".cursor", "skills"],
+    generic: [cwd, ".agents", "skills"],
+  };
+  const userRoots = {
+    codex: [process.env.CODEX_HOME?.trim() || path.join(home, ".codex"), "skills"],
+    claude: [home, ".claude", "skills"],
+    "claude-code": [home, ".claude", "skills"],
+    cursor: [home, ".cursor", "skills"],
+    generic: [home, ".agents", "skills"],
+  };
+
+  const roots = normalizedScope === "project" ? projectRoots : userRoots;
+  const parts = roots[normalizedAgent];
+  if (!parts) {
+    throw new Error(`Unsupported skills agent '${agent}'. Expected one of: codex, claude, claude-code, cursor, generic.`);
+  }
+  return path.resolve(...parts);
+}
+
+export function listBundledSkills(packageRoot) {
   const skillsSrc = path.join(packageRoot, "skills");
   if (!fs.existsSync(skillsSrc)) {
-    return { installed: [], skipped: true, destination: null };
+    return [];
   }
 
-  const codexHome = getCodexHome();
-  const skillsDestRoot = path.join(codexHome, "skills");
-  fs.mkdirSync(skillsDestRoot, { recursive: true });
+  return fs
+    .readdirSync(skillsSrc, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(skillsSrc, entry.name, "SKILL.md")))
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function sameRealPath(a, b) {
+  try {
+    return fs.realpathSync(a) === fs.realpathSync(b);
+  } catch {
+    return false;
+  }
+}
 
-  const installed = [];
-  for (const entry of fs.readdirSync(skillsSrc, { withFileTypes: true })) {
-    if (!entry.isDirectory()) {
-      continue;
+function installOneSkill(src, dest, { force, mode }) {
+  let existingStat = null;
+  try {
+    existingStat = fs.lstatSync(dest);
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+  if (existingStat) {
+    if (existingStat.isSymbolicLink() && sameRealPath(dest, src)) {
+      return { status: "unchanged" };
+    }
+    if (!force) {
+      return { status: "conflict" };
     }
-    const src = path.join(skillsSrc, entry.name);
-    const dest = path.join(skillsDestRoot, entry.name);
     fs.rmSync(dest, { recursive: true, force: true });
+  }
+
+  if (mode === "copy") {
     fs.cpSync(src, dest, { recursive: true });
-    installed.push(entry.name);
+    return { status: "installed" };
+  }
+
+  fs.symlinkSync(src, dest, "dir");
+  return { status: "installed" };
+}
+
+function writeSkillProvenance(skillsDestRoot, skillName, payload) {
+  const provenanceRoot = path.join(skillsDestRoot, ".qingflow-skill-sources");
+  fs.mkdirSync(provenanceRoot, { recursive: true });
+  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,
+  {
+    agent = "codex",
+    scope = "user",
+    mode = "symlink",
+    force = false,
+    skills = [],
+    cwd = process.cwd(),
+  } = {},
+) {
+  const skillsSrc = path.join(packageRoot, "skills");
+  if (!fs.existsSync(skillsSrc)) {
+    return { installed: [], unchanged: [], conflicts: [], skipped: true, destination: null };
+  }
+
+  const validModes = new Set(["symlink", "copy"]);
+  if (!validModes.has(mode)) {
+    throw new Error(`Unsupported skills install mode '${mode}'. Expected 'symlink' or 'copy'.`);
+  }
+
+  const available = listBundledSkills(packageRoot);
+  const wanted = skills.length ? skills : available;
+  const unknown = wanted.filter((skillName) => !available.includes(skillName));
+  if (unknown.length) {
+    throw new Error(`Unknown bundled skill(s): ${unknown.join(", ")}. Available: ${available.join(", ")}`);
   }
 
-  return { installed, skipped: false, destination: skillsDestRoot };
+  const skillsDestRoot = getAgentSkillDest(agent, scope, cwd);
+  fs.mkdirSync(skillsDestRoot, { recursive: true });
+
+  const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+  const result = {
+    installed: [],
+    unchanged: [],
+    conflicts: [],
+    skipped: false,
+    destination: skillsDestRoot,
+    agent,
+    scope,
+    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(),
+        });
+      }
+    }
+
+    return result;
+  });
+}
+
+function parseSkillsCliArgs(args) {
+  const parsed = {
+    command: "help",
+    agent: "codex",
+    scope: "user",
+    mode: "symlink",
+    force: false,
+    json: false,
+    skills: [],
+  };
+  const rest = [...args];
+  if (rest.length && !rest[0].startsWith("-")) {
+    parsed.command = rest.shift();
+  }
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+    const next = () => {
+      index += 1;
+      if (index >= rest.length) {
+        throw new Error(`Missing value for ${arg}`);
+      }
+      return rest[index];
+    };
+    switch (arg) {
+      case "--agent":
+      case "-a":
+        parsed.agent = next();
+        break;
+      case "--scope":
+      case "-s":
+        parsed.scope = next();
+        break;
+      case "--mode":
+      case "-m":
+        parsed.mode = next();
+        break;
+      case "--skill":
+        parsed.skills.push(next());
+        break;
+      case "--all":
+        parsed.agent = "all";
+        break;
+      case "--force":
+      case "-f":
+        parsed.force = true;
+        break;
+      case "--copy":
+        parsed.mode = "copy";
+        break;
+      case "--json":
+        parsed.json = true;
+        break;
+      case "--help":
+      case "-h":
+        parsed.command = "help";
+        break;
+      default:
+        if (arg.startsWith("-")) {
+          throw new Error(`Unknown option ${arg}`);
+        }
+        parsed.skills.push(arg);
+        break;
+    }
+  }
+  return parsed;
+}
+
+function printSkillsHelp() {
+  console.log(`Qingflow bundled skills
+
+Usage:
+  qingflow-skills list [--json]
+  qingflow-skills install [--agent codex|claude|claude-code|cursor|generic|all] [--scope user|project] [--mode symlink|copy] [--skill name] [--force] [--json]
+
+Examples:
+  qingflow-skills list
+  qingflow-skills install --agent codex --scope user
+  qingflow-skills install --agent claude-code --scope project --copy
+  qingflow-skills install --agent all --scope project
+
+Defaults:
+  --agent codex
+  --scope user
+  --mode symlink
+
+Existing skills are not overwritten unless --force is provided.`);
+}
+
+function printInstallSummary(result) {
+  console.log(`[qingflow-skills] destination: ${result.destination}`);
+  if (result.installed.length) {
+    console.log(`[qingflow-skills] installed: ${result.installed.join(", ")}`);
+  }
+  if (result.unchanged.length) {
+    console.log(`[qingflow-skills] unchanged: ${result.unchanged.join(", ")}`);
+  }
+  if (result.conflicts.length) {
+    console.log(`[qingflow-skills] conflicts: ${result.conflicts.join(", ")}`);
+    console.log("[qingflow-skills] Re-run with --force to replace conflicting skills.");
+  }
+}
+
+export function runSkillsCli(packageRoot, args) {
+  let parsed;
+  try {
+    parsed = parseSkillsCliArgs(args);
+    if (parsed.command === "help") {
+      printSkillsHelp();
+      return;
+    }
+    if (parsed.command === "list") {
+      const skills = listBundledSkills(packageRoot);
+      if (parsed.json) {
+        console.log(JSON.stringify({ skills }, null, 2));
+      } else {
+        for (const skill of skills) {
+          console.log(skill);
+        }
+      }
+      return;
+    }
+    if (parsed.command !== "install") {
+      throw new Error(`Unknown qingflow skills command '${parsed.command}'.`);
+    }
+
+    const agents = parsed.agent === "all" ? ["codex", "claude-code", "cursor", "generic"] : [parsed.agent];
+    const results = agents.map((agent) =>
+      installBundledSkills(packageRoot, {
+        agent,
+        scope: parsed.scope,
+        mode: parsed.mode,
+        force: parsed.force,
+        skills: parsed.skills,
+      }),
+    );
+    if (parsed.json) {
+      console.log(JSON.stringify({ results }, null, 2));
+    } else {
+      for (const result of results) {
+        printInstallSummary(result);
+      }
+    }
+    if (results.some((result) => result.conflicts.length)) {
+      process.exit(2);
+    }
+  } catch (error) {
+    if (parsed?.json) {
+      console.error(JSON.stringify({ error: error.message }, null, 2));
+    } else {
+      console.error(`[qingflow-skills] ${error.message}`);
+      console.error("Run 'qingflow-skills --help' for usage.");
+    }
+    process.exit(1);
+  }
 }
 
 export function getVenvDir(packageRoot) {

package/npm/scripts/postinstall.mjs

@@ -6,9 +6,14 @@ 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);
+  const skills = installBundledSkills(packageRoot, { force: true });
   if (!skills.skipped) {
-    console.log(`[qingflow-mcp] Installed skills to ${skills.destination}: ${skills.installed.join(", ")}`);
+    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}`);

package/package.json

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

package/pyproject.toml

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

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

@@ -87,6 +87,7 @@ 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

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

@@ -52,7 +52,7 @@ These execute normalized patches. Some app apply tools publish by default and st
 - `app_flow_apply`: replace full workflow spec; use `patch_nodes[]` (`{id, set, unset}`) to update specific nodes without rewriting the full spec
 - `app_views_apply`: use `patch_views` for existing-view parameter replacement; use `upsert_views` for creation or full target config; remove views by key; new views default associated report/view display to visible with `limit_type="all"`; use `apps[]` for multi-app batch
 - `app_custom_buttons_apply`: use `patch_buttons` for existing-button parameter replacement; use `upsert_buttons` for creation or full target config; configure add-data field mappings/default values; bind buttons to header/detail/list view positions; `placement=list` maps to the backend `INSIDE` row/list button position; merge-mode view configs require `buttons`; use `view_configs[].mode="replace"` or `buttons=[]` to clear a view's custom button bindings. For child-record creation linked to the current source record, map `source_field: "数据ID"` to the target relation field. Use `apps[]` for multi-app batch.
-- `app_associated_resources_apply`: attach existing BI reports/views to the Qingflow app associated-resource pool and per-view display area; it does not create or edit QingBI report bodies/configs. Use `patch_resources` for existing associated-resource parameter replacement; use `upsert_resources` for creation or full target config; `view_configs`, remove, and reorder may reference existing resources by internal `associated_item_id` or by `chart_id`/`chart_key`/`view_key`; use `match_mappings` for associated view/report filters; publishes after successful writes; omit raw `sourceType`, and use `report_source="dataset"` only to attach an existing BI dataset report. Before `upsert_resources`, read `app_get.associated_resources` and reuse an existing matching `target_app_key + view_key/chart_key`; repeated upsert can create duplicates because `client_key` is only valid inside one apply call.
+- `app_associated_resources_apply`: attach existing BI reports/views to the Qingflow app associated-resource pool and per-view display area; it does not create or edit QingBI report bodies/configs. Use `patch_resources` for existing associated-resource parameter replacement; use `upsert_resources` for creation or full target config; `view_configs`, remove, and reorder may reference existing resources by internal `associated_item_id` or by `chart_id`/`chart_key`/`view_key`; use `match_mappings` for associated view/report filters; publishes after successful writes; omit raw `sourceType`, and use `report_source="dataset"` only to attach an existing BI dataset report. Before `upsert_resources`, read `app_get.associated_resources` and reuse an existing matching `target_app_key + view_key/chart_key`; repeated upsert can create duplicates because `client_key` is only valid inside one apply call. Use `apps[]` for multi-app batch.
 - `app_charts_apply`: create/edit/remove/reorder app-source QingBI report bodies/configs with `dataSourceType=qingflow`; it does not create/edit dataset BI reports and does not attach reports to Qingflow app associated-resource display. Use `patch_charts` for existing-chart parameter replacement; use `upsert_charts` for creation or full target config; supports `target/table` aliases plus QingBI chart types such as `summary`, `columnar`, `area`, `funnel`, `radar`, `scatter`, `dualaxes`, and `map`; charts are immediate-live and do not publish; use `chart_id` when names are not unique; use `apps[]` for multi-app batch
 - `portal_apply`: create or replace-update portal pages; use `dash_key` for update mode or `package_id + dash_name` for create mode; edit mode may omit `sections` for base-info-only updates; when sections are supplied they still use replace semantics; sections use a 24-column PC grid — all components in the same row (same `y`) must share the same `rows` value and their `cols` must sum to exactly 24; mismatched `rows` causes height misalignment, `cols` under 24 leaves trailing blank space; use `patch_sections[]` (`{chart_ref/view_ref/order, set, unset}`) to update individual sections without replacing all
 

package/src/qingflow_mcp/builder_facade/service.py

@@ -5486,6 +5486,9 @@ class AiBuilderFacade:
         result = []
         for c in components:
             item = {k: v for k, v in c.items() if k != "order"}
+            position = item.get("position")
+            if isinstance(position, dict):
+                item["position"] = _portal_component_position_for_request(position)
             result.append(item)
         return result
 
@@ -14180,6 +14183,27 @@ def _portal_position_payload(position: Any, *, inferred_mobile_y: int = 0) -> di
     }
 
 
+def _portal_component_position_for_request(position: dict[str, Any]) -> dict[str, Any]:
+    """Normalize portal_get component positions into PortalSectionPatch input shape."""
+    payload = deepcopy(position)
+    if isinstance(payload.get("pc"), dict) or isinstance(payload.get("mobile"), dict):
+        return payload
+    pc_keys = {"x", "y", "cols", "rows"}
+    if any(key in payload for key in pc_keys):
+        pc = {
+            "x": int(payload.get("x") or 0),
+            "y": int(payload.get("y") or 0),
+            "cols": int(payload.get("cols") or payload.get("w") or 12),
+            "rows": int(payload.get("rows") or payload.get("h") or 8),
+        }
+        normalized: dict[str, Any] = {"pc": pc}
+        mobile = payload.get("mobile")
+        if isinstance(mobile, dict):
+            normalized["mobile"] = mobile
+        return normalized
+    return payload
+
+
 def _portal_component_position_public(
     source_type: Any,
     *,

package/src/qingflow_mcp/cli/commands/builder.py

@@ -166,12 +166,13 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     associated_resource_get.set_defaults(handler=_handle_associated_resource_get, format_hint="builder_summary")
 
     associated_resource_apply = associated_resource_subparsers.add_parser("apply", help="声明式管理应用关联资源池和视图展示配置")
-    associated_resource_apply.add_argument("--app-key", required=True)
+    associated_resource_apply.add_argument("--app-key", default="")
     associated_resource_apply.add_argument("--upsert-resources-file")
     associated_resource_apply.add_argument("--patch-resources-file")
     associated_resource_apply.add_argument("--remove-associated-item-ids-file")
     associated_resource_apply.add_argument("--reorder-associated-item-ids-file")
     associated_resource_apply.add_argument("--view-configs-file")
+    associated_resource_apply.add_argument("--apps-file", help="多应用批量关联资源 JSON 数组，每项含 app_key + upsert_resources/patch_resources/remove_associated_item_ids/reorder_associated_item_ids/view_configs")
     associated_resource_apply.set_defaults(handler=_handle_associated_resource_apply, format_hint="builder_summary", force_json_output=True)
 
     portal = builder_subparsers.add_parser("portal", help="门户")
@@ -456,6 +457,36 @@ def _handle_button_apply(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 def _handle_associated_resource_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    apps = load_list_arg(getattr(args, "apps_file", None), option_name="--apps-file")
+    if apps:
+        single_app_args = [
+            a for a in [
+                "--app-key" if args.app_key else None,
+                "--upsert-resources-file" if getattr(args, "upsert_resources_file", None) else None,
+                "--patch-resources-file" if getattr(args, "patch_resources_file", None) else None,
+                "--remove-associated-item-ids-file" if getattr(args, "remove_associated_item_ids_file", None) else None,
+                "--reorder-associated-item-ids-file" if getattr(args, "reorder_associated_item_ids_file", None) else None,
+                "--view-configs-file" if getattr(args, "view_configs_file", None) else None,
+            ] if a
+        ]
+        if single_app_args:
+            raise_config_error(
+                f"associated-resource apply --apps-file cannot be combined with {', '.join(single_app_args)}.",
+                fix_hint="Use --apps-file for batch mode (each item contains app_key + per-app params), or remove --apps-file for single-app mode.",
+            )
+    if apps:
+        return context.builder.app_associated_resources_apply(
+            profile=args.profile,
+            app_key="",
+            upsert_resources=[],
+            patch_resources=[],
+            remove_associated_item_ids=[],
+            reorder_associated_item_ids=[],
+            view_configs=[],
+            apps=apps,
+        )
+    if not args.app_key:
+        raise_config_error("associated-resource apply requires --app-key or --apps-file", fix_hint="Pass --app-key APP_KEY for single-app mode, or --apps-file for batch mode.")
     return context.builder.app_associated_resources_apply(
         profile=args.profile,
         app_key=args.app_key,

package/src/qingflow_mcp/cli/main.py

@@ -9,6 +9,7 @@ from ..errors import QingflowApiError
 from ..public_surface import cli_public_tool_spec_from_namespace
 from ..response_trim import resolve_cli_tool_name, trim_error_response, trim_public_response
 from ..tools.ai_builder_tools import _attach_builder_apply_envelope
+from ..version import get_cli_version, get_cli_version_info
 from .context import CliContext, build_cli_context
 from .formatters import emit_json_result, emit_text_result
 from .commands import register_all_commands
@@ -34,7 +35,10 @@ def build_parser() -> argparse.ArgumentParser:
     parser = _QingflowArgumentParser(prog="qingflow", description="Qingflow CLI")
     parser.add_argument("--profile", default="default", help="会话 profile，默认 default")
     parser.add_argument("--json", action="store_true", help="输出 JSON")
+    parser.add_argument("--version", action="store_true", help="输出 Qingflow CLI 版本")
     subparsers = parser.add_subparsers(dest="command", required=True)
+    version_parser = subparsers.add_parser("version", help="输出 Qingflow CLI 版本")
+    version_parser.set_defaults(handler=_handle_version, format_hint="version")
     register_all_commands(subparsers)
     return parser
 
@@ -54,6 +58,8 @@ def run(
     err = stderr or sys.stderr
     parser = build_parser()
     normalized_argv = _normalize_global_args(list(argv) if argv is not None else sys.argv[1:])
+    if "--version" in normalized_argv:
+        return _emit_version(json_mode=_should_force_json_output_argv_for_version(normalized_argv), stdout=out)
     try:
         args = parser.parse_args(normalized_argv)
     except _CliArgumentError as exc:
@@ -76,6 +82,8 @@ def run(
     setattr(args, "_stdin", sys.stdin)
     setattr(args, "_stdout_stream", out)
     setattr(args, "_stderr_stream", err)
+    if getattr(args, "command", "") == "version":
+        return _emit_version(json_mode=bool(args.json), stdout=out)
     handler = getattr(args, "handler", None)
     if handler is None:
         parser.print_help(out)
@@ -121,6 +129,10 @@ def _normalize_global_args(argv: list[str]) -> list[str]:
             global_args.append(token)
             index += 1
             continue
+        if token == "--version":
+            global_args.append(token)
+            index += 1
+            continue
         if token == "--profile":
             global_args.append(token)
             if index + 1 >= len(argv):
@@ -138,6 +150,35 @@ def _normalize_global_args(argv: list[str]) -> list[str]:
     return global_args + remaining
 
 
+def _handle_version(_args: argparse.Namespace, _context: CliContext) -> dict[str, Any]:
+    info = get_cli_version_info()
+    return {
+        "ok": True,
+        "status": "success",
+        **info,
+    }
+
+
+def _emit_version(*, json_mode: bool, stdout: TextIO) -> int:
+    version = get_cli_version()
+    if json_mode:
+        emit_json_result(
+            {
+                "ok": True,
+                "status": "success",
+                **get_cli_version_info(),
+            },
+            stream=stdout,
+        )
+    else:
+        stdout.write(f"{version}\n")
+    return 0
+
+
+def _should_force_json_output_argv_for_version(argv: list[str]) -> bool:
+    return "--json" in argv
+
+
 def _should_force_json_output(args: argparse.Namespace) -> bool:
     if bool(getattr(args, "force_json_output", False)):
         return True

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -284,6 +284,7 @@ class AiBuilderTools(ToolBase):
             remove_associated_item_ids: list[int] | None = None,
             reorder_associated_item_ids: list[int] | None = None,
             view_configs: list[JSONObject] | None = None,
+            apps: list[JSONObject] | None = None,
         ) -> JSONObject:
             return self.app_associated_resources_apply(
                 profile=profile,
@@ -293,6 +294,7 @@ class AiBuilderTools(ToolBase):
                 remove_associated_item_ids=remove_associated_item_ids or [],
                 reorder_associated_item_ids=reorder_associated_item_ids or [],
                 view_configs=view_configs or [],
+                apps=apps,
             )
 
         @mcp.tool()
@@ -1120,8 +1122,24 @@ class AiBuilderTools(ToolBase):
         reorder_associated_item_ids: list[int],
         view_configs: list[JSONObject],
         patch_resources: list[JSONObject] | None = None,
+        apps: list[JSONObject] | None = None,
     ) -> JSONObject:
         """执行应用关联资源 apply 逻辑。"""
+        if apps:
+            return self._facade._batch_write_apps(
+                profile=profile,
+                apps=apps,
+                single_writer=lambda profile, app_key, **kw: self.app_associated_resources_apply(
+                    profile=profile,
+                    app_key=app_key,
+                    upsert_resources=kw.get("upsert_resources", []),
+                    patch_resources=kw.get("patch_resources", []),
+                    remove_associated_item_ids=kw.get("remove_associated_item_ids", []),
+                    reorder_associated_item_ids=kw.get("reorder_associated_item_ids", []),
+                    view_configs=kw.get("view_configs", []),
+                ),
+                tool_name="app_associated_resources_apply",
+            )
         raw_request = {
             "app_key": app_key,
             "upsert_resources": upsert_resources,
@@ -4458,6 +4476,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
     "app_associated_resources_apply": {
         "allowed_keys": [
             "app_key",
+            "apps",
             "upsert_resources",
             "patch_resources",
             "remove_associated_item_ids",
@@ -4527,6 +4546,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "if an associated resource delete returns readback_status=unavailable or still_exists, treat the result as readback pending and do not blindly repeat the delete",
             "this tool publishes after at least one write succeeds; there is no draft-only mode",
             "visible=false hides the associated-resource area without clearing previous selected ids; visible=true with limit_type=all shows the whole app-level pool",
+            "accepts apps[] for multi-app batch; each item is {app_key, upsert_resources?, patch_resources?, remove_associated_item_ids?, reorder_associated_item_ids?, view_configs?}",
         ],
         "minimal_example": {
             "profile": "default",
@@ -4557,6 +4577,22 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                 }
             ],
         },
+        "batch_example": {
+            "profile": "default",
+            "apps": [
+                {
+                    "app_key": "APP_1",
+                    "upsert_resources": [
+                        {"client_key": "orders_view", "graph_type": "view", "target_app_key": "ORDER_APP", "view_key": "ORDER_VIEW"}
+                    ],
+                    "view_configs": [{"view_key": "MAIN_VIEW", "limit_type": "select", "associated_item_refs": ["orders_view"]}],
+                },
+                {
+                    "app_key": "APP_2",
+                    "view_configs": [{"view_key": "MAIN_VIEW", "visible": True, "limit_type": "all"}],
+                },
+            ],
+        },
     },
     "app_schema_plan": {
         "allowed_keys": ["app_key", "package_id", "app_name", "icon", "color", "visibility", "create_if_missing", "add_fields", "update_fields", "remove_fields"],
@@ -5552,7 +5588,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "call workspace_icon_catalog_get or `qingflow --json builder icon catalog` for supported icon/color candidates",
             "portal_apply uses replace semantics for sections",
             "when editing an existing portal, sections may be omitted to update only base info such as visibility, icon, or package",
-            "use patch_sections[] for targeted section updates without replacing all sections; each item needs one selector (chart_ref with chart_id/chart_key/chart_name, view_ref with view_key/view_name, or order as 0-based index) plus set/unset",
+            "use patch_sections[] for section-level patch updates without replacing all sections; each item needs one selector (chart_ref with chart_id/chart_key/chart_name, view_ref with view_key/view_name, or order as 0-based index) plus set/unset",
             "when sections[] is supplied without patch_sections[], it uses replace semantics for all sections",
             "remove a section by omitting it from the sections list (replace mode) or by unset in patch_sections (patch mode)",
             "package_id is required when creating a new portal",

package/src/qingflow_mcp/version.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import sys
+from importlib import metadata
+from pathlib import Path
+
+
+def get_cli_version() -> str:
+    package_json_version = _find_package_json_version()
+    if package_json_version:
+        return package_json_version
+    try:
+        return metadata.version("qingflow-mcp")
+    except metadata.PackageNotFoundError:
+        return "0+local"
+
+
+def get_cli_version_info() -> dict[str, str | None]:
+    package_root = _find_package_root()
+    return {
+        "version": get_cli_version(),
+        "package": _find_package_name(package_root) or "@qingflow-tech/qingflow-cli",
+        "executable_path": _resolve_executable_path(),
+        "command_path": shutil.which("qingflow"),
+        "package_root": str(package_root) if package_root is not None else None,
+        "skill_version": _find_skill_version(package_root),
+    }
+
+
+def _find_package_json_version() -> str | None:
+    package_root = _find_package_root()
+    if package_root is None:
+        return None
+    try:
+        payload = json.loads((package_root / "package.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    version = str(payload.get("version") or "")
+    return version or None
+
+
+def _find_package_root() -> Path | None:
+    current = Path(__file__).resolve()
+    for parent in current.parents:
+        package_json = parent / "package.json"
+        if not package_json.exists():
+            continue
+        try:
+            payload = json.loads(package_json.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        name = str(payload.get("name") or "")
+        version = str(payload.get("version") or "")
+        if version and name in {
+            "qingflow-mcp-workspace",
+            "@qingflow-tech/qingflow-cli",
+            "@qingflow-tech/qingflow-app-user-mcp",
+            "@qingflow-tech/qingflow-app-builder-mcp",
+            "@josephyan/qingflow-cli",
+            "@josephyan/qingflow-app-user-mcp",
+            "@josephyan/qingflow-app-builder-mcp",
+        }:
+            return parent
+    return None
+
+
+def _find_package_name(package_root: Path | None) -> str | None:
+    if package_root is None:
+        return None
+    try:
+        payload = json.loads((package_root / "package.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    name = str(payload.get("name") or "")
+    return name or None
+
+
+def _resolve_executable_path() -> str | None:
+    if not sys.argv:
+        return None
+    raw = str(sys.argv[0] or "").strip()
+    if not raw:
+        return None
+    try:
+        return str(Path(raw).resolve())
+    except OSError:
+        return raw
+
+
+def _find_skill_version(package_root: Path | None) -> str | None:
+    if package_root is None:
+        return None
+    candidates = [
+        package_root / "skills" / "qingflow-cli" / "SKILL.md",
+        package_root / "skill" / "qingflow-cli" / "SKILL.md",
+    ]
+    for skill_file in candidates:
+        if not skill_file.exists():
+            continue
+        try:
+            text = skill_file.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        match = re.search(r"Skill\s*版本\**[:：]\s*`?([^`\s）)]+)", text)
+        if match:
+            return match.group(1).strip()
+    return None