mcp-probe-kit 3.0.24 → 3.2.0

package/build/lib/template-loader.js

@@ -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,24 +202,30 @@ const EMBEDDED_TEMPLATES = {
 ## 检查清单
 
 - [ ] 技术方案与现有架构一致
-- [ ] 数据模型与接口定义清晰
-- [ ] 关键设计决策已记录
+- [ ] requirements.md 中每条 FR 都被本设计覆盖（或注明不涉及）
+- [ ] 文件结构对照真实代码库，路径可定位
+- [ ] 数据模型 / 接口契约清晰（含类型与约束）
+- [ ] 关键设计决策已记录并关联需求
+- [ ] 测试策略可验证验收标准
 `,
     'specs/feature/guided/tasks.md': `# 任务清单：{feature_name}
 
 ## 概述
 
-实现 {feature_name} 功能的任务分解。
+实现 {feature_name} 功能的任务分解。每条任务都要回链到需求（FR）与设计章节，确保不漏、不越界。
 
 ---
 
 ## 任务列表
 
+> 每条任务：动词开头、单一明确、可在一次提交内完成，并标注 _需求_ 与 _设计_。
+> 示例：2.1 实现登录接口 POST /api/login — _需求: FR-1_ ｜ _设计: API 设计_
+
 ### 阶段 1: 准备工作
 
 - [ ] 1.1 [填写：任务标题]
   - [填写：具体操作说明]
-  - _需求: [填写：对应的需求编号]_
+  - _需求: [填写：FR-n]_ ｜ _设计: [填写：design.md 章节]_
 
 ---
 
@@ -177,15 +233,18 @@ const EMBEDDED_TEMPLATES = {
 
 - [ ] 2.1 [填写：任务标题]
   - [填写：具体操作说明]
-  - _需求: [填写：对应的需求编号]_
+  - _需求: [填写：FR-n]_ ｜ _设计: [填写：design.md 章节]_
+- [ ] 2.2 [填写：任务标题]
+  - [填写：具体操作说明]
+  - _需求: [填写：FR-n]_ ｜ _设计: [填写：design.md 章节]_
 
 ---
 
 ### 阶段 3: 集成测试
 
-- [ ] 3.1 [填写：任务标题]
+- [ ] 3.1 [填写：任务标题（对照验收标准逐条核验）]
   - [填写：具体操作说明]
-  - _需求: [填写：对应的需求编号]_
+  - _需求: [填写：FR-n]_ ｜ _设计: [填写：design.md 章节]_
 
 ---
 
@@ -197,6 +256,17 @@ const EMBEDDED_TEMPLATES = {
 
 ---
 
+## 需求覆盖矩阵
+
+> 自检：每条 FR 至少对应一个任务；每个任务都能追到某条 FR。空缺即风险。
+
+| 需求 ID | 设计章节 | 任务编号 | 状态 |
+|---------|----------|----------|------|
+| [填写：FR-1] | [填写：design 章节] | [填写：1.1, 2.1] | 未开始 |
+| [填写：FR-2] | [填写：design 章节] | [填写：2.2] | 未开始 |
+
+---
+
 ## 文件变更清单
 
 | 文件 | 操作 | 说明 |
@@ -207,9 +277,11 @@ const EMBEDDED_TEMPLATES = {
 
 ## 检查清单
 
-- [ ] 任务分阶段合理
+- [ ] 任务分阶段合理，粒度可在单次提交内完成
 - [ ] 每项任务可执行且可验证
-- [ ] 任务与需求一一对应
+- [ ] 每条任务都回链到 FR 与 design 章节
+- [ ] 需求覆盖矩阵已填，无遗漏的 FR
+- [ ] 阶段 3 包含"对照验收标准核验"
 `,
     'specs/feature/strict/requirements.md': `# 需求文档：{feature_name}
 
@@ -217,24 +289,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 +339,17 @@ const EMBEDDED_TEMPLATES = {
 
 {description}
 
+**对应需求:** [填写：覆盖的 FR/NFR ID，如 FR-1, FR-2]
+
 ---
 
 ## 技术方案
 
 ### 技术选型
 
-| 类别 | 选择 | 理由 |
-|------|------|------|
-| [填写：类别] | [填写：技术] | [填写：理由] |
+| 类别 | 选择 | 理由 | 关联需求 |
+|------|------|------|----------|
+| [填写：类别] | [填写：技术] | [填写：理由] | [填写：FR-n] |
 
 ### 架构设计
 
@@ -266,27 +359,27 @@ const EMBEDDED_TEMPLATES = {
 
 ## 数据模型
 
-[填写：数据结构或表设计]
+[填写：数据结构或表设计（字段/类型/约束）；无则写"不涉及"]
 
 ---
 
 ## API 设计
 
-| 方法 | 路径 | 描述 |
-|------|------|------|
-| [填写：GET/POST/...] | [填写：/path] | [填写：描述] |
+| 方法/函数 | 路径/签名 | 入参/出参 | 关联需求 |
+|------|------|------|----------|
+| [填写：GET/POST/...] | [填写：/path] | [填写] | [填写：FR-n] |
 
 ---
 
 ## 文件结构
 
-[填写：涉及的文件]
+[填写：对照真实代码库列出新增/修改文件，勿臆造路径]
 
 ---
 
 ## 设计决策
 
-### 决策 1: [填写：决策标题]
+### 决策 1: [填写：决策标题]（关联需求: [填写：FR-n]）
 
 **问题**: [填写：问题]
 **选项**: [填写：选项]
@@ -304,7 +397,7 @@ const EMBEDDED_TEMPLATES = {
 
 ## 概述
 
-实现 {feature_name} 的任务分解。
+实现 {feature_name} 的任务分解；每条任务回链 FR 与 design 章节。
 
 ---
 
@@ -312,19 +405,20 @@ const EMBEDDED_TEMPLATES = {
 
 ### 阶段 1: 准备工作
 
-- [ ] 1.1 [填写：任务标题]
+- [ ] 1.1 [填写：任务标题] — _需求: [填写：FR-n]_ ｜ _设计: [填写：章节]_
 
 ---
 
 ### 阶段 2: 核心实现
 
-- [ ] 2.1 [填写：任务标题]
+- [ ] 2.1 [填写：任务标题] — _需求: [填写：FR-n]_ ｜ _设计: [填写：章节]_
+- [ ] 2.2 [填写：任务标题] — _需求: [填写：FR-n]_ ｜ _设计: [填写：章节]_
 
 ---
 
 ### 阶段 3: 集成测试
 
-- [ ] 3.1 [填写：任务标题]
+- [ ] 3.1 [填写：任务标题（对照验收标准核验）] — _需求: [填写：FR-n]_
 
 ---
 
@@ -336,6 +430,14 @@ const EMBEDDED_TEMPLATES = {
 
 ---
 
+## 需求覆盖矩阵
+
+| 需求 ID | 设计章节 | 任务编号 | 状态 |
+|---------|----------|----------|------|
+| [填写：FR-1] | [填写：design 章节] | [填写：任务号] | 未开始 |
+
+---
+
 ## 文件变更清单
 
 | 文件 | 操作 | 说明 |

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;
+};

package/build/lib/tool-annotations.js

@@ -0,0 +1,55 @@
+/**
+ * 工具注解（MCP Tool Annotations）集中映射
+ *
+ * 注解是给客户端的「提示」（非安全保证）：客户端据此决定是否自动放行、是否提示用户等。
+ * - readOnlyHint:    工具不改动其环境（不写用户源码/项目状态）
+ * - idempotentHint:  相同入参重复调用无额外副作用
+ * - destructiveHint: 可能做破坏性更新（仅在非只读时有意义）
+ * - openWorldHint:   会与外部实体交互（HTTP/外部进程），结果可能非确定
+ *
+ * 分类：
+ *  - 只读指南型：仅基于输入/内嵌数据计算并返回指南/计划，不碰用户源码、不触外部
+ *  - 只读+openWorld：查 Qdrant / 跑 gitnexus 分析 / 结果随仓库或外部变化
+ *  - 写型：落盘 / 写记忆 / 写缓存（均为非破坏性追加，destructive=false）
+ */
+export const TOOL_ANNOTATIONS = {
+    // —— 只读指南型（可安全自动放行）——
+    init_project: { title: '初始化项目', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    gencommit: { title: '生成提交信息', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    code_review: { title: '代码审查', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    gentest: { title: '生成测试', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    refactor: { title: '重构建议', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    fix_bug: { title: 'Bug 真因分析指南', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    add_feature: { title: '生成功能规格模板', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    estimate: { title: '工作量估算', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    check_spec: { title: '规格完整性校验', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    interview: { title: '需求访谈', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    ask_user: { title: '向用户提问', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    git_work_report: { title: 'Git 工作报告指南', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    ui_design_system: { title: '生成设计系统', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    ui_search: { title: '搜索 UI/UX 数据', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    start_product: { title: '产品设计编排', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    // 返回脚本/文件内容 + delegated plan，由 Agent 落盘 .ralph/——工具自身不写
+    start_ralph: { title: 'Ralph 循环开发编排', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    // 只读扫描本地代码、返回候选模式；不写记忆（存储是 memorize_asset 的事）
+    scan_and_extract_patterns: { title: '扫描并提取模式', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    // —— 只读 + 触外部 / 非确定 ——
+    search_memory: { title: '检索共享记忆', readOnlyHint: true, idempotentHint: false, openWorldHint: true },
+    read_memory_asset: { title: '读取记忆资产', readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    start_ui: { title: 'UI 开发编排', readOnlyHint: true, idempotentHint: false, openWorldHint: true },
+    start_onboard: { title: '项目上手编排', readOnlyHint: true, idempotentHint: false, openWorldHint: true },
+    code_insight: { title: '代码图谱洞察', readOnlyHint: true, idempotentHint: false, openWorldHint: true },
+    start_feature: { title: '新功能开发编排', readOnlyHint: true, idempotentHint: false, openWorldHint: true },
+    start_bugfix: { title: 'Bug 修复编排', readOnlyHint: true, idempotentHint: false, openWorldHint: true },
+    // —— 写型（工具自身落盘 / 写记忆 / 写缓存，非破坏）——
+    init_project_context: { title: '生成项目上下文', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }, // 自己写 docs/.mcp-probe/layout.json（其余为指令）
+    memorize_asset: { title: '沉淀记忆资产', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }, // 写 Qdrant
+    sync_ui_data: { title: '同步 UI 数据', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }, // 下载 + 写缓存
+};
+/**
+ * 把注解合并进工具定义（用于 ListTools 返回前）。
+ */
+export function withToolAnnotations(tool) {
+    const annotations = TOOL_ANNOTATIONS[tool.name];
+    return annotations ? { ...tool, annotations } : tool;
+}

package/build/lib/toolset-manager.js

@@ -21,6 +21,7 @@ export const TOOLSET_DEFINITIONS = {
         'refactor',
         'fix_bug',
         'add_feature',
+        'check_spec',
         'init_project',
         'init_project_context',
         'estimate',
@@ -42,6 +43,7 @@ export const TOOLSET_DEFINITIONS = {
         'refactor',
         'fix_bug',
         'add_feature',
+        'check_spec',
         'init_project',
         'init_project_context',
         'estimate',

package/build/resources/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * MCP Resources 统一导出
+ */
+export { getToolParamsGuide } from "./tool-params-guide.js";

package/build/resources/index.js

@@ -0,0 +1,4 @@
+/**
+ * MCP Resources 统一导出
+ */
+export { getToolParamsGuide } from "./tool-params-guide.js";