@luckychen1993/pm-mcp 0.1.5 → 0.4.0

package/dist/index-store.js

@@ -3,9 +3,10 @@ import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { isInitialized } from "./paths.js";
 import { normSep } from "./budget.js";
-import { getIndex, getMeta, setMeta } from "./index-db.js";
+import { ignoreMatcher, projectScanIgnores } from "./scan-policy.js";
+import { freshness, getIndex, getMeta, setMeta } from "./index-db.js";
 import { clearWatcherDirty, coordinateWatcherLeader, markWatcherDirty, watcherIsClean } from "./watcher-coordinator.js";
-export { aggregates, closeIndex, getIndex, getMeta, iterateFileRows, setMeta } from "./index-db.js";
+export { aggregates, closeIndex, freshness, getIndex, getMeta, indexSummary, iterateFileRows, setMeta } from "./index-db.js";
 import { BINARY_EXTS, countLoc, isLockfile, isTestFile, extOf, countSkipLines, needsSkipCount, looksTrivialTest, DEFAULT_IGNORE_DIRS, walkStatEntries, } from "./scan.js";
 /**
  * SQLite 扫描索引（超大项目核心）：
@@ -65,6 +66,7 @@ export function deleteSubtree(db, prefix) {
     db.prepare("DELETE FROM files WHERE rel LIKE ?").run(prefix.replace(/[%_]/g, (c) => "\\" + c) + "/%");
 }
 export function walkRefresh(root, opts = {}) {
+    const scanPolicy = JSON.stringify(projectScanIgnores(root));
     const db = getIndex(root);
     db.exec("CREATE TEMP TABLE IF NOT EXISTS walked(rel TEXT PRIMARY KEY, mtime REAL, size INTEGER)");
     db.exec("DELETE FROM walked");
@@ -152,6 +154,7 @@ export function walkRefresh(root, opts = {}) {
     setMeta(db, "lastWalk", new Date().toISOString());
     setMeta(db, "skippedDeep", String(skippedDeep));
     setMeta(db, "rootPath", path.resolve(root));
+    setMeta(db, "scanPolicy", scanPolicy);
     // 走查刚完成的这一刻索引就是最新的：watcher 模式下立即续心跳，
     // 否则长走查期间（库忙）心跳可能一直写不进，走查一结束就被判"过期"再走一遍
     if (getMeta(db, "mode") === "watcher") {
@@ -167,41 +170,16 @@ export function walkRefresh(root, opts = {}) {
     activeWatchers.get(path.resolve(root))?.reconciled();
     return { totalFiles: total, changed: processed, deleted: Number(del.changes ?? 0), hits: total - processed, skippedDeep };
 }
-const BEAT_STALE_MS = 90_000;
-export function freshness(root) {
-    const db = getIndex(root);
-    const files = db.prepare(`SELECT COUNT(*) c FROM files`).get().c;
-    const lastWalk = getMeta(db, "lastWalk");
-    const lastBeat = getMeta(db, "lastBeat");
-    const mode = (getMeta(db, "mode") ?? "walk");
-    const pending = Number(getMeta(db, "pending") ?? 0);
-    const beatAge = lastBeat ? Date.now() - Date.parse(lastBeat) : Number.POSITIVE_INFINITY;
-    // rootPath 守卫：索引库随项目目录被拷贝/移动时，旧心跳与行集都属于原路径——不可信任
-    const owned = getMeta(db, "rootPath") === path.resolve(root);
-    const lastEvent = getMeta(db, "lastEvent");
-    const eventAge = lastEvent ? Date.now() - Date.parse(lastEvent) : Number.POSITIVE_INFINITY;
-    const watcherSession = getMeta(db, "watcherSession");
-    const sessionReconciled = watcherSession !== null && getMeta(db, "lastWalkSession") === watcherSession;
-    const watcherHealthy = !(getMeta(db, "watcherError") ?? "");
-    const watcherClean = watcherIsClean(root);
-    // 卡死计数自愈：防抖 150ms，若计数>0 但 30s 无任何事件推进，说明计数器失真（如持锁期抛错），不再信任
-    const pendingClean = pending === 0 || eventAge > 30_000;
-    const fresh = files > 0 &&
-        lastWalk !== null &&
-        owned &&
-        mode === "watcher" &&
-        sessionReconciled &&
-        watcherHealthy &&
-        watcherClean &&
-        pendingClean &&
-        beatAge < BEAT_STALE_MS;
-    return { mode, fresh, files, lastWalk, lastBeat, pendingEvents: pending };
-}
+/* ------------------------------ watcher 新鲜度 ------------------------------ */
 /**
  * 确保索引可用：watcher 活跃且心跳新鲜 → 直接用（稳态免走查）；
  * 否则精确全量走查（冷启动/巡检进程/server 未运行时）。
  */
 export function ensureFresh(root) {
+    if (getMeta(getIndex(root), "scanPolicy") !== JSON.stringify(projectScanIgnores(root))) {
+        walkRefresh(root, { forceContent: true });
+        return { used: "walk", freshness: freshness(root) };
+    }
     let f = freshness(root);
     if (!f.fresh && f.mode === "watcher" && f.pendingEvents > 0) {
         // 变更风暴刚过：事件还在防抖队列里。本进程有 watcher 时就地排空（毫秒级），
@@ -248,12 +226,15 @@ export function startWatcher(root) {
     let leader = false;
     let stopped = false;
     let locallyUnhealthy = false;
+    let policy = projectScanIgnores(abs);
+    let customIgnored = ignoreMatcher(policy);
     const active = {
         timers,
         closed: () => stopped || !leader,
-        reconciled: () => { locallyUnhealthy = false; },
+        reconciled: () => { locallyUnhealthy = false; policy = projectScanIgnores(abs); customIgnored = ignoreMatcher(policy); },
     };
-    const ignored = (rel) => DEFAULT_IGNORE_DIRS.has(rel.split("/")[0]) || rel.split("/")[0] === ".pm";
+    const ignored = (rel) => DEFAULT_IGNORE_DIRS.has(rel.split("/")[0]) ||
+        rel.split("/").slice(0, -1).some((part) => DEFAULT_IGNORE_DIRS.has(part)) || customIgnored(rel, true);
     const recordWatcherError = (stage, error) => {
         locallyUnhealthy = true;
         try {
@@ -291,6 +272,12 @@ export function startWatcher(root) {
             return;
         let succeeded = false;
         try {
+            if (ignored(rel)) {
+                deleteFile(db, rel);
+                deleteSubtree(db, rel);
+                succeeded = true;
+                return;
+            }
             const full = path.join(abs, ...rel.split("/"));
             let st;
             try {
@@ -362,11 +349,24 @@ export function startWatcher(root) {
         db = getIndex(abs);
         try {
             watcher = fs.watch(abs, { recursive: true }, (_event, filename) => {
-                if (stopped || !leader || !filename)
+                if (stopped || !leader)
+                    return;
+                if (!filename) {
+                    recordWatcherError("incomplete event", new Error("监视器未提供文件名，需要精确走查恢复索引。"));
                     return;
+                }
                 let rel;
                 try {
                     rel = normSep(String(filename));
+                    if (rel === ".pm/project.json") {
+                        const currentPolicy = projectScanIgnores(abs);
+                        if (JSON.stringify(currentPolicy) !== JSON.stringify(policy)) {
+                            policy = currentPolicy;
+                            customIgnored = ignoreMatcher(policy);
+                            markWatcherDirty(abs);
+                        }
+                        return;
+                    }
                     if (ignored(rel))
                         return;
                 }
@@ -438,13 +438,4 @@ export function startWatcher(root) {
             coordinator.stop();
         } } };
 }
-/** 巡检/诊断用：索引概况一行 */
-export function indexSummary(root) {
-    const f = freshness(root);
-    if (f.files === 0)
-        return "索引：空（未走查）";
-    const age = f.lastWalk ? `，走查于 ${f.lastWalk.slice(0, 16).replace("T", " ")}` : "";
-    const beat = f.fresh ? "，watcher 保鲜中" : `（watcher ${f.mode === "watcher" ? "心跳过期" : "未运行"}，下次审计将全量走查）`;
-    return `索引：${f.files} 文件${age}${beat}`;
-}
 export { isInitialized };

package/dist/index.js

@@ -17,6 +17,9 @@ import { AcceptanceReportSchema } from "./acceptance-report.js";
 import { runCoalescedRead } from "./idempotency.js";
 import { recordUsage } from "./tool-base.js";
 import { logRuntime } from "./usage-log.js";
+import { VERSION } from "./version.js";
+import { taskPage } from "./task-pagination.js";
+import { budgetLines } from "./tool-base.js";
 /* --root 参数 > PM_ROOT 环境变量 > 启动时工作目录 */
 const argv = process.argv.slice(2);
 let explicitRoot;
@@ -25,8 +28,9 @@ for (let i = 0; i < argv.length; i++) {
         explicitRoot = argv[i + 1];
 }
 const root = resolveRoot(explicitRoot);
-const server = new McpServer({ name: "pm-mcp", version: "0.1.5" }, {
+const server = new McpServer({ name: "pm-mcp", version: VERSION }, {
     instructions: [
+        `pm-mcp ${VERSION}。get_status 返回实际运行版本与项目根；配置修改后须重连核验。list_tasks 有 has_more 时保持过滤条件并使用 next_cursor 续取，不能把一页当全量。feature/fix 默认要求 tests_observed，未知计数不冒充测试通过。`,
         "多 Agent 规则：相同业务的所有写工具调用必须携带相同 idempotency_key（建议 task-id:operation）；同键同参数只执行一次，同键不同参数会被拒绝。",
         "完全相同的并行读请求会由服务端合并并复用结果；不要让多个分支重复请求同一工具和参数。",
         "看到“幂等复用”时直接采用首次结果；看到“幂等占位/正在执行”时等待负责该业务的 Agent，不要换键重试。",
@@ -72,20 +76,23 @@ server.registerResource("roadmap", "pm://roadmap", { description: "路线图（
         },
     ],
 }));
-server.registerResource("tasks", "pm://tasks", { description: "任务清单原始数据（tasks.json；超 100 条截断，完整数据用 list_tasks 过滤）" }, async (uri) => ({
+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", () => {
-                const tasks = loadTasks(root).tasks;
+                const data = loadTasks(root);
+                const tasks = data.tasks;
                 // 资源也要守 token 预算：全量 dump 大账本会吃爆上下文（截断后仍是合法 JSON）
                 if (tasks.length <= 100)
                     return JSON.stringify(tasks, null, 2);
-                const shown = tasks.slice(0, 100);
+                const page = taskPage(root, { include_done: true, page_size: 100 }, budgetLines(root) - 4, data);
+                const shown = tasks.slice(0, page.returned);
                 shown.push({
-                    id: `_TRUNCATED_${tasks.length - 100}`,
-                    title: `…另有 ${tasks.length - 100} 个任务已截断，用 list_tasks 按状态/里程碑过滤获取`,
+                    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);
             }),
@@ -156,12 +163,12 @@ server.registerPrompt("end-session", { description: "收工仪式：更新任务
                 type: "text",
                 text: [
                     "收工前依次完成（顺序执行，缺一不可）：",
-                    "1. 完成的任务：update_task 置 done，必须写 result_note（做了什么），feature/fix 类补 verification（用什么测试/命令证明）。",
+                    "1. feature/fix 先执行适用测试，生成最新质量报告；update_task 置 done，给 result_note 与实际 files，record_session=true 可一并归档。",
                     "2. 未完成的任务：checkpoint 保存「进展 + 下一步具体动作」。",
                     "3. 本次落地的功能：register_feature 登记（入口文件 + 测试文件）。",
                     "4. 修过的 bug：log_debug 记录症状/根因/修法/验证。",
                     "5. 走过的捷径：add_task(type=debt) 登记债务，别让它在沉默中腐烂。",
-                    "6. log_session 记录会话摘要与改动文件清单（如实列出，波及面统计靠它）。",
+                    "6. update_task 已返回自动会话编号时，不重复 log_session；否则用 log_session 记录真实改动清单。纯问答不需要另建任务或反复写会话。",
                     "7. 若到达里程碑节点：update_milestone 流转状态；可 snapshot_codebase 拍快照 + audit_structure 对账。",
                 ].join("\n"),
             },

package/dist/knowledge-tools.js

@@ -5,9 +5,11 @@ import { foldLines, normSep } from "./budget.js";
 import { refreshDerived } from "./dashboard.js";
 import { decisionsDir, requireInitialized } from "./paths.js";
 import { formatCodeSearch, searchCode, searchKnowledge } from "./search.js";
-import { loadDebugLog, loadFeatures, loadFileNotes, loadProject, loadSessions, nextId, saveDebugLog, saveFeatures, saveFileNotes, saveSessions, } from "./store.js";
+import { loadDebugLog, loadFeatures, loadFileNotes, loadProject, nextId, saveDebugLog, saveFeatures, saveFileNotes, } from "./store.js";
 import { budgetLines, toolR, toolW } from "./tool-base.js";
 import { now } from "./types.js";
+import { appendSession } from "./session-log.js";
+import { captureFileHashes } from "./git-state.js";
 export function registerFeatureTools(server, root) {
     toolW(server, root, "register_feature", "登记功能（回答「这个项目有哪些功能」）。entry_files=入口文件（漂移对账锚点），test_files=测试文件（测试背书）。", {
         name: z.string().min(1),
@@ -113,28 +115,17 @@ export function registerSessionTools(server, root) {
         files: z.array(z.string()).optional().describe("本次改动/新增/删除的文件（相对路径）"),
         next_steps: z.array(z.string()).optional().describe("留给下次的下一步"),
         author: z.string().optional().describe("署名：zcode / codex / human:名字"),
-    }, (args) => {
+    }, (args, hashes) => {
         requireInitialized(root);
         const project = loadProject(root);
-        const data = loadSessions(root);
-        const id = nextId("S", data.seq, 4);
-        data.seq += 1;
-        data.sessions.push({
-            id,
-            date: now(),
-            author: args.author ?? "",
-            summary: args.summary,
-            files: (args.files ?? []).map(normSep),
-            next_steps: args.next_steps ?? [],
-        });
-        saveSessions(root, data);
+        const id = appendSession(root, args, hashes);
         refreshDerived(root);
         const L = [`✅ 会话 ${id} 已记录，changelog.md 已更新。`];
         if ((args.files ?? []).length > project.budgets.sessionBlastRadius) {
             L.push(`⚠️ 本次波及 ${(args.files ?? []).length} 个文件，超过阈值 ${project.budgets.sessionBlastRadius}——波及面过大，考虑拆任务或立重构任务。`);
         }
         return L.join("\n");
-    });
+    }, (args) => { requireInitialized(root); return captureFileHashes(root, args.files ?? []); });
     toolW(server, root, "log_debug", "记录调试过程：症状 / 根因 / 修法 / 怎么验证的。调试知识账——下次同样的错不用从零猜，search_knowledge 可查。", {
         symptom: z.string().describe("症状：什么现象、报什么错"),
         root_cause: z.string().describe("根因（诊断出的真正原因，不是表面现象）"),

package/dist/language-adapters.js

@@ -1,18 +1,14 @@
 import fs from "node:fs";
 import path from "node:path";
 import { spawn } from "node:child_process";
+import { SCAN_IGNORE_DIRS, ignoreMatcher, projectScanIgnores } from "./scan-policy.js";
 import { parseManifestDependencies } from "./language-dependencies.js";
-const DEFAULT_IGNORE_DIRS = new Set([
-    ".git", ".pm", ".idea", ".vscode", ".venv", "venv", "env", "__pycache__",
-    "node_modules", "dist", "build", "out", "target", ".gradle", ".next", ".nuxt",
-    ".output", ".turbo", "coverage", ".cache",
-]);
-const LANGUAGE_ORDER = [
-    "javascript", "typescript", "python", "go", "rust", "java", "kotlin", "csharp",
-];
+const DEFAULT_IGNORE_DIRS = SCAN_IGNORE_DIRS;
+const LANGUAGE_ORDER = ["javascript", "typescript", "python", "go", "rust", "java", "kotlin", "csharp"];
 const KIND_ORDER = ["test", "build", "lint", "typecheck", "coverage", "security"];
 const DEFAULT_TIMEOUT_MS = 5 * 60_000;
-const DEFAULT_OUTPUT_BYTES = 64 * 1024;
+// 计数汇总（"# tests N"）在输出末尾，只保留头部会把它一起丢掉 → 计数器解析为 null → 验收把实测值判成 -1。
+const DEFAULT_OUTPUT_BYTES = 1024 * 1024;
 function normalize(value) {
     return value.replace(/\\/g, "/");
 }
@@ -258,6 +254,7 @@ export function discoverProjectUnits(root, options = {}) {
     if (!Number.isInteger(maxDepth) || maxDepth < 0)
         throw new Error("maxDepth must be a non-negative integer");
     const ignored = new Set([...DEFAULT_IGNORE_DIRS, ...(options.ignoreDirs ?? [])]);
+    const excluded = ignoreMatcher(projectScanIgnores(repositoryRoot));
     const grouped = new Map();
     const walk = (dir, depth) => {
         if (depth > maxDepth)
@@ -265,6 +262,8 @@ export function discoverProjectUnits(root, options = {}) {
         const entries = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
         for (const entry of entries) {
             const absolute = path.join(dir, entry.name);
+            if (excluded(normalize(path.relative(repositoryRoot, absolute)), entry.isDirectory()))
+                continue;
             if (entry.isDirectory()) {
                 if (!ignored.has(entry.name))
                     walk(absolute, depth + 1);
@@ -403,7 +402,9 @@ async function runOne(item) {
         // shell:false is intentional: arguments never undergo shell parsing.
         let child;
         try {
-            child = spawn(item.command, item.args, { cwd: item.cwd, shell: false, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
+            // Node 测试宿主的内部标记会让子 node --test 直接跳过文件并退出0，不能泄漏给质量命令。
+            const { NODE_TEST_CONTEXT: _nodeTestContext, ...env } = process.env;
+            child = spawn(item.command, item.args, { cwd: item.cwd, env, shell: false, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
         }
         catch (error) {
             const err = error;

package/dist/license.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import { scanExclusionNote } from "./scan-policy.js";
 import path from "node:path";
 import { loadFileNotes, loadProject } from "./store.js";
 import { isTestFile, readDirectDeps } from "./scan.js";
@@ -11,10 +12,11 @@ import { foldLines } from "./budget.js";
  */
 const STRONG_COPYLEFT = ["GPL-2.0", "GPL-3.0", "AGPL-3.0", "SSPL-1.0", "GPL", "AGPL", "SSPL"];
 const WEAK_COPYLEFT = ["LGPL", "MPL-2.0", "MPL", "EPL", "CDDL", "EUPL", "Sleepycat"];
-const PERMISSIVE = ["MIT", "Apache-2.0", "Apache", "BSD-2-Clause", "BSD-3-Clause", "BSD", "ISC", "0BSD", "Unlicense", "Zlib", "Python-2.0", "BSL-1.0"];
+const PERMISSIVE = ["MIT", "Apache-2.0", "Apache", "BSD-2-Clause", "BSD-3-Clause", "BSD", "ISC", "0BSD", "Unlicense", "Zlib", "Python-2.0", "BSL-1.0", "BlueOak-1.0.0"];
 /** 单个包最多登记数（巨型依赖树保护；超出部分计数上报） */
 const MAX_DEPS = 800;
-function classify(license) {
+/** 单个许可标识的判定（不含 SPDX 表达式拆解）。 */
+function classifySingle(license) {
     const l = license.trim();
     if (!l)
         return "unknown";
@@ -31,6 +33,27 @@ function classify(license) {
         return "permissive";
     return "unknown";
 }
+/**
+ * 判定依赖许可证。支持 SPDX 表达式：去掉外层括号后按 OR 拆开，逐项判定并取【最严格】的一项。
+ * 取最严格而非最宽松，是为了不削弱发布门禁：(MIT OR GPL-3.0) 仍判 strong-copyleft；
+ * 只有全部操作数都为宽松许可时（如 (MIT OR WTFPL)）才不再落到 unknown。
+ */
+function classify(license) {
+    const stripped = license.trim().replace(/^\((.*)\)$/u, "$1").trim();
+    if (!stripped)
+        return "unknown";
+    if (/\s+OR\s+/iu.test(stripped)) {
+        const rank = { unknown: 0, permissive: 1, "weak-copyleft": 2, "strong-copyleft": 3 };
+        let worst = "unknown";
+        for (const part of stripped.split(/\s+OR\s+/iu)) {
+            const kind = classifySingle(part.replace(/^\((.*)\)$/u, "$1").trim());
+            if (rank[kind] > rank[worst])
+                worst = kind;
+        }
+        return worst;
+    }
+    return classifySingle(stripped);
+}
 function readPkgLicense(pkgFile) {
     try {
         const pkg = JSON.parse(fs.readFileSync(pkgFile, "utf8"));
@@ -96,6 +119,8 @@ function readNodeLicenses(root) {
         if (!fs.existsSync(nested))
             continue;
         for (const entry of fs.readdirSync(nested, { withFileTypes: true })) {
+            if (entry.name.startsWith("."))
+                continue;
             if (entry.name.startsWith("@") && isDirLike(entry)) {
                 for (const sub of fs.readdirSync(path.join(nested, entry.name), { withFileTypes: true })) {
                     if (isDirLike(sub))
@@ -147,6 +172,7 @@ export function auditLicense(root, maxLines = 150, forceFresh = false, indexPrep
     const declared = project.license || pkgLicense;
     const projectKind = classify(declared);
     const L = [];
+    L.push(...scanExclusionNote(root));
     L.push("## 许可证审计");
     /* ① 项目声明 */
     L.push("");

package/dist/osv.js

@@ -0,0 +1,139 @@
+import fs from "node:fs";
+import path from "node:path";
+import { discoverProjectUnits } from "./language-adapters.js";
+import { foldLines } from "./budget.js";
+/**
+ * OSV.dev 已知漏洞查询（联网，显式确认后才会发起请求）。
+ *
+ * 依赖来源是本地 manifest 解析（discoverProjectUnits），只把「包名/版本/生态」
+ * 三个字段发给 api.osv.dev querybatch；不发送代码、路径或任何项目内容。
+ * 版本为范围声明（^ ~ >=）时按原样精确匹配，可能漏报——在报告中如实声明该边界。
+ */
+const OSV_ENDPOINT = "https://api.osv.dev/v1/querybatch";
+const BATCH_SIZE = 100;
+export function ecosystemFor(parser) {
+    if (parser === "package-json")
+        return "npm";
+    if (parser.startsWith("requirements") || parser.startsWith("pyproject"))
+        return "PyPI";
+    if (parser.startsWith("go-mod"))
+        return "Go";
+    if (parser.startsWith("cargo"))
+        return "crates.io";
+    if (parser.startsWith("maven") || parser.startsWith("gradle"))
+        return "Maven";
+    if (parser.startsWith("msbuild"))
+        return "NuGet";
+    return null;
+}
+/**
+ * npm 生态优先用 package-lock.json 的实装版本：manifest 里的 ^ ~ 范围串发给 OSV
+ * 会被解析到边界之下造成误报（实装版本已在修复线之上也会命中），实装版本才准确。
+ */
+function npmLockVersions(root) {
+    const versions = new Map();
+    try {
+        const lock = JSON.parse(fs.readFileSync(path.join(root, "package-lock.json"), "utf8"));
+        for (const [key, entry] of Object.entries(lock.packages ?? {})) {
+            if (!key.startsWith("node_modules/"))
+                continue;
+            const name = key.slice("node_modules/".length);
+            if (name.length === 0 || name.includes("node_modules/") || typeof entry.version !== "string")
+                continue;
+            if (!versions.has(name))
+                versions.set(name, entry.version);
+        }
+    }
+    catch { /* 无 lockfile 或不可读：退回 manifest 版本并在报告中声明 */ }
+    return versions;
+}
+export function collectOsvQueries(root) {
+    const npmVersions = npmLockVersions(root);
+    const merged = new Map();
+    let skippedUnknownEcosystem = 0;
+    for (const unit of discoverProjectUnits(root)) {
+        for (const dep of unit.dependencies) {
+            const ecosystem = ecosystemFor(dep.parser);
+            if (!ecosystem) {
+                skippedUnknownEcosystem += 1;
+                continue;
+            }
+            const resolved = ecosystem === "npm" ? npmVersions.get(dep.name) : undefined;
+            const version = resolved ?? dep.version;
+            const key = `${dep.name}@${version}@${ecosystem}`;
+            const existing = merged.get(key);
+            if (existing) {
+                if (!existing.sourceManifests.includes(dep.sourceManifest))
+                    existing.sourceManifests.push(dep.sourceManifest);
+            }
+            else
+                merged.set(key, { name: dep.name, version, ecosystem, sourceManifests: [dep.sourceManifest], versionSource: resolved ? "lockfile" : "manifest" });
+        }
+    }
+    return { queries: [...merged.values()].sort((a, b) => a.ecosystem.localeCompare(b.ecosystem) || a.name.localeCompare(b.name)), skippedUnknownEcosystem };
+}
+/** 分批查询 OSV；fetcher 可注入以便测试全程离线。 */
+export async function auditOsv(root, options = {}) {
+    const started = Date.now();
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const fetcher = options.fetcher ?? globalThis.fetch;
+    const { queries } = collectOsvQueries(root);
+    const capped = typeof options.maxPackages === "number" ? queries.slice(0, options.maxPackages) : queries;
+    const batches = Math.ceil(capped.length / BATCH_SIZE);
+    const vulnerablePackages = [];
+    let vulnCount = 0;
+    for (let batch = 0; batch < batches; batch += 1) {
+        const slice = capped.slice(batch * BATCH_SIZE, (batch + 1) * BATCH_SIZE);
+        const response = await fetcher(OSV_ENDPOINT, {
+            method: "POST",
+            headers: { "content-type": "application/json", "user-agent": "pm-mcp-osv (project ledger; reports only package name/version/ecosystem)" },
+            body: JSON.stringify({ queries: slice.map((q) => ({ package: { name: q.name, ecosystem: q.ecosystem }, version: q.version })) }),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok)
+            throw new Error(`OSV 查询失败：HTTP ${response.status}（第 ${batch + 1}/${batches} 批）`);
+        const payload = JSON.parse(await response.text());
+        const results = payload.results ?? [];
+        for (let i = 0; i < slice.length; i += 1) {
+            const vulns = (results[i]?.vulns ?? []).map((v) => ({
+                id: typeof v.id === "string" ? v.id : "UNKNOWN",
+                summary: typeof v.summary === "string" ? v.summary : typeof v.details === "string" ? v.details.slice(0, 160) : "",
+                aliases: Array.isArray(v.aliases) ? v.aliases.filter((a) => typeof a === "string") : [],
+            }));
+            if (vulns.length === 0)
+                continue;
+            vulnerablePackages.push({ ...slice[i], vulns });
+            vulnCount += vulns.length;
+        }
+    }
+    return {
+        queried: capped.length,
+        batches,
+        lockfileVersions: capped.filter((q) => q.versionSource === "lockfile").length,
+        manifestVersions: capped.filter((q) => q.versionSource === "manifest").length,
+        vulnerablePackages,
+        vulnCount,
+        durationMs: Date.now() - started,
+    };
+}
+export function renderOsv(scan, maxLines = 150, skippedUnknownEcosystem = 0) {
+    const lines = [
+        "## OSV 已知漏洞查询（联网完成）",
+        `- 查询: ${scan.queried} 个依赖（${scan.batches} 批，仅发送 包名/版本/生态）· 命中 ${scan.vulnerablePackages.length} 个包 / ${scan.vulnCount} 条漏洞 · 耗时 ${scan.durationMs}ms`,
+    ];
+    for (const finding of scan.vulnerablePackages) {
+        for (const vuln of finding.vulns) {
+            const aliases = vuln.aliases.length > 0 ? `（${vuln.aliases.slice(0, 3).join(", ")}）` : "";
+            lines.push(`- 🚩 ${finding.ecosystem}/${finding.name}@${finding.version} ${vuln.id}${aliases} ${vuln.summary.slice(0, 120)}`);
+        }
+    }
+    if (scan.vulnerablePackages.length === 0)
+        lines.push("- ✅ 未命中已知漏洞");
+    else
+        lines.push(`- ✅ 其余 ${scan.queried - scan.vulnerablePackages.length} 个依赖未命中已知漏洞`);
+    lines.push("> 边界：npm 依赖按 package-lock.json 实装版本查询（" + scan.lockfileVersions + " 个）" +
+        (scan.manifestVersions > 0 ? `；${scan.manifestVersions} 个非 npm 依赖按 manifest 声明版本（范围声明可能不准）` : "") +
+        "；devDependencies 一并计入；结果不写台账，联网由每次调用显式 confirm 门控。" +
+        (skippedUnknownEcosystem > 0 ? ` 未识别生态依赖 ${skippedUnknownEcosystem} 个已跳过。` : ""));
+    return foldLines(lines, { maxLines, hint: "修复后可再次 audit_osv 复核" });
+}

package/dist/probe.js

@@ -0,0 +1,141 @@
+import fs from "node:fs";
+import { spawnSync } from "node:child_process";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { VERSION } from "./version.js";
+/**
+ * 标准 raw tools/list 直连探针。
+ *
+ * 宿主（ZCode/Codex/Cursor）是唯一 MCP client 持有者，不向模型透传原始
+ * `tools/list`；本探针绕过宿主，自己以 MCP client 身份直连服务器进程，
+ * 拿协议线上的原始工具清单，并可与期望表比对（如 Codex allowlist）。
+ */
+export const PROBE_USAGE = "pm-mcp probe [--timeout <毫秒>] [--expect <逗号分隔工具名> | --expect-file <json>] -- <启动 MCP 服务器的命令...>";
+export function parseProbeArgs(argv) {
+    const separator = argv.indexOf("--");
+    const optionArgs = separator >= 0 ? argv.slice(0, separator) : argv;
+    const serverArgs = separator >= 0 ? argv.slice(separator + 1) : [];
+    const options = { command: "", args: [], timeoutMs: 30_000 };
+    let expectSeen = 0;
+    for (let index = 0; index < optionArgs.length; index++) {
+        const arg = optionArgs[index], value = optionArgs[index + 1];
+        if (arg === "--timeout") {
+            const parsed = Number(value);
+            if (!value || !Number.isFinite(parsed) || parsed <= 0)
+                throw new Error(`probe 参数无效: ${arg} ${value ?? "(缺值)"}`);
+            options.timeoutMs = parsed;
+            index++;
+        }
+        else if (arg === "--expect" || arg === "--expect-file") {
+            if (!value)
+                throw new Error(`probe 参数无效: ${arg} (缺值)`);
+            if (++expectSeen > 1)
+                throw new Error("--expect 与 --expect-file 只能用一个。");
+            options.expect = arg === "--expect" ? parseExpectList(value) : readExpectFile(value);
+            index++;
+        }
+        else
+            throw new Error(`probe 参数无效: ${arg}。用法：${PROBE_USAGE}`);
+    }
+    if (separator < 0 || serverArgs.length === 0)
+        throw new Error(`缺少 "-- <服务器启动命令>"。用法：${PROBE_USAGE}`);
+    if (serverArgs.includes("--"))
+        throw new Error("服务器启动命令内部不能再出现 -- 分隔符。");
+    options.command = serverArgs[0];
+    options.args = serverArgs.slice(1);
+    return options;
+}
+function parseExpectList(value) {
+    const names = [...new Set(value.split(",").map((name) => name.trim()).filter(Boolean))];
+    if (names.length === 0)
+        throw new Error("--expect 至少需要一个工具名。");
+    return names;
+}
+/** 期望表接受：字符串数组、上一轮 probe 报告、或 {tools:[名字|{name}]}。 */
+function readExpectFile(file) {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 2 * 1024 * 1024)
+        throw new Error("expect 文件必须为有界普通文件，禁止链接。");
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`expect 文件不是合法 JSON：${error.message}`);
+    }
+    const list = Array.isArray(parsed) ? parsed
+        : Array.isArray(parsed?.tools) ? parsed.tools
+            : undefined;
+    if (!list)
+        throw new Error("expect 文件格式不识别：应为字符串数组、probe 报告或 {tools:[...]}。");
+    const names = [...new Set(list.map((entry) => typeof entry === "string" ? entry : entry?.name)
+            .filter((name) => typeof name === "string" && name.length > 0))];
+    if (names.length === 0)
+        throw new Error("expect 文件里没有可识别的工具名。");
+    return names;
+}
+export async function runProbe(options) {
+    const timeoutMs = options.timeoutMs;
+    const report = { ok: false, command: options.command, args: options.args, toolCount: 0, tools: [], issues: [] };
+    const client = new Client({ name: "pm-mcp-probe", version: VERSION });
+    // env 为覆盖式合并（SDK 先取默认安全白名单再覆盖），供 PM_MCP_HOME 之类的沙箱重定向。
+    const transport = new StdioClientTransport({ command: options.command, args: options.args, stderr: "pipe", env: options.env });
+    try {
+        await client.connect(transport, { timeout: timeoutMs });
+        transport.stderr?.on("data", () => undefined);
+        const info = client.getServerVersion();
+        if (info)
+            report.serverInfo = { name: info.name, version: info.version };
+        const tools = [];
+        let cursor;
+        do {
+            const page = await client.listTools(cursor ? { cursor } : {}, { timeout: timeoutMs });
+            for (const tool of page.tools)
+                tools.push({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema });
+            cursor = page.nextCursor;
+        } while (cursor);
+        report.tools = tools;
+        report.toolCount = tools.length;
+        if (tools.length === 0)
+            report.issues.push("服务器未暴露任何工具。");
+        if (options.expect) {
+            const actual = new Set(tools.map((tool) => tool.name));
+            const expected = [...new Set(options.expect)];
+            const missing = expected.filter((name) => !actual.has(name));
+            const extra = tools.map((tool) => tool.name).filter((name) => !expected.includes(name));
+            report.expect = { expected, missing, extra };
+            if (missing.length > 0)
+                report.issues.push(`服务器未暴露 ${missing.length} 个期望工具: ${missing.join(", ")}`);
+            if (extra.length > 0)
+                report.issues.push(`服务器暴露了 ${extra.length} 个期望之外的工具: ${extra.join(", ")}`);
+        }
+        report.ok = report.issues.length === 0;
+    }
+    catch (error) {
+        report.issues.push(`raw tools/list 探测失败: ${error.message}`);
+    }
+    finally {
+        await client.close().catch(() => undefined);
+        hardKill(transport);
+    }
+    return report;
+}
+/** client.close() 正常会终止子进程；这里兜底清理仍存活的残留，避免夹具/服务器挂死。 */
+function hardKill(transport) {
+    const pid = transport.pid;
+    if (!pid)
+        return;
+    try {
+        process.kill(pid, 0);
+    }
+    catch {
+        return;
+    }
+    try {
+        if (process.platform === "win32")
+            spawnSync("taskkill", ["/PID", String(pid), "/T", "/F"], { windowsHide: true });
+        else
+            process.kill(pid, "SIGKILL");
+    }
+    catch { /* 尽力而为 */ }
+}