mcp-probe-kit 3.2.0 → 3.6.0

package/build/lib/memory-orchestration.js

@@ -1,5 +1,6 @@
 import { createMemoryClient } from './memory-client.js';
 import { getMemoryConfig } from './memory-config.js';
+import { buildMemoryAssetHandles, DEFAULT_GRAPH_RESOURCE_URI, mergeHandles, } from './handles.js';
 function kindSearchPreferences(kind) {
     switch (kind) {
         case 'bugfix':
@@ -195,6 +196,25 @@ export function renderMemoryGuideSection(context) {
     }
     return blocks.join('\n');
 }
+export function buildMemoryInjectionHandles(context) {
+    if (!context.enabled || context.results.length === 0) {
+        return {};
+    }
+    return {
+        memory_assets: buildMemoryAssetHandles(context.results.map((item) => ({
+            id: item.id,
+            name: item.name,
+            type: item.type,
+            summary: item.summary,
+        }))),
+    };
+}
+export function buildOrchestrationHandles(memoryContext, options) {
+    const memoryHandles = memoryContext ? buildMemoryInjectionHandles(memoryContext) : {};
+    return mergeHandles(memoryHandles, {
+        graph_resource: options?.graphResourceUri ?? DEFAULT_GRAPH_RESOURCE_URI,
+    });
+}
 export function buildMemoryPlanStep(kind = 'default') {
     if (kind === 'bugfix') {
         return {

package/build/lib/merge-agents-md.d.ts

@@ -1,6 +1,6 @@
 export type AgentsMdMergeMode = "created" | "prepended" | "replaced-and-moved-to-top" | "skipped-empty";
-export declare function wrapMcpProbeBlock(innerMarkdown: string): string;
-export declare function mergeAgentsMdBlock(existingContent: string | null | undefined, generatedInner: string): {
+export declare function wrapMcpProbeBlock(innerMarkdown: string, contextVersion?: string): string;
+export declare function mergeAgentsMdBlock(existingContent: string | null | undefined, generatedInner: string, contextVersion?: string): {
     content: string;
     mergeMode: AgentsMdMergeMode;
 };

package/build/lib/merge-agents-md.js

@@ -1,7 +1,10 @@
+import { VERSION } from "../version.js";
+import { formatAgentsContextVersionMarker } from "./workflow-skill-version.js";
 const BLOCK_BEGIN = "<!-- mcp-probe:context begin — auto-generated; re-run init_project_context updates this block only -->";
 const BLOCK_END = "<!-- mcp-probe:context end -->";
-export function wrapMcpProbeBlock(innerMarkdown) {
-    return `${BLOCK_BEGIN}\n${innerMarkdown.trim()}\n${BLOCK_END}`;
+export function wrapMcpProbeBlock(innerMarkdown, contextVersion = VERSION) {
+    const versionLine = formatAgentsContextVersionMarker(contextVersion);
+    return `${BLOCK_BEGIN}\n${versionLine}\n${innerMarkdown.trim()}\n${BLOCK_END}`;
 }
 function stripExistingBlock(content) {
     const beginIdx = content.indexOf(BLOCK_BEGIN);
@@ -28,8 +31,8 @@ function stripExistingBlock(content) {
     const after = content.slice(endIdx + BLOCK_END.length).trimStart();
     return [before, after].filter(Boolean).join("\n\n").trim();
 }
-export function mergeAgentsMdBlock(existingContent, generatedInner) {
-    const block = wrapMcpProbeBlock(generatedInner);
+export function mergeAgentsMdBlock(existingContent, generatedInner, contextVersion = VERSION) {
+    const block = wrapMcpProbeBlock(generatedInner, contextVersion);
     if (!existingContent?.trim()) {
         return { content: `${block}\n`, mergeMode: "created" };
     }

package/build/lib/output-schema-registry.d.ts

@@ -0,0 +1,11 @@
+/**
+ * tools/list 的 outputSchema 注册表（与 tools-manifest.json structuredOutput.schemas 对齐）
+ */
+type JsonSchema = Record<string, unknown>;
+export declare function getOutputSchemaForTool(toolName: string): JsonSchema | undefined;
+export declare function withOutputSchema<T extends {
+    name: string;
+}>(tool: T): T & {
+    outputSchema?: JsonSchema;
+};
+export {};

package/build/lib/output-schema-registry.js

@@ -0,0 +1,80 @@
+/**
+ * tools/list 的 outputSchema 注册表（与 tools-manifest.json structuredOutput.schemas 对齐）
+ */
+import { CodeReviewReportSchema, BugAnalysisSchema, TestSuiteSchema, RefactorPlanSchema, } from '../schemas/output/core-tools.js';
+import { FeatureSpecSchema, ProjectInitSchema, ProjectContextSchema, EstimateSchema, } from '../schemas/output/project-tools.js';
+import { DesignSystemSchema, UISearchResultSchema, SyncReportSchema, } from '../schemas/output/ui-ux-tools.js';
+import { InterviewReportSchema } from '../schemas/output/product-design-tools.js';
+import { CommitGuidanceSchema, FeatureReportSchema, BugFixReportSchema, UIReportSchema, OnboardingReportSchema, RalphLoopReportSchema, WorkflowReportSchema, } from '../schemas/structured-output.js';
+import { MemorySearchSchema, MemoryAssetDetailSchema, MemorizeResultSchema, DeleteMemoryResultSchema, UpdateMemoryResultSchema, PatternExtractionSchema, } from '../schemas/output/memory-tools.js';
+import { CodeInsightSchema } from '../schemas/output/code-insight-tools.js';
+const SpecValidationReportSchema = {
+    type: 'object',
+    properties: {
+        passed: { type: 'boolean' },
+        errorCount: { type: 'number' },
+        warningCount: { type: 'number' },
+        issues: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    file: { type: 'string' },
+                    severity: { type: 'string', enum: ['error', 'warning'] },
+                    code: { type: 'string' },
+                    message: { type: 'string' },
+                },
+                required: ['file', 'severity', 'message'],
+            },
+        },
+        frIds: { type: 'array', items: { type: 'string' } },
+        summary: { type: 'string' },
+    },
+    required: ['passed', 'errorCount', 'warningCount', 'issues', 'summary'],
+};
+const UserQuestionSchema = {
+    type: 'object',
+    properties: {
+        question: { type: 'string' },
+        options: { type: 'array', items: { type: 'string' } },
+        context: { type: 'string' },
+    },
+    required: ['question'],
+};
+const OUTPUT_SCHEMA_BY_TOOL = {
+    gencommit: CommitGuidanceSchema,
+    code_insight: CodeInsightSchema,
+    code_review: CodeReviewReportSchema,
+    fix_bug: BugAnalysisSchema,
+    gentest: TestSuiteSchema,
+    refactor: RefactorPlanSchema,
+    add_feature: FeatureSpecSchema,
+    check_spec: SpecValidationReportSchema,
+    estimate: EstimateSchema,
+    start_feature: FeatureReportSchema,
+    start_bugfix: BugFixReportSchema,
+    start_onboard: OnboardingReportSchema,
+    start_ui: UIReportSchema,
+    start_product: WorkflowReportSchema,
+    start_ralph: RalphLoopReportSchema,
+    init_project: ProjectInitSchema,
+    init_project_context: ProjectContextSchema,
+    interview: InterviewReportSchema,
+    ask_user: UserQuestionSchema,
+    ui_design_system: DesignSystemSchema,
+    ui_search: UISearchResultSchema,
+    sync_ui_data: SyncReportSchema,
+    search_memory: MemorySearchSchema,
+    read_memory_asset: MemoryAssetDetailSchema,
+    memorize_asset: MemorizeResultSchema,
+    delete_memory_asset: DeleteMemoryResultSchema,
+    update_memory_asset: UpdateMemoryResultSchema,
+    scan_and_extract_patterns: PatternExtractionSchema,
+};
+export function getOutputSchemaForTool(toolName) {
+    return OUTPUT_SCHEMA_BY_TOOL[toolName];
+}
+export function withOutputSchema(tool) {
+    const outputSchema = getOutputSchemaForTool(tool.name);
+    return outputSchema ? { ...tool, outputSchema } : tool;
+}

package/build/lib/quality-constraints.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 质量约束「单一真相源」
+ *
+ * 目标：把散落在 task 模板、code_review、UI 工具里的软性质量要求，
+ * 收敛到一个集中管理的硬约束模块。三个落点工具都从这里 import，
+ * 改一处、处处生效，杜绝规则漂移。
+ *
+ * 设计哲学（借鉴 taste-skill / impeccable）：
+ * 凡是想让下游 AI 真正照做的规则，必须用「机器可判定的硬约束 +
+ * 精确字符串黑名单 + 二元禁令 + 交付前 checklist」，
+ * 禁用「尽量 / 建议 / sparingly」这类会被 AI 忽略的软措辞。
+ *
+ * 本模块为纯常量 + 字符串渲染，无 I/O、零运行时依赖，便于单测。
+ */
+export interface CodeLimits {
+    /** 单文件最大行数；超出必须拆分模块/组件 */
+    maxFileLines: number;
+    /** 单函数最大行数；超出必须拆分方法 */
+    maxFunctionLines: number;
+    /** 最大嵌套层数；超出用提前返回（early return）展平 */
+    maxNestingDepth: number;
+    /** 最大参数个数；超出改用参数对象 */
+    maxParameters: number;
+}
+export declare const CODE_LIMITS: CodeLimits;
+/**
+ * 占位/省略式代码模式——出现即判「未完成的破碎输出」。
+ * 措辞二元：零容忍，不存在「少量允许」。
+ */
+export declare const BANNED_CODE_PATTERNS: string[];
+/**
+ * 每条都是带数值/比例的硬约束，区别于含糊的「保持一致」。
+ * 精选自 impeccable，挑机器可判定、收益最高的条款。
+ */
+export declare const UI_HARD_RULES: string[];
+/**
+ * 命中即「AI slop」。这些是 taste-skill / impeccable 生产测试中
+ * 最高频的 AI 设计破绽（tells）。
+ */
+export declare const UI_BANNED_LIST: string[];
+/** 代码量硬约束清单 */
+export declare function renderCodeLimits(): string;
+/** 完整性黑名单（占位符/省略式代码） */
+export declare function renderBannedPatterns(): string;
+/** UI 设计硬红线 */
+export declare function renderUiHardRules(): string;
+/** UI 禁用黑名单 */
+export declare function renderUiBannedList(): string;
+/**
+ * 交付前自检矩阵（Pre-Flight Checklist）。
+ * 把所有约束收口成一个生成结束前必须逐条诚实勾选的闭环。
+ * 任意一项不能诚实勾选 = 未完成。
+ */
+export declare function renderPreFlightChecklist(): string;

package/build/lib/quality-constraints.js

@@ -0,0 +1,155 @@
+/**
+ * 质量约束「单一真相源」
+ *
+ * 目标：把散落在 task 模板、code_review、UI 工具里的软性质量要求，
+ * 收敛到一个集中管理的硬约束模块。三个落点工具都从这里 import，
+ * 改一处、处处生效，杜绝规则漂移。
+ *
+ * 设计哲学（借鉴 taste-skill / impeccable）：
+ * 凡是想让下游 AI 真正照做的规则，必须用「机器可判定的硬约束 +
+ * 精确字符串黑名单 + 二元禁令 + 交付前 checklist」，
+ * 禁用「尽量 / 建议 / sparingly」这类会被 AI 忽略的软措辞。
+ *
+ * 本模块为纯常量 + 字符串渲染，无 I/O、零运行时依赖，便于单测。
+ */
+export const CODE_LIMITS = {
+    maxFileLines: 500,
+    maxFunctionLines: 50,
+    maxNestingDepth: 4,
+    maxParameters: 3,
+};
+// ============================================================
+// 二、代码完整性黑名单（精确字符串，机械可扫描）
+// ============================================================
+/**
+ * 占位/省略式代码模式——出现即判「未完成的破碎输出」。
+ * 措辞二元：零容忍，不存在「少量允许」。
+ */
+export const BANNED_CODE_PATTERNS = [
+    '// ...',
+    '/* ... */',
+    '// TODO',
+    '// FIXME（遗留未实现）',
+    '// rest of code',
+    '// rest of the code',
+    '// implement here',
+    '// your code here',
+    '// similar to above',
+    '// same as before',
+    '裸露的省略号 ...（作为代码占位）',
+    'the rest follows the same pattern',
+    'and so on',
+    '以此类推（作为代码省略）',
+    '其余代码省略',
+    '此处省略',
+];
+// ============================================================
+// 三、UI 设计硬红线（带数值，可机器判定）
+// ============================================================
+/**
+ * 每条都是带数值/比例的硬约束，区别于含糊的「保持一致」。
+ * 精选自 impeccable，挑机器可判定、收益最高的条款。
+ */
+export const UI_HARD_RULES = [
+    '间距系统：强制 4pt 基准阶梯 [4, 8, 12, 16, 24, 32, 48, 64, 96]px。同组元素 8-12px，跨区块 48-96px。任何不在阶梯内的 padding/margin/gap 判为漂移。',
+    '触控目标：≥ 44×44px。视觉元素更小时用 padding 或伪元素扩大命中区。',
+    '对比度（WCAG）：正文 ≥ 4.5:1；大文本（≥18px 或 bold ≥14px）≥ 3:1；UI 组件/图标 ≥ 3:1；placeholder 同样 ≥ 4.5:1（不可用默认浅灰）。',
+    '字阶比例：相邻级别 ≥ 1.25（品牌站）或 1.125-1.2（产品界面）。禁止扁平字阶（14/15/16px 相邻）。最多 5 级。',
+    '主正文流字号：≥ 16px / 1rem，且用 rem 而非 px（脚注、表格密集数据、图例等辅助文本可更小）。',
+    'Hero 字号天花板：clamp() 的 max ≤ 6rem（96px）。clamp max ≤ 2.5 × min，否则破坏浏览器缩放与回流。',
+    'Display 标题字间距：≥ -0.04em，再紧字母会粘连。',
+    '色彩空间：用 OKLCH，禁用 HSL。中性色加微着色 chroma 0.005-0.015，朝品牌色（不默认朝暖橙 hue 60 / 冷蓝 hue 250）。',
+    '色彩权重：遵守 60-30-10（60% 中性底 / 30% 次要 / 10% 强调）。一个页面锁定单一强调色，逐组件审计一致性。',
+    '行高：标题 1.1-1.2，正文 1.5-1.7。深色背景上字重降一档、行高 +0.05-0.1。',
+    '交互八态完整性：每个交互元素必须设计 Default / Hover / Focus / Active / Disabled / Loading / Error / Success 八态，缺一即 P1。',
+    'Focus 可见性：禁止裸 outline:none。用 :focus-visible，2-3px 粗，对比 ≥ 3:1，outline-offset 在元素外侧。',
+    '动效：时长 150-300ms；缓动用 ease-out-expo/quart/quint；禁 bounce/elastic；必须有 @media (prefers-reduced-motion: reduce) 分支。',
+    '认知负荷：营销/落地页类界面任意决策点 ≤ 4 个可见选项（导航 ≤ 5 顶级项、表单每组 ≤ 4 字段、定价常见 ≤ 3-4 档）。数据密集型后台（监控大盘、交易看板）按信息需求放宽，不强套此限。',
+    'z-index：建立语义层级（dropdown → sticky → modal-backdrop → modal → toast → tooltip）。禁止任意值 999 / 9999。',
+];
+// ============================================================
+// 四、UI 禁用黑名单（match-and-refuse，二元禁令）
+// ============================================================
+/**
+ * 命中即「AI slop」。这些是 taste-skill / impeccable 生产测试中
+ * 最高频的 AI 设计破绽（tells）。
+ */
+export const UI_BANNED_LIST = [
+    '默认字体 Inter / Roboto / Open Sans（无明确理由时禁用）。',
+    'AI 默认紫蓝渐变（紫→蓝光辉），最典型的 AI 破绽。',
+    'gradient text（background-clip:text + 渐变）作为标题默认效果。',
+    'side-stripe 装饰边框（border-left/right > 1px 纯装饰）。',
+    '默认 glassmorphism（无真实层次的毛玻璃）。',
+    '相同卡片等距网格（无层次的 N 等分 card grid）。',
+    '嵌套卡片（nested cards 永远是错的）。',
+    '卡片圆角 ≥ 32px（卡片圆角上限 12-16px）。',
+    'ghost-card：同元素 border 1px + box-shadow blur ≥16px。',
+    'cream / sand / beige 米色正文背景（2026 年的饱和 AI 默认底色）。',
+    'hero-metric 模板（巨大数字 + 小标签的套路化英雄区）。',
+    '每段都有的 tiny uppercase eyebrow 小标签（每 3 区块最多 1 个）。',
+    '01 / 02 / 03 编号式小标题装饰。',
+    '英文排版/UI 文案中滥用 em-dash（"—"）：英文语境最高频的 AI 破绽，禁止用作随意连接符（中文正文的破折号属合法标点，不在此列）。',
+    '占位文案 "Lorem Ipsum" / "John Doe" / "Acme"。',
+    'AI 陈词滥调文案：Elevate / Seamless / Unleash / Delve / 赋能 / 一站式。',
+    '同页重复 CTA 意图（如 "Get in touch" + "Let\'s talk" 并存）。',
+];
+// ============================================================
+// 渲染函数：返回 markdown 片段，供各工具拼进指南
+// ============================================================
+/** 代码量硬约束清单 */
+export function renderCodeLimits() {
+    return `**代码量硬约束（超出即判 HIGH，必须重构）**：
+- [ ] 单文件 ≤ ${CODE_LIMITS.maxFileLines} 行：超出必须拆分为多个模块/组件
+- [ ] 单函数 ≤ ${CODE_LIMITS.maxFunctionLines} 行：超出必须拆分方法
+- [ ] 嵌套 ≤ ${CODE_LIMITS.maxNestingDepth} 层：超出用提前返回（early return）展平
+- [ ] 参数 ≤ ${CODE_LIMITS.maxParameters} 个：超出改用参数对象`;
+}
+/** 完整性黑名单（占位符/省略式代码） */
+export function renderBannedPatterns() {
+    const list = BANNED_CODE_PATTERNS.map((p) => `- \`${p}\``).join('\n');
+    return `**完整性检查（命中即判 CRITICAL：「部分输出 = 破碎输出」）**：
+
+下列占位/省略模式零容忍，扫描到任意一个即判定该交付物未完成：
+
+${list}
+
+> 二元规则：不存在「少量允许」。任何用占位符、省略注释代替真实实现的行为都是破碎输出。`;
+}
+/** UI 设计硬红线 */
+export function renderUiHardRules() {
+    const list = UI_HARD_RULES.map((r, i) => `${i + 1}. ${r}`).join('\n');
+    return `## UI 设计硬红线（带数值，可逐条核验）
+
+${list}`;
+}
+/** UI 禁用黑名单 */
+export function renderUiBannedList() {
+    const list = UI_BANNED_LIST.map((b) => `- ❌ ${b}`).join('\n');
+    return `## UI 禁用黑名单（命中即 AI slop，二元禁令）
+
+${list}`;
+}
+/**
+ * 交付前自检矩阵（Pre-Flight Checklist）。
+ * 把所有约束收口成一个生成结束前必须逐条诚实勾选的闭环。
+ * 任意一项不能诚实勾选 = 未完成。
+ */
+export function renderPreFlightChecklist() {
+    return `## 交付前自检矩阵（Pre-Flight Check）
+
+> 生成结束前必须逐条诚实勾选。任意一项不能勾选 = 未完成，禁止交付。
+
+**完整性**：
+- [ ] 无任何占位符 / 省略注释 / TODO（对照完整性黑名单）
+- [ ] 交付物数量与需求一致（Scope-lock：先数清楚再交付）
+
+**代码量**：
+- [ ] 所有文件 ≤ ${CODE_LIMITS.maxFileLines} 行，函数 ≤ ${CODE_LIMITS.maxFunctionLines} 行
+
+**UI（若涉及界面）**：
+- [ ] 间距落在 4pt 阶梯内
+- [ ] 对比度达标（正文 ≥ 4.5:1）
+- [ ] 交互元素八态齐全
+- [ ] 未命中 UI 禁用黑名单（无 em-dash、无 AI 紫蓝渐变、无米色底等）
+- [ ] 单一强调色、统一圆角阶梯（一致性锁）`;
+}

package/build/lib/skill-bridge.js

@@ -84,17 +84,17 @@ export function renderSkillBridgeSection(status) {
     const conclusion = status.ready
         ? "全部 skill 可用，建议按顺序调用后再执行 MCP 工具步骤。"
         : "部分 skill 缺失：继续执行 MCP 主流程，不阻塞；安装缺失 skill 后下次运行可获得更高质量输出。";
-    return `## 🧩 Skill Bridge（UI/PRD 增强）
-
-按顺序调用（宿主支持时）：
-${orderLines}
-
-当前状态：
-${stateLines}
-
-${conclusion}
-
----
-
+    return `## 🧩 Skill Bridge（UI/PRD 增强）
+
+按顺序调用（宿主支持时）：
+${orderLines}
+
+当前状态：
+${stateLines}
+
+${conclusion}
+
+---
+
 `;
 }

package/build/lib/spec-gate.d.ts

@@ -0,0 +1,32 @@
+export interface SpecGateContext {
+    featureName: string;
+    docsDir: string;
+    specDir: string;
+    detected: boolean;
+}
+export declare function specArtifactsExist(projectRoot: string, docsDir: string, featureName: string): boolean;
+/**
+ * 解析 Bug 修复关联的 feature_name：
+ * 1) 显式传入优先
+ * 2) specs 下仅有一个目录时自动采用
+ * 3) 错误描述中唯一匹配某个 spec 目录名
+ */
+export declare function resolveBugfixFeatureName(explicitFeatureName: string, projectRoot: string, docsDir: string, hintText: string): string | null;
+export declare function resolveBugfixSpecGate(input: {
+    featureName?: string;
+    projectRoot: string;
+    docsDir: string;
+    hintText: string;
+}): SpecGateContext | null;
+export declare function buildCheckSpecPlanStep(featureName: string, docsDir: string): {
+    id: string;
+    tool: string;
+    when: string;
+    args: {
+        feature_name: string;
+        docs_dir: string;
+    };
+    outputs: string[];
+    note: string;
+};
+export declare function renderSpecGatePromptSection(specGate: SpecGateContext): string;

package/build/lib/spec-gate.js

@@ -0,0 +1,83 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export function specArtifactsExist(projectRoot, docsDir, featureName) {
+    const specDir = path.join(projectRoot, docsDir, 'specs', featureName);
+    return (fs.existsSync(path.join(specDir, 'requirements.md')) ||
+        fs.existsSync(path.join(specDir, 'design.md')) ||
+        fs.existsSync(path.join(specDir, 'tasks.md')));
+}
+/**
+ * 解析 Bug 修复关联的 feature_name：
+ * 1) 显式传入优先
+ * 2) specs 下仅有一个目录时自动采用
+ * 3) 错误描述中唯一匹配某个 spec 目录名
+ */
+export function resolveBugfixFeatureName(explicitFeatureName, projectRoot, docsDir, hintText) {
+    const explicit = explicitFeatureName.trim();
+    if (explicit) {
+        return explicit;
+    }
+    const specsRoot = path.join(projectRoot, docsDir, 'specs');
+    if (!fs.existsSync(specsRoot)) {
+        return null;
+    }
+    const dirs = fs
+        .readdirSync(specsRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name);
+    if (dirs.length === 1) {
+        return dirs[0] ?? null;
+    }
+    const lowerHint = hintText.toLowerCase();
+    const matched = dirs.filter((name) => {
+        const lowerName = name.toLowerCase();
+        if (lowerHint.includes(lowerName)) {
+            return true;
+        }
+        return lowerName
+            .split(/[-_]+/)
+            .filter((part) => part.length > 3)
+            .some((part) => lowerHint.includes(part));
+    });
+    return matched.length === 1 ? (matched[0] ?? null) : null;
+}
+export function resolveBugfixSpecGate(input) {
+    const featureName = resolveBugfixFeatureName(input.featureName ?? '', input.projectRoot, input.docsDir, input.hintText);
+    if (!featureName || !specArtifactsExist(input.projectRoot, input.docsDir, featureName)) {
+        return null;
+    }
+    return {
+        featureName,
+        docsDir: input.docsDir,
+        specDir: `${input.docsDir}/specs/${featureName}`,
+        detected: !input.featureName?.trim(),
+    };
+}
+export function buildCheckSpecPlanStep(featureName, docsDir) {
+    return {
+        id: 'check-spec',
+        tool: 'check_spec',
+        when: '修复与回归测试通过后，且本次 Bug 关联功能规格存在时',
+        args: {
+            feature_name: featureName,
+            docs_dir: docsDir,
+        },
+        outputs: [`${docsDir}/specs/${featureName}/`],
+        note: '若修复改动影响 requirements/design/tasks，先更新规格文档再重跑 check_spec；未通过不得视为修复闭环',
+    };
+}
+export function renderSpecGatePromptSection(specGate) {
+    const detectNote = specGate.detected
+        ? `\n- 自动识别关联规格: \`${specGate.specDir}/\``
+        : `\n- 关联规格: \`${specGate.specDir}/\``;
+    return `
+
+## 📐 步骤 3: 规格闸门（修复后）
+
+**调用**: \`check_spec\`
+\`\`\`json
+{ "feature_name": "${specGate.featureName}", "docs_dir": "${specGate.docsDir}" }
+\`\`\`
+${detectNote}
+**未通过**：按报告补全 requirements/design/tasks 后**重跑 check_spec**；规格与实现不一致时不得结案。`;
+}

package/build/lib/spec-validator.js

@@ -7,8 +7,8 @@
  *
  * 本模块为纯逻辑、无 I/O，便于单测。
  */
-/** 匹配未填写的占位符，如 `[填写：xxx]` / `[填写:xxx]` */
-const PLACEHOLDER_RE = /\[填写[：:][^\]]*\]/g;
+/** 匹配未填写的占位符：`[填写：xxx]` / `[填写:xxx]` / 裸 `[填写]` 都算 */
+const PLACEHOLDER_RE = /\[填写[：:]?[^\]]*\]/g;
 function countPlaceholders(content) {
     const matches = content.match(PLACEHOLDER_RE);
     return matches ? matches.length : 0;
@@ -29,7 +29,7 @@ export function extractFrIds(content) {
 const REQUIRED_SECTIONS = {
     requirements: ['功能概述', '需求列表', '非功能需求', '依赖关系'],
     design: ['概述', '技术方案', '文件结构'],
-    tasks: ['任务列表', '需求覆盖矩阵'],
+    tasks: ['交付物清单', '任务列表', '需求覆盖矩阵', '文件变更清单'],
 };
 /**
  * 校验三份规格文档。传入各文件的全文（不存在传 null）。
@@ -93,6 +93,19 @@ export function validateSpecDocuments(input) {
             });
         }
     }
+    // tasks：详细度校验——每条任务应附「证据块」，避免宽泛任务导致 AI 偷懒
+    if (tasks && tasks.trim()) {
+        const taskItemCount = (tasks.match(/^\s*-\s*\[\s*\]\s*\d+\.\d+/gm) || []).length;
+        const evidenceCount = (tasks.match(/证据块/g) || []).length;
+        if (taskItemCount > 0 && evidenceCount < taskItemCount) {
+            issues.push({
+                file: 'tasks',
+                severity: 'warning',
+                code: 'thin_task',
+                message: `tasks.md 有 ${taskItemCount} 条任务，但仅 ${evidenceCount} 条标注「证据块」；过于宽泛的任务易导致实现时偷懒/跳步`,
+            });
+        }
+    }
     const errorCount = issues.filter((item) => item.severity === 'error').length;
     const warningCount = issues.filter((item) => item.severity === 'warning').length;
     const passed = errorCount === 0;

package/build/lib/task-defaults.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 长耗时工具默认走 MCP Task，避免阻塞 stdio 宿主。
+ */
+export declare function isAutoTaskTool(toolName: string): boolean;
+export declare function isAutoTaskEnabled(): boolean;
+export declare function shouldAutoEscalateToTask(toolName: string, hasExplicitTaskRequest: boolean): boolean;

package/build/lib/task-defaults.js

@@ -0,0 +1,20 @@
+/**
+ * 长耗时工具默认走 MCP Task，避免阻塞 stdio 宿主。
+ */
+const AUTO_TASK_TOOLS = new Set(['code_insight', 'scan_and_extract_patterns']);
+export function isAutoTaskTool(toolName) {
+    return AUTO_TASK_TOOLS.has(toolName);
+}
+export function isAutoTaskEnabled() {
+    const raw = process.env.MCP_DISABLE_AUTO_TASK?.trim();
+    if (raw && /^(1|true|yes|on)$/i.test(raw)) {
+        return false;
+    }
+    return true;
+}
+export function shouldAutoEscalateToTask(toolName, hasExplicitTaskRequest) {
+    if (hasExplicitTaskRequest) {
+        return false;
+    }
+    return isAutoTaskEnabled() && isAutoTaskTool(toolName);
+}