@josephyan/qingflow-app-user-mcp 0.2.0-beta.1 → 0.2.0-beta.1000

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.1
+npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.1000
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.1 qingflow-app-user-mcp
+npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.1000 qingflow-app-user-mcp
 ```
 
 Environment:
@@ -19,3 +19,19 @@ Environment:
 - `QINGFLOW_MCP_HOME`
 
 This package bootstraps a local Python runtime on first install and then starts the `qingflow-app-user-mcp` stdio MCP server.
+
+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,30 @@
 # 本地智能体安装
 
-这个目录下现在只保留两个本地命令入口：
+这个目录下现在有三个本地命令入口：
 
-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`
+
+## 本地鉴权推荐方案
+
+本地模式现在推荐优先使用 `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 安装器适用场景
 
@@ -62,15 +83,17 @@ npm run pack:npm
 会生成：
 
 ```bash
-dist/npm/josephyan-qingflow-app-user-mcp-<version>.tgz
-dist/npm/josephyan-qingflow-app-builder-mcp-<version>.tgz
+dist/npm/qingflow-tech-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
-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
+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
 ```
 
 安装时会自动：
@@ -78,7 +101,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 +109,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 +117,7 @@ node ./npm/bin/qingflow-app-builder-mcp.mjs
 如果你是全局安装：
 
 ```bash
+qingflow --help
 qingflow-app-user-mcp
 qingflow-app-builder-mcp
 ```
@@ -100,6 +125,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 +133,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
 ```
@@ -129,7 +156,10 @@ qingflow-app-builder-mcp
       ],
       "env": {
         "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
-        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp"
+        "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"
       }
     }
   }
@@ -146,7 +176,10 @@ qingflow-app-builder-mcp
       "args": [],
       "env": {
         "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
-        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp"
+        "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"
       }
     }
   }
@@ -163,7 +196,10 @@ qingflow-app-builder-mcp
       "args": [],
       "env": {
         "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
-        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp"
+        "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"
       }
     }
   }
@@ -184,7 +220,10 @@ qingflow-app-builder-mcp
         "@josephyan/qingflow-app-user-mcp"
       ],
       "env": {
-        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api"
+        "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": {
@@ -194,7 +233,10 @@ qingflow-app-builder-mcp
         "@josephyan/qingflow-app-builder-mcp"
       ],
       "env": {
-        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api"
+        "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"
       }
     }
   }
@@ -202,9 +244,10 @@ 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
 - 全局安装方式更适合长期固定使用的本机开发环境
+- 计费接口使用当前登录会话的 `token` 与 `wsId` 请求头，可通过 `QINGFLOW_MCP_CREDIT_APAAS_BASE_URL/PATH` 覆盖调用记录接口地址
 
 ## 排障
 
@@ -226,3 +269,41 @@ 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`。如果运行时缺失或版本不一致，入口会直接报错并提示重装，而不是静默自修复。
+
+## 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/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(" ")}`);
   }
 }
 
@@ -29,6 +31,43 @@ export function getPackageRoot(metaUrl) {
   return path.resolve(path.dirname(fileURLToPath(metaUrl)), "..", "..");
 }
 
+export function getCodexHome() {
+  const configured = process.env.CODEX_HOME?.trim();
+  if (configured) {
+    return path.resolve(configured);
+  }
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (!home) {
+    throw new Error("Cannot resolve CODEX_HOME because HOME is not set.");
+  }
+  return path.join(home, ".codex");
+}
+
+export function installBundledSkills(packageRoot) {
+  const skillsSrc = path.join(packageRoot, "skills");
+  if (!fs.existsSync(skillsSrc)) {
+    return { installed: [], skipped: true, destination: null };
+  }
+
+  const codexHome = getCodexHome();
+  const skillsDestRoot = path.join(codexHome, "skills");
+  fs.mkdirSync(skillsDestRoot, { recursive: true });
+
+  const installed = [];
+  for (const entry of fs.readdirSync(skillsSrc, { withFileTypes: true })) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const src = path.join(skillsSrc, entry.name);
+    const dest = path.join(skillsDestRoot, entry.name);
+    fs.rmSync(dest, { recursive: true, force: true });
+    fs.cpSync(src, dest, { recursive: true });
+    installed.push(entry.name);
+  }
+
+  return { installed, skipped: false, destination: skillsDestRoot };
+}
+
 export function getVenvDir(packageRoot) {
   return path.join(packageRoot, ".npm-python");
 }
@@ -45,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")
@@ -82,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;
   }
 
@@ -108,6 +245,7 @@ export function ensurePythonEnv(packageRoot, { force = false, commandName = "qin
       {
         installed_at: new Date().toISOString(),
         installer: "npm",
+        package_version: packageVersion,
       },
       null,
       2
@@ -121,17 +259,79 @@ 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, stdio = "proxy" } = {},
+) {
+  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: stdio === "inherit" ? "inherit" : ["pipe", "pipe", "pipe"],
     env: process.env,
+    windowsHide: true,
   });
 
-  child.on("exit", (code, signal) => {
+  if (stdio !== "inherit") {
+    proxyStreams(child);
+  }
+  forwardSignal(child, "SIGINT");
+  forwardSignal(child, "SIGTERM");
+
+  child.on("close", (code, signal) => {
     if (signal) {
       process.kill(process.pid, signal);
       return;

package/npm/scripts/postinstall.mjs

@@ -1,4 +1,4 @@
-import { ensurePythonEnv, getPackageRoot } from "../lib/runtime.mjs";
+import { ensurePythonEnv, getPackageRoot, installBundledSkills } from "../lib/runtime.mjs";
 
 const packageRoot = getPackageRoot(import.meta.url);
 
@@ -6,6 +6,10 @@ try {
   console.log("[qingflow-mcp] Bootstrapping Python runtime...");
   ensurePythonEnv(packageRoot, { commandName: "qingflow-app-user-mcp" });
   console.log("[qingflow-mcp] Python runtime is ready.");
+  const skills = installBundledSkills(packageRoot);
+  if (!skills.skipped) {
+    console.log(`[qingflow-mcp] Installed skills to ${skills.destination}: ${skills.installed.join(", ")}`);
+  }
 } catch (error) {
   console.error(`[qingflow-mcp] postinstall failed: ${error.message}`);
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0-beta.1000",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
   "license": "MIT",
   "type": "module",
@@ -18,7 +18,8 @@
     "src/qingflow_mcp/py.typed",
     "qingflow-app-user-mcp",
     "npm/",
-    "docs/local-agent-install.md"
+    "docs/local-agent-install.md",
+    "skills/"
   ],
   "engines": {
     "node": ">=16.16.0"

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "0.2.0b1"
+version = "0.2.0b1000"
 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

@@ -0,0 +1,88 @@
+---
+name: qingflow-app-user
+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: Router for Qingflow operational skills
+---
+
+# Qingflow App User
+
+## Overview
+
+This skill is a lightweight router for operational Qingflow work.
+Assumes MCP is connected, authenticated, and on the correct workspace.
+Before routing, skim the shared maintenance baseline: [public-surface-sync.md](references/public-surface-sync.md).
+
+## Default Paths
+
+Route to exactly one of these specialized paths:
+
+1. Record insert  
+   Switch to [$qingflow-record-insert](../qingflow-record-insert/SKILL.md)
+
+2. Record update  
+   Switch to [$qingflow-record-update](../qingflow-record-update/SKILL.md)
+
+3. Record delete  
+   Switch to [$qingflow-record-delete](../qingflow-record-delete/SKILL.md)
+
+4. Record import  
+   Switch to [$qingflow-record-import](../qingflow-record-import/SKILL.md)
+
+5. Task workflow operations  
+   Switch to [$qingflow-task-ops](../qingflow-task-ops/SKILL.md)
+
+6. Analysis  
+   Switch to [$qingflow-record-analysis](../qingflow-record-analysis/SKILL.md)
+
+7. MCP connection / auth / workspace selection  
+   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)
+
+## 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 is about package, app, field, layout, workflow, view, chart, portal, visibility, icon, or app base configuration, switch to `$qingflow-app-builder`
+- 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 task discovery by natural language query, still route to `$qingflow-task-ops`; `task_list --query` now uses backend search first and only falls back to local matching when backend returns zero rows
+- 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
+
+- Shared public-surface baseline: [public-surface-sync.md](references/public-surface-sync.md)
+- Record insert: [$qingflow-record-insert](../qingflow-record-insert/SKILL.md)
+- Record update: [$qingflow-record-update](../qingflow-record-update/SKILL.md)
+- Record delete: [$qingflow-record-delete](../qingflow-record-delete/SKILL.md)
+- 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)