mcp-probe-kit 3.0.18 → 3.0.19

package/build/tools/start_feature.js

@@ -1,5 +1,4 @@
 import * as fs from "node:fs";
-import * as path from "node:path";
 import { parseArgs, getString, getNumber } from "../utils/parseArgs.js";
 import { okStructured } from "../lib/response.js";
 import { renderOrchestrationHeader } from "../lib/orchestration-guidance.js";
@@ -8,6 +7,7 @@ import { reportToolProgress, throwIfAborted, } from "../lib/tool-execution-conte
 import { buildFeatureGraphContext } from "../lib/gitnexus-bridge.js";
 import { buildMemoryPlanStep, loadMemoryInjectionContext, renderMemoryGuideSection, } from "../lib/memory-orchestration.js";
 import { resolveWorkspaceRoot, toWorkspacePath, isLikelyProjectNamedRelativePath, buildProjectRootRetryHint } from "../lib/workspace-root.js";
+import { layoutAbsPath, parseLayoutArgsFromRecord, resolveProjectContextLayout, } from "../lib/project-context-layout.js";
 /**
  * start_feature 智能编排工具
  *
@@ -54,114 +54,114 @@ function extractFeatureInfo(input) {
         description: input,
     };
 }
-const PROMPT_TEMPLATE = `# 🚀 新功能开发编排（委托式）
-
-本工具仅生成 **执行计划（steps）**。AI 需要按顺序调用对应工具并落盘文档。
-
-## 🎯 目标
-开发新功能：**{feature_name}**
-功能描述：{description}
-
----
-
-## ✅ 执行计划（按顺序）
-
-### 0) 项目上下文（如缺失）
-**检查**:
-- \`{docs_dir}/project-context.md\`
-- \`{docs_dir}/graph-insights/latest.md\`
-- \`{docs_dir}/graph-insights/latest.json\`
-**缺失则调用**: \`init_project_context\`
-\`\`\`json
-{ "docs_dir": "{docs_dir}", "project_root": "{project_root}" }
-\`\`\`
-
-### 1) 生成功能规格
-**调用**: \`add_feature\`
-\`\`\`json
-{
-  "feature_name": "{feature_name}",
-  "description": "{description}",
-  "docs_dir": "{docs_dir}",
-  "template_profile": "{template_profile}"
-}
-\`\`\`
-**预期输出**:
-- \`{docs_dir}/specs/{feature_name}/requirements.md\`
-- \`{docs_dir}/specs/{feature_name}/design.md\`
-- \`{docs_dir}/specs/{feature_name}/tasks.md\`
-
-### 2) 工作量估算
-**调用**: \`estimate\`
-\`\`\`json
-{
-  "task_description": "实现 {feature_name} 功能：{description}",
-  "code_context": "参考生成的 tasks.md 中的任务列表"
-}
-\`\`\`
-
----
-
-## ✅ 输出汇总（执行完成后）
-1. 规格文档位置: \`{docs_dir}/specs/{feature_name}/\`
-2. 图谱入口: \`{docs_dir}/graph-insights/latest.md\`
-3. 估算结果: 故事点 + 时间区间
-4. 主要风险（如有）
-5. 下一步: 按 tasks.md 开始开发
-
----
-
+const PROMPT_TEMPLATE = `# 🚀 新功能开发编排（委托式）
+
+本工具仅生成 **执行计划（steps）**。AI 需要按顺序调用对应工具并落盘文档。
+
+## 🎯 目标
+开发新功能：**{feature_name}**
+功能描述：{description}
+
+---
+
+## ✅ 执行计划（按顺序）
+
+### 0) 项目上下文（如缺失）
+**检查**:
+- \`{docs_dir}/project-context.md\`
+- \`{docs_dir}/graph-insights/latest.md\`
+- \`{docs_dir}/graph-insights/latest.json\`
+**缺失则调用**: \`init_project_context\`
+\`\`\`json
+{ "docs_dir": "{docs_dir}", "project_root": "{project_root}" }
+\`\`\`
+
+### 1) 生成功能规格
+**调用**: \`add_feature\`
+\`\`\`json
+{
+  "feature_name": "{feature_name}",
+  "description": "{description}",
+  "docs_dir": "{docs_dir}",
+  "template_profile": "{template_profile}"
+}
+\`\`\`
+**预期输出**:
+- \`{docs_dir}/specs/{feature_name}/requirements.md\`
+- \`{docs_dir}/specs/{feature_name}/design.md\`
+- \`{docs_dir}/specs/{feature_name}/tasks.md\`
+
+### 2) 工作量估算
+**调用**: \`estimate\`
+\`\`\`json
+{
+  "task_description": "实现 {feature_name} 功能：{description}",
+  "code_context": "参考生成的 tasks.md 中的任务列表"
+}
+\`\`\`
+
+---
+
+## ✅ 输出汇总（执行完成后）
+1. 规格文档位置: \`{docs_dir}/specs/{feature_name}/\`
+2. 图谱入口: \`{docs_dir}/graph-insights/latest.md\`
+3. 估算结果: 故事点 + 时间区间
+4. 主要风险（如有）
+5. 下一步: 按 tasks.md 开始开发
+
+---
+
 *编排工具: MCP Probe Kit - start_feature*`;
-const LOOP_PROMPT_TEMPLATE = `# 🧭 需求澄清与补全（Requirements Loop）
-
-本模式用于**生产级稳健补全**：在不改变用户意图的前提下补齐关键要素，并输出可审计的结构化结果。
-
-## 🎯 目标
-开发新功能：**{feature_name}**  
-功能描述：{description}
-
-## ✅ 规则
-1. **不覆盖用户原始需求**
-2. **补全内容必须标注来源**（User / Derived / Assumption）
-3. **假设必须进入待确认列表**
-4. **每轮问题 ≤ {question_budget}，假设 ≤ {assumption_cap}**
-
----
-
-## 🔁 执行步骤（每轮）
-
-### 1) 生成待确认问题
-使用 \`ask_user\` 提问，问题来源于“功能需求补全清单”（角色/触发/约束/异常/依赖等）。
-
-**调用示例**:
-\`\`\`json
-{
-  "questions": [
-    { "question": "目标用户或角色是谁？", "context": "角色定义", "required": true },
-    { "question": "触发场景是什么？", "context": "业务场景", "required": true }
-  ]
-}
-\`\`\`
-
-### 2) 更新结构化输出
-将回答补入 \`requirements\`，并标注来源：
-- User：用户明确回答
-- Derived：合理推导
-- Assumption：无法确认但补全（需确认）
-
-### 3) 自检与结束
-若 \`openQuestions\` 为空且无高风险假设，则结束 loop，进入规格生成与估算。
-
----
-
-## ✅ 结束后继续
-当满足结束条件时，执行：
-1. 调用 \`add_feature\` 生成规格文档
-2. 调用 \`estimate\` 进行工作量估算
-
----
-
-*编排工具: MCP Probe Kit - start_feature (requirements loop)*
+const LOOP_PROMPT_TEMPLATE = `# 🧭 需求澄清与补全（Requirements Loop）
+
+本模式用于**生产级稳健补全**：在不改变用户意图的前提下补齐关键要素，并输出可审计的结构化结果。
+
+## 🎯 目标
+开发新功能：**{feature_name}**  
+功能描述：{description}
+
+## ✅ 规则
+1. **不覆盖用户原始需求**
+2. **补全内容必须标注来源**（User / Derived / Assumption）
+3. **假设必须进入待确认列表**
+4. **每轮问题 ≤ {question_budget}，假设 ≤ {assumption_cap}**
+
+---
+
+## 🔁 执行步骤（每轮）
+
+### 1) 生成待确认问题
+使用 \`ask_user\` 提问，问题来源于“功能需求补全清单”（角色/触发/约束/异常/依赖等）。
+
+**调用示例**:
+\`\`\`json
+{
+  "questions": [
+    { "question": "目标用户或角色是谁？", "context": "角色定义", "required": true },
+    { "question": "触发场景是什么？", "context": "业务场景", "required": true }
+  ]
+}
+\`\`\`
+
+### 2) 更新结构化输出
+将回答补入 \`requirements\`，并标注来源：
+- User：用户明确回答
+- Derived：合理推导
+- Assumption：无法确认但补全（需确认）
+
+### 3) 自检与结束
+若 \`openQuestions\` 为空且无高风险假设，则结束 loop，进入规格生成与估算。
+
+---
+
+## ✅ 结束后继续
+当满足结束条件时，执行：
+1. 调用 \`add_feature\` 生成规格文档
+2. 调用 \`estimate\` 进行工作量估算
+
+---
+
+*编排工具: MCP Probe Kit - start_feature (requirements loop)*
 `;
 function buildOpenQuestions(questionBudget) {
     const base = [
@@ -252,15 +252,21 @@ export async function startFeature(args, context) {
         }
         throwIfAborted(context?.signal, "start_feature 已取消");
         await reportToolProgress(context, 55, "start_feature: 刷新图谱并收敛需求范围");
+        const resolvedProjectRoot = resolveWorkspaceRoot(projectRoot);
+        const layout = resolveProjectContextLayout(resolvedProjectRoot, parseLayoutArgsFromRecord({ docs_dir: docsDir }));
+        const projectRootAbs = layout.projectRoot;
         const graphDocs = {
-            latestMarkdownPath: `${docsDir}/graph-insights/latest.md`,
-            latestJsonPath: `${docsDir}/graph-insights/latest.json`,
+            latestMarkdownPath: layout.latestMarkdownPath,
+            latestJsonPath: layout.latestJsonPath,
         };
-        const resolvedProjectRoot = resolveWorkspaceRoot(projectRoot);
         const bootstrapState = {
-            projectContextExists: fs.existsSync(path.join(resolvedProjectRoot, docsDir, "project-context.md")),
-            latestMarkdownExists: fs.existsSync(path.join(resolvedProjectRoot, docsDir, "graph-insights", "latest.md")),
-            latestJsonExists: fs.existsSync(path.join(resolvedProjectRoot, docsDir, "graph-insights", "latest.json")),
+            projectContextExists: fs.existsSync(layoutAbsPath(layout, layout.indexPath)) ||
+                fs.existsSync(layoutAbsPath(layout, layout.legacyIndexPath)),
+            latestMarkdownExists: fs.existsSync(layoutAbsPath(layout, layout.latestMarkdownPath)),
+            latestJsonExists: fs.existsSync(layoutAbsPath(layout, layout.latestJsonPath)),
+            indexPath: layout.indexPath,
+            projectRoot: layout.projectRootPosix,
+            layoutManifest: layout.manifestPath,
         };
         const graphDocsMissing = !bootstrapState.latestMarkdownExists || !bootstrapState.latestJsonExists;
         const graphContext = await buildFeatureGraphContext({
@@ -272,18 +278,18 @@ export async function startFeature(args, context) {
         const graphStatusNote = graphContext.available
             ? `任务图谱收敛: 可用（${graphContext.mode}）`
             : "任务图谱收敛: 已降级（自动回退）";
-        const graphGuideSection = `
-
-## 🧠 代码图谱上下文
-- 基线入口: ${graphDocs.latestMarkdownPath}
-- 基线结构化副本: ${graphDocs.latestJsonPath}
-- 基线状态: ${graphDocsMissing ? "缺失（需要补初始化）" : "可用"}
-- 任务级收敛: ${graphContext.available ? "可用" : "降级"}
-- 任务级摘要: ${graphContext.summary}
+        const graphGuideSection = `
+
+## 🧠 代码图谱上下文
+- 基线入口: ${graphDocs.latestMarkdownPath}
+- 基线结构化副本: ${graphDocs.latestJsonPath}
+- 基线状态: ${graphDocsMissing ? "缺失（需要补初始化）" : "可用"}
+- 任务级收敛: ${graphContext.available ? "可用" : "降级"}
+- 任务级摘要: ${graphContext.summary}
 ${graphContext.highlights.length > 0
             ? `- 任务级线索:\n${graphContext.highlights.slice(0, 3).map((item) => `  - ${item}`).join("\n")}`
-            : "- 任务级线索: 无"}
-- 使用方式: 先参考基线图谱，再使用本次任务图谱线索约束模块边界和改动范围
+            : "- 任务级线索: 无"}
+- 使用方式: 先参考基线图谱，再使用本次任务图谱线索约束模块边界和改动范围
 `;
         const estimateCodeContext = [
             `参考生成的 ${docsDir}/specs/${featureName}/tasks.md`,
@@ -327,12 +333,12 @@ ${graphContext.highlights.length > 0
                     {
                         id: 'context',
                         tool: 'init_project_context',
-                        when: `缺少 ${docsDir}/project-context.md 或 ${graphDocs.latestMarkdownPath} / ${graphDocs.latestJsonPath}`,
+                        when: `缺少 ${layout.indexPath} 或 ${graphDocs.latestMarkdownPath} / ${graphDocs.latestJsonPath}`,
                         args: {
                             docs_dir: docsDir,
                             ...(projectRoot ? { project_root: projectRoot } : {}),
                         },
-                        outputs: [`${docsDir}/project-context.md`, graphDocs.latestMarkdownPath, graphDocs.latestJsonPath],
+                        outputs: [layout.indexPath, graphDocs.latestMarkdownPath, graphDocs.latestJsonPath],
                         note: `兼容老项目：即使已有旧版 project-context，只要缺少图谱文档，也要先补齐 ${graphDocs.latestMarkdownPath}`,
                     },
                     {
@@ -373,7 +379,7 @@ ${graphContext.highlights.length > 0
                         },
                         outputs: [],
                     },
-                    ...(memoryContext.enabled ? [buildMemoryPlanStep()] : []),
+                    ...(memoryContext.enabled ? [buildMemoryPlanStep('feature')] : []),
                 ],
             };
             const header = renderOrchestrationHeader({
@@ -463,12 +469,12 @@ ${graphContext.highlights.length > 0
                 {
                     id: 'context',
                     tool: 'init_project_context',
-                    when: `缺少 ${docsDir}/project-context.md 或 ${graphDocs.latestMarkdownPath} / ${graphDocs.latestJsonPath}`,
+                    when: `缺少 ${layout.indexPath} 或 ${graphDocs.latestMarkdownPath} / ${graphDocs.latestJsonPath}`,
                     args: {
                         docs_dir: docsDir,
                         ...(projectRoot ? { project_root: projectRoot } : {}),
                     },
-                    outputs: [`${docsDir}/project-context.md`, graphDocs.latestMarkdownPath, graphDocs.latestJsonPath],
+                    outputs: [layout.indexPath, graphDocs.latestMarkdownPath, graphDocs.latestJsonPath],
                     note: `兼容老项目：即使已有旧版 project-context，只要缺少图谱文档，也要先补齐 ${graphDocs.latestMarkdownPath}`,
                 },
                 {
@@ -490,7 +496,7 @@ ${graphContext.highlights.length > 0
                     },
                     outputs: [],
                 },
-                ...(memoryContext.enabled ? [buildMemoryPlanStep()] : []),
+                ...(memoryContext.enabled ? [buildMemoryPlanStep('feature')] : []),
             ],
         };
         // 创建结构化的功能开发报告
@@ -501,7 +507,7 @@ ${graphContext.highlights.length > 0
                 {
                     name: '检查项目上下文',
                     status: 'pending',
-                    description: `检查 ${docsDir}/project-context.md 与 graph-insights/latest.* 是否存在，缺失则调用 init_project_context`,
+                    description: `检查 ${layout.indexPath} 与 graph-insights/latest.* 是否存在，缺失则调用 init_project_context`,
                 },
                 {
                     name: '生成功能规格',