mcp-probe-kit 3.0.18 → 3.0.19

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

@@ -0,0 +1,78 @@
+export declare const DEFAULT_CONTEXT_ROOT = "docs";
+export declare const DEFAULT_INDEX_PATH = "AGENTS.md";
+/** Relative path to layout manifest under a given context root */
+export declare function layoutManifestRel(contextRoot?: string): string;
+/** Default manifest location when contextRoot is `docs` */
+export declare const LAYOUT_MANIFEST_REL: string;
+export type IndexStyle = "auto" | "agents" | "legacy";
+export type LayoutSource = "args" | "manifest" | "detect" | "default";
+export type DocumentLocale = "en" | "zh-CN";
+export interface ProjectContextLayout {
+    /** Absolute project root (platform path) */
+    projectRoot: string;
+    /** Absolute project root (POSIX, stored in layout.json) */
+    projectRootPosix: string;
+    indexPath: string;
+    contextRoot: string;
+    modularDir: string;
+    graphDir: string;
+    latestMarkdownPath: string;
+    latestJsonPath: string;
+    manifestPath: string;
+    indexStyle: "agents" | "legacy";
+    source: LayoutSource;
+    legacyIndexPath: string;
+}
+export interface ProjectContextLayoutArgs {
+    docs_dir?: string;
+    output?: string;
+    output_dir?: string;
+    filename?: string;
+    index_style?: IndexStyle;
+}
+/** Primary env key recorded in layout.json (optional local override via projectRoot) */
+export declare const LAYOUT_PROJECT_ROOT_ENV = "MCP_PROJECT_ROOT";
+export interface LayoutManifestV1 {
+    version: 1;
+    /** Ignored if present in old files — project root is always inferred from manifest path */
+    projectRoot?: string;
+    /** Env fallback when manifest path cannot be resolved (default MCP_PROJECT_ROOT) */
+    projectRootEnv?: string;
+    indexPath: string;
+    contextRoot: string;
+    modularDir: string;
+    graphDir: string;
+    indexStyle: "agents" | "legacy";
+    generatedBy: string;
+    generatedAt: string;
+}
+export declare function toPosixPath(value: string): string;
+export declare function relativeLink(fromRel: string, toRel: string): string;
+export declare function assertPathInsideProject(projectRoot: string, relativePath: string): void;
+export declare function projectRootToManifestValue(projectRoot: string): string;
+/**
+ * Resolve project root: infer from manifest file path → env → fallback (never reads manifest.projectRoot).
+ */
+export declare function resolveManifestProjectRoot(manifest: LayoutManifestV1, fallbackProjectRoot: string, manifestFilePath?: string): string;
+/**
+ * `{projectRoot}/{contextRoot}/.mcp-probe/layout.json` → walk up from manifest file to project root.
+ */
+export declare function inferProjectRootFromManifestPath(manifestFilePath: string, contextRoot?: string): string;
+export declare function findLayoutManifestPath(startDir: string): string | null;
+export declare function discoverProjectRootFromLayout(startDir: string): string | null;
+export declare function readLayoutManifestFromPath(manifestFilePath: string): LayoutManifestV1 | null;
+export declare function readLayoutManifest(projectRoot: string): LayoutManifestV1 | null;
+export declare function manifestPathRelativeToProject(projectRoot: string, absoluteManifestPath: string): string;
+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 layoutFromManifest(manifest: LayoutManifestV1, fallbackProjectRoot: string, manifestFilePath?: string): ProjectContextLayout;
+export declare function resolveProjectContextLayout(projectRoot: string, args?: ProjectContextLayoutArgs): ProjectContextLayout;
+export declare function countCjkChars(text: string): number;
+export declare function detectDocumentLocale(projectRoot: string, existingAgentsContent?: string): DocumentLocale;
+export declare function legacyProjectContextExists(projectRoot: string, layout: ProjectContextLayout): boolean;
+export declare function agentsMdExists(projectRoot: string, layout: ProjectContextLayout): boolean;
+export declare function parseLayoutArgsFromRecord(args: Record<string, unknown>): ProjectContextLayoutArgs;
+export {};

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

@@ -0,0 +1,350 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const DEFAULT_CONTEXT_ROOT = "docs";
+export const DEFAULT_INDEX_PATH = "AGENTS.md";
+/** Relative path to layout manifest under a given context root */
+export function layoutManifestRel(contextRoot = DEFAULT_CONTEXT_ROOT) {
+    return joinRel(normalizeRelativePath(contextRoot), ".mcp-probe/layout.json");
+}
+/** Default manifest location when contextRoot is `docs` */
+export const LAYOUT_MANIFEST_REL = layoutManifestRel(DEFAULT_CONTEXT_ROOT);
+const MANIFEST_SCAN_SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "coverage"]);
+/** Primary env key recorded in layout.json (optional local override via projectRoot) */
+export const LAYOUT_PROJECT_ROOT_ENV = "MCP_PROJECT_ROOT";
+const LAYOUT_PROJECT_ROOT_ENV_FALLBACKS = [
+    LAYOUT_PROJECT_ROOT_ENV,
+    "MCP_WORKSPACE_ROOT",
+    "CURSOR_WORKSPACE_ROOT",
+    "WORKSPACE_ROOT",
+    "PROJECT_ROOT",
+];
+export function toPosixPath(value) {
+    return value.replace(/\\/g, "/");
+}
+export function relativeLink(fromRel, toRel) {
+    const fromDir = path.posix.dirname(toPosixPath(fromRel).replace(/^\.\//, "") || ".");
+    const toPath = toPosixPath(toRel).replace(/^\.\//, "");
+    let rel = path.posix.relative(fromDir, toPath);
+    if (!rel || rel === ".") {
+        return toPath;
+    }
+    if (!rel.startsWith(".")) {
+        rel = `./${rel}`;
+    }
+    return rel;
+}
+function normalizeRelativePath(raw) {
+    const cleaned = toPosixPath(raw.trim()).replace(/^\/+/, "").replace(/\/+$/, "");
+    if (!cleaned || cleaned === ".") {
+        return cleaned || ".";
+    }
+    if (cleaned.split("/").includes("..")) {
+        throw new Error(`路径不允许包含 '..': ${raw}`);
+    }
+    return cleaned;
+}
+function joinRel(...segments) {
+    return normalizeRelativePath(path.posix.join(...segments.filter(Boolean)));
+}
+function isExistingDirectory(target) {
+    try {
+        return fs.existsSync(target) && fs.statSync(target).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function assertPathInsideProject(projectRoot, relativePath) {
+    const resolved = path.resolve(projectRoot, relativePath);
+    const root = path.resolve(projectRoot);
+    const relative = path.relative(root, resolved);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error(`路径必须在项目根目录内: ${relativePath}`);
+    }
+}
+function fileExists(projectRoot, relativePath) {
+    return fs.existsSync(path.join(projectRoot, relativePath));
+}
+export function projectRootToManifestValue(projectRoot) {
+    return toPosixPath(path.resolve(projectRoot));
+}
+function resolveProjectRootFromEnv(envKey) {
+    const keys = envKey?.trim()
+        ? [envKey.trim(), ...LAYOUT_PROJECT_ROOT_ENV_FALLBACKS]
+        : [...LAYOUT_PROJECT_ROOT_ENV_FALLBACKS];
+    const seen = new Set();
+    for (const key of keys) {
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        const raw = process.env[key]?.trim();
+        if (!raw) {
+            continue;
+        }
+        const resolved = path.resolve(raw.replace(/\//g, path.sep));
+        if (isExistingDirectory(resolved)) {
+            return resolved;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve project root: infer from manifest file path → env → fallback (never reads manifest.projectRoot).
+ */
+export function resolveManifestProjectRoot(manifest, fallbackProjectRoot, manifestFilePath) {
+    if (manifestFilePath) {
+        const inferred = inferProjectRootFromManifestPath(manifestFilePath, manifest.contextRoot);
+        if (isExistingDirectory(inferred)) {
+            return inferred;
+        }
+    }
+    const fromEnv = resolveProjectRootFromEnv(manifest.projectRootEnv);
+    if (fromEnv) {
+        return fromEnv;
+    }
+    return path.resolve(fallbackProjectRoot);
+}
+/**
+ * `{projectRoot}/{contextRoot}/.mcp-probe/layout.json` → walk up from manifest file to project root.
+ */
+export function inferProjectRootFromManifestPath(manifestFilePath, contextRoot = DEFAULT_CONTEXT_ROOT) {
+    let dir = path.dirname(path.resolve(manifestFilePath));
+    const segments = layoutManifestRel(contextRoot).split("/").filter(Boolean);
+    for (let i = 1; i < segments.length; i++) {
+        dir = path.dirname(dir);
+    }
+    return dir;
+}
+function findLayoutManifestInTree(dir) {
+    const defaultCandidate = path.join(dir, LAYOUT_MANIFEST_REL);
+    if (fs.existsSync(defaultCandidate)) {
+        return defaultCandidate;
+    }
+    try {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (!entry.isDirectory() || MANIFEST_SCAN_SKIP_DIRS.has(entry.name)) {
+                continue;
+            }
+            const candidate = path.join(dir, entry.name, ".mcp-probe", "layout.json");
+            if (fs.existsSync(candidate)) {
+                return candidate;
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+export function findLayoutManifestPath(startDir) {
+    let current = path.resolve(startDir);
+    while (true) {
+        const found = findLayoutManifestInTree(current);
+        if (found) {
+            return found;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+export function discoverProjectRootFromLayout(startDir) {
+    const manifestPath = findLayoutManifestPath(startDir);
+    if (!manifestPath) {
+        return null;
+    }
+    const manifest = readLayoutManifestFromPath(manifestPath);
+    if (!manifest) {
+        return inferProjectRootFromManifestPath(manifestPath);
+    }
+    return resolveManifestProjectRoot(manifest, startDir, manifestPath);
+}
+export function readLayoutManifestFromPath(manifestFilePath) {
+    if (!fs.existsSync(manifestFilePath)) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(fs.readFileSync(manifestFilePath, "utf8"));
+        if (parsed?.version !== 1) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function readLayoutManifest(projectRoot) {
+    const manifestPath = findLayoutManifestPath(projectRoot);
+    return manifestPath ? readLayoutManifestFromPath(manifestPath) : null;
+}
+export function manifestPathRelativeToProject(projectRoot, absoluteManifestPath) {
+    const rel = path.relative(path.resolve(projectRoot), path.resolve(absoluteManifestPath));
+    return toPosixPath(rel);
+}
+export function layoutAbsPath(layout, relativePath) {
+    return path.join(layout.projectRoot, normalizeRelativePath(relativePath));
+}
+export function attachProjectRoot(layout, projectRoot) {
+    const resolved = path.resolve(projectRoot);
+    return {
+        ...layout,
+        projectRoot: resolved,
+        projectRootPosix: projectRootToManifestValue(resolved),
+    };
+}
+export function buildLayoutManifest(layout) {
+    return {
+        version: 1,
+        projectRootEnv: LAYOUT_PROJECT_ROOT_ENV,
+        indexPath: layout.indexPath,
+        contextRoot: layout.contextRoot,
+        modularDir: layout.modularDir,
+        graphDir: layout.graphDir,
+        indexStyle: layout.indexStyle,
+        generatedBy: "init_project_context",
+        generatedAt: new Date().toISOString(),
+    };
+}
+export function writeLayoutManifest(projectRoot, layout) {
+    const resolvedRoot = path.resolve(projectRoot);
+    const manifestRel = layoutManifestRel(layout.contextRoot);
+    const manifest = buildLayoutManifest(attachProjectRoot(layout, resolvedRoot));
+    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;
+}
+export function layoutFromManifest(manifest, fallbackProjectRoot, manifestFilePath) {
+    const contextRoot = normalizeRelativePath(manifest.contextRoot);
+    const projectRoot = resolveManifestProjectRoot(manifest, fallbackProjectRoot, manifestFilePath);
+    const graphDir = normalizeRelativePath(manifest.graphDir);
+    const manifestRel = manifestFilePath
+        ? manifestPathRelativeToProject(projectRoot, manifestFilePath)
+        : layoutManifestRel(contextRoot);
+    return attachProjectRoot({
+        indexPath: normalizeRelativePath(manifest.indexPath),
+        contextRoot,
+        modularDir: normalizeRelativePath(manifest.modularDir),
+        graphDir,
+        latestMarkdownPath: joinRel(graphDir, "latest.md"),
+        latestJsonPath: joinRel(graphDir, "latest.json"),
+        manifestPath: manifestRel,
+        indexStyle: manifest.indexStyle,
+        source: "manifest",
+        legacyIndexPath: joinRel(contextRoot, "project-context.md"),
+    }, projectRoot);
+}
+function buildLayoutFromParts(projectRoot, contextRoot, indexPath, indexStyle, source) {
+    const modularDir = joinRel(contextRoot, "project-context");
+    const graphDir = joinRel(contextRoot, "graph-insights");
+    return attachProjectRoot({
+        indexPath,
+        contextRoot,
+        modularDir,
+        graphDir,
+        latestMarkdownPath: joinRel(graphDir, "latest.md"),
+        latestJsonPath: joinRel(graphDir, "latest.json"),
+        manifestPath: layoutManifestRel(contextRoot),
+        indexStyle,
+        source,
+        legacyIndexPath: joinRel(contextRoot, "project-context.md"),
+    }, projectRoot);
+}
+export function resolveProjectContextLayout(projectRoot, args = {}) {
+    const startRoot = path.resolve(projectRoot);
+    const hasExplicitArgs = Boolean(args.docs_dir?.trim() ||
+        args.output?.trim() ||
+        args.output_dir?.trim() ||
+        args.filename?.trim() ||
+        args.index_style);
+    const manifestPath = findLayoutManifestPath(startRoot);
+    const manifest = manifestPath ? readLayoutManifestFromPath(manifestPath) : readLayoutManifest(startRoot);
+    let canonicalRoot = startRoot;
+    if (!hasExplicitArgs && manifest) {
+        canonicalRoot = resolveManifestProjectRoot(manifest, startRoot, manifestPath ?? undefined);
+    }
+    if (!hasExplicitArgs && manifest) {
+        const fromManifest = layoutFromManifest(manifest, canonicalRoot, manifestPath ?? undefined);
+        assertPathInsideProject(fromManifest.projectRoot, fromManifest.indexPath);
+        assertPathInsideProject(fromManifest.projectRoot, fromManifest.contextRoot);
+        return fromManifest;
+    }
+    const contextRoot = normalizeRelativePath(args.docs_dir?.trim() || DEFAULT_CONTEXT_ROOT);
+    let indexPath;
+    let indexStyle;
+    if (args.output?.trim()) {
+        indexPath = normalizeRelativePath(args.output.trim());
+        indexStyle = indexPath.endsWith("AGENTS.md") ? "agents" : "legacy";
+    }
+    else if (args.output_dir?.trim()) {
+        indexPath = joinRel(args.output_dir.trim(), args.filename?.trim() || "project-context.md");
+        indexStyle = "legacy";
+    }
+    else if (args.index_style === "legacy") {
+        indexPath = joinRel(contextRoot, "project-context.md");
+        indexStyle = "legacy";
+    }
+    else if (args.index_style === "agents") {
+        indexPath = DEFAULT_INDEX_PATH;
+        indexStyle = "agents";
+    }
+    else {
+        indexPath = DEFAULT_INDEX_PATH;
+        indexStyle = "agents";
+    }
+    const layout = buildLayoutFromParts(canonicalRoot, contextRoot, indexPath, indexStyle, hasExplicitArgs ? "args" : manifest ? "manifest" : "default");
+    assertPathInsideProject(layout.projectRoot, layout.indexPath);
+    assertPathInsideProject(layout.projectRoot, layout.contextRoot);
+    assertPathInsideProject(layout.projectRoot, layout.modularDir);
+    assertPathInsideProject(layout.projectRoot, layout.graphDir);
+    return layout;
+}
+export function countCjkChars(text) {
+    return (text.match(/[\u4e00-\u9fff\u3400-\u4dbf]/g) || []).length;
+}
+export function detectDocumentLocale(projectRoot, existingAgentsContent) {
+    if (existingAgentsContent) {
+        const begin = existingAgentsContent.indexOf("<!-- mcp-probe:context begin");
+        const end = existingAgentsContent.indexOf("<!-- mcp-probe:context end -->");
+        if (begin !== -1 && end > begin) {
+            const block = existingAgentsContent.slice(begin, end);
+            if (countCjkChars(block) >= 8) {
+                return "zh-CN";
+            }
+        }
+    }
+    const readmePath = path.join(projectRoot, "README.md");
+    if (fs.existsSync(readmePath)) {
+        const sample = fs.readFileSync(readmePath, "utf8").slice(0, 4000);
+        const cjk = countCjkChars(sample);
+        const letters = (sample.match(/[a-zA-Z]/g) || []).length;
+        if (cjk >= 20 && cjk / Math.max(letters, 1) > 0.12) {
+            return "zh-CN";
+        }
+    }
+    if (fs.existsSync(path.join(projectRoot, "i18n", "README.zh-CN.md"))) {
+        return "zh-CN";
+    }
+    return "en";
+}
+export function legacyProjectContextExists(projectRoot, layout) {
+    return fileExists(layout.projectRoot, layout.legacyIndexPath);
+}
+export function agentsMdExists(projectRoot, layout) {
+    return fileExists(layout.projectRoot, layout.indexPath);
+}
+export function parseLayoutArgsFromRecord(args) {
+    return {
+        docs_dir: typeof args.docs_dir === "string" ? args.docs_dir : undefined,
+        output: typeof args.output === "string" ? args.output : undefined,
+        output_dir: typeof args.output_dir === "string" ? args.output_dir : undefined,
+        filename: typeof args.filename === "string" ? args.filename : undefined,
+        index_style: args.index_style === "auto" || args.index_style === "agents" || args.index_style === "legacy"
+            ? args.index_style
+            : undefined,
+    };
+}

package/build/lib/workspace-root.js

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
+import { discoverProjectRootFromLayout } from "./project-context-layout.js";
 const WORKSPACE_ENV_KEYS = [
     "MCP_PROJECT_ROOT",
     "MCP_WORKSPACE_ROOT",
@@ -131,10 +132,14 @@ export function buildProjectRootRetryHint(inputPath) {
 export function resolveWorkspaceRoot(explicitProjectRoot) {
     const explicit = safeResolve(explicitProjectRoot || "");
     if (isExistingDirectory(explicit)) {
-        return explicit;
+        return discoverProjectRootFromLayout(explicit) ?? explicit;
     }
     const packageRoot = getRuntimePackageRoot();
     const cwd = safeResolve(process.cwd()) || packageRoot;
+    const fromLayout = discoverProjectRootFromLayout(cwd);
+    if (fromLayout) {
+        return fromLayout;
+    }
     for (const key of WORKSPACE_ENV_KEYS) {
         const candidate = safeResolve(process.env[key] || "");
         const resolved = findWorkspaceAncestor(candidate, packageRoot);

package/build/resources/ui-ux-data/metadata.json

@@ -1,6 +1,6 @@
 {
   "version": "2.2.3",
-  "syncedAt": "2026-05-20T09:05:15.322Z",
+  "syncedAt": "2026-05-26T08:30:56.969Z",
   "source": "uipro-cli",
   "format": "json"
 }

package/build/schemas/index.d.ts

@@ -195,13 +195,35 @@ export declare const allToolSchemas: ({
     };
 } | {
     readonly name: "init_project_context";
-    readonly description: "当用户需要生成项目上下文文档、帮助团队快速上手时使用。生成项目上下文文档（技术栈/架构/编码规范），供后续开发参考";
+    readonly description: "生成/更新项目上下文：默认写入 AGENTS.md（含 MCP 与 GitNexus 触发规则）及 docs/project-context/。新功能请先 start_feature，修 bug 请先 start_bugfix。完成后 Agent 应阅读 AGENTS.md。";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {
             readonly docs_dir: {
                 readonly type: "string";
-                readonly description: "文档目录。可选，默认 docs";
+                readonly description: "附属文档根目录（project-context、graph-insights）。默认 docs";
+            };
+            readonly index_style: {
+                readonly type: "string";
+                readonly enum: readonly ["auto", "agents", "legacy"];
+                readonly description: "索引风格：auto（默认 AGENTS.md）、agents、legacy（docs/project-context.md）";
+            };
+            readonly output: {
+                readonly type: "string";
+                readonly description: "高级：索引文件相对路径，如 AGENTS.md";
+            };
+            readonly output_dir: {
+                readonly type: "string";
+                readonly description: "高级：索引所在目录，如 .claude/rules";
+            };
+            readonly filename: {
+                readonly type: "string";
+                readonly description: "高级：与 output_dir 合用，默认 project-context.md";
+            };
+            readonly locale: {
+                readonly type: "string";
+                readonly enum: readonly ["en", "zh-CN"];
+                readonly description: "AGENTS.md 语言；默认根据 README 探测";
             };
         };
         readonly required: readonly [];
@@ -682,7 +704,7 @@ export declare const allToolSchemas: ({
     };
 } | {
     readonly name: "memorize_asset";
-    readonly description: "当 AI 完成开发并确认存在可复用代码、模式或规范时使用。将高价值资产沉淀到记忆系统。";
+    readonly description: "沉淀可检索资产到记忆系统：可复用代码/模式；Bug 修复后必须写入 type=bugfix（现象、根因、改法、tags 含 bugfix）。";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {

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

@@ -14,7 +14,7 @@ export declare const memoryToolSchemas: readonly [{
     };
 }, {
     readonly name: "memorize_asset";
-    readonly description: "当 AI 完成开发并确认存在可复用代码、模式或规范时使用。将高价值资产沉淀到记忆系统。";
+    readonly description: "沉淀可检索资产到记忆系统：可复用代码/模式；Bug 修复后必须写入 type=bugfix（现象、根因、改法、tags 含 bugfix）。";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {

package/build/schemas/memory-tools.js

@@ -16,7 +16,7 @@ export const memoryToolSchemas = [
     },
     {
         name: 'memorize_asset',
-        description: '当 AI 完成开发并确认存在可复用代码、模式或规范时使用。将高价值资产沉淀到记忆系统。',
+        description: '沉淀可检索资产到记忆系统：可复用代码/模式；Bug 修复后必须写入 type=bugfix（现象、根因、改法、tags 含 bugfix）。',
         inputSchema: {
             type: 'object',
             properties: {

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

@@ -3,13 +3,35 @@
  */
 export declare const projectToolSchemas: readonly [{
     readonly name: "init_project_context";
-    readonly description: "当用户需要生成项目上下文文档、帮助团队快速上手时使用。生成项目上下文文档（技术栈/架构/编码规范），供后续开发参考";
+    readonly description: "生成/更新项目上下文：默认写入 AGENTS.md（含 MCP 与 GitNexus 触发规则）及 docs/project-context/。新功能请先 start_feature，修 bug 请先 start_bugfix。完成后 Agent 应阅读 AGENTS.md。";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {
             readonly docs_dir: {
                 readonly type: "string";
-                readonly description: "文档目录。可选，默认 docs";
+                readonly description: "附属文档根目录（project-context、graph-insights）。默认 docs";
+            };
+            readonly index_style: {
+                readonly type: "string";
+                readonly enum: readonly ["auto", "agents", "legacy"];
+                readonly description: "索引风格：auto（默认 AGENTS.md）、agents、legacy（docs/project-context.md）";
+            };
+            readonly output: {
+                readonly type: "string";
+                readonly description: "高级：索引文件相对路径，如 AGENTS.md";
+            };
+            readonly output_dir: {
+                readonly type: "string";
+                readonly description: "高级：索引所在目录，如 .claude/rules";
+            };
+            readonly filename: {
+                readonly type: "string";
+                readonly description: "高级：与 output_dir 合用，默认 project-context.md";
+            };
+            readonly locale: {
+                readonly type: "string";
+                readonly enum: readonly ["en", "zh-CN"];
+                readonly description: "AGENTS.md 语言；默认根据 README 探测";
             };
         };
         readonly required: readonly [];

package/build/schemas/project-tools.js

@@ -4,13 +4,35 @@
 export const projectToolSchemas = [
     {
         name: "init_project_context",
-        description: "当用户需要生成项目上下文文档、帮助团队快速上手时使用。生成项目上下文文档（技术栈/架构/编码规范），供后续开发参考",
+        description: "生成/更新项目上下文：默认写入 AGENTS.md（含 MCP 与 GitNexus 触发规则）及 docs/project-context/。新功能请先 start_feature，修 bug 请先 start_bugfix。完成后 Agent 应阅读 AGENTS.md。",
         inputSchema: {
             type: "object",
             properties: {
                 docs_dir: {
                     type: "string",
-                    description: "文档目录。可选，默认 docs",
+                    description: "附属文档根目录（project-context、graph-insights）。默认 docs",
+                },
+                index_style: {
+                    type: "string",
+                    enum: ["auto", "agents", "legacy"],
+                    description: "索引风格：auto（默认 AGENTS.md）、agents、legacy（docs/project-context.md）",
+                },
+                output: {
+                    type: "string",
+                    description: "高级：索引文件相对路径，如 AGENTS.md",
+                },
+                output_dir: {
+                    type: "string",
+                    description: "高级：索引所在目录，如 .claude/rules",
+                },
+                filename: {
+                    type: "string",
+                    description: "高级：与 output_dir 合用，默认 project-context.md",
+                },
+                locale: {
+                    type: "string",
+                    enum: ["en", "zh-CN"],
+                    description: "AGENTS.md 语言；默认根据 README 探测",
                 },
             },
             required: [],

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

@@ -144,15 +144,15 @@ describe("code_insight 单元测试", () => {
             expect(text).toMatch(/不要只口头总结而不写文件/);
             expect(text).toMatch(/docs\/graph-insights\/latest\.md/);
             expect(text).toMatch(/使用场景指南/);
-            expect(structured.projectDocs.latestMarkdownFilePath).toContain("/docs/graph-insights/latest.md");
+            expect(structured.projectDocs.latestMarkdownFilePath).toMatch(/docs\/graph-insights\/latest\.md$/);
             expect(structured.projectDocs.archiveMarkdownFilePath).toContain("/docs/graph-insights/");
-            expect(structured.projectDocs.projectContextFilePath).toContain("/docs/project-context.md");
+            expect(structured.projectDocs.projectContextFilePath).toMatch(/\/(AGENTS\.md|docs\/project-context\.md)$/);
             expect(structured.projectDocs.navigationSnippet).toMatch(/代码图谱洞察/);
             expect(structured.plan.mode).toBe("delegated");
             expect(structured.plan.steps).toHaveLength(2);
             expect(structured.plan.steps[0].id).toBe("consume-result");
             expect(structured.plan.steps[1].id).toBe("optional-save");
-            expect(structured.plan.steps[1].outputs[0]).toContain("/docs/graph-insights/latest.md");
+            expect(structured.plan.steps[1].outputs[0]).toMatch(/docs\/graph-insights\/latest\.md$/);
             expect(fs.existsSync(path.join(projectRoot, "docs", "graph-insights", "latest.md"))).toBe(false);
         }
         finally {