mcp-probe-kit 3.6.3 → 3.6.8

package/build/lib/harness-adapters.d.ts

@@ -0,0 +1,19 @@
+import { type HarnessAdapterKind, type HarnessDetectionResult, type LayoutHarnessManifest } from "./harness-skill-targets.js";
+export interface HarnessAdapterWriteResult {
+    id: string;
+    path: string;
+    kind: HarnessAdapterKind;
+    created: boolean;
+    updated: boolean;
+    skipped: boolean;
+}
+export interface HarnessAdapterEnsureResult {
+    detection: HarnessDetectionResult;
+    adapters: HarnessAdapterWriteResult[];
+    layoutHarness: LayoutHarnessManifest;
+}
+/**
+ * Write optional harness adapters. AGENTS.md and canonical Skill are unchanged.
+ * Canonical Skill must already exist at `.agents/skills/mcp-probe-kit/SKILL.md`.
+ */
+export declare function ensureHarnessAdapters(projectRoot: string, skillContent: string, agentsIndexPath?: string): HarnessAdapterEnsureResult;

package/build/lib/harness-adapters.js

@@ -0,0 +1,166 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { CANONICAL_SKILL_REL_PATH, detectHarnessContext, toLayoutHarnessManifest, } from "./harness-skill-targets.js";
+import { getMcpProbeSkillVersion } from "./workflow-skill-version.js";
+const RULES_POINTER_VERSION_KEY = "mcp-probe-kit-harness-adapter-version";
+const CLAUDE_BLOCK_BEGIN = "<!-- mcp-probe:harness begin — auto-generated; do not edit -->";
+const CLAUDE_BLOCK_END = "<!-- mcp-probe:harness end -->";
+function generateRulesPointerContent(skillCanonical, version, agentsIndexPath) {
+    return `# mcp-probe-kit MCP
+
+> ${RULES_POINTER_VERSION_KEY}: ${version}
+
+配置 **mcp-probe-kit** MCP 后，写代码 / 改文件前：
+
+1. 阅读项目根 \`${agentsIndexPath}\` 中 \`<!-- mcp-probe:context -->\` 块（MCP 触发规则）
+2. 需要完整工具表时阅读 \`${skillCanonical}\`
+
+**不要**跳过 MCP 直接改业务代码。拿不准先调 \`workflow\`。
+`;
+}
+function generateComateRulesContent(skillCanonical, version, agentsIndexPath) {
+    return `# mcp-probe-kit-mcp
+
+> ${RULES_POINTER_VERSION_KEY}: ${version}
+
+配置 mcp-probe-kit MCP 后，写代码前阅读 ${agentsIndexPath} 的 mcp-probe 块或 ${skillCanonical}。拿不准先调 workflow。
+`;
+}
+function generateClaudePointerBlock(skillCanonical, agentsPath) {
+    return `${CLAUDE_BLOCK_BEGIN}
+## MCP (mcp-probe-kit)
+
+Before coding, read the \`mcp-probe:context\` block in \`${agentsPath}\` or Skill \`${skillCanonical}\`.
+${CLAUDE_BLOCK_END}`;
+}
+function stripClaudeHarnessBlock(content) {
+    const beginIdx = content.indexOf(CLAUDE_BLOCK_BEGIN);
+    if (beginIdx === -1) {
+        return content.trim();
+    }
+    const endIdx = content.indexOf(CLAUDE_BLOCK_END);
+    if (endIdx === -1) {
+        return content.trim();
+    }
+    const before = content.slice(0, beginIdx).trimEnd();
+    const after = content.slice(endIdx + CLAUDE_BLOCK_END.length).trimStart();
+    return [before, after].filter(Boolean).join("\n\n").trim();
+}
+function mergeClaudePointer(existing, block) {
+    const userBody = existing ? stripClaudeHarnessBlock(existing) : "";
+    if (!userBody) {
+        return `${block}\n`;
+    }
+    return `${block}\n\n${userBody}\n`;
+}
+function adapterNeedsUpdate(existing, nextContent, kind, agentsIndexPath) {
+    if (!existing?.trim()) {
+        return true;
+    }
+    if (kind === "skill-mirror") {
+        return existing !== nextContent;
+    }
+    const version = getMcpProbeSkillVersion();
+    if (!existing.includes(RULES_POINTER_VERSION_KEY) || !existing.includes(version)) {
+        return true;
+    }
+    if (kind === "claude-pointer") {
+        return (!existing.includes(CANONICAL_SKILL_REL_PATH) ||
+            Boolean(agentsIndexPath && !existing.includes(agentsIndexPath)));
+    }
+    if (kind === "rules-pointer" && agentsIndexPath && !existing.includes(agentsIndexPath)) {
+        return true;
+    }
+    return existing !== nextContent;
+}
+function resolveAdapterContent(adapter, skillContent, agentsIndexPath) {
+    const version = getMcpProbeSkillVersion();
+    switch (adapter.kind) {
+        case "skill-mirror":
+            return skillContent;
+        case "rules-pointer":
+            return adapter.relPath.endsWith(".mdr")
+                ? generateComateRulesContent(CANONICAL_SKILL_REL_PATH, version, agentsIndexPath)
+                : generateRulesPointerContent(CANONICAL_SKILL_REL_PATH, version, agentsIndexPath);
+        case "claude-pointer":
+            return mergeClaudePointer(null, generateClaudePointerBlock(CANONICAL_SKILL_REL_PATH, agentsIndexPath));
+        default:
+            return skillContent;
+    }
+}
+function writeAdapterFile(projectRoot, adapter, content, agentsIndexPath) {
+    const absolute = path.join(projectRoot, adapter.relPath);
+    const existing = fs.existsSync(absolute) ? fs.readFileSync(absolute, "utf8") : null;
+    if (adapter.kind === "claude-pointer" && existing) {
+        const block = generateClaudePointerBlock(CANONICAL_SKILL_REL_PATH, agentsIndexPath);
+        const merged = mergeClaudePointer(existing, block);
+        if (!adapterNeedsUpdate(existing, merged, adapter.kind, agentsIndexPath)) {
+            return {
+                id: adapter.id,
+                path: adapter.relPath,
+                kind: adapter.kind,
+                created: false,
+                updated: false,
+                skipped: true,
+            };
+        }
+        fs.mkdirSync(path.dirname(absolute), { recursive: true });
+        fs.writeFileSync(absolute, merged, "utf8");
+        return {
+            id: adapter.id,
+            path: adapter.relPath,
+            kind: adapter.kind,
+            created: false,
+            updated: true,
+            skipped: false,
+        };
+    }
+    if (!adapterNeedsUpdate(existing, content, adapter.kind, agentsIndexPath)) {
+        return {
+            id: adapter.id,
+            path: adapter.relPath,
+            kind: adapter.kind,
+            created: false,
+            updated: false,
+            skipped: true,
+        };
+    }
+    fs.mkdirSync(path.dirname(absolute), { recursive: true });
+    fs.writeFileSync(absolute, content, "utf8");
+    const hadContent = Boolean(existing?.trim());
+    return {
+        id: adapter.id,
+        path: adapter.relPath,
+        kind: adapter.kind,
+        created: !hadContent,
+        updated: hadContent,
+        skipped: false,
+    };
+}
+function collectInstalledAdapterManifest(projectRoot, detection) {
+    return detection.adaptersToWrite
+        .filter((adapter) => fs.existsSync(path.join(projectRoot, adapter.relPath)))
+        .map((adapter) => ({
+        id: adapter.id,
+        kind: adapter.kind,
+        path: adapter.relPath,
+    }));
+}
+/**
+ * Write optional harness adapters. AGENTS.md and canonical Skill are unchanged.
+ * Canonical Skill must already exist at `.agents/skills/mcp-probe-kit/SKILL.md`.
+ */
+export function ensureHarnessAdapters(projectRoot, skillContent, agentsIndexPath = "AGENTS.md") {
+    const root = path.resolve(projectRoot);
+    const detection = detectHarnessContext(root);
+    const adapters = [];
+    for (const adapter of detection.adaptersToWrite) {
+        const content = resolveAdapterContent(adapter, skillContent, agentsIndexPath);
+        adapters.push(writeAdapterFile(root, adapter, content, agentsIndexPath));
+    }
+    return {
+        detection,
+        adapters,
+        layoutHarness: toLayoutHarnessManifest(detection, collectInstalledAdapterManifest(root, detection)),
+    };
+}

package/build/lib/harness-skill-targets.d.ts

@@ -0,0 +1,38 @@
+/** Canonical Skill path — never changes per harness */
+export declare const CANONICAL_SKILL_REL_PATH = ".agents/skills/mcp-probe-kit/SKILL.md";
+export type HarnessId = "agents" | "cursor" | "claude" | "codex" | "opencode" | "trae" | "traecli" | "codebuddy" | "lingma" | "comate";
+export type HarnessAdapterKind = "skill-mirror" | "rules-pointer" | "claude-pointer";
+export interface HarnessAdapterTarget {
+    id: string;
+    harnessId: HarnessId;
+    relPath: string;
+    kind: HarnessAdapterKind;
+    /** 项目内已有该目录时才写适配层（零配置） */
+    markerDir: string;
+}
+export interface HarnessDetectionResult {
+    markerHarnesses: HarnessId[];
+    detected: HarnessId[];
+    skillCanonical: string;
+    adaptersToWrite: HarnessAdapterTarget[];
+}
+export declare const HARNESS_ADAPTER_TARGETS: HarnessAdapterTarget[];
+/**
+ * 零配置 harness 检测：项目里已有工具目录（如 `.trae/`）则写对应薄适配。
+ * AGENTS.md 与 canonical Skill 路径始终不变。
+ */
+export declare function detectHarnessContext(projectRoot: string): HarnessDetectionResult;
+export interface LayoutHarnessManifest {
+    detected: HarnessId[];
+    skillCanonical: string;
+    adapters: Array<{
+        id: string;
+        kind: HarnessAdapterKind;
+        path: string;
+    }>;
+}
+export declare function toLayoutHarnessManifest(detection: HarnessDetectionResult, writtenAdapters: Array<{
+    id: string;
+    kind: HarnessAdapterKind;
+    path: string;
+}>): LayoutHarnessManifest;

package/build/lib/harness-skill-targets.js

@@ -0,0 +1,95 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { MCP_PROBE_SKILL_REL_PATH } from "./workflow-skill-template.js";
+/** Canonical Skill path — never changes per harness */
+export const CANONICAL_SKILL_REL_PATH = MCP_PROBE_SKILL_REL_PATH;
+export const HARNESS_ADAPTER_TARGETS = [
+    {
+        id: "trae-skill",
+        harnessId: "trae",
+        relPath: ".trae/skills/mcp-probe-kit/SKILL.md",
+        kind: "skill-mirror",
+        markerDir: ".trae",
+    },
+    {
+        id: "traecli-skill",
+        harnessId: "traecli",
+        relPath: ".traecli/skills/mcp-probe-kit/SKILL.md",
+        kind: "skill-mirror",
+        markerDir: ".traecli",
+    },
+    {
+        id: "codebuddy-skill",
+        harnessId: "codebuddy",
+        relPath: ".codebuddy/skills/mcp-probe-kit/SKILL.md",
+        kind: "skill-mirror",
+        markerDir: ".codebuddy",
+    },
+    {
+        id: "lingma-rules",
+        harnessId: "lingma",
+        relPath: ".lingma/rules/mcp-probe-kit-mcp.md",
+        kind: "rules-pointer",
+        markerDir: ".lingma",
+    },
+    {
+        id: "comate-rules",
+        harnessId: "comate",
+        relPath: ".comate/rules/mcp-probe-kit-mcp.mdr",
+        kind: "rules-pointer",
+        markerDir: ".comate",
+    },
+    {
+        id: "claude-pointer",
+        harnessId: "claude",
+        relPath: "CLAUDE.md",
+        kind: "claude-pointer",
+        markerDir: ".claude",
+    },
+];
+const MARKER_DIR_TO_HARNESS = {
+    ".trae": "trae",
+    ".traecli": "traecli",
+    ".codebuddy": "codebuddy",
+    ".lingma": "lingma",
+    ".comate": "comate",
+    ".cursor": "cursor",
+    ".claude": "claude",
+    ".codex": "codex",
+    ".opencode": "opencode",
+};
+function detectMarkerHarnesses(projectRoot) {
+    const found = [];
+    for (const [markerDir, harnessId] of Object.entries(MARKER_DIR_TO_HARNESS)) {
+        if (fs.existsSync(path.join(projectRoot, markerDir))) {
+            found.push(harnessId);
+        }
+    }
+    return found;
+}
+function shouldWriteAdapter(projectRoot, adapter) {
+    return fs.existsSync(path.join(projectRoot, adapter.markerDir));
+}
+/**
+ * 零配置 harness 检测：项目里已有工具目录（如 `.trae/`）则写对应薄适配。
+ * AGENTS.md 与 canonical Skill 路径始终不变。
+ */
+export function detectHarnessContext(projectRoot) {
+    const root = path.resolve(projectRoot);
+    const markerHarnesses = detectMarkerHarnesses(root);
+    const detected = markerHarnesses.length > 0 ? markerHarnesses : ["agents"];
+    const adaptersToWrite = HARNESS_ADAPTER_TARGETS.filter((adapter) => shouldWriteAdapter(root, adapter));
+    return {
+        markerHarnesses,
+        detected,
+        skillCanonical: CANONICAL_SKILL_REL_PATH,
+        adaptersToWrite,
+    };
+}
+export function toLayoutHarnessManifest(detection, writtenAdapters) {
+    return {
+        detected: detection.detected,
+        skillCanonical: detection.skillCanonical,
+        adapters: writtenAdapters,
+    };
+}

package/build/lib/init-project-writer.d.ts

@@ -0,0 +1,7 @@
+import { type FileDeliveryReport } from "./file-delivery.js";
+export declare function writeInitProjectSkeletons(input: {
+    projectRoot: string;
+    projectName: string;
+    featureSlug: string;
+    requirement: string;
+}): FileDeliveryReport;

package/build/lib/init-project-writer.js

@@ -0,0 +1,161 @@
+import { mergeDeliveryReports, writeProjectFile, } from "./file-delivery.js";
+export function writeInitProjectSkeletons(input) {
+    const { projectRoot, projectName, featureSlug, requirement } = input;
+    const specBase = `docs/specs/${featureSlug}`;
+    const projectContext = `# ${projectName} - 项目上下文
+
+> 由 init_project 自动生成的骨架，请根据仓库实际情况补充。
+
+## 项目概览
+
+| 属性 | 值 |
+|------|-----|
+| 项目名称 | ${projectName} |
+| 描述 | ${requirement || "待补充"} |
+
+## 技术栈
+
+- 待补充
+
+## 架构
+
+- 待补充
+
+## 开发流程
+
+- 待补充
+
+---
+*生成工具: mcp-probe-kit init_project*
+`;
+    const constitution = `# ${projectName} - 项目宪法
+
+> 定义项目核心原则与约束。
+
+## 代码风格
+
+- 待补充
+
+## 架构原则
+
+- 待补充
+
+## 安全准则
+
+- 待补充
+
+## 测试要求
+
+- 待补充
+
+## 文档标准
+
+- 待补充
+
+---
+*生成工具: mcp-probe-kit init_project*
+`;
+    const requirements = `# 需求文档：${projectName}
+
+## 功能概述
+
+${requirement || "待补充"}
+
+## 术语定义
+
+- 待补充
+
+## 需求列表（EARS）
+
+### 用户故事
+
+- As a ... I want ... So that ...
+
+### 验收标准
+
+- WHEN ... THEN THE system SHALL ...
+
+## 非功能需求
+
+- 性能、安全、兼容性：待补充
+
+---
+*生成工具: mcp-probe-kit init_project*
+`;
+    const design = `# 设计文档：${projectName}
+
+## 技术方案
+
+- 待补充
+
+## 架构设计
+
+- 待补充
+
+## 数据模型
+
+- 待补充
+
+## API 设计
+
+- 待补充
+
+---
+*生成工具: mcp-probe-kit init_project*
+`;
+    const tasks = `# 任务清单：${projectName}
+
+## 概述
+
+实现 ${projectName} 的任务分解。
+
+## 任务列表
+
+### 阶段 1: 项目初始化
+
+- [ ] 1.1 搭建项目骨架
+
+### 阶段 2: 核心功能
+
+- [ ] 2.1 实现核心逻辑
+
+### 阶段 3: 测试
+
+- [ ] 3.1 编写测试
+
+---
+*生成工具: mcp-probe-kit init_project*
+`;
+    const research = `# 技术调研：${projectName}
+
+## 技术栈调研
+
+- 待补充
+
+## 版本兼容性
+
+- 待补充
+
+## 风险与最佳实践
+
+- 待补充
+
+---
+*生成工具: mcp-probe-kit init_project*
+`;
+    return mergeDeliveryReports({
+        writtenFiles: [
+            writeProjectFile(projectRoot, "docs/project-context.md", projectContext, "ifMissing"),
+            writeProjectFile(projectRoot, "docs/constitution.md", constitution, "ifMissing"),
+            writeProjectFile(projectRoot, `${specBase}/requirements.md`, requirements, "ifMissing"),
+            writeProjectFile(projectRoot, `${specBase}/design.md`, design, "ifMissing"),
+            writeProjectFile(projectRoot, `${specBase}/tasks.md`, tasks, "ifMissing"),
+            writeProjectFile(projectRoot, `${specBase}/research.md`, research, "ifMissing"),
+        ],
+        pendingFiles: [
+            { path: "scripts/check-prerequisites.sh", reason: "需 Agent 按指南创建辅助脚本" },
+            { path: "scripts/setup.sh", reason: "需 Agent 按指南创建辅助脚本" },
+            { path: "src/", reason: "源代码目录需按项目类型创建" },
+        ],
+    });
+}

package/build/lib/project-context-layout.d.ts

@@ -32,6 +32,15 @@ export interface ProjectContextLayoutArgs {
 }
 /** Primary env key recorded in layout.json (optional local override via projectRoot) */
 export declare const LAYOUT_PROJECT_ROOT_ENV = "MCP_PROJECT_ROOT";
+export interface LayoutManifestHarnessV1 {
+    detected: string[];
+    skillCanonical: string;
+    adapters: Array<{
+        id: string;
+        kind: string;
+        path: string;
+    }>;
+}
 export interface LayoutManifestV1 {
     version: 1;
     /** Ignored if present in old files — project root is always inferred from manifest path */
@@ -45,6 +54,8 @@ export interface LayoutManifestV1 {
     indexStyle: "agents" | "legacy";
     generatedBy: string;
     generatedAt: string;
+    /** Harness detection snapshot (AGENTS.md + canonical Skill stay harness-agnostic) */
+    harness?: LayoutManifestHarnessV1;
 }
 export declare function toPosixPath(value: string): string;
 export declare function relativeLink(fromRel: string, toRel: string): string;
@@ -66,8 +77,10 @@ export declare function manifestPathRelativeToProject(projectRoot: string, absol
 export declare function layoutAbsPath(layout: ProjectContextLayout, relativePath: string): string;
 type ProjectContextLayoutCore = Omit<ProjectContextLayout, "projectRoot" | "projectRootPosix">;
 export declare function attachProjectRoot(layout: ProjectContextLayoutCore, projectRoot: string): ProjectContextLayout;
-export declare function buildLayoutManifest(layout: ProjectContextLayout): LayoutManifestV1;
-export declare function writeLayoutManifest(projectRoot: string, layout: ProjectContextLayout): string;
+export declare function buildLayoutManifest(layout: ProjectContextLayout, harness?: LayoutManifestHarnessV1): LayoutManifestV1;
+export declare function writeLayoutManifest(projectRoot: string, layout: ProjectContextLayout, harness?: LayoutManifestHarnessV1): string;
+/** Patch harness section on an existing layout.json (e.g. after bootstrap adapters). */
+export declare function patchLayoutManifestHarness(projectRoot: string, harness: LayoutManifestHarnessV1): string | null;
 export declare function layoutFromManifest(manifest: LayoutManifestV1, fallbackProjectRoot: string, manifestFilePath?: string): ProjectContextLayout;
 export declare function resolveProjectContextLayout(projectRoot: string, args?: ProjectContextLayoutArgs): ProjectContextLayout;
 export declare function countCjkChars(text: string): number;

package/build/lib/project-context-layout.js

@@ -196,7 +196,7 @@ export function attachProjectRoot(layout, projectRoot) {
         projectRootPosix: projectRootToManifestValue(resolved),
     };
 }
-export function buildLayoutManifest(layout) {
+export function buildLayoutManifest(layout, harness) {
     return {
         version: 1,
         projectRootEnv: LAYOUT_PROJECT_ROOT_ENV,
@@ -207,17 +207,41 @@ export function buildLayoutManifest(layout) {
         indexStyle: layout.indexStyle,
         generatedBy: "init_project_context",
         generatedAt: new Date().toISOString(),
+        ...(harness ? { harness } : {}),
     };
 }
-export function writeLayoutManifest(projectRoot, layout) {
+export function writeLayoutManifest(projectRoot, layout, harness) {
     const resolvedRoot = path.resolve(projectRoot);
     const manifestRel = layoutManifestRel(layout.contextRoot);
-    const manifest = buildLayoutManifest(attachProjectRoot(layout, resolvedRoot));
+    const manifest = buildLayoutManifest(attachProjectRoot(layout, resolvedRoot), harness);
     const absoluteManifest = path.join(resolvedRoot, ...manifestRel.split("/"));
     fs.mkdirSync(path.dirname(absoluteManifest), { recursive: true });
     fs.writeFileSync(absoluteManifest, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
     return manifestRel;
 }
+function layoutHarnessEquals(left, right) {
+    return JSON.stringify(left ?? null) === JSON.stringify(right);
+}
+/** Patch harness section on an existing layout.json (e.g. after bootstrap adapters). */
+export function patchLayoutManifestHarness(projectRoot, harness) {
+    const resolvedRoot = path.resolve(projectRoot);
+    const existing = readLayoutManifest(resolvedRoot);
+    if (!existing) {
+        return null;
+    }
+    if (layoutHarnessEquals(existing.harness, harness)) {
+        return null;
+    }
+    const layout = layoutFromManifest(existing, resolvedRoot);
+    const manifestRel = layout.manifestPath;
+    const absoluteManifest = path.join(resolvedRoot, ...manifestRel.split("/"));
+    const updated = {
+        ...existing,
+        harness,
+    };
+    fs.writeFileSync(absoluteManifest, `${JSON.stringify(updated, null, 2)}\n`, "utf8");
+    return manifestRel;
+}
 export function layoutFromManifest(manifest, fallbackProjectRoot, manifestFilePath) {
     const contextRoot = normalizeRelativePath(manifest.contextRoot);
     const projectRoot = resolveManifestProjectRoot(manifest, fallbackProjectRoot, manifestFilePath);

package/build/lib/project-context-writer.d.ts

@@ -0,0 +1,41 @@
+import type { ProjectContextLayout } from "./project-context-layout.js";
+export interface WrittenFileRecord {
+    path: string;
+    action: "created" | "updated" | "skipped";
+}
+export interface ProjectContextWriteResult {
+    agentsMd: WrittenFileRecord;
+    projectContextIndex: WrittenFileRecord | null;
+    modularDocs: WrittenFileRecord[];
+}
+type DocEntry = {
+    file: string;
+    title: string;
+    purpose: string;
+};
+type ProjectInfo = {
+    name: string;
+    version: string;
+    description: string;
+};
+type Detection = {
+    language: string;
+    framework?: string;
+    category: string;
+    confidence?: number;
+};
+export declare function buildProjectContextIndexMarkdown(projectInfo: ProjectInfo, detection: Detection, docs: DocEntry[], docsDir: string): string;
+export declare function buildModularDocSkeleton(doc: DocEntry, projectInfo: ProjectInfo, detection: Detection): string;
+/**
+ * 由 init_project_context 服务端直接落盘（勿依赖 Agent fsWrite）。
+ */
+export declare function writeProjectContextArtifacts(input: {
+    layout: ProjectContextLayout;
+    mergedAgentsContent: string;
+    skipModularDocs: boolean;
+    projectInfo: ProjectInfo;
+    detection: Detection;
+    docs: DocEntry[];
+}): ProjectContextWriteResult;
+export declare function formatWriteSummary(result: ProjectContextWriteResult): string;
+export {};