@luckychen1993/pm-mcp 0.1.1

package/dist/task-tools.js

@@ -0,0 +1,198 @@
+import { z } from "zod";
+import { refreshDerived } from "./dashboard.js";
+import { foldLines, normSep } from "./budget.js";
+import { requireInitialized } from "./paths.js";
+import { loadRoadmap, loadTasks, nextId, saveTasks } from "./store.js";
+import { now } from "./types.js";
+import { budgetLines, tool, toolW } from "./tool-base.js";
+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。", {
+        title: z.string().min(1),
+        detail: z.string().optional(),
+        type: z.enum(["feature", "refactor", "fix", "chore", "debt"]).optional().describe("默认 feature"),
+        priority: z.enum(["P0", "P1", "P2", "P3"]).optional(),
+        milestone: z.string().optional().describe("所属里程碑 id，如 M1"),
+        tags: z.array(z.string()).optional(),
+        files: z.array(z.string()).optional().describe("关联文件（相对路径）"),
+        acceptance: z.string().optional().describe("验收标准"),
+        steps: z.array(stepSchema).optional().describe("步骤清单（长任务必填）"),
+    }, (args) => {
+        requireInitialized(root);
+        const roadmap = loadRoadmap(root);
+        if (args.milestone && !roadmap.milestones.some((m) => m.id === args.milestone)) {
+            throw new Error(`里程碑 ${args.milestone} 不存在。现有: ${roadmap.milestones.map((m) => m.id).join(", ") || "无"}`);
+        }
+        const data = loadTasks(root);
+        const id = nextId("T", data.seq);
+        const t = now();
+        data.seq += 1;
+        data.tasks.push({
+            id,
+            title: args.title,
+            detail: args.detail ?? "",
+            type: args.type ?? "feature",
+            status: "backlog",
+            priority: args.priority ?? null,
+            milestone: args.milestone ?? null,
+            steps: (args.steps ?? []).map((s) => ({ text: s.text, done: s.done ?? false })),
+            checkpoint: null,
+            files: (args.files ?? []).map(normSep),
+            acceptance: args.acceptance ?? "",
+            result_note: "",
+            verification: "",
+            tags: args.tags ?? [],
+            author: "",
+            created: t,
+            updated: t,
+            started_at: null,
+            completed_at: null,
+        });
+        saveTasks(root, data);
+        refreshDerived(root);
+        const tip = (args.steps ?? []).length === 0
+            ? "\n提示: 长任务建议补 steps（update_task 传 steps），否则中断后续做只能靠回忆。"
+            : "";
+        return `✅ 任务 ${id}「${args.title}」已创建（${args.type ?? "feature"}/${args.milestone ?? "无里程碑"}）。${tip}`;
+    });
+    tool(server, "list_tasks", "列出任务（默认不含 done/cancelled）。可按状态/类型/里程碑/标签过滤。", {
+        status: z.enum(["backlog", "todo", "in_progress", "blocked", "done", "cancelled"]).optional(),
+        type: z.enum(["feature", "refactor", "fix", "chore", "debt"]).optional(),
+        milestone: z.string().optional(),
+        tag: z.string().optional(),
+        include_done: z.boolean().optional().describe("默认 false"),
+    }, (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 整体替换步骤清单。", {
+        id: z.string(),
+        status: z.enum(["backlog", "todo", "in_progress", "blocked", "done", "cancelled"]).optional(),
+        title: z.string().optional(),
+        detail: z.string().optional(),
+        priority: z.enum(["P0", "P1", "P2", "P3"]).nullable().optional(),
+        milestone: z.string().nullable().optional(),
+        tags: z.array(z.string()).optional(),
+        files: z.array(z.string()).optional(),
+        acceptance: z.string().optional(),
+        result_note: z.string().optional().describe("完成笔记（转 done 必填）"),
+        verification: z.string().optional().describe("怎么验证的：命令/测试名"),
+        steps: z.array(stepSchema).optional().describe("整体替换步骤清单"),
+        step_done: z.number().int().min(1).optional().describe("勾选完成第 N 步"),
+        author: z.string().optional(),
+    }, (args) => {
+        requireInitialized(root);
+        const data = loadTasks(root);
+        const t = data.tasks.find((x) => x.id === args.id);
+        if (!t)
+            throw new Error(`找不到任务 ${args.id}。`);
+        const tnow = now();
+        if (args.title !== undefined)
+            t.title = args.title;
+        if (args.detail !== undefined)
+            t.detail = args.detail;
+        if (args.priority !== undefined)
+            t.priority = args.priority ?? null;
+        if (args.milestone !== undefined) {
+            if (args.milestone) {
+                const roadmap = loadRoadmap(root);
+                if (!roadmap.milestones.some((m) => m.id === args.milestone)) {
+                    throw new Error(`里程碑 ${args.milestone} 不存在。`);
+                }
+            }
+            t.milestone = args.milestone ?? null;
+        }
+        if (args.tags !== undefined)
+            t.tags = args.tags;
+        if (args.files !== undefined)
+            t.files = args.files.map(normSep);
+        if (args.acceptance !== undefined)
+            t.acceptance = args.acceptance;
+        if (args.result_note !== undefined)
+            t.result_note = args.result_note;
+        if (args.verification !== undefined)
+            t.verification = args.verification;
+        if (args.author !== undefined)
+            t.author = args.author;
+        if (args.steps !== undefined)
+            t.steps = args.steps.map((s) => ({ text: s.text, done: s.done ?? false }));
+        if (args.step_done !== undefined) {
+            const s = t.steps[args.step_done - 1];
+            if (!s)
+                throw new Error(`步骤 ${args.step_done} 不存在（共 ${t.steps.length} 步）。`);
+            s.done = true;
+        }
+        const notes = [];
+        if (args.status !== undefined && args.status !== t.status) {
+            if (args.status === "done") {
+                const note = args.result_note !== undefined ? args.result_note : t.result_note;
+                if (!note.trim()) {
+                    throw new Error(`转 done 必须填 result_note（完成笔记）——「声称做完」要有交代。当前任务 ${t.id} 缺少。`);
+                }
+                if (note.trim().length < 4) {
+                    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;
+            if (args.status === "in_progress" && !t.started_at)
+                t.started_at = tnow;
+            t.status = args.status;
+        }
+        t.updated = tnow;
+        saveTasks(root, data);
+        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");
+    });
+    toolW(server, root, "checkpoint", "断点存档：长任务做到一半（或上下文快满）时随手保存「当前进度 + 下一步动作」。新会话 get_status 会直接给出恢复点，不用靠回忆。", {
+        task_id: z.string(),
+        note: z.string().describe("当前进展到哪了"),
+        next_step: z.string().describe("下一个具体动作（新会话从这里续做）"),
+    }, (args) => {
+        requireInitialized(root);
+        const data = loadTasks(root);
+        const t = data.tasks.find((x) => x.id === args.task_id);
+        if (!t)
+            throw new Error(`找不到任务 ${args.task_id}。`);
+        t.checkpoint = { note: args.note, next_step: args.next_step, at: now() };
+        if (t.status === "backlog" || t.status === "todo")
+            t.status = "in_progress";
+        t.updated = now();
+        saveTasks(root, data);
+        refreshDerived(root);
+        return `✅ 断点已存档（${t.id}）。下次会话开工 get_status 会显示「下一步: ${args.next_step}」。`;
+    });
+}

package/dist/tool-base.js

@@ -0,0 +1,32 @@
+import { loadProject, withLedgerLock } from "./store.js";
+export function tool(server, name, description, schema, fn) {
+    server.registerTool(name, { description, inputSchema: schema }, (async (args) => {
+        try {
+            const text = await fn(args);
+            return { content: [{ type: "text", text }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `错误: ${error.message}` }], isError: true };
+        }
+    }));
+}
+/** 写工具必须使用同步 handler，保证跨进程账本锁覆盖完整读-改-写。 */
+export function toolW(server, root, name, description, schema, fn) {
+    server.registerTool(name, { description, inputSchema: schema }, ((args) => {
+        try {
+            const text = withLedgerLock(root, () => fn(args));
+            return { content: [{ type: "text", text }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `错误: ${error.message}` }], isError: true };
+        }
+    }));
+}
+export function budgetLines(root) {
+    try {
+        return loadProject(root).budgets.outputBudgetLines;
+    }
+    catch {
+        return 150;
+    }
+}

package/dist/tools.js

@@ -0,0 +1,21 @@
+import { registerAcceptanceTools } from "./acceptance-tools.js";
+import { registerAuditTools, registerRegistryTools } from "./audit-tools.js";
+import { registerGovernanceTools } from "./governance-tools.js";
+import { registerDecisionTools, registerFeatureTools, registerSearchTools, registerSessionTools, } from "./knowledge-tools.js";
+import { registerProjectTools, registerRoadmapTools } from "./project-tools.js";
+import { registerTaskTools } from "./task-tools.js";
+export { registerProjectTools, registerRoadmapTools, registerTaskTools, registerFeatureTools, registerDecisionTools, registerSessionTools, registerSearchTools, registerAuditTools, registerRegistryTools, };
+/** Stable aggregate entrypoint used by the MCP server. */
+export function registerAllTools(server, root) {
+    registerProjectTools(server, root);
+    registerRoadmapTools(server, root);
+    registerTaskTools(server, root);
+    registerFeatureTools(server, root);
+    registerDecisionTools(server, root);
+    registerSessionTools(server, root);
+    registerSearchTools(server, root);
+    registerAuditTools(server, root);
+    registerRegistryTools(server);
+    registerGovernanceTools(server, root);
+    registerAcceptanceTools(server, root);
+}

package/dist/types.js

@@ -0,0 +1,208 @@
+import { z } from "zod";
+import { normSep } from "./budget.js";
+export const now = () => new Date().toISOString();
+/** 文件清单字段：统一 / 分隔（Windows 反斜杠入库即规范化），缺省空数组 */
+const filesField = () => z.array(z.string()).default([]).transform((list) => list.map(normSep));
+/* ---------------------------------- 项目 ---------------------------------- */
+export const BudgetsSchema = z.object({
+    /** 单文件行数预算（超出进复杂度账） */
+    maxFileLoc: z.number().int().min(10).default(500),
+    /** 里程碑重构类任务（refactor+debt）最低占比 %，低于则告警"重构被挤出" */
+    refactorQuotaPct: z.number().min(0).max(100).default(20),
+    /** 单次会话波及文件数阈值（超出告警"波及面过大"） */
+    sessionBlastRadius: z.number().int().min(1).default(15),
+    /** 读类工具输出行数硬预算（超出自动折叠） */
+    outputBudgetLines: z.number().int().min(20).default(150),
+});
+export const ExposureSchema = z.enum(["local", "network", "public"]);
+export const ProjectSchema = z.object({
+    name: z.string().trim().min(1),
+    description: z.string().default(""),
+    stack: z.array(z.string()).default([]),
+    goals: z.array(z.string()).default([]),
+    /** 当前阶段，自由文本，如 "MVP 开发中" */
+    phase: z.string().default(""),
+    /** 登记的模块名（用于复杂度账的"未登记目录"检测） */
+    modules: z.array(z.string()).default([]),
+    /** 暴露面：local=本机工具 / network=内网服务 / public=公网服务，影响安全告警力度 */
+    exposure: ExposureSchema.default("local"),
+    /** 项目许可证（SPDX 或名称），用于依赖兼容性对账 */
+    license: z.string().default(""),
+    budgets: BudgetsSchema.default(BudgetsSchema.parse({})),
+    created: z.string(),
+    updated: z.string(),
+});
+/* --------------------------------- 里程碑 --------------------------------- */
+export const MilestoneStatusSchema = z.enum(["planned", "active", "done", "paused"]);
+export const MilestoneSchema = z.object({
+    id: z.string(),
+    title: z.string().trim().min(1),
+    goal: z.string().default(""),
+    status: MilestoneStatusSchema.default("planned"),
+    order: z.number().int().default(0),
+    created: z.string(),
+    updated: z.string(),
+});
+export const RoadmapFileSchema = z.object({
+    seq: z.number().int().default(0),
+    milestones: z.array(MilestoneSchema).default([]),
+});
+/* ---------------------------------- 任务 ---------------------------------- */
+export const TaskTypeSchema = z.enum(["feature", "refactor", "fix", "chore", "debt"]);
+export const TaskStatusSchema = z.enum([
+    "backlog",
+    "todo",
+    "in_progress",
+    "blocked",
+    "done",
+    "cancelled",
+]);
+export const StepSchema = z.object({
+    text: z.string(),
+    done: z.boolean().default(false),
+});
+export const CheckpointSchema = z.object({
+    note: z.string(),
+    next_step: z.string(),
+    at: z.string(),
+});
+export const TaskSchema = z.object({
+    id: z.string(),
+    title: z.string().trim().min(1),
+    detail: z.string().default(""),
+    type: TaskTypeSchema.default("feature"),
+    status: TaskStatusSchema.default("backlog"),
+    priority: z.enum(["P0", "P1", "P2", "P3"]).nullable().default(null),
+    milestone: z.string().nullable().default(null),
+    /** 长任务显式步骤清单——断点续做的载体 */
+    steps: z.array(StepSchema).default([]),
+    checkpoint: CheckpointSchema.nullable().default(null),
+    files: filesField(),
+    acceptance: z.string().default(""),
+    result_note: z.string().default(""),
+    /** done 时"怎么证明"：用什么命令/测试验证 */
+    verification: z.string().default(""),
+    tags: z.array(z.string()).default([]),
+    author: z.string().default(""),
+    created: z.string(),
+    updated: z.string(),
+    started_at: z.string().nullable().default(null),
+    completed_at: z.string().nullable().default(null),
+});
+export const TasksFileSchema = z.object({
+    seq: z.number().int().default(0),
+    tasks: z.array(TaskSchema).default([]),
+});
+/* ---------------------------------- 功能 ---------------------------------- */
+export const FeatureStatusSchema = z.enum(["planned", "implemented", "deprecated"]);
+export const FeatureSchema = z.object({
+    id: z.string(),
+    name: z.string().trim().min(1),
+    description: z.string().default(""),
+    module: z.string().default(""),
+    entry_files: filesField(),
+    test_files: filesField(),
+    status: FeatureStatusSchema.default("implemented"),
+    created: z.string(),
+    updated: z.string(),
+});
+export const FeaturesFileSchema = z.object({
+    seq: z.number().int().default(0),
+    features: z.array(FeatureSchema).default([]),
+});
+/* ---------------------------------- 会话 ---------------------------------- */
+export const SessionSchema = z.object({
+    id: z.string(),
+    date: z.string(),
+    /** 谁做的：zcode / codex / human:张三 …… */
+    author: z.string().default(""),
+    summary: z.string().trim().min(1),
+    files: filesField(),
+    next_steps: z.array(z.string()).default([]),
+});
+export const SessionsFileSchema = z.object({
+    seq: z.number().int().default(0),
+    sessions: z.array(SessionSchema).default([]),
+});
+/* --------------------------------- 调试记录 --------------------------------- */
+export const DebugEntrySchema = z.object({
+    id: z.string(),
+    date: z.string(),
+    author: z.string().default(""),
+    symptom: z.string(),
+    root_cause: z.string(),
+    fix: z.string(),
+    verified_how: z.string().default(""),
+    files: filesField(),
+    task_id: z.string().nullable().default(null),
+});
+export const DebugLogFileSchema = z.object({
+    seq: z.number().int().default(0),
+    entries: z.array(DebugEntrySchema).default([]),
+});
+/* -------------------------------- 文件用途索引 ------------------------------- */
+export const FileNoteSchema = z.object({
+    purpose: z.string(),
+    /** 代码来源（如 Stack Overflow 链接、某仓库），provenance 用 */
+    source: z.string().default(""),
+    /** 该文件引用代码的许可证 */
+    license: z.string().default(""),
+    updated: z.string(),
+});
+export const FileNotesFileSchema = z.object({
+    notes: z.record(z.string(), FileNoteSchema).default({}),
+});
+/* --------------------------------- 安全体检 --------------------------------- */
+export const SeveritySchema = z.enum(["high", "medium", "low"]);
+export const FindingSchema = z.object({
+    id: z.string(),
+    rule: z.string(),
+    severity: SeveritySchema,
+    file: z.string(),
+    line: z.number().int(),
+    /** sha1(rule + 相对路径 + 命中内容)，行号漂移不误报；绝不存命中明文 */
+    fingerprint: z.string(),
+    status: z.enum(["open", "fixed", "accepted"]).default("open"),
+    note: z.string().default(""),
+    first_seen: z.string(),
+    last_seen: z.string(),
+});
+export const SecurityFileSchema = z.object({
+    findings: z.array(FindingSchema).default([]),
+    last_scan: z.string().nullable().default(null),
+});
+/* ---------------------------------- 快照 ---------------------------------- */
+export const SnapshotSchema = z.object({
+    taken_at: z.string(),
+    file: z.string(),
+    total_files: z.number().int(),
+    total_loc: z.number().int(),
+    test_files: z.number().int(),
+    skip_markers: z.number().int(),
+    /** 依赖清单（扫描时的直接依赖，供 audit 对比新增） */
+    deps: z.array(z.string()).default([]),
+    by_ext: z.array(z.object({ ext: z.string(), files: z.number().int(), loc: z.number().int() })).default([]),
+    top_dirs: z.array(z.object({ dir: z.string(), files: z.number().int(), loc: z.number().int() })).default([]),
+    largest_files: z.array(z.object({ path: z.string(), loc: z.number().int() })).default([]),
+    index_coverage_pct: z.number().default(0),
+});
+/* --------------------------------- 全局注册表 -------------------------------- */
+export const RegistryEntrySchema = z.object({
+    name: z.string(),
+    root: z.string(),
+    last_seen: z.string(),
+});
+export const RegistrySchema = z.object({
+    projects: z.array(RegistryEntrySchema).default([]),
+});
+/* --------------------------- 用户自定义安全规则 ------------------------------ */
+export const CustomRuleSchema = z.object({
+    id: z.string(),
+    severity: SeveritySchema.default("medium"),
+    pattern: z.string(),
+    message: z.string().default(""),
+    glob: z.string().optional(),
+});
+export const ExtraRulesFileSchema = z.object({
+    rules: z.array(CustomRuleSchema).default([]),
+});