mcp-probe-kit 3.6.8 → 3.6.9

package/build/lib/__tests__/file-delivery.unit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/lib/__tests__/file-delivery.unit.test.js

@@ -0,0 +1,62 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, expect, test } from "vitest";
+import { buildFileStatusEntries } from "../file-delivery.js";
+const tempDirs = [];
+afterEach(() => {
+    while (tempDirs.length > 0) {
+        const dir = tempDirs.pop();
+        if (dir) {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    }
+});
+describe("buildFileStatusEntries", () => {
+    test("marks MCP-created files as written", () => {
+        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "file-delivery-"));
+        tempDirs.push(projectRoot);
+        const result = buildFileStatusEntries(projectRoot, [{ path: "docs/guide.md", purpose: "User guide" }], [{ path: "docs/guide.md", action: "created" }], []);
+        expect(result).toEqual([
+            {
+                path: "docs/guide.md",
+                purpose: "User guide",
+                exists: false,
+                written: true,
+                agent_action_required: false,
+            },
+        ]);
+    });
+    test("treats pre-existing on-disk files as written when not pending", () => {
+        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "file-delivery-"));
+        tempDirs.push(projectRoot);
+        const relPath = "docs/existing.md";
+        fs.mkdirSync(path.join(projectRoot, "docs"), { recursive: true });
+        fs.writeFileSync(path.join(projectRoot, relPath), "# existing", "utf8");
+        const result = buildFileStatusEntries(projectRoot, [{ path: relPath }], [], []);
+        expect(result).toEqual([
+            {
+                path: relPath,
+                exists: true,
+                written: true,
+                agent_action_required: false,
+            },
+        ]);
+    });
+    test("pending files require agent action and are not written", () => {
+        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "file-delivery-"));
+        tempDirs.push(projectRoot);
+        const relPath = "docs/pending.md";
+        fs.mkdirSync(path.join(projectRoot, "docs"), { recursive: true });
+        fs.writeFileSync(path.join(projectRoot, relPath), "stub", "utf8");
+        const result = buildFileStatusEntries(projectRoot, [{ path: relPath }], [{ path: relPath, action: "skipped" }], [{ path: relPath, reason: "Agent must fill template" }]);
+        expect(result).toEqual([
+            {
+                path: relPath,
+                exists: true,
+                written: false,
+                agent_action_required: true,
+            },
+        ]);
+    });
+});

package/build/lib/file-delivery.d.ts

@@ -11,7 +11,18 @@ export interface FileDeliveryReport {
     writtenFiles: DeliveredFile[];
     pendingFiles: PendingFile[];
 }
+export interface FileStatusEntry {
+    path: string;
+    exists: boolean;
+    written: boolean;
+    agent_action_required: boolean;
+    purpose?: string;
+}
 export declare function toPosixRel(relPath: string): string;
 export declare function writeProjectFile(projectRoot: string, relPath: string, content: string, policy: "ifMissing" | "always"): DeliveredFile;
+export declare function buildFileStatusEntries(projectRoot: string, entries: Array<{
+    path: string;
+    purpose?: string;
+}>, writtenFiles: DeliveredFile[], pendingFiles: PendingFile[]): FileStatusEntry[];
 export declare function mergeDeliveryReports(...reports: FileDeliveryReport[]): FileDeliveryReport;
 export declare function formatFileDeliverySection(report: FileDeliveryReport): string;

package/build/lib/file-delivery.js

@@ -14,6 +14,26 @@ export function writeProjectFile(projectRoot, relPath, content, policy) {
     fs.writeFileSync(absPath, content, "utf8");
     return { path: posixPath, action: existed ? "updated" : "created" };
 }
+export function buildFileStatusEntries(projectRoot, entries, writtenFiles, pendingFiles) {
+    const writtenByMcp = new Set(writtenFiles
+        .filter((file) => file.action === "created" || file.action === "updated")
+        .map((file) => toPosixRel(file.path)));
+    const pendingPaths = new Set(pendingFiles.map((file) => toPosixRel(file.path)));
+    return entries.map(({ path: relPath, purpose }) => {
+        const posixPath = toPosixRel(relPath);
+        const absPath = path.join(path.resolve(projectRoot), ...posixPath.split("/"));
+        const exists = fs.existsSync(absPath);
+        const agent_action_required = pendingPaths.has(posixPath);
+        const written = writtenByMcp.has(posixPath) || (exists && !agent_action_required);
+        return {
+            path: posixPath,
+            ...(purpose !== undefined ? { purpose } : {}),
+            exists,
+            written,
+            agent_action_required,
+        };
+    });
+}
 export function mergeDeliveryReports(...reports) {
     return {
         writtenFiles: reports.flatMap((report) => report.writtenFiles),

package/build/schemas/index.d.ts

@@ -218,7 +218,7 @@ export declare const allToolSchemas: ({
     };
 } | {
     readonly name: "init_project_context";
-    readonly description: "生成/更新项目上下文：默认写入 AGENTS.md（含 MCP 与 GitNexus 触发规则）及 docs/project-context/。新功能请先 start_feature，修 bug 请先 start_bugfix。完成后 Agent 应阅读 AGENTS.md。";
+    readonly description: "生成/更新项目上下文写作计划（delegated）：MCP 写入 AGENTS.md 与 layout.json；project-context 分类文档与 graph-insights 由 Agent 按返回的 plan 落盘。新功能请先 start_feature，修 bug 请先 start_bugfix。";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {

package/build/schemas/output/project-tools.d.ts

@@ -216,9 +216,21 @@ export declare const ProjectContextSchema: {
                     readonly purpose: {
                         readonly type: "string";
                     };
+                    readonly exists: {
+                        readonly type: "boolean";
+                        readonly description: "文件是否已存在于磁盘";
+                    };
+                    readonly written: {
+                        readonly type: "boolean";
+                        readonly description: "内容是否已落盘（MCP 已写或 Agent 无需再写）";
+                    };
+                    readonly agent_action_required: {
+                        readonly type: "boolean";
+                        readonly description: "是否仍需 Agent 按 plan 手动写入";
+                    };
                 };
             };
-            readonly description: "文档索引（含已写入与待生成）";
+            readonly description: "文档索引（含 exists / written / agent_action_required 状态）";
         };
         readonly writtenFiles: {
             readonly type: "array";
@@ -602,6 +614,9 @@ export interface ProjectContext {
     documentation?: Array<{
         path?: string;
         purpose?: string;
+        exists?: boolean;
+        written?: boolean;
+        agent_action_required?: boolean;
     }>;
     nextSteps?: string[];
     metadata?: Record<string, any>;

package/build/schemas/output/project-tools.js

@@ -120,9 +120,15 @@ export const ProjectContextSchema = {
                 properties: {
                     path: { type: 'string' },
                     purpose: { type: 'string' },
+                    exists: { type: 'boolean', description: '文件是否已存在于磁盘' },
+                    written: { type: 'boolean', description: '内容是否已落盘（MCP 已写或 Agent 无需再写）' },
+                    agent_action_required: {
+                        type: 'boolean',
+                        description: '是否仍需 Agent 按 plan 手动写入',
+                    },
                 },
             },
-            description: '文档索引（含已写入与待生成）',
+            description: '文档索引（含 exists / written / agent_action_required 状态）',
         },
         writtenFiles: {
             type: 'array',

package/build/schemas/project-tools.d.ts

@@ -22,7 +22,7 @@ export declare const projectToolSchemas: readonly [{
     };
 }, {
     readonly name: "init_project_context";
-    readonly description: "生成/更新项目上下文：默认写入 AGENTS.md（含 MCP 与 GitNexus 触发规则）及 docs/project-context/。新功能请先 start_feature，修 bug 请先 start_bugfix。完成后 Agent 应阅读 AGENTS.md。";
+    readonly description: "生成/更新项目上下文写作计划（delegated）：MCP 写入 AGENTS.md 与 layout.json；project-context 分类文档与 graph-insights 由 Agent 按返回的 plan 落盘。新功能请先 start_feature，修 bug 请先 start_bugfix。";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {

package/build/schemas/project-tools.js

@@ -25,7 +25,7 @@ export const projectToolSchemas = [
     },
     {
         name: "init_project_context",
-        description: "生成/更新项目上下文：默认写入 AGENTS.md（含 MCP 与 GitNexus 触发规则）及 docs/project-context/。新功能请先 start_feature，修 bug 请先 start_bugfix。完成后 Agent 应阅读 AGENTS.md。",
+        description: "生成/更新项目上下文写作计划（delegated）：MCP 写入 AGENTS.md 与 layout.json；project-context 分类文档与 graph-insights 由 Agent 按返回的 plan 落盘。新功能请先 start_feature，修 bug 请先 start_bugfix。",
         inputSchema: {
             type: "object",
             properties: {

package/build/tools/__tests__/add_feature.write.unit.test.js

@@ -15,8 +15,11 @@ describe("add_feature 不落盘", () => {
             });
             expect(result.isError).toBeFalsy();
             const structured = result.structuredContent;
+            expect(structured.summary).toBe("已生成功能规格写作计划：user-auth");
             expect(structured.pendingFiles).toHaveLength(3);
+            expect(structured.specPaths).toHaveLength(3);
             expect(structured.writtenFiles).toBeUndefined();
+            expect(result._meta?.note).toMatch(/不代写文件/);
             expect(fs.existsSync(path.join(projectRoot, "docs", "specs", "user-auth", "requirements.md"))).toBe(false);
             const text = String(result.content[0].text);
             expect(text).toMatch(/由 Agent 落盘/);

package/build/tools/__tests__/init_project.write.unit.test.js

@@ -13,6 +13,9 @@ describe("init_project 落盘边界", () => {
         });
         expect(result.isError).toBeFalsy();
         const structured = result.structuredContent;
+        expect(structured.summary).toBe("已生成项目初始化写作计划，请 Agent 按指南落盘 docs/specs/scripts/src");
+        expect(structured.nextSteps[0]).toContain("MCP 仅写入 Skill 与 AGENTS.md");
+        expect(structured.nextSteps[0]).toContain("Agent 须按指南手动落盘");
         expect(structured.writtenFiles.length).toBe(2);
         expect(structured.pendingFiles.length).toBeGreaterThan(0);
         expect(fs.existsSync(path.join(projectRoot, "AGENTS.md"))).toBe(true);

package/build/tools/__tests__/init_project_context.unit.test.js

@@ -25,6 +25,21 @@ describe("init_project_context 单元测试", () => {
         expect(fs.existsSync(path.join(projectRoot, "docs", "project-context", "tech-stack.md"))).toBe(false);
         const plan = structured.metadata?.plan;
         expect(plan?.mode).toBe("delegated");
+        expect(structured.summary).toMatch(/写作计划/);
+        expect(structured.summary).not.toMatch(/^生成 .*项目上下文/);
+        expect(structured.nextSteps?.[0]).toMatch(/不会自动生成完整/);
+        const legacyDoc = structured.documentation?.find((doc) => doc.path === "docs/project-context.md");
+        expect(legacyDoc).toMatchObject({
+            exists: false,
+            written: false,
+            agent_action_required: true,
+        });
+        const agentsDoc = structured.documentation?.find((doc) => doc.path === "AGENTS.md");
+        expect(agentsDoc).toMatchObject({
+            exists: true,
+            written: true,
+            agent_action_required: false,
+        });
         expect(plan.steps.map((step) => step.id)).toEqual([
             "write-modular-docs",
             "bootstrap-code-insight",
@@ -59,6 +74,19 @@ describe("init_project_context 单元测试", () => {
             "persist-graph-docs",
         ]);
         expect(structured.pendingFiles.every((f) => !f.path.startsWith("docs/project-context"))).toBe(true);
+        expect(structured.summary).toMatch(/保留现有分类文档/);
+        const legacyDoc = structured.documentation?.find((doc) => doc.path === "docs/project-context.md");
+        expect(legacyDoc).toMatchObject({
+            exists: true,
+            written: true,
+            agent_action_required: false,
+        });
+        const graphDoc = structured.documentation?.find((doc) => doc.path === "docs/graph-insights/latest.md");
+        expect(graphDoc).toMatchObject({
+            exists: false,
+            written: false,
+            agent_action_required: true,
+        });
         expect(fs.readFileSync(path.join(projectRoot, "docs", "project-context.md"), "utf8")).toBe("# existing context\n");
         expect(fs.existsSync(path.join(projectRoot, "AGENTS.md"))).toBe(true);
         const text = result.content[0].text;

package/build/tools/add_feature.js

@@ -296,7 +296,7 @@ ${fenceClose}
             reason: "由 Agent 根据本工具返回的模板写入",
         }));
         const structuredData = {
-            summary: `功能规格：${featureName}`,
+            summary: `已生成功能规格写作计划：${featureName}`,
             featureName,
             requirements: ["见 requirements.md 模板"],
             tasks: [{ id: "1", title: "按模板创建 specs 文档", description: "将下方模板落盘并补充真实内容" }],

package/build/tools/init_project.js

@@ -4,6 +4,7 @@ import { ensureMcpProbeKitBootstrap } from "../lib/workflow-skill-installer.js";
 import { MCP_PROBE_SKILL_REL_PATH } from "../lib/workflow-skill-template.js";
 import { resolveWorkspaceRootWithMeta } from "../lib/workspace-root.js";
 import { toPosixPath } from "../lib/project-context-layout.js";
+const AGENT_MANUAL_WRITE_NOTICE = "MCP 仅写入 Skill 与 AGENTS.md；Agent 须按指南手动落盘 pendingFiles 中的 docs、specs、scripts、src。";
 /**
  * init_project 工具
  *
@@ -226,7 +227,7 @@ ${warningBlock}
 MCP 已写入 Skill 与 AGENTS.md。请按上述步骤由 Agent 创建 docs、scripts、src 及 specs 文档。`;
         // 创建结构化数据对象
         const structuredData = {
-            summary: `初始化项目：${projectName}`,
+            summary: "已生成项目初始化写作计划，请 Agent 按指南落盘 docs/specs/scripts/src",
             projectName: projectName,
             projectRoot: toPosixPath(projectRoot),
             bootstrap: {
@@ -255,11 +256,12 @@ MCP 已写入 Skill 与 AGENTS.md。请按上述步骤由 Agent 创建 docs、sc
             writtenFiles: bootstrapWritten,
             pendingFiles,
             nextSteps: [
-                '确认 Skill 与 AGENTS.md 已落盘',
-                '按指南创建 docs/ 文档与 specs',
-                '创建 scripts/ 辅助脚本',
-                '创建 src/ 源代码目录',
-                '运行 init_project_context 生成完整上下文与图谱',
+                AGENT_MANUAL_WRITE_NOTICE,
+                "确认 Skill 与 AGENTS.md 已落盘",
+                "按指南创建 docs/ 文档与 specs",
+                "创建 scripts/ 辅助脚本",
+                "创建 src/ 源代码目录",
+                "运行 init_project_context 生成完整上下文与图谱",
             ]
         };
         return okStructured(message, structuredData, {

package/build/tools/init_project_context.js

@@ -9,9 +9,10 @@ import { generateAgentsMdInner } from "../lib/agents-md-template.js";
 import { ensureHarnessAdapters } from "../lib/harness-adapters.js";
 import { generateWorkflowSkillContent, MCP_PROBE_SKILL_REL_PATH } from "../lib/workflow-skill-template.js";
 import { getMcpProbeSkillVersion } from "../lib/workflow-skill-version.js";
-import { formatFileDeliverySection, writeProjectFile, } from "../lib/file-delivery.js";
+import { buildFileStatusEntries, formatFileDeliverySection, writeProjectFile, } from "../lib/file-delivery.js";
 import * as fs from "fs";
 import * as path from "path";
+const AGENT_MANUAL_WRITE_NOTICE = "本工具不会自动生成完整 project-context 与图谱内容，Agent 必须根据 metadata.plan 与 pendingFiles 手动写入这些文件。";
 /**
  * init_project_context 工具
  *
@@ -275,22 +276,43 @@ async function generateProjectContext(layout, projectRoot) {
         const header = renderOrchestrationHeader({
             tool: "init_project_context",
             goal: modularExists
-                ? "补齐图谱（保留现有分类文档；AGENTS.md 已由 MCP 写入）"
-                : "写入 AGENTS.md 与 layout，由 Agent 生成 project-context 与图谱",
+                ? "已生成 delegated 写作计划（保留现有分类文档；AGENTS.md 已由 MCP 写入）"
+                : "已生成 delegated 写作计划（AGENTS.md 与 layout 已由 MCP 写入）",
             tasks: modularExists
-                ? ["保留现有分类文档", "code_insight + Agent 落盘图谱"]
-                : ["MCP 已写 AGENTS.md 与 layout", "Agent 写分类文档", "code_insight + Agent 落盘图谱"],
+                ? ["保留现有分类文档", "Agent 按 plan 落盘图谱"]
+                : ["Agent 按 plan 落盘 project-context 分类文档", "code_insight + Agent 落盘图谱"],
             notes: [
                 `项目根目录: ${toPosixPath(resolvedRoot)}`,
                 `上下文目录: ${docsDir}`,
                 `索引: ${layout.indexPath}`,
                 `layout: ${manifestWritten}（已服务端写入）`,
+                AGENT_MANUAL_WRITE_NOTICE,
             ],
         });
+        const documentationDefs = [
+            { path: layout.indexPath, purpose: "Harness 入口（MCP 触发规则，省 token）" },
+            {
+                path: layout.legacyIndexPath,
+                purpose: "项目上下文索引（写代码前优先读，链到分类文档）",
+            },
+            ...docs.map((doc) => ({
+                path: `${layout.modularDir}/${doc.file}`,
+                purpose: doc.purpose,
+            })),
+            {
+                path: layout.latestMarkdownPath,
+                purpose: "最新代码图谱洞察（由 code_insight 维护）",
+            },
+            {
+                path: layout.latestJsonPath,
+                purpose: "最新代码图谱结构化结果（由 code_insight 维护）",
+            },
+            { path: layout.manifestPath, purpose: "layout manifest（工具链路径发现）" },
+        ];
         const structuredData = {
             summary: modularExists
-                ? `检测到现有项目上下文，补齐图谱与 ${layout.indexPath}`
-                : `生成 ${detection.category} 项目上下文与 ${layout.indexPath}`,
+                ? "已生成上下文写作计划（保留现有分类文档），请 Agent 按 plan 落盘图谱文件"
+                : "已生成上下文写作计划，请 Agent 按 plan 落盘文件",
             mode: "modular",
             projectOverview: {
                 name: projectInfo.name,
@@ -298,31 +320,16 @@ async function generateProjectContext(layout, projectRoot) {
                 techStack: detection.framework ? [detection.framework] : [],
                 architecture: detection.category,
             },
-            documentation: [
-                { path: layout.indexPath, purpose: "Harness 入口（MCP 触发规则，省 token）" },
-                {
-                    path: layout.legacyIndexPath,
-                    purpose: "项目上下文索引（写代码前优先读，链到分类文档）",
-                },
-                ...docs.map((doc) => ({
-                    path: `${layout.modularDir}/${doc.file}`,
-                    purpose: doc.purpose,
-                })),
-                {
-                    path: layout.latestMarkdownPath,
-                    purpose: "最新代码图谱洞察（由 code_insight 维护）",
-                },
-                {
-                    path: layout.latestJsonPath,
-                    purpose: "最新代码图谱结构化结果（由 code_insight 维护）",
-                },
-                { path: layout.manifestPath, purpose: "layout manifest（工具链路径发现）" },
-            ],
+            documentation: buildFileStatusEntries(projectRootAbs, documentationDefs, writtenFiles, pendingFiles).map((entry) => ({
+                ...entry,
+                purpose: entry.purpose ?? "",
+            })),
             nextSteps: [
+                AGENT_MANUAL_WRITE_NOTICE,
                 ...(modularExists
                     ? [`保留 ${layout.legacyIndexPath} 与分类文档`]
                     : [`由 Agent 按模板创建 ${layout.modularDir}/ 分类文档`]),
-                "调用 code_insight，由 Agent 落盘图谱",
+                "调用 code_insight，由 Agent 按 metadata.plan 落盘图谱",
                 `${layout.indexPath} 与 ${manifestWritten} 已由 MCP 写入（mergeMode: ${mergedAgents.mergeMode}）`,
             ],
             writtenFiles,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-probe-kit",
-  "version": "3.6.8",
+  "version": "3.6.9",
   "description": "AI-Powered Development Toolkit - MCP Server with 30 tools covering code quality, development efficiency, project management, and UI/UX design. Features: Structured Output, Workflow Orchestration, MCP Skill auto-sync, UI/UX Pro Max, and Requirements Interview.",
   "mcpName": "io.github.mybolide/mcp-probe-kit",
   "type": "module",