@luckychen1993/pm-mcp 0.1.4 → 0.3.0

package/dist/tool-base.js

@@ -1,14 +1,51 @@
 import { loadProject } from "./store.js";
 import { IdempotencyKeySchema, runCoalescedRead, runIdempotentWrite, runIdempotentWriteSync } from "./idempotency.js";
+import { drainFoldSavings } from "./budget.js";
+import { estimateTokens, logRuntime, logUsage } from "./usage-log.js";
+/** 工具/资源调用结束后写使用日志（含本次折叠省下的 token 估算）；绝不抛错。 */
+export function recordUsage(root, tool, kind, started, outcome) {
+    try {
+        const folded = drainFoldSavings();
+        logUsage(root, {
+            ts: new Date().toISOString(),
+            tool,
+            kind,
+            ok: outcome.ok,
+            ms: Date.now() - started,
+            ...(outcome.text !== undefined ? { out_chars: outcome.text.length, est_tokens: estimateTokens(outcome.text) } : {}),
+            ...(folded ? { folded_chars: folded.chars, folded_tokens: folded.tokens } : {}),
+            ...(outcome.replayed ? { replayed: true } : {}),
+            ...(outcome.pending ? { pending: true } : {}),
+            ...(outcome.uncertain ? { uncertain: true } : {}),
+            ...(outcome.error ? { error: outcome.error.slice(0, 300) } : {}),
+        });
+    }
+    catch {
+        /* 使用日志绝不影响工具调用 */
+    }
+}
 /** 只读工具：跨 Agent/进程合并完全相同的并行请求，短窗复用结果。 */
-export function toolR(server, root, name, description, schema, fn) {
-    server.registerTool(name, { description, inputSchema: schema, annotations: { readOnlyHint: true } }, (async (args) => {
+export function toolR(server, root, name, description, schema, fn, presentation) {
+    server.registerTool(name, { description, inputSchema: schema, ...(presentation ? { outputSchema: presentation.outputSchema } : {}), annotations: { readOnlyHint: true } }, (async (args) => {
+        const started = Date.now();
         try {
-            const result = await runCoalescedRead(root, name, args, fn);
-            return { content: [{ type: "text", text: result.text }] };
+            const result = await runCoalescedRead(root, presentation ? `${name}:${presentation.cacheVersion ?? "structured-v1"}` : name, args, fn);
+            const decoded = presentation?.decode(result.text);
+            const text = decoded?.text ?? result.text;
+            recordUsage(root, name, "read", started, {
+                ok: !result.pending,
+                text: decoded ? text + JSON.stringify(decoded.data) : text,
+                replayed: result.replayed,
+                pending: result.pending,
+                uncertain: result.uncertain,
+            });
+            return { content: [{ type: "text", text }], ...(decoded ? { structuredContent: decoded.data } : {}) };
         }
         catch (error) {
-            return { content: [{ type: "text", text: `错误: ${error.message}` }], isError: true };
+            const message = error.message;
+            recordUsage(root, name, "read", started, { ok: false, error: message });
+            logRuntime(root, "error", "tool.error", `${name}: ${message.slice(0, 200)}`);
+            return { content: [{ type: "text", text: `错误: ${message}` }], isError: true };
         }
     }));
 }
@@ -22,26 +59,50 @@ function writeSchema(schema) {
 /** 同步写工具：业务幂等占位 + 跨进程账本锁覆盖完整读-改-写。 */
 export function toolW(server, root, name, description, schema, fn, prepare) {
     server.registerTool(name, { description: `${description} ${idempotencyDescription}`, inputSchema: writeSchema(schema), annotations: { readOnlyHint: false } }, ((args) => {
+        const started = Date.now();
         try {
             const result = runIdempotentWriteSync(root, name, args, fn, prepare);
             const prefix = result.replayed ? `↩️ 幂等复用 ${result.key}\n` : result.pending ? `⏳ 幂等占位 ${result.key}\n` : "";
-            return { content: [{ type: "text", text: prefix + result.text }], ...(result.pending ? { isError: true } : {}) };
+            const text = prefix + result.text;
+            recordUsage(root, name, "write", started, {
+                ok: !result.pending,
+                text,
+                replayed: result.replayed,
+                pending: result.pending,
+                uncertain: result.uncertain,
+            });
+            return { content: [{ type: "text", text }], ...(result.pending ? { isError: true } : {}) };
         }
         catch (error) {
-            return { content: [{ type: "text", text: `错误: ${error.message}` }], isError: true };
+            const message = error.message;
+            recordUsage(root, name, "write", started, { ok: false, error: message });
+            logRuntime(root, "error", "tool.error", `${name}: ${message.slice(0, 200)}`);
+            return { content: [{ type: "text", text: `错误: ${message}` }], isError: true };
         }
     }));
 }
 /** 已自带内部锁或异步执行的写工具：先跨进程占位，完成后缓存结果。 */
 export function toolI(server, root, name, description, schema, fn) {
     server.registerTool(name, { description: `${description} ${idempotencyDescription}`, inputSchema: writeSchema(schema), annotations: { readOnlyHint: false } }, (async (args) => {
+        const started = Date.now();
         try {
             const result = await runIdempotentWrite(root, name, args, fn);
             const prefix = result.replayed ? `↩️ 幂等复用 ${result.key}\n` : result.pending ? `⏳ 幂等占位 ${result.key}\n` : "";
-            return { content: [{ type: "text", text: prefix + result.text }], ...(result.pending ? { isError: true } : {}) };
+            const text = prefix + result.text;
+            recordUsage(root, name, "write-async", started, {
+                ok: !result.pending,
+                text,
+                replayed: result.replayed,
+                pending: result.pending,
+                uncertain: result.uncertain,
+            });
+            return { content: [{ type: "text", text }], ...(result.pending ? { isError: true } : {}) };
         }
         catch (error) {
-            return { content: [{ type: "text", text: `错误: ${error.message}` }], isError: true };
+            const message = error.message;
+            recordUsage(root, name, "write-async", started, { ok: false, error: message });
+            logRuntime(root, "error", "tool.error", `${name}: ${message.slice(0, 200)}`);
+            return { content: [{ type: "text", text: `错误: ${message}` }], isError: true };
         }
     }));
 }

package/dist/types.js

@@ -1,5 +1,7 @@
 import { z } from "zod";
 import { normSep } from "./budget.js";
+import { ScanIgnoreSchema } from "./scan-policy.js";
+import { CompletionEvidenceSchema } from "./quality-evidence.js";
 export const now = () => new Date().toISOString();
 /** 文件清单字段：统一 / 分隔（Windows 反斜杠入库即规范化），缺省空数组 */
 const filesField = () => z.array(z.string()).default([]).transform((list) => list.map(normSep));
@@ -24,6 +26,8 @@ export const ProjectSchema = z.object({
     phase: z.string().default(""),
     /** 登记的模块名（用于复杂度账的"未登记目录"检测） */
     modules: z.array(z.string()).default([]),
+    scan_ignore: ScanIgnoreSchema.optional(),
+    completion_evidence: CompletionEvidenceSchema.optional(),
     /** 暴露面：local=本机工具 / network=内网服务 / public=公网服务，影响安全告警力度 */
     exposure: ExposureSchema.default("local"),
     /** 项目许可证（SPDX 或名称），用于依赖兼容性对账 */
@@ -118,6 +122,7 @@ export const SessionSchema = z.object({
     author: z.string().default(""),
     summary: z.string().trim().min(1),
     files: filesField(),
+    file_hashes: z.record(z.string().regex(/^[a-f0-9]{64}$/)).optional(),
     next_steps: z.array(z.string()).default([]),
 });
 export const SessionsFileSchema = z.object({

package/dist/usage-log.js

@@ -0,0 +1,278 @@
+import fs from "node:fs";
+import { isInitialized, pmPath } from "./paths.js";
+/**
+ * 使用日志 + 运行日志（运行时数据，非账本）：
+ * - usage-log.jsonl：每次 MCP 工具/资源调用一条（工具名、成败、耗时、输出与折叠省下的 token 估算）。
+ *   只记计量不记参数内容，避免敏感信息与大参数进日志。
+ * - runtime-log.jsonl：服务级事件（server 就绪、watcher 状态、工具报错、轮转）。
+ * 均为追加式 JSONL，超限自动轮转（当前 + .1 共两份），绝不抛错——日志永远不能影响工具调用本身。
+ */
+export const USAGE_LOG = "usage-log.jsonl";
+export const RUNTIME_LOG = "runtime-log.jsonl";
+const DEFAULT_MAX_BYTES = 1024 * 1024;
+const ROTATE_CHECK_EVERY = 32;
+const rotateCheckCounter = new Map();
+function maxLogBytes() {
+    const override = Number(process.env.PM_TEST_LOG_MAX_BYTES);
+    return Number.isFinite(override) && override > 0 ? override : DEFAULT_MAX_BYTES;
+}
+function rotatedFile(file) {
+    return file.replace(/\.jsonl$/, ".1.jsonl");
+}
+function appendLine(root, file, line) {
+    try {
+        if (!isInitialized(root))
+            return;
+        fs.appendFileSync(file, line + "\n", "utf8");
+        // 每 N 次写查一次大小（测试覆盖了轮转，此时每次都查）
+        const every = process.env.PM_TEST_LOG_MAX_BYTES ? 1 : ROTATE_CHECK_EVERY;
+        const n = (rotateCheckCounter.get(file) ?? 0) + 1;
+        rotateCheckCounter.set(file, n);
+        if (n % every !== 0)
+            return;
+        if (fs.statSync(file).size <= maxLogBytes())
+            return;
+        const rotated = rotatedFile(file);
+        try {
+            fs.rmSync(rotated, { force: true });
+            fs.renameSync(file, rotated);
+        }
+        catch {
+            // 多进程并发轮转竞争失败可接受：当前文件继续追加，下次再试
+        }
+    }
+    catch {
+        /* 日志绝不影响工具调用 */
+    }
+}
+export function logUsage(root, entry) {
+    appendLine(root, pmPath(root, USAGE_LOG), JSON.stringify(entry));
+}
+export function logRuntime(root, level, event, detail) {
+    const entry = { ts: new Date().toISOString(), level, event, ...(detail ? { detail } : {}) };
+    appendLine(root, pmPath(root, RUNTIME_LOG), JSON.stringify(entry));
+}
+/** 粗估 token 数：CJK 每字≈1 token，其余≈4字符/token（混合中英文经验值，够做趋势判断） */
+export function estimateTokens(text) {
+    let cjk = 0;
+    for (const ch of text) {
+        const c = ch.codePointAt(0);
+        if ((c >= 0x4e00 && c <= 0x9fff) || (c >= 0x3400 && c <= 0x4dbf) ||
+            (c >= 0x3000 && c <= 0x303f) || (c >= 0xff00 && c <= 0xffef))
+            cjk += 1;
+    }
+    return cjk + Math.ceil((text.length - cjk) / 4);
+}
+function readJsonl(root, file, coerce) {
+    const out = [];
+    for (const target of [rotatedFile(file), file]) {
+        let raw;
+        try {
+            raw = fs.readFileSync(target, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const line of raw.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const parsed = coerce(JSON.parse(trimmed));
+                if (parsed !== null)
+                    out.push(parsed);
+            }
+            catch {
+                /* 坏行跳过（轮转竞争/手工编辑残留） */
+            }
+        }
+    }
+    return out;
+}
+function asString(v) {
+    return typeof v === "string" ? v : undefined;
+}
+function coerceUsage(raw) {
+    const tool = asString(raw.tool);
+    const ts = asString(raw.ts);
+    if (!tool || !ts)
+        return null;
+    return {
+        ts,
+        tool,
+        kind: raw.kind === "write" || raw.kind === "write-async" ? raw.kind : "read",
+        ok: raw.ok === true,
+        ms: typeof raw.ms === "number" && Number.isFinite(raw.ms) ? raw.ms : 0,
+        ...(typeof raw.out_chars === "number" ? { out_chars: raw.out_chars } : {}),
+        ...(typeof raw.est_tokens === "number" ? { est_tokens: raw.est_tokens } : {}),
+        ...(typeof raw.folded_chars === "number" ? { folded_chars: raw.folded_chars } : {}),
+        ...(typeof raw.folded_tokens === "number" ? { folded_tokens: raw.folded_tokens } : {}),
+        ...(raw.replayed === true ? { replayed: true } : {}),
+        ...(raw.pending === true ? { pending: true } : {}),
+        ...(raw.uncertain === true ? { uncertain: true } : {}),
+        ...(asString(raw.error) ? { error: asString(raw.error) } : {}),
+    };
+}
+function coerceRuntime(raw) {
+    const ts = asString(raw.ts);
+    const event = asString(raw.event);
+    const level = raw.level === "info" || raw.level === "warn" || raw.level === "error" ? raw.level : null;
+    if (!ts || !event || !level)
+        return null;
+    return { ts, level, event, ...(asString(raw.detail) ? { detail: asString(raw.detail) } : {}) };
+}
+/** 读全部保留的使用日志（轮转份 + 当前份，按时间序） */
+export function loadUsageEntries(root) {
+    return readJsonl(root, pmPath(root, USAGE_LOG), coerceUsage);
+}
+export function loadRuntimeEntries(root) {
+    return readJsonl(root, pmPath(root, RUNTIME_LOG), coerceRuntime);
+}
+export function usageSummary(entries) {
+    const calls = entries.length;
+    const errors = entries.filter((e) => !e.ok).length;
+    const totalMs = entries.reduce((sum, e) => sum + e.ms, 0);
+    const slowest = entries.reduce((best, e) => (best === null || e.ms > best.ms ? e : best), null);
+    const estTokensOut = entries.reduce((sum, e) => sum + (e.est_tokens ?? 0), 0);
+    const estTokensSaved = entries.reduce((sum, e) => sum + (e.folded_tokens ?? 0), 0);
+    const byTool = new Map();
+    for (const e of entries) {
+        const bucket = byTool.get(e.tool) ?? { calls: 0, errors: 0, ms: 0 };
+        bucket.calls += 1;
+        if (!e.ok)
+            bucket.errors += 1;
+        bucket.ms += e.ms;
+        byTool.set(e.tool, bucket);
+    }
+    const topTools = [...byTool.entries()]
+        .map(([tool, b]) => ({ tool, calls: b.calls, errors: b.errors, avgMs: Math.round(b.ms / Math.max(1, b.calls)) }))
+        .sort((a, b) => b.calls - a.calls || a.tool.localeCompare(b.tool))
+        .slice(0, 8);
+    return {
+        calls,
+        errors,
+        errorRate: calls === 0 ? 0 : errors / calls,
+        avgMs: calls === 0 ? 0 : Math.round(totalMs / calls),
+        maxMs: slowest?.ms ?? 0,
+        slowestTool: slowest?.tool ?? "",
+        estTokensOut,
+        estTokensSaved,
+        savePct: estTokensOut + estTokensSaved === 0 ? 0 : estTokensSaved / (estTokensOut + estTokensSaved),
+        replayed: entries.filter((e) => e.replayed).length,
+        pending: entries.filter((e) => e.pending).length,
+        uncertain: entries.filter((e) => e.uncertain).length,
+        folds: entries.filter((e) => (e.folded_chars ?? 0) > 0).length,
+        topTools,
+    };
+}
+/** 过滤出明细（汇总始终基于全部保留日志，明细才吃 filter） */
+export function filterUsage(entries, filter) {
+    let list = entries;
+    if (filter.tool)
+        list = list.filter((e) => e.tool === filter.tool);
+    if (filter.ok !== undefined)
+        list = list.filter((e) => e.ok === filter.ok);
+    if (filter.since)
+        list = list.filter((e) => e.ts >= filter.since);
+    const last = filter.last ?? 20;
+    return list.slice(-last).reverse();
+}
+export function filterRuntime(entries, filter) {
+    let list = entries;
+    if (filter.level)
+        list = list.filter((e) => e.level === filter.level);
+    if (filter.event)
+        list = list.filter((e) => e.event === filter.event);
+    if (filter.since)
+        list = list.filter((e) => e.ts >= filter.since);
+    const last = filter.last ?? 20;
+    return list.slice(-last).reverse();
+}
+/* ------------------------------ 渲染（供工具层） ------------------------------ */
+function fmtK(n) {
+    return n >= 10000 ? `${(n / 1000).toFixed(0)}k` : n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n);
+}
+function fmtPct(rate) {
+    return `${(rate * 100).toFixed(rate < 0.1 && rate > 0 ? 1 : 0)}%`;
+}
+function outcomeMark(e) {
+    if (!e.ok)
+        return "❌";
+    if (e.uncertain)
+        return "⚠️";
+    if (e.replayed)
+        return "↩️";
+    if (e.pending)
+        return "⏳";
+    return "✅";
+}
+export function renderUsageLogLines(root, filter) {
+    const entries = loadUsageEntries(root);
+    if (entries.length === 0) {
+        return [
+            "（使用日志为空：还没有记录到工具调用；日志在项目初始化后自动开始记录。）",
+            "提示: 本日志只记工具名与计量（耗时/输出量），不记录参数内容。",
+        ];
+    }
+    const summary = usageSummary(entries);
+    const list = filterUsage(entries, filter);
+    const conditions = [
+        filter.tool ? `工具=${filter.tool}` : "",
+        filter.ok !== undefined ? `结果=${filter.ok ? "成功" : "失败"}` : "",
+        filter.since ? `since=${filter.since}` : "",
+    ].filter(Boolean).join(" · ");
+    const L = [];
+    L.push(`## 使用日志汇总（保留 ${entries.length} 次调用）`);
+    L.push(`- 调用 ${summary.calls} 次 · 失败 ${summary.errors} 次（${fmtPct(summary.errorRate)}）· 平均 ${summary.avgMs}ms · 最慢 ${summary.maxMs}ms（${summary.slowestTool}）`);
+    L.push(`- 幂等复用 ${summary.replayed} 次 · 等待占位 ${summary.pending} 次 · 不确定 ${summary.uncertain} 次 · 发生折叠 ${summary.folds} 次`);
+    L.push(`- 估算输出 tokens ≈ ${fmtK(summary.estTokensOut)} · 折叠省下 ≈ ${fmtK(summary.estTokensSaved)}（占总产出 ${fmtPct(summary.savePct)}）——省 token 主要来自输出折叠与过滤引导`);
+    if (summary.topTools.length > 0) {
+        L.push(`- 热门工具: ${summary.topTools.map((t) => `${t.tool}×${t.calls}${t.errors > 0 ? `(${t.errors}败)` : ""}`).join(" · ")}`);
+    }
+    L.push("");
+    L.push(`## 明细（最近 ${list.length} 条${conditions ? `，过滤: ${conditions}` : ""}）`);
+    if (list.length === 0)
+        L.push("（无匹配条目，放宽过滤条件试试。）");
+    for (const e of list) {
+        const parts = [
+            e.ts.slice(0, 19),
+            `${outcomeMark(e)} ${e.tool}`,
+            `${e.ms}ms`,
+            e.out_chars !== undefined ? `输出 ${fmtK(e.out_chars)} 字/tok≈${fmtK(e.est_tokens ?? 0)}` : "",
+            (e.folded_tokens ?? 0) > 0 ? `折叠省 tok≈${fmtK(e.folded_tokens)}` : "",
+            e.error ? `错误: ${e.error.slice(0, 160)}` : "",
+        ].filter(Boolean);
+        L.push(parts.join(" "));
+    }
+    return L;
+}
+export function renderRuntimeLogLines(root, filter) {
+    const entries = loadRuntimeEntries(root);
+    if (entries.length === 0) {
+        return ["（运行日志为空：服务级事件（启动、watcher、工具报错）会在项目初始化后自动记录。）"];
+    }
+    const counts = { info: 0, warn: 0, error: 0 };
+    for (const e of entries)
+        counts[e.level] += 1;
+    const list = filterRuntime(entries, filter);
+    const conditions = [
+        filter.level ? `level=${filter.level}` : "",
+        filter.event ? `event=${filter.event}` : "",
+        filter.since ? `since=${filter.since}` : "",
+    ].filter(Boolean).join(" · ");
+    const L = [];
+    L.push(`## 运行日志（保留 ${entries.length} 条：info ${counts.info} · warn ${counts.warn} · error ${counts.error}）`);
+    if (counts.error > 0) {
+        const lastError = [...entries].reverse().find((e) => e.level === "error");
+        if (lastError)
+            L.push(`- 最近 error: ${lastError.ts.slice(0, 19)} ${lastError.event} ${lastError.detail ?? ""}`.trimEnd());
+    }
+    L.push("");
+    L.push(`## 明细（最近 ${list.length} 条${conditions ? `，过滤: ${conditions}` : ""}）`);
+    if (list.length === 0)
+        L.push("（无匹配条目，放宽过滤条件试试。）");
+    for (const e of list) {
+        L.push([e.ts.slice(0, 19), `[${e.level}]`, e.event, e.detail ?? ""].filter(Boolean).join(" ").trimEnd());
+    }
+    return L;
+}

package/dist/version.js

@@ -0,0 +1,10 @@
+import fs from "node:fs";
+// src/ 与发布后的 dist/ 共用包根，避免服务端与安装器各自硬编码版本。
+const metadata = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+export const SERVER_NAME = "pm-mcp";
+export const VERSION = metadata.version;
+export const PACKAGE_SPEC = `${metadata.name}@${VERSION}`;
+export const RUNTIME_CONTRACT = "pagination-evidence-v1";
+// 服务器工具目录契约（doctor 与独立巡检 health-check 都以此核对）。
+// 新增/移除 MCP 工具时必须同步更新这里，并用 `pm-mcp probe` 实测复核。
+export const TOOL_CATALOG_SIZE = 49;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckychen1993/pm-mcp",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "description": "AI 编码项目的单一事实来源 + 健康台账 MCP 服务（事实来源 / 路线图 / 防幻觉 / 七本账 / 断点续做 / token 经济）",
   "keywords": [
     "mcp",
@@ -32,12 +32,15 @@
   "engines": {
     "node": ">=22.18.0"
   },
+  "pm_mcp": {
+    "acceptance_baseline": { "id": "pm-mcp-local-release", "version": "1.1.0" }
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "prepare": "npm run build",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.scripts.json",
-    "test": "node --test \"test/*.test.ts\"",
-    "coverage": "node --experimental-test-coverage --test-coverage-include=\"src/**/*.ts\" --test-coverage-lines=90 --test-coverage-branches=85 --test-coverage-functions=90 --test \"test/*.test.ts\"",
+    "test": "node --test-concurrency=2 --test \"test/*.test.ts\"",
+    "coverage": "node --experimental-test-coverage --test-coverage-include=\"src/**/*.ts\" --test-coverage-lines=90 --test-coverage-branches=85 --test-coverage-functions=90 --test-concurrency=2 --test \"test/*.test.ts\"",
     "audit": "node scripts/health-check.mts",
     "benchmark": "node scripts/benchmark.mts",
     "benchmark:volume": "node scripts/benchmark-volume.mts",
@@ -45,7 +48,7 @@
     "quality:plan": "node scripts/quality-gate.mts --plan",
     "acceptance:evidence": "node scripts/collect-acceptance-evidence.mts --root .",
     "acceptance:prepare": "node scripts/create-pm-acceptance-evaluation.mts --root .",
-    "acceptance": "node scripts/acceptance-gate.mts --root . --baseline-id pm-mcp-local-release --baseline-version 1.0.0 --evaluation .pm/acceptance/evaluations/pm-mcp-local-release-1.0.0.json",
+    "acceptance": "node scripts/acceptance-cycle.mts --root .",
     "acceptance:cycle": "node scripts/acceptance-cycle.mts --root .",
     "gate": "npm run audit -- --root . && npm run quality && npm run acceptance:cycle",
     "start": "node dist/index.js",