@luckychen1993/pm-mcp 0.1.1

package/dist/index-store.js

@@ -0,0 +1,381 @@
+import fs from "node:fs";
+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";
+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";
+/**
+ * SQLite 扫描索引（超大项目核心）：
+ * - .pm/index.db 取代 index.json：增量 upsert 而非全量重写（10M 行 JSON 会膨胀到 GB 级）
+ * - 索引是可重建的缓存（.gitignore 它），账本仍走 git 友好的 JSON——两者是两回事
+ * - 走查 = temp 表集合 diff：未变更文件不重读内容（与旧 JSON 索引同语义）
+ * - 聚合全部走 SQL：避免把大规模索引整体物化进 JS 内存
+ * - watcher 活跃时索引持续保鲜，audit/快照可免走查（见 ensureFresh）
+ */
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+/** 读单个文件内容并计算索引字段（watcher 与走查共用同一条语义） */
+export function computeEntry(root, rel, stat) {
+    const ext = extOf(rel);
+    const lock = isLockfile(rel);
+    const isTest = isTestFile(rel);
+    if (BINARY_EXTS.has(ext) || lock) {
+        return { loc: 0, skip: 0, trivial: false, oversize: false, contentOk: false };
+    }
+    if (stat.size > MAX_FILE_BYTES) {
+        return { loc: 0, skip: 0, trivial: false, oversize: true, contentOk: false };
+    }
+    try {
+        const content = fs.readFileSync(path.join(root, ...rel.split("/")), "utf8");
+        if (content.includes("\0"))
+            return { loc: 0, skip: 0, trivial: false, oversize: false, contentOk: false };
+        return {
+            loc: countLoc(content),
+            skip: needsSkipCount(rel, isTest) ? countSkipLines(content) : 0,
+            trivial: isTest && looksTrivialTest(content),
+            oversize: false,
+            contentOk: true,
+        };
+    }
+    catch {
+        return { loc: 0, skip: 0, trivial: false, oversize: false, contentOk: false };
+    }
+}
+function topOf(rel) {
+    const parts = rel.split("/");
+    if (parts.length <= 1)
+        return ".";
+    return parts.slice(0, Math.min(2, parts.length - 1)).join("/");
+}
+export function upsertFile(root, db, rel, stat, entry) {
+    const parts = rel.split("/");
+    db.prepare(`INSERT INTO files(rel,top,root1,dir,ext,is_test,is_lock,mtime,size,loc,skip,trivial,oversize,content_ok)
+     VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+     ON CONFLICT(rel) DO UPDATE SET top=excluded.top,root1=excluded.root1,dir=excluded.dir,ext=excluded.ext,
+       is_test=excluded.is_test,is_lock=excluded.is_lock,mtime=excluded.mtime,size=excluded.size,
+       loc=excluded.loc,skip=excluded.skip,trivial=excluded.trivial,oversize=excluded.oversize,
+       content_ok=excluded.content_ok`).run(rel, topOf(rel), parts.length > 1 ? parts[0] : ".", parts.slice(0, -1).join("/") || ".", extOf(rel), isTestFile(rel) ? 1 : 0, isLockfile(rel) ? 1 : 0, stat.mtimeMs, stat.size, entry.loc, entry.skip, entry.trivial ? 1 : 0, entry.oversize ? 1 : 0, entry.contentOk ? 1 : 0);
+}
+export function deleteFile(db, rel) {
+    db.prepare("DELETE FROM files WHERE rel=?").run(rel);
+}
+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 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");
+    const ins = db.prepare("INSERT OR REPLACE INTO walked VALUES(?,?,?)");
+    let total = 0;
+    let batch = [];
+    const flush = () => {
+        if (batch.length === 0)
+            return;
+        db.exec("BEGIN");
+        for (const b of batch)
+            ins.run(...b);
+        db.exec("COMMIT");
+        batch = [];
+    };
+    let skippedDeep = 0;
+    for (const e of walkStatEntries(root, opts, () => (skippedDeep += 1))) {
+        total += 1;
+        batch.push([e.rel, e.mtime, e.size]);
+        if (batch.length >= 2000)
+            flush();
+    }
+    flush();
+    const changedSql = opts.forceContent
+        ? `SELECT w.rel AS rel, w.mtime AS mtime, w.size AS size FROM walked w
+       WHERE w.rel > ? ORDER BY w.rel LIMIT ?`
+        : `SELECT w.rel AS rel, w.mtime AS mtime, w.size AS size FROM walked w
+       LEFT JOIN files f ON f.rel = w.rel
+       WHERE w.rel > ? AND (f.rel IS NULL OR f.mtime <> w.mtime OR f.size <> w.size)
+       ORDER BY w.rel LIMIT ?`;
+    const changedStmt = db.prepare(changedSql);
+    let processed = 0;
+    const upsertStmt = db.prepare(`INSERT INTO files(rel,top,root1,dir,ext,is_test,is_lock,mtime,size,loc,skip,trivial,oversize,content_ok)
+     VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+     ON CONFLICT(rel) DO UPDATE SET top=excluded.top,root1=excluded.root1,dir=excluded.dir,ext=excluded.ext,
+       is_test=excluded.is_test,is_lock=excluded.is_lock,mtime=excluded.mtime,size=excluded.size,
+       loc=excluded.loc,skip=excluded.skip,trivial=excluded.trivial,oversize=excluded.oversize,
+       content_ok=excluded.content_ok`);
+    let upBatch = [];
+    const flushUp = () => {
+        if (upBatch.length === 0)
+            return;
+        db.exec("BEGIN");
+        for (const r of upBatch) {
+            upsertStmt.run(r.rel, r.top, r.root1, r.dir, r.ext, r.isTest, r.isLock, r.mtime, r.size, r.loc, r.skip, r.trivial, r.oversize, r.contentOk);
+        }
+        db.exec("COMMIT");
+        upBatch = [];
+    };
+    // 游标分页而不是 .all() 物化全部变更行；20GiB/百万文件首次走查也只保留一批。
+    let changedCursor = "";
+    while (true) {
+        const changedRows = changedStmt.all(changedCursor, 500);
+        if (changedRows.length === 0)
+            break;
+        for (const row of changedRows) {
+            const rel = row.rel;
+            const statLike = { mtimeMs: row.mtime, size: row.size };
+            const entry = computeEntry(root, rel, statLike);
+            const parts = rel.split("/");
+            upBatch.push({
+                rel,
+                top: topOf(rel),
+                root1: parts.length > 1 ? parts[0] : ".",
+                dir: parts.slice(0, -1).join("/") || ".",
+                ext: extOf(rel),
+                isTest: isTestFile(rel) ? 1 : 0,
+                isLock: isLockfile(rel) ? 1 : 0,
+                mtime: row.mtime,
+                size: row.size,
+                loc: entry.loc,
+                skip: entry.skip,
+                trivial: entry.trivial ? 1 : 0,
+                oversize: entry.oversize ? 1 : 0,
+                contentOk: entry.contentOk ? 1 : 0,
+            });
+            processed += 1;
+            if (upBatch.length >= 500)
+                flushUp();
+        }
+        changedCursor = changedRows[changedRows.length - 1].rel;
+    }
+    flushUp();
+    const del = db.prepare(`DELETE FROM files WHERE rel NOT IN (SELECT rel FROM walked)`).run();
+    setMeta(db, "lastWalk", new Date().toISOString());
+    setMeta(db, "skippedDeep", String(skippedDeep));
+    setMeta(db, "rootPath", path.resolve(root));
+    // 走查刚完成的这一刻索引就是最新的：watcher 模式下立即续心跳，
+    // 否则长走查期间（库忙）心跳可能一直写不进，走查一结束就被判"过期"再走一遍
+    if (getMeta(db, "mode") === "watcher") {
+        setMeta(db, "lastBeat", new Date().toISOString());
+        // watcher 心跳只能证明“现在有人监听”，不能证明它覆盖了进程停机期间的改动。
+        // 将精确走查绑定到本次 watcher 会话；下次进程启动会换代，旧索引因而必须先对账。
+        const watcherSession = getMeta(db, "watcherSession");
+        if (watcherSession !== null)
+            setMeta(db, "lastWalkSession", watcherSession);
+    }
+    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;
+    // 卡死计数自愈：防抖 150ms，若计数>0 但 30s 无任何事件推进，说明计数器失真（如持锁期抛错），不再信任
+    const pendingClean = pending === 0 || eventAge > 30_000;
+    const fresh = files > 0 &&
+        lastWalk !== null &&
+        owned &&
+        mode === "watcher" &&
+        sessionReconciled &&
+        pendingClean &&
+        beatAge < BEAT_STALE_MS;
+    return { mode, fresh, files, lastWalk, lastBeat, pendingEvents: pending };
+}
+/**
+ * 确保索引可用：watcher 活跃且心跳新鲜 → 直接用（稳态免走查）；
+ * 否则精确全量走查（冷启动/巡检进程/server 未运行时）。
+ */
+export function ensureFresh(root) {
+    let f = freshness(root);
+    if (!f.fresh && f.mode === "watcher" && f.pendingEvents > 0) {
+        // 变更风暴刚过：事件还在防抖队列里。本进程有 watcher 时就地排空（毫秒级），
+        // 免得为几十个文件的变更回退一次全量走查（分钟级）
+        if (drainWatcher(root))
+            f = freshness(root);
+    }
+    if (f.fresh)
+        return { used: "watcher", freshness: f };
+    walkRefresh(root);
+    return { used: "walk", freshness: freshness(root) };
+}
+const activeWatchers = new Map();
+/**
+ * 就地排空本进程 watcher 的事件队列：把已排队的防抖定时器立即执行。
+ * 场景：变更风暴后紧接着调 audit——事件本要 150ms 后才消化、pending>0 导致回退全量走查；
+ * 排空后索引立即反映全部变更，审计直接走 SQL。返回是否发生排空。
+ */
+export function drainWatcher(root) {
+    const w = activeWatchers.get(path.resolve(root));
+    if (!w || w.closed())
+        return false;
+    let drained = 0;
+    for (const [, entry] of [...w.timers]) {
+        clearTimeout(entry.timer);
+        entry.run();
+        drained += 1;
+    }
+    return drained > 0;
+}
+/**
+ * 递归 watcher（Windows 原生 ReadDirectoryChangesW，单调用监视全树）持续维护索引。
+ * - 事件防抖 150ms；新增目录补扫子树；删除事件清行
+ * - 每 30s 写心跳；unref 保证 server 随 stdio 关闭退出
+ * - 失败（网络盘/权限）静默降级为纯走查模式（freshness.mode=walk）
+ */
+export function startWatcher(root) {
+    const abs = path.resolve(root);
+    const db = getIndex(abs);
+    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";
+    };
+    const bumpPending = (d) => {
+        pending = Math.max(0, pending + d);
+        try {
+            setMeta(db, "pending", String(pending));
+        }
+        catch {
+            /* 库忙时持久化失败无所谓——内存计数仍准，meta 会随后续写收敛 */
+        }
+    };
+    const process = (rel) => {
+        if (closed)
+            return;
+        try {
+            const full = path.join(abs, ...rel.split("/"));
+            const st = fs.statSync(full);
+            if (st.isDirectory()) {
+                // 新目录：补扫该子树（走 walkStatEntries 的 include 限定）
+                for (const e of walkStatEntries(abs, { include: [rel + "/**"] }, () => undefined)) {
+                    const st2 = fs.statSync(path.join(abs, ...e.rel.split("/")));
+                    upsertFile(abs, db, e.rel, st2, computeEntry(abs, e.rel, st2));
+                }
+            }
+            else if (st.isFile()) {
+                if (ignored(rel))
+                    return;
+                upsertFile(abs, db, rel, st, computeEntry(abs, rel, st));
+            }
+        }
+        catch {
+            // 消失了 → 删行
+            try {
+                deleteFile(db, rel);
+                deleteSubtree(db, rel);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        finally {
+            bumpPending(-1);
+            try {
+                setMeta(db, "lastEvent", new Date().toISOString());
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    };
+    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))
+                    return;
+            }
+            catch {
+                return;
+            }
+            // 先建定时器再计数：即使计数持久化撞锁抛错，定时器也已就位（否则计数永不归零）
+            const prev = timers.get(rel);
+            if (prev) {
+                clearTimeout(prev.timer);
+                bumpPending(-1);
+            }
+            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 });
+        });
+    }
+    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 */
+        }
+    }, 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 */
+            }
+            try {
+                setMeta(db, "mode", "walk");
+            }
+            catch {
+                /* 库可能已被关闭（closeIndex 先行）——telemetry 失败无所谓 */
+            }
+        },
+    };
+}
+/** 巡检/诊断用：索引概况一行 */
+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

@@ -0,0 +1,210 @@
+#!/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 { registerAllTools } from "./tools.js";
+import { loadRoadmap, loadTasks } from "./store.js";
+import { renderRoadmap } from "./roadmap.js";
+import { buildChangelog } from "./dashboard.js";
+import { dashboardFile, pmPath } from "./paths.js";
+import { startWatcher } from "./index-store.js";
+import { auditGovernance } from "./governance-audit.js";
+import { buildPortfolioReport, loadPortfolioProject } from "./portfolio.js";
+import fs from "node:fs";
+import path from "node:path";
+import { listAcceptanceBaselines } from "./acceptance-tools.js";
+import { AcceptanceReportSchema } from "./acceptance-report.js";
+/* --root 参数 > PM_ROOT 环境变量 > 启动时工作目录 */
+const argv = process.argv.slice(2);
+let explicitRoot;
+for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--root" && argv[i + 1])
+        explicitRoot = argv[i + 1];
+}
+const root = resolveRoot(explicitRoot);
+const server = new McpServer({ name: "pm-mcp", version: "0.1.1" });
+registerAllTools(server, root);
+/* -------------------------------- Resources ------------------------------- */
+function safeText(fn) {
+    try {
+        return fn();
+    }
+    catch (e) {
+        return `（不可用: ${e.message}）`;
+    }
+}
+server.registerResource("dashboard", "pm://dashboard", { description: "项目仪表盘（与仓库根 PROJECT.md 同源），路线图/健康摘要/任务/功能清单" }, (uri) => ({
+    contents: [
+        {
+            uri: uri.href,
+            mimeType: "text/markdown",
+            text: safeText(() => fs.readFileSync(dashboardFile(root), "utf8")),
+        },
+    ],
+}));
+server.registerResource("roadmap", "pm://roadmap", { description: "路线图（里程碑进度 + 活跃里程碑任务明细）" }, (uri) => ({
+    contents: [
+        {
+            uri: uri.href,
+            mimeType: "text/markdown",
+            text: safeText(() => renderRoadmap(loadRoadmap(root).milestones, loadTasks(root).tasks, 2).join("\n")),
+        },
+    ],
+}));
+server.registerResource("tasks", "pm://tasks", { description: "任务清单原始数据（tasks.json；超 100 条截断，完整数据用 list_tasks 过滤）" }, (uri) => ({
+    contents: [
+        {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: safeText(() => {
+                const tasks = loadTasks(root).tasks;
+                // 资源也要守 token 预算：全量 dump 大账本会吃爆上下文（截断后仍是合法 JSON）
+                if (tasks.length <= 100)
+                    return JSON.stringify(tasks, null, 2);
+                const shown = tasks.slice(0, 100);
+                shown.push({
+                    id: `_TRUNCATED_${tasks.length - 100}`,
+                    title: `…另有 ${tasks.length - 100} 个任务已截断，用 list_tasks 按状态/里程碑过滤获取`,
+                });
+                return JSON.stringify(shown, null, 2);
+            }),
+        },
+    ],
+}));
+server.registerResource("changelog", "pm://changelog", { description: "变更日志（由 sessions.json 生成的人类可读版本）" }, (uri) => ({
+    contents: [
+        {
+            uri: uri.href,
+            mimeType: "text/markdown",
+            text: safeText(() => buildChangelog(root)),
+        },
+    ],
+}));
+server.registerResource("architecture", "pm://architecture", { description: "跨文件/模块/语言治理审计：语义覆盖、依赖边界、接口、循环与质量矩阵" }, (uri) => ({
+    contents: [{ uri: uri.href, mimeType: "text/markdown", text: safeText(() => auditGovernance(root, 150).report) }],
+}));
+server.registerResource("portfolio", "pm://portfolio", { description: "当前项目的组合视图与跨仓依赖/版本风险" }, (uri) => ({
+    contents: [{
+            uri: uri.href,
+            mimeType: "application/json",
+            text: safeText(() => JSON.stringify(buildPortfolioReport({ projects: [loadPortfolioProject(root)], projectsRequested: 1 }), null, 2)),
+        }],
+}));
+server.registerResource("acceptance", "pm://acceptance", { description: "标准化产品验收概览：版本化预批准基线与最近一次机器判定报告" }, (uri) => ({
+    contents: [{
+            uri: uri.href,
+            mimeType: "application/json",
+            text: safeText(() => {
+                const reportDir = pmPath(root, "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(root), latest_report: latestReport }, null, 2);
+            }),
+        }],
+}));
+/* --------------------------------- Prompts -------------------------------- */
+server.registerPrompt("start-session", { description: "开工仪式：恢复项目上下文，从断点续做，不靠回忆。" }, () => ({
+    messages: [
+        {
+            role: "user",
+            content: {
+                type: "text",
+                text: [
+                    "按以下顺序恢复项目上下文（本项目由 pm-mcp 管理，状态以 .pm/ 为准，不要凭记忆陈述）：",
+                    "1. 调用 get_status：了解阶段、里程碑进度、进行中任务及其 checkpoint 下一步。",
+                    "2. 若要动的模块不清楚，先 search_code 定位到具体文件与行，再读文件——三段式定位，不要全量读代码。",
+                    "3. 陈述本次计划：要做哪个任务、动哪些文件、验收标准是什么。",
+                    "4. 过程纪律：走捷径就 add_task(type=debt) 登记债务；修 bug 完成后 log_debug 记根因；长任务随手 checkpoint。",
+                ].join("\n"),
+            },
+        },
+    ],
+}));
+server.registerPrompt("end-session", { description: "收工仪式：更新任务与里程碑、留断点、记会话——把本次上下文写回仓库。" }, () => ({
+    messages: [
+        {
+            role: "user",
+            content: {
+                type: "text",
+                text: [
+                    "收工前依次完成（顺序执行，缺一不可）：",
+                    "1. 完成的任务：update_task 置 done，必须写 result_note（做了什么），feature/fix 类补 verification（用什么测试/命令证明）。",
+                    "2. 未完成的任务：checkpoint 保存「进展 + 下一步具体动作」。",
+                    "3. 本次落地的功能：register_feature 登记（入口文件 + 测试文件）。",
+                    "4. 修过的 bug：log_debug 记录症状/根因/修法/验证。",
+                    "5. 走过的捷径：add_task(type=debt) 登记债务，别让它在沉默中腐烂。",
+                    "6. log_session 记录会话摘要与改动文件清单（如实列出，波及面统计靠它）。",
+                    "7. 若到达里程碑节点：update_milestone 流转状态；可 snapshot_codebase 拍快照 + audit_structure 对账。",
+                ].join("\n"),
+            },
+        },
+    ],
+}));
+server.registerPrompt("onboard", { description: "入职简报工作流：引导客户端为新成员（人或 AI）生成项目现状一页纸。" }, () => ({
+    messages: [
+        {
+            role: "user",
+            content: {
+                type: "text",
+                text: [
+                    "为新加入的成员（人或 AI）生成入职简报，数据全部来自 .pm/ 状态，不要编造：",
+                    "1. 读 pm://dashboard（或 PROJECT.md）：项目是什么、路线图到哪、健康状态如何。",
+                    "2. list_decisions + 阅读最近 3 条 ADR：理解关键取舍的「为什么」。",
+                    "3. list_features：了解已有功能地图与各功能入口文件。",
+                    "4. get_status：当前焦点与断点。",
+                    "5. 读 pm://architecture 与 pm://portfolio：模块 owner、公开接口、跨语言质量矩阵和跨仓版本风险。",
+                    "输出一页纸简报：项目一句话 / 技术栈与模块 / 路线图现状 / 关键决策与红线 / 模块与接口边界 / 当前焦点与下一步 / 哪里有坑（债务、安全、语义与跨仓风险）。",
+                ].join("\n"),
+            },
+        },
+    ],
+}));
+server.registerPrompt("architecture-review", { description: "跨文件/模块/语言架构评审：先取证，再判断影响和门禁。" }, () => ({
+    messages: [{
+            role: "user",
+            content: {
+                type: "text",
+                text: [
+                    "按证据完成跨模块/跨语言架构评审：",
+                    "1. 读取 pm://architecture 或调用 audit_governance，先检查语义覆盖、unresolved、owner、私有接口、循环和边界违规。",
+                    "2. 对本次变更调用 impact_analysis，列出反向依赖文件与模块；未知文件不得忽略。",
+                    "3. 调用 plan_quality_matrix；这一步只是计划，不能声称测试通过。",
+                    "4. 只有用户明确要求执行时才调用 run_quality_matrix(confirm_execute=true)，并分别报告每种语言的真实结果。",
+                    "5. 跨仓变更读取 pm://portfolio，核对依赖目标、版本约束、加载失败与仓库循环。",
+                ].join("\n"),
+            },
+        }],
+}));
+server.registerPrompt("acceptance-review", { description: "标准化终验：冻结质量基线后执行证据核验，不能把开发者自测冒充认证。" }, () => ({
+    messages: [{
+            role: "user",
+            content: {
+                type: "text",
+                text: [
+                    "按 pm-mcp 的标准化验收闭环执行，不得事后调低阈值：",
+                    "1. list_acceptance_baselines 并读取目标基线，确认 ISO/IEC 25010 九特性适用性、量化指标、风险和测试双向追踪。",
+                    "2. 只有产品负责人审阅 draft fingerprint 后，才能 approve_acceptance_baseline；批准后的同版本不可修改。",
+                    "3. 执行基线定义的质量、治理、性能与安全测试；失败、跳过、缺工具和过期证据都不得写成通过。",
+                    "4. evaluate_acceptance 会重算项目内证据 SHA-256，并由机器生成不可覆盖的 JSON/Markdown 报告。",
+                    "5. 分开陈述：第一方范围内验收、独立评价、托管 CI、生产证据和 ISO 认证；任何一层都不能冒充另一层。",
+                ].join("\n"),
+            },
+        }],
+}));
+/* ---------------------------------- 启动 ---------------------------------- */
+await server.connect(new StdioServerTransport());
+// 超大项目核心：server 常驻期间用递归 watcher 持续保鲜 SQLite 索引，
+// audit/快照稳态下免全量走查（失败自动降级为纯走查模式）
+if (isInitialized(root)) {
+    const watcher = startWatcher(root);
+    console.error(`[pm-mcp] watcher: ${watcher ? "active" : "unavailable（降级为按需全量走查）"}`);
+}
+// stdio 是协议通道，日志只能走 stderr
+console.error(`[pm-mcp] ready. project root: ${root}`);

package/dist/init.js

@@ -0,0 +1,40 @@
+import fs from "node:fs";
+import { saveDebugLog, saveFeatures, saveFileNotes, saveProject, saveRoadmap, saveSessions, saveTasks, } from "./store.js";
+import { ensurePmDirs, isInitialized, pmPath } from "./paths.js";
+import { now } from "./types.js";
+import { governancePath, saveGovernance } from "./governance-model.js";
+/** 初始化 .pm/ 状态目录（幂等防护：已初始化则报错） */
+export function initProject(root, input) {
+    if (isInitialized(root)) {
+        throw new Error(`项目已初始化（${pmPath(root, "project.json")} 已存在）。修改信息请用 update_project。`);
+    }
+    ensurePmDirs(root);
+    const t = now();
+    const project = {
+        name: input.name,
+        description: input.description ?? "",
+        stack: input.stack ?? [],
+        goals: input.goals ?? [],
+        phase: "",
+        modules: input.modules ?? [],
+        exposure: input.exposure ?? "local",
+        license: input.license ?? "",
+        budgets: { maxFileLoc: 500, refactorQuotaPct: 20, sessionBlastRadius: 15, outputBudgetLines: 150 },
+        created: t,
+        updated: t,
+    };
+    saveProject(root, project);
+    saveRoadmap(root, { seq: 0, milestones: [] });
+    saveTasks(root, { seq: 0, tasks: [] });
+    saveFeatures(root, { seq: 0, features: [] });
+    saveSessions(root, { seq: 0, sessions: [] });
+    saveDebugLog(root, { seq: 0, entries: [] });
+    saveFileNotes(root, { notes: {} });
+    if (!fs.existsSync(governancePath(root)))
+        saveGovernance(root, {});
+    const secFile = pmPath(root, "security.json");
+    if (!fs.existsSync(secFile)) {
+        fs.writeFileSync(secFile, JSON.stringify({ findings: [], last_scan: null }, null, 2) + "\n", "utf8");
+    }
+    return project;
+}