@luckychen1993/pm-mcp 0.1.3 → 0.1.4

package/dist/index-store.js

@@ -4,6 +4,7 @@ import { randomUUID } from "node:crypto";
 import { isInitialized } from "./paths.js";
 import { normSep } from "./budget.js";
 import { 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";
 import { BINARY_EXTS, countLoc, isLockfile, isTestFile, extOf, countSkipLines, needsSkipCount, looksTrivialTest, DEFAULT_IGNORE_DIRS, walkStatEntries, } from "./scan.js";
 /**
@@ -160,7 +161,10 @@ export function walkRefresh(root, opts = {}) {
         const watcherSession = getMeta(db, "watcherSession");
         if (watcherSession !== null)
             setMeta(db, "lastWalkSession", watcherSession);
+        setMeta(db, "watcherError", "");
     }
+    clearWatcherDirty(root);
+    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;
@@ -178,6 +182,8 @@ export function freshness(root) {
     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 &&
@@ -185,6 +191,8 @@ export function freshness(root) {
         owned &&
         mode === "watcher" &&
         sessionReconciled &&
+        watcherHealthy &&
+        watcherClean &&
         pendingClean &&
         beatAge < BEAT_STALE_MS;
     return { mode, fresh, files, lastWalk, lastBeat, pendingEvents: pending };
@@ -232,29 +240,71 @@ export function drainWatcher(root) {
  */
 export function startWatcher(root) {
     const abs = path.resolve(root);
-    const db = getIndex(abs);
+    let db = null;
     let pending = 0;
     const timers = new Map();
-    let closed = false;
-    const ignored = (rel) => {
-        const first = rel.split("/")[0];
-        return DEFAULT_IGNORE_DIRS.has(first) || first === ".pm";
+    let watcher = null;
+    let beat = null;
+    let leader = false;
+    let stopped = false;
+    let locallyUnhealthy = false;
+    const active = {
+        timers,
+        closed: () => stopped || !leader,
+        reconciled: () => { locallyUnhealthy = false; },
+    };
+    const ignored = (rel) => DEFAULT_IGNORE_DIRS.has(rel.split("/")[0]) || rel.split("/")[0] === ".pm";
+    const recordWatcherError = (stage, error) => {
+        locallyUnhealthy = true;
+        try {
+            markWatcherDirty(abs);
+        }
+        catch (markerError) {
+            console.error(`[pm-mcp] watcher dirty marker failed: ${markerError instanceof Error ? markerError.message : String(markerError)}`);
+        }
+        console.error(`[pm-mcp] watcher ${stage} failed: ${error instanceof Error ? error.message : String(error)}`);
+        if (!db)
+            return;
+        try {
+            setMeta(db, "watcherError", new Date().toISOString());
+        }
+        catch (metaError) {
+            console.error(`[pm-mcp] watcher error state persistence failed: ${metaError instanceof Error ? metaError.message : String(metaError)}`);
+        }
     };
-    const bumpPending = (d) => {
+    const bumpPending = (d, allowClean = false) => {
         pending = Math.max(0, pending + d);
         try {
-            setMeta(db, "pending", String(pending));
+            if (pending > 0)
+                markWatcherDirty(abs);
+            if (db)
+                setMeta(db, "pending", String(pending));
+            if (pending === 0 && allowClean && !locallyUnhealthy)
+                clearWatcherDirty(abs);
         }
-        catch {
-            /* 库忙时持久化失败无所谓——内存计数仍准，meta 会随后续写收敛 */
+        catch (error) {
+            recordWatcherError("persist pending", error);
         }
     };
     const process = (rel) => {
-        if (closed)
+        if (stopped || !leader || !db)
             return;
+        let succeeded = false;
         try {
             const full = path.join(abs, ...rel.split("/"));
-            const st = fs.statSync(full);
+            let st;
+            try {
+                st = fs.statSync(full);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+                deleteFile(db, rel);
+                deleteSubtree(db, rel);
+                setMeta(db, "lastEvent", new Date().toISOString());
+                succeeded = true;
+                return;
+            }
             if (st.isDirectory()) {
                 // 新目录：补扫该子树（走 walkStatEntries 的 include 限定）
                 for (const e of walkStatEntries(abs, { include: [rel + "/**"] }, () => undefined)) {
@@ -267,107 +317,126 @@ export function startWatcher(root) {
                     return;
                 upsertFile(abs, db, rel, st, computeEntry(abs, rel, st));
             }
+            setMeta(db, "lastEvent", new Date().toISOString());
+            succeeded = true;
         }
-        catch {
-            // 消失了 → 删行
-            try {
-                deleteFile(db, rel);
-                deleteSubtree(db, rel);
-            }
-            catch {
-                /* ignore */
-            }
+        catch (error) {
+            // In particular, SQLITE_BUSY must never be reported as a successful
+            // watcher event. Mark the shared cache unhealthy; the next audit walks.
+            recordWatcherError(`event ${rel}`, error);
         }
         finally {
-            bumpPending(-1);
+            bumpPending(-1, succeeded);
+        }
+    };
+    const deactivateLeader = () => {
+        if (!leader)
+            return;
+        leader = false;
+        if (activeWatchers.get(abs) === active)
+            activeWatchers.delete(abs);
+        if (beat)
+            clearInterval(beat);
+        beat = null;
+        for (const entry of timers.values())
+            clearTimeout(entry.timer);
+        timers.clear();
+        pending = 0;
+        try {
+            watcher?.close();
+        }
+        catch { /* best effort */ }
+        watcher = null;
+        if (db) {
             try {
-                setMeta(db, "lastEvent", new Date().toISOString());
+                setMeta(db, "pending", "0");
+                setMeta(db, "mode", "walk");
             }
-            catch {
-                /* ignore */
+            catch (error) {
+                if (!(error instanceof Error && /database is not open/i.test(error.message)))
+                    recordWatcherError("demotion", error);
             }
         }
     };
-    let watcher;
-    try {
-        watcher = fs.watch(abs, { recursive: true }, (_event, filename) => {
-            if (closed || !filename)
-                return;
-            let rel;
-            try {
-                rel = normSep(String(filename));
-                if (ignored(rel))
+    const activateLeader = () => {
+        db = getIndex(abs);
+        try {
+            watcher = fs.watch(abs, { recursive: true }, (_event, filename) => {
+                if (stopped || !leader || !filename)
                     return;
-            }
-            catch {
-                return;
-            }
-            // 先建定时器再计数：即使计数持久化撞锁抛错，定时器也已就位（否则计数永不归零）
-            const prev = timers.get(rel);
-            if (prev) {
-                clearTimeout(prev.timer);
-                bumpPending(-1);
-            }
-            bumpPending(1);
-            const run = () => {
-                timers.delete(rel);
+                let rel;
                 try {
-                    process(rel);
+                    rel = normSep(String(filename));
+                    if (ignored(rel))
+                        return;
                 }
                 catch {
-                    bumpPending(-1);
+                    return;
                 }
-            };
-            timers.set(rel, { timer: setTimeout(run, 150), due: Date.now() + 150, run });
-        });
-    }
-    catch {
-        setMeta(db, "mode", "walk");
-        return null;
-    }
-    watcher.unref();
-    // 每次 watcher 启动都换一个会话代次。只有本次会话建立后的精确走查
-    // 会把 lastWalkSession 对齐，因此停机窗口内的增删改不可能被旧心跳掩盖。
-    setMeta(db, "watcherSession", randomUUID());
-    setMeta(db, "pending", "0");
-    setMeta(db, "mode", "watcher");
-    let stopped = false;
-    activeWatchers.set(abs, { timers, closed: () => stopped });
-    const beat = setInterval(() => {
-        if (closed)
-            return;
-        try {
-            setMeta(db, "lastBeat", new Date().toISOString());
-        }
-        catch {
-            /* ignore */
+                // 先建定时器再计数：即使计数持久化撞锁抛错，定时器也已就位（否则计数永不归零）
+                const prev = timers.get(rel);
+                if (prev) {
+                    clearTimeout(prev.timer);
+                }
+                else
+                    bumpPending(1);
+                const run = () => {
+                    timers.delete(rel);
+                    try {
+                        process(rel);
+                    }
+                    catch {
+                        bumpPending(-1);
+                    }
+                };
+                timers.set(rel, { timer: setTimeout(run, 150), due: Date.now() + 150, run });
+            });
         }
-    }, 10_000);
-    beat.unref();
-    // 立刻打一次心跳（避免刚启动的 90s 空窗被判不新鲜）
-    setMeta(db, "lastBeat", new Date().toISOString());
-    return {
-        stop() {
-            stopped = true;
-            activeWatchers.delete(abs);
-            closed = true;
-            clearInterval(beat);
-            for (const t of timers.values())
-                clearTimeout(t.timer);
-            try {
-                watcher.close();
-            }
-            catch {
-                /* ignore */
-            }
+        catch (error) {
             try {
                 setMeta(db, "mode", "walk");
             }
-            catch {
-                /* 库可能已被关闭（closeIndex 先行）——telemetry 失败无所谓 */
-            }
-        },
+            catch { /* freshness also requires a live heartbeat */ }
+            recordWatcherError("activation", error);
+            return null;
+        }
+        try {
+            watcher.unref();
+            leader = true;
+            // 每位 leader 都换一个会话代次。强杀/接管之间的停机窗口必须先精确走查。
+            setMeta(db, "watcherSession", randomUUID());
+            setMeta(db, "pending", "0");
+            setMeta(db, "watcherError", "");
+            setMeta(db, "mode", "watcher");
+            setMeta(db, "lastBeat", new Date().toISOString());
+            activeWatchers.set(abs, active);
+            beat = setInterval(() => {
+                if (stopped || !leader || !db)
+                    return;
+                try {
+                    setMeta(db, "lastBeat", new Date().toISOString());
+                    if (!(getMeta(db, "watcherError") ?? "") && watcherIsClean(abs))
+                        locallyUnhealthy = false;
+                }
+                catch (error) {
+                    recordWatcherError("heartbeat", error);
+                }
+            }, 10_000);
+            beat.unref();
+            return deactivateLeader;
+        }
+        catch (error) {
+            deactivateLeader();
+            throw error;
+        }
     };
+    const coordinator = coordinateWatcherLeader(abs, activateLeader, recordWatcherError);
+    if (!coordinator)
+        return null;
+    return { stop() { if (!stopped) {
+            stopped = true;
+            coordinator.stop();
+        } } };
 }
 /** 巡检/诊断用：索引概况一行 */
 export function indexSummary(root) {

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { resolveRoot, isInitialized } from "./paths.js";
+import { resolveRoot, isInitialized, ensurePmRuntimeIgnored } from "./paths.js";
 import { registerAllTools } from "./tools.js";
 import { loadRoadmap, loadTasks } from "./store.js";
 import { renderRoadmap } from "./roadmap.js";
@@ -14,6 +14,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { listAcceptanceBaselines } from "./acceptance-tools.js";
 import { AcceptanceReportSchema } from "./acceptance-report.js";
+import { runCoalescedRead } from "./idempotency.js";
 /* --root 参数 > PM_ROOT 环境变量 > 启动时工作目录 */
 const argv = process.argv.slice(2);
 let explicitRoot;
@@ -22,7 +23,7 @@ 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.3" }, {
+const server = new McpServer({ name: "pm-mcp", version: "0.1.4" }, {
     instructions: [
         "多 Agent 规则：相同业务的所有写工具调用必须携带相同 idempotency_key（建议 task-id:operation）；同键同参数只执行一次，同键不同参数会被拒绝。",
         "完全相同的并行读请求会由服务端合并并复用结果；不要让多个分支重复请求同一工具和参数。",
@@ -39,30 +40,33 @@ function safeText(fn) {
         return `（不可用: ${e.message}）`;
     }
 }
-server.registerResource("dashboard", "pm://dashboard", { description: "项目仪表盘（与仓库根 PROJECT.md 同源），路线图/健康摘要/任务/功能清单" }, (uri) => ({
+async function resourceText(name, fn) {
+    return (await runCoalescedRead(root, `resource:${name}`, {}, () => safeText(fn))).text;
+}
+server.registerResource("dashboard", "pm://dashboard", { description: "项目仪表盘（与仓库根 PROJECT.md 同源），路线图/健康摘要/任务/功能清单" }, async (uri) => ({
     contents: [
         {
             uri: uri.href,
             mimeType: "text/markdown",
-            text: safeText(() => fs.readFileSync(dashboardFile(root), "utf8")),
+            text: await resourceText("dashboard", () => fs.readFileSync(dashboardFile(root), "utf8")),
         },
     ],
 }));
-server.registerResource("roadmap", "pm://roadmap", { description: "路线图（里程碑进度 + 活跃里程碑任务明细）" }, (uri) => ({
+server.registerResource("roadmap", "pm://roadmap", { description: "路线图（里程碑进度 + 活跃里程碑任务明细）" }, async (uri) => ({
     contents: [
         {
             uri: uri.href,
             mimeType: "text/markdown",
-            text: safeText(() => renderRoadmap(loadRoadmap(root).milestones, loadTasks(root).tasks, 2).join("\n")),
+            text: await resourceText("roadmap", () => renderRoadmap(loadRoadmap(root).milestones, loadTasks(root).tasks, 2).join("\n")),
         },
     ],
 }));
-server.registerResource("tasks", "pm://tasks", { description: "任务清单原始数据（tasks.json；超 100 条截断，完整数据用 list_tasks 过滤）" }, (uri) => ({
+server.registerResource("tasks", "pm://tasks", { description: "任务清单原始数据（tasks.json；超 100 条截断，完整数据用 list_tasks 过滤）" }, async (uri) => ({
     contents: [
         {
             uri: uri.href,
             mimeType: "application/json",
-            text: safeText(() => {
+            text: await resourceText("tasks", () => {
                 const tasks = loadTasks(root).tasks;
                 // 资源也要守 token 预算：全量 dump 大账本会吃爆上下文（截断后仍是合法 JSON）
                 if (tasks.length <= 100)
@@ -77,30 +81,30 @@ server.registerResource("tasks", "pm://tasks", { description: "任务清单原
         },
     ],
 }));
-server.registerResource("changelog", "pm://changelog", { description: "变更日志（由 sessions.json 生成的人类可读版本）" }, (uri) => ({
+server.registerResource("changelog", "pm://changelog", { description: "变更日志（由 sessions.json 生成的人类可读版本）" }, async (uri) => ({
     contents: [
         {
             uri: uri.href,
             mimeType: "text/markdown",
-            text: safeText(() => buildChangelog(root)),
+            text: await resourceText("changelog", () => buildChangelog(root)),
         },
     ],
 }));
-server.registerResource("architecture", "pm://architecture", { description: "跨文件/模块/语言治理审计：语义覆盖、依赖边界、接口、循环与质量矩阵" }, (uri) => ({
-    contents: [{ uri: uri.href, mimeType: "text/markdown", text: safeText(() => auditGovernance(root, 150).report) }],
+server.registerResource("architecture", "pm://architecture", { description: "跨文件/模块/语言治理审计：语义覆盖、依赖边界、接口、循环与质量矩阵" }, async (uri) => ({
+    contents: [{ uri: uri.href, mimeType: "text/markdown", text: await resourceText("architecture", () => auditGovernance(root, 150).report) }],
 }));
-server.registerResource("portfolio", "pm://portfolio", { description: "当前项目的组合视图与跨仓依赖/版本风险" }, (uri) => ({
+server.registerResource("portfolio", "pm://portfolio", { description: "当前项目的组合视图与跨仓依赖/版本风险" }, async (uri) => ({
     contents: [{
             uri: uri.href,
             mimeType: "application/json",
-            text: safeText(() => JSON.stringify(buildPortfolioReport({ projects: [loadPortfolioProject(root)], projectsRequested: 1 }), null, 2)),
+            text: await resourceText("portfolio", () => JSON.stringify(buildPortfolioReport({ projects: [loadPortfolioProject(root)], projectsRequested: 1 }), null, 2)),
         }],
 }));
-server.registerResource("acceptance", "pm://acceptance", { description: "标准化产品验收概览：版本化预批准基线与最近一次机器判定报告" }, (uri) => ({
+server.registerResource("acceptance", "pm://acceptance", { description: "标准化产品验收概览：版本化预批准基线与最近一次机器判定报告" }, async (uri) => ({
     contents: [{
             uri: uri.href,
             mimeType: "application/json",
-            text: safeText(() => {
+            text: await resourceText("acceptance", () => {
                 const reportDir = pmPath(root, "acceptance", "reports");
                 let latestReport = null;
                 if (fs.existsSync(reportDir)) {
@@ -209,8 +213,9 @@ await server.connect(new StdioServerTransport());
 // 超大项目核心：server 常驻期间用递归 watcher 持续保鲜 SQLite 索引，
 // audit/快照稳态下免全量走查（失败自动降级为纯走查模式）
 if (isInitialized(root)) {
+    ensurePmRuntimeIgnored(root);
     const watcher = startWatcher(root);
-    console.error(`[pm-mcp] watcher: ${watcher ? "active" : "unavailable（降级为按需全量走查）"}`);
+    console.error(`[pm-mcp] watcher coordinator: ${watcher ? "active（同项目单 leader）" : "unavailable（降级为按需全量走查）"}`);
 }
 // stdio 是协议通道，日志只能走 stderr
 console.error(`[pm-mcp] ready. project root: ${root}`);

package/dist/license.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { loadFileNotes, loadProject } from "./store.js";
 import { isTestFile, readDirectDeps } from "./scan.js";
-import { ensureFresh, getIndex, iterateFileRows } from "./index-store.js";
+import { ensureFresh, getIndex, iterateFileRows, walkRefresh } from "./index-store.js";
 import { readText } from "./search.js";
 import { foldLines } from "./budget.js";
 /**
@@ -130,7 +130,9 @@ function readNodeLicenses(root) {
     return { list, truncated };
 }
 const GPL_HEADER = /GNU (LESSER |AFFERO )?GENERAL PUBLIC LICENSE/i;
-export function auditLicense(root, maxLines = 150) {
+export function auditLicense(root, maxLines = 150, forceFresh = false, indexPrepared = false) {
+    if (forceFresh)
+        walkRefresh(root, { forceContent: true });
     const project = loadProject(root);
     const rootPkg = path.join(root, "package.json");
     let pkgLicense = "";
@@ -207,7 +209,8 @@ export function auditLicense(root, maxLines = 150) {
     /* ③ 可疑许可证头 */
     L.push("");
     L.push("### ③ 源码中的 GPL 家族许可证头（复制带许可证代码的常见痕迹）");
-    ensureFresh(root);
+    if (!forceFresh && !indexPrepared)
+        ensureFresh(root);
     const hits = [];
     for (const row of iterateFileRows(getIndex(root))) {
         const rel = row.rel;
@@ -216,7 +219,7 @@ export function auditLicense(root, maxLines = 150) {
         // 测试文件常内嵌许可证字符串作为 fixture，不参与该启发式（信号针对混入源码的复制代码）
         if (isTestFile(rel))
             continue;
-        const content = readText(root, rel);
+        const content = readText(root, rel, forceFresh);
         if (content === null)
             continue;
         if (GPL_HEADER.test(content.split("\n").slice(0, 40).join("\n")))

package/dist/paths.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import fs from "node:fs";
 import os from "node:os";
+import { randomUUID } from "node:crypto";
 /** 项目根解析顺序：--root 参数 > PM_ROOT 环境变量 > 当前工作目录 */
 export function resolveRoot(explicit) {
     const raw = explicit?.trim() || process.env.PM_ROOT?.trim() || process.cwd();
@@ -48,4 +49,38 @@ export function ensurePmDirs(root) {
     fs.mkdirSync(pmPath(root), { recursive: true });
     fs.mkdirSync(decisionsDir(root), { recursive: true });
     fs.mkdirSync(snapshotsDir(root), { recursive: true });
+    ensurePmRuntimeIgnored(root);
+}
+/** 本机协调/缓存状态必须留在 .pm 内共享，但绝不能进入项目 Git。 */
+export function ensurePmRuntimeIgnored(root) {
+    const directory = pmPath(root);
+    fs.mkdirSync(directory, { recursive: true });
+    fs.mkdirSync(path.join(directory, ".runtime", "idempotency"), { recursive: true });
+    const file = path.join(directory, ".gitignore");
+    const required = [".lock", ".runtime/", "benchmarks/", "index.db*"];
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const current = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+        const lines = current.split(/\r?\n/).map((line) => line.trim());
+        const missing = required.filter((entry) => !lines.includes(entry));
+        if (missing.length === 0)
+            return;
+        const separator = current.length === 0 || current.endsWith("\n") ? "" : "\n";
+        const content = `${current}${separator}${missing.join("\n")}\n`;
+        const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+        fs.writeFileSync(temporary, content, "utf8");
+        try {
+            fs.renameSync(temporary, file);
+        }
+        catch (error) {
+            try {
+                fs.rmSync(temporary, { force: true });
+            }
+            catch { /* best effort */ }
+            const converged = fs.existsSync(file) && required.every((entry) => fs.readFileSync(file, "utf8").split(/\r?\n/).map((line) => line.trim()).includes(entry));
+            if (converged)
+                return;
+            if (attempt === 2)
+                throw error;
+        }
+    }
 }

package/dist/search.js

@@ -74,7 +74,7 @@ let diskReadBytes = 0;
 let cacheHits = 0;
 let contentReadObserver = null;
 /** 读取文本内容：mtime+size 未变走进程缓存（server 常驻，二次搜索/扫描免重读）。返回 null=不可读/二进制。 */
-export function readText(root, rel) {
+export function readText(root, rel, force = false) {
     const abs = path.join(root, rel);
     // 缓存必须按“项目根 + 相对路径”隔离；仅用 rel 会让两个项目在
     // mtime/size 恰好相同时串用彼此内容，安全与许可证扫描会随之失真。
@@ -87,7 +87,7 @@ export function readText(root, rel) {
         return null;
     }
     const hit = contentCache.get(cacheKey);
-    if (hit && hit.mtime === st.mtimeMs && hit.size === st.size) {
+    if (!force && hit && hit.mtime === st.mtimeMs && hit.size === st.size) {
         // LRU touch
         contentCache.delete(cacheKey);
         contentCache.set(cacheKey, hit);

package/dist/security.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { loadExtraRules, loadProject, loadSecurity, saveSecurity } from "./store.js";
 import { latestSnapshot } from "./audit.js";
 import { readDirectDeps } from "./scan.js";
-import { ensureFresh, getIndex, iterateFileRows } from "./index-store.js";
+import { ensureFresh, getIndex, iterateFileRows, walkRefresh } from "./index-store.js";
 import { readText } from "./search.js";
 import { now } from "./types.js";
 const SECRET_PATTERNS = [
@@ -69,7 +69,7 @@ function findSecretRule(value) {
 function fingerprint(ruleId, rel, matched) {
     return createHash("sha1").update(ruleId + "|" + rel + "|" + matched).digest("hex").slice(0, 16);
 }
-function scanDetections(root) {
+function scanDetections(root, forceContent = false, indexPrepared = false) {
     const out = [];
     const rules = [...SECRET_PATTERNS, ...DANGEROUS_PATTERNS];
     // 用户自定义规则
@@ -87,7 +87,8 @@ function scanDetections(root) {
             /* 非法自定义规则跳过 */
         }
     }
-    ensureFresh(root);
+    if (!indexPrepared)
+        ensureFresh(root);
     const db = getIndex(root);
     // .env 类文件存在性检查（是否被 git 提交需人工确认）
     for (const row of iterateFileRows(db, { excludeOversize: false })) {
@@ -109,7 +110,7 @@ function scanDetections(root) {
             continue;
         if (rel.startsWith(".pm/"))
             continue;
-        const content = readText(root, rel);
+        const content = readText(root, rel, forceContent);
         if (content === null)
             continue;
         const lines = content.split("\n");
@@ -134,11 +135,19 @@ function scanDetections(root) {
     }
     return out;
 }
+/** 昂贵的全仓扫描阶段；调用方可在账本锁外完成，再把脱敏发现提交到账本。 */
+export function prepareSecurityAudit(root, options = {}) {
+    const forceIndex = options.forceIndex ?? true;
+    const forceContent = options.forceContent ?? true;
+    if (forceIndex)
+        walkRefresh(root, { forceContent: true });
+    return { detections: scanDetections(root, forceContent, forceIndex || options.indexPrepared === true) };
+}
 /** 扫描并更新台账（幂等：重复扫描不产生重复条目） */
-export function auditSecurity(root) {
+export function auditSecurity(root, prepared) {
     const project = loadProject(root);
     const stamp = now();
-    const detections = scanDetections(root);
+    const detections = prepared?.detections ?? scanDetections(root);
     const security = loadSecurity(root);
     const existing = new Map(security.findings.map((f) => [f.fingerprint, f]));
     const acceptedRefound = [];

package/dist/setup.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
-export const PACKAGE_SPEC = "@luckychen1993/pm-mcp@0.1.3";
+export const PACKAGE_SPEC = "@luckychen1993/pm-mcp@0.1.4";
 export const SERVER_NAME = "pm-mcp";
 const CLIENTS = ["codex", "claude", "zcode", "cursor", "vscode"];
 export function parseSetupArgs(argv) {