@luckychen1993/pm-mcp 0.1.5 → 0.3.0

package/dist/task-tools.js

@@ -1,10 +1,14 @@
 import { z } from "zod";
 import { refreshDerived } from "./dashboard.js";
-import { foldLines, normSep } from "./budget.js";
+import { normSep } from "./budget.js";
 import { requireInitialized } from "./paths.js";
 import { loadRoadmap, loadTasks, nextId, saveTasks } from "./store.js";
 import { now } from "./types.js";
 import { budgetLines, toolR, toolW } from "./tool-base.js";
+import { captureFileHashes } from "./git-state.js";
+import { appendSession } from "./session-log.js";
+import { verifiedTaskEvidence } from "./task-evidence.js";
+import { taskPage, taskPageText, TaskPageSchema } from "./task-pagination.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,43 +59,19 @@ export function registerTaskTools(server, root) {
             : "";
         return `✅ 任务 ${id}「${args.title}」已创建（${args.type ?? "feature"}/${args.milestone ?? "无里程碑"}）。${tip}`;
     });
-    toolR(server, root, "list_tasks", "列出任务（默认不含 done/cancelled）。可按状态/类型/里程碑/标签过滤。", {
+    toolR(server, root, "list_tasks", "分页列出任务（默认不含 done/cancelled，每页25）。按原过滤条件传 next_cursor 可取下一页；数据变化会使游标失效。文字摘要与结构化分页结果同时返回，不漏掉折叠的中间任务。", {
         status: z.enum(["backlog", "todo", "in_progress", "blocked", "done", "cancelled"]).optional(),
         type: z.enum(["feature", "refactor", "fix", "chore", "debt"]).optional(),
         milestone: z.string().optional(),
         tag: z.string().optional(),
         include_done: z.boolean().optional().describe("默认 false"),
+        page_size: z.number().int().min(1).max(100).optional().describe("默认25，受项目输出预算限制"),
+        cursor: z.string().min(1).max(1024).optional().describe("上页返回的 next_cursor；保留相同过滤条件"),
     }, (args) => {
         requireInitialized(root);
-        const { tasks } = loadTasks(root);
-        let list = tasks;
-        if (args.status)
-            list = list.filter((t) => t.status === args.status);
-        else if (!args.include_done)
-            list = list.filter((t) => t.status !== "done" && t.status !== "cancelled");
-        if (args.type)
-            list = list.filter((t) => t.type === args.type);
-        if (args.milestone)
-            list = list.filter((t) => t.milestone === args.milestone);
-        if (args.tag)
-            list = list.filter((t) => t.tags.includes(args.tag));
-        const L = list.map((t) => {
-            const mark = t.status === "in_progress" ? "🔄" : t.status === "blocked" ? "🚫" : t.status === "done" ? "✅" : "☐";
-            const extra = [];
-            if (t.priority)
-                extra.push(t.priority);
-            if (t.type !== "feature")
-                extra.push(t.type);
-            if (t.checkpoint)
-                extra.push(`下一步: ${t.checkpoint.next_step}`);
-            return `${mark} ${t.id} ${t.title}${extra.length ? `（${extra.join(", ")}）` : ""}`;
-        });
-        return foldLines([`共 ${list.length} 个任务（全部 ${tasks.length} 个）:`, ...L], {
-            maxLines: budgetLines(root),
-            hint: "用 status/type/milestone 过滤",
-        });
-    });
-    toolW(server, root, "update_task", "更新任务。转 done 必须填 result_note；feature/fix 建议填 verification（用什么命令/测试证明）。step_done 勾选第 N 步（从 1 起）。steps 整体替换步骤清单。", {
+        return JSON.stringify(taskPage(root, args, budgetLines(root) - 4));
+    }, { outputSchema: TaskPageSchema.shape, decode: (value) => { const page = TaskPageSchema.parse(JSON.parse(value)); return { text: taskPageText(page), data: page }; } });
+    toolW(server, root, "update_task", "一次更新任务、checkpoint 与会话。checkpoint 默认记会话；完成时用 record_session:true 一并记录，不再另调 log_session；files 给实际关联文件。feature/fix 转 done 必须有最新成功且源码匹配的测试报告，verification_run 可指明报告。文字 verification 不能代替执行证据。", {
         id: z.string(),
         status: z.enum(["backlog", "todo", "in_progress", "blocked", "done", "cancelled"]).optional(),
         title: z.string().optional(),
@@ -103,20 +83,27 @@ export function registerTaskTools(server, root) {
         acceptance: z.string().optional(),
         result_note: z.string().optional().describe("完成笔记（转 done 必填）"),
         verification: z.string().optional().describe("怎么验证的：命令/测试名"),
+        verification_run: z.string().min(1).optional().describe(".pm/quality-runs 内最新的质量报告；省略时自动选最新"),
+        checkpoint: z.object({ note: z.string().trim().min(1), next_step: z.string().trim().min(1) }).optional(),
+        record_session: z.boolean().optional().describe("checkpoint 默认 true；完成任务时设 true 合并会话。省略保留旧式单独记录方式"),
         steps: z.array(stepSchema).optional().describe("整体替换步骤清单"),
         step_done: z.number().int().min(1).optional().describe("勾选完成第 N 步"),
         author: z.string().optional(),
-    }, (args) => {
+    }, (args, prepared) => {
         requireInitialized(root);
         const data = loadTasks(root);
         const t = data.tasks.find((x) => x.id === args.id);
         if (!t)
             throw new Error(`找不到任务 ${args.id}。`);
+        if (JSON.stringify(t) !== prepared.taskSnapshot)
+            throw new Error("任务在证据校验期间发生变化，请重新读取状态。");
         const tnow = now();
         if (args.title !== undefined)
             t.title = args.title;
         if (args.detail !== undefined)
             t.detail = args.detail;
+        if (args.type !== undefined)
+            t.type = args.type; // schema 接受 type 但 handler 此前未应用（schema-handler 失配 bug）
         if (args.priority !== undefined)
             t.priority = args.priority ?? null;
         if (args.milestone !== undefined) {
@@ -138,6 +125,8 @@ export function registerTaskTools(server, root) {
             t.result_note = args.result_note;
         if (args.verification !== undefined)
             t.verification = args.verification;
+        if (prepared.evidence)
+            t.verification = prepared.evidence + (args.verification ? `\n验证说明: ${args.verification}` : "");
         if (args.author !== undefined)
             t.author = args.author;
         if (args.steps !== undefined)
@@ -149,6 +138,13 @@ export function registerTaskTools(server, root) {
             s.done = true;
         }
         const notes = [];
+        if (args.checkpoint) {
+            t.checkpoint = { ...args.checkpoint, at: tnow };
+            if (args.status === undefined && (t.status === "backlog" || t.status === "todo")) {
+                t.status = "in_progress";
+                t.started_at ??= tnow;
+            }
+        }
         if (args.status !== undefined && args.status !== t.status) {
             if (args.status === "done") {
                 const note = args.result_note !== undefined ? args.result_note : t.result_note;
@@ -159,11 +155,6 @@ export function registerTaskTools(server, root) {
                     throw new Error(`result_note 过于空洞（「${note.trim()}」）：完成笔记至少要说明做了什么（4 字以上），别拿一个字糊弄账本。`);
                 }
                 t.completed_at = tnow;
-                if (!t.verification.trim() && (args.verification === undefined || !args.verification.trim())) {
-                    if (t.type === "feature" || t.type === "fix") {
-                        notes.push("💡 提示: 该任务是 " + t.type + " 类型但没填 verification——用什么命令/测试证明它真的好了？建议补上（update_task id=" + t.id + " verification=...）。");
-                    }
-                }
             }
             if (t.status === "done" && args.status !== "done")
                 t.completed_at = null;
@@ -173,9 +164,28 @@ export function registerTaskTools(server, root) {
         }
         t.updated = tnow;
         saveTasks(root, data);
+        if (args.record_session ?? (args.checkpoint !== undefined)) {
+            const session = appendSession(root, {
+                summary: `${t.id} ${t.title}：${args.status === "done" ? t.result_note : args.checkpoint?.note ?? `状态 ${t.status}`}`,
+                files: args.files ?? [], next_steps: args.checkpoint ? [args.checkpoint.next_step] : [], author: args.author,
+            }, prepared.hashes);
+            notes.push(`会话 ${session} 已自动记录，无需重复 log_session。`);
+        }
         refreshDerived(root);
         const stepsInfo = t.steps.length > 0 ? `，步骤 ${t.steps.filter((s) => s.done).length}/${t.steps.length}` : "";
         return [`✅ ${t.id} 已更新（${t.status}${stepsInfo}）。`, ...notes].join("\n");
+    }, (args) => {
+        requireInitialized(root);
+        const task = loadTasks(root).tasks.find((item) => item.id === args.id);
+        if (!task)
+            throw new Error(`找不到任务 ${args.id}。`);
+        if (args.status === "done" && (args.result_note ?? task.result_note).trim().length < 4) {
+            throw new Error("转 done 必须填写 result_note（至少4字，不能过于空洞）。");
+        }
+        const evidence = args.status === "done" && (task.type === "feature" || task.type === "fix")
+            ? verifiedTaskEvidence(root, args.verification_run, args.files ?? task.files) : undefined;
+        const record = args.record_session ?? (args.checkpoint !== undefined);
+        return { evidence, taskSnapshot: JSON.stringify(task), hashes: record ? captureFileHashes(root, args.files ?? []) : {} };
     });
     toolW(server, root, "checkpoint", "断点存档：长任务做到一半（或上下文快满）时随手保存「当前进度 + 下一步动作」。新会话 get_status 会直接给出恢复点，不用靠回忆。", {
         task_id: z.string(),

package/dist/tool-base.js

@@ -25,19 +25,21 @@ export function recordUsage(root, tool, kind, started, outcome) {
     }
 }
 /** 只读工具：跨 Agent/进程合并完全相同的并行请求，短窗复用结果。 */
-export function toolR(server, root, name, description, schema, fn) {
-    server.registerTool(name, { description, inputSchema: schema, annotations: { readOnlyHint: true } }, (async (args) => {
+export function toolR(server, root, name, description, schema, fn, presentation) {
+    server.registerTool(name, { description, inputSchema: schema, ...(presentation ? { outputSchema: presentation.outputSchema } : {}), annotations: { readOnlyHint: true } }, (async (args) => {
         const started = Date.now();
         try {
-            const result = await runCoalescedRead(root, name, args, fn);
+            const result = await runCoalescedRead(root, presentation ? `${name}:${presentation.cacheVersion ?? "structured-v1"}` : name, args, fn);
+            const decoded = presentation?.decode(result.text);
+            const text = decoded?.text ?? result.text;
             recordUsage(root, name, "read", started, {
                 ok: !result.pending,
-                text: result.text,
+                text: decoded ? text + JSON.stringify(decoded.data) : text,
                 replayed: result.replayed,
                 pending: result.pending,
                 uncertain: result.uncertain,
             });
-            return { content: [{ type: "text", text: result.text }] };
+            return { content: [{ type: "text", text }], ...(decoded ? { structuredContent: decoded.data } : {}) };
         }
         catch (error) {
             const message = error.message;

package/dist/types.js

@@ -1,5 +1,7 @@
 import { z } from "zod";
 import { normSep } from "./budget.js";
+import { ScanIgnoreSchema } from "./scan-policy.js";
+import { CompletionEvidenceSchema } from "./quality-evidence.js";
 export const now = () => new Date().toISOString();
 /** 文件清单字段：统一 / 分隔（Windows 反斜杠入库即规范化），缺省空数组 */
 const filesField = () => z.array(z.string()).default([]).transform((list) => list.map(normSep));
@@ -24,6 +26,8 @@ export const ProjectSchema = z.object({
     phase: z.string().default(""),
     /** 登记的模块名（用于复杂度账的"未登记目录"检测） */
     modules: z.array(z.string()).default([]),
+    scan_ignore: ScanIgnoreSchema.optional(),
+    completion_evidence: CompletionEvidenceSchema.optional(),
     /** 暴露面：local=本机工具 / network=内网服务 / public=公网服务，影响安全告警力度 */
     exposure: ExposureSchema.default("local"),
     /** 项目许可证（SPDX 或名称），用于依赖兼容性对账 */
@@ -118,6 +122,7 @@ export const SessionSchema = z.object({
     author: z.string().default(""),
     summary: z.string().trim().min(1),
     files: filesField(),
+    file_hashes: z.record(z.string().regex(/^[a-f0-9]{64}$/)).optional(),
     next_steps: z.array(z.string()).default([]),
 });
 export const SessionsFileSchema = z.object({

package/dist/version.js

@@ -0,0 +1,10 @@
+import fs from "node:fs";
+// src/ 与发布后的 dist/ 共用包根，避免服务端与安装器各自硬编码版本。
+const metadata = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+export const SERVER_NAME = "pm-mcp";
+export const VERSION = metadata.version;
+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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckychen1993/pm-mcp",
-  "version": "0.1.5",
+  "version": "0.3.0",
   "description": "AI 编码项目的单一事实来源 + 健康台账 MCP 服务（事实来源 / 路线图 / 防幻觉 / 七本账 / 断点续做 / token 经济）",
   "keywords": [
     "mcp",
@@ -32,12 +32,15 @@
   "engines": {
     "node": ">=22.18.0"
   },
+  "pm_mcp": {
+    "acceptance_baseline": { "id": "pm-mcp-local-release", "version": "1.1.0" }
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "prepare": "npm run build",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.scripts.json",
-    "test": "node --test \"test/*.test.ts\"",
-    "coverage": "node --experimental-test-coverage --test-coverage-include=\"src/**/*.ts\" --test-coverage-lines=90 --test-coverage-branches=85 --test-coverage-functions=90 --test \"test/*.test.ts\"",
+    "test": "node --test-concurrency=2 --test \"test/*.test.ts\"",
+    "coverage": "node --experimental-test-coverage --test-coverage-include=\"src/**/*.ts\" --test-coverage-lines=90 --test-coverage-branches=85 --test-coverage-functions=90 --test-concurrency=2 --test \"test/*.test.ts\"",
     "audit": "node scripts/health-check.mts",
     "benchmark": "node scripts/benchmark.mts",
     "benchmark:volume": "node scripts/benchmark-volume.mts",
@@ -45,7 +48,7 @@
     "quality:plan": "node scripts/quality-gate.mts --plan",
     "acceptance:evidence": "node scripts/collect-acceptance-evidence.mts --root .",
     "acceptance:prepare": "node scripts/create-pm-acceptance-evaluation.mts --root .",
-    "acceptance": "node scripts/acceptance-gate.mts --root . --baseline-id pm-mcp-local-release --baseline-version 1.0.0 --evaluation .pm/acceptance/evaluations/pm-mcp-local-release-1.0.0.json",
+    "acceptance": "node scripts/acceptance-cycle.mts --root .",
     "acceptance:cycle": "node scripts/acceptance-cycle.mts --root .",
     "gate": "npm run audit -- --root . && npm run quality && npm run acceptance:cycle",
     "start": "node dist/index.js",