@luckychen1993/pm-mcp 0.3.0 → 0.5.0

package/README.md

@@ -33,7 +33,7 @@ node dist/cli.js doctor --root .
 
 ## 已有管理流程
 
-用户仍然直接说“继续这个任务”“保存进度”“完成后帮我验收”。49 个工具全部保留，由 AI 组合调用，无需用户记工具名。
+用户仍然直接说“继续这个任务”“保存进度”“完成后帮我验收”。53 个工具全部保留，由 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。目录范围匹配不等于代码覆盖率证明；第一方报告也不构成防篡改认证。
@@ -202,6 +202,17 @@ node dist/cli.js probe --expect-file 上一轮probe报告.json -- node 其他服
 - `--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 会话自动遵守：
@@ -235,7 +246,7 @@ snapshot_codebase + audit_structure 对账；audit_security 安全体检；audit
 
 也可以直接用内置 prompts：`start-session` / `end-session` / `onboard` / `architecture-review` / `acceptance-review`；其中 `onboard` 会引导客户端读取状态并生成新人/AI 入职简报。
 
-## 工具清单（49 个）
+## 工具清单（53 个）
 
 | 域 | 工具 | 说明 |
 |---|---|---|
@@ -248,13 +259,13 @@ snapshot_codebase + audit_structure 对账；audit_security 安全体检；audit
 | 调试 | `log_debug` | 调试知识账：症状/根因/修法/验证 |
 | 求证 | `search_code` / `search_knowledge` / `annotate_file` | 代码检索（file:line）、七类知识源检索（含模块/接口/仓库治理）、文件用途索引 |
 | 审计 | `snapshot_codebase` / `audit_structure` | 结构快照；完整性/增长/漂移/债务/churn/复杂度/索引/足迹/测试/Git 十节对账 |
-| 安全 | `audit_security` / `list_findings` / `resolve_finding` | 密钥+危险模式+新增/通配依赖提示；扫描命中原文不落盘，处置 note 拒绝内置密钥形态 |
+| 安全 | `audit_security` / `list_findings` / `resolve_finding` / `search_code_public` | 密钥+危险模式+新增/通配依赖提示；扫描命中原文不落盘，处置 note 拒绝内置密钥形态；公开代码反查（联网默认关，confirm 门控，字面命中≠侵权结论） |
 | 法律 | `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` / `replace_semantic_evidence_for_file` | 编译器/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/audit-tools.js

@@ -8,6 +8,9 @@ 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";
+import { renderPublicSearch, searchPublicCode } from "./public-search.js";
 export function registerAuditTools(server, root) {
     toolW(server, root, "snapshot_codebase", "给代码结构拍快照（文件数/行数/目录分布/测试数/skip 标记/依赖清单）。之后 audit_structure 会与上次快照 diff。建议每个会话或每个里程碑结束时拍一次。", {}, () => {
         requireInitialized(root);
@@ -19,6 +22,33 @@ 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));
+    });
+    toolR(server, root, "search_code_public", "公开代码反查（联网！默认关）：把一段本仓源码行作为精确短语发给 GitHub Code Search，列出包含相同代码的公开仓库；片段在参数里对用户全程可见，必须显式 confirm=true。", {
+        confirm: z.literal(true).describe("显式确认联网：本工具会把一段真实代码行发送到 GitHub"),
+        snippet: z.string().trim().min(8).max(400).optional().describe("要反查的单行代码片段（与 file 二选一）"),
+        file: z.string().trim().min(1).max(512).optional().describe("从该文件取一行作为片段（相对项目根；缺省取最长行）"),
+        line: z.number().int().min(1).optional().describe("指定取第几行（1-based）"),
+        max_results: z.number().int().min(1).max(30).optional().describe("列出的命中数上限，默认 10"),
+        timeout_ms: z.number().int().min(5000).max(120000).optional().describe("请求超时毫秒数，默认 30000"),
+    }, async (args) => {
+        requireInitialized(root);
+        const result = await searchPublicCode(root, { snippet: args.snippet, file: args.file, line: args.line, maxResults: args.max_results, timeoutMs: args.timeout_ms });
+        return renderPublicSearch(result, budgetLines(root));
+    });
     toolW(server, root, "audit_security", "安全体检（只扫描本地、不联网，结果写入安全台账）：密钥泄露 / 危险模式（eval、SQL 拼接、禁用证书校验等）/ 依赖风险。修复后重扫自动关闭；接受风险必须留理由。", {}, (_args, prepared) => {
         requireInitialized(root);
         const report = auditSecurity(root, prepared);

package/dist/cli.js

@@ -25,6 +25,28 @@ else if (process.argv[2] === "doctor") {
         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");

package/dist/duplicates.js

@@ -0,0 +1,228 @@
+import fs from "node:fs";
+import path from "node:path";
+import { foldLines } from "./budget.js";
+import { ensureFresh, getIndex } from "./index-store.js";
+/**
+ * 重复代码检测（零依赖、确定性）：行指纹滑动窗口聚类。
+ *
+ * 归一化规则：剥离注释（按语言族：// 与 # 、块注释 /* *\/）、字符串字面量内容替换为占位符、
+ * 空白折叠——因此注释/空白/字面量文本的差异不算差异，标识符与结构差异才算。
+ * 聚类：对每个哈希相同且出现在 ≥2 个文件的窗口做连续对齐合并（成对扩展成长块），
+ * 长度 ≥ minLines（有效代码行）的块按长度降序输出。仅跨文件重复计入 v1。
+ */
+export const DUPLICATE_SOURCE_EXTENSIONS = new Set([
+    ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts",
+    ".py", ".go", ".rs", ".java", ".kt", ".kts", ".cs", ".c", ".h", ".cpp", ".hpp",
+    ".php", ".rb", ".swift", ".scala", ".vue", ".svelte",
+]);
+const MAX_FILE_BYTES = 400 * 1024;
+const MAX_RUNS = 5000;
+const MAX_LOCATIONS_PER_HASH = 8;
+const SLASH_STYLE = { lineMarkers: ["//"], blockOpen: "/*", blockClose: "*/" };
+const HASH_STYLE = { lineMarkers: ["#"], blockOpen: null, blockClose: null };
+function styleFor(ext) {
+    return ext === ".py" || ext === ".rb" ? HASH_STYLE : SLASH_STYLE;
+}
+/** 单遍扫描：跨行维护块注释与字符串状态；字符串内容丢弃、留一个占位符。 */
+function normalizeLines(content, style) {
+    const out = [];
+    let inBlock = false;
+    let inString = null;
+    let buffer = "";
+    let lineNo = 1;
+    const flush = () => {
+        const norm = buffer.replace(/\s+/g, " ").trim();
+        if (norm.length > 0)
+            out.push({ norm, line: lineNo });
+        buffer = "";
+    };
+    for (let i = 0; i < content.length; i++) {
+        const ch = content[i];
+        if (ch === "\n") {
+            flush();
+            lineNo += 1;
+            continue;
+        }
+        if (inBlock) {
+            if (style.blockClose && content.startsWith(style.blockClose, i)) {
+                inBlock = false;
+                i += style.blockClose.length - 1;
+            }
+            continue;
+        }
+        if (inString) {
+            if (ch === "\\") {
+                i += 1;
+                continue;
+            }
+            if (ch === inString)
+                inString = null;
+            continue;
+        }
+        if (style.blockOpen && content.startsWith(style.blockOpen, i)) {
+            inBlock = true;
+            i += style.blockOpen.length - 1;
+            continue;
+        }
+        if (style.lineMarkers.some((marker) => content.startsWith(marker, i))) {
+            while (i < content.length && content[i] !== "\n")
+                i += 1;
+            i -= 1;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === "`") {
+            inString = ch;
+            buffer += "s";
+            continue;
+        }
+        buffer += ch;
+    }
+    flush();
+    return out;
+}
+/** 双 32 位 djb2 变体拼成 64-bit 指纹；跨平台确定性，够抵御行级指纹碰撞。 */
+function hashLines(joined) {
+    let h1 = 5381;
+    let h2 = 52711;
+    for (let i = 0; i < joined.length; i++) {
+        const code = joined.charCodeAt(i);
+        h1 = ((h1 * 33) ^ code) >>> 0;
+        h2 = (h2 * 31 + code) >>> 0;
+    }
+    return h1.toString(16).padStart(8, "0") + h2.toString(16).padStart(8, "0");
+}
+const clamp = (value, min, max, fallback) => {
+    const n = Math.trunc(value ?? fallback);
+    return Math.min(max, Math.max(min, Number.isFinite(n) ? n : fallback));
+};
+export function findDuplicateBlocks(root, options = {}) {
+    const started = Date.now();
+    const minLines = clamp(options.minLines, 4, 20, 6);
+    const limit = clamp(options.limit, 1, 100, 20);
+    ensureFresh(root);
+    const db = getIndex(root);
+    const rows = db.prepare("SELECT rel, size, oversize FROM files WHERE skip = 0").all();
+    let skippedOversize = rows.filter((row) => row.oversize !== 0).length;
+    const normalized = new Map();
+    let scannedFiles = 0;
+    for (const row of rows) {
+        const ext = path.extname(row.rel).toLowerCase();
+        if (!DUPLICATE_SOURCE_EXTENSIONS.has(ext))
+            continue;
+        if (row.oversize !== 0 || row.size > MAX_FILE_BYTES) {
+            skippedOversize += 1;
+            continue;
+        }
+        let content;
+        try {
+            content = fs.readFileSync(path.join(root, row.rel), "utf8");
+        }
+        catch {
+            continue;
+        }
+        normalized.set(row.rel, normalizeLines(content, styleFor(ext)));
+        scannedFiles += 1;
+    }
+    // 窗口指纹 → 位置（按文件名规范排序，保证成对遍历确定性）
+    const windows = new Map();
+    for (const [rel, lines] of normalized) {
+        if (lines.length < minLines)
+            continue;
+        for (let i = 0; i + minLines <= lines.length; i++) {
+            const slice = lines.slice(i, i + minLines);
+            const key = hashLines(slice.map((item) => item.norm).join("\n"));
+            const bucket = windows.get(key);
+            if (bucket)
+                bucket.push({ file: rel, index: i, line: slice[0].line });
+            else
+                windows.set(key, [{ file: rel, index: i, line: slice[0].line }]);
+        }
+    }
+    // 先按哈希收集全部成对匹配，再按索引排序做连续对齐合并——顺序处理才能拼出完整长块
+    const pairMatches = new Map();
+    let truncated = false;
+    for (const locations of windows.values()) {
+        if (locations.length < 2)
+            continue;
+        const sorted = [...locations].sort((x, y) => x.file.localeCompare(y.file) || x.index - y.index);
+        if (sorted.length > MAX_LOCATIONS_PER_HASH)
+            truncated = true;
+        const capped = sorted.slice(0, MAX_LOCATIONS_PER_HASH);
+        for (let i = 0; i < capped.length; i++) {
+            for (let j = i + 1; j < capped.length; j++) {
+                const p = capped[i], q = capped[j];
+                if (p.file === q.file)
+                    continue; // v1 只报跨文件重复
+                const pairKey = p.file < q.file ? `${p.file}\u0000${q.file}` : `${q.file}\u0000${p.file}`;
+                const forward = p.file < q.file;
+                const match = forward
+                    ? { a: p.file, b: q.file, indexA: p.index, indexB: q.index }
+                    : { a: q.file, b: p.file, indexA: q.index, indexB: p.index };
+                const list = pairMatches.get(pairKey);
+                if (list)
+                    list.push(match);
+                else
+                    pairMatches.set(pairKey, [match]);
+            }
+        }
+    }
+    const pairRuns = new Map();
+    const runs = [];
+    for (const [pairKey, matches] of pairMatches) {
+        matches.sort((x, y) => x.indexA - y.indexA || x.indexB - y.indexB);
+        for (const match of matches) {
+            const list = pairRuns.get(pairKey);
+            const previous = list?.[list.length - 1];
+            if (previous && previous.endA === match.indexA - 1 && previous.endB === match.indexB - 1) {
+                previous.endA = match.indexA;
+                previous.endB = match.indexB;
+                previous.len += 1;
+                continue;
+            }
+            if (runs.length >= MAX_RUNS) {
+                truncated = true;
+                break;
+            }
+            const run = { a: match.a, b: match.b, startA: match.indexA, startB: match.indexB, endA: match.indexA, endB: match.indexB, len: 1 };
+            if (list)
+                list.push(run);
+            else
+                pairRuns.set(pairKey, [run]);
+            runs.push(run);
+        }
+        if (truncated)
+            break;
+    }
+    const linesOf = (rel) => normalized.get(rel) ?? [];
+    const toRange = (file, startIndex, len) => {
+        const lines = linesOf(file);
+        const first = lines[startIndex]?.line ?? startIndex + 1;
+        const last = lines[Math.min(startIndex + len - 1, lines.length - 1)]?.line ?? first;
+        return { file, start: first, end: Math.max(first, last) };
+    };
+    const groups = runs
+        .sort((x, y) => y.len - x.len || x.a.localeCompare(y.a) || x.b.localeCompare(y.b) || x.startA - y.startA)
+        .slice(0, limit)
+        .map((run) => ({
+        lines: run.len + minLines - 1,
+        members: [toRange(run.a, run.startA, run.len + minLines - 1), toRange(run.b, run.startB, run.len + minLines - 1)],
+    }));
+    return { scannedFiles, skippedOversize, threshold: minLines, groups, truncated, durationMs: Date.now() - started };
+}
+export function renderDuplicates(root, options = {}, maxLines = 150) {
+    const scan = findDuplicateBlocks(root, options);
+    const lines = [
+        "## 重复代码",
+        `- 扫描: ${scan.scannedFiles} 个源文件（超限跳过 ${scan.skippedOversize}）· 阈值 ≥${scan.threshold} 有效代码行 · 跨文件 · 耗时 ${scan.durationMs}ms`,
+    ];
+    if (scan.groups.length === 0)
+        lines.push("- ✅ 未发现跨文件重复块");
+    else {
+        lines.push(`- 共列出 ${scan.groups.length} 组重复（按长度降序${scan.truncated ? "，已达运行上限截断" : ""}）：`);
+        scan.groups.forEach((group, index) => {
+            const members = group.members.map((m) => `${m.file}:${m.start}-${m.end}`).join(" ↔ ");
+            lines.push(`- 组${index + 1}（${group.lines} 行）${members}`);
+        });
+    }
+    return foldLines(lines, { maxLines, hint: "调高 min_lines 只看大块克隆；检测不改变任何台账状态" });
+}

package/dist/governance-audit.js

@@ -5,6 +5,7 @@ import { loadGovernance } from "./governance-model.js";
 import { assessQualityCoverage, createQualityPlan, discoverProjectUnits } from "./language-adapters.js";
 import { buildSemanticGraph, moduleForFile } from "./semantic-graph.js";
 import { loadAllSemanticEvidence } from "./semantic-evidence-store.js";
+import { relPath } from "./semantic-parsers.js";
 function languageIssues(governance, graph) {
     const issues = [];
     for (const module of governance.modules) {
@@ -64,6 +65,13 @@ function graphIssues(graph) {
     for (const cycle of graph.cycles) {
         issues.push({ severity: "error", code: "module-cycle", message: `模块依赖循环: ${cycle.join(" -> ")} -> ${cycle[0]}`, evidence: cycle });
     }
+    // 文件级循环通常是 barrel/重导出或真实的循环依赖；比模块环轻，作警告可见。
+    for (const cycle of graph.fileCycles.slice(0, 10)) {
+        issues.push({ severity: "warning", code: "file-cycle", message: `文件级依赖循环: ${cycle.join(" -> ")} -> ${cycle[0]}`, evidence: cycle });
+    }
+    if (graph.fileCycles.length > 10) {
+        issues.push({ severity: "warning", code: "file-cycle-truncated", message: `文件级依赖循环共 ${graph.fileCycles.length} 个，仅列出前 10 个`, evidence: [] });
+    }
     return issues;
 }
 function render(governance, graph, units, qualityCoverage, issues, maxLines) {
@@ -73,7 +81,7 @@ function render(governance, graph, units, qualityCoverage, issues, maxLines) {
         "## 跨文件/模块/语言治理审计",
         `${errors.length === 0 ? "✅" : "🚩"} modules=${governance.modules.length} · interfaces=${governance.interfaces.length} · repositories=${governance.repositories.length} · errors=${errors.length} · warnings=${warnings.length}`,
         `语义覆盖: source ${graph.coverage.sourceCoveragePct}%（${graph.coverage.parsedFiles}/${graph.coverage.sourceCandidateFiles}）· assurance ${graph.coverage.semanticAssurancePct}% · AST ${graph.coverage.astFiles} · runtime ${graph.coverage.runtimeFiles} · heuristic ${graph.coverage.heuristicFiles} · internal resolution ${graph.coverage.resolutionPct}% · unresolved ${graph.coverage.unresolvedInternal}`,
-        `关系: files ${graph.files.length} · file edges ${graph.fileEdges.length} · module edges ${graph.moduleEdges.length} · contracts ${graph.contracts.length} · cycles ${graph.cycles.length}`,
+        `关系: files ${graph.files.length} · file edges ${graph.fileEdges.length} · module edges ${graph.moduleEdges.length} · contracts ${graph.contracts.length} · cycles ${graph.cycles.length} · file cycles ${graph.fileCycles.length}`,
         `质量矩阵: units ${qualityCoverage.totalUnits} · covered ${qualityCoverage.unitsWithCommands} · coverage ${qualityCoverage.coveragePct}% · commands ${qualityCoverage.commandKinds.join(", ") || "无"}`,
         `manifest 依赖: ${units.reduce((sum, unit) => sum + unit.dependencies.length, 0)} · parse errors ${units.reduce((sum, unit) => sum + unit.dependencyErrors.length, 0)}`,
         `语言: ${[...new Set(units.flatMap((unit) => unit.languages))].sort().join(", ") || "未发现"}`,
@@ -124,3 +132,92 @@ export function auditGovernance(root, maxLines = 150) {
     const ok = !issues.some((issue) => issue.severity === "error");
     return { ok, governance, graph, units, qualityPlan, qualityCoverage, issues, report: render(governance, graph, units, qualityCoverage, issues, maxLines) };
 }
+const MAX_CYCLE_LIST = 10;
+const MAX_FOCUS_NODES = 80;
+/** 依赖图查询：全局摘要（关系/环/枢纽）+ 模块与文件级循环 + 聚焦文件邻域；输出折叠在行预算内。 */
+export function dependencyGraphReport(root, args = {}, maxLines = 150) {
+    const absolute = path.resolve(root);
+    const governance = loadGovernance(absolute);
+    const graph = buildSemanticGraph(absolute, governance, { semanticEvidence: loadAllSemanticEvidence(absolute) });
+    const lines = [
+        "## 依赖图",
+        `- 关系: files ${graph.files.length} · file edges ${graph.fileEdges.length} · module edges ${graph.moduleEdges.length} · unresolved ${graph.unresolved.length}`,
+        `- 环: module cycles ${graph.cycles.length} · file cycles ${graph.fileCycles.length}`,
+    ];
+    const fanOut = new Map();
+    const fanIn = new Map();
+    for (const edge of graph.fileEdges) {
+        if (edge.to === null || edge.resolution !== "file")
+            continue;
+        fanOut.set(edge.from, (fanOut.get(edge.from) ?? 0) + 1);
+        fanIn.set(edge.to, (fanIn.get(edge.to) ?? 0) + 1);
+    }
+    const hubs = (counts) => [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 5).map(([file, n]) => `${file}(${n})`).join(", ") || "无";
+    lines.push(`- 出边枢纽: ${hubs(fanOut)}`);
+    lines.push(`- 入边枢纽: ${hubs(fanIn)}`);
+    for (const cycle of graph.cycles.slice(0, 5))
+        lines.push(`- 🔴 模块循环: ${cycle.join(" -> ")} -> ${cycle[0]}`);
+    for (const cycle of graph.fileCycles.slice(0, MAX_CYCLE_LIST))
+        lines.push(`- ⚠️ 文件循环: ${cycle.join(" -> ")} -> ${cycle[0]}`);
+    if (args.focus) {
+        // focus 可传相对或绝对路径：先解析并转成项目内相对 posix 路径，再与语义图对表。
+        const focusRel = relPath(path.relative(absolute, path.resolve(absolute, args.focus)));
+        if (!graph.files.some((file) => file.path === focusRel)) {
+            lines.push(`- 🚩 聚焦文件不在语义图中（未解析或不在治理范围）: ${focusRel}`);
+            return foldLines(lines, { maxLines, hint: "先确认路径在模块 root 下且语言已登记" });
+        }
+        const forward = new Map();
+        const backward = new Map();
+        for (const edge of graph.fileEdges) {
+            if (edge.to === null || edge.resolution !== "file")
+                continue;
+            forward.set(edge.from, [...(forward.get(edge.from) ?? []), edge.to]);
+            backward.set(edge.to, [...(backward.get(edge.to) ?? []), edge.from]);
+        }
+        const depth = args.depth ?? 2;
+        const walk = (start, adjacency) => {
+            const seen = new Map([[start, 0]]);
+            let frontier = [start];
+            for (let level = 1; level <= depth; level += 1) {
+                const next = [];
+                for (const node of frontier)
+                    for (const neighbor of adjacency.get(node) ?? []) {
+                        if (!seen.has(neighbor)) {
+                            seen.set(neighbor, level);
+                            next.push(neighbor);
+                        }
+                    }
+                if (next.length === 0)
+                    break;
+                frontier = next.sort();
+            }
+            return seen;
+        };
+        lines.push(`### 聚焦 ${focusRel}（depth=${depth}）`);
+        const sides = [
+            { title: "依赖（出边）", adjacency: forward, enabled: args.direction !== "dependents" },
+            { title: "被依赖（入边）", adjacency: backward, enabled: args.direction !== "deps" },
+        ];
+        for (const side of sides) {
+            if (!side.enabled)
+                continue;
+            const seen = walk(focusRel, side.adjacency);
+            const levels = [...seen.entries()].filter(([file]) => file !== focusRel).sort((a, b) => a[1] - b[1] || a[0].localeCompare(b[0]));
+            if (levels.length === 0) {
+                lines.push(`- ${side.title}: 无`);
+                continue;
+            }
+            const byLevel = new Map();
+            for (const [file, level] of levels.slice(0, MAX_FOCUS_NODES))
+                byLevel.set(level, [...(byLevel.get(level) ?? []), file]);
+            for (const level of [...byLevel.keys()].sort((a, b) => a - b))
+                lines.push(`- ${side.title} L${level}: ${byLevel.get(level).join(", ")}`);
+            if (levels.length > MAX_FOCUS_NODES)
+                lines.push(`  …另有 ${levels.length - MAX_FOCUS_NODES} 个节点未展开（提高 depth 或改用 impact_analysis 反向闭包）`);
+        }
+        const focusUnresolved = graph.unresolved.filter((edge) => edge.from === focusRel).slice(0, 10).map((edge) => edge.specifier);
+        if (focusUnresolved.length > 0)
+            lines.push(`- 未解析引用: ${focusUnresolved.join(", ")}`);
+    }
+    return foldLines(lines, { maxLines, hint: "用 focus 参数聚焦单个文件，或提高 depth 扩大邻域" });
+}

package/dist/governance-tools.js

@@ -5,7 +5,7 @@ import { foldLines } from "./budget.js";
 import { refreshDerived } from "./dashboard.js";
 import { requireInitialized } from "./paths.js";
 import { initGovernance, loadGovernance, saveGovernance, } from "./governance-model.js";
-import { auditGovernance } from "./governance-audit.js";
+import { auditGovernance, dependencyGraphReport } from "./governance-audit.js";
 import { impactAnalysis } from "./semantic-graph.js";
 import { assessQualityCoverage, createQualityPlan, discoverProjectUnits, runQualityPlan } from "./language-adapters.js";
 import { buildPortfolioFromRegistry, buildPortfolioReport, loadPortfolioProject } from "./portfolio.js";
@@ -156,6 +156,14 @@ export function registerGovernanceTools(server, root) {
         requireInitialized(root);
         return auditGovernance(root, budgetLines(root)).report;
     });
+    toolR(server, root, "dependency_graph", "查询跨文件/模块依赖图：全局摘要（关系/环/入出边枢纽）、模块与文件级循环、聚焦文件的依赖邻域（BFS 方向与深度可调、未解析引用）。", {
+        focus: z.string().trim().min(1).max(512).optional().describe("聚焦文件（相对项目根路径）"),
+        direction: z.enum(["deps", "dependents", "both"]).optional().describe("邻域方向，默认 both"),
+        depth: z.number().int().min(1).max(6).optional().describe("邻域深度 1-6，默认 2"),
+    }, (args) => {
+        requireInitialized(root);
+        return dependencyGraphReport(root, args ?? {}, budgetLines(root));
+    });
     toolR(server, root, "list_semantic_evidence", "列出已登记的语言原生 AST、编译器或运行时语义证据；损坏文档会使整次读取失败。", {}, () => {
         requireInitialized(root);
         return JSON.stringify(listSemanticEvidence(root), null, 2);

package/dist/osv.js

@@ -0,0 +1,139 @@
+import fs from "node:fs";
+import path from "node:path";
+import { discoverProjectUnits } from "./language-adapters.js";
+import { foldLines } from "./budget.js";
+/**
+ * OSV.dev 已知漏洞查询（联网，显式确认后才会发起请求）。
+ *
+ * 依赖来源是本地 manifest 解析（discoverProjectUnits），只把「包名/版本/生态」
+ * 三个字段发给 api.osv.dev querybatch；不发送代码、路径或任何项目内容。
+ * 版本为范围声明（^ ~ >=）时按原样精确匹配，可能漏报——在报告中如实声明该边界。
+ */
+const OSV_ENDPOINT = "https://api.osv.dev/v1/querybatch";
+const BATCH_SIZE = 100;
+export function ecosystemFor(parser) {
+    if (parser === "package-json")
+        return "npm";
+    if (parser.startsWith("requirements") || parser.startsWith("pyproject"))
+        return "PyPI";
+    if (parser.startsWith("go-mod"))
+        return "Go";
+    if (parser.startsWith("cargo"))
+        return "crates.io";
+    if (parser.startsWith("maven") || parser.startsWith("gradle"))
+        return "Maven";
+    if (parser.startsWith("msbuild"))
+        return "NuGet";
+    return null;
+}
+/**
+ * npm 生态优先用 package-lock.json 的实装版本：manifest 里的 ^ ~ 范围串发给 OSV
+ * 会被解析到边界之下造成误报（实装版本已在修复线之上也会命中），实装版本才准确。
+ */
+function npmLockVersions(root) {
+    const versions = new Map();
+    try {
+        const lock = JSON.parse(fs.readFileSync(path.join(root, "package-lock.json"), "utf8"));
+        for (const [key, entry] of Object.entries(lock.packages ?? {})) {
+            if (!key.startsWith("node_modules/"))
+                continue;
+            const name = key.slice("node_modules/".length);
+            if (name.length === 0 || name.includes("node_modules/") || typeof entry.version !== "string")
+                continue;
+            if (!versions.has(name))
+                versions.set(name, entry.version);
+        }
+    }
+    catch { /* 无 lockfile 或不可读：退回 manifest 版本并在报告中声明 */ }
+    return versions;
+}
+export function collectOsvQueries(root) {
+    const npmVersions = npmLockVersions(root);
+    const merged = new Map();
+    let skippedUnknownEcosystem = 0;
+    for (const unit of discoverProjectUnits(root)) {
+        for (const dep of unit.dependencies) {
+            const ecosystem = ecosystemFor(dep.parser);
+            if (!ecosystem) {
+                skippedUnknownEcosystem += 1;
+                continue;
+            }
+            const resolved = ecosystem === "npm" ? npmVersions.get(dep.name) : undefined;
+            const version = resolved ?? dep.version;
+            const key = `${dep.name}@${version}@${ecosystem}`;
+            const existing = merged.get(key);
+            if (existing) {
+                if (!existing.sourceManifests.includes(dep.sourceManifest))
+                    existing.sourceManifests.push(dep.sourceManifest);
+            }
+            else
+                merged.set(key, { name: dep.name, version, ecosystem, sourceManifests: [dep.sourceManifest], versionSource: resolved ? "lockfile" : "manifest" });
+        }
+    }
+    return { queries: [...merged.values()].sort((a, b) => a.ecosystem.localeCompare(b.ecosystem) || a.name.localeCompare(b.name)), skippedUnknownEcosystem };
+}
+/** 分批查询 OSV；fetcher 可注入以便测试全程离线。 */
+export async function auditOsv(root, options = {}) {
+    const started = Date.now();
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const fetcher = options.fetcher ?? globalThis.fetch;
+    const { queries } = collectOsvQueries(root);
+    const capped = typeof options.maxPackages === "number" ? queries.slice(0, options.maxPackages) : queries;
+    const batches = Math.ceil(capped.length / BATCH_SIZE);
+    const vulnerablePackages = [];
+    let vulnCount = 0;
+    for (let batch = 0; batch < batches; batch += 1) {
+        const slice = capped.slice(batch * BATCH_SIZE, (batch + 1) * BATCH_SIZE);
+        const response = await fetcher(OSV_ENDPOINT, {
+            method: "POST",
+            headers: { "content-type": "application/json", "user-agent": "pm-mcp-osv (project ledger; reports only package name/version/ecosystem)" },
+            body: JSON.stringify({ queries: slice.map((q) => ({ package: { name: q.name, ecosystem: q.ecosystem }, version: q.version })) }),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok)
+            throw new Error(`OSV 查询失败：HTTP ${response.status}（第 ${batch + 1}/${batches} 批）`);
+        const payload = JSON.parse(await response.text());
+        const results = payload.results ?? [];
+        for (let i = 0; i < slice.length; i += 1) {
+            const vulns = (results[i]?.vulns ?? []).map((v) => ({
+                id: typeof v.id === "string" ? v.id : "UNKNOWN",
+                summary: typeof v.summary === "string" ? v.summary : typeof v.details === "string" ? v.details.slice(0, 160) : "",
+                aliases: Array.isArray(v.aliases) ? v.aliases.filter((a) => typeof a === "string") : [],
+            }));
+            if (vulns.length === 0)
+                continue;
+            vulnerablePackages.push({ ...slice[i], vulns });
+            vulnCount += vulns.length;
+        }
+    }
+    return {
+        queried: capped.length,
+        batches,
+        lockfileVersions: capped.filter((q) => q.versionSource === "lockfile").length,
+        manifestVersions: capped.filter((q) => q.versionSource === "manifest").length,
+        vulnerablePackages,
+        vulnCount,
+        durationMs: Date.now() - started,
+    };
+}
+export function renderOsv(scan, maxLines = 150, skippedUnknownEcosystem = 0) {
+    const lines = [
+        "## OSV 已知漏洞查询（联网完成）",
+        `- 查询: ${scan.queried} 个依赖（${scan.batches} 批，仅发送 包名/版本/生态）· 命中 ${scan.vulnerablePackages.length} 个包 / ${scan.vulnCount} 条漏洞 · 耗时 ${scan.durationMs}ms`,
+    ];
+    for (const finding of scan.vulnerablePackages) {
+        for (const vuln of finding.vulns) {
+            const aliases = vuln.aliases.length > 0 ? `（${vuln.aliases.slice(0, 3).join(", ")}）` : "";
+            lines.push(`- 🚩 ${finding.ecosystem}/${finding.name}@${finding.version} ${vuln.id}${aliases} ${vuln.summary.slice(0, 120)}`);
+        }
+    }
+    if (scan.vulnerablePackages.length === 0)
+        lines.push("- ✅ 未命中已知漏洞");
+    else
+        lines.push(`- ✅ 其余 ${scan.queried - scan.vulnerablePackages.length} 个依赖未命中已知漏洞`);
+    lines.push("> 边界：npm 依赖按 package-lock.json 实装版本查询（" + scan.lockfileVersions + " 个）" +
+        (scan.manifestVersions > 0 ? `；${scan.manifestVersions} 个非 npm 依赖按 manifest 声明版本（范围声明可能不准）` : "") +
+        "；devDependencies 一并计入；结果不写台账，联网由每次调用显式 confirm 门控。" +
+        (skippedUnknownEcosystem > 0 ? ` 未识别生态依赖 ${skippedUnknownEcosystem} 个已跳过。` : ""));
+    return foldLines(lines, { maxLines, hint: "修复后可再次 audit_osv 复核" });
+}

package/dist/public-search.js

@@ -0,0 +1,105 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { foldLines } from "./budget.js";
+/**
+ * 公开代码反查（GitHub Code Search，联网，显式确认后才会发起请求）。
+ *
+ * 与 audit_osv 的本质差异：OSV 只发包名/版本，本工具会把一段**真实代码行**发到
+ * GitHub——因此门控更强：confirm 必须显式为 true，且片段来自用户显式传入的
+ * snippet 参数或 file+line 选择（在客户端审批界面全程可见）。
+ * 仅做精确短语匹配：命中 ≠ 侵权结论，私有仓库不可见，配额 10 次/分钟。
+ */
+const GITHUB_SEARCH_ENDPOINT = "https://api.github.com/search/code";
+const MIN_SNIPPET = 8;
+const MAX_QUERY_CHARS = 200;
+/** 解析要外发的片段：显式 snippet 优先；否则 file（+可选 line，缺省取最长行）。 */
+export function resolveSnippet(root, args) {
+    if (args.snippet !== undefined && args.snippet !== "") {
+        const snippet = args.snippet.replace(/\s+/g, " ").trim();
+        if (snippet.length < MIN_SNIPPET)
+            throw new Error(`片段太短（≥${MIN_SNIPPET} 字符），太短会命中海量无关仓库。`);
+        if (args.file !== undefined)
+            throw new Error("snippet 与 file 二选一。");
+        return snippet;
+    }
+    if (args.file !== undefined) {
+        const absolute = path.resolve(root, args.file);
+        if (absolute !== root && !absolute.startsWith(root + path.sep))
+            throw new Error("file 必须位于项目根内。");
+        const raw = fs.readFileSync(absolute, "utf8");
+        const lines = raw.split(/\r?\n/);
+        const index = args.line === undefined
+            ? lines.reduce((best, line, i) => (line.trim().length > (lines[best]?.trim().length ?? 0) ? i : best), 0)
+            : args.line - 1;
+        const line = lines[index];
+        if (line === undefined)
+            throw new Error(`行号越界：${args.file} 共 ${lines.length} 行，第 ${args.line ?? 0} 行不存在。`);
+        const snippet = line.replace(/\s+/g, " ").trim();
+        if (snippet.length < MIN_SNIPPET)
+            throw new Error(`选中的行太短（≥${MIN_SNIPPET} 字符）：${snippet.slice(0, 40)}`);
+        return snippet.slice(0, MAX_QUERY_CHARS);
+    }
+    throw new Error("需要 snippet 或 file 之一：确认要外发到 GitHub 的代码片段。");
+}
+function resolveToken(explicit) {
+    if (explicit)
+        return explicit;
+    const fromEnv = process.env.GH_TOKEN ?? process.env.GITHUB_TOKEN;
+    if (fromEnv)
+        return fromEnv;
+    const gh = spawnSync("gh", ["auth", "token"], { encoding: "utf8", windowsHide: true });
+    const fromGh = gh.status === 0 ? gh.stdout.trim() : "";
+    if (fromGh)
+        return fromGh;
+    throw new Error("未找到 GitHub 凭据：设置 GH_TOKEN/GITHUB_TOKEN，或先 gh auth login。");
+}
+export async function searchPublicCode(root, args = {}) {
+    const started = Date.now();
+    const snippet = resolveSnippet(root, args);
+    const token = args.tokenResolver ? args.tokenResolver() : resolveToken(args.token);
+    const fetcher = args.fetcher ?? globalThis.fetch;
+    const maxResults = Math.min(30, Math.max(1, Math.trunc(args.maxResults ?? 10)));
+    // GitHub REST code search 是词项检索（不支持带引号短语）：按空白拆词、去掉引号后以 AND 语义提交。
+    const query = snippet.replace(/"/g, " ").split(/\s+/).filter(Boolean).join(" ");
+    const response = await fetcher(`${GITHUB_SEARCH_ENDPOINT}?q=${encodeURIComponent(query)}&per_page=${maxResults}`, {
+        method: "GET",
+        headers: {
+            authorization: `Bearer ${token}`,
+            accept: "application/vnd.github+json",
+            "user-agent": "pm-mcp-public-search (single-line provenance lookup)",
+            "x-github-api-version": "2022-11-28",
+        },
+        signal: AbortSignal.timeout(args.timeoutMs ?? 30_000),
+    });
+    if (response.status === 401)
+        throw new Error("GitHub token 无效（401）。");
+    if (response.status === 403)
+        throw new Error("GitHub 拒绝（403）：可能触发了 code search 限流（10 次/分钟）或 token 权限不足。");
+    if (response.status === 422)
+        throw new Error("GitHub 拒绝查询（422）：短语可能不合法，换一段更普通的行试试。");
+    if (!response.ok)
+        throw new Error(`GitHub Code Search 失败：HTTP ${response.status}`);
+    const payload = JSON.parse(await response.text());
+    const items = Array.isArray(payload.items) ? payload.items : [];
+    const hits = items.slice(0, maxResults).map((item) => ({
+        repo: typeof item.repository?.full_name === "string" ? item.repository.full_name : "unknown",
+        path: typeof item.path === "string" ? item.path : "",
+        url: typeof item.html_url === "string" ? item.html_url : "",
+    }));
+    const totalCount = typeof payload.total_count === "number" ? payload.total_count : hits.length;
+    return { snippet: snippet.slice(0, MAX_QUERY_CHARS), totalCount, hits, truncated: totalCount > hits.length, durationMs: Date.now() - started };
+}
+export function renderPublicSearch(result, maxLines = 150) {
+    const lines = [
+        "## 公开代码反查（GitHub Code Search，联网完成）",
+        `- 外发片段（已确认）: "${result.snippet}"`,
+        `- 命中: ${result.totalCount} 处（列出前 ${result.hits.length}${result.truncated ? "，已截断" : ""}）· 耗时 ${result.durationMs}ms`,
+    ];
+    for (const hit of result.hits)
+        lines.push(`- 命中 ${hit.repo} · ${hit.path}${hit.url ? ` · ${hit.url}` : ""}`);
+    if (result.hits.length === 0)
+        lines.push("- ✅ 公开索引中未发现相同代码行");
+    lines.push("> 命中是字面相同，不是侵权结论：可能是同一开源出处、常见写法或独立实现。私有仓库不可见；配额 10 次/分钟。");
+    return foldLines(lines, { maxLines, hint: "换更长或更独特的行可提高区分度" });
+}

package/dist/semantic-graph.js

@@ -363,6 +363,8 @@ export function buildSemanticGraph(root, governance, options = {}) {
             limitations: [...analysisLimitations],
         },
         files, fileEdges, moduleEdges, exports: exportedSymbols, contracts, unresolved, cycles: findModuleCycles(moduleEdges), violations,
+        // Tarjan 对 {from,to} 边同构，文件内边与模块边共用同一实现。
+        fileCycles: findModuleCycles(fileEdges.flatMap((edge) => (edge.to !== null && edge.resolution === "file" ? [{ from: edge.from, to: edge.to }] : []))),
         coverage: {
             totalFiles: files.length,
             sourceCandidateFiles,

package/dist/ui.js

@@ -0,0 +1,191 @@
+import http from "node:http";
+import path from "node:path";
+import fs from "node:fs";
+import { isInitialized } from "./paths.js";
+import { loadProject, loadTasks, loadRoadmap, loadFeatures, loadSessions, loadSecurity } from "./store.js";
+import { milestoneStats } from "./roadmap.js";
+import { aggregates, ensureFresh, getIndex } from "./index-store.js";
+import { VERSION } from "./version.js";
+/**
+ * 本地只读 Web 仪表盘（零依赖 node:http）：
+ *   pm-mcp ui [--root <项目>] [--port <端口>]
+ *
+ * 安全边界：仅绑定 127.0.0.1、纯 GET 只读、未初始化 fail-closed、无外部资源、
+ * 所有插值经 HTML 转义（任务标题等用户内容不可注入）；响应 CSP 禁止脚本。
+ */
+const esc = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+function latestQualityRun(root) {
+    const dir = path.join(root, ".pm", "quality-runs");
+    try {
+        const latest = fs.readdirSync(dir).filter((name) => name.endsWith(".json")).sort().pop();
+        if (!latest)
+            return null;
+        const raw = JSON.parse(fs.readFileSync(path.join(dir, latest), "utf8"));
+        const summary = raw.results?.[0]?.output_summary;
+        return { at: raw.run_at ?? "", ok: raw.ok === true, tests: summary ? `${summary.passed}/${summary.tests}` : "n/a" };
+    }
+    catch {
+        return null;
+    }
+}
+export function buildDashboardState(root) {
+    const absolute = path.resolve(root);
+    const project = loadProject(absolute);
+    const { tasks } = loadTasks(absolute);
+    const { milestones } = loadRoadmap(absolute);
+    const features = loadFeatures(absolute).features;
+    const security = loadSecurity(absolute).findings;
+    const sessions = loadSessions(absolute).sessions;
+    const byStatus = {};
+    for (const task of tasks)
+        byStatus[task.status] = (byStatus[task.status] ?? 0) + 1;
+    const recent = [...tasks]
+        .sort((a, b) => b.id.localeCompare(a.id))
+        .slice(0, 10)
+        .map((task) => ({ id: task.id, title: task.title, status: task.status, priority: task.priority ?? "" }));
+    let index = null;
+    try {
+        ensureFresh(absolute);
+        const agg = aggregates(getIndex(absolute));
+        index = { files: agg.totalFiles, loc: agg.totalLoc };
+    }
+    catch {
+        index = null;
+    }
+    const last = sessions.length > 0 ? sessions[sessions.length - 1] : null;
+    return {
+        name: project.name,
+        description: project.description,
+        phase: project.phase,
+        exposure: project.exposure,
+        version: VERSION,
+        milestones: milestones.map((milestone) => {
+            const stats = milestoneStats(tasks, milestone.id);
+            return { id: milestone.id, title: milestone.title, status: milestone.status, done: stats.done, total: stats.total, pct: stats.total === 0 ? 0 : stats.pct };
+        }),
+        tasks: { total: tasks.length, byStatus, recent },
+        features: {
+            total: features.length,
+            implemented: features.filter((f) => f.status === "implemented").length,
+            planned: features.filter((f) => f.status === "planned").length,
+            deprecated: features.filter((f) => f.status === "deprecated").length,
+        },
+        security: {
+            open: security.filter((f) => f.status === "open").length,
+            high: security.filter((f) => f.status === "open" && f.severity === "high").length,
+            accepted: security.filter((f) => f.status === "accepted").length,
+        },
+        sessions: {
+            count: sessions.length,
+            last: last ? { at: last.date, author: last.author, summary: last.summary } : null,
+        },
+        index,
+        quality: latestQualityRun(absolute),
+    };
+}
+export function renderDashboardHtml(state) {
+    const taskStatus = Object.entries(state.tasks.byStatus).map(([status, count]) => `${esc(status)} ${count}`).join(" · ") || "无";
+    const milestoneRows = state.milestones.map((m) => {
+        const statusIcon = m.status === "done" ? "✅" : m.status === "active" ? "▶" : "☐";
+        return `<tr><td>${esc(m.id)}</td><td>${statusIcon} ${esc(m.title)}</td><td>${m.done}/${m.total}</td>` +
+            `<td><div class="bar"><div class="fill" style="width:${Math.min(100, Math.max(0, m.pct))}%"></div></div>${m.pct}%</td></tr>`;
+    }).join("");
+    const taskRows = state.tasks.recent.map((task) => `<tr><td>${esc(task.id)}</td><td>${esc(task.title)}</td><td>${esc(task.status)}</td><td>${esc(task.priority)}</td></tr>`).join("");
+    const lastSession = state.sessions.last
+        ? `<p>最近：${esc(state.sessions.last.at)} · ${esc(state.sessions.last.author)} — ${esc(state.sessions.last.summary.slice(0, 160))}</p>`
+        : "<p>（无会话记录）</p>";
+    const quality = state.quality
+        ? `<span class="${state.quality.ok ? "ok" : "bad"}">${state.quality.ok ? "✅" : "🚩"} ${esc(state.quality.tests)}</span> @ ${esc(state.quality.at)}`
+        : "（暂无质量报告）";
+    return `<!doctype html>
+<html lang="zh-CN"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${esc(state.name)} · pm-mcp</title>
+<style>
+body{font-family:system-ui,"Segoe UI",sans-serif;margin:0;background:#f6f7f9;color:#1c2733}
+main{max-width:960px;margin:0 auto;padding:24px}
+h1{font-size:22px}h2{font-size:16px;margin:28px 0 8px;border-bottom:1px solid #dde3ea;padding-bottom:6px}
+.grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(150px,1fr));gap:12px}
+.card{background:#fff;border:1px solid #dde3ea;border-radius:8px;padding:12px}
+.card b{display:block;font-size:20px}.card span{color:#5b6b7c;font-size:12px}
+table{width:100%;border-collapse:collapse;background:#fff;border:1px solid #dde3ea}
+td,th{padding:6px 10px;border-bottom:1px solid #eef1f4;text-align:left;font-size:13px}
+.bar{background:#e8edf2;border-radius:6px;height:10px;min-width:80px;display:inline-block;vertical-align:middle;margin-right:6px}
+.fill{background:#3d7bd9;height:10px;border-radius:6px}
+.ok{color:#1a7f37}.bad{color:#c62828}
+footer{color:#8a97a5;font-size:12px;margin-top:24px}
+</style></head><body><main>
+<h1>${esc(state.name)} <small style="font-size:13px;color:#5b6b7c">pm-mcp v${esc(state.version)}</small></h1>
+<p>${esc(state.description || "（无描述）")} · 阶段：${esc(state.phase || "未设置")} · 暴露面：${esc(state.exposure)}</p>
+<h2>概览</h2>
+<div class="grid">
+<div class="card"><b>${state.tasks.total}</b><span>任务</span></div>
+<div class="card"><b>${state.features.implemented}</b><span>功能已实现 / 共 ${state.features.total}</span></div>
+<div class="card"><b class="${state.security.high > 0 ? "bad" : "ok"}">${state.security.open}</b><span>安全未处理（高危 ${state.security.high}）</span></div>
+<div class="card"><b>${state.sessions.count}</b><span>会话记录</span></div>
+<div class="card"><b>${state.index ? state.index.files : "—"}</b><span>索引文件${state.index ? ` / ${state.index.loc} 行` : ""}</span></div>
+<div class="card"><b>${quality}</b><span>最近质量门禁</span></div>
+</div>
+<h2>里程碑</h2>
+${milestoneRows ? `<table><tr><th>ID</th><th>标题</th><th>任务</th><th>进度</th></tr>${milestoneRows}</table>` : "<p>（无里程碑）</p>"}
+<h2>最近任务</h2>
+${taskRows ? `<table><tr><th>ID</th><th>标题</th><th>状态</th><th>优先级</th></tr>${taskRows}</table><p style="font-size:12px;color:#5b6b7c">状态分布：${esc(taskStatus)}</p>` : "<p>（无任务）</p>"}
+<h2>会话</h2>
+${lastSession}
+<footer>只读视图 · 仅绑定 127.0.0.1 · 数据来自 ${esc(state.name)} 的 .pm/ 台账 · ${new Date().toISOString()}</footer>
+</main></body></html>`;
+}
+const HEAD_405 = { allow: "GET, HEAD" };
+export async function startUiServer(root, options = {}) {
+    const absolute = path.resolve(root);
+    if (!isInitialized(absolute))
+        throw new Error(`目标不是已纳管项目（缺 .pm/）：${absolute}`);
+    const server = http.createServer((request, response) => {
+        response.setHeader("content-security-policy", "default-src 'none'; style-src 'unsafe-inline'");
+        response.setHeader("x-content-type-options", "nosniff");
+        response.setHeader("cache-control", "no-store");
+        try {
+            const url = new URL(request.url ?? "/", "http://127.0.0.1");
+            if (request.method !== "GET" && request.method !== "HEAD") {
+                response.writeHead(405, HEAD_405);
+                response.end("只读服务");
+                return;
+            }
+            if (url.pathname === "/healthz") {
+                response.writeHead(200, { "content-type": "text/plain" });
+                response.end("ok");
+                return;
+            }
+            if (url.pathname === "/api/state") {
+                response.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+                response.end(JSON.stringify(buildDashboardState(absolute)));
+                return;
+            }
+            if (url.pathname === "/") {
+                response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+                response.end(renderDashboardHtml(buildDashboardState(absolute)));
+                return;
+            }
+            response.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+            response.end("404");
+        }
+        catch (error) {
+            // fail-closed：不泄漏堆栈，只给一条简短原因
+            response.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+            response.end(`500: ${error.message.slice(0, 200)}`);
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port ?? 0, "127.0.0.1", resolve);
+    });
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+        server.close();
+        throw new Error("UI 服务监听失败。");
+    }
+    return {
+        url: `http://127.0.0.1:${address.port}/`,
+        close: () => new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve()))),
+    };
+}

package/dist/version.js

@@ -7,4 +7,4 @@ export const PACKAGE_SPEC = `${metadata.name}@${VERSION}`;
 export const RUNTIME_CONTRACT = "pagination-evidence-v1";
 // 服务器工具目录契约（doctor 与独立巡检 health-check 都以此核对）。
 // 新增/移除 MCP 工具时必须同步更新这里，并用 `pm-mcp probe` 实测复核。
-export const TOOL_CATALOG_SIZE = 49;
+export const TOOL_CATALOG_SIZE = 53;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckychen1993/pm-mcp",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "AI 编码项目的单一事实来源 + 健康台账 MCP 服务（事实来源 / 路线图 / 防幻觉 / 七本账 / 断点续做 / token 经济）",
   "keywords": [
     "mcp",
@@ -33,7 +33,10 @@
     "node": ">=22.18.0"
   },
   "pm_mcp": {
-    "acceptance_baseline": { "id": "pm-mcp-local-release", "version": "1.1.0" }
+    "acceptance_baseline": {
+      "id": "pm-mcp-local-release",
+      "version": "1.1.0"
+    }
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",