@qingflow-tech/qingflow-app-user-mcp 1.0.11 → 1.0.12

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @qingflow-tech/qingflow-app-user-mcp@1.0.11
+npm install @qingflow-tech/qingflow-app-user-mcp@1.0.12
 ```
 
 Run:
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-app-user-mcp@1.0.11 qingflow-app-user-mcp
+npx -y -p @qingflow-tech/qingflow-app-user-mcp@1.0.12 qingflow-app-user-mcp
 ```
 
 Environment:
@@ -23,6 +23,9 @@ 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-app-builder`
+- `skills/qingflow-app-builder-code-integrations`
 - `skills/qingflow-record-insert`
 - `skills/qingflow-record-update`
 - `skills/qingflow-record-delete`
@@ -33,5 +36,8 @@ Bundled skills:
 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 @josephyan/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 安装到某个空目录，命令通常位于：

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-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

@@ -43,29 +43,320 @@ export function getCodexHome() {
   return path.join(home, ".codex");
 }
 
-export function installBundledSkills(packageRoot) {
+function getHomeDir() {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (!home) {
+    throw new Error("Cannot resolve user home because HOME is not set.");
+  }
+  return home;
+}
+
+function getAgentSkillDest(agent, scope, cwd = process.cwd()) {
+  const normalizedAgent = agent.trim().toLowerCase();
+  const normalizedScope = scope.trim().toLowerCase();
+  const home = getHomeDir();
+  if (!["user", "project"].includes(normalizedScope)) {
+    throw new Error(`Unsupported skills scope '${scope}'. Expected 'user' or 'project'.`);
+  }
+
+  const projectRoots = {
+    codex: [cwd, ".codex", "skills"],
+    claude: [cwd, ".claude", "skills"],
+    "claude-code": [cwd, ".claude", "skills"],
+    cursor: [cwd, ".cursor", "skills"],
+    generic: [cwd, ".agents", "skills"],
+  };
+  const userRoots = {
+    codex: [process.env.CODEX_HOME?.trim() || path.join(home, ".codex"), "skills"],
+    claude: [home, ".claude", "skills"],
+    "claude-code": [home, ".claude", "skills"],
+    cursor: [home, ".cursor", "skills"],
+    generic: [home, ".agents", "skills"],
+  };
+
+  const roots = normalizedScope === "project" ? projectRoots : userRoots;
+  const parts = roots[normalizedAgent];
+  if (!parts) {
+    throw new Error(`Unsupported skills agent '${agent}'. Expected one of: codex, claude, claude-code, cursor, generic.`);
+  }
+  return path.resolve(...parts);
+}
+
+export function listBundledSkills(packageRoot) {
   const skillsSrc = path.join(packageRoot, "skills");
   if (!fs.existsSync(skillsSrc)) {
-    return { installed: [], skipped: true, destination: null };
+    return [];
   }
 
-  const codexHome = getCodexHome();
-  const skillsDestRoot = path.join(codexHome, "skills");
-  fs.mkdirSync(skillsDestRoot, { recursive: true });
+  return fs
+    .readdirSync(skillsSrc, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(skillsSrc, entry.name, "SKILL.md")))
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function sameRealPath(a, b) {
+  try {
+    return fs.realpathSync(a) === fs.realpathSync(b);
+  } catch {
+    return false;
+  }
+}
 
-  const installed = [];
-  for (const entry of fs.readdirSync(skillsSrc, { withFileTypes: true })) {
-    if (!entry.isDirectory()) {
-      continue;
+function installOneSkill(src, dest, { force, mode }) {
+  let existingStat = null;
+  try {
+    existingStat = fs.lstatSync(dest);
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+  if (existingStat) {
+    if (existingStat.isSymbolicLink() && sameRealPath(dest, src)) {
+      return { status: "unchanged" };
+    }
+    if (!force) {
+      return { status: "conflict" };
     }
-    const src = path.join(skillsSrc, entry.name);
-    const dest = path.join(skillsDestRoot, entry.name);
     fs.rmSync(dest, { recursive: true, force: true });
+  }
+
+  if (mode === "copy") {
     fs.cpSync(src, dest, { recursive: true });
-    installed.push(entry.name);
+    return { status: "installed" };
+  }
+
+  fs.symlinkSync(src, dest, "dir");
+  return { status: "installed" };
+}
+
+function writeSkillProvenance(skillsDestRoot, skillName, payload) {
+  const provenanceRoot = path.join(skillsDestRoot, ".qingflow-skill-sources");
+  fs.mkdirSync(provenanceRoot, { recursive: true });
+  fs.writeFileSync(path.join(provenanceRoot, `${skillName}.json`), `${JSON.stringify(payload, null, 2)}\n`);
+}
+
+export function installBundledSkills(
+  packageRoot,
+  {
+    agent = "codex",
+    scope = "user",
+    mode = "symlink",
+    force = false,
+    skills = [],
+    cwd = process.cwd(),
+  } = {},
+) {
+  const skillsSrc = path.join(packageRoot, "skills");
+  if (!fs.existsSync(skillsSrc)) {
+    return { installed: [], unchanged: [], conflicts: [], skipped: true, destination: null };
   }
 
-  return { installed, skipped: false, destination: skillsDestRoot };
+  const validModes = new Set(["symlink", "copy"]);
+  if (!validModes.has(mode)) {
+    throw new Error(`Unsupported skills install mode '${mode}'. Expected 'symlink' or 'copy'.`);
+  }
+
+  const available = listBundledSkills(packageRoot);
+  const wanted = skills.length ? skills : available;
+  const unknown = wanted.filter((skillName) => !available.includes(skillName));
+  if (unknown.length) {
+    throw new Error(`Unknown bundled skill(s): ${unknown.join(", ")}. Available: ${available.join(", ")}`);
+  }
+
+  const skillsDestRoot = getAgentSkillDest(agent, scope, cwd);
+  fs.mkdirSync(skillsDestRoot, { recursive: true });
+
+  const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+  const result = {
+    installed: [],
+    unchanged: [],
+    conflicts: [],
+    skipped: false,
+    destination: skillsDestRoot,
+    agent,
+    scope,
+    mode,
+  };
+
+  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;
+}
+
+function parseSkillsCliArgs(args) {
+  const parsed = {
+    command: "help",
+    agent: "codex",
+    scope: "user",
+    mode: "symlink",
+    force: false,
+    json: false,
+    skills: [],
+  };
+  const rest = [...args];
+  if (rest.length && !rest[0].startsWith("-")) {
+    parsed.command = rest.shift();
+  }
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+    const next = () => {
+      index += 1;
+      if (index >= rest.length) {
+        throw new Error(`Missing value for ${arg}`);
+      }
+      return rest[index];
+    };
+    switch (arg) {
+      case "--agent":
+      case "-a":
+        parsed.agent = next();
+        break;
+      case "--scope":
+      case "-s":
+        parsed.scope = next();
+        break;
+      case "--mode":
+      case "-m":
+        parsed.mode = next();
+        break;
+      case "--skill":
+        parsed.skills.push(next());
+        break;
+      case "--all":
+        parsed.agent = "all";
+        break;
+      case "--force":
+      case "-f":
+        parsed.force = true;
+        break;
+      case "--copy":
+        parsed.mode = "copy";
+        break;
+      case "--json":
+        parsed.json = true;
+        break;
+      case "--help":
+      case "-h":
+        parsed.command = "help";
+        break;
+      default:
+        if (arg.startsWith("-")) {
+          throw new Error(`Unknown option ${arg}`);
+        }
+        parsed.skills.push(arg);
+        break;
+    }
+  }
+  return parsed;
+}
+
+function printSkillsHelp() {
+  console.log(`Qingflow bundled skills
+
+Usage:
+  qingflow-skills list [--json]
+  qingflow-skills install [--agent codex|claude|claude-code|cursor|generic|all] [--scope user|project] [--mode symlink|copy] [--skill name] [--force] [--json]
+
+Examples:
+  qingflow-skills list
+  qingflow-skills install --agent codex --scope user
+  qingflow-skills install --agent claude-code --scope project --copy
+  qingflow-skills install --agent all --scope project
+
+Defaults:
+  --agent codex
+  --scope user
+  --mode symlink
+
+Existing skills are not overwritten unless --force is provided.`);
+}
+
+function printInstallSummary(result) {
+  console.log(`[qingflow-skills] destination: ${result.destination}`);
+  if (result.installed.length) {
+    console.log(`[qingflow-skills] installed: ${result.installed.join(", ")}`);
+  }
+  if (result.unchanged.length) {
+    console.log(`[qingflow-skills] unchanged: ${result.unchanged.join(", ")}`);
+  }
+  if (result.conflicts.length) {
+    console.log(`[qingflow-skills] conflicts: ${result.conflicts.join(", ")}`);
+    console.log("[qingflow-skills] Re-run with --force to replace conflicting skills.");
+  }
+}
+
+export function runSkillsCli(packageRoot, args) {
+  let parsed;
+  try {
+    parsed = parseSkillsCliArgs(args);
+    if (parsed.command === "help") {
+      printSkillsHelp();
+      return;
+    }
+    if (parsed.command === "list") {
+      const skills = listBundledSkills(packageRoot);
+      if (parsed.json) {
+        console.log(JSON.stringify({ skills }, null, 2));
+      } else {
+        for (const skill of skills) {
+          console.log(skill);
+        }
+      }
+      return;
+    }
+    if (parsed.command !== "install") {
+      throw new Error(`Unknown qingflow skills command '${parsed.command}'.`);
+    }
+
+    const agents = parsed.agent === "all" ? ["codex", "claude-code", "cursor", "generic"] : [parsed.agent];
+    const results = agents.map((agent) =>
+      installBundledSkills(packageRoot, {
+        agent,
+        scope: parsed.scope,
+        mode: parsed.mode,
+        force: parsed.force,
+        skills: parsed.skills,
+      }),
+    );
+    if (parsed.json) {
+      console.log(JSON.stringify({ results }, null, 2));
+    } else {
+      for (const result of results) {
+        printInstallSummary(result);
+      }
+    }
+    if (results.some((result) => result.conflicts.length)) {
+      process.exit(2);
+    }
+  } catch (error) {
+    if (parsed?.json) {
+      console.error(JSON.stringify({ error: error.message }, null, 2));
+    } else {
+      console.error(`[qingflow-skills] ${error.message}`);
+      console.error("Run 'qingflow-skills --help' for usage.");
+    }
+    process.exit(1);
+  }
 }
 
 export function getVenvDir(packageRoot) {

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,10 +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);
-  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,11 +1,12 @@
 {
   "name": "@qingflow-tech/qingflow-app-user-mcp",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "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.0.11"
+version = "1.0.12"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"