@josephyan/qingflow-app-user-mcp 0.2.0-beta.6 → 0.2.0-beta.61

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.6
+npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.61
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.6 qingflow-app-user-mcp
+npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.61 qingflow-app-user-mcp
 ```
 
 Environment:
@@ -20,11 +20,18 @@ Environment:
 
 This package bootstraps a local Python runtime on first install and then starts the `qingflow-app-user-mcp` stdio MCP server.
 
-Bundled skill:
+Bundled skills:
 
 - `skills/qingflow-app-user`
+- `skills/qingflow-record-insert`
+- `skills/qingflow-record-update`
+- `skills/qingflow-record-delete`
+- `skills/qingflow-record-import`
+- `skills/qingflow-task-ops`
+- `skills/qingflow-record-analysis`
 
 Note:
 
 - The skill files are included in the npm package.
 - On install, the package copies them to `$CODEX_HOME/skills` (or `~/.codex/skills` if `CODEX_HOME` is unset).
+- If a stdio MCP client reports `Transport closed`, delete `.npm-python`, reinstall the package, and make sure CLI/user/builder packages are on the same version. The stdio entrypoints refuse runtime bootstrap so install logs never corrupt MCP stdout.

package/docs/local-agent-install.md

@@ -1,9 +1,10 @@
 # 本地智能体安装
 
-这个目录下现在只保留两个本地命令入口：
+这个目录下现在有三个本地命令入口：
 
-1. 记录/待办优先的 `qingflow-app-user-mcp`
-2. 精简 builder 的 `qingflow-app-builder-mcp`
+1. 统一 CLI：`qingflow`
+2. 记录/待办优先的 `qingflow-app-user-mcp`
+3. 精简 builder 的 `qingflow-app-builder-mcp`
 
 ## npm 安装器适用场景
 
@@ -62,6 +63,7 @@ npm run pack:npm
 会生成：
 
 ```bash
+dist/npm/josephyan-qingflow-cli-<version>.tgz
 dist/npm/josephyan-qingflow-app-user-mcp-<version>.tgz
 dist/npm/josephyan-qingflow-app-builder-mcp-<version>.tgz
 ```
@@ -69,6 +71,7 @@ dist/npm/josephyan-qingflow-app-builder-mcp-<version>.tgz
 然后在目标机器安装：
 
 ```bash
+npm install /absolute/path/to/dist/npm/josephyan-qingflow-cli-<version>.tgz
 npm install /absolute/path/to/dist/npm/josephyan-qingflow-app-user-mcp-<version>.tgz
 npm install /absolute/path/to/dist/npm/josephyan-qingflow-app-builder-mcp-<version>.tgz
 ```
@@ -78,7 +81,7 @@ npm install /absolute/path/to/dist/npm/josephyan-qingflow-app-builder-mcp-<versi
 1. 创建 `.npm-python/`
 2. 在其中建立 Python 虚拟环境
 3. 执行 `pip install .`
-4. 在安装位置暴露 `qingflow-app-user-mcp`、`qingflow-app-builder-mcp` 命令
+4. 在安装位置暴露 `qingflow`、`qingflow-app-user-mcp`、`qingflow-app-builder-mcp` 命令
 
 ## 本地验证
 
@@ -86,6 +89,7 @@ npm install /absolute/path/to/dist/npm/josephyan-qingflow-app-builder-mcp-<versi
 
 ```bash
 cd qingflow-support/mcp-server
+node ./npm/bin/qingflow.mjs --help
 node ./npm/bin/qingflow-app-user-mcp.mjs
 node ./npm/bin/qingflow-app-builder-mcp.mjs
 ```
@@ -93,6 +97,7 @@ node ./npm/bin/qingflow-app-builder-mcp.mjs
 如果你是全局安装：
 
 ```bash
+qingflow --help
 qingflow-app-user-mcp
 qingflow-app-builder-mcp
 ```
@@ -100,6 +105,7 @@ qingflow-app-builder-mcp
 如果你是把包安装到了某个本地 agent workspace，命令通常位于：
 
 ```bash
+/absolute/path/to/agent-workspace/node_modules/.bin/qingflow
 /absolute/path/to/agent-workspace/node_modules/.bin/qingflow-app-user-mcp
 /absolute/path/to/agent-workspace/node_modules/.bin/qingflow-app-builder-mcp
 ```
@@ -107,6 +113,7 @@ qingflow-app-builder-mcp
 如果你是从 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
 ```
@@ -202,7 +209,7 @@ qingflow-app-builder-mcp
 ```
 
 说明：
-- 源码目录 `npm install` 不会把命令加到全局 PATH；这种模式请用 `node ./npm/bin/qingflow-app-user-mcp.mjs` 或 `node ./npm/bin/qingflow-app-builder-mcp.mjs`
+- 源码目录 `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
 - 全局安装方式更适合长期固定使用的本机开发环境
 
@@ -226,3 +233,12 @@ rm -rf .npm-python
 ```bash
 npm install
 ```
+
+如果 MCP 客户端一调用工具就报 `Transport closed`，优先检查这几件事：
+
+1. 不要混用不同版本的 `@josephyan/qingflow-cli`、`@josephyan/qingflow-app-user-mcp`、`@josephyan/qingflow-app-builder-mcp`
+2. 删除安装目录下的 `.npm-python`
+3. 重新执行 `npm install` 或重新安装对应 tgz/npm 包
+4. 再启动 MCP 客户端
+
+现在 stdio MCP 入口会拒绝在启动瞬间“边启动边重建 Python 运行时”，因为安装日志一旦写进 stdout，就会破坏 MCP 握手并表现成 `Transport closed`。如果运行时缺失或版本不一致，入口会直接报错并提示重装，而不是静默自修复。

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

@@ -4,4 +4,4 @@ import { getPackageRoot, spawnServer } from "../lib/runtime.mjs";
 
 const packageRoot = getPackageRoot(import.meta.url);
 
-spawnServer(packageRoot, process.argv.slice(2), "qingflow-app-user-mcp");
+spawnServer(packageRoot, process.argv.slice(2), "qingflow-app-user-mcp", { allowRuntimeBootstrap: false });

package/npm/lib/runtime.mjs

@@ -7,14 +7,16 @@ const WINDOWS = process.platform === "win32";
 
 function runChecked(command, args, options = {}) {
   const result = spawnSync(command, args, {
-    stdio: "inherit",
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
     ...options,
   });
   if (result.error) {
     throw result.error;
   }
   if (result.status !== 0) {
-    throw new Error(`Command failed: ${command} ${args.join(" ")}`);
+    const details = [result.stderr, result.stdout].filter((value) => typeof value === "string" && value.trim()).join("\n");
+    throw new Error(details ? `Command failed: ${command} ${args.join(" ")}\n${details}` : `Command failed: ${command} ${args.join(" ")}`);
   }
 }
 
@@ -82,6 +84,105 @@ export function getVenvServerCommand(packageRoot, commandName = "qingflow-mcp")
     : path.join(getVenvDir(packageRoot), "bin", commandName);
 }
 
+function readPackageVersion(packageRoot) {
+  const packageJsonPath = path.join(packageRoot, "package.json");
+  try {
+    const payload = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    return typeof payload.version === "string" && payload.version.trim() ? payload.version.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+function readBootstrapStamp(stampPath) {
+  if (!fs.existsSync(stampPath)) {
+    return { exists: false, version: null };
+  }
+  try {
+    const payload = JSON.parse(fs.readFileSync(stampPath, "utf8"));
+    const version = typeof payload.package_version === "string" && payload.package_version.trim() ? payload.package_version.trim() : null;
+    return { exists: true, version };
+  } catch {
+    return { exists: true, version: null };
+  }
+}
+
+export function inspectPythonEnv(packageRoot, commandName = "qingflow-mcp") {
+  const venvDir = getVenvDir(packageRoot);
+  const serverCommand = getVenvServerCommand(packageRoot, commandName);
+  const stampPath = path.join(venvDir, ".bootstrap.json");
+  const packageVersion = readPackageVersion(packageRoot);
+  const stamp = readBootstrapStamp(stampPath);
+  const problems = [];
+
+  if (!packageVersion) {
+    problems.push("package-version-missing");
+  }
+  if (!fs.existsSync(serverCommand)) {
+    problems.push("server-command-missing");
+  }
+  if (!stamp.exists) {
+    problems.push("bootstrap-stamp-missing");
+  } else if (!stamp.version) {
+    problems.push("bootstrap-stamp-invalid");
+  } else if (packageVersion && stamp.version !== packageVersion) {
+    problems.push("bootstrap-version-mismatch");
+  }
+
+  return {
+    ready: problems.length === 0,
+    packageVersion,
+    stampVersion: stamp.version,
+    stampExists: stamp.exists,
+    stampPath,
+    serverCommand,
+    venvDir,
+    problems,
+  };
+}
+
+function formatRuntimeProblem(runtime, commandName, { allowRuntimeBootstrap = false } = {}) {
+  const problemLines = [];
+  for (const problem of runtime.problems) {
+    switch (problem) {
+      case "package-version-missing":
+        problemLines.push("- package.json is missing a valid version field");
+        break;
+      case "server-command-missing":
+        problemLines.push(`- missing Python entrypoint: ${runtime.serverCommand}`);
+        break;
+      case "bootstrap-stamp-missing":
+        problemLines.push(`- missing bootstrap stamp: ${runtime.stampPath}`);
+        break;
+      case "bootstrap-stamp-invalid":
+        problemLines.push(`- bootstrap stamp is unreadable or invalid: ${runtime.stampPath}`);
+        break;
+      case "bootstrap-version-mismatch":
+        problemLines.push(
+          `- bootstrap version mismatch: package=${runtime.packageVersion ?? "unknown"}, runtime=${runtime.stampVersion ?? "unknown"}`
+        );
+        break;
+      default:
+        problemLines.push(`- ${problem}`);
+        break;
+    }
+  }
+
+  const action = allowRuntimeBootstrap
+    ? "Delete .npm-python and retry, or rerun npm install to rebuild the embedded Python runtime."
+    : "Delete .npm-python and rerun npm install, or reinstall the npm package before starting the MCP server.";
+
+  const bootstrapNote = allowRuntimeBootstrap
+    ? ""
+    : "\nRuntime bootstrap is disabled for stdio MCP entrypoints so install logs can never corrupt the MCP stdout transport.";
+
+  return [
+    `[qingflow-mcp] Python runtime for ${commandName} is not ready.`,
+    ...problemLines,
+    action + bootstrapNote,
+  ].join("\n");
+}
+
 function getVenvPip(packageRoot) {
   return WINDOWS
     ? path.join(getVenvDir(packageRoot), "Scripts", "pip.exe")
@@ -119,12 +220,11 @@ export function findPython() {
 
 export function ensurePythonEnv(packageRoot, { force = false, commandName = "qingflow-mcp" } = {}) {
   const python = findPython();
-  const venvDir = getVenvDir(packageRoot);
+  const runtime = inspectPythonEnv(packageRoot, commandName);
   const venvPython = getVenvPython(packageRoot);
-  const serverCommand = getVenvServerCommand(packageRoot, commandName);
-  const stampPath = path.join(venvDir, ".bootstrap.json");
+  const { packageVersion, serverCommand, stampPath, venvDir, stampVersion } = runtime;
 
-  if (!force && fs.existsSync(serverCommand) && fs.existsSync(stampPath)) {
+  if (!force && fs.existsSync(serverCommand) && fs.existsSync(stampPath) && stampVersion && stampVersion === packageVersion) {
     return serverCommand;
   }
 
@@ -145,6 +245,7 @@ export function ensurePythonEnv(packageRoot, { force = false, commandName = "qin
       {
         installed_at: new Date().toISOString(),
         installer: "npm",
+        package_version: packageVersion,
       },
       null,
       2
@@ -158,17 +259,72 @@ export function ensurePythonEnv(packageRoot, { force = false, commandName = "qin
   return serverCommand;
 }
 
-export function spawnServer(packageRoot, args, commandName = "qingflow-mcp") {
-  const serverCommand = fs.existsSync(getVenvServerCommand(packageRoot, commandName))
-    ? getVenvServerCommand(packageRoot, commandName)
-    : ensurePythonEnv(packageRoot, { commandName });
+function proxyStreams(child) {
+  if (process.stdin.readable && child.stdin) {
+    process.stdin.pipe(child.stdin);
+    child.stdin.on("error", (error) => {
+      if (error.code !== "EPIPE") {
+        console.error(`[qingflow-mcp] Failed to forward stdin: ${error.message}`);
+      }
+    });
+  } else if (child.stdin) {
+    child.stdin.end();
+  }
+
+  if (child.stdout) {
+    child.stdout.pipe(process.stdout);
+  }
+  if (child.stderr) {
+    child.stderr.pipe(process.stderr);
+  }
+}
+
+function forwardSignal(child, signal) {
+  process.on(signal, () => {
+    if (!child.killed) {
+      child.kill(signal);
+    }
+  });
+}
+
+export function spawnServer(packageRoot, args, commandName = "qingflow-mcp", { allowRuntimeBootstrap = false } = {}) {
+  let runtime = inspectPythonEnv(packageRoot, commandName);
+  let serverCommand = runtime.serverCommand;
+
+  if (!runtime.ready) {
+    if (!allowRuntimeBootstrap) {
+      console.error(formatRuntimeProblem(runtime, commandName, { allowRuntimeBootstrap }));
+      process.exit(1);
+      return;
+    }
+
+    try {
+      serverCommand = ensurePythonEnv(packageRoot, { commandName });
+      runtime = inspectPythonEnv(packageRoot, commandName);
+    } catch (error) {
+      console.error(`[qingflow-mcp] Failed to prepare Python runtime for ${commandName}: ${error.message}`);
+      process.exit(1);
+      return;
+    }
+
+    if (!runtime.ready) {
+      console.error(formatRuntimeProblem(runtime, commandName, { allowRuntimeBootstrap }));
+      process.exit(1);
+      return;
+    }
+  }
 
   const child = spawn(serverCommand, args, {
-    stdio: "inherit",
+    stdio: ["pipe", "pipe", "pipe"],
     env: process.env,
+    windowsHide: true,
   });
 
-  child.on("exit", (code, signal) => {
+  proxyStreams(child);
+  forwardSignal(child, "SIGINT");
+  forwardSignal(child, "SIGTERM");
+
+  child.on("close", (code, signal) => {
     if (signal) {
       process.kill(process.pid, signal);
       return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.6",
+  "version": "0.2.0-beta.61",
   "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 = "0.2.0b6"
+version = "0.2.0b61"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"
@@ -26,8 +26,10 @@ dependencies = [
   "mcp>=1.9.4,<2.0.0",
   "httpx>=0.27,<1.0",
   "keyring>=25.5,<26.0",
+  "openpyxl>=3.1,<4.0",
   "pydantic>=2.8,<3.0",
   "pycryptodome>=3.20,<4.0",
+  "python-socketio[client]>=5.11,<6.0",
 ]
 
 [project.optional-dependencies]
@@ -44,6 +46,7 @@ build = [
 [project.scripts]
 qingflow-app-user-mcp = "qingflow_mcp.server_app_user:main"
 qingflow-app-builder-mcp = "qingflow_mcp.server_app_builder:main"
+qingflow = "qingflow_mcp.cli.main:main"
 
 [project.urls]
 Homepage = "https://github.com/qingflow/qingflow-mcp"

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

@@ -1,158 +1,79 @@
 ---
 name: qingflow-app-user
-description: Use Qingflow apps as an operational end user after the MCP is already connected and authenticated. Use when the user wants to create, search, read, update, or delete business records, inspect or manage task-center work, add comments, or perform workflow usage actions inside an existing app. Do not use this skill to design apps, modify schemas, or build a brand new SolutionSpec.
+description: Route Qingflow end-user requests to the right specialized operational skill after the MCP is already connected and authenticated. Use when the task is operational but it is not yet clear whether it is record CRUD or final analysis.
 metadata:
-  short-description: Use Qingflow apps for business data and task operations
+  short-description: Router for Qingflow operational skills
 ---
 
 # Qingflow App User
 
 ## Overview
 
-This skill is for business-user operations inside existing Qingflow apps. It focuses on records, task-center usage, comments, and usage-side workflow actions, not app design or system configuration. If the task is about building or changing app structure, switch to `$qingflow-app-builder`.
-
-Before operating on data, identify whether the task targets `test` or `prod` and read [references/environments.md](references/environments.md). If the user did not specify one, default to `prod`.
-When the task is in `prod`, browser parity matters, or the user says "the page has data but MCP does not", restate the expected `base_url` and `qf_version`, then prefer tools that expose `request_route` so you can confirm the live route before concluding.
-
-## Tool Scope
-
-Primary record and data tools:
-
-- `record_query`
-- `record_query_plan`
-- `record_write_plan`
-- `record_field_resolve`
-- `record_aggregate`
-- `record_create`
-- `record_get`
-- `record_update`
-- `record_delete`
-
-Directory and organization lookup tools when the user is asking about internal members, departments, org structure, ownership, approver candidates, or wants full contact exports:
-
-- `directory_search`
-- `directory_list_internal_users`
-- `directory_list_all_internal_users`
-- `directory_list_internal_departments`
-- `directory_list_all_departments`
-- `directory_list_sub_departments`
-- `directory_list_external_members`
-
-Usage-side collaboration and flow tools when needed:
-
-- `record_comment_*`
-- `task_approve`
-- `task_reject`
-- `task_rollback*`
-- `task_transfer*`
-
-Task-center and inbox tools when the user is asking about pending work, processed work, cc, or workflow workload:
-
-- `task_list`
-- `task_list_grouped`
-- `task_statistics`
-- `task_urge`
-
-Do not use builder-side tools here:
-
-- `app_*`
-- `view_*`
-- `workflow_*`
-- `portal_*`
-- `navigation_*`
-- `package_*`
-- `solution_*`
-
-## Standard Operating Order
-
-1. Ensure auth exists
-2. Ensure workspace is selected
-3. Confirm target app, task scope, and operation type
-4. For org, member, department, approver, or ownership questions, start with `directory_*`
-5. For inbox, pending, processed, cc, or workload questions, start with `task_statistics`, `task_list`, or `task_list_grouped`
-6. When a task query identifies the target record, switch to `record_get` or `record_query` for business data details
-7. For non-trivial record reads, start with `record_query` and use `record_query_plan` first when field ids, filters, or scan scope are uncertain
-8. For non-trivial writes, start with `record_write_plan`, especially when using `fields`
-9. Prefer read-first when changing existing records
-10. Report the affected task ids, record ids, member ids, department ids, or counts after actions
-11. For `prod`, complex forms, attachments, or any unfamiliar schema, prefer `record_create(..., verify_write=true)` or read back immediately after create/update
-
-## Data Rules
-
-- Prefer `record_query` as the default read entry
-- Treat `record_query(list)` as the default wide-table browse and export endpoint; pass explicit `select_columns`, do not expect raw answer arrays there, and let the tool auto-batch columns when the backend per-request field cap is hit
-- Use `request_route` from tool responses to verify the active `base_url` and `qf_version` whenever route mismatches are plausible
-- Use `directory_search` for fuzzy internal lookup across both members and departments
-- Use `directory_list_all_internal_users` when the user explicitly wants a complete internal member list within the current workspace or within a specific department or role
-- Use `directory_list_all_departments` when the user explicitly wants the full department tree or all departments under a root
-- Use `directory_list_internal_departments` for keyword-based department search, not full exports
-- Use `task_statistics` before `task_list` when the user only needs counts
-- Use `task_list_grouped` when worksheet or group buckets matter
-- Use `task_urge` only when the user clearly wants a reminder sent for a pending task
-- Use `record_query_plan` before final statistics or when field selectors are ambiguous
-- For precise record lookup, use `record_get` when `apply_id` is known
-- Use `record_field_resolve` when the user gives field titles and you are not fully sure about the exact schema; do not guess ambiguous fields silently
-- Treat field selectors as schema-first and platform-generic. Prefer exact field titles, then neutral aliases such as `创建时间`, `新增时间`, `负责人`, `部门`, `时间`, or `阶段` only when the tool resolves them clearly. Do not assume CRM shorthand like `销售`, `商机阶段`, `客户全称`, or similar domain shortcuts apply across arbitrary Qingflow apps
-- For updates, inspect current data first unless the user already provided the exact target and patch
-- For deletes, confirm the exact record scope and report the deleted ids
-- When validating business data volume, use `effective_count` over raw backend totals
-- For summary or aggregate conclusions, prefer `strict_full=true`
-- In `prod`, prefer read-first even more strictly and avoid deletes unless the record scope is explicit in the conversation
-- For attachments, first run `file_upload_local`, then pass the returned `attachment_value` into `record_create` or `record_update`; do not try to write local file paths directly into attachment fields
-- For relation fields, first query the target app and resolve the referenced record `apply_id`; do not assume titles, numbers, or business keys can be written directly into a relation field
-- For subtable fields, write a list of row objects keyed by the subfield titles. When updating existing rows, include `rowId` / `row_id` / `__row_id__` only if the source record already exposes it
-- Treat `14/34/35/36` as unsupported direct-write field types in app-user flows:
-  - `14`: time range
-  - `34`: image recognition
-  - `35`: image generation
-  - `36`: document parsing
-- For those unsupported types, stop and explain the limitation instead of inventing payloads
-- Use `record_write_plan` to inspect `write_format.support_level` before non-trivial writes:
-  - `full`: generic scalar/select/date writes are directly supported
-  - `restricted`: member/department/attachment/relation/subtable writes need the documented presteps
-  - `unsupported`: stop and explain the limitation
-- For relation-heavy, attachment, subtable, or production writes, default to `verify_write=true` so field drops are surfaced immediately instead of being reported as success
-
-## Mock and Demo Data
-
-When the user asks for demo data, seed, smoke data, or mock data:
-
-- default to at least `5` records for the relevant entity unless the user asks for fewer
-- keep titles realistic and business-like
-- vary statuses, dates, and categories enough to make views and charts useful
-- if the task is `prod`, do not create mock or smoke data unless the user explicitly asks for it
-
-## Response Interpretation
-
-- low-level list totals from the backend may report `0` while rows are present; prefer `record_query(summary)` or `record_aggregate` for final conclusions
-- `record_query(summary)` and `record_aggregate` expose `completeness`; do not treat partial scans as final conclusions
-- `record_write_plan` is static preflight, not a guarantee that submit will pass runtime linkage or visibility checks
-- `record_create` now returns integer `apply_id`; you can pass that id directly into `record_get`, `record_update`, or `record_delete`
-- `verify_write=true` means the tool read the record back and compared the written fields; if it returns `status=verification_failed` or `ok=false`, do not report the create or update as successful
-- Relation writes are `apply_id`-based; if the user only gives a title, number, or business key, query the target app first and resolve the real record id before writing
-- Task counts and record counts are not interchangeable; a task query reflects task-center workload, not the underlying record total
-- When reporting task results, include the task dimension that was used, such as pending, processed, cc, node, or worksheet
-- Prefer summarizing titles and counts instead of dumping raw answer arrays
-- When records reference other entities, verify references are coherent before reporting success
-- `file_upload_local` may transparently change `effective_upload_kind` and `upload_protocol`; surface those fields when debugging production upload behavior instead of assuming all uploads are direct `PUT`
-
-## Practical Patterns
-
-- Bulk mock data creation: query current data first, run `record_write_plan`, then create missing records
-- Data correction: query, inspect, preflight, update, and re-read
-- Inbox triage: use `task_statistics` first, then `task_list` or `task_list_grouped`, then switch to `record_*` for the underlying record when needed
-- Bottleneck analysis: start with `task_statistics` and `task_list_grouped` before drilling into specific records
-- Workflow collaboration: comment, transfer, or reassign only after identifying the exact record
-- Approval actions: identify the exact record and current node first, then use `task_approve` or `task_reject`; do not guess `nodeId`
-- Demo validation: create at least `5` rows and confirm they are queryable
-- Org export: use `directory_list_all_internal_users` for full member exports and `directory_list_all_departments` for full org-tree exports before mapping owners or departments into record operations
-- Attachment write: upload first, write the returned URL object second, and prefer `verify_write=true`
-- Relation write: query the target app first, capture the referenced record `apply_id`, then write the relation field and verify the readback
-- Production discrepancy triage: compare the response `request_route` with the browser environment before assuming the data query is wrong
+This skill is a lightweight router for operational Qingflow work.
+Assumes MCP is connected, authenticated, and on the correct workspace.
+
+## Default Paths
+
+Route to exactly one of these specialized paths:
+
+1. Record insert  
+   Switch to [$qingflow-record-insert](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-insert/SKILL.md)
+
+2. Record update  
+   Switch to [$qingflow-record-update](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-update/SKILL.md)
+
+3. Record delete  
+   Switch to [$qingflow-record-delete](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-delete/SKILL.md)
+
+4. Record import  
+   Switch to [$qingflow-record-import](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-import/SKILL.md)
+
+5. Task workflow operations  
+   Switch to [$qingflow-task-ops](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-task-ops/SKILL.md)
+
+6. Analysis  
+   Switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
+
+7. MCP connection / auth / workspace selection  
+   Switch to [$qingflow-mcp-setup](/Users/yanqidong/.codex/skills/qingflow-mcp-setup/SKILL.md)
+
+## Routing Rules
+
+- If the user does not know the target `app_key`, discover apps first with `app_list` or `app_search`, then route to the specialized skill
+- If the app is known but the available data range is unclear, call `app_get` first and inspect `accessible_views`
+- If the task is about creating or new record entry, switch to `$qingflow-record-insert`
+- If the task is about editing an existing record directly, switch to `$qingflow-record-update`
+- 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 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
+- 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
+- If the task is about subtable writes, still route to the matching insert/update skill, but shape the payload as parent subtable field -> row array; do not route users toward top-level leaf selectors
+- If the task is insert-focused and readback consistency matters, keep the same route and prefer `record_get / record_list` with `output_profile="normalized"` after the write
+- If the user sounds like an ordinary workflow assignee rather than a system operator, prefer `$qingflow-task-ops` over direct record mutation whenever both paths could fit
+- If the task is about grouped distributions, ratios, rankings, trends, insights, or any final statistical conclusion, switch to `$qingflow-record-analysis`
+- If the MCP is not connected, authenticated, or bound to the right workspace, switch to `$qingflow-mcp-setup`
+
+## Shared Preconditions
+
+- prefer canonical app ids, record ids, task ids, and workflow node ids over guessed names
+- if a field or target is still ambiguous after schema/task lookup, ask the user to confirm from a short candidate list instead of guessing
+- if schema fields include `linkage.sources` or `linkage.affects_fields`, treat those as the preferred high-level explanation of field dependencies instead of trying to infer hidden front-end logic
+- if the task can stay read-only, do not write or act
+- if the task involves a user-uploaded import file, do not modify the file unless the user explicitly authorizes repair or normalization
+- if the task involves record import, call `app_get` first and inspect `data.import_capability` before template download, file repair, or import start
+- if the current MCP capability is unsupported, the workflow is awkward, or the user's need still cannot be satisfied after reasonable use, summarize the gap, ask whether to submit feedback, and call `feedback_submit` only after explicit user confirmation
+
+## Shared Helper
+
+- `feedback_submit` is a cross-cutting helper for product feedback submission
+- It does not require Qingflow login or workspace selection
+- Use it only after the user explicitly confirms they want to submit feedback
 
 ## Resources
 
-- Environment switching: [references/environments.md](references/environments.md)
-- Record operation patterns: [references/record-patterns.md](references/record-patterns.md)
-- Workflow usage actions: [references/workflow-usage.md](references/workflow-usage.md)
-- Data gotchas: [references/data-gotchas.md](references/data-gotchas.md)
+- Record insert: [$qingflow-record-insert](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-insert/SKILL.md)
+- Record update: [$qingflow-record-update](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-update/SKILL.md)
+- Record delete: [$qingflow-record-delete](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-delete/SKILL.md)
+- Record import: [$qingflow-record-import](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-import/SKILL.md)
+- Dedicated analysis workflow: [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)

package/skills/qingflow-app-user/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Qingflow App User"
-  short_description: "Use Qingflow apps for business data and task operations"
-  default_prompt: "Use $qingflow-app-user to query members or departments, inspect workload, and safely create, query, update, validate, approve, reject, or otherwise operate records in an existing Qingflow app, paying attention to request_route, verify_write, nodeId accuracy, and attachment upload flows when needed."
+  short_description: "Route Qingflow operational tasks to insert, update, delete, import, task ops, or analysis"
+  default_prompt: "Use $qingflow-app-user as a router: switch to $qingflow-record-insert for new record entry, $qingflow-record-update for direct edits, $qingflow-record-delete for deletes, $qingflow-record-import for bulk import, $qingflow-task-ops for task-center, comments, directory, and workflow usage actions, and $qingflow-record-analysis for grouped analysis or final statistical conclusions."