@luckychen1993/pm-mcp 0.1.5 → 0.4.0

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

@@ -8,6 +8,42 @@
 
 > 核心理念：**把恶化从「无声发生」变成「显式记账」，把上下文从「模型记忆」搬到「仓库文件」。**
 
+当前源码为 **0.3.0 本地候选版本，尚未由本轮工作发布**。下方公共安装示例仍使用已发布的 0.1.5。候选版可用 `setup --local` 绑定已构建的本地入口；未发布前不要配置依赖注册表中 0.3.0 的 npx 启动项。
+
+## 0.3.0：升级生效、任务取全与证据分级
+
+- `get_status` 同时显示当前进程的运行版本、项目根和结构化 runtime，避免把项目 phase 中的旧文字当作实际版本。
+- `list_tasks` 默认每页 25 条，可用 `page_size`（1–100，受输出预算限制）和 `next_cursor` 连续读取；保持原过滤条件，数据变化会使游标失效。文字及结构化结果都给出本页范围、总数和后续游标。长标题/下一步可能缩略，但编号与分页条目完整。`pm://tasks` 的大列表也提供 continuation。
+- 质量摘要标明 `execution_only`、`tests_observed`、`coverage_observed` 等观测等级及计数来源。支持 Node、Jest、Vitest、pytest 的常见英文摘要；无法识别时明确保留未知计数，不猜测为零。等级不等于测试充分性、通过结果或防篡改认证。
+- feature/fix 默认必须具有可识别的非零测试及完整状态计数。需要兼容无计数运行器时，由项目负责人明确设置 `update_project({completion_evidence:{minimum:"execution_only",reason:"说明至少八个字的具体理由"}})`；完成记录仍标出弱证据等级。已知零测试、失败、跳过、截断或过期证据始终拒绝。
+- 质量子进程不会继承 Node 宿主的内部 `NODE_TEST_CONTEXT`，避免嵌套 `node --test` 跳过文件却退出 0。
+
+本地候选的 Codex 项目升级在构建后按以下步骤执行。先预览，再替换该项目的 command/args，保留其他设置与工具预算：
+
+```powershell
+npm run build
+node dist/cli.js setup --client codex --project --local --force --dry-run
+node dist/cli.js setup --client codex --project --local --force
+node dist/cli.js doctor --root .
+```
+
+`doctor` 会核对配置并建立短期本地 MCP 读连接，检查实际版本、项目根、48 工具与新参数契约；不会把探测新进程冒充已经重连的客户端。探测不复制自定义凭据环境；结果会产生既有运行计量。显式 `--entry <本地入口>` 可用于安装包检查。配置更新后仍需在实际客户端重新连接，再调用 get_status 确认版本。复杂或歧义配置会拒绝自动替换，已有配置与升级前备份保留。
+
+验收脚本从 `package.json` 的 `pm_mcp.acceptance_baseline` 统一读取基线 ID/版本，命令行可显式覆盖。批准记录不自动升版、不选择猜测的“最新”文件；本仓选择 1.1.0，原 1.0.0 保留。新版评价使用对应版本的计划与失败记录。
+
+## 已有管理流程
+
+用户仍然直接说“继续这个任务”“保存进度”“完成后帮我验收”。52 个工具全部保留，由 AI 组合调用，无需用户记工具名。
+
+- `update_task` 可同时更新进度、保存 `checkpoint:{note,next_step}` 并记录会话；完成时给 `record_session:true`，返回会话编号后不再另调 `log_session`。省略该参数仍兼容旧的手动记会话流程。同一幂等键重放不会重复落账；跨多个文件的异常仍遵守原有“不确定状态需核对”规则，不宣称事务原子性。
+- `feature/fix` 转 `done` 必须关联实际文件，并先通过 `run_quality_matrix` 执行相应测试。系统自动选择最新报告，核对执行成功、测试前后与当前源码摘要、测试单元目录和项目证据策略。`verification_run` 可明确指向最新报告，文字 `verification` 只作补充说明。报告存于 `.pm/quality-runs/`，任务保存报告与源码 SHA-256。目录范围匹配不等于代码覆盖率证明；第一方报告也不构成防篡改认证。
+- Git 对账按所有会话的文件内容摘要核对，保留删除、重命名和中文路径。旧版只有路径的记录标为“未验证”；同一路径内容再次变化仍会告警。这里只核对当前工作区内容，不代替暂存区审查或提交验收。
+- 扫描、索引、搜索、语言发现和源码指纹共用排除规则，默认排除 `.runtime`、`.zcode`、`EBWebView` 等缓存。含义不明确的 `release`、`userdata` 不默认隐藏；确认是产物后由 AI 用 `update_project({scan_ignore:["release/**"]})` 配置，传 `[]` 恢复。报告列明自定义排除范围，规则变动会刷新索引并使旧质量证据失效。
+
+旧账本保持可读，历史已完成任务不会自动重开；新增字段为可选字段。所有读写同一项目的 MCP 进程应统一升级并重启，旧版本写入可能丢弃新元数据。已有 `AGENTS.md` 保留原文；新初始化项目和内置 `end-session` 提示使用合并流程。
+
+仓库测试默认同时运行两个测试文件，避免文件级并发与内部进程压力叠加；20 进程竞争等测试的内部并发、锁超时和覆盖率门槛保持原设定。这是测试资源控制，不是产品并发能力或生产负载的证明。
+
 ## 为什么需要它
 
 AI 编码项目的典型失控（本工具逐一给出机制）：
@@ -32,7 +68,7 @@ AI 编码项目的典型失控（本工具逐一给出机制）：
 
 ## 一个命令自动添加到 AI 编程助手
 
-本页安装示例固定使用 **0.1.5**，包含安全扫描、项目命名和字面量搜索修复。0.1.4 不支持 `setup --project`；验证这些能力时请确认实际运行版本为 0.1.5 或更新版本。
+本页安装示例使用 npm 上最新的**已发布**版本（当前为 **0.1.5**）。0.1.4 不支持 `setup --project`；验证这些能力时请确认实际运行版本为 0.1.5 或更新版本。仓库源码当前为 **0.3.0**（新增任务游标分页、完成证据分级、受控升级与 WorkBuddy 客户端等），**尚未发布到 npm**——需要这些能力时请从源码构建，或见下方各客户端的本地入口用法。
 
 要求：Node.js ≥ 22.18。Windows、macOS 和 Linux 使用同一条命令：
 
@@ -40,13 +76,23 @@ AI 编码项目的典型失控（本工具逐一给出机制）：
 npx -y @luckychen1993/pm-mcp@latest setup
 ```
 
-安装器自动检测本机的 Codex、Claude Code、ZCode、Cursor 和 VS Code，并配置所有检测到的客户端。JSON 配置会先备份；已经存在的 Codex/Claude 配置默认保留，用 `setup --force` 才替换。先预览、不写配置：
+安装器自动检测本机的 Codex、Claude Code、ZCode、Cursor、VS Code 和 WorkBuddy，并配置所有检测到的客户端。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，也不会调用远程模型。
+非标准安装路径无法自动发现时，可在同一命令末尾指定 `--client codex|claude|zcode|cursor|vscode|workbuddy`；`--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 必用）
 
@@ -86,6 +132,37 @@ $u='https://raw.githubusercontent.com/happy520ai/pm-mcp/v0.1.5/install.ps1'; $f=
 
 脚本只写对应客户端的 MCP 配置；已有 JSON 配置会先生成带时间戳的备份。建议执行前先打开 [`install.ps1`](install.ps1) 审阅。ZCode 默认写入 `$ZCODE_HOME/cli/config.json` 或 `~/.zcode/cli/config.json`，Cursor 默认写入 `~/.cursor/mcp.json`；也可用 `-ConfigPath` 指定路径。
 
+#### WorkBuddy 桌面版
+
+> **要求 pm-mcp ≥ 0.3.0**：`--client workbuddy` 是 0.3.0 新增的客户端；npm 上当前的 0.1.5 **不支持**该参数，直接跑会报 `--client must be auto, all, codex, claude, zcode, cursor, vscode, or print`。
+
+0.3.0 发布后：
+
+```bash
+npx -y @luckychen1993/pm-mcp@latest setup --client workbuddy
+```
+
+0.3.0 发布前，从源码构建后用本地入口接入（`--local` 绑定本包已构建的 `dist/index.js`）：
+
+```bash
+npm ci && npm run build
+node dist/cli.js setup --client workbuddy --local
+```
+
+写入 `<WorkBuddy 数据目录>/mcp.json`，结构与下方通用 JSON 一致。数据目录按 `WORKBUDDY_CONFIG_DIR` → `~/.workbuddy-ai`（当前版本）→ `~/.workbuddy`（旧版）顺序解析，写入前会生成带时间戳的备份，未知顶层字段与既有 server 全部保留。
+
+与其他客户端的关键差别：**WorkBuddy 的条目刻意不写 `--root`**。它的 MCP 子进程由会话工作区拉起，cwd 即当前项目，服务端按 cwd 解析项目根——因此一条配置同时服务所有工作区，不需要逐项目钉根；未初始化的目录只返回「未初始化」，不会写入任何文件。
+
+⚠️ 注意该设计的边界：**跨项目操作会失效**。若在 A 项目的会话里让 pm-mcp 去改 B 项目，它读到的始终是 A（MCP 子进程的 cwd 就是会话工作区）。跨项目时请在目标项目的会话内操作，或改用显式钉根的配置。
+
+接入后用 `doctor` 核验（它会读取该 `mcp.json` 的 pm-mcp 条目并做真实握手）：
+
+```bash
+node dist/cli.js doctor --root . --client workbuddy           # 核验 48 工具与项目根
+```
+
+`doctor` 会读取该 `mcp.json` 的 pm-mcp 条目，只认可识别的本地 pm-mcp 启动项（npx 发布版或 node + 本包 `dist/index.js`），被 `disabled` 的条目与未知启动器一律拒绝，且不读取或转发自定义凭据环境。配置完成后需在 WorkBuddy 的「连接器管理 → 自定义连接器」中确认信任 pm-mcp，再重开会话调用 `get_status` 核验。
+
 #### 其他支持 stdio MCP 的客户端
 
 ```json
@@ -110,6 +187,32 @@ $u='https://raw.githubusercontent.com/happy520ai/pm-mcp/v0.1.5/install.ps1'; $f=
 | `PM_ROOT` | 项目根（次优先级） |
 | `PM_MCP_HOME` | 全局注册表重定向（默认 `~`；多环境/测试隔离用） |
 
+### pm-mcp probe：标准 raw tools/list 直连探针
+
+宿主（ZCode/Codex/Cursor 等）是唯一 MCP client 持有者，不会向模型透传原始 `tools/list`；要拿服务器在协议线上的真实工具清单，用 `probe` 绕过宿主直连：
+
+```bash
+node dist/cli.js probe -- node dist/index.js --root .
+node dist/cli.js probe --timeout 10000 --expect get_status,list_tasks,search_code -- node dist/index.js --root .
+node dist/cli.js probe --expect-file 上一轮probe报告.json -- node 其他服务器/dist/index.js
+```
+
+- 输出原始工具清单 JSON（`tools` 含 name/description/inputSchema，自动翻页取全）与 `serverInfo`；退出码 0/1。
+- `--expect` 与期望工具表比对（如从 Codex `config.toml` 的 `[mcp_servers.X.tools.*]` 提取），缺失/多余都会列进 `issues` 并置 `ok:false`。
+- `--expect-file` 接受上一轮 probe 报告、字符串数组或 `{tools:[...]}`，便于跨项目基线比对。
+- 探测进程与服务器子进程在结束时都会被清理，不会残留。
+
+### pm-mcp ui：本地只读 Web 仪表盘
+
+```bash
+node dist/cli.js ui --root .            # 端口自动分配
+node dist/cli.js ui --root . --port 7781
+```
+
+- 仅绑定 `127.0.0.1`、纯 GET 只读、未纳管项目拒绝启动；概览（任务/功能/安全/会话/索引/质量门禁）+ 里程碑进度 + 最近任务。
+- `/api/state` 输出同源 JSON，`/healthz` 健康检查；所有插值 HTML 转义，CSP 禁止脚本。
+- Ctrl+C 退出。不新增 MCP 工具，不改变工具目录契约。
+
 ## 推荐工作流（写给 AI 的规矩）
 
 把下面这段放进目标项目的 `AGENTS.md`，任何 AI 会话自动遵守：
@@ -126,16 +229,16 @@ $u='https://raw.githubusercontent.com/happy520ai/pm-mcp/v0.1.5/install.ps1'; $f=
 4. 陈述本次计划：做哪个任务、动哪些文件、验收标准
 
 ## 做事过程
-- 长任务：add_task 时给 steps；上下文快满或中断前 checkpoint 存断点
+- 长任务：add_task 时给 steps；update_task 附 checkpoint 一次更新进度与会话
 - 走捷径：立刻 add_task(type=debt) 登记债务，不许无声欠债
 - 修 bug：完成后 log_debug 记录症状/根因/修法/验证
 - 陈述"某功能在某文件"之前，先 search_code 求证
 
 ## 收工（缺一不可）
-1. 完成的任务 update_task 置 done + result_note；feature/fix 补 verification
+1. feature/fix 先 run_quality_matrix 执行测试；update_task 置 done + result_note + files，record_session:true 一并归档
 2. 未完成任务 checkpoint（进展 + 下一步）
 3. 落地的功能 register_feature（入口文件 + 测试文件）
-4. log_session 如实记录改动文件清单
+4. update_task 已返回自动会话编号时不重复 log_session；否则如实记录改动文件清单。纯问答无需新建任务或重复记账
 
 ## 每个里程碑节点
 snapshot_codebase + audit_structure 对账；audit_security 安全体检；audit_license 许可证审计；audit_governance 模块/语言边界审计；plan_quality_matrix 生成真实质量矩阵
@@ -143,16 +246,16 @@ snapshot_codebase + audit_structure 对账；audit_security 安全体检；audit
 
 也可以直接用内置 prompts：`start-session` / `end-session` / `onboard` / `architecture-review` / `acceptance-review`；其中 `onboard` 会引导客户端读取状态并生成新人/AI 入职简报。
 
-## 工具清单（48 个）
+## 工具清单（52 个）
 
 | 域 | 工具 | 说明 |
 |---|---|---|
 | 状态 | `init_project` / `get_status` / `update_project` / `regenerate_dashboard` | 初始化、一站式「我在哪」（`since` 汇总任务/会话变化）、改元信息与预算、重生成仪表盘 |
 | 路线图 | `add_milestone` / `update_milestone` / `get_roadmap` | 里程碑生命周期；depth=1 单行摘要 / depth=2 展开活跃任务 |
-| 任务 | `add_task` / `list_tasks` / `update_task` / `checkpoint` | 类型 feature/refactor/fix/chore/debt；转 done 强制 result_note；断点存档 |
+| 任务 | `add_task` / `list_tasks` / `update_task` / `checkpoint` | 进度/断点/会话合并更新；feature/fix 完成强制关联文件与最新真实测试报告 |
 | 功能 | `register_feature` / `list_features` | 功能地图（入口文件 = 漂移对账锚点；测试文件 = 测试背书） |
 | 决策 | `record_decision` / `list_decisions` | ADR 架构决策记录（不可变编号） |
-| 会话 | `log_session` | 收工仪式：摘要 + 变更足迹 + 下一步（churn 数据源） |
+| 会话 | `log_session` | 摘要 + 变更足迹/内容摘要 + 下一步（churn 与 Git 内容对账来源） |
 | 调试 | `log_debug` | 调试知识账：症状/根因/修法/验证 |
 | 求证 | `search_code` / `search_knowledge` / `annotate_file` | 代码检索（file:line）、七类知识源检索（含模块/接口/仓库治理）、文件用途索引 |
 | 审计 | `snapshot_codebase` / `audit_structure` | 结构快照；完整性/增长/漂移/债务/churn/复杂度/索引/足迹/测试/Git 十节对账 |
@@ -161,8 +264,8 @@ snapshot_codebase + audit_structure 对账；audit_security 安全体检；audit
 | 可观测 | `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/覆盖率与变更反向闭包 |
-| 质量与组合 | `plan_quality_matrix` / `run_quality_matrix` / `get_portfolio` | plan 与真实执行严格分离；shell=false；跨仓阶段/债务/安全/版本/cycle 聚合 |
+| 语义治理 | `discover_languages` / `audit_governance` / `dependency_graph` / `impact_analysis` / `list_semantic_evidence` / `save_semantic_evidence` / `replace_semantic_evidence_for_file` | 编译器/Tree-sitter AST 关系、hash-bound 原生分析器/运行时证据、模块与文件级循环、依赖邻域/枢纽/unresolved/覆盖率与变更反向闭包 |
+| 质量与组合 | `plan_quality_matrix` / `run_quality_matrix` / `get_portfolio` / `find_duplicates` / `audit_osv` | plan 与真实执行严格分离；shell=false；跨仓阶段/债务/安全/版本/cycle 聚合；行指纹聚类跨文件重复块；OSV 联网漏洞比对（默认关，须显式 confirm=true） |
 | 标准化验收 | `list_acceptance_baselines` / `get_acceptance_baseline` / `save_acceptance_baseline_draft` / `approve_acceptance_baseline` / `evaluate_acceptance` | ISO/SQuaRE 对齐的版本化质量基线、冻结证据指针、需求—风险—测试追踪、机器判定报告与 SHA-256 manifest |
 
 Resources：`pm://dashboard`、`pm://roadmap`、`pm://tasks`、`pm://changelog`、`pm://architecture`、`pm://portfolio`、`pm://acceptance`。

package/dist/agents-md.js

@@ -19,16 +19,16 @@ const SECTION = `${BEGIN}
 3. 陈述本次计划：做哪个任务、动哪些文件、验收标准
 
 ## 做事过程
-- 长任务：add_task 时给 steps；上下文快满或中断前 checkpoint 存断点
+- 长任务：add_task 时给 steps；用 update_task 附 checkpoint 一次更新进度与会话；保留独立 checkpoint 兼容旧流程
 - 走捷径：立刻 add_task(type=debt) 登记债务，不许无声欠债
 - 修 bug：完成后 log_debug 记录症状/根因/修法/验证
 - 陈述「某功能在某文件」之前，先 search_code 求证
 
 ## 收工（缺一不可）
-1. 完成的任务 update_task 置 done + result_note；feature/fix 补 verification
+1. feature/fix 先执行相应测试并生成当前源码的质量报告；update_task 置 done + result_note + files，设 record_session:true 一并归档
 2. 未完成任务 checkpoint（进展 + 下一步具体动作）
 3. 落地的功能 register_feature（入口文件 + 测试文件）
-4. log_session 如实记录改动文件清单
+4. update_task 已返回自动会话编号时不重复 log_session；否则用 log_session 如实记录改动文件清单。纯问答无需新建任务或重复记账
 
 ## 每个里程碑节点
 snapshot_codebase + audit_structure 对账；audit_security 安全体检；audit_license 许可证审计

package/dist/audit-tools.js

@@ -8,6 +8,8 @@ import { listRegistry } from "./registry.js";
 import { auditSecurity, listFindings, prepareSecurityAudit, resolveFinding } from "./security.js";
 import { budgetLines, toolR, toolW } from "./tool-base.js";
 import { walkRefresh } from "./index-store.js";
+import { renderDuplicates } from "./duplicates.js";
+import { renderOsv, auditOsv } from "./osv.js";
 export function registerAuditTools(server, root) {
     toolW(server, root, "snapshot_codebase", "给代码结构拍快照（文件数/行数/目录分布/测试数/skip 标记/依赖清单）。之后 audit_structure 会与上次快照 diff。建议每个会话或每个里程碑结束时拍一次。", {}, () => {
         requireInitialized(root);
@@ -19,6 +21,21 @@ export function registerAuditTools(server, root) {
         requireInitialized(root);
         return auditStructure(root, budgetLines(root), true);
     });
+    toolR(server, root, "find_duplicates", "重复代码检测：注释剥离/字符串占位/空白归一化的行指纹滑动窗口聚类，跨文件重复块按长度降序列出。", {
+        min_lines: z.number().int().min(4).max(20).optional().describe("最小重复行数（有效代码行），默认 6"),
+        limit: z.number().int().min(1).max(100).optional().describe("最多列出的重复组数，默认 20"),
+    }, (args) => {
+        requireInitialized(root);
+        return renderDuplicates(root, args ?? {}, budgetLines(root));
+    });
+    toolR(server, root, "audit_osv", "OSV.dev 已知漏洞查询（联网！默认关）：把 manifest 声明的依赖（仅包名/版本/生态）批量发给 api.osv.dev 比对；必须显式 confirm=true 才发起网络请求。", {
+        confirm: z.literal(true).describe("显式确认联网：本工具会把依赖名与版本发送到 api.osv.dev"),
+        timeout_ms: z.number().int().min(5000).max(120000).optional().describe("每批请求超时毫秒数，默认 30000"),
+    }, async (args) => {
+        requireInitialized(root);
+        const scan = await auditOsv(root, { timeoutMs: args.timeout_ms });
+        return renderOsv(scan, budgetLines(root));
+    });
     toolW(server, root, "audit_security", "安全体检（只扫描本地、不联网，结果写入安全台账）：密钥泄露 / 危险模式（eval、SQL 拼接、禁用证书校验等）/ 依赖风险。修复后重扫自动关闭；接受风险必须留理由。", {}, (_args, prepared) => {
         requireInitialized(root);
         const report = auditSecurity(root, prepared);

package/dist/audit.js

@@ -1,14 +1,15 @@
 import fs from "node:fs";
 import path from "node:path";
-import { spawnSync } from "node:child_process";
 import { loadFeatures, loadFileNotes, loadProject, loadRoadmap, loadSessions, loadTasks, saveJson, } from "./store.js";
 import { decisionsDir, pmPath, snapshotsDir } from "./paths.js";
-import { normSep, foldLines } from "./budget.js";
+import { foldLines } from "./budget.js";
 import { readDirectDeps } from "./scan.js";
 import { aggregates, ensureFresh, freshness, getIndex, getMeta, walkRefresh } from "./index-store.js";
 import { quotaWarnings, milestoneStats } from "./roadmap.js";
 import { blastRadiusWarning, churnStats, debtAging, footprint } from "./health.js";
 import { now } from "./types.js";
+import { changedGitFiles, captureFileHashes } from "./git-state.js";
+import { scanExclusionNote } from "./scan-policy.js";
 /* --------------------------------- 快照 ---------------------------------- */
 /** 用途索引覆盖：登记过用途且真实存在的文件数 */
 export function annotatedCount(root, db) {
@@ -130,7 +131,7 @@ export function pmIntegrity(root) {
 }
 /** git 对账：自报变更足迹 vs 真实工作区状态 */
 export function gitAudit(root) {
-    const out = { available: false, unaccounted: [], ignoresPm: false, error: null };
+    const out = { available: false, unaccounted: [], unverified: [], ignoresPm: false, error: null };
     if (!fs.existsSync(path.join(root, ".git")))
         return out;
     out.available = true;
@@ -148,23 +149,23 @@ export function gitAudit(root) {
         }
     }
     // -uall：未跟踪目录展开为具体文件（默认只给 "?? src/" 目录缩写，抓不到文件）
-    const status = spawnSync("git", ["status", "--porcelain", "-uall"], { cwd: root, encoding: "utf8", timeout: 10_000 });
-    if (status.error || status.status !== 0) {
-        out.error = status.error?.message ?? `git status 退出码 ${status.status ?? "未知"}: ${(status.stderr ?? "").trim().slice(0, 200)}`;
-        return out;
+    try {
+        const changed = changedGitFiles(root);
+        const hashes = captureFileHashes(root, changed);
+        const sessions = loadSessions(root).sessions;
+        for (const rel of changed) {
+            const receipts = sessions.filter((session) => session.files.includes(rel) && typeof session.file_hashes?.[rel] === "string");
+            if (receipts.some((session) => session.file_hashes[rel] === hashes[rel]))
+                continue;
+            if (receipts.length === 0 && sessions.some((session) => session.files.includes(rel)))
+                out.unverified.push(rel);
+            else
+                out.unaccounted.push(rel);
+        }
     }
-    const changed = new Set();
-    for (const line of status.stdout.split("\n")) {
-        const rel = normSep(line.slice(3).trim().split(" -> ").pop() ?? "");
-        if (!rel)
-            continue;
-        if (rel.startsWith(".pm/") || rel === "PROJECT.md" || rel === ".gitignore")
-            continue;
-        changed.add(rel);
+    catch (error) {
+        out.error = error.message;
     }
-    const sessions = loadSessions(root).sessions;
-    const lastFiles = new Set(sessions[sessions.length - 1]?.files ?? []);
-    out.unaccounted = [...changed].filter((f) => !lastFiles.has(f));
     return out;
 }
 /** 完整结构对账：九项报告 */
@@ -343,6 +344,7 @@ export function auditStructure(root, maxLines = 150, forceFresh = false, indexPr
     const git = gitAudit(root);
     L.push("");
     L.push("## ⑨ git 对账（自报足迹 vs 真实工作区）");
+    L.push(...scanExclusionNote(root));
     if (git.available) {
         if (git.error) {
             L.push(`- 🚩 git status 对账失败（fail-closed）: ${git.error}`);
@@ -351,10 +353,12 @@ export function auditStructure(root, maxLines = 150, forceFresh = false, indexPr
             L.push("- 🚩 .gitignore 把 .pm/ 排除出版本控制——团队与多 AI 共享失效，状态只活在你本机。请移除该规则并提交 .pm/。");
         }
         if (git.unaccounted.length > 0) {
-            L.push(`- 🚩 ${git.unaccounted.length} 个文件有 git 变更但未在最近一次会话入账（log_session 漏报会被这里抓到）: ${git.unaccounted.slice(0, 5).join(", ")}`);
+            L.push(`- 🚩 ${git.unaccounted.length} 个文件的当前 git 变更未被会话内容证据覆盖: ${git.unaccounted.slice(0, 5).join(", ")}`);
         }
-        if (!git.error && !git.ignoresPm && git.unaccounted.length === 0) {
-            L.push("✅ 工作区变更与最近会话足迹一致。");
+        if (git.unverified.length)
+            L.push(`- ⚠️ ${git.unverified.length} 个文件已有旧版路径记录，但缺少当前内容摘要，尚未验证: ${git.unverified.slice(0, 5).join(", ")}`);
+        if (!git.error && !git.ignoresPm && git.unaccounted.length === 0 && git.unverified.length === 0) {
+            L.push("✅ 工作区变更与已记录的会话内容证据一致。");
         }
     }
     else {

package/dist/cli.js

@@ -9,6 +9,60 @@ if (process.argv[2] === "setup") {
         process.exitCode = 1;
     }
 }
+else if (process.argv[2] === "doctor") {
+    try {
+        const { parseDoctorArgs, runDoctor } = await import("./doctor.js");
+        if (process.argv.includes("--help") || process.argv.includes("-h"))
+            console.log("pm-mcp doctor --root <项目> [--client codex|workbuddy] [--config <配置文件> | --entry <本地入口>]");
+        else {
+            const result = await runDoctor(parseDoctorArgs(process.argv.slice(3)));
+            console.log(JSON.stringify(result, null, 2));
+            process.exitCode = result.ok ? 0 : 1;
+        }
+    }
+    catch (error) {
+        console.error(`[pm-mcp doctor] ERROR: ${error.message}`);
+        process.exitCode = 1;
+    }
+}
+else if (process.argv[2] === "ui") {
+    try {
+        const { startUiServer } = await import("./ui.js");
+        const args = process.argv.slice(3);
+        const value = (flag) => {
+            const index = args.indexOf(flag);
+            return index >= 0 ? args[index + 1] : undefined;
+        };
+        const root = value("--root") ?? process.cwd();
+        const portArg = value("--port");
+        const { url, close } = await startUiServer(root, { port: portArg ? Number(portArg) : 0 });
+        console.log(`pm-mcp ui 已启动（只读、仅绑定 127.0.0.1）：${url}  按 Ctrl+C 退出`);
+        const shutdown = () => { void close().finally(() => process.exit(0)); };
+        process.on("SIGINT", shutdown);
+        process.on("SIGTERM", shutdown);
+        await new Promise(() => { });
+    }
+    catch (error) {
+        console.error(`[pm-mcp ui] ERROR: ${error.message}`);
+        process.exitCode = 1;
+    }
+}
+else if (process.argv[2] === "probe") {
+    try {
+        const { PROBE_USAGE, parseProbeArgs, runProbe } = await import("./probe.js");
+        if (process.argv.includes("--help") || process.argv.includes("-h"))
+            console.log(PROBE_USAGE);
+        else {
+            const report = await runProbe(parseProbeArgs(process.argv.slice(3)));
+            console.log(JSON.stringify(report, null, 2));
+            process.exitCode = report.ok ? 0 : 1;
+        }
+    }
+    catch (error) {
+        console.error(`[pm-mcp probe] ERROR: ${error.message}`);
+        process.exitCode = 1;
+    }
+}
 else {
     await import("./index.js");
 }

package/dist/dashboard.js

@@ -4,7 +4,7 @@ import { atomicWrite, loadDebugLog, loadFeatures, loadProject, loadRoadmap, load
 import { decisionsDir, pmPath, dashboardFile } from "./paths.js";
 import { mermaidRoadmap, quotaWarnings, renderRoadmap, checkpointSuffix } from "./roadmap.js";
 import { churnStats, debtAging } from "./health.js";
-import { featureVerifyMark } from "./audit.js";
+import { detectDrift, featureVerifyMark } from "./audit.js";
 import { loadGovernance } from "./governance-model.js";
 import { touchRegistry } from "./registry.js";
 /** 生成 PROJECT.md 全文 */
@@ -100,17 +100,19 @@ export function buildDashboard(root) {
     const highFindings = openFindings.filter((f) => f.severity === "high");
     const churn = churnStats(sessions);
     const implemented = features.filter((f) => f.status === "implemented");
-    const drifted = implemented.filter((f) => f.entry_files.some((p) => !fs.existsSync(path.join(root, p))));
+    // 与 audit_structure 的「漂移对账」共用同一实现，避免两处口径不一致：
+    // detectDrift 覆盖 implemented 功能的 entry_files 与 done 任务的 files。
+    const drift = detectDrift(root);
     L.push(`| 账本 | 状态 |`);
     L.push(`|---|---|`);
-    L.push(`| 漂移（防幻觉） | ${drifted.length === 0 ? "✅ 无" : `⚠️ ${drifted.length} 个功能入口文件缺失`} |`);
+    L.push(`| 漂移（防幻觉） | ${drift.length === 0 ? "✅ 无" : `⚠️ ${drift.length} 项（功能入口文件或 done 任务关联文件缺失）`} |`);
     L.push(`| 债务（反挤出） | ${aging.openDebt === 0 ? "✅ 无未清债务" : `⚠️ ${aging.openDebt} 条，最老 ${aging.oldestDays} 天`} |`);
     L.push(`| churn（变更率） | ${churn.hotspots.length === 0 ? "✅ 无热点" : `⚠️ 热点 ${churn.hotspots.slice(0, 3).map((h) => `${h.file}(${h.count})`).join(", ")}`} |`);
     L.push(`| 安全 | ${openFindings.length === 0 ? "✅ 无未处理发现" : `⚠️ ${openFindings.length} 个未处理（高危 ${highFindings.length}）`} |`);
     L.push(`| 调试知识 | ${debugEntries.length} 条记录 |`);
     L.push(`| 测试背书 | ${implemented.length === 0 ? "—" : `${implemented.filter((f) => f.test_files.length > 0).length}/${implemented.length} 个功能带测试`} |`);
     L.push(`| 语义治理 | ${governance ? `${governance.modules.length} 模块 / ${governance.interfaces.length} 接口 / ${governance.repositories.length} 仓库` : "⚠️ 未初始化"} |`);
-    L.push(`| 质量矩阵 | ${latestQuality ? `${latestQuality.ok ? "✅" : "🚩"} ${latestQuality.run_at.slice(0, 16).replace("T", " ")}（${latestQuality.results.filter((item) => item.status === "passed").length}/${latestQuality.results.length}）` : "⚠️ 尚无真实执行记录"} |`);
+    L.push(`| 质量矩阵 | ${latestQuality ? `${latestQuality.ok ? "✅" : "🚩"} ${latestQuality.run_at.slice(0, 16).replace("T", " ")}（命令 ${latestQuality.results.filter((item) => item.status === "passed").length}/${latestQuality.results.length}；证据 ${latestQuality.evidence_level ?? "旧格式未标级"}）` : "⚠️ 尚无真实执行记录"} |`);
     L.push(`| 标准化验收 | ${latestAcceptance ? `${latestAcceptance.verdict === "accepted" ? "✅" : "🚩"} ${latestAcceptance.report_generated_at.slice(0, 16).replace("T", " ")}（需求 ${latestAcceptance.summary.requirements_passed}/${latestAcceptance.summary.requirements_total}，errors ${latestAcceptance.summary.errors}）` : "⚠️ 尚无正式评价报告"} |`);
     L.push("");
     /* 跨模块/语言治理（这里只读账本，不在每次写操作时重跑全仓语义图） */

package/dist/doctor.js

@@ -0,0 +1,148 @@
+import os from "node:os";
+import fs from "node:fs";
+import path from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { PACKAGE_SPEC, RUNTIME_CONTRACT, SERVER_NAME, TOOL_CATALOG_SIZE, VERSION } from "./version.js";
+import { canonicalProjectRoot, findCodexProjectEntry, isLocalLaunch, isLocalServerEntry, isPackageLaunch, readCodexConfig } from "./setup-project.js";
+import { localProjectLaunch, workbuddyConfigPath } from "./setup.js";
+export function parseDoctorArgs(argv) {
+    const options = { root: process.cwd() };
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index], value = argv[index + 1];
+        if (!["--root", "--entry", "--config", "--client"].includes(arg) || !value || value.startsWith("--"))
+            throw new Error(`doctor 参数无效: ${arg}`);
+        if (arg === "--root")
+            options.root = path.resolve(value);
+        if (arg === "--entry")
+            options.entry = path.resolve(value);
+        if (arg === "--config")
+            options.config = path.resolve(value);
+        if (arg === "--client") {
+            if (value !== "codex" && value !== "workbuddy")
+                throw new Error("doctor 支持 --client codex|workbuddy，其他客户端可用 --entry 验证本地入口。");
+            options.client = value;
+        }
+        index++;
+    }
+    if (options.entry && options.config)
+        throw new Error("--entry 与 --config 不能同时使用。");
+    return options;
+}
+/**
+ * 从 WorkBuddy 的 `mcp.json` 中取出 pm-mcp 条目。
+ *
+ * 只读取启动定义（command/args），不复制也不输出任何自定义 env / 凭据。
+ * 文件必须是**有界普通文件**：链接、目录、超 2MB 一律拒绝。
+ */
+function readWorkbuddyEntry(file) {
+    if (!fs.existsSync(file))
+        return undefined;
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 2 * 1024 * 1024)
+        throw new Error("WorkBuddy 配置必须为有界普通文件，禁止链接。");
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`WorkBuddy 配置不是合法 JSON：${error.message}`);
+    }
+    const servers = parsed?.mcpServers;
+    const entry = servers?.[SERVER_NAME];
+    if (!entry)
+        return undefined;
+    if (entry.disabled === true)
+        throw new Error("WorkBuddy 中 pm-mcp 条目被禁用，现有客户端不会启动它。");
+    if (typeof entry.command !== "string" || entry.command.length === 0)
+        throw new Error("WorkBuddy 中 pm-mcp 条目缺少可识别的 command。");
+    const args = entry.args === undefined ? [] : entry.args;
+    if (!Array.isArray(args) || !args.every((value) => typeof value === "string"))
+        throw new Error("WorkBuddy 中 pm-mcp 条目的 args 不是字符串数组。");
+    return { command: entry.command, args: args };
+}
+/** 短期本地读连接；不把探测新进程冒充已重新连接的客户端。 */
+export async function runDoctor(options) {
+    const root = path.resolve(options.root);
+    const report = {
+        ok: false, expected_version: VERSION, root, configuration: options.entry ? "explicit_entry" : (options.client ?? "codex"), issues: [],
+        existing_client: "not_observed", note: "这是新建的本地探测连接。现有客户端须重新连接，并在其中调用 get_status 核对运行版本；未读取或转发自定义凭据环境。",
+    };
+    let launch;
+    try {
+        if (options.entry)
+            launch = { command: process.execPath, args: [options.entry, "--root", root] };
+        else if (options.client === "workbuddy") {
+            const file = options.config ?? workbuddyConfigPath(process.env, os.homedir(), fs.existsSync);
+            const entry = readWorkbuddyEntry(file);
+            if (!entry)
+                throw new Error("未在 WorkBuddy 的 mcp.json 中找到 pm-mcp 条目。");
+            report.configured_server = SERVER_NAME;
+            if (!isLocalServerEntry(entry))
+                throw new Error("WorkBuddy 中的 pm-mcp 不是可识别的本地 pm-mcp 启动项；未执行未知启动命令。");
+            // 配置通常不钉根（由会话工作区决定）；探测需要明确目标根，故补上 --root。
+            launch = entry.args.includes("--root") ? entry : { command: entry.command, args: [...entry.args, "--root", root] };
+            report.configuration = "workbuddy_local_probe";
+        }
+        else {
+            if (!options.config && fs.existsSync(path.join(root, ".codex", "config.toml")))
+                throw new Error("存在项目级 Codex 配置，可能覆盖全局设置；请用 --config 明确核验的配置文件并检查实际客户端。");
+            const file = options.config ?? path.join(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), "config.toml");
+            const entry = findCodexProjectEntry(readCodexConfig(file), root);
+            if (!entry)
+                throw new Error("未找到已明确绑定此项目的 Codex pm-mcp 配置。");
+            report.configured_server = entry.name;
+            if (!entry.enabled)
+                throw new Error("该服务在配置中被禁用，现有客户端不会启动它。");
+            if (entry.toolFilters)
+                throw new Error(`存在工具过滤设置，请核对后再确认全部${TOOL_CATALOG_SIZE}工具可用。`);
+            if (isPackageLaunch(entry)) {
+                if (entry.args[1] !== PACKAGE_SPEC)
+                    throw new Error(`启动配置版本与本包 ${PACKAGE_SPEC} 不一致，请先预览并升级配置。`);
+                launch = localProjectLaunch(root);
+                report.configuration = "codex_package_matches_local_probe";
+            }
+            else
+                launch = entry;
+        }
+        if (!isLocalLaunch(launch))
+            throw new Error("探测入口不是可识别的本地 pm-mcp 包；不执行未知启动命令。");
+    }
+    catch (error) {
+        report.issues.push(error.message);
+        return report;
+    }
+    const client = new Client({ name: "pm-mcp-doctor", version: VERSION });
+    const transport = new StdioClientTransport({ command: launch.command, args: launch.args,
+        env: { PM_MCP_HOME: path.join(root, ".pm", ".runtime", "doctor-home") }, stderr: "pipe" });
+    const timer = setTimeout(() => { void client.close(); }, 20_000);
+    timer.unref();
+    try {
+        await client.connect(transport, { timeout: 10_000 });
+        transport.stderr?.on("data", () => undefined);
+        const info = client.getServerVersion();
+        const inventory = await client.listTools({}, { timeout: 10_000 });
+        const status = await client.callTool({ name: "get_status", arguments: {} }, undefined, { timeout: 10_000 });
+        const runtime = status.structuredContent?.runtime;
+        report.probe = { server: info?.name, version: info?.version, tools: inventory.tools.length, runtime };
+        if (info?.name !== SERVER_NAME || info.version !== VERSION)
+            report.issues.push("握手返回的服务名或运行版本不匹配。");
+        if (status.isError || typeof runtime?.root !== "string" || canonicalProjectRoot(runtime.root) !== canonicalProjectRoot(root))
+            report.issues.push("实际状态读取未确认目标项目根。");
+        if (runtime?.version !== VERSION || runtime?.contract !== RUNTIME_CONTRACT)
+            report.issues.push("实际运行契约不支持本轮升级，不能仅凭配置宣称生效。");
+        const list = inventory.tools.find((tool) => tool.name === "list_tasks");
+        const project = inventory.tools.find((tool) => tool.name === "update_project");
+        if (inventory.tools.length !== TOOL_CATALOG_SIZE || !list?.inputSchema.properties?.cursor || !project?.inputSchema.properties?.completion_evidence)
+            report.issues.push("工具目录或新参数契约不完整。");
+        report.ok = report.issues.length === 0;
+    }
+    catch (error) {
+        report.issues.push(`本地连接验证失败: ${error.message}`);
+    }
+    finally {
+        clearTimeout(timer);
+        await client.close();
+    }
+    return report;
+}