@luckychen1993/pm-mcp 0.1.3 → 0.1.5

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,9 @@ 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";
+import { recordUsage } from "./tool-base.js";
+import { logRuntime } from "./usage-log.js";
 /* --root 参数 > PM_ROOT 环境变量 > 启动时工作目录 */
 const argv = process.argv.slice(2);
 let explicitRoot;
@@ -22,7 +25,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.5" }, {
     instructions: [
         "多 Agent 规则：相同业务的所有写工具调用必须携带相同 idempotency_key（建议 task-id:operation）；同键同参数只执行一次，同键不同参数会被拒绝。",
         "完全相同的并行读请求会由服务端合并并复用结果；不要让多个分支重复请求同一工具和参数。",
@@ -39,30 +42,42 @@ function safeText(fn) {
         return `（不可用: ${e.message}）`;
     }
 }
-server.registerResource("dashboard", "pm://dashboard", { description: "项目仪表盘（与仓库根 PROJECT.md 同源），路线图/健康摘要/任务/功能清单" }, (uri) => ({
+async function resourceText(name, fn) {
+    const started = Date.now();
+    try {
+        const text = (await runCoalescedRead(root, `resource:${name}`, {}, () => safeText(fn))).text;
+        recordUsage(root, `resource:${name}`, "read", started, { ok: true, text });
+        return text;
+    }
+    catch (error) {
+        recordUsage(root, `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: 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 +92,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 +224,11 @@ 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（降级为按需全量走查）"}`);
+    logRuntime(root, watcher ? "info" : "warn", watcher ? "watcher.active" : "watcher.unavailable", watcher ? undefined : "降级为按需全量走查");
 }
+logRuntime(root, "info", "server.ready", `pid=${process.pid} node=${process.versions.node}`);
 // stdio 是协议通道，日志只能走 stderr
 console.error(`[pm-mcp] ready. project root: ${root}`);

package/dist/init.js

@@ -3,6 +3,7 @@ import { saveDebugLog, saveFeatures, saveFileNotes, saveProject, saveRoadmap, sa
 import { ensurePmDirs, isInitialized, pmPath } from "./paths.js";
 import { now } from "./types.js";
 import { governancePath, saveGovernance } from "./governance-model.js";
+import { upsertAgentsMd } from "./agents-md.js";
 /** 初始化 .pm/ 状态目录（幂等防护：已初始化则报错） */
 export function initProject(root, input) {
     if (isInitialized(root)) {
@@ -36,5 +37,7 @@ export function initProject(root, input) {
     if (!fs.existsSync(secFile)) {
         fs.writeFileSync(secFile, JSON.stringify({ findings: [], last_scan: null }, null, 2) + "\n", "utf8");
     }
+    // 项目开启即有规矩：AGENTS.md 自动写入（已有则增量合并，绝不覆盖既有内容）
+    upsertAgentsMd(root, input.agentsMd !== false);
     return project;
 }

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*", "usage-log*.jsonl*", "runtime-log*.jsonl*"];
+    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/project-tools.js

@@ -8,6 +8,7 @@ import { loadGovernance } from "./governance-model.js";
 import { loadProject, loadRoadmap, loadSecurity, loadSessions, loadTasks, saveProject, saveRoadmap, } from "./store.js";
 import { now } from "./types.js";
 import { budgetLines, toolI, toolR, toolW } from "./tool-base.js";
+import { renderRuntimeLogLines, renderUsageLogLines } from "./usage-log.js";
 function taskLine(t, withNext = false) {
     const parts = [`[${t.status}]`, t.id, t.title, `(${t.type}${t.milestone ? `,${t.milestone}` : ""})`];
     if (withNext && t.checkpoint) {
@@ -16,7 +17,7 @@ function taskLine(t, withNext = false) {
     return parts.join(" ");
 }
 export function registerProjectTools(server, root) {
-    toolW(server, root, "init_project", "初始化当前项目的 .pm/ 状态目录（单一事实来源）。每个新项目只调用一次；已初始化请用 update_project。", {
+    toolW(server, root, "init_project", "初始化当前项目的 .pm/ 状态目录（单一事实来源），并自动写入 AGENTS.md 工作规矩（已存在则增量合并，不覆盖你的内容）。每个新项目只调用一次；已初始化请用 update_project。", {
         name: z.string().min(1).describe("项目名"),
         description: z.string().optional().describe("一句话描述"),
         stack: z.array(z.string()).optional().describe("技术栈，如 [\"TypeScript\",\"React\"]"),
@@ -24,13 +25,15 @@ export function registerProjectTools(server, root) {
         license: z.string().optional().describe("项目许可证（SPDX 名，如 MIT）"),
         exposure: z.enum(["local", "network", "public"]).optional().describe("暴露面，影响安全告警力度"),
         modules: z.array(z.string()).optional().describe("初始模块登记"),
+        agents_md: z.boolean().optional().describe("默认 true：自动写入/合并 AGENTS.md 工作规矩（false 关闭）"),
     }, (args) => {
-        const project = initProject(root, args);
+        const project = initProject(root, { ...args, agentsMd: args.agents_md });
         refreshDerived(root);
         return [
             `✅ 项目已初始化: ${project.name}`,
             `状态目录: ${pmPath(root, "")}（随 git 提交，团队/AI 共享）`,
             "仪表盘已生成: PROJECT.md",
+            args.agents_md === false ? "AGENTS.md 规矩：按要求跳过（agents_md:false）" : "AGENTS.md 工作规矩已写入（已存在则合并；ZCode 每次打开该项目自动加载）",
             "建议顺序: upsert_module 声明模块/owner/语言 → add_milestone 建里程碑 → add_task 拆任务 → 开工前 get_status / 收工后 log_session。",
         ].join("\n");
     });
@@ -95,6 +98,24 @@ export function registerProjectTools(server, root) {
         L.push("> 三段式定位：本状态 → search_code 精确到行 → 才读具体文件。别全量读代码。");
         return foldLines(L, { maxLines: budgetLines(root) });
     });
+    toolR(server, root, "get_usage_log", "使用日志：pm-mcp 被用了哪些工具、成败、耗时，以及输出 token 估算与「折叠省下的 token」——回答“用它到底省不省 token”。只记工具名与计量，不记参数内容。日志滚动保留约 2MB。", {
+        last: z.number().int().min(1).max(200).optional().describe("返回最近 N 条明细（默认 20；汇总始终覆盖全部保留日志）"),
+        tool: z.string().optional().describe("只看某工具，如 get_status"),
+        ok: z.boolean().optional().describe("true 只看成，false 只看败"),
+        since: z.string().optional().describe("ISO 日期/时间，只看该时间之后的明细"),
+    }, (args) => {
+        requireInitialized(root);
+        return foldLines(renderUsageLogLines(root, args), { maxLines: budgetLines(root) });
+    });
+    toolR(server, root, "get_runtime_log", "运行日志：server 就绪、watcher 状态、工具报错等服务级事件（info/warn/error），判断 pm-mcp 运行是否健康、哪里在反复出错。", {
+        last: z.number().int().min(1).max(200).optional().describe("返回最近 N 条明细（默认 20）"),
+        level: z.enum(["info", "warn", "error"]).optional().describe("只看某级别"),
+        event: z.string().optional().describe("只看某事件，如 tool.error / server.ready"),
+        since: z.string().optional().describe("ISO 日期/时间，只看该时间之后的明细"),
+    }, (args) => {
+        requireInitialized(root);
+        return foldLines(renderRuntimeLogLines(root, args), { maxLines: budgetLines(root) });
+    });
     toolW(server, root, "update_project", "更新项目元信息/预算（描述、技术栈、目标、阶段、模块登记、许可证、暴露面、复杂度与输出预算）。", {
         description: z.string().optional(),
         stack: z.array(z.string()).optional(),

package/dist/search.js

@@ -41,7 +41,7 @@ export function rgSearch(root, query, glob, maxResults, regex) {
     if (regex)
         args.push("-e", query);
     else
-        args.push("-F", query);
+        args.push("-F", "-e", query);
     if (glob)
         args.push("--glob", glob);
     args.push(".");
@@ -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);