@luckychen1993/pm-mcp 0.4.0 → 0.6.0

package/dist/resources.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { dashboardFile, pmPath } from "./paths.js";
+import { loadRoadmap, loadTasks } from "./store.js";
+import { renderRoadmap } from "./roadmap.js";
+import { buildChangelog } from "./dashboard.js";
+import { auditGovernance } from "./governance-audit.js";
+import { buildPortfolioReport, loadPortfolioProject } from "./portfolio.js";
+import { listAcceptanceBaselines } from "./acceptance-tools.js";
+import { AcceptanceReportSchema } from "./acceptance-report.js";
+import { runCoalescedRead } from "./idempotency.js";
+import { budgetLines, recordUsage, requestContext } from "./tool-base.js";
+import { taskPage } from "./task-pagination.js";
+export function registerResources(server, root) {
+    function safeText(fn) {
+        try {
+            return fn();
+        }
+        catch (e) {
+            return `（不可用: ${e.message}）`;
+        }
+    }
+    async function resourceText(name, fn) {
+        const started = Date.now();
+        const target = requestContext(name, {}, root).root;
+        try {
+            const text = (await runCoalescedRead(target, `resource:${name}`, {}, () => safeText(() => fn(target)))).text;
+            recordUsage(target, `resource:${name}`, "read", started, { ok: true, text });
+            return text;
+        }
+        catch (error) {
+            recordUsage(target, `resource:${name}`, "read", started, { ok: false, error: error.message });
+            throw error;
+        }
+    }
+    server.registerResource("dashboard", "pm://dashboard", { description: "项目仪表盘（与仓库根 PROJECT.md 同源），路线图/健康摘要/任务/功能清单" }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "text/markdown",
+                text: await resourceText("dashboard", (r) => fs.readFileSync(dashboardFile(r), "utf8")),
+            },
+        ],
+    }));
+    server.registerResource("roadmap", "pm://roadmap", { description: "路线图（里程碑进度 + 活跃里程碑任务明细）" }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "text/markdown",
+                text: await resourceText("roadmap", (r) => renderRoadmap(loadRoadmap(r).milestones, loadTasks(r).tasks, 2).join("\n")),
+            },
+        ],
+    }));
+    server.registerResource("tasks", "pm://tasks", { description: "任务原始数据；大列表末尾返回 continuation，可通过 list_tasks 保持 include_done:true 连续取回后续任务" }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "application/json",
+                text: await resourceText("tasks", (r) => {
+                    const data = loadTasks(r);
+                    const tasks = data.tasks;
+                    // 资源也要守 token 预算：全量 dump 大账本会吃爆上下文（截断后仍是合法 JSON）
+                    if (tasks.length <= 100)
+                        return JSON.stringify(tasks, null, 2);
+                    const page = taskPage(r, { include_done: true, page_size: 100 }, budgetLines(r) - 4, data);
+                    const shown = tasks.slice(0, page.returned);
+                    shown.push({
+                        id: `_TRUNCATED_${tasks.length - page.returned}`,
+                        title: `…本次输出已截断，另有 ${tasks.length - page.returned} 个任务，用 continuation 连续读取`,
+                        continuation: { tool: "list_tasks", arguments: { include_done: true, cursor: page.next_cursor } },
+                    });
+                    return JSON.stringify(shown, null, 2);
+                }),
+            },
+        ],
+    }));
+    server.registerResource("changelog", "pm://changelog", { description: "变更日志（由 sessions.json 生成的人类可读版本）" }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "text/markdown",
+                text: await resourceText("changelog", (r) => buildChangelog(r)),
+            },
+        ],
+    }));
+    server.registerResource("architecture", "pm://architecture", { description: "跨文件/模块/语言治理审计：语义覆盖、依赖边界、接口、循环与质量矩阵" }, async (uri) => ({
+        contents: [{ uri: uri.href, mimeType: "text/markdown", text: await resourceText("architecture", (r) => auditGovernance(r, 150).report) }],
+    }));
+    server.registerResource("portfolio", "pm://portfolio", { description: "当前项目的组合视图与跨仓依赖/版本风险" }, async (uri) => ({
+        contents: [{
+                uri: uri.href,
+                mimeType: "application/json",
+                text: await resourceText("portfolio", (r) => JSON.stringify(buildPortfolioReport({ projects: [loadPortfolioProject(r)], projectsRequested: 1 }), null, 2)),
+            }],
+    }));
+    server.registerResource("acceptance", "pm://acceptance", { description: "标准化产品验收概览：版本化预批准基线与最近一次机器判定报告" }, async (uri) => ({
+        contents: [{
+                uri: uri.href,
+                mimeType: "application/json",
+                text: await resourceText("acceptance", (r) => {
+                    const reportDir = pmPath(r, "acceptance", "reports");
+                    let latestReport = null;
+                    if (fs.existsSync(reportDir)) {
+                        const candidates = fs.readdirSync(reportDir, { withFileTypes: true })
+                            .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+                            .map((entry) => ({ name: entry.name, mtime: fs.statSync(path.join(reportDir, entry.name)).mtimeMs }))
+                            .sort((a, b) => b.mtime - a.mtime || a.name.localeCompare(b.name));
+                        if (candidates[0])
+                            latestReport = AcceptanceReportSchema.parse(JSON.parse(fs.readFileSync(path.join(reportDir, candidates[0].name), "utf8")));
+                    }
+                    return JSON.stringify({ baselines: listAcceptanceBaselines(r), latest_report: latestReport }, null, 2);
+                }),
+            }],
+    }));
+}

package/dist/scan.js

@@ -78,6 +78,10 @@ export function looksTrivialTest(content) {
 export function countSkipLines(content) {
     let n = 0;
     for (const line of content.split("\n")) {
+        // 排除两类误报：正则模式定义行（本扫描器源码自身）与夹具字符串模板行（含转义 \n 的内嵌代码）
+        const trimmed = line.trim();
+        if (trimmed.startsWith("/") || line.includes("\\n"))
+            continue;
         if (SKIP_MARKER_PATTERNS.some((re) => re.test(line)))
             n += 1;
     }

package/dist/setup-project.js

@@ -90,7 +90,7 @@ 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)))
+    if (!/^(?:index|cli|qoder-launch)\.(?:js|ts)$/.test(path.basename(file)))
         return false;
     try {
         const stat = fs.lstatSync(file);

package/dist/setup.js

@@ -11,15 +11,15 @@ 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"];
+const CLIENTS = ["codex", "claude", "zcode", "cursor", "vscode", "workbuddy", "qoder"];
 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", "workbuddy", "print"].includes(value)) {
-                throw new Error("--client must be auto, all, codex, claude, zcode, cursor, vscode, workbuddy, or print");
+            if (!value || !["auto", "all", "codex", "claude", "zcode", "cursor", "vscode", "workbuddy", "qoder", "print"].includes(value)) {
+                throw new Error("--client must be auto, all, codex, claude, zcode, cursor, vscode, workbuddy, qoder, or print");
             }
             options.client = value;
             index += 1;
@@ -48,8 +48,8 @@ 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 && !["codex", "workbuddy", "qoder", "print"].includes(options.client))
+        throw new Error("--local 目前只支持 --client codex、workbuddy、qoder 或 print");
     if (options.local && options.client === "codex" && !options.project)
         throw new Error("Codex --local 需要 --project 明确项目根");
     return options;
@@ -99,6 +99,9 @@ export function detectClients(context) {
     // 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");
+    // Qoder：CLI 命令、QODER_CONFIG_DIR，或既有数据目录任一命中即视为已安装。
+    if (context.commandExists("qoder") || context.commandExists("qoderclicn") || Boolean(env.QODER_CONFIG_DIR) || exists(path.join(home, ".qoder-cn")) || exists(path.join(home, ".qoder")))
+        found.push("qoder");
     return found;
 }
 function asObject(value, label) {
@@ -191,6 +194,30 @@ export function workbuddyConfigPath(env, home, exists) {
         return path.join(legacy, "mcp.json");
     return path.join(current, "mcp.json");
 }
+/**
+ * Qoder 用户级 MCP 配置路径：`QODER_CONFIG_DIR` → `~/.qoder-cn` → `~/.qoder`。
+ *
+ * Qoder 拉起 MCP 子进程时 cwd 是安装目录，所以条目指向 `dist/qoder-launch.js` 适配器，
+ * 由它按会话解析工作区后再钉 `--root`；配置本身同样不钉根，一条服务所有工作区。
+ */
+export function qoderConfigPath(env, home, exists) {
+    if (env.QODER_CONFIG_DIR)
+        return path.join(env.QODER_CONFIG_DIR, "settings.json");
+    const cn = path.join(home, ".qoder-cn");
+    if (exists(cn))
+        return path.join(cn, "settings.json");
+    const intl = path.join(home, ".qoder");
+    if (exists(intl))
+        return path.join(intl, "settings.json");
+    return path.join(cn, "settings.json");
+}
+/** 本包已构建的 Qoder 适配器入口 */
+export function localQoderLaunch() {
+    const entry = fileURLToPath(new URL("../dist/qoder-launch.js", import.meta.url));
+    if (!fs.existsSync(entry) || !fs.lstatSync(entry).isFile())
+        throw new Error("本地入口未构建，请先 npm run build。");
+    return { command: process.execPath, args: [entry] };
+}
 function hasCodexServer(text) {
     return /^\s*\[mcp_servers\.(?:pm-mcp|"pm-mcp")\]\s*$/m.test(text);
 }
@@ -276,6 +303,16 @@ function configureClient(client, options, context, log, projectRoot) {
             log(`[backup] ${backup}`);
         return;
     }
+    if (client === "qoder") {
+        const file = qoderConfigPath(context.env, context.home, context.exists);
+        log(`[${options.dryRun ? "plan" : "write"}] qoder: ${file}`);
+        // 发布版走 `pm-mcp launch` 适配器入口；--local 绑定本包已构建的 dist/qoder-launch.js。
+        const launch = options.local ? localQoderLaunch() : { command: "npx", args: ["-y", PACKAGE_SPEC, "launch"] };
+        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] });
@@ -286,11 +323,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|workbuddy|print] [--project [dir]] [--force] [--dry-run] [--local]`);
+    log(`Usage: npx -y ${PACKAGE_SPEC} setup [--client auto|all|codex|claude|zcode|cursor|vscode|workbuddy|qoder|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("qoder: 写入 <QODER_CONFIG_DIR|~/.qoder-cn>/settings.json，条目指向 qoder-launch 适配器；它按会话取工作区，一条配置服务所有项目。");
     log("升级后运行 pm-mcp doctor --root <项目目录> 核验；现有客户端仍需重新连接。");
 }
 export function runSetup(argv, overrides = {}) {
@@ -360,11 +398,16 @@ export function runSetup(argv, overrides = {}) {
     else if (selected.length === 1 && selected[0] === "workbuddy") {
         log("完成。请在 WorkBuddy 的「连接器管理 → 自定义连接器」中确认信任 pm-mcp，再重开会话调用 get_status 核验。");
     }
+    else if (selected.length === 1 && selected[0] === "qoder") {
+        log("完成。请在 Qoder 里执行 /mcp reload（或重开会话）并确认信任提示，再调用 get_status 核验项目根与解析依据。");
+    }
     else {
         // 多客户端时逐条给出各自的重连/授权要求，避免只提其中一个造成误导。
         const notes = [];
         if (selected.includes("workbuddy"))
             notes.push("WorkBuddy 需在「连接器管理 → 自定义连接器」确认信任 pm-mcp");
+        if (selected.includes("qoder"))
+            notes.push("Qoder 需 /mcp reload 并确认信任");
         if (selected.includes("codex"))
             notes.push("Codex 需完全退出并重启");
         log(notes.length > 0

package/dist/task-evidence.js

@@ -23,12 +23,12 @@ 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 关联实际实现或测试文件。");
+        throw new Error("完成开发/修复任务需要通过 files 关联实际实现或测试文件。请在 update_task 里传 files: [\"src/…\", \"test/…\"]（相对路径）；未验证的功能/杂项任务请改用 type=chore 或 checkpoint 存档。");
     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}`);
+            throw new Error(`任务文件不在源码验证范围内: ${rel}。请改用 src/ 或 test/ 内的相对路径；.pm/、PROJECT.md、文档与 scan_ignore 排除项不能作为任务文件。`);
         }
         for (let index = 0; index < parts.length; index++) {
             const target = path.join(absolute, ...parts.slice(0, index + 1));
@@ -40,7 +40,7 @@ export function verifiedTaskEvidence(root, requested, files = []) {
                 if (error.code !== "ENOENT")
                     throw error;
                 if (!changedGitFiles(absolute).includes(rel))
-                    throw new Error(`任务关联文件不存在，也没有 Git 删除记录: ${rel}`);
+                    throw new Error(`任务关联文件不存在，也没有 Git 删除记录: ${rel}。请核对路径拼写（相对路径、/ 分隔），确认文件真实存在于本仓库。`);
                 break;
             }
             if (stat.isSymbolicLink() || (index === parts.length - 1 ? !stat.isFile() : !stat.isDirectory())) {
@@ -51,7 +51,7 @@ export function verifiedTaskEvidence(root, requested, files = []) {
     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，缺少质量验证报告。");
+            throw new Error("完成开发/修复任务前请执行 run_quality_matrix，缺少质量验证报告。先调用 run_quality_matrix(confirm_execute: true) 生成报告，全绿后再 update_task(done)。");
         const stat = fs.lstatSync(part);
         if (!stat.isDirectory() || stat.isSymbolicLink())
             throw new Error("质量证据目录必须是项目内的普通目录。");
@@ -70,9 +70,9 @@ export function verifiedTaskEvidence(root, requested, files = []) {
     }).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。");
+        throw new Error("缺少质量验证报告，请先执行 run_quality_matrix（confirm_execute: true），全绿后再 update_task(done)。");
     if (requested !== undefined && projectFilePath(requested) !== latest.relative)
-        throw new Error("必须使用最新质量报告，不能绕过后来出现的验证结果。");
+        throw new Error("必须使用最新质量报告，不能绕过后来出现的验证结果。请省略 verification_run 参数（自动选最新），或用最新报告的路径重试。");
     const parsed = reportSchema.safeParse(latest.value);
     if (!parsed.success)
         throw new Error("最新质量报告无效或格式过旧，请重新执行验证。");
@@ -80,7 +80,7 @@ export function verifiedTaskEvidence(root, requested, files = []) {
     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("最新质量验证失败、未执行、输出不完整或存在跳过项，不能标记完成。");
+        throw new Error("最新质量验证失败、未执行、输出不完整或存在跳过项，不能标记完成。请先修复失败原因，重跑 run_quality_matrix 直到全绿，再 update_task(done)。");
     }
     const tests = report.results.filter((item) => item.kind === "test" || item.kind === "coverage");
     if (tests.length === 0 || tests.some((item) => item.output_summary.tests === 0))
@@ -100,11 +100,11 @@ export function verifiedTaskEvidence(root, requested, files = []) {
     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("质量报告的测试单元未覆盖任务关联文件所在目录。");
+        throw new Error("质量报告的测试单元未覆盖任务关联文件所在目录。请把关联文件纳入测试覆盖，或将 files 改为质量报告已覆盖目录内的文件后重试。");
     }
     const current = fingerprintProject(absolute);
     if (current.sha256 !== report.source.after.sha256)
-        throw new Error("质量验证对应的源码已变化，证据过期，请重新验证。");
+        throw new Error("质量验证对应的源码已变化，证据过期，请重新验证。重新执行 run_quality_matrix 刷新证据，全绿后再 update_task(done)。");
     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-tools.js

@@ -10,8 +10,8 @@ import { appendSession } from "./session-log.js";
 import { verifiedTaskEvidence } from "./task-evidence.js";
 import { taskPage, taskPageText, TaskPageSchema } from "./task-pagination.js";
 const stepSchema = z.object({ text: z.string(), done: z.boolean().optional() });
-export function registerTaskTools(server, root) {
-    toolW(server, root, "add_task", "添加任务。长任务务必给 steps（显式步骤清单，断点续做的载体）；走了捷径 type=debt 登记（债务账）；修 bug type=fix。", {
+export function registerTaskTools(server, startupRoot) {
+    toolW(server, startupRoot, "add_task", "添加任务。长任务务必给 steps（显式步骤清单，断点续做的载体）；走了捷径 type=debt 登记（债务账）；修 bug type=fix。", {
         title: z.string().min(1),
         detail: z.string().optional(),
         type: z.enum(["feature", "refactor", "fix", "chore", "debt"]).optional().describe("默认 feature"),
@@ -21,7 +21,8 @@ export function registerTaskTools(server, root) {
         files: z.array(z.string()).optional().describe("关联文件（相对路径）"),
         acceptance: z.string().optional().describe("验收标准"),
         steps: z.array(stepSchema).optional().describe("步骤清单（长任务必填）"),
-    }, (args) => {
+    }, (args, ctx) => {
+        const root = ctx.root;
         requireInitialized(root);
         const roadmap = loadRoadmap(root);
         if (args.milestone && !roadmap.milestones.some((m) => m.id === args.milestone)) {
@@ -59,7 +60,7 @@ export function registerTaskTools(server, root) {
             : "";
         return `✅ 任务 ${id}「${args.title}」已创建（${args.type ?? "feature"}/${args.milestone ?? "无里程碑"}）。${tip}`;
     });
-    toolR(server, root, "list_tasks", "分页列出任务（默认不含 done/cancelled，每页25）。按原过滤条件传 next_cursor 可取下一页；数据变化会使游标失效。文字摘要与结构化分页结果同时返回，不漏掉折叠的中间任务。", {
+    toolR(server, startupRoot, "list_tasks", "分页列出任务（默认不含 done/cancelled，每页25）。按原过滤条件传 next_cursor 可取下一页；数据变化会使游标失效。文字摘要与结构化分页结果同时返回，不漏掉折叠的中间任务。", {
         status: z.enum(["backlog", "todo", "in_progress", "blocked", "done", "cancelled"]).optional(),
         type: z.enum(["feature", "refactor", "fix", "chore", "debt"]).optional(),
         milestone: z.string().optional(),
@@ -67,11 +68,12 @@ export function registerTaskTools(server, root) {
         include_done: z.boolean().optional().describe("默认 false"),
         page_size: z.number().int().min(1).max(100).optional().describe("默认25，受项目输出预算限制"),
         cursor: z.string().min(1).max(1024).optional().describe("上页返回的 next_cursor；保留相同过滤条件"),
-    }, (args) => {
+    }, (args, ctx) => {
+        const root = ctx.root;
         requireInitialized(root);
         return JSON.stringify(taskPage(root, args, budgetLines(root) - 4));
     }, { outputSchema: TaskPageSchema.shape, decode: (value) => { const page = TaskPageSchema.parse(JSON.parse(value)); return { text: taskPageText(page), data: page }; } });
-    toolW(server, root, "update_task", "一次更新任务、checkpoint 与会话。checkpoint 默认记会话；完成时用 record_session:true 一并记录，不再另调 log_session；files 给实际关联文件。feature/fix 转 done 必须有最新成功且源码匹配的测试报告，verification_run 可指明报告。文字 verification 不能代替执行证据。", {
+    toolW(server, startupRoot, "update_task", "一次更新任务、checkpoint 与会话。checkpoint 默认记会话；完成时用 record_session:true 一并记录，不再另调 log_session；files 给实际关联文件。feature/fix 转 done 必须有最新成功且源码匹配的测试报告，verification_run 可指明报告。文字 verification 不能代替执行证据。", {
         id: z.string(),
         status: z.enum(["backlog", "todo", "in_progress", "blocked", "done", "cancelled"]).optional(),
         title: z.string().optional(),
@@ -89,7 +91,8 @@ export function registerTaskTools(server, root) {
         steps: z.array(stepSchema).optional().describe("整体替换步骤清单"),
         step_done: z.number().int().min(1).optional().describe("勾选完成第 N 步"),
         author: z.string().optional(),
-    }, (args, prepared) => {
+    }, (args, ctx, prepared) => {
+        const root = ctx.root;
         requireInitialized(root);
         const data = loadTasks(root);
         const t = data.tasks.find((x) => x.id === args.id);
@@ -174,7 +177,8 @@ export function registerTaskTools(server, root) {
         refreshDerived(root);
         const stepsInfo = t.steps.length > 0 ? `，步骤 ${t.steps.filter((s) => s.done).length}/${t.steps.length}` : "";
         return [`✅ ${t.id} 已更新（${t.status}${stepsInfo}）。`, ...notes].join("\n");
-    }, (args) => {
+    }, (args, ctx) => {
+        const root = ctx.root;
         requireInitialized(root);
         const task = loadTasks(root).tasks.find((item) => item.id === args.id);
         if (!task)
@@ -187,11 +191,12 @@ export function registerTaskTools(server, root) {
         const record = args.record_session ?? (args.checkpoint !== undefined);
         return { evidence, taskSnapshot: JSON.stringify(task), hashes: record ? captureFileHashes(root, args.files ?? []) : {} };
     });
-    toolW(server, root, "checkpoint", "断点存档：长任务做到一半（或上下文快满）时随手保存「当前进度 + 下一步动作」。新会话 get_status 会直接给出恢复点，不用靠回忆。", {
+    toolW(server, startupRoot, "checkpoint", "断点存档：长任务做到一半（或上下文快满）时随手保存「当前进度 + 下一步动作」。新会话 get_status 会直接给出恢复点，不用靠回忆。", {
         task_id: z.string(),
         note: z.string().describe("当前进展到哪了"),
         next_step: z.string().describe("下一个具体动作（新会话从这里续做）"),
-    }, (args) => {
+    }, (args, ctx) => {
+        const root = ctx.root;
         requireInitialized(root);
         const data = loadTasks(root);
         const t = data.tasks.find((x) => x.id === args.task_id);

package/dist/tool-base.js

@@ -1,7 +1,25 @@
+import { z } from "zod";
 import { loadProject } from "./store.js";
 import { IdempotencyKeySchema, runCoalescedRead, runIdempotentWrite, runIdempotentWriteSync } from "./idempotency.js";
 import { drainFoldSavings } from "./budget.js";
 import { estimateTokens, logRuntime, logUsage } from "./usage-log.js";
+import { resolveRequestRoot } from "./caller-workspace.js";
+import { rootResolution } from "./paths.js";
+/** 客户端共用一个常驻服务进程时，启动根只是默认值；每次调用都要重新认领调用方工作区 */
+export function requestContext(tool, args, startupRoot) {
+    const resolution = resolveRequestRoot({
+        tool,
+        args,
+        startupRoot,
+        startupSource: rootResolution()?.source ?? "unknown",
+    });
+    return { root: resolution.root, rootSource: resolution.source, ...(resolution.candidates ? { rootCandidates: resolution.candidates } : {}) };
+}
+/** 无法自动认领工作区时的显式逃生口：任何工具都可以直接指定项目根 */
+const rootOverride = z.string().optional().describe("项目根绝对路径。仅当服务端报告无法确定调用方工作区（root_source 含「未猜测」）时才需要传。");
+function readSchema(schema) {
+    return { ...schema, root: rootOverride };
+}
 /** 工具/资源调用结束后写使用日志（含本次折叠省下的 token 估算）；绝不抛错。 */
 export function recordUsage(root, tool, kind, started, outcome) {
     try {
@@ -25,11 +43,13 @@ export function recordUsage(root, tool, kind, started, outcome) {
     }
 }
 /** 只读工具：跨 Agent/进程合并完全相同的并行请求，短窗复用结果。 */
-export function toolR(server, root, name, description, schema, fn, presentation) {
-    server.registerTool(name, { description, inputSchema: schema, ...(presentation ? { outputSchema: presentation.outputSchema } : {}), annotations: { readOnlyHint: true } }, (async (args) => {
+export function toolR(server, startupRoot, name, description, schema, fn, presentation) {
+    server.registerTool(name, { description, inputSchema: readSchema(schema), ...(presentation ? { outputSchema: presentation.outputSchema } : {}), annotations: { readOnlyHint: true } }, (async (args) => {
+        const ctx = requestContext(name, (args ?? {}), startupRoot);
+        const root = ctx.root;
         const started = Date.now();
         try {
-            const result = await runCoalescedRead(root, presentation ? `${name}:${presentation.cacheVersion ?? "structured-v1"}` : name, args, fn);
+            const result = await runCoalescedRead(root, presentation ? `${name}:${presentation.cacheVersion ?? "structured-v1"}` : name, args, () => fn(args, ctx));
             const decoded = presentation?.decode(result.text);
             const text = decoded?.text ?? result.text;
             recordUsage(root, name, "read", started, {
@@ -53,15 +73,18 @@ const idempotencyDescription = "多 Agent 执行同一业务时传相同 idempot
 function writeSchema(schema) {
     return {
         ...schema,
+        root: rootOverride,
         idempotency_key: IdempotencyKeySchema.optional().describe("跨 Agent 业务幂等键，建议格式 task-id:operation，如 T-123:add-task"),
     };
 }
 /** 同步写工具：业务幂等占位 + 跨进程账本锁覆盖完整读-改-写。 */
-export function toolW(server, root, name, description, schema, fn, prepare) {
+export function toolW(server, startupRoot, name, description, schema, fn, prepare) {
     server.registerTool(name, { description: `${description} ${idempotencyDescription}`, inputSchema: writeSchema(schema), annotations: { readOnlyHint: false } }, ((args) => {
+        const ctx = requestContext(name, (args ?? {}), startupRoot);
+        const root = ctx.root;
         const started = Date.now();
         try {
-            const result = runIdempotentWriteSync(root, name, args, fn, prepare);
+            const result = runIdempotentWriteSync(root, name, args, (value, prepared) => fn(value, ctx, prepared), prepare ? (value) => prepare(value, ctx) : undefined);
             const prefix = result.replayed ? `↩️ 幂等复用 ${result.key}\n` : result.pending ? `⏳ 幂等占位 ${result.key}\n` : "";
             const text = prefix + result.text;
             recordUsage(root, name, "write", started, {
@@ -82,11 +105,13 @@ export function toolW(server, root, name, description, schema, fn, prepare) {
     }));
 }
 /** 已自带内部锁或异步执行的写工具：先跨进程占位，完成后缓存结果。 */
-export function toolI(server, root, name, description, schema, fn) {
+export function toolI(server, startupRoot, name, description, schema, fn) {
     server.registerTool(name, { description: `${description} ${idempotencyDescription}`, inputSchema: writeSchema(schema), annotations: { readOnlyHint: false } }, (async (args) => {
+        const ctx = requestContext(name, (args ?? {}), startupRoot);
+        const root = ctx.root;
         const started = Date.now();
         try {
-            const result = await runIdempotentWrite(root, name, args, fn);
+            const result = await runIdempotentWrite(root, name, args, (value) => fn(value, ctx));
             const prefix = result.replayed ? `↩️ 幂等复用 ${result.key}\n` : result.pending ? `⏳ 幂等占位 ${result.key}\n` : "";
             const text = prefix + result.text;
             recordUsage(root, name, "write-async", started, {

package/dist/typescript-semantic.js

@@ -13,6 +13,18 @@ function scriptKind(rel) {
 function stringValue(node) {
     return node && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) ? node.text : null;
 }
+function insideEvidenceProperty(node) {
+    let current = node;
+    while (current.parent && (ts.isArrayLiteralExpression(current.parent) || ts.isSpreadElement(current.parent))) {
+        current = current.parent;
+    }
+    const parent = current.parent;
+    if (!parent || !ts.isPropertyAssignment(parent))
+        return false;
+    const name = parent.name;
+    const text = ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : undefined;
+    return text !== undefined && /evidence/i.test(text);
+}
 function bindingNames(name) {
     if (ts.isIdentifier(name))
         return [name.text];
@@ -239,16 +251,22 @@ export function analyzeTypeScriptSource(rel, content) {
                 addReference(node, "grpc", firstArgument, 0.86);
         }
         else if (ts.isStringLiteralLike(node)) {
-            const value = node.text;
-            const pathPart = value.split("#", 1)[0].replace(/\\/g, "/");
-            const basename = pathPart.split("/").at(-1) ?? "";
-            // Extension constants such as ".proto" are metadata, not contract links.
-            // Requiring a real basename keeps AST evidence precise while still
-            // accepting both nearby files (service.proto) and relative paths.
-            if (/^[^.\s][^/\s]*\.(?:proto|graphql|gql)$/i.test(basename))
-                addReference(node, "contract", value, 0.98, true);
-            else if (/^[^.\s][^/\s]*(?:openapi|swagger|asyncapi|contracts?|schemas?)[^/\s]*\.(?:ya?ml|json)$/i.test(basename))
-                addReference(node, "contract", value, 0.95, true);
+            // Structured evidence fields (evidenceRef / lastEvidenceRef / evidence: [...]) carry
+            // data payloads pointing at evidence artifacts, not module specifiers; a path value
+            // like "apps/<pkg>/evidence/...-schema.json" must not become a contract link
+            // (upstream report T-095: phantom taiji-beidou-engine -> ai-gateway-service edge).
+            if (!insideEvidenceProperty(node)) {
+                const value = node.text;
+                const pathPart = value.split("#", 1)[0].replace(/\\/g, "/");
+                const basename = pathPart.split("/").at(-1) ?? "";
+                // Extension constants such as ".proto" are metadata, not contract links.
+                // Requiring a real basename keeps AST evidence precise while still
+                // accepting both nearby files (service.proto) and relative paths.
+                if (/^[^.\s][^/\s]*\.(?:proto|graphql|gql)$/i.test(basename))
+                    addReference(node, "contract", value, 0.98, true);
+                else if (/^[^.\s][^/\s]*(?:openapi|swagger|asyncapi|contracts?|schemas?)[^/\s]*\.(?:ya?ml|json)$/i.test(basename))
+                    addReference(node, "contract", value, 0.95, true);
+            }
         }
         else if (ts.isTaggedTemplateExpression(node) && /^(?:gql|graphql)$/.test(expressionPath(node.tag))) {
             addReference(node, "contract", "inline GraphQL", 0.96);

package/dist/version.js

@@ -7,4 +7,4 @@ export const PACKAGE_SPEC = `${metadata.name}@${VERSION}`;
 export const RUNTIME_CONTRACT = "pagination-evidence-v1";
 // 服务器工具目录契约（doctor 与独立巡检 health-check 都以此核对）。
 // 新增/移除 MCP 工具时必须同步更新这里，并用 `pm-mcp probe` 实测复核。
-export const TOOL_CATALOG_SIZE = 52;
+export const TOOL_CATALOG_SIZE = 54;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckychen1993/pm-mcp",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "AI 编码项目的单一事实来源 + 健康台账 MCP 服务（事实来源 / 路线图 / 防幻觉 / 七本账 / 断点续做 / token 经济）",
   "keywords": [
     "mcp",