@qingflow-tech/qingflow-app-user-mcp 1.0.41 → 1.0.43

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @qingflow-tech/qingflow-app-user-mcp@1.0.41
+npm install @qingflow-tech/qingflow-app-user-mcp@1.0.43
 ```
 
 Run:
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-app-user-mcp@1.0.41 qingflow-app-user-mcp
+npx -y -p @qingflow-tech/qingflow-app-user-mcp@1.0.43 qingflow-app-user-mcp
 ```
 
 Environment:
@@ -24,8 +24,6 @@ Bundled skills:
 
 - `skills/qingflow-app-user`
 - `skills/qingflow-mcp-setup`
-- `skills/qingflow-app-builder`
-- `skills/qingflow-app-builder-code-integrations`
 - `skills/qingflow-record-insert`
 - `skills/qingflow-record-update`
 - `skills/qingflow-record-delete`

package/docs/local-agent-install.md

@@ -128,7 +128,7 @@ qingflow-skills install --agent codex --scope user
 如果通过一次性 `npx -p <package>` 执行安装，请加 `--copy`，避免 symlink 指向 npm 临时执行缓存：
 
 ```bash
-npx -y -p @josephyan/qingflow-cli qingflow-skills install --agent codex --scope user --copy
+npx -y -p @qingflow-tech/qingflow-cli qingflow-skills install --agent codex --scope user --copy
 ```
 
 也可以挂载到项目级 agent 目录：
@@ -268,7 +268,7 @@ qingflow-app-builder-mcp-skills list
       "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",
@@ -281,7 +281,7 @@ qingflow-app-builder-mcp-skills list
       "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",
@@ -323,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-app-user-mcp",
-  "version": "1.0.41",
+  "version": "1.0.43",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

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

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

@@ -7,7 +7,7 @@ metadata:
 
 # Qingflow App User
 
-> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+> **Skill 版本**：`qingflow-skills-2026.06.24.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
 
 ## Overview
 
@@ -41,7 +41,7 @@ Route to exactly one of these specialized paths:
    Switch to [$qingflow-mcp-setup](../qingflow-mcp-setup/SKILL.md)
 
 8. App / view / workflow / chart / portal / package configuration
-   Switch to [$qingflow-app-builder](../qingflow-app-builder/SKILL.md)
+   This is outside the App User MCP tool surface. Use the separate `qingflow-app-builder` skill/MCP package when that builder surface is installed; otherwise ask the user to enable the builder MCP.
 
 ## Routing Rules
 
@@ -52,7 +52,7 @@ Route to exactly one of these specialized paths:
 - If the task is about deleting records directly, switch to `$qingflow-record-delete`
 - If the task is about import templates, import capability discovery, import-file verification, authorized local file repair, import execution, or import status, switch to `$qingflow-record-import`
 - If the task is about todo discovery, task context, approval actions, rollback or transfer, associated report review, or workflow log review, switch to `$qingflow-task-ops`
-- If the task is about package, app, field, layout, workflow, view, chart, portal, visibility, icon, or app base configuration, switch to `$qingflow-app-builder`
+- If the task is about package, app, field, layout, workflow, view, chart, portal, visibility, icon, or app base configuration, do not continue with App User MCP tools. Use the separate `qingflow-app-builder` skill/MCP package when available, or ask the user to enable the builder MCP.
 - If the task involves member, department, or relation fields and the user only has natural names/titles, keep the same route; direct write now supports backend-native auto resolution and may return `needs_confirmation` with candidates instead of failing blind
 - For member/department field ambiguity, keep the record insert/update route and use `record_member_candidates` / `record_department_candidates`; do not switch to `directory_*`, builder member search, external-contact lookup, or contact-directory management queries. App User MCP only exposes `directory_search` for member-visible keyword search, not directory tree/list management.
 - If the task involves linked visibility, upstream/downstream field dependencies, reference-driven auto fill, or formula-driven defaulting, keep the same insert/update route and read field-level `linkage` from the schema before composing payloads
@@ -89,4 +89,4 @@ Route to exactly one of these specialized paths:
 - Record import: [$qingflow-record-import](../qingflow-record-import/SKILL.md)
 - Task workflow operations: [$qingflow-task-ops](../qingflow-task-ops/SKILL.md)
 - Dedicated analysis workflow: [$qingflow-record-analysis](../qingflow-record-analysis/SKILL.md)
-- Builder workflow: [$qingflow-app-builder](../qingflow-app-builder/SKILL.md)
+- Builder workflow requires the separate `qingflow-app-builder` skill/MCP package.

package/skills/qingflow-mcp-setup/SKILL.md

@@ -7,7 +7,7 @@ metadata:
 
 # Qingflow MCP Setup
 
-> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+> **Skill 版本**：`qingflow-skills-2026.06.24.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
 
 ## Overview
 

package/skills/qingflow-record-analysis/SKILL.md

@@ -7,7 +7,7 @@ metadata:
 
 # Qingflow Record Analysis
 
-> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+> **Skill 版本**：`qingflow-skills-2026.06.24.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
 
 Use this skill only for final statistical conclusions: counts, distributions, ratios, averages, rankings, trends, comparisons, and analysis reports.
 

package/skills/qingflow-record-delete/SKILL.md

@@ -7,7 +7,7 @@ metadata:
 
 # Qingflow Record Delete
 
-> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+> **Skill 版本**：`qingflow-skills-2026.06.24.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
 
 ## Default Path
 

package/skills/qingflow-record-import/SKILL.md

@@ -7,7 +7,7 @@ metadata:
 
 # Qingflow Record Import
 
-> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+> **Skill 版本**：`qingflow-skills-2026.06.24.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
 
 ## Default Path
 

package/skills/qingflow-record-insert/SKILL.md

@@ -8,7 +8,7 @@ metadata:
 
 # Qingflow Record Insert
 
-> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+> **Skill 版本**：`qingflow-skills-2026.06.24.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
 
 ## Default Path
 

package/skills/qingflow-record-update/SKILL.md

@@ -7,7 +7,7 @@ metadata:
 
 # Qingflow Record Update
 
-> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+> **Skill 版本**：`qingflow-skills-2026.06.24.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
 
 ## Default Path
 

package/skills/qingflow-task-ops/SKILL.md

@@ -7,7 +7,7 @@ metadata:
 
 # Qingflow Task Ops
 
-> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+> **Skill 版本**：`qingflow-skills-2026.06.24.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
 
 ## Overview
 

package/src/qingflow_mcp/builder_facade/service.py

@@ -650,6 +650,42 @@ class AiBuilderFacade:
                 normalized_args=normalized_args,
             )
             if layout_result.get("status") not in {"success", "partial_success"}:
+                prior_package_write_executed = bool(
+                    created
+                    or (
+                        metadata_requested
+                        and isinstance(update_result, dict)
+                        and update_result.get("status") in {"success", "partial_success"}
+                        and not bool(update_result.get("noop"))
+                    )
+                )
+                if prior_package_write_executed:
+                    layout_details = layout_result.get("details") if isinstance(layout_result.get("details"), dict) else {}
+                    partial = _post_write_readback_pending_result(
+                        error_code=str(layout_result.get("error_code") or "PACKAGE_APPLY_PARTIAL"),
+                        message="created or updated package, but package layout apply failed; read package before retrying",
+                        normalized_args=normalized_args,
+                        details={
+                            "package_id": effective_package_id,
+                            "layout_error_code": layout_result.get("error_code"),
+                            "layout_result": layout_result,
+                            **(
+                                {"layout_write_error": layout_details.get("write_error")}
+                                if isinstance(layout_details.get("write_error"), dict)
+                                else {}
+                            ),
+                        },
+                        suggested_next_call={
+                            "tool_name": "package_get",
+                            "arguments": {"profile": profile, "package_id": effective_package_id},
+                        },
+                        request_id=layout_result.get("request_id") if isinstance(layout_result.get("request_id"), str) else None,
+                        backend_code=layout_result.get("backend_code"),
+                        http_status=layout_result.get("http_status") if isinstance(layout_result.get("http_status"), int) else None,
+                    )
+                    partial["package_id"] = effective_package_id
+                    partial["layout_failed"] = True
+                    return _apply_permission_outcomes(partial, *permission_outcomes)
                 return _apply_permission_outcomes(layout_result, *permission_outcomes)
 
         write_executed = bool(
@@ -13881,7 +13917,7 @@ def _failed_from_api_error(
                 "category": error.category,
             },
         )
-    return _failed(
+    result = _failed(
         effective_error_code,
         public_message,
         recoverable=recoverable,
@@ -13894,6 +13930,14 @@ def _failed_from_api_error(
         backend_code=error.backend_code,
         http_status=public_http_status,
     )
+    if _is_environment_quota_code(error.backend_code):
+        _mark_environment_quota_block(
+            result,
+            write_executed=False,
+            next_action="retry_after_quota_restored",
+            message="backend quota/AI assistant limit blocked this operation; retry after quota is restored",
+        )
+    return result
 
 
 def _post_write_readback_pending_result(
@@ -13947,6 +13991,15 @@ def _post_write_readback_pending_result(
         "next_action": "readback_before_retry",
     }
     result["verification"]["readback_before_retry"] = True
+    if _is_environment_quota_code(effective_backend_code):
+        result["readback_blocked_by_environment"] = True
+        result["verification"]["readback_blocked_by_environment"] = True
+        _mark_environment_quota_block(
+            result,
+            write_executed=True,
+            next_action="retry_after_quota_restored",
+            message="post-write readback was blocked by backend quota/AI assistant limit; retry readback after quota is restored",
+        )
     return result
 
 
@@ -13974,7 +14027,7 @@ def _post_write_may_have_succeeded_result(
     ):
         if value is not None:
             warning[key] = value
-    return {
+    result = {
         "status": "partial_success",
         "error_code": error_code,
         "recoverable": True,
@@ -14001,6 +14054,16 @@ def _post_write_may_have_succeeded_result(
         "safe_to_retry": False,
         "next_action": "readback_before_retry",
     }
+    if _is_environment_quota_code(effective_backend_code):
+        result["readback_blocked_by_environment"] = True
+        result["verification"]["readback_blocked_by_environment"] = True
+        _mark_environment_quota_block(
+            result,
+            write_executed=True,
+            next_action="retry_after_quota_restored",
+            message="write result or readback was blocked by backend quota/AI assistant limit; retry after quota is restored",
+        )
+    return result
 
 
 def _readback_transport_error_from_details(details: JSONObject) -> JSONObject | None:
@@ -14047,6 +14110,43 @@ def _transport_error_payload(error: QingflowApiError) -> JSONObject:
     }
 
 
+def _is_environment_quota_code(code: Any) -> bool:
+    return backend_code_value_int(code) == 59004
+
+
+def _mark_environment_quota_block(
+    payload: JSONObject,
+    *,
+    write_executed: bool,
+    next_action: str,
+    message: str,
+) -> None:
+    payload["environment_blocked"] = True
+    payload["blocker_type"] = "quota_limit"
+    payload["next_action"] = next_action
+    payload["safe_to_retry"] = False
+    payload["write_executed"] = bool(write_executed)
+    details = payload.get("details")
+    if not isinstance(details, dict):
+        details = {}
+        payload["details"] = details
+    details.setdefault("environment_blocked", True)
+    details.setdefault("blocker_type", "quota_limit")
+    details.setdefault("next_action", next_action)
+    details.setdefault("fix_hint", message)
+    warnings = payload.get("warnings")
+    if not isinstance(warnings, list):
+        warnings = []
+        payload["warnings"] = warnings
+    if not any(isinstance(item, dict) and item.get("code") == "ENVIRONMENT_QUOTA_LIMIT" for item in warnings):
+        warning = _warning("ENVIRONMENT_QUOTA_LIMIT", message)
+        for key in ("backend_code", "http_status", "request_id"):
+            value = payload.get(key)
+            if value is not None:
+                warning[key] = value
+        warnings.append(warning)
+
+
 def _is_uncertain_write_transport_error(error: QingflowApiError) -> bool:
     if is_auth_like_error(error):
         return False

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

@@ -5,7 +5,7 @@ from copy import deepcopy
 
 from ..context import CliContext
 from ..json_io import load_json_value
-from .common import load_list_arg, load_object_arg, raise_config_error, require_list_arg
+from .common import load_list_arg, load_object_arg, parse_bool_text, raise_config_error, require_list_arg
 
 
 def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
@@ -196,7 +196,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     schema_apply_apply.add_argument("--color")
     schema_apply_apply.add_argument("--visibility-file")
     schema_apply_apply.add_argument("--create-if-missing", action="store_true")
-    schema_apply_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
+    schema_apply_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=None)
     schema_apply_apply.add_argument("--apps-file", help="多应用 schema JSON 数组；每项可带 client_key/app_name/add_fields，支持 relation target_app_ref")
     schema_apply_apply.add_argument("--add-fields-file", help="字段 JSON 数组；字段可用 as_data_title/as_data_cover 标记数据标题/封面")
     schema_apply_apply.add_argument("--update-fields-file", help="字段更新 JSON 数组；set 内可用 as_data_title/as_data_cover 标记数据标题/封面")
@@ -483,8 +483,20 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
     apps_warnings = apps_payload.get("warnings") or []
     package_id = args.package_id
     if package_id is None and apps_payload.get("package_id") is not None:
-        package_id = int(apps_payload["package_id"])
+        package_id = _coerce_apps_file_package_id(apps_payload["package_id"])
     if args.apps_file:
+        file_create_if_missing = _coerce_apps_file_bool(
+            apps_payload.get("create_if_missing"),
+            field_name="create_if_missing",
+            default=False,
+        )
+        file_publish = _coerce_apps_file_bool(
+            apps_payload.get("publish"),
+            field_name="publish",
+            default=True,
+        )
+        effective_create_if_missing = bool(args.create_if_missing or file_create_if_missing)
+        effective_publish = bool(args.publish if args.publish is not None else file_publish)
         if not apps:
             raise_config_error(
                 "schema apply multi-app mode requires a non-empty --apps-file.",
@@ -505,8 +517,8 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
             profile=args.profile,
             package_id=package_id,
             visibility=load_object_arg(args.visibility_file, option_name="--visibility-file"),
-            create_if_missing=bool(args.create_if_missing),
-            publish=bool(args.publish),
+            create_if_missing=effective_create_if_missing,
+            publish=effective_publish,
             apps=apps,
             add_fields=[],
             update_fields=[],
@@ -543,7 +555,7 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
         color=args.color,
         visibility=load_object_arg(args.visibility_file, option_name="--visibility-file"),
         create_if_missing=bool(args.create_if_missing),
-        publish=bool(args.publish),
+        publish=True if args.publish is None else bool(args.publish),
         add_fields=load_list_arg(args.add_fields_file, option_name="--add-fields-file"),
         update_fields=load_list_arg(args.update_fields_file, option_name="--update-fields-file"),
         remove_fields=load_list_arg(args.remove_fields_file, option_name="--remove-fields-file"),
@@ -595,6 +607,10 @@ def _load_apps_file_arg(path: str | None) -> dict[str, object]:
             }
             if wrapper.get("package_id") is not None:
                 result["package_id"] = wrapper.get("package_id")
+            if wrapper.get("create_if_missing") is not None:
+                result["create_if_missing"] = wrapper.get("create_if_missing")
+            if wrapper.get("publish") is not None:
+                result["publish"] = wrapper.get("publish")
             return result
         if any(isinstance(item, dict) and "apps" in item for item in payload):
             raise_config_error(
@@ -616,6 +632,10 @@ def _load_apps_file_arg(path: str | None) -> dict[str, object]:
         result: dict[str, object] = {"apps": apps}
         if payload.get("package_id") is not None:
             result["package_id"] = payload.get("package_id")
+        if payload.get("create_if_missing") is not None:
+            result["create_if_missing"] = payload.get("create_if_missing")
+        if payload.get("publish") is not None:
+            result["publish"] = payload.get("publish")
         return result
     raise_config_error(
         "--apps-file must be a JSON array or an object containing apps.",
@@ -625,6 +645,60 @@ def _load_apps_file_arg(path: str | None) -> dict[str, object]:
     )
 
 
+def _coerce_apps_file_package_id(value: object) -> int:
+    package_id: int
+    if isinstance(value, bool):
+        _raise_apps_file_package_id_invalid(value)
+    if isinstance(value, int):
+        package_id = value
+    elif isinstance(value, str):
+        stripped = value.strip()
+        try:
+            package_id = int(stripped)
+        except ValueError:
+            _raise_apps_file_package_id_invalid(value)
+    else:
+        _raise_apps_file_package_id_invalid(value)
+    if package_id <= 0:
+        _raise_apps_file_package_id_invalid(value)
+    return package_id
+
+
+def _raise_apps_file_package_id_invalid(value: object) -> None:
+    raise_config_error(
+        "--apps-file package_id must be a positive integer.",
+        fix_hint='Use a numeric package_id, for example {"package_id":1001,"apps":[...]}.',
+        error_code="APPS_FILE_PACKAGE_ID_INVALID",
+        details={
+            "field": "package_id",
+            "value": value,
+            "expected": "positive integer or numeric string",
+        },
+    )
+
+
+def _coerce_apps_file_bool(value: object, *, field_name: str, default: bool) -> bool:
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        try:
+            return parse_bool_text(value)
+        except argparse.ArgumentTypeError:
+            pass
+    raise_config_error(
+        f"--apps-file {field_name} must be a boolean.",
+        fix_hint=f'Use "{field_name}": true or "{field_name}": false in --apps-file.',
+        error_code="APPS_FILE_BOOLEAN_INVALID",
+        details={
+            "field": field_name,
+            "value": value,
+            "expected": "boolean true/false or string true/false/1/0/yes/no",
+        },
+    )
+
+
 def _handle_layout_apply(args: argparse.Namespace, context: CliContext) -> dict:
     return context.builder.app_layout_apply(
         profile=args.profile,

package/src/qingflow_mcp/response_trim.py

@@ -100,7 +100,7 @@ def trim_error_response(payload: dict[str, Any]) -> dict[str, Any]:
     details = trimmed.get("details")
     if isinstance(details, dict):
         preserved = {}
-        for key in ("blocking_issues", "compiled_match_rules"):
+        for key in ("blocking_issues", "compiled_match_rules", "issues", "expected_shape"):
             if key in details:
                 preserved[key] = details.get(key)
         compact_details = _compact_scalar_dict(details)
@@ -184,7 +184,7 @@ def _trim_returned_failure(payload: dict[str, Any]) -> dict[str, Any]:
     details = trimmed.get("details")
     if isinstance(details, dict):
         preserved = {}
-        for key in ("blocking_issues", "compiled_match_rules"):
+        for key in ("blocking_issues", "compiled_match_rules", "issues", "expected_shape"):
             if key in details:
                 preserved[key] = details.get(key)
         compact_details = _compact_scalar_dict(details)
@@ -1071,8 +1071,9 @@ def _trim_builder_envelope(payload: JSONObject) -> None:
         if isinstance(details, dict):
             _drop_deep_keys(details, {"request_route", "base_url", "normalized_args", "suggested_next_call", "transport", "response", "body", "raw"})
             preserved = {}
-            if isinstance(details.get("compiled_match_rules"), dict):
-                preserved["compiled_match_rules"] = details.get("compiled_match_rules")
+            for key in ("compiled_match_rules", "issues", "expected_shape"):
+                if key in details:
+                    preserved[key] = details.get(key)
             compact = _compact_scalar_dict(details)
             compact.update(preserved)
             if compact: