@luckychen1993/pm-mcp 0.1.4 → 0.1.5

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 pm-mcp contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 pm-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -32,6 +32,8 @@ AI 编码项目的典型失控（本工具逐一给出机制）：
 
 ## 一个命令自动添加到 AI 编程助手
 
+本页安装示例固定使用 **0.1.5**，包含安全扫描、项目命名和字面量搜索修复。0.1.4 不支持 `setup --project`；验证这些能力时请确认实际运行版本为 0.1.5 或更新版本。
+
 要求：Node.js ≥ 22.18。Windows、macOS 和 Linux 使用同一条命令：
 
 ```bash
@@ -46,6 +48,16 @@ npx -y @luckychen1993/pm-mcp@latest setup --dry-run
 
 非标准安装路径无法自动发现时，可在同一命令末尾指定 `--client codex|claude|zcode|cursor|vscode`；`--client print` 输出通用 MCP JSON。首次启动由 `npx` 下载并在本机运行，pm-mcp 本身不需要 API Key，也不会调用远程模型。
 
+### 新项目一条命令上手（Codex 必用）
+
+Codex 桌面版启动 MCP 服务时不带工作区路径，逐项目钉根才能用。在项目目录里跑一条命令，自动完成「注册钉定条目 + 初始化 .pm + 写 AGENTS.md 工作规矩」：
+
+```bash
+npx -y @luckychen1993/pm-mcp@0.1.5 setup --client codex --project
+```
+
+跑完完全重启 Codex，新会话即可用（工具名前缀 `pm-mcp-<目录名>-<路径摘要>`）。不同中文目录和同名目录独立注册；重复执行会核对项目路径，匹配的旧版条目仍可复用。
+
 ### 客户端官方命令（自动检测失败时备用）
 
 #### Codex / ChatGPT 桌面版 / Codex IDE 扩展
@@ -53,7 +65,7 @@ npx -y @luckychen1993/pm-mcp@latest setup --dry-run
 Codex 的本地客户端共享同一份 MCP 配置。复制执行：
 
 ```bash
-codex mcp add pm-mcp -- npx -y @luckychen1993/pm-mcp@0.1.4
+codex mcp add pm-mcp -- npx -y @luckychen1993/pm-mcp@0.1.5
 ```
 
 重启客户端后可用 `codex mcp list` 检查。该命令遵循 [OpenAI 官方 MCP CLI 格式](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)。
@@ -61,7 +73,7 @@ codex mcp add pm-mcp -- npx -y @luckychen1993/pm-mcp@0.1.4
 #### Claude Code
 
 ```bash
-claude mcp add pm-mcp --scope user -- npx -y @luckychen1993/pm-mcp@0.1.4
+claude mcp add pm-mcp --scope user -- npx -y @luckychen1993/pm-mcp@0.1.5
 ```
 
 #### ZCode、Cursor、VS Code（Windows 备用脚本）
@@ -69,7 +81,7 @@ claude mcp add pm-mcp --scope user -- npx -y @luckychen1993/pm-mcp@0.1.4
 将 `<client>` 替换为 `zcode`、`cursor` 或 `vscode`，整行复制到 PowerShell：
 
 ```powershell
-$u='https://raw.githubusercontent.com/happy520ai/pm-mcp/v0.1.4/install.ps1'; $f=Join-Path $env:TEMP 'install-pm-mcp.ps1'; Invoke-WebRequest $u -OutFile $f; & $f -Client <client>
+$u='https://raw.githubusercontent.com/happy520ai/pm-mcp/v0.1.5/install.ps1'; $f=Join-Path $env:TEMP 'install-pm-mcp.ps1'; Invoke-WebRequest $u -OutFile $f; & $f -Client <client>
 ```
 
 脚本只写对应客户端的 MCP 配置；已有 JSON 配置会先生成带时间戳的备份。建议执行前先打开 [`install.ps1`](install.ps1) 审阅。ZCode 默认写入 `$ZCODE_HOME/cli/config.json` 或 `~/.zcode/cli/config.json`，Cursor 默认写入 `~/.cursor/mcp.json`；也可用 `-ConfigPath` 指定路径。
@@ -81,7 +93,7 @@ $u='https://raw.githubusercontent.com/happy520ai/pm-mcp/v0.1.4/install.ps1'; $f=
   "mcpServers": {
     "pm-mcp": {
       "command": "npx",
-      "args": ["-y", "@luckychen1993/pm-mcp@0.1.4"],
+      "args": ["-y", "@luckychen1993/pm-mcp@0.1.5"],
       "env": {}
     }
   }
@@ -131,7 +143,7 @@ snapshot_codebase + audit_structure 对账；audit_security 安全体检；audit
 
 也可以直接用内置 prompts：`start-session` / `end-session` / `onboard` / `architecture-review` / `acceptance-review`；其中 `onboard` 会引导客户端读取状态并生成新人/AI 入职简报。
 
-## 工具清单（46 个）
+## 工具清单（48 个）
 
 | 域 | 工具 | 说明 |
 |---|---|---|
@@ -146,6 +158,7 @@ snapshot_codebase + audit_structure 对账；audit_security 安全体检；audit
 | 审计 | `snapshot_codebase` / `audit_structure` | 结构快照；完整性/增长/漂移/债务/churn/复杂度/索引/足迹/测试/Git 十节对账 |
 | 安全 | `audit_security` / `list_findings` / `resolve_finding` | 密钥+危险模式+新增/通配依赖提示；扫描命中原文不落盘，处置 note 拒绝内置密钥形态 |
 | 法律 | `audit_license` | 依赖许可证清单、copyleft 冲突、GPL 头检测、LICENSE 检查、来源登记 |
+| 可观测 | `get_usage_log` / `get_runtime_log` | 使用日志（工具调用统计、错误率、耗时、输出与折叠省下的 token 估算——验证省不省 token）与运行日志（server/watcher/工具报错）；只记计量不记参数内容 |
 | 注册表 | `list_projects` | 本机所有被管理项目 |
 | 治理模型 | `init_governance` / `get_governance` / `upsert_module` / `upsert_interface` / `upsert_repository` / `set_governance_policies` | 结构化模块根、owner、语言、公开接口、允许/禁止依赖、跨仓版本约束与强制策略 |
 | 语义治理 | `discover_languages` / `audit_governance` / `impact_analysis` / `list_semantic_evidence` / `save_semantic_evidence` | 编译器/Tree-sitter AST 关系、hash-bound 原生分析器/运行时证据、循环/越界/unresolved/覆盖率与变更反向闭包 |
@@ -312,7 +325,7 @@ npm run gate          # 完整本地门禁
 | 单元 | budget/store/roadmap/health/security/license/audit/search/dashboard | 各账本与机制的正确性（含伪造密钥/危险模式 fixture、已识别命中原文不落盘断言） |
 | 治理 | governance-model/language-adapters/semantic-graph/semantic-evidence/polyglot-ast/portfolio/governance-audit | 模块 schema、八语言 AST、symbol-bound call、原生/runtime证据、私有接口、循环、影响闭包、semver 与跨仓 fail-closed |
 | 标准化验收 | acceptance-evaluator/acceptance-tools/acceptance-gate/quality-evidence | 九特性/五阶段、冻结指标与断言、双向追踪、风险接受、源码/证据/报告 SHA-256、伪造 PASS 失败 |
-| 集成 | integration/governance-mcp/quality-gate | 真实拉起 stdio server 全链路：46 工具、7 资源、5 提示词；真实执行安全 argv 质量命令 |
+| 集成 | integration/governance-mcp/quality-gate | 真实拉起 stdio server 全链路：48 工具、7 资源、5 提示词；真实执行安全 argv 质量命令 |
 | 场景 | scenario.test.ts | **对 dist 产物**跑三段会话生命周期：中文+空格路径、CRLF、断点跨进程恢复、故障注入（删测试/加 skip/删入口文件/新增依赖/伪造密钥/GPL 头）、三种根解析方式（cwd / PM_ROOT / --root）各用一遍 |
 | 完整性 + 真实仓库 | integrity.test.ts / realrepo.test.ts | 状态不变式（全账本 schema、派生逐字节一致、原子性、损坏恢复、500 任务规模折叠、并发双进程零丢失）；并以本仓库真实 `.pm` 为被测对象（漂移为零、PROJECT.md 同步、done 纪律、全仓拷贝审计不误报） |
 | 钻空（红队） | exploit.test.ts | 每个反制机制配一个「先钻、再断言钻不进」的测试（见上表） |

package/dist/agents-md.js

@@ -0,0 +1,51 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * AGENTS.md 工作规矩：init_project 时自动写入/合并（"项目开启即有规矩"）。
+ * - 文件不存在 → 创建
+ * - 已存在且无标记段 → 末尾追加（绝不覆盖你的内容）
+ * - 已存在且有标记段 → 原样保留（幂等；模板升级时用新版本号标记替换）
+ */
+const BEGIN = "<!-- pm-mcp:agents-md:v1:begin -->";
+const END = "<!-- pm-mcp:agents-md:v1:end -->";
+const SECTION = `${BEGIN}
+# 项目管理规矩（pm-mcp 自动维护段落，可整体删除但不建议）
+
+本项目由 pm-mcp 管理，状态以 .pm/ 目录为准，禁止凭记忆陈述项目状态。
+
+## 开工（每次会话第一件事）
+1. get_status：了解阶段、里程碑、进行中任务与其 checkpoint 下一步
+2. 不清楚的模块先 search_code 定位到 file:line 再读文件，不要全量读代码
+3. 陈述本次计划：做哪个任务、动哪些文件、验收标准
+
+## 做事过程
+- 长任务：add_task 时给 steps；上下文快满或中断前 checkpoint 存断点
+- 走捷径：立刻 add_task(type=debt) 登记债务，不许无声欠债
+- 修 bug：完成后 log_debug 记录症状/根因/修法/验证
+- 陈述「某功能在某文件」之前，先 search_code 求证
+
+## 收工（缺一不可）
+1. 完成的任务 update_task 置 done + result_note；feature/fix 补 verification
+2. 未完成任务 checkpoint（进展 + 下一步具体动作）
+3. 落地的功能 register_feature（入口文件 + 测试文件）
+4. log_session 如实记录改动文件清单
+
+## 每个里程碑节点
+snapshot_codebase + audit_structure 对账；audit_security 安全体检；audit_license 许可证审计
+${END}`;
+/** 幂等 upsert：返回发生了什么（skipped = 调用方显式关闭） */
+export function upsertAgentsMd(root, enabled = true) {
+    if (!enabled)
+        return "skipped";
+    const file = path.join(root, "AGENTS.md");
+    if (!fs.existsSync(file)) {
+        fs.writeFileSync(file, SECTION + "\n", "utf8");
+        return "created";
+    }
+    const content = fs.readFileSync(file, "utf8");
+    if (content.includes(BEGIN))
+        return "unchanged";
+    const separator = content.endsWith("\n") ? "" : "\n";
+    fs.writeFileSync(file, content + separator + "\n" + SECTION + "\n", "utf8");
+    return "appended";
+}

package/dist/budget.js

@@ -1,4 +1,32 @@
 import { relative as pathRelative } from "node:path";
+import { estimateTokens } from "./usage-log.js";
+/**
+ * token 经济：读类工具输出硬预算。
+ * 超出预算自动折叠为 "Top N + 另有 M 项已折叠"，引导模型用过滤参数缩小范围。
+ * 折叠/截断省下的字符与 token 会记账，供使用日志统计「省了多少 token」。
+ */
+let foldSavedChars = 0;
+let foldSavedTokens = 0;
+function noteFoldSavings(full, out) {
+    const savedChars = full.length - out.length;
+    if (savedChars <= 0)
+        return;
+    foldSavedChars += savedChars;
+    foldSavedTokens += Math.max(0, estimateTokens(full) - estimateTokens(out));
+}
+/**
+ * 取走自上次调用以来折叠/截断省下的字符与 token（估算）。
+ * 单进程内计数：并发异步调用之间的归因可能漂移，但总量精确（每次折叠恰好记一次）。
+ * 工具包装器在业务函数返回后调用，把省量归到本次工具调用。
+ */
+export function drainFoldSavings() {
+    if (foldSavedChars <= 0)
+        return null;
+    const out = { chars: foldSavedChars, tokens: foldSavedTokens };
+    foldSavedChars = 0;
+    foldSavedTokens = 0;
+    return out;
+}
 /** 限制字符串单行长度，超长截断（防止一行巨长文件吃 token） */
 export function capLine(line, maxChars = 300) {
     if (line.length <= maxChars)
@@ -12,8 +40,11 @@ export function capLine(line, maxChars = 300) {
 export function foldLines(lines, opts) {
     const { maxLines, hint } = opts;
     const capped = lines.map((l) => capLine(l));
-    if (capped.length <= maxLines)
-        return capped.join("\n");
+    if (capped.length <= maxLines) {
+        const out = capped.join("\n");
+        noteFoldSavings(lines.join("\n"), out);
+        return out;
+    }
     const keep = Math.max(1, Math.floor(maxLines * 0.8));
     const tail = Math.max(0, maxLines - keep - 1);
     const hidden = capped.length - keep - tail;
@@ -21,7 +52,9 @@ export function foldLines(lines, opts) {
     parts.push(`…（另有 ${hidden} 项已折叠${hint ? "，" + hint : ""}，请用过滤参数缩小范围）`);
     if (tail > 0)
         parts.push(...capped.slice(-tail));
-    return parts.join("\n");
+    const out = parts.join("\n");
+    noteFoldSavings(lines.join("\n"), out);
+    return out;
 }
 /** 对整段文本按行折叠 */
 export function foldText(text, maxLines, hint) {

package/dist/index.js

@@ -15,6 +15,8 @@ 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";
 /* --root 参数 > PM_ROOT 环境变量 > 启动时工作目录 */
 const argv = process.argv.slice(2);
 let explicitRoot;
@@ -23,7 +25,7 @@ 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: "0.1.5" }, {
     instructions: [
         "多 Agent 规则：相同业务的所有写工具调用必须携带相同 idempotency_key（建议 task-id:operation）；同键同参数只执行一次，同键不同参数会被拒绝。",
         "完全相同的并行读请求会由服务端合并并复用结果；不要让多个分支重复请求同一工具和参数。",
@@ -41,7 +43,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: [
@@ -216,6 +227,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/paths.js

@@ -57,7 +57,7 @@ export function ensurePmRuntimeIgnored(root) {
     fs.mkdirSync(directory, { recursive: true });
     fs.mkdirSync(path.join(directory, ".runtime", "idempotency"), { recursive: true });
     const file = path.join(directory, ".gitignore");
-    const required = [".lock", ".runtime/", "benchmarks/", "index.db*"];
+    const required = [".lock", ".runtime/", "benchmarks/", "index.db*", "usage-log*.jsonl*", "runtime-log*.jsonl*"];
     for (let attempt = 0; attempt < 3; attempt += 1) {
         const current = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
         const lines = current.split(/\r?\n/).map((line) => line.trim());

package/dist/project-tools.js

@@ -8,6 +8,7 @@ import { loadGovernance } from "./governance-model.js";
 import { loadProject, loadRoadmap, loadSecurity, loadSessions, loadTasks, saveProject, saveRoadmap, } from "./store.js";
 import { now } from "./types.js";
 import { budgetLines, toolI, toolR, toolW } from "./tool-base.js";
+import { renderRuntimeLogLines, renderUsageLogLines } from "./usage-log.js";
 function taskLine(t, withNext = false) {
     const parts = [`[${t.status}]`, t.id, t.title, `(${t.type}${t.milestone ? `,${t.milestone}` : ""})`];
     if (withNext && t.checkpoint) {
@@ -16,7 +17,7 @@ function taskLine(t, withNext = false) {
     return parts.join(" ");
 }
 export function registerProjectTools(server, root) {
-    toolW(server, root, "init_project", "初始化当前项目的 .pm/ 状态目录（单一事实来源）。每个新项目只调用一次；已初始化请用 update_project。", {
+    toolW(server, root, "init_project", "初始化当前项目的 .pm/ 状态目录（单一事实来源），并自动写入 AGENTS.md 工作规矩（已存在则增量合并，不覆盖你的内容）。每个新项目只调用一次；已初始化请用 update_project。", {
         name: z.string().min(1).describe("项目名"),
         description: z.string().optional().describe("一句话描述"),
         stack: z.array(z.string()).optional().describe("技术栈，如 [\"TypeScript\",\"React\"]"),
@@ -24,13 +25,15 @@ export function registerProjectTools(server, root) {
         license: z.string().optional().describe("项目许可证（SPDX 名，如 MIT）"),
         exposure: z.enum(["local", "network", "public"]).optional().describe("暴露面，影响安全告警力度"),
         modules: z.array(z.string()).optional().describe("初始模块登记"),
+        agents_md: z.boolean().optional().describe("默认 true：自动写入/合并 AGENTS.md 工作规矩（false 关闭）"),
     }, (args) => {
-        const project = initProject(root, args);
+        const project = initProject(root, { ...args, agentsMd: args.agents_md });
         refreshDerived(root);
         return [
             `✅ 项目已初始化: ${project.name}`,
             `状态目录: ${pmPath(root, "")}（随 git 提交，团队/AI 共享）`,
             "仪表盘已生成: PROJECT.md",
+            args.agents_md === false ? "AGENTS.md 规矩：按要求跳过（agents_md:false）" : "AGENTS.md 工作规矩已写入（已存在则合并；ZCode 每次打开该项目自动加载）",
             "建议顺序: upsert_module 声明模块/owner/语言 → add_milestone 建里程碑 → add_task 拆任务 → 开工前 get_status / 收工后 log_session。",
         ].join("\n");
     });
@@ -95,6 +98,24 @@ export function registerProjectTools(server, root) {
         L.push("> 三段式定位：本状态 → search_code 精确到行 → 才读具体文件。别全量读代码。");
         return foldLines(L, { maxLines: budgetLines(root) });
     });
+    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"),
+        ok: z.boolean().optional().describe("true 只看成，false 只看败"),
+        since: z.string().optional().describe("ISO 日期/时间，只看该时间之后的明细"),
+    }, (args) => {
+        requireInitialized(root);
+        return foldLines(renderUsageLogLines(root, args), { maxLines: budgetLines(root) });
+    });
+    toolR(server, root, "get_runtime_log", "运行日志：server 就绪、watcher 状态、工具报错等服务级事件（info/warn/error），判断 pm-mcp 运行是否健康、哪里在反复出错。", {
+        last: z.number().int().min(1).max(200).optional().describe("返回最近 N 条明细（默认 20）"),
+        level: z.enum(["info", "warn", "error"]).optional().describe("只看某级别"),
+        event: z.string().optional().describe("只看某事件，如 tool.error / server.ready"),
+        since: z.string().optional().describe("ISO 日期/时间，只看该时间之后的明细"),
+    }, (args) => {
+        requireInitialized(root);
+        return foldLines(renderRuntimeLogLines(root, args), { maxLines: budgetLines(root) });
+    });
     toolW(server, root, "update_project", "更新项目元信息/预算（描述、技术栈、目标、阶段、模块登记、许可证、暴露面、复杂度与输出预算）。", {
         description: z.string().optional(),
         stack: z.array(z.string()).optional(),

package/dist/search.js

@@ -41,7 +41,7 @@ export function rgSearch(root, query, glob, maxResults, regex) {
     if (regex)
         args.push("-e", query);
     else
-        args.push("-F", query);
+        args.push("-F", "-e", query);
     if (glob)
         args.push("--glob", glob);
     args.push(".");

package/dist/security.js

@@ -1,3 +1,5 @@
+import fs from "node:fs";
+import path from "node:path";
 import { createHash } from "node:crypto";
 import { loadExtraRules, loadProject, loadSecurity, saveSecurity } from "./store.js";
 import { latestSnapshot } from "./audit.js";
@@ -69,8 +71,37 @@ function findSecretRule(value) {
 function fingerprint(ruleId, rel, matched) {
     return createHash("sha1").update(ruleId + "|" + rel + "|" + matched).digest("hex").slice(0, 16);
 }
+/** 只有根内普通路径的 ENOENT 才证明删除；权限错误、目录和链接均不证明修复。 */
+function findingFileState(root, rel) {
+    const parts = rel.replace(/\\/g, "/").split("/");
+    if (path.isAbsolute(rel) || parts.some((part) => !part || part === "." || part === ".."))
+        return "unknown";
+    let current = root;
+    let stat;
+    for (const part of parts) {
+        current = path.join(current, part);
+        try {
+            stat = fs.lstatSync(current);
+            if (stat.isSymbolicLink())
+                return "unknown";
+        }
+        catch (error) {
+            return error.code === "ENOENT" ? "missing" : "unknown";
+        }
+    }
+    return stat?.isFile() ? "file" : "unknown";
+}
 function scanDetections(root, forceContent = false, indexPrepared = false) {
     const out = [];
+    // 只跟踪已有 open 发现，不为百万文件仓库额外物化整棵扫描覆盖表。
+    const pending = loadSecurity(root).findings.filter((finding) => finding.status === "open");
+    const byFile = new Map();
+    for (const finding of pending) {
+        const entries = byFile.get(finding.file) ?? [];
+        entries.push(finding);
+        byFile.set(finding.file, entries);
+    }
+    const checkedFindings = new Map();
     const rules = [...SECRET_PATTERNS, ...DANGEROUS_PATTERNS];
     // 用户自定义规则
     for (const r of loadExtraRules(root).rules) {
@@ -113,6 +144,7 @@ function scanDetections(root, forceContent = false, indexPrepared = false) {
         const content = readText(root, rel, forceContent);
         if (content === null)
             continue;
+        const contentDigest = byFile.has(rel) ? createHash("sha256").update(content).digest("hex") : undefined;
         const lines = content.split("\n");
         for (const rule of rules) {
             if (rule.glob && !rule.glob.test(rel))
@@ -131,9 +163,18 @@ function scanDetections(root, forceContent = false, indexPrepared = false) {
                     message: rule.message,
                 });
             }
+            for (const finding of byFile.get(rel) ?? []) {
+                if (finding.rule === rule.id)
+                    checkedFindings.set(finding.fingerprint, contentDigest);
+            }
+        }
+    }
+    for (const finding of pending) {
+        if (!checkedFindings.has(finding.fingerprint) && findingFileState(root, finding.file) === "missing") {
+            checkedFindings.set(finding.fingerprint, null);
         }
     }
-    return out;
+    return { detections: out, checkedFindings };
 }
 /** 昂贵的全仓扫描阶段；调用方可在账本锁外完成，再把脱敏发现提交到账本。 */
 export function prepareSecurityAudit(root, options = {}) {
@@ -141,13 +182,14 @@ export function prepareSecurityAudit(root, options = {}) {
     const forceContent = options.forceContent ?? true;
     if (forceIndex)
         walkRefresh(root, { forceContent: true });
-    return { detections: scanDetections(root, forceContent, forceIndex || options.indexPrepared === true) };
+    return scanDetections(root, forceContent, forceIndex || options.indexPrepared === true);
 }
 /** 扫描并更新台账（幂等：重复扫描不产生重复条目） */
 export function auditSecurity(root, prepared) {
     const project = loadProject(root);
     const stamp = now();
-    const detections = prepared?.detections ?? scanDetections(root);
+    const scan = prepared ?? scanDetections(root);
+    const detections = scan.detections;
     const security = loadSecurity(root);
     const existing = new Map(security.findings.map((f) => [f.fingerprint, f]));
     const acceptedRefound = [];
@@ -186,10 +228,25 @@ export function auditSecurity(root, prepared) {
             });
         }
     }
-    // 不再检出且仍 open 的 → 自动转 fixed（附注说明）
+    // 没有命中不等于已修复：必须证明该旧发现的文件/规则已检查，或文件确已删除。
     let autoFixed = 0;
+    let unverified = 0;
+    const currentDigests = new Map();
     for (const f of security.findings) {
         if (f.status === "open" && !seen.has(f.fingerprint)) {
+            const expected = scan.checkedFindings?.get(f.fingerprint);
+            let confirmed = expected === null && findingFileState(root, f.file) === "missing";
+            if (typeof expected === "string") {
+                if (!currentDigests.has(f.file)) {
+                    const content = findingFileState(root, f.file) === "file" ? readText(root, f.file, true) : null;
+                    currentDigests.set(f.file, content === null ? null : createHash("sha256").update(content).digest("hex"));
+                }
+                confirmed = currentDigests.get(f.file) === expected;
+            }
+            if (!confirmed) {
+                unverified += 1;
+                continue;
+            }
             f.status = "fixed";
             f.note += "（自动：最近一次扫描未再检出）";
             autoFixed += 1;
@@ -236,7 +293,9 @@ export function auditSecurity(root, prepared) {
         }
     }
     if (autoFixed > 0)
-        L.push(`自动关闭 ${autoFixed} 个（代码中已不再出现）。`);
+        L.push(`自动关闭 ${autoFixed} 个（已成功重扫未命中或确认文件删除）。`);
+    if (unverified > 0)
+        L.push(`⚠️ 扫描覆盖不足：${unverified} 个旧发现未获得完整检查证据，保持未解决状态（检查文件大小、可读性、扫描范围和规则）。`);
     if (newDeps.length > 0)
         L.push(`⚠️ 上次快照后新增依赖: ${newDeps.join(", ")}（AI 引入的依赖请审查来源与必要性）`);
     if (riskyDeps.length > 0)

package/dist/setup.js

@@ -2,11 +2,15 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
-export const PACKAGE_SPEC = "@luckychen1993/pm-mcp@0.1.4";
+import { createHash, randomUUID } from "node:crypto";
+import { initProject } from "./init.js";
+import { isInitialized } from "./paths.js";
+import { refreshDerived } from "./dashboard.js";
+export const PACKAGE_SPEC = "@luckychen1993/pm-mcp@0.1.5";
 export const SERVER_NAME = "pm-mcp";
 const CLIENTS = ["codex", "claude", "zcode", "cursor", "vscode"];
 export function parseSetupArgs(argv) {
-    const options = { client: "auto", force: false, dryRun: false, help: false };
+    const options = { client: "auto", force: false, dryRun: false, help: false, project: false };
     for (let index = 0; index < argv.length; index += 1) {
         const arg = argv[index];
         if (arg === "--client") {
@@ -17,6 +21,14 @@ export function parseSetupArgs(argv) {
             options.client = value;
             index += 1;
         }
+        else if (arg === "--project") {
+            options.project = true;
+            const value = argv[index + 1];
+            if (value && !value.startsWith("--")) {
+                options.projectDir = value;
+                index += 1;
+            }
+        }
         else if (arg === "--force") {
             options.force = true;
         }
@@ -82,7 +94,7 @@ export function mergeJsonServer(document, shape) {
 }
 function backupName(file) {
     const stamp = new Date().toISOString().replace(/[-:.TZ]/g, "");
-    return `${file}.backup-${stamp}-${process.pid}`;
+    return `${file}.backup-${stamp}-${process.pid}-${randomUUID()}`;
 }
 export function writeJsonClientConfig(file, shape, dryRun = false) {
     const absolute = path.resolve(file);
@@ -146,6 +158,86 @@ function appendCodexConfig(file, dryRun, log) {
     const block = `${separator}\n[mcp_servers.${SERVER_NAME}]\ncommand = "npx"\nargs = ["-y", "${PACKAGE_SPEC}"]\n`;
     fs.appendFileSync(absolute, block, "utf8");
 }
+function canonicalProjectRoot(projectRoot) {
+    const absolute = path.resolve(projectRoot);
+    let resolved;
+    try {
+        resolved = fs.realpathSync.native(absolute);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        resolved = absolute;
+    }
+    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+function legacyProjectServerKey(projectRoot) {
+    const base = path.basename(projectRoot);
+    const safe = base.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+    return `${SERVER_NAME}-${safe || "project"}`;
+}
+/** 完整规范路径参与命名，区分中文目录和位于不同父目录下的同名项目。 */
+export function codexProjectServerKey(projectRoot) {
+    const canonical = canonicalProjectRoot(projectRoot);
+    return `${legacyProjectServerKey(canonical)}-${createHash("sha256").update(canonical).digest("hex").slice(0, 12)}`;
+}
+/** 只解析本安装器生成的单行 JSON 兼容 args；手写复杂 TOML 不猜测其绑定。 */
+function projectEntry(text, server) {
+    const header = new RegExp(`^\\s*\\[mcp_servers\\.(?:${server}|"${server}"|'${server}')\\]\\s*(?:#.*)?$`, "m").exec(text);
+    if (!header)
+        return undefined;
+    const tail = text.slice(header.index + header[0].length);
+    const nextHeader = tail.search(/^\s*\[/m);
+    const section = nextHeader < 0 ? tail : tail.slice(0, nextHeader);
+    const argsLine = /^\s*args\s*=\s*(\[[^\r\n]*\])\s*(?:#.*)?$/m.exec(section);
+    try {
+        const args = argsLine ? JSON.parse(argsLine[1]) : undefined;
+        if (!Array.isArray(args) || !args.every((value) => typeof value === "string"))
+            return {};
+        const positions = args.flatMap((value, index) => value === "--root" ? [index] : []);
+        if (positions.length !== 1 || !path.isAbsolute(args[positions[0] + 1] ?? ""))
+            return {};
+        return { root: canonicalProjectRoot(args[positions[0] + 1]) };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * --project 模式：把指定目录作为钉定项目写进 Codex config.toml（npx + --root）。
+ * 桌面版 Codex 起 MCP 服务时 cwd 不在工作区，必须逐项目钉根；同名条目已存在则跳过（fail-closed，不产生重复 TOML 表头）。
+ */
+export function appendCodexProjectConfig(file, projectRoot, force, dryRun, log) {
+    const absolute = path.resolve(file);
+    const server = codexProjectServerKey(projectRoot);
+    const canonical = canonicalProjectRoot(projectRoot);
+    const existing = fs.existsSync(absolute) ? fs.readFileSync(absolute, "utf8") : "";
+    const entry = projectEntry(existing, server);
+    const legacy = legacyProjectServerKey(canonical);
+    const legacyEntry = projectEntry(existing, legacy);
+    if (entry && entry.root !== canonical) {
+        throw new Error(`已有 [mcp_servers.${server}] 指向不同项目或无法确认 --root；未修改配置。`);
+    }
+    if (entry || legacyEntry?.root === canonical) {
+        const reused = entry ? server : legacy;
+        if (!force)
+            log(`[skip] Codex already has [mcp_servers.${reused}] for this project; nothing to change.`);
+        else
+            throw new Error(`Codex already has [mcp_servers.${reused}]; 请先手工删除该段再 --force 重加。`);
+        return;
+    }
+    log(`[${dryRun ? "plan" : "write"}] Codex: ${absolute}`);
+    if (dryRun)
+        return;
+    fs.mkdirSync(path.dirname(absolute), { recursive: true });
+    if (fs.existsSync(absolute))
+        fs.copyFileSync(absolute, backupName(absolute), fs.constants.COPYFILE_EXCL);
+    const tomlRoot = path.resolve(projectRoot).replace(/\\/g, "/");
+    const separator = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+    const block = `${separator}\n[mcp_servers.${server}]\ncommand = "npx"\nargs = ["-y", ${JSON.stringify(PACKAGE_SPEC)}, "--root", ${JSON.stringify(tomlRoot)}]\n`;
+    fs.appendFileSync(absolute, block, "utf8");
+    log(`[entry] [mcp_servers.${server}] → --root ${tomlRoot}`);
+}
 function run(command, args, visible) {
     const result = spawnSync(command, args, {
         shell: false,
@@ -177,8 +269,12 @@ function configureCliClient(client, options, available, log) {
         throw new Error(`${client} could not add ${SERVER_NAME}`);
     return true;
 }
-function configureClient(client, options, context, log) {
+function configureClient(client, options, context, log, projectRoot) {
     if (client === "codex") {
+        if (options.project && projectRoot) {
+            appendCodexProjectConfig(codexConfigPath(context.env, context.home), projectRoot, options.force, options.dryRun, log);
+            return;
+        }
         if (configureCliClient("codex", options, context.commandExists("codex"), log))
             return;
         appendCodexConfig(codexConfigPath(context.env, context.home), options.dryRun, log);
@@ -207,8 +303,9 @@ function configureClient(client, options, context, log) {
 function printHelp(log) {
     log("pm-mcp setup — configure local AI coding clients");
     log("");
-    log(`Usage: npx -y ${PACKAGE_SPEC} setup [--client auto|all|codex|claude|zcode|cursor|vscode|print] [--force] [--dry-run]`);
+    log(`Usage: npx -y ${PACKAGE_SPEC} setup [--client auto|all|codex|claude|zcode|cursor|vscode|print] [--project [dir]] [--force] [--dry-run]`);
     log("Default auto mode configures every detected supported client.");
+    log("--project [dir]: 在 Codex 把该目录注册为钉定项目并初始化 .pm（新项目一条命令上手；默认当前目录）");
 }
 export function runSetup(argv, overrides = {}) {
     const options = parseSetupArgs(argv);
@@ -226,24 +323,42 @@ export function runSetup(argv, overrides = {}) {
     const context = {
         env,
         home,
+        cwd: overrides.cwd,
         commandExists: overrides.commandExists ?? ((command) => commandExists(command, env)),
         exists: overrides.exists ?? fs.existsSync,
     };
+    const projectRoot = options.project ? path.resolve(options.projectDir?.trim() || context.cwd || process.cwd()) : undefined;
     const selected = options.client === "all"
         ? CLIENTS
         : options.client === "auto"
             ? detectClients(context)
             : [options.client];
-    if (selected.length === 0) {
+    if (selected.length === 0 && !options.project) {
         log("No supported client was detected. Use --client <name>, or --client print for generic JSON.");
         return 1;
     }
     log(`pm-mcp setup ${PACKAGE_SPEC}`);
-    log(`clients: ${selected.join(", ")}`);
+    if (selected.length > 0)
+        log(`clients: ${selected.join(", ")}`);
+    if (options.project && projectRoot) {
+        const name = path.basename(projectRoot) || "project";
+        log(`project: ${projectRoot}`);
+        if (options.dryRun) {
+            log(`[plan] init_project ${name}（.pm/ + PROJECT.md + AGENTS.md 工作规矩）`);
+        }
+        else if (isInitialized(projectRoot)) {
+            log("[skip] 项目已初始化（.pm/project.json 已存在）。");
+        }
+        else {
+            initProject(projectRoot, { name });
+            refreshDerived(projectRoot);
+            log(`[init] ✅ ${name} 已初始化：.pm/ 状态目录 + PROJECT.md 仪表盘 + AGENTS.md 工作规矩`);
+        }
+    }
     let failures = 0;
     for (const client of selected) {
         try {
-            configureClient(client, options, context, log);
+            configureClient(client, options, context, log, projectRoot);
         }
         catch (error) {
             failures += 1;
@@ -252,6 +367,11 @@ export function runSetup(argv, overrides = {}) {
     }
     if (failures > 0)
         return 1;
-    log("Done. Restart the configured client and ask it to call pm-mcp get_status.");
+    if (options.project && selected.includes("codex")) {
+        log("完成。请完全退出并重启 Codex，开新会话即可使用（工具名前缀 pm-mcp-<项目名>）。");
+    }
+    else {
+        log("Done. Restart the configured client and ask it to call pm-mcp get_status.");
+    }
     return 0;
 }

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 };
         }
     }));
 }
@@ -22,26 +57,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/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/package.json

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