@luckychen1993/pm-mcp 0.1.3 → 0.1.5

package/dist/tool-base.js

@@ -1,14 +1,49 @@
 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) => {
+        const started = Date.now();
         try {
             const result = await runCoalescedRead(root, name, args, fn);
+            recordUsage(root, name, "read", started, {
+                ok: !result.pending,
+                text: result.text,
+                replayed: result.replayed,
+                pending: result.pending,
+                uncertain: result.uncertain,
+            });
             return { content: [{ type: "text", text: result.text }] };
         }
         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 };
         }
     }));
 }
@@ -20,28 +55,52 @@ function writeSchema(schema) {
     };
 }
 /** 同步写工具：业务幂等占位 + 跨进程账本锁覆盖完整读-改-写。 */
-export function toolW(server, root, name, description, schema, fn) {
+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);
+            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 }] };
+            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 }] };
+            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/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/watcher-coordinator.js

@@ -0,0 +1,182 @@
+import fs from "node:fs";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+const ELECTION_POLL_MS = 1_000;
+const ELECTION_BUSY_MS = 20;
+export function watcherDirtyFile(root) {
+    return path.join(path.resolve(root), ".pm", ".runtime", "watcher-dirty");
+}
+export function markWatcherDirty(root) {
+    const file = watcherDirtyFile(root);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${new Date().toISOString()}\n`, "utf8");
+}
+export function clearWatcherDirty(root) {
+    try {
+        fs.rmSync(watcherDirtyFile(root));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+export function watcherIsClean(root) {
+    return !fs.existsSync(watcherDirtyFile(root));
+}
+function sqliteBusy(error) {
+    const candidate = error;
+    return candidate.errcode === 5 ||
+        (typeof candidate.message === "string" && /database is (?:locked|busy)/i.test(candidate.message));
+}
+function openElection(root) {
+    const file = path.join(path.resolve(root), ".pm", ".runtime", "watcher-leader.db");
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const db = new DatabaseSync(file);
+    try {
+        db.exec(`PRAGMA busy_timeout=${ELECTION_BUSY_MS}`);
+        return db;
+    }
+    catch (error) {
+        try {
+            db.close();
+        }
+        catch { /* best effort */ }
+        throw error;
+    }
+}
+function acquire(db) {
+    if (db.isTransaction)
+        return true;
+    try {
+        // Avoid startup DDL so late standbys can join while a leader holds the DB.
+        // The transactional header write forces ownership even when an empty DB
+        // would otherwise defer materializing the write reservation on this OS.
+        db.exec("BEGIN IMMEDIATE");
+        db.exec("PRAGMA user_version=1");
+        return true;
+    }
+    catch (error) {
+        if (db.isTransaction) {
+            try {
+                db.exec("ROLLBACK");
+            }
+            catch { /* close remains the fail-safe */ }
+        }
+        if (sqliteBusy(error))
+            return false;
+        throw error;
+    }
+}
+function release(db) {
+    if (db.isTransaction)
+        db.exec("ROLLBACK");
+}
+/**
+ * Elect exactly one watcher with a dedicated SQLite write transaction held for
+ * its lifetime. The OS releases the transaction after a force kill; standbys
+ * poll and take over without PID guesses, leases, or stale-file deletion.
+ */
+export function coordinateWatcherLeader(root, activate, report) {
+    let election;
+    try {
+        election = openElection(root);
+    }
+    catch (error) {
+        report("leader election unavailable", error);
+        return null;
+    }
+    let cleanup = null;
+    let timer = null;
+    let stopped = false;
+    let unavailable = false;
+    const relinquish = () => {
+        try {
+            cleanup?.();
+        }
+        catch (error) {
+            report("leader cleanup", error);
+        }
+        cleanup = null;
+        try {
+            release(election);
+        }
+        catch (error) {
+            report("leadership release", error);
+            unavailable = true;
+            try {
+                election.close();
+            }
+            catch { /* OS close releases the transaction */ }
+        }
+    };
+    const elect = () => {
+        if (stopped || unavailable || cleanup)
+            return;
+        let acquired = false;
+        try {
+            acquired = acquire(election);
+        }
+        catch (error) {
+            report("leader election", error);
+            unavailable = true;
+            stopped = true;
+            if (timer)
+                clearInterval(timer);
+            timer = null;
+            try {
+                election.close();
+            }
+            catch { /* best effort */ }
+            return;
+        }
+        if (!acquired)
+            return;
+        try {
+            const activated = activate();
+            if (!activated)
+                unavailable = true;
+            else
+                cleanup = activated;
+        }
+        catch (error) {
+            report("leader activation", error);
+        }
+        if (!cleanup)
+            relinquish();
+        if (unavailable) {
+            if (timer)
+                clearInterval(timer);
+            timer = null;
+            stopped = true;
+            try {
+                election.close();
+            }
+            catch { /* best effort */ }
+        }
+    };
+    elect();
+    if (unavailable) {
+        try {
+            election.close();
+        }
+        catch { /* best effort */ }
+        return null;
+    }
+    timer = setInterval(elect, ELECTION_POLL_MS);
+    timer.unref();
+    return {
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            if (timer)
+                clearInterval(timer);
+            timer = null;
+            relinquish();
+            try {
+                election.close();
+            }
+            catch { /* best effort */ }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckychen1993/pm-mcp",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "AI 编码项目的单一事实来源 + 健康台账 MCP 服务（事实来源 / 路线图 / 防幻觉 / 七本账 / 断点续做 / token 经济）",
   "keywords": [
     "mcp",