@josephyan/qingflow-app-user-mcp 1.1.3 → 1.1.5

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-user-mcp@1.1.3
+npm install @josephyan/qingflow-app-user-mcp@1.1.5
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-user-mcp@1.1.3 qingflow-app-user-mcp
+npx -y -p @josephyan/qingflow-app-user-mcp@1.1.5 qingflow-app-user-mcp
 ```
 
 Environment:
@@ -23,19 +23,19 @@ This package bootstraps a local Python runtime on first install and then starts
 Bundled skills:
 
 - `skills/qingflow-app-user`
+- `skills/qingflow-mcp-setup`
 - `skills/qingflow-record-insert`
 - `skills/qingflow-record-update`
 - `skills/qingflow-record-delete`
 - `skills/qingflow-record-import`
 - `skills/qingflow-task-ops`
 - `skills/qingflow-record-analysis`
-- `skills/qingflow-mcp-setup`
-- `skills/qingflow-app-builder`
-- `skills/qingflow-app-builder-code-integrations`
-- `skills/qingflow-workflow-builder`
 
 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).
+- Installing the npm package does not overwrite agent skills automatically.
+- To mount bundled skills from an installed package, run `qingflow-app-user-mcp-skills install --agent codex --scope user`.
+- For one-shot `npx -p` installs, prefer `--copy` because symlinks would point into the npm execution cache.
+- Use `qingflow-app-user-mcp-skills list` to inspect bundled skills. The installer defaults to symlinks for stable package installs and refuses to overwrite existing skills unless `--force` is provided.
 - 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

@@ -101,7 +101,51 @@ npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-app-builder-mcp-<v
 1. 创建 `.npm-python/`
 2. 在其中建立 Python 虚拟环境
 3. 执行 `pip install .`
-4. 在安装位置暴露 `qingflow`、`qingflow-app-user-mcp`、`qingflow-app-builder-mcp` 命令
+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
 
 ## 本地验证
 
@@ -110,24 +154,31 @@ npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-app-builder-mcp-<v
 ```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，命令通常位于：
+如果你是把包安装到了某个本地 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 安装到某个空目录，命令通常位于：
@@ -217,7 +268,7 @@ qingflow-app-builder-mcp
       "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",
@@ -230,7 +281,7 @@ qingflow-app-builder-mcp
       "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",
@@ -272,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/entry_point.py

@@ -7,7 +7,7 @@ src_path = os.path.abspath(os.path.join(os.path.dirname(__file__), "src"))
 if src_path not in sys.path:
     sys.path.insert(0, src_path)
 
-from qingflow_mcp.server import main
+from qingflow_mcp.server_app_user import main
 
 if __name__ == "__main__":
     main()

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

@@ -1,38 +1,7 @@
 #!/usr/bin/env node
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
 
-const PKG_BY_BIN = {
-  qingflow: "qingflow-cli",
-  "qingflow-app-user-mcp": "qingflow-app-user-mcp",
-  "qingflow-app-builder-mcp": "qingflow-app-builder-mcp",
-};
+import { getPackageRoot, spawnServer } from "../lib/runtime.mjs";
 
-function resolvePackageModule(metaUrl, ...segments) {
-  const scriptPath = fileURLToPath(metaUrl);
-  const scriptDir = path.dirname(scriptPath);
-  // bin files live in <pkg>/npm/bin/, runtime.mjs lives in the sibling <pkg>/npm/lib/,
-  // so step up one level before joining the requested segments.
-  const direct = path.join(scriptDir, "..", ...segments);
-  if (fs.existsSync(direct)) {
-    return pathToFileURL(direct).href;
-  }
-  if (path.basename(scriptDir) === ".bin") {
-    const binName = path.basename(scriptPath);
-    const pkgName = PKG_BY_BIN[binName];
-    if (!pkgName) {
-      throw new Error(`Unknown qingflow command: ${binName}`);
-    }
-    const scope = process.env.QINGFLOW_NPM_SCOPE || "@josephyan";
-    const fromBin = path.join(scriptDir, "..", scope, pkgName, "npm", ...segments);
-    if (fs.existsSync(fromBin)) {
-      return pathToFileURL(fromBin).href;
-    }
-  }
-  throw new Error(`Cannot locate ${segments.join("/")} from ${scriptPath}`);
-}
-
-const { getPackageRoot, spawnServer } = await import(resolvePackageModule(import.meta.url, "lib", "runtime.mjs"));
 const packageRoot = getPackageRoot(import.meta.url);
+
 spawnServer(packageRoot, process.argv.slice(2), "qingflow-app-user-mcp", { allowRuntimeBootstrap: false });

package/npm/bin/qingflow-skills.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { getPackageRoot, runSkillsCli } from "../lib/runtime.mjs";
+
+const packageRoot = getPackageRoot(import.meta.url);
+runSkillsCli(packageRoot, process.argv.slice(2));

package/npm/lib/runtime.mjs

@@ -5,12 +5,6 @@ import { fileURLToPath } from "node:url";
 
 const WINDOWS = process.platform === "win32";
 
-const PKG_BY_BIN = {
-  qingflow: "qingflow-cli",
-  "qingflow-app-user-mcp": "qingflow-app-user-mcp",
-  "qingflow-app-builder-mcp": "qingflow-app-builder-mcp",
-};
-
 function runChecked(command, args, options = {}) {
   const result = spawnSync(command, args, {
     encoding: "utf8",
@@ -34,18 +28,7 @@ function commandWorks(command, args) {
 }
 
 export function getPackageRoot(metaUrl) {
-  const scriptPath = fileURLToPath(metaUrl);
-  const scriptDir = path.dirname(scriptPath);
-  if (path.basename(scriptDir) === ".bin") {
-    const binName = path.basename(scriptPath);
-    const pkgName = PKG_BY_BIN[binName];
-    if (!pkgName) {
-      throw new Error(`Unknown qingflow command: ${binName}`);
-    }
-    const scope = process.env.QINGFLOW_NPM_SCOPE || "@josephyan";
-    return path.join(scriptDir, "..", scope, pkgName);
-  }
-  return path.resolve(scriptDir, "..", "..");
+  return path.resolve(path.dirname(fileURLToPath(metaUrl)), "..", "..");
 }
 
 export function getCodexHome() {
@@ -154,43 +137,6 @@ function writeSkillProvenance(skillsDestRoot, skillName, payload) {
   fs.writeFileSync(path.join(provenanceRoot, `${skillName}.json`), `${JSON.stringify(payload, null, 2)}\n`);
 }
 
-function sleepMs(ms) {
-  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-
-function withSkillInstallLock(skillsDestRoot, callback) {
-  const lockDir = path.join(skillsDestRoot, ".qingflow-skill-install.lock");
-  const startedAt = Date.now();
-  while (true) {
-    try {
-      fs.mkdirSync(lockDir);
-      break;
-    } catch (error) {
-      if (error.code !== "EEXIST") {
-        throw error;
-      }
-      try {
-        const stat = fs.statSync(lockDir);
-        if (Date.now() - stat.mtimeMs > 300_000) {
-          fs.rmSync(lockDir, { recursive: true, force: true });
-          continue;
-        }
-      } catch {
-        continue;
-      }
-      if (Date.now() - startedAt > 30_000) {
-        throw new Error(`Timed out waiting for skill install lock: ${lockDir}`);
-      }
-      sleepMs(100);
-    }
-  }
-  try {
-    return callback();
-  } finally {
-    fs.rmSync(lockDir, { recursive: true, force: true });
-  }
-}
-
 export function installBundledSkills(
   packageRoot,
   {
@@ -234,29 +180,27 @@ export function installBundledSkills(
     mode,
   };
 
-  return withSkillInstallLock(skillsDestRoot, () => {
-    for (const skillName of wanted) {
-      const src = path.join(skillsSrc, skillName);
-      const dest = path.join(skillsDestRoot, skillName);
-      const installResult = installOneSkill(src, dest, { force, mode });
-      result[installResult.status === "conflict" ? "conflicts" : installResult.status].push(skillName);
-      if (installResult.status !== "conflict") {
-        writeSkillProvenance(skillsDestRoot, skillName, {
-          package: packageJson.name ?? null,
-          version: packageJson.version ?? null,
-          skill: skillName,
-          source: src,
-          destination: dest,
-          agent,
-          scope,
-          mode,
-          installed_at: new Date().toISOString(),
-        });
-      }
+  for (const skillName of wanted) {
+    const src = path.join(skillsSrc, skillName);
+    const dest = path.join(skillsDestRoot, skillName);
+    const installResult = installOneSkill(src, dest, { force, mode });
+    result[installResult.status === "conflict" ? "conflicts" : installResult.status].push(skillName);
+    if (installResult.status !== "conflict") {
+      writeSkillProvenance(skillsDestRoot, skillName, {
+        package: packageJson.name ?? null,
+        version: packageJson.version ?? null,
+        skill: skillName,
+        source: src,
+        destination: dest,
+        agent,
+        scope,
+        mode,
+        installed_at: new Date().toISOString(),
+      });
     }
+  }
 
-    return result;
-  });
+  return result;
 }
 
 function parseSkillsCliArgs(args) {
@@ -536,17 +480,6 @@ function getVenvPip(packageRoot) {
     : path.join(getVenvDir(packageRoot), "bin", "pip");
 }
 
-function findOfflineProjectWheel(findLinksDir) {
-  const wheels = fs
-    .readdirSync(findLinksDir)
-    .filter((name) => /^qingflow_mcp-.*\.whl$/i.test(name))
-    .sort();
-  if (wheels.length === 0) {
-    throw new Error(`Offline install expected a qingflow_mcp wheel in ${findLinksDir}`);
-  }
-  return path.join(findLinksDir, wheels[wheels.length - 1]);
-}
-
 export function findPython() {
   const preferred = process.env.QINGFLOW_MCP_PYTHON?.trim();
   const candidates = preferred
@@ -595,20 +528,7 @@ export function ensurePythonEnv(packageRoot, { force = false, commandName = "qin
   }
 
   const pip = getVenvPip(packageRoot);
-  const pipArgs = ["install", "--disable-pip-version-check"];
-  const offlineFindLinks = process.env.QINGFLOW_MCP_PIP_FIND_LINKS?.trim();
-  if (process.env.QINGFLOW_MCP_PIP_NO_INDEX === "1") {
-    pipArgs.push("--no-index");
-  }
-  if (offlineFindLinks) {
-    pipArgs.push("--find-links", offlineFindLinks);
-  }
-  if (process.env.QINGFLOW_MCP_PIP_NO_INDEX === "1" && offlineFindLinks) {
-    pipArgs.push(findOfflineProjectWheel(offlineFindLinks));
-  } else {
-    pipArgs.push(".");
-  }
-  runChecked(pip, pipArgs, { cwd: packageRoot });
+  runChecked(pip, ["install", "--disable-pip-version-check", "."], { cwd: packageRoot });
 
   fs.writeFileSync(
     stampPath,

package/npm/scripts/postinstall.mjs

@@ -1,4 +1,4 @@
-import { ensurePythonEnv, getPackageRoot, installBundledSkills } from "../lib/runtime.mjs";
+import { ensurePythonEnv, getPackageRoot } from "../lib/runtime.mjs";
 
 const packageRoot = getPackageRoot(import.meta.url);
 
@@ -6,15 +6,6 @@ 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, { force: true });
-  if (!skills.skipped) {
-    const changed = [
-      skills.installed.length ? `installed=${skills.installed.join(",")}` : "",
-      skills.unchanged.length ? `unchanged=${skills.unchanged.join(",")}` : "",
-      skills.conflicts.length ? `conflicts=${skills.conflicts.join(",")}` : "",
-    ].filter(Boolean).join(" ");
-    console.log(`[qingflow-mcp] Installed skills to ${skills.destination}: ${changed || "none"}`);
-  }
 } catch (error) {
   console.error(`[qingflow-mcp] postinstall failed: ${error.message}`);
   process.exit(1);

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "qingflow-app-user-mcp": "./npm/bin/qingflow-app-user-mcp.mjs"
+    "qingflow-app-user-mcp": "./npm/bin/qingflow-app-user-mcp.mjs",
+    "qingflow-app-user-mcp-skills": "./npm/bin/qingflow-skills.mjs"
   },
   "scripts": {
     "postinstall": "node ./npm/scripts/postinstall.mjs"

package/pyproject.toml

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

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

@@ -1,64 +1,67 @@
 ---
 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.
+description: Route Qingflow end-user requests to the right specialized operational skill using the current Wingent Momo runtime MCP session. 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
 
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 ## Overview
 
 This skill is a lightweight router for operational Qingflow work.
-Assumes MCP is connected, authenticated, and on the correct workspace.
+In Wingent Momo runtime, trust injected MCP credentials, workspace, and route context until a business tool explicitly reports otherwise.
 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  
+1. Record insert
    Switch to [$qingflow-record-insert](../qingflow-record-insert/SKILL.md)
 
-2. Record update  
+2. Record update
    Switch to [$qingflow-record-update](../qingflow-record-update/SKILL.md)
 
-3. Record delete  
+3. Record delete
    Switch to [$qingflow-record-delete](../qingflow-record-delete/SKILL.md)
 
-4. Record import  
+4. Record import
    Switch to [$qingflow-record-import](../qingflow-record-import/SKILL.md)
 
-5. Task workflow operations  
+5. Task workflow operations
    Switch to [$qingflow-task-ops](../qingflow-task-ops/SKILL.md)
 
-6. Analysis  
+6. Analysis
    Switch to [$qingflow-record-analysis](../qingflow-record-analysis/SKILL.md)
 
-7. MCP connection / auth / workspace selection  
+7. Standalone MCP setup or explicit auth/workspace recovery
    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
 
-- 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 user does not know the target `app_key`, discover apps first with `app_list` / `app list --query` over current-user visible apps, then route to the specialized skill; do not use the legacy app search path for ordinary members
 - 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 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
 - 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/detail context matters, keep the same route and prefer the single-record detail readback after the write; use normalized list readback only when batch row shape is needed
 - 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`
+- In Wingent Momo runtime, do not route to `$qingflow-mcp-setup` as a preflight. Switch there only when a business tool explicitly reports missing auth, invalid session, or wrong/missing workspace, or when the user asks to configure a standalone MCP client.
 
 ## Shared Preconditions
 
@@ -86,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-app-user/references/data-gotchas.md

@@ -9,12 +9,12 @@ For final statistics, grouped distributions, rankings, trends, or insight-style
 - `record_get` is for one exact record and downloads readable detail-page images into `media_assets.items[].local_path` plus attachments/documents/tables into `file_assets.items[].local_path`
 - Use `record_browse_schema_get` when field titles are uncertain instead of guessing ids
 - Do not present paged browse output as if it were a grouped or full-population conclusion
-- Use `record_export_direct` only when the user explicitly asks for export/download/Excel output
+- Use `record_export_direct` only when the user explicitly asks for export/download/Excel output, and always pass an explicit `view_id` from `app_get.accessible_views` or the frontend URL
 
 ## Direct Writes
 
 - `record_insert` is schema-first through `record_insert_schema_get`; default to `items=[{"fields": {...}}]`
-- `record_update` is schema-first through `record_update_schema_get`
+- `record_update` is detail-first: read `record_get`, compose the requested title-keyed `fields` map, then write directly; use `record_update_schema_get` only after update failure or ambiguity
 - `record_delete` does not need a schema-get step
 - For batch insert, `partial_success` means some rows were created; use `created_record_ids`, failed `row_number`, and `failed_fields` to repair only failed rows
 - If a direct-write tool returns `write_executed=false`, the write was blocked and not executed for that item

package/skills/qingflow-app-user/references/public-surface-sync.md

@@ -1,6 +1,6 @@
 # Qingflow Core Public Surface Sync
 
-Use this file as the maintenance baseline for the core Qingflow skills.  
+Use this file as the maintenance baseline for the core Qingflow skills.
 It is not a user-facing product spec. It exists to prevent skill drift.
 
 ## Current Public Defaults
@@ -12,9 +12,9 @@ It is not a user-facing product spec. It exists to prevent skill drift.
 - Standard flows:
   - analyze: `app_get -> record_browse_schema_get -> record_access -> Python`
   - browse detail: `app_get -> record_browse_schema_get -> record_list / record_get`
-  - explicit export/download/Excel: `view_get -> record_export_*` or `record_export_direct`
+  - explicit export/download/Excel: `app_get -> choose view_id -> view_get -> record_export_*` or `record_export_direct`; export tools require explicit `view_id`
   - insert: `record_insert_schema_get -> record_insert(items)`
-  - update: `record_update_schema_get -> record_update`
+  - update: `record_get -> record_update`; use `record_update_schema_get` only for failure diagnosis or ambiguous writable-field routing
 
 ### Tasks
 

package/skills/qingflow-app-user/references/record-patterns.md

@@ -41,13 +41,13 @@ Use `record_insert_schema_get -> record_insert(items)`.
 
 ## Update Pattern
 
-Use `record_update_schema_get -> record_update`.
+Use `record_get -> record_update`.
 
 1. Confirm the target app and `record_id`
-2. Read `writable_fields` and `payload_template`
-3. Update only fields present in `writable_fields`
-4. Let MCP auto-select the first matched accessible view that can execute the payload
-5. Run `record_update`
+2. Read `record_get` in the same view/context the user is using when a `view_id` is known
+3. Build a field-title keyed `fields` map from `record_get.fields[]` and the user's requested changes
+4. Run `record_update` directly; let MCP auto-select the executable update route
+5. If `record_update` fails because fields/routes are ambiguous or unavailable, then use `record_update_schema_get` as a diagnostic tool
 
 ## Delete Pattern
 

package/skills/qingflow-app-user/references/workflow-usage.md

@@ -14,13 +14,12 @@ Examples:
 
 Rules:
 
-- if the user starts from inbox, todo, workload, cc, or bottleneck language, use `task_*` first
-- use `task_summary` for headline counts
-- use `task_list` for flat browsing
-- use `task_facets` when worksheet or workflow-node buckets matter
+- if the user starts from inbox, todo, workload, cc, or bottleneck language, use the public task tools first
+- use `task_list` for headline counts and flat browsing; group locally by app or workflow node when buckets matter
+- use `task_get`, `task_workflow_log_get`, and `task_associated_report_detail_get` only after locating the exact task
 - treat task counts as task-center counts, not record counts
 - switch to `record_*` only after locating the exact business record behind a task
 - identify the exact target first
-- for approve or reject, identify the exact `workflow_node_id` first; prefer task-center results or current audit info, then use `task_approve` or `task_reject`
+- for approve or reject, identify the exact target first; prefer `task_id` from task-center results, then use `task_action_execute` with action `approve` or `reject`
 - avoid usage-side workflow actions on ambiguous records
 - summarize the final action and target task ids or record ids

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

@@ -7,6 +7,8 @@ metadata:
 
 # Qingflow MCP Setup
 
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 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.
@@ -73,24 +75,26 @@ cd <repo_root>/qingflow-support/mcp-server
 
 Prefer validating through the client after config is added.
 
-### Step 5: Authenticate and select workspace
+### 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.
 
-Recommended order inside the client:
+For a standalone local MCP client that has no injected session, use this setup order:
 
-1. `auth_use_token` or `auth_login`
+1. `auth_use_credential` or `auth_login`
 2. `workspace_list`
 3. `workspace_select`
-4. Only then use business tools
+4. Run a small read-only business tool
 
-If the user already knows the target workspace, prefer `auth_use_token(..., ws_id=<id>)`.
+`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_token` is a tool call, not a custom HTTP header. The runtime injects `token`, `wsId`, and when needed `Cookie: qfVersion=...` after the session is established.
-Do not skip `workspace_select` on production paths. If `/user` does not return a version lane, the session now falls back to the workspace `systemVersion`.
+`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_token` or `auth_login`
+- 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`
@@ -98,7 +102,7 @@ Do not skip `workspace_select` on production paths. If `/user` does not return a
 ## Guardrails
 
 - Never write tokens into the skill files
-- Never assume a workspace is selected until `auth_whoami` or `workspace_select` confirms it
+- 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