@luckychen1993/pm-mcp 0.1.5 → 0.3.0

package/dist/probe.js

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

package/dist/project-fingerprint.js

@@ -1,11 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
-const DEFAULT_IGNORED_DIRECTORIES = new Set([
-    ".git", ".pm", ".cache", ".gradle", ".idea", ".next", ".nuxt", ".output", ".turbo", ".venv", ".vscode", ".zcode",
-    "__pycache__", "build", "coverage", "dist", "env", "node_modules", "out", "target", "venv",
-]);
-function hashRegularFile(file) {
+import { SCAN_IGNORE_DIRS, ignoreMatcher, projectScanIgnores } from "./scan-policy.js";
+const DEFAULT_IGNORED_DIRECTORIES = SCAN_IGNORE_DIRS;
+export function hashRegularFile(file) {
     const handle = fs.openSync(file, "r");
     const digest = createHash("sha256");
     const buffer = Buffer.allocUnsafe(1024 * 1024);
@@ -43,6 +41,10 @@ export function fingerprintProject(root) {
         throw new Error(`项目根必须是普通目录: ${absolute}`);
     const rootReal = fs.realpathSync.native(absolute);
     const tree = createHash("sha256");
+    const ignores = projectScanIgnores(root);
+    const excluded = ignoreMatcher(ignores);
+    if (ignores.length)
+        tree.update(`scan-ignore\0${JSON.stringify(ignores)}\0`);
     let files = 0;
     let bytes = 0;
     const visit = (directory, relativeDirectory) => {
@@ -52,6 +54,8 @@ export function fingerprintProject(root) {
                 continue;
             const absoluteEntry = path.join(directory, entry.name);
             const relative = path.posix.join(relativeDirectory.replace(/\\/g, "/"), entry.name);
+            if (excluded(relative, entry.isDirectory()))
+                continue;
             if (relative === "PROJECT.md")
                 continue; // generated dashboard; authoritative inputs live in .pm and source files
             const stat = fs.lstatSync(absoluteEntry);

package/dist/project-tools.js

@@ -9,6 +9,9 @@ import { loadProject, loadRoadmap, loadSecurity, loadSessions, loadTasks, savePr
 import { now } from "./types.js";
 import { budgetLines, toolI, toolR, toolW } from "./tool-base.js";
 import { renderRuntimeLogLines, renderUsageLogLines } from "./usage-log.js";
+import { ScanIgnoreSchema } from "./scan-policy.js";
+import { VERSION, RUNTIME_CONTRACT } from "./version.js";
+import { CompletionEvidenceSchema } from "./quality-evidence.js";
 function taskLine(t, withNext = false) {
     const parts = [`[${t.status}]`, t.id, t.title, `(${t.type}${t.milestone ? `,${t.milestone}` : ""})`];
     if (withNext && t.checkpoint) {
@@ -46,6 +49,7 @@ export function registerProjectTools(server, root) {
         const security = loadSecurity(root);
         const L = [];
         L.push(`# ${project.name}${project.phase ? ` — ${project.phase}` : ""}`);
+        L.push(`运行版本: pm-mcp ${VERSION} · 项目根: ${root}`);
         if (project.description)
             L.push(project.description);
         L.push("");
@@ -96,8 +100,9 @@ export function registerProjectTools(server, root) {
         }
         L.push("");
         L.push("> 三段式定位：本状态 → search_code 精确到行 → 才读具体文件。别全量读代码。");
-        return foldLines(L, { maxLines: budgetLines(root) });
-    });
+        return JSON.stringify({ text: foldLines(L, { maxLines: budgetLines(root) }), runtime: { version: VERSION, root, contract: RUNTIME_CONTRACT } });
+    }, { cacheVersion: `runtime:${VERSION}`, outputSchema: { runtime: z.object({ version: z.string(), root: z.string(), contract: z.string() }) },
+        decode: (value) => { const result = JSON.parse(value); return { text: result.text, data: { runtime: result.runtime } }; } });
     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"),
@@ -124,6 +129,8 @@ export function registerProjectTools(server, root) {
         license: z.string().optional(),
         exposure: z.enum(["local", "network", "public"]).optional(),
         modules: z.array(z.string()).optional().describe("模块登记（用于未登记目录检测）"),
+        scan_ignore: ScanIgnoreSchema.optional().describe("本项目产物/缓存的相对排除 glob，例如 release/**；传 [] 清除；不应排除真实源码"),
+        completion_evidence: CompletionEvidenceSchema.optional().describe("默认要求tests_observed；兼容无计数运行器时显式选择execution_only并记录原因"),
         max_file_loc: z.number().int().min(10).optional().describe("单文件行数预算"),
         refactor_quota_pct: z.number().min(0).max(100).optional().describe("里程碑重构类任务最低占比%"),
         session_blast_radius: z.number().int().min(1).optional().describe("单会话波及文件阈值"),
@@ -145,6 +152,10 @@ export function registerProjectTools(server, root) {
             project.exposure = args.exposure;
         if (args.modules !== undefined)
             project.modules = args.modules;
+        if (args.scan_ignore !== undefined)
+            project.scan_ignore = args.scan_ignore;
+        if (args.completion_evidence !== undefined)
+            project.completion_evidence = CompletionEvidenceSchema.parse(args.completion_evidence);
         if (args.max_file_loc !== undefined)
             project.budgets.maxFileLoc = args.max_file_loc;
         if (args.refactor_quota_pct !== undefined)

package/dist/quality-evidence.js

@@ -0,0 +1,56 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+export const CompletionEvidenceSchema = z.object({
+    minimum: z.enum(["tests_observed", "execution_only"]),
+    reason: z.string().trim().min(8).max(1000),
+});
+const ranks = { unverified: 0, execution_only: 1, tests_observed: 2, coverage_observed: 3 };
+/** 等级描述观测强度，不代表测试充分、结果通过或来源不可伪造。 */
+export function evidenceLevel(kind, summary, truncated = false) {
+    if (truncated || !["test", "coverage"].includes(kind))
+        return "execution_only";
+    const counters = [summary.failed, summary.skipped, summary.cancelled, summary.todo];
+    if (summary.tests === null || !Number.isSafeInteger(summary.tests) || summary.tests <= 0 ||
+        counters.some((n) => n === null || !Number.isSafeInteger(n) || n < 0) ||
+        counters.reduce((total, n) => total + (n ?? 0), 0) > summary.tests)
+        return "execution_only";
+    if (summary.passed != null && summary.passed + counters.reduce((total, n) => total + (n ?? 0), 0) !== summary.tests)
+        return "execution_only";
+    const coverage = z.object({ lines_pct: z.number().min(0).max(100), branches_pct: z.number().min(0).max(100), functions_pct: z.number().min(0).max(100) }).safeParse(summary.coverage);
+    return coverage.success ? "coverage_observed" : "tests_observed";
+}
+export function weakestEvidence(levels) {
+    return levels.length ? levels.reduce((a, b) => ranks[a] < ranks[b] ? a : b) : "execution_only";
+}
+export function evidenceLabel(level) {
+    return { unverified: "无可用验证证据", execution_only: "仅执行记录，未确认测试数量", tests_observed: "已观察测试结果", coverage_observed: "已观察测试与覆盖率" }[level ?? ""] ?? "旧报告未标等级";
+}
+export function qualityResultSummary(item) {
+    const summary = qualityOutputSummary(item.command.kind, item.stdout, item.stderr, item.truncated);
+    return { ...summary, evidence_level: item.exitCode === null ? "unverified" : summary.evidence_level };
+}
+export function qualityOutputSummary(kind, stdout, stderr, truncated = false) {
+    const output = `${stdout}\n${stderr}`.replace(/\u001b\[[0-9;]*m/g, "");
+    const diagnostic = (label) => {
+        const matches = [...output.matchAll(new RegExp(`^[ \\t]*(?:ℹ|#)?[ \\t]*${label}[ \\t]+(\\d+)[ \\t]*\\r?$`, "gmi"))];
+        return matches.length ? Number(matches.at(-1)[1]) : null;
+    };
+    let counts = { tests: diagnostic("tests"), passed: diagnostic("pass"), failed: diagnostic("fail"), cancelled: diagnostic("cancelled"), skipped: diagnostic("skipped"), todo: diagnostic("todo") };
+    let counterSource = counts.tests === null ? "unknown" : "node_test_summary";
+    const jest = [...output.matchAll(/^\s*Tests:\s*(.+?)(\d+)\s+total\s*$/gm)].at(-1);
+    const vitest = [...output.matchAll(/^\s*Tests\s+(.+?)\s*\((\d+)\)\s*$/gm)].at(-1);
+    const pytest = [...output.matchAll(/^=+\s+((?:\d+\s+(?:passed|failed|skipped|xfailed|xpassed|deselected|errors?|warnings?)[,\s]*)+)\s+in\s+[\d.]+s.*?=+\s*$/gm)].at(-1);
+    if (counts.tests === null && (jest || vitest || pytest)) {
+        const text = (jest ?? vitest ?? pytest)[1];
+        const number = (label) => Number(new RegExp(`(\\d+)\\s+${label}\\b`).exec(text)?.[1] ?? 0);
+        const passed = number("passed"), failed = number("failed") + number("errors?") + number("xpassed");
+        const skipped = number("skipped") + number("xfailed") + number("deselected"), todo = number("todo");
+        counts = { tests: jest ? Number(jest[2]) : vitest ? Number(vitest[2]) : passed + failed + skipped + todo, passed, failed, skipped, todo, cancelled: 0 };
+        counterSource = jest ? "jest_summary" : vitest ? "vitest_summary" : "pytest_summary";
+    }
+    const coverage = output.match(/(?:^|\n)(?:ℹ|#)?\s*all files\s*\|\s*([\d.]+)\s*\|\s*([\d.]+)\s*\|\s*([\d.]+)(?:\s*\|\s*([\d.]+))?/i);
+    counts.coverage = coverage ? { lines_pct: Number(coverage[4] ?? coverage[1]), branches_pct: Number(coverage[2]), functions_pct: Number(coverage[3]) } : null;
+    return { stdout_bytes: Buffer.byteLength(stdout), stderr_bytes: Buffer.byteLength(stderr),
+        output_sha256: createHash("sha256").update(stdout).update("\0").update(stderr).digest("hex"),
+        ...counts, counter_source: counterSource, evidence_level: evidenceLevel(kind, counts, truncated) };
+}

package/dist/quality-store.js

@@ -1,48 +1,28 @@
 import fs from "node:fs";
 import path from "node:path";
-import { createHash } from "node:crypto";
 import { atomicWrite, withLedgerLock } from "./store.js";
 import { refreshDerived } from "./dashboard.js";
-function numericDiagnostic(output, label) {
-    const match = output.match(new RegExp(`(?:^|\\n)(?:ℹ|#)?\\s*${label}\\s+(\\d+)(?:\\s|$)`, "i"));
-    return match ? Number(match[1]) : null;
-}
-function outputSummary(stdout, stderr) {
-    const combined = `${stdout}\n${stderr}`;
-    // Node's test reporter exposes line|branch|function, while Istanbul/c8 uses
-    // statement|branch|function|line. Preserve one normalized three-metric shape.
-    const coverage = combined.match(/(?:^|\n)(?:ℹ|#)?\s*all files\s*\|\s*([\d.]+)\s*\|\s*([\d.]+)\s*\|\s*([\d.]+)(?:\s*\|\s*([\d.]+))?/i);
-    return {
-        stdout_bytes: Buffer.byteLength(stdout),
-        stderr_bytes: Buffer.byteLength(stderr),
-        output_sha256: createHash("sha256").update(stdout, "utf8").update("\0", "utf8").update(stderr, "utf8").digest("hex"),
-        tests: numericDiagnostic(combined, "tests"),
-        passed: numericDiagnostic(combined, "pass"),
-        failed: numericDiagnostic(combined, "fail"),
-        cancelled: numericDiagnostic(combined, "cancelled"),
-        skipped: numericDiagnostic(combined, "skipped"),
-        todo: numericDiagnostic(combined, "todo"),
-        coverage: coverage ? { lines_pct: Number(coverage[4] ?? coverage[1]), branches_pct: Number(coverage[2]), functions_pct: Number(coverage[3]) } : null,
-    };
-}
+import { qualityResultSummary, weakestEvidence } from "./quality-evidence.js";
 /** Persist a secret-minimised quality summary; raw stdout/stderr never enter the ledger. */
 export function saveQualityRun(root, result, provenance) {
     const runAt = new Date();
     const stamp = runAt.toISOString().replace(/[-:]/g, "").replace("T", "-").replace(".", "-").replace(/Z$/, "");
     const effectiveOk = result.ok && result.execute && result.results.length > 0 && result.results.every((item) => item.status === "passed" && item.exitCode === 0 && item.signal === null);
+    const summaries = result.results.map(qualityResultSummary);
     const payload = JSON.stringify({
         schema_version: 2,
         run_at: runAt.toISOString(),
         ok: effectiveOk,
         reported_ok: result.ok,
         execute: result.execute,
+        evidence_level: result.execute && result.results.some((item) => item.exitCode !== null) ? weakestEvidence(summaries.filter((_item, i) => ["test", "coverage"].includes(result.results[i].command.kind)).map((item) => item.evidence_level)) : "unverified",
         environment: { platform: process.platform, arch: process.arch, node: process.version },
         source: provenance ? {
             before: provenance.source_before,
             after: provenance.source_after,
             stable: provenance.source_before.sha256 === provenance.source_after.sha256,
         } : null,
-        results: result.results.map((item) => ({
+        results: result.results.map((item, index) => ({
             unit_root: item.command.cwd,
             kind: item.command.kind,
             command: item.command.command,
@@ -52,7 +32,7 @@ export function saveQualityRun(root, result, provenance) {
             signal: item.signal,
             duration_ms: item.durationMs,
             output_truncated: item.truncated,
-            output_summary: outputSummary(item.stdout, item.stderr),
+            output_summary: summaries[index],
             error: item.error ?? "",
         })),
     }, null, 2) + "\n";

package/dist/registry.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { RegistrySchema, now } from "./types.js";
 import { registryFile } from "./paths.js";
@@ -23,9 +24,18 @@ export function saveRegistry(data) {
 }
 /** 登记/刷新一个项目（init 与每次写操作都会 touch） */
 export function touchRegistry(root, name) {
-    const data = loadRegistry();
     const abs = path.resolve(root);
-    const idx = data.projects.findIndex((p) => path.resolve(p.root) === abs);
+    // 防污染（T-034 根因）：临时目录里的"项目"从不进入真实注册表——
+    // 测试若未设 PM_MCP_HOME 沙箱，写入会被这里拦下而不是污染 ~/.pm-mcp。
+    // 沙箱化测试（显式设了 PM_MCP_HOME）不受影响，仍写沙箱注册表。
+    if (!process.env.PM_MCP_HOME?.trim() && isUnderTemp(abs)) {
+        console.error(`[pm-mcp] 跳过注册临时目录项目（如需管理请移出临时目录）: ${abs}`);
+        return;
+    }
+    const data = loadRegistry();
+    // Windows 路径大小写不敏感：按小写比较去重（e:/E: 重复注册缺陷）
+    const key = abs.toLowerCase();
+    const idx = data.projects.findIndex((p) => path.resolve(p.root).toLowerCase() === key);
     const entry = { name, root: abs, last_seen: now() };
     if (idx >= 0)
         data.projects[idx] = entry;
@@ -33,6 +43,22 @@ export function touchRegistry(root, name) {
         data.projects.push(entry);
     saveRegistry(data);
 }
+function isUnderTemp(abs) {
+    const normalized = abs.toLowerCase();
+    // tmpdir 可能以 8.3 短名返回（ADMINI~1），与注册表里的长名不一致——两种形态都比对
+    let tmpLong = os.tmpdir().toLowerCase();
+    try {
+        tmpLong = fs.realpathSync.native(os.tmpdir()).toLowerCase();
+    }
+    catch {
+        /* keep default */
+    }
+    for (const tmp of new Set([tmpLong, os.tmpdir().toLowerCase()])) {
+        if (normalized === tmp || normalized.startsWith(tmp.replace(/\$/, "") + path.sep))
+            return true;
+    }
+    return false;
+}
 export function listRegistry() {
     return loadRegistry().projects.sort((a, b) => b.last_seen.localeCompare(a.last_seen));
 }

package/dist/scan-policy.js

@@ -0,0 +1,34 @@
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { globToRegExp, normSep } from "./budget.js";
+export const SCAN_IGNORE_DIRS = new Set([
+    "node_modules", ".git", "dist", "build", "out", ".next", ".nuxt", ".output", ".turbo", "coverage",
+    "__pycache__", ".venv", "venv", "env", ".pm", ".idea", ".vscode", "target", ".cache", ".gradle",
+    ".zcode", ".runtime", "EBWebView",
+    // 包管理器缓存 / 运行时数据 / 临时与上下文目录：属于环境而非项目源码（T-045）
+    ".pnpm-cache", ".pnpm-store", ".npm-cache", ".yarn-cache", ".data", ".tmp", ".temp",
+    ".codex-context", "userdata", "logs",
+]);
+export const ScanIgnoreSchema = z.array(z.string().trim().min(1).max(512).transform(normSep).refine((glob) => !glob.startsWith("/") && !glob.startsWith("!") && !/^[a-z]:/i.test(glob) && !glob.split("/").includes(".."), "扫描排除必须是项目内的正向相对 glob")).max(100);
+export function projectScanIgnores(root) {
+    const file = path.join(root, ".pm", "project.json");
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    return [...new Set(ScanIgnoreSchema.parse(JSON.parse(raw).scan_ignore ?? []))].sort();
+}
+export function ignoreMatcher(globs) {
+    const patterns = globs.map(globToRegExp);
+    return (rel, directory = false) => patterns.some((pattern) => pattern.test(rel) || (directory && pattern.test(`${rel}/`)));
+}
+export function scanExclusionNote(root) {
+    const ignores = projectScanIgnores(root);
+    return ignores.length ? [`扫描范围排除：${ignores.join(", ")}；排除内容不属于本次检查结论。`] : [];
+}

package/dist/scan.js

@@ -2,33 +2,13 @@ import fs from "node:fs";
 import path from "node:path";
 import { globToRegExp, normSep } from "./budget.js";
 import { aggregates, getIndex, walkRefresh } from "./index-store.js";
+import { SCAN_IGNORE_DIRS, ignoreMatcher, projectScanIgnores } from "./scan-policy.js";
 /**
  * 代码树扫描：低层走查（生成器，内存恒定）+ scanProject 聚合入口。
  * 内容级结果存 SQLite 索引（index-store），未变更文件永不重读。
  * 超大项目保护：>10 万文件不物化 files 数组（聚合与点名走 SQL）。
  */
-export const DEFAULT_IGNORE_DIRS = new Set([
-    "node_modules",
-    ".git",
-    "dist",
-    "build",
-    "out",
-    ".next",
-    ".nuxt",
-    ".output",
-    ".turbo",
-    "coverage",
-    "__pycache__",
-    ".venv",
-    "venv",
-    "env",
-    ".pm",
-    ".idea",
-    ".vscode",
-    "target",
-    ".cache",
-    ".gradle",
-]);
+export const DEFAULT_IGNORE_DIRS = SCAN_IGNORE_DIRS;
 /** 真实目录树不太可能超过 64 层；超限的计数上报，绝不静默丢失 */
 export const DEPTH_LIMIT = 64;
 export const BINARY_EXTS = new Set([
@@ -112,7 +92,7 @@ export function needsSkipCount(rel, isTest) {
  * onSkippedDeep 在超深路径被跳过时回调（计数上报用）。
  */
 export function* walkStatEntries(root, opts = {}, onSkippedDeep) {
-    const extraRe = (opts.extraIgnores ?? []).map(globToRegExp);
+    const excluded = ignoreMatcher([...projectScanIgnores(root), ...(opts.extraIgnores ?? [])]);
     const includeRe = opts.include?.map(globToRegExp);
     const maxBytes = opts.maxFileBytes ?? 2 * 1024 * 1024;
     void maxBytes;
@@ -134,12 +114,12 @@ export function* walkStatEntries(root, opts = {}, onSkippedDeep) {
             if (entry.isDirectory()) {
                 if (DEFAULT_IGNORE_DIRS.has(entry.name))
                     continue;
-                if (extraRe.some((re) => re.test(rel)))
+                if (excluded(rel, true))
                     continue;
                 yield* walk(abs, depth + 1);
             }
             else if (entry.isFile()) {
-                if (extraRe.some((re) => re.test(rel)))
+                if (excluded(rel))
                     continue;
                 if (includeRe && !includeRe.some((re) => re.test(rel)))
                     continue;

package/dist/search.js

@@ -6,6 +6,7 @@ import { decisionsDir } from "./paths.js";
 import { loadGovernance } from "./governance-model.js";
 import { listFiles, DEFAULT_IGNORE_DIRS } from "./scan.js";
 import { foldLines, normSep } from "./budget.js";
+import { projectScanIgnores } from "./scan-policy.js";
 /**
  * 求证与检索：search_code（锚定真实代码）+ search_knowledge（历史结论）。
  * token 经济的一部分：返回 file:line 片段而非整文件。
@@ -36,6 +37,7 @@ export function rgSearch(root, query, glob, maxResults, regex) {
             args.push("-g", "!.pm/**");
         else
             args.push("-g", `!${dir}/**`);
+        args.push("-g", `!**/${dir}/**`);
     }
     args.push("--max-count", String(maxResults * 3));
     if (regex)
@@ -44,6 +46,8 @@ export function rgSearch(root, query, glob, maxResults, regex) {
         args.push("-F", "-e", query);
     if (glob)
         args.push("--glob", glob);
+    for (const excluded of projectScanIgnores(root))
+        args.push("--glob", `!${excluded}`);
     args.push(".");
     const r = spawnSync("rg", args, { cwd: root, encoding: "utf8", timeout: 120_000, maxBuffer: 64 * 1024 * 1024 });
     if (process.env.PM_RG_DEBUG)

package/dist/security.js

@@ -7,6 +7,7 @@ import { readDirectDeps } from "./scan.js";
 import { ensureFresh, getIndex, iterateFileRows, walkRefresh } from "./index-store.js";
 import { readText } from "./search.js";
 import { now } from "./types.js";
+import { scanExclusionNote } from "./scan-policy.js";
 const SECRET_PATTERNS = [
     { id: "secret.aws-access-key", severity: "high", pattern: /AKIA[0-9A-Z]{16}/, message: "疑似 AWS Access Key" },
     { id: "secret.github-token", severity: "high", pattern: /gh[pousr]_[A-Za-z0-9]{20,}/, message: "疑似 GitHub Token" },
@@ -265,6 +266,7 @@ export function auditSecurity(root, prepared) {
     const high = open.filter((f) => f.severity === "high");
     const L = [];
     L.push(`## 安全体检报告（exposure=${project.exposure}）`);
+    L.push(...scanExclusionNote(root));
     // exposure 兑现：不同暴露面使用不同处置口径
     if (project.exposure === "public") {
         const mustFix = open.filter((f) => f.severity === "high" || f.severity === "medium");

package/dist/semantic-evidence-store.js

@@ -102,6 +102,28 @@ export function saveSemanticEvidence(root, id, input) {
         return parsed.data;
     });
 }
+/** Atomically replace the evidence set for one repository-relative source file under the ledger lock. */
+export function replaceSemanticEvidenceForFile(root, id, input) {
+    const safeId = validateSemanticEvidenceId(id);
+    const parsed = SemanticEvidenceDocumentSchema.safeParse(input);
+    if (!parsed.success) {
+        throw new Error(`语义证据 schema 校验失败: ${parsed.error.issues.map((issue) => `${issue.path.join(".") || "document"}: ${issue.message}`).join("; ")}`);
+    }
+    const absoluteRoot = path.resolve(root);
+    const directory = semanticEvidenceDir(absoluteRoot);
+    assertRealDirectoryWithinRoot(absoluteRoot, directory, true);
+    return withLedgerLock(absoluteRoot, () => {
+        assertRealDirectoryWithinRoot(absoluteRoot, directory, false);
+        const oldIds = evidenceIdsUnlocked(absoluteRoot)
+            .filter((candidate) => candidate !== safeId)
+            .filter((candidate) => loadUnlocked(absoluteRoot, candidate).file === parsed.data.file);
+        atomicWrite(semanticEvidencePath(absoluteRoot, safeId), `${JSON.stringify(parsed.data, null, 2)}
+`);
+        for (const oldId of oldIds)
+            fs.rmSync(semanticEvidencePath(absoluteRoot, oldId), { force: false });
+        return parsed.data;
+    });
+}
 export function loadSemanticEvidence(root, id) {
     return loadUnlocked(path.resolve(root), validateSemanticEvidenceId(id));
 }

package/dist/semantic-parsers.js

@@ -298,6 +298,24 @@ export function candidates(from, specifier, language, ownerRoots = []) {
         if (base === ".." || base.startsWith("../"))
             continue;
         out.add(base);
+        // TypeScript ESM convention: source specifiers ending in .js/.jsx/.mjs/.cjs often
+        // refer to .ts/.tsx/.mts/.cts files on disk (tsc rewriteRelativeImportExtensions
+        // and Node type stripping both map them this way). Candidates are appended after
+        // the literal path, so an existing .js file still wins resolution.
+        const specExt = path.posix.extname(base);
+        if (specExt === ".js" || specExt === ".jsx" || specExt === ".mjs" || specExt === ".cjs") {
+            const stem = base.slice(0, base.length - specExt.length);
+            if (specExt === ".js") {
+                out.add(`${stem}.ts`);
+                out.add(`${stem}.tsx`);
+            }
+            else if (specExt === ".jsx")
+                out.add(`${stem}.tsx`);
+            else if (specExt === ".mjs")
+                out.add(`${stem}.mts`);
+            else
+                out.add(`${stem}.cts`);
+        }
         if (!path.posix.extname(base)) {
             for (const ext of RESOLVE_EXTS)
                 out.add(base + ext);

package/dist/session-log.js

@@ -0,0 +1,14 @@
+import { loadSessions, nextId, saveSessions } from "./store.js";
+import { now } from "./types.js";
+import { captureFileHashes, projectFilePath } from "./git-state.js";
+/** 调用方持有账本锁；共享显式会话与任务自动会话的同一记录方式。 */
+export function appendSession(root, input, hashes) {
+    const files = (input.files ?? []).map(projectFilePath);
+    const fileHashes = hashes ?? captureFileHashes(root, files);
+    const data = loadSessions(root);
+    const id = nextId("S", data.seq, 4);
+    data.seq += 1;
+    data.sessions.push({ id, date: now(), author: input.author ?? "", summary: input.summary, files, next_steps: input.next_steps ?? [], file_hashes: fileHashes });
+    saveSessions(root, data);
+    return id;
+}