@luckychen1993/pm-mcp 0.1.1 → 0.1.3

package/README.md

@@ -25,48 +25,63 @@ AI 编码项目的典型失控（本工具逐一给出机制）：
 | 调试过程随会话消失 | `log_debug` 调试知识账（症状/根因/修法/验证） |
 | 长任务崩溃、上下文丢失 | 任务步骤清单 + `checkpoint` 断点存档，新会话从恢复点续做 |
 | 团队协作与知识传递 | Git 项目中共享 `.pm/` + 会话署名 + `onboard` 入职简报工作流 |
+| 多 Agent 重复读写 | 并行读请求跨进程合并；写工具支持业务幂等键并自动抑制瞬时完全重复调用 |
 | token 猛烧 | 三段式定位 + 读类工具输出硬预算 + 文件用途索引 |
 | 法律知识产权 | `audit_license` 依赖许可证/copyleft 冲突 + 来源登记（provenance） |
 | 测试投机（删测试、skip 凑绿） | 禁用/蒸发/空测试检测 + 功能测试背书占比 + done 必附验证 |
 
-## 一键添加到 AI 编程助手
+## 一个命令自动添加到 AI 编程助手
 
-要求：Node.js ≥ 22.18。下面的配置固定到 npm 版本 `0.1.1`；首次启动由 `npx` 下载并在本机运行，pm-mcp 本身不需要 API Key，也不会调用远程模型。
+要求：Node.js ≥ 22.18。Windows、macOS 和 Linux 使用同一条命令：
 
-### Codex / ChatGPT 桌面版 / Codex IDE 扩展
+```bash
+npx -y @luckychen1993/pm-mcp@latest setup
+```
+
+安装器自动检测本机的 Codex、Claude Code、ZCode、Cursor 和 VS Code，并配置所有检测到的客户端。JSON 配置会先备份；已经存在的 Codex/Claude 配置默认保留，用 `setup --force` 才替换。先预览、不写配置：
+
+```bash
+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 / ChatGPT 桌面版 / Codex IDE 扩展
 
 Codex 的本地客户端共享同一份 MCP 配置。复制执行：
 
 ```bash
-codex mcp add pm-mcp -- npx -y @luckychen1993/pm-mcp@0.1.1
+codex mcp add pm-mcp -- npx -y @luckychen1993/pm-mcp@0.1.3
 ```
 
 重启客户端后可用 `codex mcp list` 检查。该命令遵循 [OpenAI 官方 MCP CLI 格式](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)。
 
-### Claude Code
+#### Claude Code
 
 ```bash
-claude mcp add pm-mcp --scope user -- npx -y @luckychen1993/pm-mcp@0.1.1
+claude mcp add pm-mcp --scope user -- npx -y @luckychen1993/pm-mcp@0.1.3
 ```
 
-### ZCode、Cursor、VS Code（Windows 一键脚本）
+#### ZCode、Cursor、VS Code（Windows 备用脚本）
 
 将 `<client>` 替换为 `zcode`、`cursor` 或 `vscode`，整行复制到 PowerShell：
 
 ```powershell
-$u='https://raw.githubusercontent.com/happy520ai/pm-mcp/v0.1.1/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.3/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` 指定路径。
 
-### 其他支持 stdio MCP 的客户端
+#### 其他支持 stdio MCP 的客户端
 
 ```json
 {
   "mcpServers": {
     "pm-mcp": {
       "command": "npx",
-      "args": ["-y", "@luckychen1993/pm-mcp@0.1.1"],
+      "args": ["-y", "@luckychen1993/pm-mcp@0.1.3"],
       "env": {}
     }
   }
@@ -139,6 +154,8 @@ snapshot_codebase + audit_structure 对账；audit_security 安全体检；audit
 
 Resources：`pm://dashboard`、`pm://roadmap`、`pm://tasks`、`pm://changelog`、`pm://architecture`、`pm://portfolio`、`pm://acceptance`。
 
+所有写工具都接受可选 `idempotency_key`。同一业务的多个 Agent 应传同一个稳定键（例如 `T-123:add-login-task`）：同键同参数只执行一次并复用首次结果，同键不同参数直接拒绝。即使没有显式键，完全相同的并发写也会在短窗口内自动合并；完全相同的并行读会等待首个执行者并复用结果。
+
 ## 数据模型（被管理项目内的 `.pm/`；JSON/Markdown 账本可 git diff，`index.db` 是忽略并可重建的缓存）
 
 ```
@@ -161,7 +178,7 @@ PROJECT.md        # 仓库根，自动生成的仪表盘（勿手改）
 changelog.md      # 自动生成
 ```
 
-全局注册表：`~/.pm-mcp/registry.json`。
+全局注册表：`~/.pm-mcp/registry.json`。跨进程读合并/写幂等运行态位于 `~/.pm-mcp/idempotency/<项目路径哈希>/`，不会污染被管理项目或进入 Git。
 
 ## 跨文件、跨模块、跨语言治理
 
@@ -238,6 +255,7 @@ npm run benchmark:volume -- --size-gib 20 --file-bytes 1048576 --full-audit --te
 - **许可证审计**覆盖直接+传递 Node 依赖（npm 嵌套与 pnpm 布局）；语言单元虽可跨生态发现，但许可证深度仍不是所有生态的通用供应链图，也不替代法务意见。
 - **测试背书占比**是代理指标（功能是否挂了真实存在的测试文件），不是行覆盖率。
 - **token 消耗**本身是客户端的账，工具用「足迹/产出比」做空转代理指标。
+- 幂等层能避免重复计算、重复落账并缩短重复调用输出，但无法返还模型在发起 MCP 调用前已经消耗的推理 token；客户端/Agent 编排仍应避免无意义扇出。
 - 结构/安全扫描忽略内置目录（node_modules/.git/dist/build/venv 等）与常见二进制/锁文件，尚不通用解析 `.gitignore`；`search_code` 的 rg 后端会解析。目录深度上限 64 层（超限计数上报，不静默）。
 - **仓库提供 fail-closed 巡检命令**；定时器、托管 CI 与会话 hooks 属部署层，必须在相应环境单独配置和监控。
 - 语义层面无法强制的（笔记内容是否属实、AI 是否真跑了测试）依赖 git 对账与审计交叉验证，不承诺语义级防伪。

package/dist/acceptance-tools.js

@@ -7,7 +7,7 @@ import { acceptanceBaselineFingerprint, evaluateAcceptance } from "./acceptance-
 import { writeAcceptanceReport } from "./acceptance-report.js";
 import { requireInitialized } from "./paths.js";
 import { loadJson, saveJson, withLedgerLock } from "./store.js";
-import { tool } from "./tool-base.js";
+import { toolI, toolR } from "./tool-base.js";
 import { refreshDerived } from "./dashboard.js";
 const IdSchema = z.string().trim().min(1).max(120).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);
 const SemVerSchema = z.string().regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/);
@@ -269,11 +269,11 @@ export function evaluateAcceptanceFile(root, input) {
     return { report, ...files };
 }
 export function registerAcceptanceTools(server, root) {
-    tool(server, "list_acceptance_baselines", "列出版本化验收基线、审批状态、当前 fingerprint 和规模。", {}, () => {
+    toolR(server, root, "list_acceptance_baselines", "列出版本化验收基线、审批状态、当前 fingerprint 和规模。", {}, () => {
         requireInitialized(root);
         return JSON.stringify(listAcceptanceBaselines(root), null, 2);
     });
-    tool(server, "get_acceptance_baseline", "读取一个验收基线；默认返回摘要，full=true 返回严格 JSON。", {
+    toolR(server, root, "get_acceptance_baseline", "读取一个验收基线；默认返回摘要，full=true 返回严格 JSON。", {
         baseline_id: IdSchema,
         baseline_version: SemVerSchema,
         full: z.boolean().optional(),
@@ -284,14 +284,14 @@ export function registerAcceptanceTools(server, root) {
             return JSON.stringify(baseline, null, 2);
         return JSON.stringify(listAcceptanceBaselines(root).find((item) => item.id === args.baseline_id && item.version === args.baseline_version), null, 2);
     });
-    tool(server, "save_acceptance_baseline_draft", "从项目内 .pm/acceptance 下的严格 JSON 保存 draft 基线；批准后的同版本不可覆盖。", {
+    toolI(server, root, "save_acceptance_baseline_draft", "从项目内 .pm/acceptance 下的严格 JSON 保存 draft 基线；批准后的同版本不可覆盖。", {
         baseline_file: JsonPathSchema,
     }, (args) => {
         requireInitialized(root);
         const baseline = saveDraftAcceptanceBaselineFile(root, args.baseline_file);
         return `✅ draft ${baseline.baseline_id}@${baseline.baseline_version} 已保存；fingerprint=${acceptanceBaselineFingerprint(baseline)}`;
     });
-    tool(server, "approve_acceptance_baseline", "按当前 SHA-256 fingerprint 原子批准基线；fingerprint 变化即拒绝，批准后修改必须升版。", {
+    toolI(server, root, "approve_acceptance_baseline", "按当前 SHA-256 fingerprint 原子批准基线；fingerprint 变化即拒绝，批准后修改必须升版。", {
         baseline_id: IdSchema,
         baseline_version: SemVerSchema,
         expected_fingerprint_sha256: Sha256Schema,
@@ -303,7 +303,7 @@ export function registerAcceptanceTools(server, root) {
         const approved = approveAcceptanceBaseline(root, args);
         return `✅ baseline ${approved.baseline_id}@${approved.baseline_version} 已批准；approved fingerprint=${acceptanceBaselineFingerprint(approved)}`;
     });
-    tool(server, "evaluate_acceptance", "读取项目内 .pm/acceptance evaluation JSON，逐项复算证据 SHA-256，再生成不可手填、不可覆盖的正式报告。", {
+    toolI(server, root, "evaluate_acceptance", "读取项目内 .pm/acceptance evaluation JSON，逐项复算证据 SHA-256，再生成不可手填、不可覆盖的正式报告。", {
         baseline_id: IdSchema,
         baseline_version: SemVerSchema,
         evaluation_file: JsonPathSchema,

package/dist/audit-tools.js

@@ -6,7 +6,7 @@ import { auditLicense } from "./license.js";
 import { isInitialized, requireInitialized } from "./paths.js";
 import { listRegistry } from "./registry.js";
 import { auditSecurity, listFindings, resolveFinding } from "./security.js";
-import { budgetLines, tool, toolW } from "./tool-base.js";
+import { budgetLines, toolR, toolW } from "./tool-base.js";
 export function registerAuditTools(server, root) {
     toolW(server, root, "snapshot_codebase", "给代码结构拍快照（文件数/行数/目录分布/测试数/skip 标记/依赖清单）。之后 audit_structure 会与上次快照 diff。建议每个会话或每个里程碑结束时拍一次。", {}, () => {
         requireInitialized(root);
@@ -14,7 +14,7 @@ export function registerAuditTools(server, root) {
         refreshDerived(root);
         return [...summary, `下次 audit_structure 将以此为基线（${snapshot.file}）。`].join("\n");
     });
-    tool(server, "audit_structure", "八项结构对账（定期做）：①增长与新增依赖 ②漂移对账（功能↔文件，防幻觉）③债务与重构配额 ④churn 热点 ⑤复杂度预算 ⑥索引覆盖率 ⑦足迹/产出 ⑧测试健康（禁用/蒸发/空测试/背书占比）。", {}, () => {
+    toolR(server, root, "audit_structure", "八项结构对账（定期做）：①增长与新增依赖 ②漂移对账（功能↔文件，防幻觉）③债务与重构配额 ④churn 热点 ⑤复杂度预算 ⑥索引覆盖率 ⑦足迹/产出 ⑧测试健康（禁用/蒸发/空测试/背书占比）。", {}, () => {
         requireInitialized(root);
         return auditStructure(root, budgetLines(root));
     });
@@ -24,7 +24,7 @@ export function registerAuditTools(server, root) {
         refreshDerived(root);
         return report.text.join("\n");
     });
-    tool(server, "list_findings", "查看安全台账（可按状态过滤）。", { status: z.enum(["open", "fixed", "accepted"]).optional() }, (args) => {
+    toolR(server, root, "list_findings", "查看安全台账（可按状态过滤）。", { status: z.enum(["open", "fixed", "accepted"]).optional() }, (args) => {
         requireInitialized(root);
         const list = listFindings(root, args.status);
         if (list.length === 0)
@@ -42,13 +42,13 @@ export function registerAuditTools(server, root) {
         refreshDerived(root);
         return `✅ ${f.id} 已置为 ${f.status}${f.note ? `（${f.note}）` : ""}。`;
     });
-    tool(server, "audit_license", "许可证审计（法律账）：依赖许可证清单与 copyleft 冲突、源码中的 GPL 家族许可证头、LICENSE 文件检查、来源登记清单。离线启发式，不替代法务。", {}, () => {
+    toolR(server, root, "audit_license", "许可证审计（法律账）：依赖许可证清单与 copyleft 冲突、源码中的 GPL 家族许可证头、LICENSE 文件检查、来源登记清单。离线启发式，不替代法务。", {}, () => {
         requireInitialized(root);
         return auditLicense(root, budgetLines(root));
     });
 }
-export function registerRegistryTools(server) {
-    tool(server, "list_projects", "列出本机所有被 pm-mcp 管理的项目（全局注册表）。", {}, () => {
+export function registerRegistryTools(server, root) {
+    toolR(server, root, "list_projects", "列出本机所有被 pm-mcp 管理的项目（全局注册表）。", {}, () => {
         const list = listRegistry();
         if (list.length === 0)
             return "（注册表为空。在任何项目里 init_project 后会自动登记。）";

package/dist/cli.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+if (process.argv[2] === "setup") {
+    try {
+        const { runSetup } = await import("./setup.js");
+        process.exitCode = runSetup(process.argv.slice(3));
+    }
+    catch (error) {
+        console.error(`[pm-mcp setup] ERROR: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+    }
+}
+else {
+    await import("./index.js");
+}
+export {};

package/dist/governance-tools.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { z } from "zod";
-import { budgetLines, tool, toolW } from "./tool-base.js";
+import { budgetLines, toolI, toolR, toolW } from "./tool-base.js";
 import { foldLines } from "./budget.js";
 import { refreshDerived } from "./dashboard.js";
 import { requireInitialized } from "./paths.js";
@@ -64,13 +64,13 @@ function qualityLines(commands) {
     return commands.map((command, index) => `${index + 1}. [${command.kind}] (${command.cwd}) ${command.command} ${command.args.join(" ")}`);
 }
 export function registerGovernanceTools(server, root) {
-    tool(server, "init_governance", "为旧项目初始化 .pm/governance.json；新项目 init_project 已自动创建。", {}, () => {
+    toolI(server, root, "init_governance", "为旧项目初始化 .pm/governance.json；新项目 init_project 已自动创建。", {}, () => {
         requireInitialized(root);
         const governance = initGovernance(root, {});
         refreshDerived(root);
         return `✅ 治理模型已初始化（schema v${governance.schema_version}）。下一步用 upsert_module 声明模块、owner 与语言。`;
     });
-    tool(server, "get_governance", "查看结构化模块、owner、公开接口、仓库依赖与强制策略。", {}, () => {
+    toolR(server, root, "get_governance", "查看结构化模块、owner、公开接口、仓库依赖与强制策略。", {}, () => {
         requireInitialized(root);
         return compactGovernance(loadGovernance(root));
     });
@@ -140,7 +140,7 @@ export function registerGovernanceTools(server, root) {
         refreshDerived(root);
         return `✅ 治理策略已更新：coverage>=${governance.policies.minimum_coverage_pct}% · semantic>=${governance.policies.minimum_semantic_assurance} · regex-fallback=${governance.policies.fail_on_semantic_fallback ? "forbidden" : "allowed"}`;
     });
-    tool(server, "discover_languages", "递归发现 Node/Python/Go/Rust/JVM/.NET 单元及其受控质量命令，不执行命令。", {}, () => {
+    toolR(server, root, "discover_languages", "递归发现 Node/Python/Go/Rust/JVM/.NET 单元及其受控质量命令，不执行命令。", {}, () => {
         requireInitialized(root);
         const units = discoverProjectUnits(root);
         const coverage = assessQualityCoverage(units);
@@ -151,15 +151,15 @@ export function registerGovernanceTools(server, root) {
             lines.push(`- 🚩 无质量命令: ${coverage.withoutCommands.join(", ")}`);
         return foldLines(lines, { maxLines: budgetLines(root), hint: "按模块拆分治理 root" });
     });
-    tool(server, "audit_governance", "审计跨文件/模块/语言语义覆盖、owner、公开接口、依赖边界、循环、unresolved 与质量矩阵覆盖。", {}, () => {
+    toolR(server, root, "audit_governance", "审计跨文件/模块/语言语义覆盖、owner、公开接口、依赖边界、循环、unresolved 与质量矩阵覆盖。", {}, () => {
         requireInitialized(root);
         return auditGovernance(root, budgetLines(root)).report;
     });
-    tool(server, "list_semantic_evidence", "列出已登记的语言原生 AST、编译器或运行时语义证据；损坏文档会使整次读取失败。", {}, () => {
+    toolR(server, root, "list_semantic_evidence", "列出已登记的语言原生 AST、编译器或运行时语义证据；损坏文档会使整次读取失败。", {}, () => {
         requireInitialized(root);
         return JSON.stringify(listSemanticEvidence(root), null, 2);
     });
-    tool(server, "save_semantic_evidence", "保存一份绑定源码 SHA-256 的语言原生 AST/编译器/运行时证据；过期摘要在治理审计中严格失败。", {
+    toolI(server, root, "save_semantic_evidence", "保存一份绑定源码 SHA-256 的语言原生 AST/编译器/运行时证据；过期摘要在治理审计中严格失败。", {
         id: z.string().trim().min(1).max(128),
         document: SemanticEvidenceDocumentSchema,
     }, (args) => {
@@ -167,7 +167,7 @@ export function registerGovernanceTools(server, root) {
         const saved = saveSemanticEvidence(root, args.id, args.document);
         return `✅ semantic evidence ${args.id} 已保存：${saved.file} · ${saved.analyzer.id} · ${saved.analyzer.assurance} · ${saved.status}`;
     });
-    tool(server, "impact_analysis", "从变更文件沿 file/module 反向依赖闭包计算受影响文件与模块。", {
+    toolR(server, root, "impact_analysis", "从变更文件沿 file/module 反向依赖闭包计算受影响文件与模块。", {
         files: z.array(z.string().min(1)).min(1).max(100),
     }, (args) => {
         requireInitialized(root);
@@ -180,7 +180,7 @@ export function registerGovernanceTools(server, root) {
             ...(impact.unknownChangedFiles.length ? [`⚠️ 未进入语义图: ${impact.unknownChangedFiles.join(", ")}`] : []),
         ], { maxLines: budgetLines(root), hint: "缩小 files 输入或按模块运行" });
     });
-    tool(server, "plan_quality_matrix", "生成跨语言真实质量命令计划；只规划，不启动进程。", {
+    toolR(server, root, "plan_quality_matrix", "生成跨语言真实质量命令计划；只规划，不启动进程。", {
         unit: z.string().optional(),
         kinds: z.array(z.enum(["test", "build", "lint", "typecheck", "coverage", "security"])).optional(),
     }, (args) => {
@@ -192,7 +192,7 @@ export function registerGovernanceTools(server, root) {
             ...(plan.coverage.withoutCommands.length ? [`🚩 无命令单元: ${plan.coverage.withoutCommands.join(", ")}`] : []),
         ], { maxLines: budgetLines(root), hint: "用 unit/kinds 过滤；真实执行需 run_quality_matrix confirm_execute=true" });
     });
-    tool(server, "run_quality_matrix", "显式执行跨语言质量矩阵。只运行受支持适配器生成的 argv，shell=false；缺工具/超时/非零均失败。", {
+    toolI(server, root, "run_quality_matrix", "显式执行跨语言质量矩阵。只运行受支持适配器生成的 argv，shell=false；缺工具/超时/非零均失败。", {
         confirm_execute: z.literal(true).describe("必须显式为 true；该操作会运行目标项目构建/测试命令"),
         unit: z.string().optional(),
         kinds: z.array(z.enum(["test", "build", "lint", "typecheck", "coverage", "security"])).optional(),
@@ -219,7 +219,7 @@ export function registerGovernanceTools(server, root) {
             lines.push(`- [${item.status}] ${item.command.kind} ${item.command.cwd} (${item.durationMs}ms${item.exitCode === null ? "" : `, exit ${item.exitCode}`})`);
         return foldLines(lines, { maxLines: budgetLines(root), hint: "查看 .pm/quality-runs 结构化摘要（不落原始输出）" });
     });
-    tool(server, "get_portfolio", "聚合当前项目或全局注册项目的阶段、里程碑、债务、安全、语言、跨仓依赖/版本/cycle；加载失败不能假绿。", {
+    toolR(server, root, "get_portfolio", "聚合当前项目或全局注册项目的阶段、里程碑、债务、安全、语言、跨仓依赖/版本/cycle；加载失败不能假绿。", {
         current_only: z.boolean().optional(),
     }, (args) => {
         requireInitialized(root);

package/dist/idempotency.js

@@ -0,0 +1,293 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { z } from "zod";
+import { atomicWrite, withLedgerLock } from "./store.js";
+import { pmPath, registryFile } from "./paths.js";
+export const IdempotencyKeySchema = z.string()
+    .trim()
+    .min(1)
+    .max(128)
+    .regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/, "仅允许 ASCII 字母、数字、点、下划线、冒号和连字符");
+const OperationRecordSchema = z.object({
+    schema_version: z.literal(1),
+    key: z.string().min(1).max(256),
+    explicit: z.boolean(),
+    tool: z.string().min(1),
+    args_sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    mode: z.enum(["read", "write"]),
+    status: z.enum(["pending", "completed"]),
+    owner_pid: z.number().int().positive(),
+    owner_token: z.string().uuid(),
+    created_at: z.string().datetime({ offset: true }),
+    updated_at: z.string().datetime({ offset: true }),
+    result: z.string().nullable(),
+});
+const AUTO_REPLAY_MS = 1_000;
+const READ_WAIT_MS = 30_000;
+const LOCK_STALE_MS = 10_000;
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, item]) => [key, canonical(item)]));
+    }
+    return value;
+}
+export function operationArgsHash(args) {
+    return sha256(JSON.stringify(canonical(args)));
+}
+export function splitIdempotencyArgs(args) {
+    if (!args || typeof args !== "object" || Array.isArray(args))
+        return { businessArgs: args };
+    const { idempotency_key: rawKey, ...business } = args;
+    const explicitKey = rawKey === undefined ? undefined : IdempotencyKeySchema.parse(rawKey);
+    return { businessArgs: business, ...(explicitKey ? { explicitKey } : {}) };
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function operationDirectory(root) {
+    return path.join(path.dirname(registryFile()), "idempotency", sha256(path.resolve(root)));
+}
+function revisionFile(root) {
+    return path.join(operationDirectory(root), "revision");
+}
+function readRevision(root) {
+    try {
+        return fs.readFileSync(revisionFile(root), "utf8").trim() || "0";
+    }
+    catch {
+        return "0";
+    }
+}
+function bumpRevision(root) {
+    fs.mkdirSync(operationDirectory(root), { recursive: true });
+    atomicWrite(revisionFile(root), randomUUID() + "\n");
+}
+function operationFile(root, key) {
+    return path.join(operationDirectory(root), `${sha256(key)}.json`);
+}
+function readRecord(file) {
+    if (!fs.existsSync(file))
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`幂等记录损坏，拒绝继续写入: ${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const parsed = OperationRecordSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new Error(`幂等记录 schema 无效，拒绝继续写入: ${file}`);
+    return parsed.data;
+}
+function lockOwner(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        return typeof parsed.pid === "number" && typeof parsed.token === "string" ? { pid: parsed.pid, token: parsed.token } : null;
+    }
+    catch {
+        return null;
+    }
+}
+function withOperationLock(file, fn) {
+    const lock = `${file}.lock`;
+    const token = randomUUID();
+    const payload = JSON.stringify({ pid: process.pid, token });
+    let held = false;
+    for (let index = 0; index < 150 && !held; index += 1) {
+        try {
+            fs.writeFileSync(lock, payload, { flag: "wx" });
+            held = true;
+        }
+        catch {
+            try {
+                const current = lockOwner(lock);
+                const stale = Date.now() - fs.statSync(lock).mtimeMs > LOCK_STALE_MS;
+                if (stale && (!current || !processAlive(current.pid)))
+                    fs.rmSync(lock, { force: true });
+            }
+            catch {
+                // The lock disappeared between checks; retry.
+            }
+            if (!held)
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+        }
+    }
+    if (!held)
+        throw new Error("幂等键锁获取超时（3s），请稍后重试同一 idempotency_key。");
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            if (lockOwner(lock)?.token === token)
+                fs.rmSync(lock, { force: true });
+        }
+        catch {
+            // Best-effort release; stale-owner recovery handles process crashes.
+        }
+    }
+}
+function claim(root, tool, args, mode, explicitKey) {
+    const argsHash = operationArgsHash(args);
+    const key = explicitKey ?? `auto:${mode}:${tool}:${argsHash}`;
+    const file = operationFile(root, key);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    return withOperationLock(file, () => {
+        const existing = readRecord(file);
+        if (existing) {
+            if (existing.key !== key || existing.tool !== tool || existing.mode !== mode || existing.args_sha256 !== argsHash) {
+                throw new Error(`idempotency_key 冲突：${key} 已绑定其他工具或参数，拒绝误复用。`);
+            }
+            if (existing.status === "completed") {
+                const age = Date.now() - Date.parse(existing.updated_at);
+                if (existing.explicit || (mode === "write" && age <= AUTO_REPLAY_MS))
+                    return { kind: "replay", record: existing };
+            }
+            else if (processAlive(existing.owner_pid)) {
+                return { kind: "pending", file, record: existing };
+            }
+        }
+        const timestamp = new Date().toISOString();
+        const record = {
+            schema_version: 1,
+            key,
+            explicit: explicitKey !== undefined,
+            tool,
+            args_sha256: argsHash,
+            mode,
+            status: "pending",
+            owner_pid: process.pid,
+            owner_token: randomUUID(),
+            created_at: timestamp,
+            updated_at: timestamp,
+            result: null,
+        };
+        atomicWrite(file, JSON.stringify(OperationRecordSchema.parse(record), null, 2) + "\n");
+        return { kind: "execute", file, record };
+    });
+}
+function complete(file, reservation, result) {
+    withOperationLock(file, () => {
+        const current = readRecord(file);
+        if (!current || current.owner_token !== reservation.owner_token || current.status !== "pending") {
+            throw new Error(`幂等记录所有权变化，拒绝把结果写到其他操作: ${reservation.key}`);
+        }
+        current.status = "completed";
+        current.result = result;
+        current.updated_at = new Date().toISOString();
+        atomicWrite(file, JSON.stringify(OperationRecordSchema.parse(current), null, 2) + "\n");
+    });
+}
+function abandon(file, reservation) {
+    try {
+        withOperationLock(file, () => {
+            const current = readRecord(file);
+            if (current?.owner_token === reservation.owner_token && current.status === "pending")
+                fs.rmSync(file, { force: true });
+        });
+    }
+    catch {
+        // Preserve the original operation error. A dead-owner retry can recover later.
+    }
+}
+function replay(record) {
+    return {
+        text: record.result ?? `⏳ 相同业务正在由另一 Agent 执行：${record.key}`,
+        replayed: record.status === "completed",
+        pending: record.status === "pending",
+        key: record.key,
+    };
+}
+export function runIdempotentWriteSync(root, tool, args, fn) {
+    const { businessArgs, explicitKey } = splitIdempotencyArgs(args);
+    const reservation = claim(root, tool, businessArgs, "write", explicitKey);
+    if (reservation.kind !== "execute")
+        return replay(reservation.record);
+    try {
+        const text = withLedgerLock(root, () => {
+            const value = fn(businessArgs);
+            bumpRevision(root);
+            return value;
+        });
+        complete(reservation.file, reservation.record, text);
+        return { text, replayed: false, pending: false, key: reservation.record.key };
+    }
+    catch (error) {
+        abandon(reservation.file, reservation.record);
+        throw error;
+    }
+}
+export async function runIdempotentWrite(root, tool, args, fn) {
+    const { businessArgs, explicitKey } = splitIdempotencyArgs(args);
+    const reservation = claim(root, tool, businessArgs, "write", explicitKey);
+    if (reservation.kind !== "execute")
+        return replay(reservation.record);
+    try {
+        const text = await fn(businessArgs);
+        bumpRevision(root);
+        complete(reservation.file, reservation.record, text);
+        return { text, replayed: false, pending: false, key: reservation.record.key };
+    }
+    catch (error) {
+        abandon(reservation.file, reservation.record);
+        throw error;
+    }
+}
+async function waitForRead(file, record) {
+    const deadline = Date.now() + READ_WAIT_MS;
+    while (Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, 25));
+        const current = readRecord(file);
+        if (!current || current.owner_token !== record.owner_token)
+            return null;
+        if (current.status === "completed")
+            return current;
+        if (!processAlive(current.owner_pid))
+            return null;
+    }
+    return null;
+}
+export async function runCoalescedRead(root, tool, args, fn) {
+    // Read-only calls before project initialization must not create .pm state.
+    if (!fs.existsSync(pmPath(root, "project.json"))) {
+        const text = await fn(args);
+        return { text, replayed: false, pending: false, key: "uncached:uninitialized" };
+    }
+    const readClaim = () => claim(root, tool, { revision: readRevision(root), args }, "read");
+    let reservation = readClaim();
+    if (reservation.kind === "replay")
+        return replay(reservation.record);
+    if (reservation.kind === "pending") {
+        const completed = await waitForRead(reservation.file, reservation.record);
+        if (completed)
+            return replay(completed);
+        reservation = readClaim();
+        if (reservation.kind !== "execute")
+            return replay(reservation.record);
+    }
+    try {
+        const text = await fn(args);
+        complete(reservation.file, reservation.record, text);
+        return { text, replayed: false, pending: false, key: reservation.record.key };
+    }
+    catch (error) {
+        abandon(reservation.file, reservation.record);
+        throw error;
+    }
+}

package/dist/index.js

@@ -22,7 +22,13 @@ 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.1" });
+const server = new McpServer({ name: "pm-mcp", version: "0.1.3" }, {
+    instructions: [
+        "多 Agent 规则：相同业务的所有写工具调用必须携带相同 idempotency_key（建议 task-id:operation）；同键同参数只执行一次，同键不同参数会被拒绝。",
+        "完全相同的并行读请求会由服务端合并并复用结果；不要让多个分支重复请求同一工具和参数。",
+        "看到“幂等复用”时直接采用首次结果；看到“幂等占位/正在执行”时等待负责该业务的 Agent，不要换键重试。",
+    ].join(" "),
+});
 registerAllTools(server, root);
 /* -------------------------------- Resources ------------------------------- */
 function safeText(fn) {

package/dist/knowledge-tools.js

@@ -6,7 +6,7 @@ import { refreshDerived } from "./dashboard.js";
 import { decisionsDir, requireInitialized } from "./paths.js";
 import { formatCodeSearch, searchCode, searchKnowledge } from "./search.js";
 import { loadDebugLog, loadFeatures, loadFileNotes, loadProject, loadSessions, nextId, saveDebugLog, saveFeatures, saveFileNotes, saveSessions, } from "./store.js";
-import { budgetLines, tool, toolW } from "./tool-base.js";
+import { budgetLines, toolR, toolW } from "./tool-base.js";
 import { now } from "./types.js";
 export function registerFeatureTools(server, root) {
     toolW(server, root, "register_feature", "登记功能（回答「这个项目有哪些功能」）。entry_files=入口文件（漂移对账锚点），test_files=测试文件（测试背书）。", {
@@ -41,7 +41,7 @@ export function registerFeatureTools(server, root) {
             : "";
         return `✅ 功能 ${id}「${args.name}」已登记${args.module ? `（${args.module}）` : ""}。audit_structure 会核对其入口文件是否真实存在（防幻觉对账）。${hint}`;
     });
-    tool(server, "list_features", "列出功能清单（可按模块/状态过滤）。", { module: z.string().optional(), status: z.enum(["planned", "implemented", "deprecated"]).optional() }, (args) => {
+    toolR(server, root, "list_features", "列出功能清单（可按模块/状态过滤）。", { module: z.string().optional(), status: z.enum(["planned", "implemented", "deprecated"]).optional() }, (args) => {
         requireInitialized(root);
         let list = loadFeatures(root).features;
         if (args.module)
@@ -95,7 +95,7 @@ export function registerDecisionTools(server, root) {
         refreshDerived(root);
         return `✅ 决策已记录: .pm/decisions/${file}（不可变编号，git 友好）。search_knowledge 可检索。`;
     });
-    tool(server, "list_decisions", "列出全部架构决策（ADR）。", {}, () => {
+    toolR(server, root, "list_decisions", "列出全部架构决策（ADR）。", {}, () => {
         requireInitialized(root);
         const dir = decisionsDir(root);
         const names = fs.existsSync(dir) ? fs.readdirSync(dir).filter((n) => n.endsWith(".md")).sort() : [];
@@ -164,7 +164,7 @@ export function registerSessionTools(server, root) {
     });
 }
 export function registerSearchTools(server, root) {
-    tool(server, "search_code", "在真实代码里检索（防幻觉事中防线）：谈某个功能/文件之前先搜实码。返回 file:line 片段而非整文件（token 经济）。默认按字面量匹配；regex=true 时按 JavaScript 正则（仅在你确需时开启）。", {
+    toolR(server, root, "search_code", "在真实代码里检索（防幻觉事中防线）：谈某个功能/文件之前先搜实码。返回 file:line 片段而非整文件（token 经济）。默认按字面量匹配；regex=true 时按 JavaScript 正则（仅在你确需时开启）。", {
         query: z.string().min(1).describe("关键词（默认字面量匹配）"),
         glob: z.string().optional().describe("限定文件范围，如 src/**/*.ts"),
         max_results: z.number().int().min(1).max(100).optional().describe("默认 30"),
@@ -174,7 +174,7 @@ export function registerSearchTools(server, root) {
         const res = searchCode(root, args.query, args.glob, args.max_results ?? 30, args.regex ?? false);
         return formatCodeSearch(res, args.query);
     });
-    tool(server, "search_knowledge", "检索六类项目知识源（ADR/任务/功能/会话/调试记录/文件索引）——回答「之前为什么这么做」「上次这个错怎么解的」，用历史结论代替重新推理。代码内容请用 search_code。", { query: z.string().min(1) }, (args) => {
+    toolR(server, root, "search_knowledge", "检索六类项目知识源（ADR/任务/功能/会话/调试记录/文件索引）——回答「之前为什么这么做」「上次这个错怎么解的」，用历史结论代替重新推理。代码内容请用 search_code。", { query: z.string().min(1) }, (args) => {
         requireInitialized(root);
         return searchKnowledge(root, args.query);
     });

package/dist/project-tools.js

@@ -7,7 +7,7 @@ import { foldLines } from "./budget.js";
 import { loadGovernance } from "./governance-model.js";
 import { loadProject, loadRoadmap, loadSecurity, loadSessions, loadTasks, saveProject, saveRoadmap, } from "./store.js";
 import { now } from "./types.js";
-import { budgetLines, tool, toolW } from "./tool-base.js";
+import { budgetLines, toolI, toolR, toolW } from "./tool-base.js";
 function taskLine(t, withNext = false) {
     const parts = [`[${t.status}]`, t.id, t.title, `(${t.type}${t.milestone ? `,${t.milestone}` : ""})`];
     if (withNext && t.checkpoint) {
@@ -34,7 +34,7 @@ export function registerProjectTools(server, root) {
             "建议顺序: upsert_module 声明模块/owner/语言 → add_milestone 建里程碑 → add_task 拆任务 → 开工前 get_status / 收工后 log_session。",
         ].join("\n");
     });
-    tool(server, "get_status", "一站式「我在哪」：项目阶段 + 里程碑进度 + 进行中任务（含断点下一步）+ 健康摘要 + 最近变更。会话开工第一件事。since 可只看某日期以来的任务/会话变化。", { since: z.string().optional().describe("ISO 日期，如 2026-09-01：只看该日期以来的任务/会话变化") }, (args) => {
+    toolR(server, root, "get_status", "一站式「我在哪」：项目阶段 + 里程碑进度 + 进行中任务（含断点下一步）+ 健康摘要 + 最近变更。会话开工第一件事。since 可只看某日期以来的任务/会话变化。", { since: z.string().optional().describe("ISO 日期，如 2026-09-01：只看该日期以来的任务/会话变化") }, (args) => {
         requireInitialized(root);
         const project = loadProject(root);
         const { milestones } = loadRoadmap(root);
@@ -136,7 +136,7 @@ export function registerProjectTools(server, root) {
         refreshDerived(root);
         return `✅ 项目信息已更新（阶段: ${project.phase || "—"}，模块: ${project.modules.join(", ") || "—"}）。仪表盘已刷新。`;
     });
-    tool(server, "regenerate_dashboard", "手动重新生成 PROJECT.md 仪表盘与 changelog.md（正常情况下每次写操作已自动刷新）。", {}, () => {
+    toolI(server, root, "regenerate_dashboard", "手动重新生成 PROJECT.md 仪表盘与 changelog.md（正常情况下每次写操作已自动刷新）。", {}, () => {
         requireInitialized(root);
         refreshDerived(root);
         return "✅ PROJECT.md 与 changelog.md 已重新生成。";
@@ -196,7 +196,7 @@ export function registerRoadmapTools(server, root) {
         const s = milestoneStats(tasks, m.id);
         return [`✅ ${m.id} 已更新（${m.status}）。进度: ${s.done}/${s.total}（${s.pct}%）。`, ...warnings].join("\n");
     });
-    tool(server, "get_roadmap", "查看路线图。depth=1 每个里程碑一行摘要（功能再多也不乱）；depth=2 额外展开活跃里程碑的任务明细与断点。", { depth: z.number().int().min(1).max(2).optional().describe("默认 1") }, (args) => {
+    toolR(server, root, "get_roadmap", "查看路线图。depth=1 每个里程碑一行摘要（功能再多也不乱）；depth=2 额外展开活跃里程碑的任务明细与断点。", { depth: z.number().int().min(1).max(2).optional().describe("默认 1") }, (args) => {
         requireInitialized(root);
         const { milestones } = loadRoadmap(root);
         const { tasks } = loadTasks(root);

package/dist/setup.js

@@ -0,0 +1,257 @@
+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.3";
+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 };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--client") {
+            const value = argv[index + 1];
+            if (!value || !["auto", "all", "codex", "claude", "zcode", "cursor", "vscode", "print"].includes(value)) {
+                throw new Error("--client must be auto, all, codex, claude, zcode, cursor, vscode, or print");
+            }
+            options.client = value;
+            index += 1;
+        }
+        else if (arg === "--force") {
+            options.force = true;
+        }
+        else if (arg === "--dry-run") {
+            options.dryRun = true;
+        }
+        else if (arg === "--help" || arg === "-h") {
+            options.help = true;
+        }
+        else {
+            throw new Error(`unknown setup argument: ${arg}`);
+        }
+    }
+    return options;
+}
+export function commandExists(command, env = process.env, platform = process.platform) {
+    const searchPath = env.PATH ?? env.Path ?? "";
+    const suffixes = platform === "win32" ? [".exe", ".cmd", ".bat", ""] : [""];
+    return searchPath.split(path.delimiter).filter(Boolean).some((directory) => suffixes.some((suffix) => {
+        try {
+            return fs.statSync(path.join(directory, command + suffix)).isFile();
+        }
+        catch {
+            return false;
+        }
+    }));
+}
+export function detectClients(context) {
+    const found = [];
+    const { env, home, exists } = context;
+    if (context.commandExists("codex") || Boolean(env.CODEX_HOME) || exists(path.join(home, ".codex")))
+        found.push("codex");
+    if (context.commandExists("claude"))
+        found.push("claude");
+    if (context.commandExists("zcode") || Boolean(env.ZCODE_HOME) || exists(path.join(home, ".zcode")))
+        found.push("zcode");
+    if (context.commandExists("cursor") || exists(path.join(home, ".cursor")))
+        found.push("cursor");
+    if (context.commandExists("code"))
+        found.push("vscode");
+    return found;
+}
+function asObject(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${label} must be a JSON object`);
+    return value;
+}
+export function mergeJsonServer(document, shape) {
+    const root = asObject(document, "configuration root");
+    let servers;
+    if (shape === "zcode") {
+        const mcp = root.mcp === undefined ? (root.mcp = {}) : root.mcp;
+        const mcpObject = asObject(mcp, "mcp");
+        const currentServers = mcpObject.servers === undefined ? (mcpObject.servers = {}) : mcpObject.servers;
+        servers = asObject(currentServers, "mcp.servers");
+    }
+    else {
+        const currentServers = root.mcpServers === undefined ? (root.mcpServers = {}) : root.mcpServers;
+        servers = asObject(currentServers, "mcpServers");
+    }
+    servers[SERVER_NAME] = { command: "npx", args: ["-y", PACKAGE_SPEC], env: {} };
+    return root;
+}
+function backupName(file) {
+    const stamp = new Date().toISOString().replace(/[-:.TZ]/g, "");
+    return `${file}.backup-${stamp}-${process.pid}`;
+}
+export function writeJsonClientConfig(file, shape, dryRun = false) {
+    const absolute = path.resolve(file);
+    const exists = fs.existsSync(absolute);
+    let document = {};
+    if (exists) {
+        const stat = fs.lstatSync(absolute);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error(`refusing non-regular config file: ${absolute}`);
+        try {
+            document = JSON.parse(fs.readFileSync(absolute, "utf8"));
+        }
+        catch (error) {
+            throw new Error(`invalid JSON in ${absolute}; no changes made: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const merged = mergeJsonServer(document, shape);
+    if (dryRun)
+        return null;
+    fs.mkdirSync(path.dirname(absolute), { recursive: true });
+    const backup = exists ? backupName(absolute) : null;
+    if (backup)
+        fs.copyFileSync(absolute, backup, fs.constants.COPYFILE_EXCL);
+    const temporary = `${absolute}.tmp-${process.pid}`;
+    try {
+        fs.writeFileSync(temporary, JSON.stringify(merged, null, 2) + "\n", { encoding: "utf8", flag: "wx" });
+        fs.renameSync(temporary, absolute);
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch { /* nothing to clean */ }
+        throw error;
+    }
+    return backup;
+}
+function codexConfigPath(env, home) {
+    return path.join(env.CODEX_HOME || path.join(home, ".codex"), "config.toml");
+}
+function zcodeConfigPath(env, home) {
+    return path.join(env.ZCODE_HOME || path.join(home, ".zcode"), "cli", "config.json");
+}
+function hasCodexServer(text) {
+    return /^\s*\[mcp_servers\.(?:pm-mcp|"pm-mcp")\]\s*$/m.test(text);
+}
+function appendCodexConfig(file, dryRun, log) {
+    const absolute = path.resolve(file);
+    const existing = fs.existsSync(absolute) ? fs.readFileSync(absolute, "utf8") : "";
+    if (hasCodexServer(existing)) {
+        log(`[skip] Codex already has ${SERVER_NAME}; use --force with the Codex CLI to replace it.`);
+        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 separator = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+    const block = `${separator}\n[mcp_servers.${SERVER_NAME}]\ncommand = "npx"\nargs = ["-y", "${PACKAGE_SPEC}"]\n`;
+    fs.appendFileSync(absolute, block, "utf8");
+}
+function run(command, args, visible) {
+    const result = spawnSync(command, args, {
+        shell: false,
+        windowsHide: true,
+        stdio: visible ? "inherit" : "ignore",
+    });
+    if (result.error)
+        return -1;
+    return result.status ?? -1;
+}
+function configureCliClient(client, options, available, log) {
+    if (!available)
+        return false;
+    const getArgs = ["mcp", "get", SERVER_NAME];
+    const exists = run(client, getArgs, false) === 0;
+    if (exists && !options.force) {
+        log(`[skip] ${client} already has ${SERVER_NAME}; run setup --force to replace it.`);
+        return true;
+    }
+    const addArgs = client === "codex"
+        ? ["mcp", "add", SERVER_NAME, "--", "npx", "-y", PACKAGE_SPEC]
+        : ["mcp", "add", SERVER_NAME, "--scope", "user", "--", "npx", "-y", PACKAGE_SPEC];
+    log(`[${options.dryRun ? "plan" : "run"}] ${client} ${addArgs.join(" ")}`);
+    if (options.dryRun)
+        return true;
+    if (exists && run(client, ["mcp", "remove", SERVER_NAME], true) !== 0)
+        throw new Error(`${client} could not remove the existing server`);
+    if (run(client, addArgs, true) !== 0)
+        throw new Error(`${client} could not add ${SERVER_NAME}`);
+    return true;
+}
+function configureClient(client, options, context, log) {
+    if (client === "codex") {
+        if (configureCliClient("codex", options, context.commandExists("codex"), log))
+            return;
+        appendCodexConfig(codexConfigPath(context.env, context.home), options.dryRun, log);
+        return;
+    }
+    if (client === "claude") {
+        if (!configureCliClient("claude", options, context.commandExists("claude"), log))
+            throw new Error("claude was not found in PATH");
+        return;
+    }
+    if (client === "zcode" || client === "cursor") {
+        const file = client === "zcode" ? zcodeConfigPath(context.env, context.home) : path.join(context.home, ".cursor", "mcp.json");
+        log(`[${options.dryRun ? "plan" : "write"}] ${client}: ${file}`);
+        const backup = writeJsonClientConfig(file, client === "zcode" ? "zcode" : "standard", options.dryRun);
+        if (backup)
+            log(`[backup] ${backup}`);
+        return;
+    }
+    if (!context.commandExists("code"))
+        throw new Error("code was not found in PATH");
+    const definition = JSON.stringify({ name: SERVER_NAME, command: "npx", args: ["-y", PACKAGE_SPEC] });
+    log(`[${options.dryRun ? "plan" : "run"}] code --add-mcp ${definition}`);
+    if (!options.dryRun && run("code", ["--add-mcp", definition], true) !== 0)
+        throw new Error("VS Code could not add pm-mcp");
+}
+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("Default auto mode configures every detected supported client.");
+}
+export function runSetup(argv, overrides = {}) {
+    const options = parseSetupArgs(argv);
+    const log = overrides.log ?? console.log;
+    if (options.help) {
+        printHelp(log);
+        return 0;
+    }
+    if (options.client === "print") {
+        log(JSON.stringify({ mcpServers: { [SERVER_NAME]: { command: "npx", args: ["-y", PACKAGE_SPEC], env: {} } } }, null, 2));
+        return 0;
+    }
+    const env = overrides.env ?? process.env;
+    const home = overrides.home ?? os.homedir();
+    const context = {
+        env,
+        home,
+        commandExists: overrides.commandExists ?? ((command) => commandExists(command, env)),
+        exists: overrides.exists ?? fs.existsSync,
+    };
+    const selected = options.client === "all"
+        ? CLIENTS
+        : options.client === "auto"
+            ? detectClients(context)
+            : [options.client];
+    if (selected.length === 0) {
+        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(", ")}`);
+    let failures = 0;
+    for (const client of selected) {
+        try {
+            configureClient(client, options, context, log);
+        }
+        catch (error) {
+            failures += 1;
+            console.error(`[failed] ${client}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (failures > 0)
+        return 1;
+    log("Done. Restart the configured client and ask it to call pm-mcp get_status.");
+    return 0;
+}

package/dist/store.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 import { DebugLogFileSchema, FeaturesFileSchema, FileNotesFileSchema, now, ProjectSchema, RoadmapFileSchema, SecurityFileSchema, SessionsFileSchema, TasksFileSchema, } from "./types.js";
 import { DEBUGLOG_JSON, EXTRA_RULES_FILE, FEATURES_JSON, FILE_NOTES_JSON, PROJECT_JSON, ROADMAP_JSON, SECURITY_JSON, SESSIONS_JSON, TASKS_JSON, pmPath, } from "./paths.js";
 import { ExtraRulesFileSchema } from "./types.js";
@@ -39,24 +40,55 @@ export function saveJson(file, data) {
 }
 /**
  * 账本互斥锁：把「读账本 → 改 → 写」整个事务串行化，多客户端（如 ZCode+Codex 并行）
- * 不再互相覆盖丢数据。锁文件 .pm/.lock（O_EXCL 创建）；持有超过 10s 视为残留强制接管
- * （进程崩溃不留死锁）；等待上限 3s，超时明确报错而非静默丢写。
+ * 不再互相覆盖丢数据。锁文件 .pm/.lock（O_EXCL 创建）；超过 10s 且持锁进程已死亡
+ * 才视为残留并接管。活着的长任务不会被误抢锁；释放时也只删除自己的 token。
+ * 等待上限 3s，超时明确报错而非静默丢写。
  */
 export function withLedgerLock(root, fn) {
     const lockFile = pmPath(root, ".lock");
     fs.mkdirSync(pmPath(root), { recursive: true });
+    const token = randomUUID();
+    const payload = JSON.stringify({ pid: process.pid, token, created_at: new Date().toISOString() });
+    const owner = () => {
+        try {
+            const raw = fs.readFileSync(lockFile, "utf8");
+            try {
+                const parsed = JSON.parse(raw);
+                return typeof parsed.pid === "number"
+                    ? { pid: parsed.pid, ...(typeof parsed.token === "string" ? { token: parsed.token } : {}) }
+                    : null;
+            }
+            catch {
+                const pid = Number(raw.trim());
+                return Number.isInteger(pid) && pid > 0 ? { pid } : null;
+            }
+        }
+        catch {
+            return null;
+        }
+    };
+    const alive = (pid) => {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (error) {
+            return error.code === "EPERM";
+        }
+    };
     const acquire = () => {
         try {
-            fs.writeFileSync(lockFile, String(process.pid), { flag: "wx" });
+            fs.writeFileSync(lockFile, payload, { flag: "wx" });
             return true;
         }
         catch {
             try {
                 const st = fs.statSync(lockFile);
-                if (Date.now() - st.mtimeMs > 10_000) {
+                const current = owner();
+                if (Date.now() - st.mtimeMs > 10_000 && (!current || !alive(current.pid))) {
                     fs.rmSync(lockFile, { force: true });
                     try {
-                        fs.writeFileSync(lockFile, String(process.pid), { flag: "wx" });
+                        fs.writeFileSync(lockFile, payload, { flag: "wx" });
                         return true;
                     }
                     catch {
@@ -84,7 +116,8 @@ export function withLedgerLock(root, fn) {
     }
     finally {
         try {
-            fs.rmSync(lockFile, { force: true });
+            if (owner()?.token === token)
+                fs.rmSync(lockFile, { force: true });
         }
         catch {
             /* 尽力释放 */

package/dist/task-tools.js

@@ -4,7 +4,7 @@ import { foldLines, normSep } from "./budget.js";
 import { requireInitialized } from "./paths.js";
 import { loadRoadmap, loadTasks, nextId, saveTasks } from "./store.js";
 import { now } from "./types.js";
-import { budgetLines, tool, toolW } from "./tool-base.js";
+import { budgetLines, toolR, toolW } from "./tool-base.js";
 const stepSchema = z.object({ text: z.string(), done: z.boolean().optional() });
 export function registerTaskTools(server, root) {
     toolW(server, root, "add_task", "添加任务。长任务务必给 steps（显式步骤清单，断点续做的载体）；走了捷径 type=debt 登记（债务账）；修 bug type=fix。", {
@@ -55,7 +55,7 @@ export function registerTaskTools(server, root) {
             : "";
         return `✅ 任务 ${id}「${args.title}」已创建（${args.type ?? "feature"}/${args.milestone ?? "无里程碑"}）。${tip}`;
     });
-    tool(server, "list_tasks", "列出任务（默认不含 done/cancelled）。可按状态/类型/里程碑/标签过滤。", {
+    toolR(server, root, "list_tasks", "列出任务（默认不含 done/cancelled）。可按状态/类型/里程碑/标签过滤。", {
         status: z.enum(["backlog", "todo", "in_progress", "blocked", "done", "cancelled"]).optional(),
         type: z.enum(["feature", "refactor", "fix", "chore", "debt"]).optional(),
         milestone: z.string().optional(),

package/dist/tool-base.js

@@ -1,21 +1,44 @@
-import { loadProject, withLedgerLock } from "./store.js";
-export function tool(server, name, description, schema, fn) {
-    server.registerTool(name, { description, inputSchema: schema }, (async (args) => {
+import { loadProject } from "./store.js";
+import { IdempotencyKeySchema, runCoalescedRead, runIdempotentWrite, runIdempotentWriteSync } from "./idempotency.js";
+/** 只读工具：跨 Agent/进程合并完全相同的并行请求，短窗复用结果。 */
+export function toolR(server, root, name, description, schema, fn) {
+    server.registerTool(name, { description, inputSchema: schema, annotations: { readOnlyHint: true } }, (async (args) => {
         try {
-            const text = await fn(args);
-            return { content: [{ type: "text", text }] };
+            const result = await runCoalescedRead(root, name, args, fn);
+            return { content: [{ type: "text", text: result.text }] };
         }
         catch (error) {
             return { content: [{ type: "text", text: `错误: ${error.message}` }], isError: true };
         }
     }));
 }
-/** 写工具必须使用同步 handler，保证跨进程账本锁覆盖完整读-改-写。 */
+const idempotencyDescription = "多 Agent 执行同一业务时传相同 idempotency_key；同键同参数只执行一次，同键不同参数拒绝。";
+function writeSchema(schema) {
+    return {
+        ...schema,
+        idempotency_key: IdempotencyKeySchema.optional().describe("跨 Agent 业务幂等键，建议格式 task-id:operation，如 T-123:add-task"),
+    };
+}
+/** 同步写工具：业务幂等占位 + 跨进程账本锁覆盖完整读-改-写。 */
 export function toolW(server, root, name, description, schema, fn) {
-    server.registerTool(name, { description, inputSchema: schema }, ((args) => {
+    server.registerTool(name, { description: `${description} ${idempotencyDescription}`, inputSchema: writeSchema(schema), annotations: { readOnlyHint: false } }, ((args) => {
+        try {
+            const result = runIdempotentWriteSync(root, name, args, fn);
+            const prefix = result.replayed ? `↩️ 幂等复用 ${result.key}\n` : result.pending ? `⏳ 幂等占位 ${result.key}\n` : "";
+            return { content: [{ type: "text", text: prefix + result.text }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `错误: ${error.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) => {
         try {
-            const text = withLedgerLock(root, () => fn(args));
-            return { content: [{ type: "text", text }] };
+            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 }] };
         }
         catch (error) {
             return { content: [{ type: "text", text: `错误: ${error.message}` }], isError: true };

package/dist/tools.js

@@ -15,7 +15,7 @@ export function registerAllTools(server, root) {
     registerSessionTools(server, root);
     registerSearchTools(server, root);
     registerAuditTools(server, root);
-    registerRegistryTools(server);
+    registerRegistryTools(server, root);
     registerGovernanceTools(server, root);
     registerAcceptanceTools(server, root);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckychen1993/pm-mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "AI 编码项目的单一事实来源 + 健康台账 MCP 服务（事实来源 / 路线图 / 防幻觉 / 七本账 / 断点续做 / token 经济）",
   "keywords": [
     "mcp",
@@ -26,7 +26,7 @@
     "dist/"
   ],
   "bin": {
-    "pm-mcp": "dist/index.js"
+    "pm-mcp": "dist/cli.js"
   },
   "main": "dist/index.js",
   "engines": {