mcp-probe-kit 3.1.0 → 3.3.0

package/build/lib/spec-validator.js

@@ -0,0 +1,116 @@
+/**
+ * 规格文档「填写后校验」闸门（P1）
+ *
+ * 目标：不依赖模型自觉。落盘后机械校验 requirements/design/tasks 的完整性，
+ * 打回残留占位符、缺章节、无 FR、无验收标准、FR 未进覆盖矩阵等问题，
+ * 让中等/偏弱模型也能被强制补全到可实现的程度。
+ *
+ * 本模块为纯逻辑、无 I/O，便于单测。
+ */
+/** 匹配未填写的占位符：`[填写：xxx]` / `[填写:xxx]` / 裸 `[填写]` 都算 */
+const PLACEHOLDER_RE = /\[填写[：:]?[^\]]*\]/g;
+function countPlaceholders(content) {
+    const matches = content.match(PLACEHOLDER_RE);
+    return matches ? matches.length : 0;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** 标题行存在性（## 概述 等） */
+function hasSection(content, name) {
+    const re = new RegExp(`^#{1,6}\\s+${escapeRegExp(name)}`, 'm');
+    return re.test(content);
+}
+/** 提取去重后的 FR-n 需求 ID */
+export function extractFrIds(content) {
+    const matches = content.match(/\bFR-\d+\b/g) || [];
+    return [...new Set(matches)];
+}
+const REQUIRED_SECTIONS = {
+    requirements: ['功能概述', '需求列表', '非功能需求', '依赖关系'],
+    design: ['概述', '技术方案', '文件结构'],
+    tasks: ['交付物清单', '任务列表', '需求覆盖矩阵', '文件变更清单'],
+};
+/**
+ * 校验三份规格文档。传入各文件的全文（不存在传 null）。
+ */
+export function validateSpecDocuments(input) {
+    const issues = [];
+    const requirements = input.requirements ?? null;
+    const design = input.design ?? null;
+    const tasks = input.tasks ?? null;
+    const checkFile = (key, content) => {
+        if (!content || !content.trim()) {
+            issues.push({ file: key, severity: 'error', code: 'missing_file', message: `${key}.md 不存在或为空` });
+            return;
+        }
+        const placeholders = countPlaceholders(content);
+        if (placeholders > 0) {
+            issues.push({
+                file: key,
+                severity: 'error',
+                code: 'placeholder',
+                message: `${key}.md 仍有 ${placeholders} 处未填写的「[填写：…]」占位`,
+            });
+        }
+        for (const section of REQUIRED_SECTIONS[key]) {
+            if (!hasSection(content, section)) {
+                issues.push({ file: key, severity: 'error', code: 'missing_section', message: `${key}.md 缺少章节「${section}」` });
+            }
+        }
+    };
+    checkFile('requirements', requirements);
+    checkFile('design', design);
+    checkFile('tasks', tasks);
+    // requirements：需有带 ID 的需求与 EARS 验收标准
+    let frIds = [];
+    if (requirements && requirements.trim()) {
+        frIds = extractFrIds(requirements);
+        if (frIds.length === 0) {
+            issues.push({ file: 'requirements', severity: 'error', code: 'no_fr', message: 'requirements.md 未定义任何带稳定 ID 的需求（FR-1、FR-2…）' });
+        }
+        if (!/SHALL/i.test(requirements)) {
+            issues.push({ file: 'requirements', severity: 'error', code: 'no_acceptance', message: 'requirements.md 未发现 EARS 验收标准（应包含「SHALL」）' });
+        }
+    }
+    // design：应引用 requirements 的 FR
+    if (design && design.trim() && frIds.length > 0) {
+        const designFr = extractFrIds(design);
+        if (designFr.length === 0) {
+            issues.push({ file: 'design', severity: 'warning', code: 'no_fr_ref', message: 'design.md 未引用任何 FR-id（应在「对应需求」标注本设计覆盖的需求）' });
+        }
+    }
+    // 跨文档：每条 FR 都应在 tasks（含覆盖矩阵）出现，否则可能漏实现
+    if (requirements && tasks && tasks.trim() && frIds.length > 0) {
+        const taskFr = new Set(extractFrIds(tasks));
+        const uncovered = frIds.filter((id) => !taskFr.has(id));
+        if (uncovered.length > 0) {
+            issues.push({
+                file: 'cross',
+                severity: 'error',
+                code: 'uncovered_fr',
+                message: `以下需求未在 tasks.md（含需求覆盖矩阵）出现，可能漏实现：${uncovered.join(', ')}`,
+            });
+        }
+    }
+    // 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;
+    const summary = passed
+        ? `规格校验通过（${frIds.length} 条需求${warningCount ? `，${warningCount} 个提醒` : ''}）`
+        : `规格校验未通过：${errorCount} 个必须修复的问题${warningCount ? `、${warningCount} 个提醒` : ''}`;
+    return { passed, errorCount, warningCount, issues, frIds, summary };
+}

package/build/lib/template-loader.js

@@ -14,8 +14,8 @@ const TEMPLATE_VALIDATORS = {
         requiredFields: ['技术选型'],
     },
     'specs/feature/tasks.md': {
-        requiredSections: ['概述', '任务列表', '检查点', '文件变更清单'],
-        requiredFields: ['阶段 1', '阶段 2', '阶段 3'],
+        requiredSections: ['概述', '交付物清单', '任务列表', '检查点', '文件变更清单'],
+        requiredFields: ['阶段 1', '阶段 2', '阶段 3', '证据块'],
     },
 };
 const EMBEDDED_TEMPLATES = {
@@ -25,6 +25,15 @@ const EMBEDDED_TEMPLATES = {
 
 {description}
 
+> 用一段话点明"做什么、给谁用、解决什么问题"。
+
+## 历史经验与坑（来自记忆库）
+
+> 开干前先看 start_feature 注入的「⚠️ 历史坑 / ♻️ 可复用经验」，把与本功能相关的条目落到这里；没有就写"暂无"。
+
+- **可复用经验**: [填写：可直接复用的历史模式/做法]
+- **必须规避的坑**: [填写：历史同类问题的根因与规避方式]
+
 ## 术语定义
 
 - **[术语1]**: [填写：定义]
@@ -32,44 +41,68 @@ const EMBEDDED_TEMPLATES = {
 
 ---
 
+## 范围边界
+
+**In Scope（本次要做）**
+- [填写：明确纳入本次的能力点]
+
+**Out of Scope（本次不做，避免过度实现）**
+- [填写：明确排除的能力点；没有就写"暂无"]
+
+---
+
 ## 需求列表
 
-### 需求 1: [填写：需求标题]
+> 每条需求一个稳定 ID（FR-1、FR-2…）。该 ID 会被 design.md 与 tasks.md 引用，三处必须一致。
+
+### FR-1: [填写：需求标题]
 
+**优先级:** [填写：Must / Should / Could]（MoSCoW）
 **用户故事:** 作为 [填写：角色]，我想要 [填写：功能]，以便 [填写：目标]。
 
-#### 验收标准
+#### 验收标准（EARS）
 
 1. WHEN [填写：触发条件] THEN 系统 SHALL [填写：响应]
 2. WHILE [填写：状态条件] THE 系统 SHALL [填写：响应]
 3. IF [填写：异常条件] THEN 系统 SHALL [填写：处理方式]
 
----
+### FR-2: [填写：需求标题]
 
-## 非功能需求
+**优先级:** [填写：Must / Should / Could]
+**用户故事:** 作为 [填写：角色]，我想要 [填写：功能]，以便 [填写：目标]。
+
+#### 验收标准（EARS）
+
+1. WHEN [填写：触发条件] THEN 系统 SHALL [填写：响应]
+2. IF [填写：异常条件] THEN 系统 SHALL [填写：处理方式]
+
+> 按实际拆分增减 FR-n；每条需求应可独立验收。
 
-### 性能要求
-- [填写：性能相关需求]
+---
 
-### 安全要求
-- [填写：安全相关需求]
+## 非功能需求
 
-### 兼容性要求
-- [填写：兼容性相关需求]
+- **NFR-1（性能）**: [填写：尽量给可量化指标]
+- **NFR-2（安全）**: [填写：安全相关需求]
+- **NFR-3（兼容性）**: [填写：兼容性相关需求]
 
 ---
 
 ## 依赖关系
 
-- [填写：列出与其他功能的依赖]
+- [填写：列出与其他功能/模块/外部服务的依赖]
 
 ---
 
 ## 检查清单
 
+- [ ] 已消化记忆库的历史经验，并逐条规避「历史坑」
 - [ ] 需求覆盖核心场景与边界场景
-- [ ] 验收标准使用 EARS 格式
-- [ ] 非功能需求明确
+- [ ] 每条需求有唯一 ID（FR-n），将在 design.md / tasks.md 中被引用
+- [ ] 验收标准使用 EARS 格式且可测
+- [ ] 已标注优先级（MoSCoW）
+- [ ] 范围边界（In/Out of Scope）明确
+- [ ] 非功能需求明确、尽量可量化
 - [ ] 依赖关系完整
 `,
     'specs/feature/guided/design.md': `# 设计文档：{feature_name}
@@ -78,7 +111,10 @@ const EMBEDDED_TEMPLATES = {
 
 {description}
 
-本设计文档描述 {feature_name} 功能的技术实现方案。
+本设计描述 {feature_name} 功能的技术实现方案。
+
+**对应需求:** [填写：本设计覆盖的需求 ID，如 FR-1, FR-2, NFR-1]
+> 设计应覆盖 requirements.md 的全部 FR；某条 FR 不在本设计范围请在此注明原因。
 
 ---
 
@@ -86,13 +122,13 @@ const EMBEDDED_TEMPLATES = {
 
 ### 技术选型
 
-| 类别 | 选择 | 理由 |
-|------|------|------|
-| [填写：类别] | [填写：技术] | [填写：选择理由] |
+| 类别 | 选择 | 理由 | 关联需求 |
+|------|------|------|----------|
+| [填写：类别] | [填写：技术] | [填写：选择理由] | [填写：FR-n] |
 
 ### 架构设计
 
-[填写：描述功能的架构设计，参考项目现有架构]
+[填写：描述功能的架构设计，参考项目现有架构与目录约定]
 
 \`\`\`
 [填写：架构图或流程图，使用 ASCII 或 Mermaid]
@@ -102,19 +138,27 @@ const EMBEDDED_TEMPLATES = {
 
 ## 数据模型
 
-[填写：如果功能涉及数据存储，描述数据模型]
+[填写：若涉及数据存储，给出实体/字段/类型/约束；无则写"不涉及"]
+
+| 实体/字段 | 类型 | 约束 | 说明 |
+|-----------|------|------|------|
+| [填写] | [填写] | [填写] | [填写] |
 
 ---
 
 ## API 设计
 
-[填写：如果功能涉及 API，描述 API 设计]
+[填写：若涉及对外接口/函数契约，给出签名与出入参；无则写"不涉及"]
+
+| 方法/函数 | 路径/签名 | 入参 | 出参 | 关联需求 |
+|-----------|-----------|------|------|----------|
+| [填写] | [填写] | [填写] | [填写] | [填写：FR-n] |
 
 ---
 
 ## 文件结构
 
-[填写：描述功能涉及的文件和目录]
+[填写：对照项目上下文与代码图谱列出新增/修改的真实文件路径，勿臆造]
 
 \`\`\`
 [项目目录]/
@@ -127,7 +171,7 @@ const EMBEDDED_TEMPLATES = {
 
 ## 设计决策
 
-### 决策 1: [填写：决策标题]
+### 决策 1: [填写：决策标题]（关联需求: [填写：FR-n]）
 
 **问题**: [填写：描述面临的问题]
 
@@ -141,6 +185,12 @@ const EMBEDDED_TEMPLATES = {
 
 ---
 
+## 测试策略
+
+[填写：如何验证本设计满足各 FR 的验收标准——单测/集成/手测要点]
+
+---
+
 ## 风险评估
 
 | 风险 | 影响 | 缓解措施 |
@@ -152,40 +202,73 @@ const EMBEDDED_TEMPLATES = {
 ## 检查清单
 
 - [ ] 技术方案与现有架构一致
-- [ ] 数据模型与接口定义清晰
-- [ ] 关键设计决策已记录
+- [ ] requirements.md 中每条 FR 都被本设计覆盖（或注明不涉及）
+- [ ] 文件结构对照真实代码库，路径可定位
+- [ ] 数据模型 / 接口契约清晰（含类型与约束）
+- [ ] 关键设计决策已记录并关联需求
+- [ ] 测试策略可验证验收标准
 `,
     'specs/feature/guided/tasks.md': `# 任务清单：{feature_name}
 
 ## 概述
 
-实现 {feature_name} 功能的任务分解。
+实现 {feature_name} 功能的任务分解。每条任务都要回链到需求（FR）与设计章节，确保不漏、不越界。
+
+> **二元禁令（零容忍）**：本文件及后续实现的交付物中，禁止出现 \`[填写]\`、\`TODO\`、\`// ...\`、省略号占位。
+> 这不是"尽量"，是"零"。任何用占位符代替真实内容的行为都视为未完成。
+
+---
+
+## 交付物清单（Scope-lock）
+
+> 先数清楚要产出什么，锁定数量。实现完成前必须回读本清单逐项核对，数量对不上即未完成。
+
+- **预计新建文件数**: [填写：N 个]
+- **预计修改文件数**: [填写：N 个]
+- **预计新增/修改函数数**: [填写：约 N 个]
+- **交付物逐项列举**:
+  1. [填写：交付物 1，如 src/auth/login.ts]
+  2. [填写：交付物 2]
 
 ---
 
 ## 任务列表
 
+> **每条任务的硬性结构**（缺一不可）：
+> 1. **标题**：[动词] + [对象] + [约束/验收点]。如"实现登录接口 POST /api/login，校验邮箱格式并返回 JWT"。
+>    - ❌ 反例（过于宽泛，会被打回）："优化登录"、"处理用户模块"
+> 2. **证据块**：动手前先读相关代码，贴出关键原文片段（文件:行号 + 代码），证明已理解现状再改。
+> 3. **涉及文件 + 行数预算**：列出本任务触及的文件；单文件预计超 500 行时，必须在此写明拆分方案（拆成哪些模块/组件）。
+> 4. **回链**：标注 _需求: FR-n_ 与 _设计: 章节_。
+
 ### 阶段 1: 准备工作
 
-- [ ] 1.1 [填写：任务标题]
-  - [填写：具体操作说明]
-  - _需求: [填写：对应的需求编号]_
+- [ ] 1.1 [填写：动词+对象+约束的具体标题]
+  - **证据块**: [填写：先读 \`文件:行号\`，贴出现状关键片段]
+  - **涉及文件**: [填写：路径 + 行数预算；超 500 行写拆分方案]
+  - _需求: [填写：FR-n]_ ｜ _设计: [填写：design.md 章节]_
 
 ---
 
 ### 阶段 2: 核心实现
 
-- [ ] 2.1 [填写：任务标题]
-  - [填写：具体操作说明]
-  - _需求: [填写：对应的需求编号]_
+- [ ] 2.1 [填写：动词+对象+约束的具体标题]
+  - **证据块**: [填写：先读 \`文件:行号\`，贴出现状关键片段]
+  - **涉及文件**: [填写：路径 + 行数预算；超 500 行写拆分方案]
+  - _需求: [填写：FR-n]_ ｜ _设计: [填写：design.md 章节]_
+- [ ] 2.2 [填写：动词+对象+约束的具体标题]
+  - **证据块**: [填写：先读 \`文件:行号\`，贴出现状关键片段]
+  - **涉及文件**: [填写：路径 + 行数预算；超 500 行写拆分方案]
+  - _需求: [填写：FR-n]_ ｜ _设计: [填写：design.md 章节]_
 
 ---
 
 ### 阶段 3: 集成测试
 
-- [ ] 3.1 [填写：任务标题]
-  - [填写：具体操作说明]
-  - _需求: [填写：对应的需求编号]_
+- [ ] 3.1 [填写：动词+对象+约束的标题（对照验收标准逐条核验）]
+  - **证据块**: [填写：先读相关测试/接口现状]
+  - **涉及文件**: [填写：测试文件路径]
+  - _需求: [填写：FR-n]_ ｜ _设计: [填写：design.md 章节]_
 
 ---
 
@@ -197,19 +280,36 @@ const EMBEDDED_TEMPLATES = {
 
 ---
 
+## 需求覆盖矩阵
+
+> 自检：每条 FR 至少对应一个任务；每个任务都能追到某条 FR。空缺即风险。
+
+| 需求 ID | 设计章节 | 任务编号 | 状态 |
+|---------|----------|----------|------|
+| [填写：FR-1] | [填写：design 章节] | [填写：1.1, 2.1] | 未开始 |
+| [填写：FR-2] | [填写：design 章节] | [填写：2.2] | 未开始 |
+
+---
+
 ## 文件变更清单
 
-| 文件 | 操作 | 说明 |
-|------|------|------|
-| [填写：文件路径] | 新建/修改 | [填写：说明] |
+| 文件 | 操作 | 行数预算 | 说明 |
+|------|------|----------|------|
+| [填写：文件路径] | 新建/修改 | [填写：预计行数] | [填写：说明] |
 
 ---
 
 ## 检查清单
 
-- [ ] 任务分阶段合理
-- [ ] 每项任务可执行且可验证
-- [ ] 任务与需求一一对应
+- [ ] 交付物清单（Scope-lock）已填，实现后数量已逐项核对
+- [ ] 每条任务标题是"动词+对象+约束"的具体描述，无宽泛标题
+- [ ] 每条任务含证据块（先读后写）
+- [ ] 每条任务标注涉及文件与行数预算，超 500 行的有拆分方案
+- [ ] 任务分阶段合理，粒度可在单次提交内完成
+- [ ] 每条任务都回链到 FR 与 design 章节
+- [ ] 需求覆盖矩阵已填，无遗漏的 FR
+- [ ] 阶段 3 包含"对照验收标准核验"
+- [ ] 全文无 \`[填写]\` / \`TODO\` / 省略号占位（二元禁令）
 `,
     'specs/feature/strict/requirements.md': `# 需求文档：{feature_name}
 
@@ -217,24 +317,43 @@ const EMBEDDED_TEMPLATES = {
 
 {description}
 
+## 历史经验与坑（来自记忆库）
+
+> 把 start_feature 注入的相关「坑 / 可复用经验」落到这里；无则写"暂无"。
+
+- **可复用经验**: [填写]
+- **必须规避的坑**: [填写]
+
+---
+
+## 范围边界
+
+- **In Scope**: [填写：本次纳入]
+- **Out of Scope**: [填写：本次排除；无则写"暂无"]
+
 ---
 
 ## 需求列表
 
-### 需求 1: [填写：需求标题]
+> 每条需求一个稳定 ID（FR-n），design.md 与 tasks.md 引用时必须一致。
 
+### FR-1: [填写：需求标题]
+
+**优先级:** [填写：Must / Should / Could]
 **用户故事:** 作为 [填写：角色]，我想要 [填写：功能]，以便 [填写：目标]。
 
-#### 验收标准
+#### 验收标准（EARS）
 
 1. WHEN [填写：触发条件] THEN 系统 SHALL [填写：响应]
 2. IF [填写：异常条件] THEN 系统 SHALL [填写：处理方式]
 
+> 按需增加 FR-2、FR-3…
+
 ---
 
 ## 非功能需求
 
-- [填写：性能/安全/兼容性]
+- **NFR-1**: [填写：性能/安全/兼容性，尽量可量化]
 
 ---
 
@@ -248,15 +367,17 @@ const EMBEDDED_TEMPLATES = {
 
 {description}
 
+**对应需求:** [填写：覆盖的 FR/NFR ID，如 FR-1, FR-2]
+
 ---
 
 ## 技术方案
 
 ### 技术选型
 
-| 类别 | 选择 | 理由 |
-|------|------|------|
-| [填写：类别] | [填写：技术] | [填写：理由] |
+| 类别 | 选择 | 理由 | 关联需求 |
+|------|------|------|----------|
+| [填写：类别] | [填写：技术] | [填写：理由] | [填写：FR-n] |
 
 ### 架构设计
 
@@ -266,27 +387,27 @@ const EMBEDDED_TEMPLATES = {
 
 ## 数据模型
 
-[填写：数据结构或表设计]
+[填写：数据结构或表设计（字段/类型/约束）；无则写"不涉及"]
 
 ---
 
 ## API 设计
 
-| 方法 | 路径 | 描述 |
-|------|------|------|
-| [填写：GET/POST/...] | [填写：/path] | [填写：描述] |
+| 方法/函数 | 路径/签名 | 入参/出参 | 关联需求 |
+|------|------|------|----------|
+| [填写：GET/POST/...] | [填写：/path] | [填写] | [填写：FR-n] |
 
 ---
 
 ## 文件结构
 
-[填写：涉及的文件]
+[填写：对照真实代码库列出新增/修改文件，勿臆造路径]
 
 ---
 
 ## 设计决策
 
-### 决策 1: [填写：决策标题]
+### 决策 1: [填写：决策标题]（关联需求: [填写：FR-n]）
 
 **问题**: [填写：问题]
 **选项**: [填写：选项]
@@ -304,27 +425,52 @@ const EMBEDDED_TEMPLATES = {
 
 ## 概述
 
-实现 {feature_name} 的任务分解。
+实现 {feature_name} 的任务分解；每条任务回链 FR 与 design 章节。
+
+> **二元禁令**：交付物中零容忍 \`[填写]\` / \`TODO\` / \`// ...\` 等占位。动手前先读相关代码贴出证据，再写实现。单文件超 500 行必须拆分。
+
+---
+
+## 交付物清单（Scope-lock）
+
+- 预计文件数: [填写：N]
+- 预计任务数: [填写：N]
+
+> 实现完成前回读本清单逐项核对，数量不符即未完成。
 
 ---
 
 ## 任务列表
 
+> 每条任务标题须为「[动词]+[对象]+[约束]」的具体写法（如「新建 auth.service.ts 实现 JWT 签发，≤120 行」），禁止「优化登录」式宽泛描述。
+
 ### 阶段 1: 准备工作
 
-- [ ] 1.1 [填写：任务标题]
+- [ ] 1.1 [填写：动词+对象+约束]
+  - 证据块: [填写：动手前需读的文件:行号]
+  - 文件: [填写：路径]（预算 [填写] 行，超 500 行拆分）
+  - _需求: [填写：FR-n]_ · _设计: [填写：章节]_
 
 ---
 
 ### 阶段 2: 核心实现
 
-- [ ] 2.1 [填写：任务标题]
+- [ ] 2.1 [填写：动词+对象+约束]
+  - 证据块: [填写：文件:行号]
+  - 文件: [填写：路径]（预算 [填写] 行）
+  - _需求: [填写：FR-n]_ · _设计: [填写：章节]_
+- [ ] 2.2 [填写：动词+对象+约束]
+  - 证据块: [填写：文件:行号]
+  - 文件: [填写：路径]（预算 [填写] 行）
+  - _需求: [填写：FR-n]_ · _设计: [填写：章节]_
 
 ---
 
 ### 阶段 3: 集成测试
 
-- [ ] 3.1 [填写：任务标题]
+- [ ] 3.1 [填写：动词+对象+约束（对照验收标准逐条核验）]
+  - 验收点: [填写：对应哪条验收标准]
+  - _需求: [填写：FR-n]_
 
 ---
 
@@ -336,11 +482,27 @@ const EMBEDDED_TEMPLATES = {
 
 ---
 
+## 需求覆盖矩阵
+
+| 需求 ID | 设计章节 | 任务编号 | 状态 |
+|---------|----------|----------|------|
+| [填写：FR-1] | [填写：design 章节] | [填写：任务号] | 未开始 |
+
+---
+
 ## 文件变更清单
 
-| 文件 | 操作 | 说明 |
-|------|------|------|
-| [填写：文件路径] | 新建/修改 | [填写：说明] |
+| 文件 | 操作 | 行数预算 | 说明 |
+|------|------|----------|------|
+| [填写：文件路径] | 新建/修改 | [填写：≤500] | [填写：说明] |
+
+---
+
+## 交付前自检
+
+- [ ] 无占位符 / TODO / 省略注释
+- [ ] 交付物数量与 Scope-lock 一致
+- [ ] 每个文件 ≤ 500 行、每条任务回链 FR
 `,
 };
 export function normalizeTemplateProfile(input) {

package/build/lib/tool-annotations.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 工具注解（MCP Tool Annotations）集中映射
+ *
+ * 注解是给客户端的「提示」（非安全保证）：客户端据此决定是否自动放行、是否提示用户等。
+ * - readOnlyHint:    工具不改动其环境（不写用户源码/项目状态）
+ * - idempotentHint:  相同入参重复调用无额外副作用
+ * - destructiveHint: 可能做破坏性更新（仅在非只读时有意义）
+ * - openWorldHint:   会与外部实体交互（HTTP/外部进程），结果可能非确定
+ *
+ * 分类：
+ *  - 只读指南型：仅基于输入/内嵌数据计算并返回指南/计划，不碰用户源码、不触外部
+ *  - 只读+openWorld：查 Qdrant / 跑 gitnexus 分析 / 结果随仓库或外部变化
+ *  - 写型：落盘 / 写记忆 / 写缓存（均为非破坏性追加，destructive=false）
+ */
+export interface ToolAnnotations {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+export declare const TOOL_ANNOTATIONS: Record<string, ToolAnnotations>;
+/**
+ * 把注解合并进工具定义（用于 ListTools 返回前）。
+ */
+export declare function withToolAnnotations<T extends {
+    name: string;
+}>(tool: T): T & {
+    annotations?: ToolAnnotations;
+};