@luckychen1993/pm-mcp 0.1.4 → 0.3.0

package/dist/doctor.js

@@ -0,0 +1,148 @@
+import os from "node:os";
+import fs from "node:fs";
+import path from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { PACKAGE_SPEC, RUNTIME_CONTRACT, SERVER_NAME, TOOL_CATALOG_SIZE, VERSION } from "./version.js";
+import { canonicalProjectRoot, findCodexProjectEntry, isLocalLaunch, isLocalServerEntry, isPackageLaunch, readCodexConfig } from "./setup-project.js";
+import { localProjectLaunch, workbuddyConfigPath } from "./setup.js";
+export function parseDoctorArgs(argv) {
+    const options = { root: process.cwd() };
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index], value = argv[index + 1];
+        if (!["--root", "--entry", "--config", "--client"].includes(arg) || !value || value.startsWith("--"))
+            throw new Error(`doctor 参数无效: ${arg}`);
+        if (arg === "--root")
+            options.root = path.resolve(value);
+        if (arg === "--entry")
+            options.entry = path.resolve(value);
+        if (arg === "--config")
+            options.config = path.resolve(value);
+        if (arg === "--client") {
+            if (value !== "codex" && value !== "workbuddy")
+                throw new Error("doctor 支持 --client codex|workbuddy，其他客户端可用 --entry 验证本地入口。");
+            options.client = value;
+        }
+        index++;
+    }
+    if (options.entry && options.config)
+        throw new Error("--entry 与 --config 不能同时使用。");
+    return options;
+}
+/**
+ * 从 WorkBuddy 的 `mcp.json` 中取出 pm-mcp 条目。
+ *
+ * 只读取启动定义（command/args），不复制也不输出任何自定义 env / 凭据。
+ * 文件必须是**有界普通文件**：链接、目录、超 2MB 一律拒绝。
+ */
+function readWorkbuddyEntry(file) {
+    if (!fs.existsSync(file))
+        return undefined;
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 2 * 1024 * 1024)
+        throw new Error("WorkBuddy 配置必须为有界普通文件，禁止链接。");
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`WorkBuddy 配置不是合法 JSON：${error.message}`);
+    }
+    const servers = parsed?.mcpServers;
+    const entry = servers?.[SERVER_NAME];
+    if (!entry)
+        return undefined;
+    if (entry.disabled === true)
+        throw new Error("WorkBuddy 中 pm-mcp 条目被禁用，现有客户端不会启动它。");
+    if (typeof entry.command !== "string" || entry.command.length === 0)
+        throw new Error("WorkBuddy 中 pm-mcp 条目缺少可识别的 command。");
+    const args = entry.args === undefined ? [] : entry.args;
+    if (!Array.isArray(args) || !args.every((value) => typeof value === "string"))
+        throw new Error("WorkBuddy 中 pm-mcp 条目的 args 不是字符串数组。");
+    return { command: entry.command, args: args };
+}
+/** 短期本地读连接；不把探测新进程冒充已重新连接的客户端。 */
+export async function runDoctor(options) {
+    const root = path.resolve(options.root);
+    const report = {
+        ok: false, expected_version: VERSION, root, configuration: options.entry ? "explicit_entry" : (options.client ?? "codex"), issues: [],
+        existing_client: "not_observed", note: "这是新建的本地探测连接。现有客户端须重新连接，并在其中调用 get_status 核对运行版本；未读取或转发自定义凭据环境。",
+    };
+    let launch;
+    try {
+        if (options.entry)
+            launch = { command: process.execPath, args: [options.entry, "--root", root] };
+        else if (options.client === "workbuddy") {
+            const file = options.config ?? workbuddyConfigPath(process.env, os.homedir(), fs.existsSync);
+            const entry = readWorkbuddyEntry(file);
+            if (!entry)
+                throw new Error("未在 WorkBuddy 的 mcp.json 中找到 pm-mcp 条目。");
+            report.configured_server = SERVER_NAME;
+            if (!isLocalServerEntry(entry))
+                throw new Error("WorkBuddy 中的 pm-mcp 不是可识别的本地 pm-mcp 启动项；未执行未知启动命令。");
+            // 配置通常不钉根（由会话工作区决定）；探测需要明确目标根，故补上 --root。
+            launch = entry.args.includes("--root") ? entry : { command: entry.command, args: [...entry.args, "--root", root] };
+            report.configuration = "workbuddy_local_probe";
+        }
+        else {
+            if (!options.config && fs.existsSync(path.join(root, ".codex", "config.toml")))
+                throw new Error("存在项目级 Codex 配置，可能覆盖全局设置；请用 --config 明确核验的配置文件并检查实际客户端。");
+            const file = options.config ?? path.join(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), "config.toml");
+            const entry = findCodexProjectEntry(readCodexConfig(file), root);
+            if (!entry)
+                throw new Error("未找到已明确绑定此项目的 Codex pm-mcp 配置。");
+            report.configured_server = entry.name;
+            if (!entry.enabled)
+                throw new Error("该服务在配置中被禁用，现有客户端不会启动它。");
+            if (entry.toolFilters)
+                throw new Error(`存在工具过滤设置，请核对后再确认全部${TOOL_CATALOG_SIZE}工具可用。`);
+            if (isPackageLaunch(entry)) {
+                if (entry.args[1] !== PACKAGE_SPEC)
+                    throw new Error(`启动配置版本与本包 ${PACKAGE_SPEC} 不一致，请先预览并升级配置。`);
+                launch = localProjectLaunch(root);
+                report.configuration = "codex_package_matches_local_probe";
+            }
+            else
+                launch = entry;
+        }
+        if (!isLocalLaunch(launch))
+            throw new Error("探测入口不是可识别的本地 pm-mcp 包；不执行未知启动命令。");
+    }
+    catch (error) {
+        report.issues.push(error.message);
+        return report;
+    }
+    const client = new Client({ name: "pm-mcp-doctor", version: VERSION });
+    const transport = new StdioClientTransport({ command: launch.command, args: launch.args,
+        env: { PM_MCP_HOME: path.join(root, ".pm", ".runtime", "doctor-home") }, stderr: "pipe" });
+    const timer = setTimeout(() => { void client.close(); }, 20_000);
+    timer.unref();
+    try {
+        await client.connect(transport, { timeout: 10_000 });
+        transport.stderr?.on("data", () => undefined);
+        const info = client.getServerVersion();
+        const inventory = await client.listTools({}, { timeout: 10_000 });
+        const status = await client.callTool({ name: "get_status", arguments: {} }, undefined, { timeout: 10_000 });
+        const runtime = status.structuredContent?.runtime;
+        report.probe = { server: info?.name, version: info?.version, tools: inventory.tools.length, runtime };
+        if (info?.name !== SERVER_NAME || info.version !== VERSION)
+            report.issues.push("握手返回的服务名或运行版本不匹配。");
+        if (status.isError || typeof runtime?.root !== "string" || canonicalProjectRoot(runtime.root) !== canonicalProjectRoot(root))
+            report.issues.push("实际状态读取未确认目标项目根。");
+        if (runtime?.version !== VERSION || runtime?.contract !== RUNTIME_CONTRACT)
+            report.issues.push("实际运行契约不支持本轮升级，不能仅凭配置宣称生效。");
+        const list = inventory.tools.find((tool) => tool.name === "list_tasks");
+        const project = inventory.tools.find((tool) => tool.name === "update_project");
+        if (inventory.tools.length !== TOOL_CATALOG_SIZE || !list?.inputSchema.properties?.cursor || !project?.inputSchema.properties?.completion_evidence)
+            report.issues.push("工具目录或新参数契约不完整。");
+        report.ok = report.issues.length === 0;
+    }
+    catch (error) {
+        report.issues.push(`本地连接验证失败: ${error.message}`);
+    }
+    finally {
+        clearTimeout(timer);
+        await client.close();
+    }
+    return report;
+}

package/dist/git-state.js

@@ -0,0 +1,75 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { normSep } from "./budget.js";
+import { hashRegularFile } from "./project-fingerprint.js";
+export function projectFilePath(relative) {
+    const rel = path.posix.normalize(normSep(relative));
+    if (!relative || path.isAbsolute(rel) || /^[a-z]:/i.test(rel) || rel === "." || rel === ".." || rel.startsWith("../")) {
+        throw new Error("文件必须是项目内的相对路径");
+    }
+    return rel;
+}
+/** 使用 NUL 分隔，避免中文转义、空格及文件名中的箭头被误解析。 */
+export function changedGitFiles(root) {
+    const result = spawnSync("git", ["status", "--porcelain=v1", "-z", "-uall"], { cwd: root, encoding: "utf8", timeout: 10000, maxBuffer: 16 * 1024 * 1024 });
+    if (result.error || result.status !== 0)
+        throw new Error(result.error?.message ?? `git status 退出码 ${result.status}`);
+    const records = result.stdout.split("\0");
+    const changed = new Set();
+    const add = (file) => {
+        const rel = projectFilePath(file);
+        if (!rel.startsWith(".pm/") && rel !== "PROJECT.md" && rel !== ".gitignore")
+            changed.add(rel);
+    };
+    for (let i = 0; i < records.length; i++) {
+        const row = records[i];
+        if (!row)
+            continue;
+        add(row.slice(3));
+        const status = row.slice(0, 2);
+        if (/[RC]/.test(status)) {
+            const original = records[++i]; // -z 先输出目标，再输出原路径
+            if (/R/.test(status))
+                add(original); // 重命名还需要核对旧路径的删除；复制不改原文件
+        }
+    }
+    return [...changed];
+}
+/** 只对调用者声明的文件流式取摘要，不跟随父目录链接或读取链接指向的内容。 */
+export function captureFileHashes(root, files) {
+    const hashes = Object.create(null);
+    for (const file of files) {
+        const rel = projectFilePath(file);
+        let current = path.resolve(root);
+        let signature = "missing";
+        const parts = rel.split("/");
+        for (let index = 0; index < parts.length; index++) {
+            current = path.join(current, parts[index]);
+            let stat;
+            try {
+                stat = fs.lstatSync(current);
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    break;
+                throw error;
+            }
+            if (stat.isSymbolicLink()) {
+                if (index !== parts.length - 1)
+                    throw new Error(`文件路径穿过符号链接: ${rel}`);
+                signature = `link\0${fs.readlinkSync(current)}`;
+            }
+            else if (index === parts.length - 1) {
+                if (!stat.isFile())
+                    throw new Error(`会话文件必须是普通文件或已删除文件: ${rel}`);
+                signature = `file\0${hashRegularFile(current).sha256}`;
+            }
+            else if (!stat.isDirectory())
+                throw new Error(`文件路径不是目录: ${rel}`);
+        }
+        hashes[rel] = createHash("sha256").update(signature).digest("hex");
+    }
+    return hashes;
+}

package/dist/governance-tools.js

@@ -10,8 +10,9 @@ import { impactAnalysis } from "./semantic-graph.js";
 import { assessQualityCoverage, createQualityPlan, discoverProjectUnits, runQualityPlan } from "./language-adapters.js";
 import { buildPortfolioFromRegistry, buildPortfolioReport, loadPortfolioProject } from "./portfolio.js";
 import { saveQualityRun } from "./quality-store.js";
+import { evidenceLabel, qualityResultSummary } from "./quality-evidence.js";
 import { SemanticEvidenceDocumentSchema } from "./semantic-evidence.js";
-import { listSemanticEvidence, saveSemanticEvidence } from "./semantic-evidence-store.js";
+import { listSemanticEvidence, replaceSemanticEvidenceForFile, saveSemanticEvidence } from "./semantic-evidence-store.js";
 import { fingerprintProject } from "./project-fingerprint.js";
 const id = z.string().trim().min(1);
 const texts = z.array(z.string().trim().min(1));
@@ -159,6 +160,14 @@ export function registerGovernanceTools(server, root) {
         requireInitialized(root);
         return JSON.stringify(listSemanticEvidence(root), null, 2);
     });
+    toolI(server, root, "replace_semantic_evidence_for_file", "按源码文件原子替换语义证据：删除该文件旧 evidence，仅保留当前 hash-bound evidence。", {
+        id: z.string().trim().min(1).max(128),
+        document: SemanticEvidenceDocumentSchema,
+    }, (args) => {
+        requireInitialized(root);
+        const saved = replaceSemanticEvidenceForFile(root, args.id, args.document);
+        return `✅ semantic evidence replaced ${args.id}：${saved.file} · ${saved.analyzer.id} · ${saved.analyzer.assurance} · ${saved.status}`;
+    });
     toolI(server, root, "save_semantic_evidence", "保存一份绑定源码 SHA-256 的语言原生 AST/编译器/运行时证据；过期摘要在治理审计中严格失败。", {
         id: z.string().trim().min(1).max(128),
         document: SemanticEvidenceDocumentSchema,
@@ -216,7 +225,8 @@ export function registerGovernanceTools(server, root) {
         if (!sourceStable)
             lines.push(`- 🚩 源码在执行期间变化：before=${sourceBefore.sha256} after=${sourceAfter.sha256}`);
         for (const item of result.results)
-            lines.push(`- [${item.status}] ${item.command.kind} ${item.command.cwd} (${item.durationMs}ms${item.exitCode === null ? "" : `, exit ${item.exitCode}`})`);
+            lines.push(`- [${item.status}] ${item.command.kind} ${item.command.cwd} (${item.durationMs}ms${item.exitCode === null ? "" : `, exit ${item.exitCode}`}) · ${evidenceLabel(qualityResultSummary(item).evidence_level)}`);
+        lines.push("命令执行结果与任务完成证据分开判断；未知计数不等于已观察测试通过。");
         return foldLines(lines, { maxLines: budgetLines(root), hint: "查看 .pm/quality-runs 结构化摘要（不落原始输出）" });
     });
     toolR(server, root, "get_portfolio", "聚合当前项目或全局注册项目的阶段、里程碑、债务、安全、语言、跨仓依赖/版本/cycle；加载失败不能假绿。", {

package/dist/index-db.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import { pmPath } from "./paths.js";
+import { watcherIsClean } from "./watcher-coordinator.js";
 /** Low-level SQLite lifecycle, metadata, row iteration, and aggregate queries. */
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS files(
@@ -95,3 +96,42 @@ export function aggregates(db) {
         indexCoverageBase: contentOk.c,
     };
 }
+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 };
+}
+/** 巡检/诊断用：索引概况一行 */
+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}`;
+}

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

@@ -15,6 +15,11 @@ 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";
+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;
@@ -23,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.4" }, {
+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，不要换键重试。",
@@ -41,7 +47,16 @@ function safeText(fn) {
     }
 }
 async function resourceText(name, fn) {
-    return (await runCoalescedRead(root, `resource:${name}`, {}, () => safeText(fn))).text;
+    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: [
@@ -61,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);
             }),
@@ -145,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"),
             },
@@ -216,6 +234,8 @@ if (isInitialized(root)) {
     ensurePmRuntimeIgnored(root);
     const watcher = startWatcher(root);
     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/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("根因（诊断出的真正原因，不是表面现象）"),