@josephyan/qingflow-cli 1.1.14 → 1.1.16

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-cli@1.1.14
+npm install @josephyan/qingflow-cli@1.1.16
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-cli@1.1.14 qingflow
+npx -y -p @josephyan/qingflow-cli@1.1.16 qingflow
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-cli",
-  "version": "1.1.14",
+  "version": "1.1.16",
   "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

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

package/skills/qingflow-cli/reference/builder/30-schema-fields.md

@@ -112,7 +112,7 @@ Example patch:
 |------|----------------|------|
 | 编辑已有应用 | `--app-key`；可选 `--no-publish` | **不要**与 `--package-id`、`--create-if-missing` 同用 |
 | 包内新建应用 | `--package-id`、`--app-name`（或 title 映射）、**`--create-if-missing`**；初始 `add-fields-file` 至少包含一个 `as_data_title: true` 字段 | 创建后可得到新 **`app_key`**（以响应为准） |
-| 多应用一次性新建 | `--package-id`、**`--create-if-missing`**、`--apps-file` | 应用包/系统里有 2 个以上应用，或同批应用之间有 `relation` 时使用；`--apps-file` 主写法为 `{package_id, apps}` 对象，raw apps array / singleton wrapper array 仅兼容；`apps[].client_key` 可被 `target_app_ref` 引用，`apps[].app_name` 可被 `target_app` 引用 |
+| 多应用一次性新建 | `--apps-file`，文件顶层写 `package_id` + `apps` | 应用包/系统里有 2 个以上应用，或同批应用之间有 `relation` 时使用；多应用默认按 `app_name` 创建或复用缺失应用，不要求额外写 `create_if_missing`；raw apps array / singleton wrapper array 仅兼容；`apps[].client_key` 可被 `target_app_ref` 引用，`apps[].app_name` 可被 `target_app` 引用 |
 | 仅增字段 | `--add-fields-file`（JSON 数组） | 与 **`update_fields`/`remove_fields`** 可同次组合（以契约为准） |
 | 改字段 | `--update-fields-file` | 每项 **`selector`**（`name`/`que_id`/`field_id`）+ **`set`** |
 | 删字段 | `--remove-fields-file` | 每项至少 **`name`/`que_id`/`field_id`** 之一 |
@@ -136,9 +136,9 @@ Example patch:
 
 **一次性新建应用**：`--package-id` + `--app-name` + `--create-if-missing` + [schema_apply_add_fields_all_types.json](../examples/schema/schema_apply_add_fields_all_types.json) 是当前推荐示例；它已包含唯一数据标题和可选数据封面（`q_linker` 使用 `https://httpbin.org/get`，`relation` 指向可读模板应用 `ead8ims5i401`）。
 
-**一次性新建多个应用**：用 `builder schema apply --package-id <TAG_ID> --create-if-missing --apps-file tmp/apps.json`，其中 `tmp/apps.json` 主写法为 `{ "package_id": 123, "apps": [...] }`，每个 `apps[]` 写顶层 `icon + color`；`apps[].client_key` 可被同批 relation 字段的 `target_app_ref` 引用，`apps[].app_name` 可被 `target_app` 引用，工具会编译成真实 `target_app_key`。这是应用包/系统搭建的默认路径，尤其适合“商机 + 订单 + 回款”“花名册 + 工时”等互相关联场景；不要为了拿 `app_key` 先逐个创建再二次补关联字段。
+**一次性新建多个应用**：用 `builder schema apply --apps-file tmp/apps.json`，其中 `tmp/apps.json` 主写法为 `{ "package_id": 123, "apps": [...] }`，每个 `apps[]` 写顶层 `icon + color`；多应用模式默认按 `app_name` 创建或复用应用。`apps[].client_key` 可被同批 relation 字段的 `target_app_ref` 引用，`apps[].app_name` 可被 `target_app` 引用，工具会编译成真实 `target_app_key`。这是应用包/系统搭建的默认路径，尤其适合“商机 + 订单 + 回款”“花名册 + 工时”等互相关联场景；不要为了拿 `app_key` 先逐个创建再二次补关联字段。
 
-**限制（平台硬性）**：每应用 **至多一个** `relation`；`--app-key` 向已有应用追加时须 **字段名不重复**、且 **不能**在已有 relation 上再增第二个。**`example.com`** 作 `q_linker` URL 易触发 **`46031`**，本清单改用 httpbin。**读回缺 `outputs[].target_field` 的 `q_linker`** 会拖死后续 `schema apply`，须修复或删除该题。
+**限制（平台硬性）**：`--app-key` 向已有应用追加字段时须 **字段名不重复**；`relation` 字段数量不做“每应用只能一个”的智能体侧限制，按后端实际校验和写后读回为准。**`example.com`** 作 `q_linker` URL 易触发 **`46031`**，本清单改用 httpbin。**读回缺 `outputs[].target_field` 的 `q_linker`** 会拖死后续 `schema apply`，须修复或删除该题。
 
 **排障**：`--json`；**`DUPLICATE_FIELD`**；**`MULTIPLE_RELATION_FIELDS_UNSUPPORTED`（49614）**。
 

package/skills/qingflow-cli/reference/builder/reference/app-delivery-sop.md

@@ -130,7 +130,7 @@ qingflow builder schema apply \
 
 - **`--icon` / `--color`**：取值以 `builder contract --tool-name app_schema_apply` / 当前 CLI 契约候选为准；不要自造 `sales-*`、`crm-*` 等业务语义 key。契约未返回候选值时省略该参数，不要猜测写入。
 
-- **创建模式要件**（与契约一致）：**`package_id` + `app_name`（或 CLI 的 app-title 映射到 app_name）+ `create_if_missing`**。
+- **单应用创建模式要件**（与契约一致）：**`package_id` + `app_name`（或 CLI 的 app-title 映射到 app_name）+ `create_if_missing`**。
 - **图标必填**：创建应用必须显式传合法的 **`icon + color`**；不要用 `template`。CLI 只校验候选，不根据应用名称自动猜图标。多应用批量创建时，每个新应用应使用不同 `icon`。
 - **数据标题必填**：最终表单必须有且仅有一个顶层可读字段标记 `as_data_title: true`；数据封面可选，必须是顶层 `attachment` 字段标记 `as_data_cover: true`。
 - **编辑模式**：**仅** **`--app-key`**（可选改名 `--app-name`），**不要**与 `package_id` / `create_if_missing` 混用。
@@ -141,12 +141,10 @@ qingflow builder schema apply \
 
 ```bash
 qingflow builder schema apply \
-  --package-id <TAG_ID> \
-  --create-if-missing \
   --apps-file tmp/apps.json
 ```
 
-`apps.json` 主写法是对象形态 `{ "package_id": 123, "apps": [...] }`。CLI 兼容 raw apps array 和 singleton wrapper array，但不作为智能体主示例；不要把多个 `{package_id, apps}` wrapper 放进数组里。每个 `apps[]` 是一个应用 schema 配置，写自己的 `client_key`、`app_name`、`icon`、`color`、`add_fields`；同批应用之间的关联字段主写 **`target_app_ref`** 指向另一个应用的 `client_key`。只有目标应用已经存在或已被读回确认时，才使用真实 `target_app_key`；不要因为同批创建时还不知道真实 `app_key` 就放弃 `target_app_ref`。写入前 CLI 会先做静态预校验，`client_key/app_name` 重复、缺少 `as_data_title`、未开 `create_if_missing`、`target_app_ref/target_app` 无法解析都会以 `MULTI_APP_STATIC_VALIDATION_FAILED` 返回，不会先创建半成品应用：
+`apps.json` 主写法是对象形态 `{ "package_id": 123, "apps": [...] }`，多应用模式默认允许按 `app_name` 创建或复用应用，不要求智能体额外写 `create_if_missing`。CLI 兼容 raw apps array 和 singleton wrapper array，但不作为智能体主示例；不要把多个 `{package_id, apps}` wrapper 放进数组里。每个 `apps[]` 是一个应用 schema 配置，写自己的 `client_key`、`app_name`、`icon`、`color`、`add_fields`；同批应用之间的关联字段主写 **`target_app_ref`** 指向另一个应用的 `client_key`。只有目标应用已经存在或已被读回确认时，才使用真实 `target_app_key`；不要因为同批创建时还不知道真实 `app_key` 就放弃 `target_app_ref`。写入前 CLI 会先做静态预校验，`client_key/app_name` 重复、缺少 `as_data_title`、显式 `create_if_missing:false` 但 `apps[]` 仍用 `app_name` 省略 `app_key`、`target_app_ref/target_app` 无法解析都会以 `MULTI_APP_STATIC_VALIDATION_FAILED` 返回，不会先创建半成品应用：
 
 ```json
 {
@@ -257,7 +255,7 @@ qingflow builder schema apply \
 （路径以 `qingflow-cli/` 技能根目录为基准；执行时可解析为该技能目录下的实际文件。）
 
 - **`name`** 须为当前应用内 **唯一** 的控件显示名；若报重名，改 **`示例搭建_CLI单行`** 后再执行。
-- 本文件对应契约 **`app_schema_apply`** 中 **`add_fields`** 的 **最小 `text`** 项；更多 **`type`** 见 **§6**；完整创建应用：单应用见 **§3.2**（**`package_id` + `app_name` + `create_if_missing`**），多应用/跨应用引用见 **§3.3**（**`--apps-file` + `client_key` / `target_app_ref`**）。
+- 本文件对应契约 **`app_schema_apply`** 中 **`add_fields`** 的 **最小 `text`** 项；更多 **`type`** 见 **§6**；完整创建应用：单应用见 **§3.2**（**`package_id` + `app_name` + `create_if_missing`**），多应用/跨应用引用见 **§3.3**（**`--apps-file` + `client_key` / `target_app_ref`**，默认创建或复用缺失应用）。
 
 ```bash
 qingflow builder schema apply \

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

@@ -563,7 +563,7 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
         file_create_if_missing = _coerce_apps_file_bool(
             apps_payload.get("create_if_missing"),
             field_name="create_if_missing",
-            default=False,
+            default=True,
         )
         file_publish = _coerce_apps_file_bool(
             apps_payload.get("publish"),
@@ -580,7 +580,7 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
             )
         if args.app_key or args.app_name or args.app_title or args.add_fields_file or args.update_fields_file or args.remove_fields_file:
             raise_config_error(
-                "schema apply multi-app mode accepts --package-id/--create-if-missing plus --apps-file only.",
+                "schema apply multi-app mode accepts --package-id plus --apps-file only; --create-if-missing is optional.",
                 fix_hint="Use `--apps-file` for batch mode, or remove `--apps-file` and use the single-app arguments.",
             )
         if package_id is None:

package/src/qingflow_mcp/server_app_builder.py

@@ -197,7 +197,7 @@ def build_builder_server() -> FastMCP:
         profile: str = DEFAULT_PROFILE,
         package_id: int | None = None,
         package_name: str | None = None,
-        create_if_missing: bool = False,
+        create_if_missing: bool | None = None,
         icon: str | None = None,
         color: str | None = None,
         visibility: dict | None = None,
@@ -426,7 +426,7 @@ def build_builder_server() -> FastMCP:
         icon: str = "",
         color: str = "",
         visibility: dict | None = None,
-        create_if_missing: bool = False,
+        create_if_missing: bool | None = None,
         publish: bool = True,
         add_fields: list[dict] | None = None,
         update_fields: list[dict] | None = None,
@@ -436,7 +436,7 @@ def build_builder_server() -> FastMCP:
         if apps:
             if app_key or app_name or app_title or add_fields or update_fields or remove_fields:
                 return _config_failure(
-                    "app_schema_apply multi-app mode accepts package_id/create_if_missing plus apps only.",
+                    "app_schema_apply multi-app mode accepts package_id plus apps only; create_if_missing is optional.",
                     fix_hint="Use `apps` for batch mode, or use the single-app arguments without `apps`.",
                 )
             if package_id is None:
@@ -448,7 +448,7 @@ def build_builder_server() -> FastMCP:
                 profile=profile,
                 package_id=package_id,
                 visibility=visibility,
-                create_if_missing=create_if_missing,
+                create_if_missing=True if create_if_missing is None else bool(create_if_missing),
                 publish=publish,
                 add_fields=[],
                 update_fields=[],
@@ -459,13 +459,14 @@ def build_builder_server() -> FastMCP:
         has_app_name = bool((app_name or "").strip())
         has_app_title = bool((app_title or "").strip())
         has_package_id = package_id is not None
+        effective_create_if_missing = bool(create_if_missing)
         if has_app_key:
-            if create_if_missing or has_package_id:
+            if effective_create_if_missing or has_package_id:
                 return _config_failure(
                     "app_schema_apply edit mode accepts app_key and optional app_name rename only.",
                     fix_hint="For existing apps, use `app_key` and optionally `app_name`. For create mode, use `package_id + app_name + create_if_missing=true`.",
                 )
-        elif not (create_if_missing and has_package_id and (has_app_name or has_app_title)):
+        elif not (effective_create_if_missing and has_package_id and (has_app_name or has_app_title)):
             return _config_failure(
                 "app_schema_apply create mode requires package_id, app_name, and create_if_missing=true.",
                 fix_hint="Use `app_key` for existing apps, or pass `package_id + app_name + create_if_missing=true` to create a new app.",
@@ -479,7 +480,7 @@ def build_builder_server() -> FastMCP:
             icon=icon,
             color=color,
             visibility=visibility,
-            create_if_missing=create_if_missing,
+            create_if_missing=effective_create_if_missing,
             publish=publish,
             add_fields=add_fields or [],
             update_fields=update_fields or [],

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -330,7 +330,7 @@ class AiBuilderTools(ToolBase):
             profile: str = DEFAULT_PROFILE,
             package_id: int | None = None,
             package_name: str | None = None,
-            create_if_missing: bool = False,
+            create_if_missing: bool | None = None,
             icon: str | JSONObject | None = None,
             color: str | None = None,
             icon_name: str | None = None,
@@ -573,7 +573,7 @@ class AiBuilderTools(ToolBase):
             icon_color: str | None = None,
             icon_config: JSONObject | None = None,
             visibility: JSONObject | None = None,
-            create_if_missing: bool = False,
+            create_if_missing: bool | None = None,
             publish: bool = True,
             add_fields: list[JSONObject] | None = None,
             update_fields: list[JSONObject] | None = None,
@@ -584,7 +584,7 @@ class AiBuilderTools(ToolBase):
                 if app_key or app_name or app_title or add_fields or update_fields or remove_fields:
                     return _config_failure(
                         tool_name="app_schema_apply",
-                        message="app_schema_apply multi-app mode accepts package_id/create_if_missing plus apps only.",
+                        message="app_schema_apply multi-app mode accepts package_id plus apps only; create_if_missing is optional.",
                         fix_hint="Use `apps` for batch mode, or use the single-app arguments without `apps`.",
                     )
                 if package_id is None:
@@ -597,7 +597,7 @@ class AiBuilderTools(ToolBase):
                     profile=profile,
                     package_id=package_id,
                     visibility=visibility,
-                    create_if_missing=create_if_missing,
+                    create_if_missing=True if create_if_missing is None else bool(create_if_missing),
                     publish=publish,
                     apps=apps,
                     add_fields=[],
@@ -608,14 +608,15 @@ class AiBuilderTools(ToolBase):
             has_app_name = bool((app_name or "").strip())
             has_app_title = bool((app_title or "").strip())
             has_package_id = package_id is not None
+            effective_create_if_missing = bool(create_if_missing)
             if has_app_key:
-                if create_if_missing or has_package_id:
+                if effective_create_if_missing or has_package_id:
                     return _config_failure(
                         tool_name="app_schema_apply",
                         message="app_schema_apply edit mode accepts app_key and optional app_name rename only.",
                         fix_hint="For existing apps, use `app_key` and optionally `app_name`. For create mode, use `package_id + app_name + create_if_missing=true`.",
                     )
-            elif not (create_if_missing and has_package_id and (has_app_name or has_app_title)):
+            elif not (effective_create_if_missing and has_package_id and (has_app_name or has_app_title)):
                 return _config_failure(
                     tool_name="app_schema_apply",
                     message="app_schema_apply create mode requires package_id, app_name, and create_if_missing=true.",
@@ -633,7 +634,7 @@ class AiBuilderTools(ToolBase):
                 icon_color=icon_color,
                 icon_config=icon_config,
                 visibility=visibility,
-                create_if_missing=create_if_missing,
+                create_if_missing=effective_create_if_missing,
                 publish=publish,
                 add_fields=add_fields or [],
                 update_fields=update_fields or [],
@@ -979,7 +980,7 @@ class AiBuilderTools(ToolBase):
         profile: str,
         package_id: int | None = None,
         package_name: str | None = None,
-        create_if_missing: bool = False,
+        create_if_missing: bool | None = None,
         icon: str | JSONObject | None = None,
         color: str | None = None,
         icon_name: str | None = None,
@@ -1849,7 +1850,7 @@ class AiBuilderTools(ToolBase):
         icon: str = "",
         color: str = "",
         visibility: JSONObject | None = None,
-        create_if_missing: bool = False,
+        create_if_missing: bool | None = None,
         add_fields: list[JSONObject],
         update_fields: list[JSONObject],
         remove_fields: list[JSONObject],
@@ -2077,7 +2078,7 @@ class AiBuilderTools(ToolBase):
         icon_color: str | None = None,
         icon_config: JSONObject | None = None,
         visibility: JSONObject | None = None,
-        create_if_missing: bool = False,
+        create_if_missing: bool | None = None,
         publish: bool = True,
         add_fields: list[JSONObject],
         update_fields: list[JSONObject],
@@ -2108,7 +2109,7 @@ class AiBuilderTools(ToolBase):
                 profile=profile,
                 package_id=package_id,
                 visibility=visibility,
-                create_if_missing=create_if_missing,
+                create_if_missing=True if create_if_missing is None else bool(create_if_missing),
                 publish=publish,
                 apps=apps,
             )
@@ -2126,7 +2127,7 @@ class AiBuilderTools(ToolBase):
             icon=icon,
             color=color,
             visibility=visibility,
-            create_if_missing=create_if_missing,
+            create_if_missing=bool(create_if_missing),
             publish=publish,
             add_fields=add_fields,
             update_fields=update_fields,
@@ -3745,8 +3746,8 @@ def _multi_app_static_validation_failure(
                     "row_number": index + 1,
                     "path": f"apps[{index}]",
                     "error_code": "CREATE_IF_MISSING_REQUIRED",
-                    "message": "new multi-app items require create_if_missing=true",
-                    "fix_hint": "Set create_if_missing=true, or pass app_key for an existing app.",
+                    "message": "apps[] item with app_name but no app_key cannot run when create_if_missing=false",
+                    "fix_hint": "Omit create_if_missing in multi-app mode, set it to true, or pass app_key for every existing app item.",
                 }
             )
 
@@ -6092,9 +6093,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "edit mode: app_key, optional app_name to rename the existing app",
             "create mode: package_id + app_name + create_if_missing=true",
             "create mode follows backend CreateAppBean: package add_app permission is checked on the target package; package edit_app is not required for the create precheck",
-            "multi-app mode: pass package_id + create_if_missing + apps[]; do not mix apps with top-level app_key/app_name/add_fields/update_fields/remove_fields",
+            "multi-app mode: pass package_id + apps[]; create_if_missing defaults to true for app_name items and may be set false only when every item uses app_key",
             "CLI --apps-file primary shape is {package_id, apps:[...]}; raw app arrays and singleton wrapper arrays are compatibility paths, not recommended examples",
-            "multi-app mode preflights static errors before writing: duplicate client_key/app_name, missing data title on new apps, create_if_missing omissions, and unresolved target_app_ref/target_app",
+            "multi-app mode preflights static errors before writing: duplicate client_key/app_name, missing data title on new apps, explicit create_if_missing=false with app_name items, and unresolved target_app_ref/target_app",
             "multi-app relation fields may use target_app_ref to point at another apps[].client_key; the tool creates/resolves app shells first and compiles it to target_app_key",
             "multi-app relation fields may also use target_app with another apps[].app_name; prefer target_app_ref/client_key when names may collide",
             "multi-app mode is not transactional; read created_app_keys and apps[].status before retrying, and retry only failed app items",
@@ -6147,7 +6148,6 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "multi_app_example": {
             "profile": "default",
             "package_id": 1001,
-            "create_if_missing": True,
             "publish": True,
             "apps": [
                 {