@luckychen1993/pm-mcp 0.1.4 → 0.3.0

package/dist/setup.js

@@ -2,24 +2,42 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
-export const PACKAGE_SPEC = "@luckychen1993/pm-mcp@0.1.4";
-export const SERVER_NAME = "pm-mcp";
-const CLIENTS = ["codex", "claude", "zcode", "cursor", "vscode"];
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { initProject } from "./init.js";
+import { isInitialized } from "./paths.js";
+import { refreshDerived } from "./dashboard.js";
+import { PACKAGE_SPEC, SERVER_NAME } from "./version.js";
+export { PACKAGE_SPEC, SERVER_NAME } from "./version.js";
+import { appendCodexProjectConfig } from "./setup-project.js";
+export { appendCodexProjectConfig, codexProjectServerKey } from "./setup-project.js";
+const CLIENTS = ["codex", "claude", "zcode", "cursor", "vscode", "workbuddy"];
 export function parseSetupArgs(argv) {
-    const options = { client: "auto", force: false, dryRun: false, help: false };
+    const options = { client: "auto", force: false, dryRun: false, help: false, project: false };
     for (let index = 0; index < argv.length; index += 1) {
         const arg = argv[index];
         if (arg === "--client") {
             const value = argv[index + 1];
-            if (!value || !["auto", "all", "codex", "claude", "zcode", "cursor", "vscode", "print"].includes(value)) {
-                throw new Error("--client must be auto, all, codex, claude, zcode, cursor, vscode, or print");
+            if (!value || !["auto", "all", "codex", "claude", "zcode", "cursor", "vscode", "workbuddy", "print"].includes(value)) {
+                throw new Error("--client must be auto, all, codex, claude, zcode, cursor, vscode, workbuddy, or print");
             }
             options.client = value;
             index += 1;
         }
+        else if (arg === "--project") {
+            options.project = true;
+            const value = argv[index + 1];
+            if (value && !value.startsWith("--")) {
+                options.projectDir = value;
+                index += 1;
+            }
+        }
         else if (arg === "--force") {
             options.force = true;
         }
+        else if (arg === "--local") {
+            options.local = true;
+        }
         else if (arg === "--dry-run") {
             options.dryRun = true;
         }
@@ -30,8 +48,29 @@ export function parseSetupArgs(argv) {
             throw new Error(`unknown setup argument: ${arg}`);
         }
     }
+    if (options.local && options.client !== "codex" && options.client !== "workbuddy" && options.client !== "print")
+        throw new Error("--local 目前只支持 --client codex、workbuddy 或 print");
+    if (options.local && options.client === "codex" && !options.project)
+        throw new Error("Codex --local 需要 --project 明确项目根");
     return options;
 }
+/**
+ * 本地已构建入口的启动定义。
+ *
+ * root 省略时不写 `--root`：宿主客户端会把**会话工作区**作为子进程 cwd，
+ * 服务端按 cwd 解析项目根。WorkBuddy 这类多项目宿主依赖这一行为，
+ * 显式钉根反而会把所有工作区都指到同一个项目。
+ */
+export function localServerLaunch(root) {
+    const entry = fileURLToPath(new URL("../dist/index.js", import.meta.url));
+    if (!fs.existsSync(entry) || !fs.lstatSync(entry).isFile())
+        throw new Error("本地入口未构建，请先 npm run build。");
+    return { command: process.execPath, args: root ? [entry, "--root", path.resolve(root)] : [entry] };
+}
+/** 钉定单个项目根的本地启动定义（Codex `--project` 等场景）。 */
+export function localProjectLaunch(root) {
+    return localServerLaunch(root);
+}
 export function commandExists(command, env = process.env, platform = process.platform) {
     const searchPath = env.PATH ?? env.Path ?? "";
     const suffixes = platform === "win32" ? [".exe", ".cmd", ".bat", ""] : [""];
@@ -57,6 +96,9 @@ export function detectClients(context) {
         found.push("cursor");
     if (context.commandExists("code"))
         found.push("vscode");
+    // WorkBuddy 桌面版：`codebuddy`/`workbuddy` 命令、WORKBUDDY_CONFIG_DIR，或既有配置目录任一命中即视为已安装。
+    if (context.commandExists("workbuddy") || context.commandExists("codebuddy") || Boolean(env.WORKBUDDY_CONFIG_DIR) || exists(path.join(home, ".workbuddy-ai")) || exists(path.join(home, ".workbuddy")))
+        found.push("workbuddy");
     return found;
 }
 function asObject(value, label) {
@@ -64,7 +106,10 @@ function asObject(value, label) {
         throw new Error(`${label} must be a JSON object`);
     return value;
 }
-export function mergeJsonServer(document, shape) {
+function defaultJsonLaunch() {
+    return { command: "npx", args: ["-y", PACKAGE_SPEC], env: {} };
+}
+export function mergeJsonServer(document, shape, launch = defaultJsonLaunch()) {
     const root = asObject(document, "configuration root");
     let servers;
     if (shape === "zcode") {
@@ -77,14 +122,14 @@ export function mergeJsonServer(document, shape) {
         const currentServers = root.mcpServers === undefined ? (root.mcpServers = {}) : root.mcpServers;
         servers = asObject(currentServers, "mcpServers");
     }
-    servers[SERVER_NAME] = { command: "npx", args: ["-y", PACKAGE_SPEC], env: {} };
+    servers[SERVER_NAME] = { ...launch, env: launch.env ?? {} };
     return root;
 }
 function backupName(file) {
     const stamp = new Date().toISOString().replace(/[-:.TZ]/g, "");
-    return `${file}.backup-${stamp}-${process.pid}`;
+    return `${file}.backup-${stamp}-${process.pid}-${randomUUID()}`;
 }
-export function writeJsonClientConfig(file, shape, dryRun = false) {
+export function writeJsonClientConfig(file, shape, dryRun = false, launch) {
     const absolute = path.resolve(file);
     const exists = fs.existsSync(absolute);
     let document = {};
@@ -99,7 +144,7 @@ export function writeJsonClientConfig(file, shape, dryRun = false) {
             throw new Error(`invalid JSON in ${absolute}; no changes made: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
-    const merged = mergeJsonServer(document, shape);
+    const merged = mergeJsonServer(document, shape, launch);
     if (dryRun)
         return null;
     fs.mkdirSync(path.dirname(absolute), { recursive: true });
@@ -126,6 +171,26 @@ function codexConfigPath(env, home) {
 function zcodeConfigPath(env, home) {
     return path.join(env.ZCODE_HOME || path.join(home, ".zcode"), "cli", "config.json");
 }
+/**
+ * WorkBuddy 桌面版的用户级 MCP 配置路径。
+ *
+ * 优先级：`WORKBUDDY_CONFIG_DIR` → `~/.workbuddy-ai`（当前版本数据目录）→ `~/.workbuddy`（旧版目录）→ 默认当前版本目录。
+ * 文件名固定 `mcp.json`，结构为标准 `{ "mcpServers": { ... } }`。
+ *
+ * 注意：WorkBuddy 的 MCP 子进程由会话工作区拉起，cwd 即当前项目，
+ * 因此这里**不写 `--root`**，一个条目即可服务所有工作区。
+ */
+export function workbuddyConfigPath(env, home, exists) {
+    if (env.WORKBUDDY_CONFIG_DIR)
+        return path.join(env.WORKBUDDY_CONFIG_DIR, "mcp.json");
+    const current = path.join(home, ".workbuddy-ai");
+    if (exists(current))
+        return path.join(current, "mcp.json");
+    const legacy = path.join(home, ".workbuddy");
+    if (exists(legacy))
+        return path.join(legacy, "mcp.json");
+    return path.join(current, "mcp.json");
+}
 function hasCodexServer(text) {
     return /^\s*\[mcp_servers\.(?:pm-mcp|"pm-mcp")\]\s*$/m.test(text);
 }
@@ -177,8 +242,12 @@ function configureCliClient(client, options, available, log) {
         throw new Error(`${client} could not add ${SERVER_NAME}`);
     return true;
 }
-function configureClient(client, options, context, log) {
+function configureClient(client, options, context, log, projectRoot) {
     if (client === "codex") {
+        if (options.project && projectRoot) {
+            appendCodexProjectConfig(codexConfigPath(context.env, context.home), projectRoot, options.force, options.dryRun, log, options.local ? localProjectLaunch(projectRoot) : undefined);
+            return;
+        }
         if (configureCliClient("codex", options, context.commandExists("codex"), log))
             return;
         appendCodexConfig(codexConfigPath(context.env, context.home), options.dryRun, log);
@@ -197,6 +266,16 @@ function configureClient(client, options, context, log) {
             log(`[backup] ${backup}`);
         return;
     }
+    if (client === "workbuddy") {
+        const file = workbuddyConfigPath(context.env, context.home, context.exists);
+        log(`[${options.dryRun ? "plan" : "write"}] workbuddy: ${file}`);
+        // 默认写 npx 发布版；--local 绑定已构建入口，未发布候选走这条路径。
+        const launch = options.local ? localServerLaunch() : undefined;
+        const backup = writeJsonClientConfig(file, "standard", options.dryRun, launch);
+        if (backup)
+            log(`[backup] ${backup}`);
+        return;
+    }
     if (!context.commandExists("code"))
         throw new Error("code was not found in PATH");
     const definition = JSON.stringify({ name: SERVER_NAME, command: "npx", args: ["-y", PACKAGE_SPEC] });
@@ -207,8 +286,12 @@ function configureClient(client, options, context, log) {
 function printHelp(log) {
     log("pm-mcp setup — configure local AI coding clients");
     log("");
-    log(`Usage: npx -y ${PACKAGE_SPEC} setup [--client auto|all|codex|claude|zcode|cursor|vscode|print] [--force] [--dry-run]`);
+    log(`Usage: npx -y ${PACKAGE_SPEC} setup [--client auto|all|codex|claude|zcode|cursor|vscode|workbuddy|print] [--project [dir]] [--force] [--dry-run] [--local]`);
     log("Default auto mode configures every detected supported client.");
+    log("--project [dir]: 在 Codex 把该目录注册为钉定项目并初始化 .pm（新项目一条命令上手；默认当前目录）");
+    log("--local: 使用本包已构建的本地入口，适合未发布候选；--force 仅升级已确认项目的 command/args。");
+    log("workbuddy: 写入 <WorkBuddy 数据目录>/mcp.json（标准 mcpServers），不钉根——服务端按会话工作区解析项目根。");
+    log("升级后运行 pm-mcp doctor --root <项目目录> 核验；现有客户端仍需重新连接。");
 }
 export function runSetup(argv, overrides = {}) {
     const options = parseSetupArgs(argv);
@@ -218,7 +301,8 @@ export function runSetup(argv, overrides = {}) {
         return 0;
     }
     if (options.client === "print") {
-        log(JSON.stringify({ mcpServers: { [SERVER_NAME]: { command: "npx", args: ["-y", PACKAGE_SPEC], env: {} } } }, null, 2));
+        const launch = options.local ? localProjectLaunch(options.projectDir ?? overrides.cwd ?? process.cwd()) : { command: "npx", args: ["-y", PACKAGE_SPEC] };
+        log(JSON.stringify({ mcpServers: { [SERVER_NAME]: { ...launch, env: {} } } }, null, 2));
         return 0;
     }
     const env = overrides.env ?? process.env;
@@ -226,24 +310,42 @@ export function runSetup(argv, overrides = {}) {
     const context = {
         env,
         home,
+        cwd: overrides.cwd,
         commandExists: overrides.commandExists ?? ((command) => commandExists(command, env)),
         exists: overrides.exists ?? fs.existsSync,
     };
+    const projectRoot = options.project ? path.resolve(options.projectDir?.trim() || context.cwd || process.cwd()) : undefined;
     const selected = options.client === "all"
         ? CLIENTS
         : options.client === "auto"
             ? detectClients(context)
             : [options.client];
-    if (selected.length === 0) {
+    if (selected.length === 0 && !options.project) {
         log("No supported client was detected. Use --client <name>, or --client print for generic JSON.");
         return 1;
     }
     log(`pm-mcp setup ${PACKAGE_SPEC}`);
-    log(`clients: ${selected.join(", ")}`);
+    if (selected.length > 0)
+        log(`clients: ${selected.join(", ")}`);
+    if (options.project && projectRoot) {
+        const name = path.basename(projectRoot) || "project";
+        log(`project: ${projectRoot}`);
+        if (options.dryRun) {
+            log(`[plan] init_project ${name}（.pm/ + PROJECT.md + AGENTS.md 工作规矩）`);
+        }
+        else if (isInitialized(projectRoot)) {
+            log("[skip] 项目已初始化（.pm/project.json 已存在）。");
+        }
+        else {
+            initProject(projectRoot, { name });
+            refreshDerived(projectRoot);
+            log(`[init] ✅ ${name} 已初始化：.pm/ 状态目录 + PROJECT.md 仪表盘 + AGENTS.md 工作规矩`);
+        }
+    }
     let failures = 0;
     for (const client of selected) {
         try {
-            configureClient(client, options, context, log);
+            configureClient(client, options, context, log, projectRoot);
         }
         catch (error) {
             failures += 1;
@@ -252,6 +354,22 @@ export function runSetup(argv, overrides = {}) {
     }
     if (failures > 0)
         return 1;
-    log("Done. Restart the configured client and ask it to call pm-mcp get_status.");
+    if (options.project && selected.includes("codex")) {
+        log("完成。请完全退出并重启 Codex，开新会话即可使用（工具名前缀 pm-mcp-<项目名>）。");
+    }
+    else if (selected.length === 1 && selected[0] === "workbuddy") {
+        log("完成。请在 WorkBuddy 的「连接器管理 → 自定义连接器」中确认信任 pm-mcp，再重开会话调用 get_status 核验。");
+    }
+    else {
+        // 多客户端时逐条给出各自的重连/授权要求，避免只提其中一个造成误导。
+        const notes = [];
+        if (selected.includes("workbuddy"))
+            notes.push("WorkBuddy 需在「连接器管理 → 自定义连接器」确认信任 pm-mcp");
+        if (selected.includes("codex"))
+            notes.push("Codex 需完全退出并重启");
+        log(notes.length > 0
+            ? `完成。重启已配置的客户端后调用 get_status 核验；${notes.join("；")}。`
+            : "Done. Restart the configured client and ask it to call pm-mcp get_status.");
+    }
     return 0;
 }

package/dist/task-evidence.js

@@ -0,0 +1,110 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { fingerprintProject } from "./project-fingerprint.js";
+import { changedGitFiles, projectFilePath } from "./git-state.js";
+import { SCAN_IGNORE_DIRS, ignoreMatcher, projectScanIgnores } from "./scan-policy.js";
+import { loadProject } from "./store.js";
+import { evidenceLevel, weakestEvidence } from "./quality-evidence.js";
+const fingerprint = z.object({ algorithm: z.literal("sha256-tree-v1"), sha256: z.string().regex(/^[a-f0-9]{64}$/) });
+const count = z.number().int().nonnegative().nullable();
+const reportSchema = z.object({
+    schema_version: z.literal(2), run_at: z.string().datetime(), ok: z.boolean(), execute: z.boolean(),
+    source: z.object({ before: fingerprint, after: fingerprint, stable: z.boolean() }).nullable(),
+    results: z.array(z.object({
+        unit_root: z.string(), kind: z.string(), command: z.string().min(1), args: z.array(z.string()),
+        status: z.string(), exit_code: z.number().nullable(), signal: z.string().nullable(), output_truncated: z.boolean(),
+        output_summary: z.object({ tests: count, passed: count.optional(), failed: count, skipped: count, cancelled: count, todo: count, coverage: z.unknown().optional() }),
+    })).min(1),
+});
+/** 只读取当前项目内生成的质量报告；链接、损坏和旧格式不冒充证据。 */
+export function verifiedTaskEvidence(root, requested, files = []) {
+    const absolute = fs.realpathSync.native(path.resolve(root));
+    const anchors = files.map(projectFilePath);
+    if (anchors.length === 0)
+        throw new Error("完成开发/修复任务需要通过 files 关联实际实现或测试文件。");
+    const excluded = ignoreMatcher(projectScanIgnores(root));
+    for (const rel of anchors) {
+        const parts = rel.split("/");
+        if (rel === "PROJECT.md" || parts.some((part, index) => (index < parts.length - 1 && SCAN_IGNORE_DIRS.has(part)) || excluded(parts.slice(0, index + 1).join("/"), index < parts.length - 1))) {
+            throw new Error(`任务文件不在源码验证范围内: ${rel}`);
+        }
+        for (let index = 0; index < parts.length; index++) {
+            const target = path.join(absolute, ...parts.slice(0, index + 1));
+            let stat;
+            try {
+                stat = fs.lstatSync(target);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+                if (!changedGitFiles(absolute).includes(rel))
+                    throw new Error(`任务关联文件不存在，也没有 Git 删除记录: ${rel}`);
+                break;
+            }
+            if (stat.isSymbolicLink() || (index === parts.length - 1 ? !stat.isFile() : !stat.isDirectory())) {
+                throw new Error(`任务必须关联项目内的普通文件，禁止链接或目录: ${rel}`);
+            }
+        }
+    }
+    const directory = path.join(absolute, ".pm", "quality-runs");
+    for (const part of [path.join(absolute, ".pm"), directory]) {
+        if (!fs.existsSync(part))
+            throw new Error("完成开发/修复任务前请执行 run_quality_matrix，缺少质量验证报告。");
+        const stat = fs.lstatSync(part);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error("质量证据目录必须是项目内的普通目录。");
+    }
+    const reports = fs.readdirSync(directory).filter((name) => /^quality-.*\.json$/.test(name)).map((name) => {
+        const file = path.join(directory, name);
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 4 * 1024 * 1024)
+            throw new Error("质量证据必须是有界普通文件，禁止符号链接。");
+        const raw = fs.readFileSync(file, "utf8");
+        const value = JSON.parse(raw);
+        const header = z.object({ run_at: z.string().datetime() }).safeParse(value);
+        if (!header.success)
+            throw new Error(`质量报告 ${name} 缺少有效生成时间，无法判断新鲜度。`);
+        return { relative: `.pm/quality-runs/${name}`, raw, value, runAt: header.data.run_at };
+    }).sort((a, b) => b.runAt.localeCompare(a.runAt) || b.relative.localeCompare(a.relative));
+    const latest = reports[0];
+    if (!latest)
+        throw new Error("缺少质量验证报告，请先执行 run_quality_matrix。");
+    if (requested !== undefined && projectFilePath(requested) !== latest.relative)
+        throw new Error("必须使用最新质量报告，不能绕过后来出现的验证结果。");
+    const parsed = reportSchema.safeParse(latest.value);
+    if (!parsed.success)
+        throw new Error("最新质量报告无效或格式过旧，请重新执行验证。");
+    const report = parsed.data;
+    if (!report.ok || !report.execute || !report.source?.stable || report.source.before.sha256 !== report.source.after.sha256 ||
+        report.results.some((item) => item.status !== "passed" || item.exit_code !== 0 || item.signal !== null || item.output_truncated ||
+            [item.output_summary.failed, item.output_summary.skipped, item.output_summary.cancelled, item.output_summary.todo].some((n) => n !== null && n > 0))) {
+        throw new Error("最新质量验证失败、未执行、输出不完整或存在跳过项，不能标记完成。");
+    }
+    const tests = report.results.filter((item) => item.kind === "test" || item.kind === "coverage");
+    if (tests.length === 0 || tests.some((item) => item.output_summary.tests === 0))
+        throw new Error("完成开发/修复任务需要实际测试或覆盖率执行证据。");
+    const level = weakestEvidence(tests.map((item) => evidenceLevel(item.kind, item.output_summary, item.output_truncated)));
+    const policy = loadProject(root).completion_evidence;
+    if (level === "execution_only" && policy?.minimum !== "execution_only") {
+        throw new Error("仅有命令执行证据，未观察到完整测试计数。默认完成策略要求 tests_observed；请使用可识别的测试摘要，或由项目负责人明确设置兼容策略并说明理由。");
+    }
+    const within = (base, target) => {
+        const relative = path.relative(base, target);
+        return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+    };
+    if (tests.some((item) => !path.isAbsolute(item.unit_root)))
+        throw new Error("质量报告的执行目录不属于当前项目。");
+    const unitRoots = tests.map((item) => fs.realpathSync.native(item.unit_root));
+    if (unitRoots.some((unit) => !within(absolute, unit)))
+        throw new Error("质量报告的执行目录不属于当前项目。");
+    if (anchors.some((file) => !unitRoots.some((unit) => within(unit, path.join(absolute, file))))) {
+        throw new Error("质量报告的测试单元未覆盖任务关联文件所在目录。");
+    }
+    const current = fingerprintProject(absolute);
+    if (current.sha256 !== report.source.after.sha256)
+        throw new Error("质量验证对应的源码已变化，证据过期，请重新验证。");
+    const digest = createHash("sha256").update(latest.raw).digest("hex");
+    return `质量报告: ${latest.relative}\n报告 SHA-256: ${digest}\n源码 SHA-256: ${current.sha256}\n执行时间: ${report.run_at}\n证据等级: ${level}${policy ? `\n项目策略: ${policy.minimum}；${policy.reason}` : "\n项目策略: tests_observed（默认）"}`;
+}

package/dist/task-pagination.js

@@ -0,0 +1,64 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { loadTasks } from "./store.js";
+import { TaskStatusSchema, TaskTypeSchema } from "./types.js";
+const CursorSchema = z.object({ v: z.literal(1), revision: z.string().regex(/^[a-f0-9]{64}$/), offset: z.number().int().positive(), size: z.number().int().min(1).max(100) }).strict();
+export const TaskPageSchema = z.object({
+    total: z.number().int().nonnegative(), all_total: z.number().int().nonnegative(),
+    offset: z.number().int().nonnegative(), page_size: z.number().int().min(1).max(100), returned: z.number().int().nonnegative(),
+    has_more: z.boolean(), next_cursor: z.string().nullable(), revision: z.string(),
+    items: z.array(z.object({ id: z.string(), title: z.string(), status: TaskStatusSchema, type: TaskTypeSchema,
+        priority: z.string().nullable(), milestone: z.string().nullable(), next_step: z.string().nullable(), abbreviated: z.boolean() })),
+});
+/** 游标是读取位置，不是授权凭据；绑定项目、过滤及同一份已读取的账本快照。 */
+export function taskPage(root, query, maximum = 100, data = loadTasks(root)) {
+    const filters = { status: query.status ?? null, type: query.type ?? null, milestone: query.milestone ?? null, tag: query.tag ?? null, include_done: query.include_done ?? false };
+    let canonical = fs.realpathSync.native(path.resolve(root));
+    if (process.platform === "win32")
+        canonical = canonical.toLowerCase();
+    const revision = createHash("sha256").update(canonical).update("\0").update(JSON.stringify(filters)).update("\0").update(JSON.stringify(data)).digest("hex");
+    let cursor;
+    if (query.cursor !== undefined) {
+        try {
+            if (query.cursor.length > 1024 || !/^[A-Za-z0-9_-]+$/.test(query.cursor))
+                throw new Error();
+            cursor = CursorSchema.parse(JSON.parse(Buffer.from(query.cursor, "base64url").toString("utf8")));
+        }
+        catch {
+            throw new Error("分页游标无效，请从第一页重新读取。");
+        }
+        if (cursor.revision !== revision)
+            throw new Error("任务数据、项目或过滤条件已变化，游标失效，请重新读取第一页。");
+    }
+    const limit = Math.max(1, Math.min(100, Math.floor(maximum)));
+    const requested = query.page_size ?? cursor?.size ?? 25;
+    if (!Number.isInteger(requested) || requested < 1 || requested > 100)
+        throw new Error("page_size 必须为 1 到 100。");
+    const size = Math.min(requested, limit);
+    if (cursor && (cursor.size !== size || cursor.offset % size !== 0))
+        throw new Error("分页大小或输出预算已变化，请重新读取第一页。");
+    const list = data.tasks.filter((task) => (query.status ? task.status === query.status : query.include_done || !["done", "cancelled"].includes(task.status)) &&
+        (!query.type || task.type === query.type) && (!query.milestone || task.milestone === query.milestone) && (!query.tag || task.tags.includes(query.tag)));
+    const offset = cursor?.offset ?? 0;
+    if (cursor && offset >= list.length)
+        throw new Error("分页游标越界，请重新读取第一页。");
+    const brief = (text, length) => { const one = text.replace(/\s+/g, " "); return one.length > length ? one.slice(0, length) + "…" : one; };
+    const items = list.slice(offset, offset + size).map((task) => {
+        const title = brief(task.title, 160), nextStep = task.checkpoint ? brief(task.checkpoint.next_step, 80) : null;
+        return { id: task.id, title, status: task.status, type: task.type, priority: task.priority, milestone: task.milestone,
+            next_step: nextStep, abbreviated: title !== task.title || nextStep !== (task.checkpoint?.next_step ?? null) };
+    });
+    const next = offset + items.length;
+    return { total: list.length, all_total: data.tasks.length, offset, page_size: size, returned: items.length, has_more: next < list.length,
+        next_cursor: next < list.length ? Buffer.from(JSON.stringify({ v: 1, revision, offset: next, size })).toString("base64url") : null, revision, items };
+}
+export function taskPageText(page) {
+    return [
+        `共 ${page.total} 个任务（全部 ${page.all_total} 个）；本页 ${page.offset + (page.returned ? 1 : 0)}-${page.offset + page.returned}，返回 ${page.returned} 个。`,
+        ...page.items.map((task) => `${task.status === "in_progress" ? "🔄" : task.status === "blocked" ? "🚫" : task.status === "done" ? "✅" : "☐"} ${task.id} [${task.status}/${task.type}${task.priority ? `/${task.priority}` : ""}] ${task.title}${task.next_step ? ` → ${task.next_step}` : ""}`),
+        page.next_cursor ? `下一页：保持过滤条件，list_tasks 传 cursor=${page.next_cursor}` : "已到末页，无更多任务。",
+        ...(page.items.some((task) => task.abbreviated) ? ["长标题或下一步已缩略；任务编号与分页条目完整。"] : []),
+    ].join("\n");
+}

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(),