@qingflow-tech/qingflow-cli 1.1.43-beta.2 → 1.1.43-beta.4

package/src/qingflow_mcp/server.py

@@ -26,12 +26,32 @@ from .tools.workflow_tools import WorkflowTools
 from .tools.workspace_tools import WorkspaceTools
 
 
+def _register_missing_builder_tools(server: FastMCP) -> None:
+    """Add current high-level builder tools to the unified MCP without duplicate names."""
+    from .server_app_builder import build_builder_server
+
+    builder_server = build_builder_server()
+    registered = server._tool_manager._tools
+    for tool in builder_server._tool_manager._tools.values():
+        if tool.name in registered:
+            continue
+        server.add_tool(
+            tool.fn,
+            name=tool.name,
+            title=tool.title,
+            description=tool.description,
+            annotations=tool.annotations,
+            icons=tool.icons,
+            meta=tool.meta,
+        )
+
+
 def build_server() -> FastMCP:
     today = date.today()
     current_year = today.year
     server = FastMCP(
         "Qingflow MCP",
-        instructions=f"""Use this server for Qingflow operational workflows. Current date: `{today.isoformat()}`.
+        instructions=f"""Use this unified server for Qingflow operational and builder workflows. Current date: `{today.isoformat()}`.
 
 ## Authentication
 
@@ -203,9 +223,9 @@ Normalize relative dates before building DSL.
 
 Default to `prod` unless the user explicitly specifies `test`.
 
-## Constraints
+## Builder Path
 
-Avoid builder-side app or schema changes here.
+Use the public builder tools for package, AppForm, workflow, view, chart, portal, and application configuration work. Pin the AppForm Schema version, preserve complete form declarations and existing IDs from draft reads, and use `app_form_apply` for reconciliation. Do not fall back to legacy raw builder write routes.
 
 ## Feedback Path
 
@@ -235,6 +255,7 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     WorkflowTools(sessions, backend).register(server)
     ViewTools(sessions, backend).register(server)
     SolutionTools(sessions, backend).register(server)
+    _register_missing_builder_tools(server)
     return server
 
 

package/src/qingflow_mcp/server_app_builder.py

@@ -36,7 +36,7 @@ def build_builder_server() -> FastMCP:
             "Use builder_tool_contract when you need a machine-readable contract, aliases, allowed enums, or a minimal valid example for a public builder tool. "
             "Use solution_install when the user explicitly wants to install a packaged solution/template by solution_key, optionally copying bundled demo data. "
             "Use package_list to find visible app packages by keyword and package_get to read package detail before editing; if creating or updating an app package may be appropriate, use package_apply with explicit user intent; otherwise use app_resolve to locate app resources, "
-            "Use workspace_icon_catalog_get before creating app packages, apps, or portals when supported icon/color candidates are needed; new workspace resources require explicit non-template icon + color, and the CLI validates choices without inferring business defaults. "
+            "Use workspace_icon_catalog_get before creating app packages or portals when supported icon/color candidates are needed; those resources require explicit non-template icon + color. AppForm-created apps derive a stable default icon and color from spec.appName. "
             "app_form_schema plus app_form_get for versioned form work, using being_draft=true only for editing and the published default for relation or record consumers; use app_get as the default non-form app map read, then app_get_fields/app_repair_code_blocks/app_get_layout/app_get_views/app_get_flow/app_get_charts/portal_list/portal_get/view_get/chart_get for focused compatibility or non-form reads, "
             "member_search/role_search/role_create when workflow assignees must come from the directory or role catalog, preferring roles over explicit members unless the user explicitly names members, "
             "then app_form_apply for complete app form targets, explicit app_delete for application deletion, and app_flow_apply/app_views_apply/app_associated_resources_apply/app_charts_apply/portal_apply/portal_delete for non-form patches. app_custom_buttons_apply is maintenance-only for explicit standalone button work outside normal view design. These apply/delete tools perform validation, normalization, writes, and readback verification where applicable. AppForm publishes only after a draft change or when the published form lags behind; views noop requests skip publish, app_custom_buttons_apply and app_associated_resources_apply publish after at least one write succeeds and expose no draft-only parameter, charts are immediate-live without publish and resolve targets by chart_id first then exact unique chart name, portal updates use replace semantics only when sections are supplied and edit-mode base-info-only updates may omit sections, portal delete separates DELETE execution from readback verification, portal pc layout is a 24-column grid and mobile is a 6-column grid so omit position or use layout_preset when unsure, publish=false only guarantees draft/base-info updates for tools that still expose that parameter, and flow should use publish=false whenever you only want draft/precheck behavior. "
@@ -44,7 +44,7 @@ def build_builder_server() -> FastMCP:
             "For existing object parameter replacement, prefer patch_views, patch_buttons, patch_resources, and patch_charts with set/unset; the tool reads current config and full-saves internally, while upsert_* is for creation or full target configuration and should not be used as an incomplete partial update. "
             "For builder delete/remove apply results, separate delete execution from readback verification: after DELETE is sent, resources expose delete_executed, readback_status, and safe_to_retry_delete=false. If readback_status is unavailable or still_exists, do not blindly repeat the delete; confirm later with app_get/view_get/chart_get or the relevant apply readback. Views/buttons use single-item readback; associated resources use one app-level resource-pool readback because there is no confirmed single-item GET. "
             "For builder write/apply results, separate write execution from final readback verification: status=partial_success with write_executed=true and safe_to_retry=false means the write was sent or succeeded, while final readback, publish verification, or metadata confirmation is pending or permission-restricted. Report it as written but unverified; do not repeat the same write blindly. "
-            "For app_form_apply, pin the version from app_form_schema, validate the JSON declaration with the qingflow-app-form Skill command, preserve the complete body and existing IDs from a draft get, and use dataTitle/dataCover on canonical fields; exactly one top-level dataTitle is required for a non-empty body, while dataCover is optional and must be a top-level attachment field. A root appKey means update and may include packageId; no appKey means create and requires packageId plus spec.appName, spec.icon, and spec.color selected from workspace_icon_catalog_get, with template forbidden. "
+            "For app_form_apply, pin the version from app_form_schema, preserve the complete body and existing IDs from a draft get, and configure data display through app-level spec.dataTitleField/spec.dataCoverField selectors rather than booleans on fields; App Builder MCP validates the declaration inside app_form_apply, while the CLI route has a separate static validate command. dataTitleField must resolve to exactly one top-level field for a non-empty body, while dataCoverField is optional and must resolve to a top-level attachment field. A root appKey means update and may include packageId; no appKey means create and requires packageId plus spec.appName. AppForm does not accept spec.icon or spec.color; creation derives a stable default icon and color from spec.appName. "
             "For app_views_apply, keep fixed saved filters in filters and configure the frontend query panel separately with query_conditions; query_conditions.rows is a matrix of field names compiled to backend queryCondition queIds. New views default associated report/view display to visible with limit_type=all; existing views preserve their current associated display unless associated_resources is explicitly patched. View writes use ViewManagementAuth (beingViewManageStatus), falling back to DataManageAuth when advanced app permissions are not enabled. "
             "For ordinary business buttons, declare them on the target view with app_views_apply.views[].action_buttons; app_views_apply writes the view first, then creates/binds the button. Use app_custom_buttons_apply only when the user explicitly asks to maintain existing standalone buttons outside view design, such as custom style/icon changes, cross-view reuse, deleting button bodies, bulk binding reorder, or exact qRobot/wings config. Button body writes require EditAppAuth; view_configs placement writes require ViewManagementAuth, matching the backend viewConfig route. For addData buttons, prefer action_buttons.target_app_key + field_mappings/default_values on the view path; do not ask agents to write raw que_relation unless maintaining a legacy config. field_mappings.source_field accepts source schema fields and supported system fields: 数据ID/row_record_id/apply_id/_id means current record id (-17), 编号/record_number means visible record number (0). To fill a target relation with the current record, map {'source_field': '数据ID', 'target_field': '目标引用字段'}; default_values is only for static constants. View button bindings merge by default; standalone view_configs are only for explicit maintenance. Builder view_key arguments are raw keys from app_get.views[].view_key and must not be prefixed with custom:. "
             "For BI reports, keep report-body development separate from Qingflow in-app display: use app_charts_apply to create, update, remove, or reorder app-source QingBI chart bodies/configs with dataSourceType=qingflow; chart dimension/metric/filter/query fields must come from app_get_fields.chart_fields, not record schema or form-only fields; dataset BI reports are not created or edited by app_charts_apply yet and should be created in QingBI first, then attached with app_associated_resources_apply using report_source=dataset. "

package/src/qingflow_mcp/tools/record_tools.py

@@ -11895,7 +11895,7 @@ class RecordTools(ToolBase):
             raise RecordInputError(
                 message=f"field '{field.que_title}' uses unsupported nested subtable writes",
                 error_code="UNSUPPORTED_WRITE_FORMAT",
-                fix_hint="Nested subtable writes are not supported in app-user tools.",
+                fix_hint="Nested subtable writes are not supported by the public record tools.",
                 details={"location": location, "field": _field_ref_payload(field), "expected_format": _write_format_for_field(field), "received_value": item},
             )
         self._raise_if_verify_unsupported_write_field(field, item, location=location)
@@ -11960,7 +11960,7 @@ class RecordTools(ToolBase):
             raise RecordInputError(
                 message=f"field '{field.que_title}' uses unsupported nested subtable writes",
                 error_code="UNSUPPORTED_WRITE_FORMAT",
-                fix_hint="Nested subtable writes are not supported in app-user tools.",
+                fix_hint="Nested subtable writes are not supported by the public record tools.",
                 details={"location": location, "field": _field_ref_payload(field), "expected_format": _write_format_for_field(field), "received_value": raw_value},
             )
         self._raise_if_verify_unsupported_write_field(field, raw_value, location=location)
@@ -21150,7 +21150,7 @@ def _subtable_cell_ref_payload(
 
 def _unsupported_write_reason(que_type: int | None) -> str:
     if que_type == 14:
-        return "time range fields require a backend-specific native payload shape that app-user tools do not build yet"
+        return "time range fields require a backend-specific native payload shape that public record tools do not build yet"
     if que_type == 34:
         return "image recognition fields are runtime AI fields and direct writes are not reliably persisted"
     if que_type == 35:

package/src/qingflow_mcp/version.py

@@ -57,11 +57,9 @@ def _find_package_root() -> Path | None:
         if version and name in {
             "qingflow-mcp-workspace",
             "@qingflow-tech/qingflow-cli",
-            "@qingflow-tech/qingflow-app-user-mcp",
-            "@qingflow-tech/qingflow-app-builder-mcp",
+            "@qingflow-tech/qingflow-mcp",
             "@josephyan/qingflow-cli",
-            "@josephyan/qingflow-app-user-mcp",
-            "@josephyan/qingflow-app-builder-mcp",
+            "@josephyan/qingflow-mcp",
         }:
             return parent
     return None

package/docs/local-agent-install.md

@@ -1,370 +0,0 @@
-# 本地智能体安装
-
-这个目录下现在有三个本地命令入口：
-
-1. 统一 CLI：`qingflow`
-2. 记录/待办优先的 `qingflow-app-user-mcp`
-3. 精简 builder 的 `qingflow-app-builder-mcp`
-
-## 本地鉴权推荐方案
-
-本地模式现在推荐优先使用 `credential` 建立会话，而不是直接注入 `token`。
-
-推荐链路：
-
-1. createClaw 或其它本地宿主为当前实例保存 `credential`
-2. 本地 MCP 调用 `auth_use_credential`
-3. MCP 用该 `credential` 请求 apaas `/mcp/auth/context`
-4. 解析并保存 `token / wsId / qfVersion / uid`
-5. 业务工具直接使用这份上下文
-
-`auth_use_credential` 是本地唯一鉴权主路径。
-
-补充说明：
-
-- 对 stdio MCP 来说，主路径仍然只有 `auth_use_credential`。
-- 如果你是在终端里直接使用 `qingflow` CLI，可以额外使用 `qingflow auth login` 作为“人类登录”入口；默认会提示轻流邮箱和隐藏密码，拿到 `token` 后建立本地 CLI 会话。
-- 也就是说，这次新增的是 CLI 的登录入口，不是给 MCP 增加第二套会话模型。
-
-## npm 安装器适用场景
-
-适合这类本地 agent / gateway：
-
-- Claude Desktop
-- Cline / Roo / Cursor 这类本地 MCP 客户端
-- OpenClaw 风格的本地 agent 容器或本地 gateway
-- 任何支持 `command + args + env` 的 stdio MCP 客户端
-
-## 前置条件
-
-- Node.js >= 16.16
-- Python >= 3.11
-- 安装过程中可以访问 PyPI
-
-如果机器上没有默认 `python3` / `python`，可以先设置：
-
-```bash
-export QINGFLOW_MCP_PYTHON=/path/to/python3.11
-```
-
-## 安装方式
-
-### 方式 1：在源码目录预热运行环境
-
-```bash
-cd qingflow-support/mcp-server
-npm install
-```
-
-这个模式适合你已经有源码 checkout，只想让当前目录具备本地 agent 可调用的运行时。
-
-### 方式 2：全局安装到当前机器
-
-```bash
-cd qingflow-support/mcp-server
-npm install -g .
-```
-
-### 方式 3：安装到某个本地 agent workspace
-
-```bash
-npm install /absolute/path/to/qingflow-support/mcp-server
-```
-
-### 方式 4：离线分发 tgz 安装包
-
-先在源码目录打包：
-
-```bash
-cd qingflow-support/mcp-server
-npm run pack:npm
-```
-
-会生成：
-
-```bash
-dist/npm/qingflow-tech-qingflow-cli-<version>.tgz
-dist/npm/qingflow-cli-<version>.tgz
-dist/npm/qingflow-tech-qingflow-app-user-mcp-<version>.tgz
-dist/npm/qingflow-tech-qingflow-app-builder-mcp-<version>.tgz
-```
-
-然后在目标机器安装：
-
-```bash
-npx -y -p /absolute/path/to/dist/npm/qingflow-cli-<version>.tgz qingflow-cli install --package /absolute/path/to/dist/npm/qingflow-tech-qingflow-cli-<version>.tgz
-npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-cli-<version>.tgz
-npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-app-user-mcp-<version>.tgz
-npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-app-builder-mcp-<version>.tgz
-```
-
-线上官网入口对应：
-
-```bash
-npx qingflow-cli@latest install
-```
-
-安装器只安装真实 CLI 包 `@qingflow-tech/qingflow-cli`。它会先检查 Node.js、npm 和 Python 3.11+；如果 `npm install -g` 因本机全局目录权限失败，安装器会自动 fallback 到用户目录（macOS/Linux 为 `~/.local`，Windows 为当前用户 AppData npm 目录），但不会修改 shell 配置文件；PATH 缺失时会打印需要执行的 shell / PowerShell 命令。排障可加 `--verbose`；如需禁止 fallback 可加 `--no-fallback`。
-
-安装时会自动：
-
-1. 创建 `.npm-python/`
-2. 在其中建立 Python 虚拟环境
-3. 执行 `pip install .`
-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
-
-## 本地验证
-
-如果你在源码目录执行了 `npm install`，可直接这样启动：
-
-```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，安装对应包后命令通常位于：
-
-```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 安装到某个空目录，命令通常位于：
-
-```bash
-/absolute/path/to/install-dir/node_modules/.bin/qingflow
-/absolute/path/to/install-dir/node_modules/.bin/qingflow-app-user-mcp
-/absolute/path/to/install-dir/node_modules/.bin/qingflow-app-builder-mcp
-```
-
-这是 stdio MCP server，正常情况下不会输出欢迎信息，而是等待客户端连接。
-
-## 客户端配置
-
-### 通用 stdio MCP 客户端
-
-如果你直接使用源码 checkout：
-
-```json
-{
-  "mcpServers": {
-    "qingflow": {
-      "command": "node",
-      "args": [
-        "/absolute/path/to/qingflow-support/mcp-server/npm/bin/qingflow-app-user-mcp.mjs"
-      ],
-      "env": {
-        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
-        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp",
-        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
-        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
-        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
-      }
-    }
-  }
-}
-```
-
-如果你已经全局安装：
-
-```json
-{
-  "mcpServers": {
-    "qingflow": {
-      "command": "qingflow-app-user-mcp",
-      "args": [],
-      "env": {
-        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
-        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp",
-        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
-        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
-        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
-      }
-    }
-  }
-}
-```
-
-如果你把包安装到了某个本地 agent workspace：
-
-```json
-{
-  "mcpServers": {
-    "qingflow": {
-      "command": "/absolute/path/to/agent-workspace/node_modules/.bin/qingflow-app-user-mcp",
-      "args": [],
-      "env": {
-        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
-        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp",
-        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
-        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
-        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
-      }
-    }
-  }
-}
-```
-
-### 使用 npx
-
-如果不做全局安装，也可以直接运行独立包：
-
-```json
-{
-  "mcpServers": {
-    "qingflow-user": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@qingflow-tech/qingflow-app-user-mcp"
-      ],
-      "env": {
-        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
-        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
-        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
-        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
-      }
-    },
-    "qingflow-builder": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@qingflow-tech/qingflow-app-builder-mcp"
-      ],
-      "env": {
-        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
-        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
-        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
-        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
-      }
-    }
-  }
-}
-```
-
-说明：
-- 源码目录 `npm install` 不会把命令加到全局 PATH；这种模式请用 `node ./npm/bin/qingflow.mjs`、`node ./npm/bin/qingflow-app-user-mcp.mjs` 或 `node ./npm/bin/qingflow-app-builder-mcp.mjs`
-- `npx` 方式适合临时安装或容器化本地 agent
-- 全局安装方式更适合长期固定使用的本机开发环境
-- 计费接口使用当前登录会话的 `token` 与 `wsId` 请求头，可通过 `QINGFLOW_MCP_CREDIT_APAAS_BASE_URL/PATH` 覆盖调用记录接口地址
-
-## 排障
-
-如果安装失败，优先检查：
-
-1. `node -v`
-2. `python3 --version`
-3. `pip` 是否能访问 PyPI
-4. 是否设置了错误的 `QINGFLOW_MCP_PYTHON`
-
-如果需要重装 Python 侧运行环境，可以删掉：
-
-```bash
-rm -rf .npm-python
-```
-
-然后重新执行：
-
-```bash
-npm install
-```
-
-如果 MCP 客户端一调用工具就报 `Transport closed`，优先检查这几件事：
-
-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 客户端
-
-现在 stdio MCP 入口会拒绝在启动瞬间“边启动边重建 Python 运行时”，因为安装日志一旦写进 stdout，就会破坏 MCP 握手并表现成 `Transport closed`。如果运行时缺失或版本不一致，入口会直接报错并提示重装，而不是静默自修复。
-
-## createClaw 本地接入示例
-
-如果 createClaw 已经为当前本地实例保存了 `credential`，推荐在首次建链时调用：
-
-```bash
-qingflow auth use-credential \
-  --base-url https://qingflow.com/api \
-  --credential-stdin
-```
-
-然后把 `credential` 写到 stdin。
-
-等价 MCP 工具调用参数：
-
-```json
-{
-  "profile": "default",
-  "base_url": "https://qingflow.com/api",
-  "credential": "1602853_277941",
-  "persist": false
-}
-```
-
-说明：
-
-- 本地会把解析后的 `token` 和原始 `credential` 写入 profile 文件，用于后续 CLI 命令恢复会话
-- `persist=true` 时，本地还会优先把解析后的 `token` 和原始 `credential` 同步写入系统 keychain
-- 当前工作区以 `/mcp/auth/context` 返回的 `wsId` 为准，不再通过本地 MCP 显式切换

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

@@ -1,115 +0,0 @@
----
-name: qingflow-mcp-setup
-description: Install, connect, authenticate, and troubleshoot the Qingflow MCP server in local AI clients such as Claude Desktop or any stdio-compatible MCP client. Use when the user wants to configure the MCP, verify local startup, log in with token/password, select a workspace, or fix connection/authentication issues.
-metadata:
-  short-description: Install and connect the Qingflow MCP locally
----
-
-# Qingflow MCP Setup
-
-> **Skill 版本**：`qingflow-skills-2026.07.01.04`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
-
-## Overview
-
-This skill sets up the local Qingflow MCP server, connects it to a local AI client, and verifies authentication and workspace selection. Use it for installation, client configuration, token login, and connection troubleshooting.
-
-## Workflow
-
-Follow these steps in order.
-
-`feedback_submit` is also available as a cross-cutting helper when setup or MCP capability gaps still block the user after reasonable troubleshooting. It does not require Qingflow login or workspace selection, and should be called only after explicit user confirmation.
-
-Before configuration or live calls, identify the target environment explicitly as `test` or `prod`, then read [references/environments.md](references/environments.md). If the user did not specify one, default to `prod`.
-
-### Step 1: Verify the local project path
-
-Resolve the repository root first. In this repo, the MCP server should live at:
-
-- `<repo_root>/qingflow-support/mcp-server`
-
-Key entrypoint:
-
-- `<repo_root>/qingflow-support/mcp-server/qingflow-mcp`
-
-If the path differs, stop and update all client config snippets before proceeding.
-If the skill is installed under `$CODEX_HOME/skills` instead of the repo-local `.codex/skills`, set `QINGFLOW_MCP_ROOT=<repo_root>/qingflow-support/mcp-server` before running `scripts/check_local_server.sh`.
-
-### Step 2: Install local dependencies
-
-Run:
-
-```bash
-cd <repo_root>/qingflow-support/mcp-server
-python3 -m venv .venv
-./.venv/bin/pip install -e '.[dev]'
-```
-
-Use `scripts/check_local_server.sh` to verify the entrypoint and virtualenv. The script will first try `QINGFLOW_MCP_ROOT`, then the current git repo, then a repo-local `.codex/skills` layout.
-
-### Step 3: Configure the local AI client
-
-For any stdio-compatible MCP client, map these values:
-
-- `command`: `<repo_root>/qingflow-support/mcp-server/qingflow-mcp`
-- `args`: `[]`
-- `env.QINGFLOW_MCP_DEFAULT_BASE_URL`: the target backend URL for the active environment
-- `env.QINGFLOW_MCP_DEFAULT_QF_VERSION`: set this when the environment must route to a specific version such as `canary`
-
-Client-specific snippets:
-
-- Claude Desktop: read [references/claude-desktop.md](references/claude-desktop.md)
-- Generic stdio MCP clients: read [references/generic-stdio.md](references/generic-stdio.md)
-
-When both test and production are in play, keep separate config snippets or clearly labeled `env` blocks so the user can switch without ambiguity.
-
-### Step 4: Validate startup
-
-The server is a stdio MCP process. A direct terminal launch may print nothing and wait for a client. That is normal.
-
-Manual startup command:
-
-```bash
-cd <repo_root>/qingflow-support/mcp-server
-./qingflow-mcp
-```
-
-Prefer validating through the client after config is added.
-
-### Step 5: Use injected session first; authenticate only for setup or recovery
-
-For Wingent Momo runtime conversations, the session normally already carries the credential-derived token, workspace, and route context. Do not run `auth_use_credential`, `auth_login`, `workspace_list`, or `workspace_select` before ordinary business tools. Start with the smallest read-only business call that fits the task; if it succeeds, continue.
-
-For a standalone local MCP client that has no injected session, use this setup order:
-
-1. `auth_use_credential` or `auth_login`
-2. `workspace_list`
-3. `workspace_select`
-4. Run a small read-only business tool
-
-`auth_use_credential` gets the selected workspace from the credential context. If the user needs a different workspace after authentication, use `workspace_list` and then `workspace_select`.
-After auth, prefer one read-only tool call that returns `request_route` so you can confirm the live `base_url` and `qf_version` before proceeding.
-`auth_use_credential` is a tool call, not a custom HTTP header. It exchanges the createClaw credential for a Qingflow token, `wsId`, and when needed `Cookie: qfVersion=...` after the session is established.
-Do not run `workspace_select` on production paths unless the user explicitly asks to switch workspace or a business tool clearly reports that no workspace is selected. If `/user` does not return a version lane, the session now falls back to the workspace `systemVersion`.
-
-### Step 6: Troubleshoot in the right layer
-
-- If the client cannot launch the server, check path, execute permission, and `.venv`
-- If tools return `auth required`, re-run `auth_use_credential` or `auth_login`
-- If tools return `workspace not selected`, call `workspace_list` and `workspace_select`
-- If calls fail after a working session, assume token expiry and re-authenticate
-- If the browser shows data but MCP does not, compare `request_route` against the browser environment and check whether `qf_version` should be `canary`
-
-## Guardrails
-
-- Never write tokens into the skill files
-- In Wingent Momo runtime, trust injected workspace context until a business tool proves otherwise; for standalone clients, confirm workspace with `auth_whoami`, `workspace_select`, or a successful read-only business call.
-- When debugging, distinguish server startup issues from Qingflow auth issues
-- When the user mentions production, restate the exact `base_url`, `qf_version`, and workspace before any live validation
-- If setup is complete but the current MCP capability is still unsupported or the user's need still cannot be satisfied, summarize the gap, ask whether to submit feedback, and call `feedback_submit` only after explicit user confirmation
-
-## Resources
-
-- Environment switching: [references/environments.md](references/environments.md)
-- Claude Desktop config: [references/claude-desktop.md](references/claude-desktop.md)
-- Generic stdio config: [references/generic-stdio.md](references/generic-stdio.md)
-- Local checks: [scripts/check_local_server.sh](scripts/check_local_server.sh)

package/skills/qingflow-mcp-setup/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Qingflow MCP Setup"
-  short_description: "Install and connect the Qingflow MCP locally"
-  default_prompt: "Use $qingflow-mcp-setup to install and connect the Qingflow MCP in a local AI client, and to verify the active base_url, qf_version, auth state, and workspace selection."

package/skills/qingflow-mcp-setup/references/claude-desktop.md

@@ -1,34 +0,0 @@
-# Claude Desktop
-
-Use this when the user wants to install Qingflow MCP in Claude Desktop.
-
-## Config snippet
-
-```json
-{
-  "mcpServers": {
-    "qingflow": {
-      "command": "<ABSOLUTE_PATH_TO_REPO>/qingflow-support/mcp-server/qingflow-mcp",
-      "args": [],
-      "env": {
-        "QINGFLOW_MCP_DEFAULT_BASE_URL": "<QINGFLOW_BASE_URL>"
-      }
-    }
-  }
-}
-```
-
-## Environment examples
-
-- `prod` (default): set `QINGFLOW_MCP_DEFAULT_BASE_URL` to `https://qingflow.com/api`
-- `test`: if needed, set `QINGFLOW_MCP_DEFAULT_BASE_URL` to the explicitly provided non-production backend
-
-Keep separate snippets for `test` and `prod` so switching environments does not require editing values in-place under pressure.
-
-## Notes
-
-- After updating the config, restart Claude Desktop
-- Replace `<ABSOLUTE_PATH_TO_REPO>` with the real checkout path on the current machine
-- If the server path changes, update the `command` field
-- The server is local stdio MCP, so no remote URL is required
-- Do not store Qingflow credentials in Claude Desktop config; pass the createClaw credential through `auth_use_credential` inside the chat, or use `auth_login` when credential exchange is unavailable