@luckychen1993/pm-mcp 0.1.5 → 0.3.0

package/dist/setup-project.js

@@ -0,0 +1,146 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { atomicWrite } from "./store.js";
+import { PACKAGE_SPEC, SERVER_NAME } from "./version.js";
+export function canonicalProjectRoot(root) {
+    const absolute = path.resolve(root);
+    let real;
+    try {
+        real = fs.realpathSync.native(absolute);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        real = absolute;
+    }
+    return process.platform === "win32" ? real.toLowerCase() : real;
+}
+export function codexProjectServerKey(root) {
+    const canonical = canonicalProjectRoot(root);
+    const slug = path.basename(canonical).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "project";
+    return `${SERVER_NAME}-${slug}-${createHash("sha256").update(canonical).digest("hex").slice(0, 12)}`;
+}
+function stringValue(value) {
+    return value.startsWith("'") ? value.slice(1, -1) : JSON.parse(value);
+}
+/** 仅处理本安装器的单行参数形式；复杂 TOML 明确拒绝，不猜测或输出配置原文。 */
+export function findCodexProjectEntry(text, root) {
+    if (text.includes('"""') || text.includes("'''"))
+        throw new Error("配置包含多行字符串，自动升级无法安全确认段落边界；未修改配置。");
+    const canonical = canonicalProjectRoot(root), expected = codexProjectServerKey(root);
+    const matches = [];
+    const headers = [...text.matchAll(/^(?:\uFEFF)?[ \t]*\[mcp_servers\.(?:([A-Za-z0-9_-]+)|"([^"\r\n]+)"|'([^'\r\n]+)')\][ \t]*(?:#.*)?\r?$/gm)];
+    for (const header of headers) {
+        const name = header[1] ?? header[2] ?? header[3];
+        if (name !== SERVER_NAME && !name.startsWith(SERVER_NAME + "-"))
+            continue;
+        const start = header.index + header[0].length;
+        const next = text.slice(start).search(/^[ \t]*\[/m);
+        const end = next < 0 ? text.length : start + next;
+        const section = text.slice(start, end);
+        const commands = [...section.matchAll(/^[ \t]*command[ \t]*=[ \t]*("[^\r\n]*"|'[^\r\n]*')[ \t]*(?:#.*)?\r?$/gm)];
+        const arrays = [...section.matchAll(/^[ \t]*args[ \t]*=[ \t]*(\[[^\r\n]*\])[ \t]*(?:#.*)?\r?$/gm)];
+        let entry;
+        try {
+            if (commands.length !== 1 || arrays.length !== 1)
+                throw new Error();
+            const command = stringValue(commands[0][1]), args = JSON.parse(arrays[0][1]);
+            if (typeof command !== "string" || !Array.isArray(args) || !args.every((value) => typeof value === "string"))
+                throw new Error();
+            const positions = args.flatMap((value, index) => value === "--root" ? [index] : []);
+            if (positions.length !== 1 || !path.isAbsolute(args[positions[0] + 1] ?? ""))
+                throw new Error();
+            const filters = [...section.matchAll(/^[ \t]*(enabled_tools|disabled_tools)[ \t]*=[ \t]*(\[[^\r\n]*\])/gm)];
+            entry = { name, command, args, root: canonicalProjectRoot(args[positions[0] + 1]), start, end,
+                enabled: !/^[ \t]*enabled[ \t]*=[ \t]*false\b/m.test(section),
+                toolFilters: [...section.matchAll(/^[ \t]*(?:enabled_tools|disabled_tools)[ \t]*=/gm)].length !== filters.length || filters.some((filter) => filter[1] === "enabled_tools" || JSON.parse(filter[2]).length > 0) };
+        }
+        catch { /* 无法识别的条目不会被覆盖 */ }
+        if (name === expected && entry?.root !== canonical)
+            throw new Error(`已有 [mcp_servers.${name}] 指向不同项目或无法确认 --root；未修改配置。`);
+        if (!entry && (name === SERVER_NAME || name === expected.slice(0, -13)))
+            throw new Error("旧 pm-mcp 条目的项目根无法确认，拒绝创建可能重复的启动项。");
+        if (entry?.root === canonical)
+            matches.push(entry);
+    }
+    if (matches.length > 1)
+        throw new Error("多个 pm-mcp 条目指向同一项目，需先明确保留哪个；未修改配置。");
+    return matches[0];
+}
+export function readCodexConfig(file) {
+    if (!fs.existsSync(file))
+        return "";
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 2 * 1024 * 1024)
+        throw new Error("Codex 配置必须为有界普通文件，禁止链接。");
+    return fs.readFileSync(file, "utf8");
+}
+export function isPackageLaunch(entry) {
+    return /^npx(?:\.(?:cmd|exe))?$/i.test(path.basename(entry.command)) && entry.args.length === 4 && entry.args[0] === "-y" &&
+        /^@luckychen1993\/pm-mcp(?:@[^\s]+)?$/.test(entry.args[1]) && entry.args[2] === "--root";
+}
+/**
+ * 校验启动项指向本包已构建的本地入口（`dist/index.js` 或 `src/index.ts`）。
+ *
+ * 与 `isLocalLaunch` 的区别：**不要求 `--root`**。WorkBuddy 等多项目宿主
+ * 以会话工作区作为子进程 cwd，服务端按 cwd 解析项目根，此时参数里没有 `--root`。
+ */
+export function isLocalServerEntry(entry) {
+    if (!/^node(?:\.exe)?$/i.test(path.basename(entry.command)) || entry.args.length < 1 || !path.isAbsolute(entry.args[0]))
+        return false;
+    const file = path.resolve(entry.args[0]);
+    if (!/^(?:index|cli)\.(?:js|ts)$/.test(path.basename(file)))
+        return false;
+    try {
+        const stat = fs.lstatSync(file);
+        return stat.isFile() && !stat.isSymbolicLink() && JSON.parse(fs.readFileSync(path.join(path.dirname(file), "..", "package.json"), "utf8")).name === "@luckychen1993/pm-mcp";
+    }
+    catch {
+        return false;
+    }
+}
+export function isLocalLaunch(entry) {
+    return entry.args.length === 3 && entry.args[1] === "--root" && isLocalServerEntry(entry);
+}
+export function appendCodexProjectConfig(file, root, force, dryRun, log, local) {
+    const absolute = path.resolve(file), existing = readCodexConfig(absolute);
+    const entry = findCodexProjectEntry(existing, root);
+    const desired = local ?? { command: "npx", args: ["-y", PACKAGE_SPEC, "--root", path.resolve(root).replace(/\\/g, "/")] };
+    let updated;
+    if (entry) {
+        if (!force) {
+            log(`[skip] Codex already has [mcp_servers.${entry.name}] for this project; --force 可升级，现有配置保留。`);
+            return;
+        }
+        if (!isPackageLaunch(entry) && !isLocalLaunch(entry))
+            throw new Error("当前启动项不是可识别的 pm-mcp npx/node 形式；未修改配置。");
+        if (entry.command === desired.command && JSON.stringify(entry.args) === JSON.stringify(desired.args)) {
+            log("[skip] 启动配置已是目标版本；仍需通过 doctor 核验连接。");
+            return;
+        }
+        const section = existing.slice(entry.start, entry.end);
+        const replace = (name, value, input) => input.replace(new RegExp(`^([ \\t]*${name}[ \\t]*=[ \\t]*)(?:\\[[^\\r\\n]*\\]|"[^\\r\\n]*"|'[^\\r\\n]*')([ \\t]*(?:#.*)?)(\\r?)$`, "m"), (_all, prefix, suffix, cr) => prefix + value + suffix + cr);
+        const patched = replace("args", JSON.stringify(desired.args), replace("command", JSON.stringify(desired.command), section));
+        updated = existing.slice(0, entry.start) + patched + existing.slice(entry.end);
+        const checked = findCodexProjectEntry(updated, root);
+        if (!checked || checked.command !== desired.command || JSON.stringify(checked.args) !== JSON.stringify(desired.args))
+            throw new Error("启动配置替换验证失败，未写入。");
+        log(`[${dryRun ? "plan" : "upgrade"}] Codex [mcp_servers.${entry.name}]；仅替换 command/args，保留其余设置。`);
+    }
+    else {
+        const separator = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+        const name = codexProjectServerKey(root);
+        updated = existing + `${separator}\n[mcp_servers.${name}]\ncommand = ${JSON.stringify(desired.command)}\nargs = ${JSON.stringify(desired.args)}\n`;
+        log(`[${dryRun ? "plan" : "write"}] Codex: ${absolute}`);
+        log(`[entry] [mcp_servers.${name}] → --root ${path.resolve(root)}`);
+    }
+    if (dryRun)
+        return;
+    fs.mkdirSync(path.dirname(absolute), { recursive: true });
+    if (readCodexConfig(absolute) !== existing)
+        throw new Error("配置在准备期间发生变化；未写入，请重新预览。");
+    if (fs.existsSync(absolute))
+        fs.copyFileSync(absolute, `${absolute}.backup-${Date.now()}-${randomUUID()}`, fs.constants.COPYFILE_EXCL);
+    atomicWrite(absolute, updated);
+}

package/dist/setup.js

@@ -2,21 +2,24 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
-import { createHash, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
 import { initProject } from "./init.js";
 import { isInitialized } from "./paths.js";
 import { refreshDerived } from "./dashboard.js";
-export const PACKAGE_SPEC = "@luckychen1993/pm-mcp@0.1.5";
-export const SERVER_NAME = "pm-mcp";
-const CLIENTS = ["codex", "claude", "zcode", "cursor", "vscode"];
+import { PACKAGE_SPEC, SERVER_NAME } from "./version.js";
+export { PACKAGE_SPEC, SERVER_NAME } from "./version.js";
+import { appendCodexProjectConfig } from "./setup-project.js";
+export { appendCodexProjectConfig, codexProjectServerKey } from "./setup-project.js";
+const CLIENTS = ["codex", "claude", "zcode", "cursor", "vscode", "workbuddy"];
 export function parseSetupArgs(argv) {
     const options = { client: "auto", force: false, dryRun: false, help: false, project: false };
     for (let index = 0; index < argv.length; index += 1) {
         const arg = argv[index];
         if (arg === "--client") {
             const value = argv[index + 1];
-            if (!value || !["auto", "all", "codex", "claude", "zcode", "cursor", "vscode", "print"].includes(value)) {
-                throw new Error("--client must be auto, all, codex, claude, zcode, cursor, vscode, or print");
+            if (!value || !["auto", "all", "codex", "claude", "zcode", "cursor", "vscode", "workbuddy", "print"].includes(value)) {
+                throw new Error("--client must be auto, all, codex, claude, zcode, cursor, vscode, workbuddy, or print");
             }
             options.client = value;
             index += 1;
@@ -32,6 +35,9 @@ export function parseSetupArgs(argv) {
         else if (arg === "--force") {
             options.force = true;
         }
+        else if (arg === "--local") {
+            options.local = true;
+        }
         else if (arg === "--dry-run") {
             options.dryRun = true;
         }
@@ -42,8 +48,29 @@ export function parseSetupArgs(argv) {
             throw new Error(`unknown setup argument: ${arg}`);
         }
     }
+    if (options.local && options.client !== "codex" && options.client !== "workbuddy" && options.client !== "print")
+        throw new Error("--local 目前只支持 --client codex、workbuddy 或 print");
+    if (options.local && options.client === "codex" && !options.project)
+        throw new Error("Codex --local 需要 --project 明确项目根");
     return options;
 }
+/**
+ * 本地已构建入口的启动定义。
+ *
+ * root 省略时不写 `--root`：宿主客户端会把**会话工作区**作为子进程 cwd，
+ * 服务端按 cwd 解析项目根。WorkBuddy 这类多项目宿主依赖这一行为，
+ * 显式钉根反而会把所有工作区都指到同一个项目。
+ */
+export function localServerLaunch(root) {
+    const entry = fileURLToPath(new URL("../dist/index.js", import.meta.url));
+    if (!fs.existsSync(entry) || !fs.lstatSync(entry).isFile())
+        throw new Error("本地入口未构建，请先 npm run build。");
+    return { command: process.execPath, args: root ? [entry, "--root", path.resolve(root)] : [entry] };
+}
+/** 钉定单个项目根的本地启动定义（Codex `--project` 等场景）。 */
+export function localProjectLaunch(root) {
+    return localServerLaunch(root);
+}
 export function commandExists(command, env = process.env, platform = process.platform) {
     const searchPath = env.PATH ?? env.Path ?? "";
     const suffixes = platform === "win32" ? [".exe", ".cmd", ".bat", ""] : [""];
@@ -69,6 +96,9 @@ export function detectClients(context) {
         found.push("cursor");
     if (context.commandExists("code"))
         found.push("vscode");
+    // WorkBuddy 桌面版：`codebuddy`/`workbuddy` 命令、WORKBUDDY_CONFIG_DIR，或既有配置目录任一命中即视为已安装。
+    if (context.commandExists("workbuddy") || context.commandExists("codebuddy") || Boolean(env.WORKBUDDY_CONFIG_DIR) || exists(path.join(home, ".workbuddy-ai")) || exists(path.join(home, ".workbuddy")))
+        found.push("workbuddy");
     return found;
 }
 function asObject(value, label) {
@@ -76,7 +106,10 @@ function asObject(value, label) {
         throw new Error(`${label} must be a JSON object`);
     return value;
 }
-export function mergeJsonServer(document, shape) {
+function defaultJsonLaunch() {
+    return { command: "npx", args: ["-y", PACKAGE_SPEC], env: {} };
+}
+export function mergeJsonServer(document, shape, launch = defaultJsonLaunch()) {
     const root = asObject(document, "configuration root");
     let servers;
     if (shape === "zcode") {
@@ -89,14 +122,14 @@ export function mergeJsonServer(document, shape) {
         const currentServers = root.mcpServers === undefined ? (root.mcpServers = {}) : root.mcpServers;
         servers = asObject(currentServers, "mcpServers");
     }
-    servers[SERVER_NAME] = { command: "npx", args: ["-y", PACKAGE_SPEC], env: {} };
+    servers[SERVER_NAME] = { ...launch, env: launch.env ?? {} };
     return root;
 }
 function backupName(file) {
     const stamp = new Date().toISOString().replace(/[-:.TZ]/g, "");
     return `${file}.backup-${stamp}-${process.pid}-${randomUUID()}`;
 }
-export function writeJsonClientConfig(file, shape, dryRun = false) {
+export function writeJsonClientConfig(file, shape, dryRun = false, launch) {
     const absolute = path.resolve(file);
     const exists = fs.existsSync(absolute);
     let document = {};
@@ -111,7 +144,7 @@ export function writeJsonClientConfig(file, shape, dryRun = false) {
             throw new Error(`invalid JSON in ${absolute}; no changes made: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
-    const merged = mergeJsonServer(document, shape);
+    const merged = mergeJsonServer(document, shape, launch);
     if (dryRun)
         return null;
     fs.mkdirSync(path.dirname(absolute), { recursive: true });
@@ -138,6 +171,26 @@ function codexConfigPath(env, home) {
 function zcodeConfigPath(env, home) {
     return path.join(env.ZCODE_HOME || path.join(home, ".zcode"), "cli", "config.json");
 }
+/**
+ * WorkBuddy 桌面版的用户级 MCP 配置路径。
+ *
+ * 优先级：`WORKBUDDY_CONFIG_DIR` → `~/.workbuddy-ai`（当前版本数据目录）→ `~/.workbuddy`（旧版目录）→ 默认当前版本目录。
+ * 文件名固定 `mcp.json`，结构为标准 `{ "mcpServers": { ... } }`。
+ *
+ * 注意：WorkBuddy 的 MCP 子进程由会话工作区拉起，cwd 即当前项目，
+ * 因此这里**不写 `--root`**，一个条目即可服务所有工作区。
+ */
+export function workbuddyConfigPath(env, home, exists) {
+    if (env.WORKBUDDY_CONFIG_DIR)
+        return path.join(env.WORKBUDDY_CONFIG_DIR, "mcp.json");
+    const current = path.join(home, ".workbuddy-ai");
+    if (exists(current))
+        return path.join(current, "mcp.json");
+    const legacy = path.join(home, ".workbuddy");
+    if (exists(legacy))
+        return path.join(legacy, "mcp.json");
+    return path.join(current, "mcp.json");
+}
 function hasCodexServer(text) {
     return /^\s*\[mcp_servers\.(?:pm-mcp|"pm-mcp")\]\s*$/m.test(text);
 }
@@ -158,86 +211,6 @@ function appendCodexConfig(file, dryRun, log) {
     const block = `${separator}\n[mcp_servers.${SERVER_NAME}]\ncommand = "npx"\nargs = ["-y", "${PACKAGE_SPEC}"]\n`;
     fs.appendFileSync(absolute, block, "utf8");
 }
-function canonicalProjectRoot(projectRoot) {
-    const absolute = path.resolve(projectRoot);
-    let resolved;
-    try {
-        resolved = fs.realpathSync.native(absolute);
-    }
-    catch (error) {
-        if (error.code !== "ENOENT")
-            throw error;
-        resolved = absolute;
-    }
-    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
-}
-function legacyProjectServerKey(projectRoot) {
-    const base = path.basename(projectRoot);
-    const safe = base.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
-    return `${SERVER_NAME}-${safe || "project"}`;
-}
-/** 完整规范路径参与命名，区分中文目录和位于不同父目录下的同名项目。 */
-export function codexProjectServerKey(projectRoot) {
-    const canonical = canonicalProjectRoot(projectRoot);
-    return `${legacyProjectServerKey(canonical)}-${createHash("sha256").update(canonical).digest("hex").slice(0, 12)}`;
-}
-/** 只解析本安装器生成的单行 JSON 兼容 args；手写复杂 TOML 不猜测其绑定。 */
-function projectEntry(text, server) {
-    const header = new RegExp(`^\\s*\\[mcp_servers\\.(?:${server}|"${server}"|'${server}')\\]\\s*(?:#.*)?$`, "m").exec(text);
-    if (!header)
-        return undefined;
-    const tail = text.slice(header.index + header[0].length);
-    const nextHeader = tail.search(/^\s*\[/m);
-    const section = nextHeader < 0 ? tail : tail.slice(0, nextHeader);
-    const argsLine = /^\s*args\s*=\s*(\[[^\r\n]*\])\s*(?:#.*)?$/m.exec(section);
-    try {
-        const args = argsLine ? JSON.parse(argsLine[1]) : undefined;
-        if (!Array.isArray(args) || !args.every((value) => typeof value === "string"))
-            return {};
-        const positions = args.flatMap((value, index) => value === "--root" ? [index] : []);
-        if (positions.length !== 1 || !path.isAbsolute(args[positions[0] + 1] ?? ""))
-            return {};
-        return { root: canonicalProjectRoot(args[positions[0] + 1]) };
-    }
-    catch {
-        return {};
-    }
-}
-/**
- * --project 模式：把指定目录作为钉定项目写进 Codex config.toml（npx + --root）。
- * 桌面版 Codex 起 MCP 服务时 cwd 不在工作区，必须逐项目钉根；同名条目已存在则跳过（fail-closed，不产生重复 TOML 表头）。
- */
-export function appendCodexProjectConfig(file, projectRoot, force, dryRun, log) {
-    const absolute = path.resolve(file);
-    const server = codexProjectServerKey(projectRoot);
-    const canonical = canonicalProjectRoot(projectRoot);
-    const existing = fs.existsSync(absolute) ? fs.readFileSync(absolute, "utf8") : "";
-    const entry = projectEntry(existing, server);
-    const legacy = legacyProjectServerKey(canonical);
-    const legacyEntry = projectEntry(existing, legacy);
-    if (entry && entry.root !== canonical) {
-        throw new Error(`已有 [mcp_servers.${server}] 指向不同项目或无法确认 --root；未修改配置。`);
-    }
-    if (entry || legacyEntry?.root === canonical) {
-        const reused = entry ? server : legacy;
-        if (!force)
-            log(`[skip] Codex already has [mcp_servers.${reused}] for this project; nothing to change.`);
-        else
-            throw new Error(`Codex already has [mcp_servers.${reused}]; 请先手工删除该段再 --force 重加。`);
-        return;
-    }
-    log(`[${dryRun ? "plan" : "write"}] Codex: ${absolute}`);
-    if (dryRun)
-        return;
-    fs.mkdirSync(path.dirname(absolute), { recursive: true });
-    if (fs.existsSync(absolute))
-        fs.copyFileSync(absolute, backupName(absolute), fs.constants.COPYFILE_EXCL);
-    const tomlRoot = path.resolve(projectRoot).replace(/\\/g, "/");
-    const separator = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
-    const block = `${separator}\n[mcp_servers.${server}]\ncommand = "npx"\nargs = ["-y", ${JSON.stringify(PACKAGE_SPEC)}, "--root", ${JSON.stringify(tomlRoot)}]\n`;
-    fs.appendFileSync(absolute, block, "utf8");
-    log(`[entry] [mcp_servers.${server}] → --root ${tomlRoot}`);
-}
 function run(command, args, visible) {
     const result = spawnSync(command, args, {
         shell: false,
@@ -272,7 +245,7 @@ function configureCliClient(client, options, available, log) {
 function configureClient(client, options, context, log, projectRoot) {
     if (client === "codex") {
         if (options.project && projectRoot) {
-            appendCodexProjectConfig(codexConfigPath(context.env, context.home), projectRoot, options.force, options.dryRun, log);
+            appendCodexProjectConfig(codexConfigPath(context.env, context.home), projectRoot, options.force, options.dryRun, log, options.local ? localProjectLaunch(projectRoot) : undefined);
             return;
         }
         if (configureCliClient("codex", options, context.commandExists("codex"), log))
@@ -293,6 +266,16 @@ function configureClient(client, options, context, log, projectRoot) {
             log(`[backup] ${backup}`);
         return;
     }
+    if (client === "workbuddy") {
+        const file = workbuddyConfigPath(context.env, context.home, context.exists);
+        log(`[${options.dryRun ? "plan" : "write"}] workbuddy: ${file}`);
+        // 默认写 npx 发布版；--local 绑定已构建入口，未发布候选走这条路径。
+        const launch = options.local ? localServerLaunch() : undefined;
+        const backup = writeJsonClientConfig(file, "standard", options.dryRun, launch);
+        if (backup)
+            log(`[backup] ${backup}`);
+        return;
+    }
     if (!context.commandExists("code"))
         throw new Error("code was not found in PATH");
     const definition = JSON.stringify({ name: SERVER_NAME, command: "npx", args: ["-y", PACKAGE_SPEC] });
@@ -303,9 +286,12 @@ function configureClient(client, options, context, log, projectRoot) {
 function printHelp(log) {
     log("pm-mcp setup — configure local AI coding clients");
     log("");
-    log(`Usage: npx -y ${PACKAGE_SPEC} setup [--client auto|all|codex|claude|zcode|cursor|vscode|print] [--project [dir]] [--force] [--dry-run]`);
+    log(`Usage: npx -y ${PACKAGE_SPEC} setup [--client auto|all|codex|claude|zcode|cursor|vscode|workbuddy|print] [--project [dir]] [--force] [--dry-run] [--local]`);
     log("Default auto mode configures every detected supported client.");
     log("--project [dir]: 在 Codex 把该目录注册为钉定项目并初始化 .pm（新项目一条命令上手；默认当前目录）");
+    log("--local: 使用本包已构建的本地入口，适合未发布候选；--force 仅升级已确认项目的 command/args。");
+    log("workbuddy: 写入 <WorkBuddy 数据目录>/mcp.json（标准 mcpServers），不钉根——服务端按会话工作区解析项目根。");
+    log("升级后运行 pm-mcp doctor --root <项目目录> 核验；现有客户端仍需重新连接。");
 }
 export function runSetup(argv, overrides = {}) {
     const options = parseSetupArgs(argv);
@@ -315,7 +301,8 @@ export function runSetup(argv, overrides = {}) {
         return 0;
     }
     if (options.client === "print") {
-        log(JSON.stringify({ mcpServers: { [SERVER_NAME]: { command: "npx", args: ["-y", PACKAGE_SPEC], env: {} } } }, null, 2));
+        const launch = options.local ? localProjectLaunch(options.projectDir ?? overrides.cwd ?? process.cwd()) : { command: "npx", args: ["-y", PACKAGE_SPEC] };
+        log(JSON.stringify({ mcpServers: { [SERVER_NAME]: { ...launch, env: {} } } }, null, 2));
         return 0;
     }
     const env = overrides.env ?? process.env;
@@ -370,8 +357,19 @@ export function runSetup(argv, overrides = {}) {
     if (options.project && selected.includes("codex")) {
         log("完成。请完全退出并重启 Codex，开新会话即可使用（工具名前缀 pm-mcp-<项目名>）。");
     }
+    else if (selected.length === 1 && selected[0] === "workbuddy") {
+        log("完成。请在 WorkBuddy 的「连接器管理 → 自定义连接器」中确认信任 pm-mcp，再重开会话调用 get_status 核验。");
+    }
     else {
-        log("Done. Restart the configured client and ask it to call pm-mcp get_status.");
+        // 多客户端时逐条给出各自的重连/授权要求，避免只提其中一个造成误导。
+        const notes = [];
+        if (selected.includes("workbuddy"))
+            notes.push("WorkBuddy 需在「连接器管理 → 自定义连接器」确认信任 pm-mcp");
+        if (selected.includes("codex"))
+            notes.push("Codex 需完全退出并重启");
+        log(notes.length > 0
+            ? `完成。重启已配置的客户端后调用 get_status 核验；${notes.join("；")}。`
+            : "Done. Restart the configured client and ask it to call pm-mcp get_status.");
     }
     return 0;
 }

package/dist/task-evidence.js

@@ -0,0 +1,110 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { fingerprintProject } from "./project-fingerprint.js";
+import { changedGitFiles, projectFilePath } from "./git-state.js";
+import { SCAN_IGNORE_DIRS, ignoreMatcher, projectScanIgnores } from "./scan-policy.js";
+import { loadProject } from "./store.js";
+import { evidenceLevel, weakestEvidence } from "./quality-evidence.js";
+const fingerprint = z.object({ algorithm: z.literal("sha256-tree-v1"), sha256: z.string().regex(/^[a-f0-9]{64}$/) });
+const count = z.number().int().nonnegative().nullable();
+const reportSchema = z.object({
+    schema_version: z.literal(2), run_at: z.string().datetime(), ok: z.boolean(), execute: z.boolean(),
+    source: z.object({ before: fingerprint, after: fingerprint, stable: z.boolean() }).nullable(),
+    results: z.array(z.object({
+        unit_root: z.string(), kind: z.string(), command: z.string().min(1), args: z.array(z.string()),
+        status: z.string(), exit_code: z.number().nullable(), signal: z.string().nullable(), output_truncated: z.boolean(),
+        output_summary: z.object({ tests: count, passed: count.optional(), failed: count, skipped: count, cancelled: count, todo: count, coverage: z.unknown().optional() }),
+    })).min(1),
+});
+/** 只读取当前项目内生成的质量报告；链接、损坏和旧格式不冒充证据。 */
+export function verifiedTaskEvidence(root, requested, files = []) {
+    const absolute = fs.realpathSync.native(path.resolve(root));
+    const anchors = files.map(projectFilePath);
+    if (anchors.length === 0)
+        throw new Error("完成开发/修复任务需要通过 files 关联实际实现或测试文件。");
+    const excluded = ignoreMatcher(projectScanIgnores(root));
+    for (const rel of anchors) {
+        const parts = rel.split("/");
+        if (rel === "PROJECT.md" || parts.some((part, index) => (index < parts.length - 1 && SCAN_IGNORE_DIRS.has(part)) || excluded(parts.slice(0, index + 1).join("/"), index < parts.length - 1))) {
+            throw new Error(`任务文件不在源码验证范围内: ${rel}`);
+        }
+        for (let index = 0; index < parts.length; index++) {
+            const target = path.join(absolute, ...parts.slice(0, index + 1));
+            let stat;
+            try {
+                stat = fs.lstatSync(target);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+                if (!changedGitFiles(absolute).includes(rel))
+                    throw new Error(`任务关联文件不存在，也没有 Git 删除记录: ${rel}`);
+                break;
+            }
+            if (stat.isSymbolicLink() || (index === parts.length - 1 ? !stat.isFile() : !stat.isDirectory())) {
+                throw new Error(`任务必须关联项目内的普通文件，禁止链接或目录: ${rel}`);
+            }
+        }
+    }
+    const directory = path.join(absolute, ".pm", "quality-runs");
+    for (const part of [path.join(absolute, ".pm"), directory]) {
+        if (!fs.existsSync(part))
+            throw new Error("完成开发/修复任务前请执行 run_quality_matrix，缺少质量验证报告。");
+        const stat = fs.lstatSync(part);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error("质量证据目录必须是项目内的普通目录。");
+    }
+    const reports = fs.readdirSync(directory).filter((name) => /^quality-.*\.json$/.test(name)).map((name) => {
+        const file = path.join(directory, name);
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 4 * 1024 * 1024)
+            throw new Error("质量证据必须是有界普通文件，禁止符号链接。");
+        const raw = fs.readFileSync(file, "utf8");
+        const value = JSON.parse(raw);
+        const header = z.object({ run_at: z.string().datetime() }).safeParse(value);
+        if (!header.success)
+            throw new Error(`质量报告 ${name} 缺少有效生成时间，无法判断新鲜度。`);
+        return { relative: `.pm/quality-runs/${name}`, raw, value, runAt: header.data.run_at };
+    }).sort((a, b) => b.runAt.localeCompare(a.runAt) || b.relative.localeCompare(a.relative));
+    const latest = reports[0];
+    if (!latest)
+        throw new Error("缺少质量验证报告，请先执行 run_quality_matrix。");
+    if (requested !== undefined && projectFilePath(requested) !== latest.relative)
+        throw new Error("必须使用最新质量报告，不能绕过后来出现的验证结果。");
+    const parsed = reportSchema.safeParse(latest.value);
+    if (!parsed.success)
+        throw new Error("最新质量报告无效或格式过旧，请重新执行验证。");
+    const report = parsed.data;
+    if (!report.ok || !report.execute || !report.source?.stable || report.source.before.sha256 !== report.source.after.sha256 ||
+        report.results.some((item) => item.status !== "passed" || item.exit_code !== 0 || item.signal !== null || item.output_truncated ||
+            [item.output_summary.failed, item.output_summary.skipped, item.output_summary.cancelled, item.output_summary.todo].some((n) => n !== null && n > 0))) {
+        throw new Error("最新质量验证失败、未执行、输出不完整或存在跳过项，不能标记完成。");
+    }
+    const tests = report.results.filter((item) => item.kind === "test" || item.kind === "coverage");
+    if (tests.length === 0 || tests.some((item) => item.output_summary.tests === 0))
+        throw new Error("完成开发/修复任务需要实际测试或覆盖率执行证据。");
+    const level = weakestEvidence(tests.map((item) => evidenceLevel(item.kind, item.output_summary, item.output_truncated)));
+    const policy = loadProject(root).completion_evidence;
+    if (level === "execution_only" && policy?.minimum !== "execution_only") {
+        throw new Error("仅有命令执行证据，未观察到完整测试计数。默认完成策略要求 tests_observed；请使用可识别的测试摘要，或由项目负责人明确设置兼容策略并说明理由。");
+    }
+    const within = (base, target) => {
+        const relative = path.relative(base, target);
+        return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+    };
+    if (tests.some((item) => !path.isAbsolute(item.unit_root)))
+        throw new Error("质量报告的执行目录不属于当前项目。");
+    const unitRoots = tests.map((item) => fs.realpathSync.native(item.unit_root));
+    if (unitRoots.some((unit) => !within(absolute, unit)))
+        throw new Error("质量报告的执行目录不属于当前项目。");
+    if (anchors.some((file) => !unitRoots.some((unit) => within(unit, path.join(absolute, file))))) {
+        throw new Error("质量报告的测试单元未覆盖任务关联文件所在目录。");
+    }
+    const current = fingerprintProject(absolute);
+    if (current.sha256 !== report.source.after.sha256)
+        throw new Error("质量验证对应的源码已变化，证据过期，请重新验证。");
+    const digest = createHash("sha256").update(latest.raw).digest("hex");
+    return `质量报告: ${latest.relative}\n报告 SHA-256: ${digest}\n源码 SHA-256: ${current.sha256}\n执行时间: ${report.run_at}\n证据等级: ${level}${policy ? `\n项目策略: ${policy.minimum}；${policy.reason}` : "\n项目策略: tests_observed（默认）"}`;
+}

package/dist/task-pagination.js

@@ -0,0 +1,64 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { loadTasks } from "./store.js";
+import { TaskStatusSchema, TaskTypeSchema } from "./types.js";
+const CursorSchema = z.object({ v: z.literal(1), revision: z.string().regex(/^[a-f0-9]{64}$/), offset: z.number().int().positive(), size: z.number().int().min(1).max(100) }).strict();
+export const TaskPageSchema = z.object({
+    total: z.number().int().nonnegative(), all_total: z.number().int().nonnegative(),
+    offset: z.number().int().nonnegative(), page_size: z.number().int().min(1).max(100), returned: z.number().int().nonnegative(),
+    has_more: z.boolean(), next_cursor: z.string().nullable(), revision: z.string(),
+    items: z.array(z.object({ id: z.string(), title: z.string(), status: TaskStatusSchema, type: TaskTypeSchema,
+        priority: z.string().nullable(), milestone: z.string().nullable(), next_step: z.string().nullable(), abbreviated: z.boolean() })),
+});
+/** 游标是读取位置，不是授权凭据；绑定项目、过滤及同一份已读取的账本快照。 */
+export function taskPage(root, query, maximum = 100, data = loadTasks(root)) {
+    const filters = { status: query.status ?? null, type: query.type ?? null, milestone: query.milestone ?? null, tag: query.tag ?? null, include_done: query.include_done ?? false };
+    let canonical = fs.realpathSync.native(path.resolve(root));
+    if (process.platform === "win32")
+        canonical = canonical.toLowerCase();
+    const revision = createHash("sha256").update(canonical).update("\0").update(JSON.stringify(filters)).update("\0").update(JSON.stringify(data)).digest("hex");
+    let cursor;
+    if (query.cursor !== undefined) {
+        try {
+            if (query.cursor.length > 1024 || !/^[A-Za-z0-9_-]+$/.test(query.cursor))
+                throw new Error();
+            cursor = CursorSchema.parse(JSON.parse(Buffer.from(query.cursor, "base64url").toString("utf8")));
+        }
+        catch {
+            throw new Error("分页游标无效，请从第一页重新读取。");
+        }
+        if (cursor.revision !== revision)
+            throw new Error("任务数据、项目或过滤条件已变化，游标失效，请重新读取第一页。");
+    }
+    const limit = Math.max(1, Math.min(100, Math.floor(maximum)));
+    const requested = query.page_size ?? cursor?.size ?? 25;
+    if (!Number.isInteger(requested) || requested < 1 || requested > 100)
+        throw new Error("page_size 必须为 1 到 100。");
+    const size = Math.min(requested, limit);
+    if (cursor && (cursor.size !== size || cursor.offset % size !== 0))
+        throw new Error("分页大小或输出预算已变化，请重新读取第一页。");
+    const list = data.tasks.filter((task) => (query.status ? task.status === query.status : query.include_done || !["done", "cancelled"].includes(task.status)) &&
+        (!query.type || task.type === query.type) && (!query.milestone || task.milestone === query.milestone) && (!query.tag || task.tags.includes(query.tag)));
+    const offset = cursor?.offset ?? 0;
+    if (cursor && offset >= list.length)
+        throw new Error("分页游标越界，请重新读取第一页。");
+    const brief = (text, length) => { const one = text.replace(/\s+/g, " "); return one.length > length ? one.slice(0, length) + "…" : one; };
+    const items = list.slice(offset, offset + size).map((task) => {
+        const title = brief(task.title, 160), nextStep = task.checkpoint ? brief(task.checkpoint.next_step, 80) : null;
+        return { id: task.id, title, status: task.status, type: task.type, priority: task.priority, milestone: task.milestone,
+            next_step: nextStep, abbreviated: title !== task.title || nextStep !== (task.checkpoint?.next_step ?? null) };
+    });
+    const next = offset + items.length;
+    return { total: list.length, all_total: data.tasks.length, offset, page_size: size, returned: items.length, has_more: next < list.length,
+        next_cursor: next < list.length ? Buffer.from(JSON.stringify({ v: 1, revision, offset: next, size })).toString("base64url") : null, revision, items };
+}
+export function taskPageText(page) {
+    return [
+        `共 ${page.total} 个任务（全部 ${page.all_total} 个）；本页 ${page.offset + (page.returned ? 1 : 0)}-${page.offset + page.returned}，返回 ${page.returned} 个。`,
+        ...page.items.map((task) => `${task.status === "in_progress" ? "🔄" : task.status === "blocked" ? "🚫" : task.status === "done" ? "✅" : "☐"} ${task.id} [${task.status}/${task.type}${task.priority ? `/${task.priority}` : ""}] ${task.title}${task.next_step ? ` → ${task.next_step}` : ""}`),
+        page.next_cursor ? `下一页：保持过滤条件，list_tasks 传 cursor=${page.next_cursor}` : "已到末页，无更多任务。",
+        ...(page.items.some((task) => task.abbreviated) ? ["长标题或下一步已缩略；任务编号与分页条目完整。"] : []),
+    ].join("\n");
+}