mcp-probe-kit 3.0.3 → 3.0.6

package/docs/specs/git-work-report/design.md

@@ -1,568 +0,0 @@
-# 设计文档：git-work-report
-
-## 概述
-
-本设计文档描述 git-work-report 功能的技术实现方案。该工具作为 MCP Probe Kit 的新工具，遵循现有的工具架构模式，通过 MCP 协议提供服务。
-
-**设计目标：**
-- 与现有工具架构保持一致
-- 高效处理 Git 命令执行
-- 提供清晰的错误处理
-- 支持结构化输出
-
----
-
-## 技术方案
-
-### 技术选型
-
-| 类别 | 选择 | 理由 |
-|------|------|------|
-| 语言 | TypeScript | 与项目现有技术栈一致 |
-| Git 交互 | child_process (promisify) | Node.js 标准库，无需额外依赖 |
-| 日期处理 | 原生 Date + 字符串格式化 | 避免引入额外依赖（如 moment.js） |
-| 输出格式化 | formatResponse (现有工具) | 保持输出格式一致性 |
-| Schema 定义 | JSON Schema | 符合 MCP 协议规范 |
-
-### 架构设计
-
-```
-用户请求 (MCP Client)
-    ↓
-MCP 服务器 (src/index.ts)
-    ↓
-git_work_report 工具 (src/tools/git_work_report.ts)
-    ↓
-    ├─→ 参数验证
-    ├─→ Git 命令执行 (child_process)
-    │   ├─→ git log (获取提交列表)
-    │   └─→ git show (获取每个提交的 diff)
-    ├─→ Diff 内容聚合
-    ├─→ AI 分析提示构建
-    └─→ 返回结构化输出
-```
-
-### 工作流程
-
-```
-1. 参数验证
-   ├─ 检查日期参数是否提供
-   ├─ 验证日期格式 (YYYY-MM-DD)
-   └─ 检查参数冲突
-
-2. 获取提交列表
-   ├─ 构建 git log 命令
-   ├─ 执行命令获取提交哈希列表
-   └─ 处理无提交情况
-
-3. 获取 Diff 内容
-   ├─ 遍历提交哈希列表
-   ├─ 对每个提交执行 git show
-   └─ 聚合所有 diff 内容
-
-4. 构建 AI 分析提示
-   ├─ 组装 diff 内容
-   ├─ 添加分析要求
-   └─ 格式化输出指令
-
-5. 返回结果
-   ├─ 使用 formatResponse 格式化
-   ├─ 可选：写入输出文件
-   └─ 返回给 MCP 客户端
-```
-
----
-
-## 数据模型
-
-### 输入参数接口
-
-```typescript
-interface GitWorkReportArgs {
-  date?: string;          // 单个日期 (YYYY-MM-DD)
-  start_date?: string;    // 起始日期 (YYYY-MM-DD)
-  end_date?: string;      // 结束日期 (YYYY-MM-DD)
-  output_file?: string;   // 输出文件路径
-}
-```
-
-### 内部数据结构
-
-```typescript
-interface CommitInfo {
-  hash: string;           // 提交哈希
-  diff: string;           // diff 内容
-}
-
-interface DateRange {
-  start: string;          // 开始日期时间 (YYYY-MM-DD HH:mm:ss)
-  end: string;            // 结束日期时间 (YYYY-MM-DD HH:mm:ss)
-}
-```
-
----
-
-## API 设计
-
-### MCP 工具 Schema
-
-```typescript
-export const gitWorkReportSchema: Tool = {
-  name: "git_work_report",
-  description: `基于 Git diff 分析生成工作报告（日报/周期报）
-
-核心功能：
-- 支持日报模式（单个日期）和周期报模式（日期范围）
-- 自动读取指定日期的所有 Git 提交
-- 对每个提交执行 git show 获取完整 diff
-- 使用 AI 分析 diff 内容提取实际工作内容
-
-输出格式：
-- 只输出「工作内容」部分
-- 每条以 - 开头，中文，简洁专业
-- 格式：做了什么 + 改了哪里/达到什么效果
-- 不输出：提交哈希、文件列表、统计数据、风险总结
-
-使用示例：
-- 日报：git_work_report --date 2026-1-27
-- 周期报：git_work_report --start_date 2026-2-1 --end_date 2026-2-6`,
-  inputSchema: {
-    type: "object",
-    properties: {
-      date: {
-        type: "string",
-        description: "单个日期，格式 YYYY-MM-DD（日报模式）",
-      },
-      start_date: {
-        type: "string",
-        description: "起始日期，格式 YYYY-MM-DD（周期报模式）",
-      },
-      end_date: {
-        type: "string",
-        description: "结束日期，格式 YYYY-MM-DD（周期报模式）",
-      },
-      output_file: {
-        type: "string",
-        description: "可选，输出文件路径",
-      },
-    },
-  },
-};
-```
-
-### 工具函数签名
-
-```typescript
-export async function gitWorkReport(
-  args: GitWorkReportArgs
-): Promise<ToolResponse>
-```
-
----
-
-## 文件结构
-
-```
-mcp-probe-kit/
-├── src/
-│   ├── tools/
-│   │   ├── git_work_report.ts          # 新增：工具实现
-│   │   ├── index.ts                    # 修改：导出新工具
-│   │   └── __tests__/
-│   │       └── git_work_report.test.ts # 新增：单元测试
-│   ├── schemas/
-│   │   ├── git-tools.ts                # 修改：添加 Schema
-│   │   └── index.ts                    # 修改：导出 Schema
-│   └── index.ts                        # 修改：注册工具路由
-├── docs/
-│   └── specs/
-│       └── git-work-report/            # 新增：规格文档目录
-│           ├── requirements.md
-│           ├── design.md
-│           └── tasks.md
-└── README.md                           # 修改：更新工具列表
-```
-
----
-
----
-
-## 返回格式说明
-
-### 工具输出
-
-`git_work_report` 作为原子工具，直接返回 text 格式的内容，而不是委托式执行计划（step）。
-
-**返回内容：**
-1. **有提交时**: 返回包含所有 diff 和分析要求的 AI 提示文本
-2. **无提交时**: 返回 "- 当日无代码提交（Git 无 commit 记录）"
-3. **错误时**: 返回错误信息
-
-**示例输出（有提交）：**
-```
-请分析以下 Git diff 内容，提取实际工作内容：
-
-diff --git a/src/auth.ts b/src/auth.ts
-+++ b/src/auth.ts
-@@ -10,6 +10,12 @@
-+export function validateToken(token: string) {
-+  // JWT 验证逻辑
-+}
-
----
-
-diff --git a/src/api.ts b/src/api.ts
-...
-
-要求：
-- 只输出「工作内容」部分
-- 每条以 - 开头
-- 中文，简洁专业，避免空话
-- 格式：做了什么 + 改了哪里/达到什么效果
-...
-```
-
-**AI 处理后的最终输出：**
-```
-- 实现了用户认证功能，添加了 JWT token 验证中间件，提升了 API 安全性
-- 修复了订单列表分页bug，调整了 SQL 查询逻辑，解决了数据重复显示问题
-- 优化了首页加载性能，使用懒加载技术，减少了 40% 的初始加载时间
-```
-
-### 与编排工具的区别
-
-| 特性 | 原子工具 (git_work_report) | 编排工具 (start_*) |
-|------|---------------------------|-------------------|
-| 返回格式 | text | structuredContent with plan |
-| 执行方式 | 直接返回结果 | 返回执行计划，需要按步骤执行 |
-| 用户体验 | 一次调用即可 | 需要多次工具调用 |
-| 适用场景 | 单一功能 | 复杂工作流 |
-
----
-
-## 核心实现
-
-### 完整工作流程
-
-```typescript
-export async function gitWorkReport(args: GitWorkReportArgs) {
-  try {
-    // 1. 参数验证
-    validateArgs(args);
-
-    // 2. 构建日期范围（用户输入日期，内部转换为完整时间）
-    const dateRange = buildDateRange(args);
-    // 例如：date="2026-1-27" -> {start: "2026-1-27 00:00:00", end: "2026-1-27 23:59:59"}
-
-    // 3. 获取提交列表
-    const commitList = await getCommitList(dateRange);
-
-    if (commitList.length === 0) {
-      const message = "- 当日无代码提交（Git 无 commit 记录）";
-      
-      if (args.output_file) {
-        await writeOutputFile(args.output_file, message);
-      }
-      
-      return formatResponse(message);
-    }
-
-    // 4. 获取每个提交的 diff
-    const diffPromises = commitList.map(hash => getCommitDiff(hash));
-    const diffs = await Promise.all(diffPromises);
-
-    // 5. 构建 AI 分析提示
-    const analysisPrompt = buildAnalysisPrompt(diffs);
-
-    // 6. 可选：写入输出文件
-    if (args.output_file) {
-      await writeOutputFile(args.output_file, analysisPrompt);
-    }
-
-    // 7. 返回 AI 分析提示（MCP 客户端的 AI 会处理并生成最终报告）
-    return formatResponse(analysisPrompt);
-
-  } catch (error) {
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    return formatResponse(`错误: ${errorMessage}`, true);
-  }
-}
-```
-
-### 1. 参数验证
-
-```typescript
-function validateArgs(args: GitWorkReportArgs): void {
-  const isDaily = !!args.date;
-  const isPeriod = !!(args.start_date && args.end_date);
-  
-  if (!isDaily && !isPeriod) {
-    throw new Error("请提供 date（日报）或 start_date + end_date（周期报）");
-  }
-  
-  if (isDaily && isPeriod) {
-    throw new Error("不能同时使用日报和周期报模式");
-  }
-  
-  // 验证日期格式
-  const dateRegex = /^\d{4}-\d{2}-\d{2}$/;
-  if (args.date && !dateRegex.test(args.date)) {
-    throw new Error("日期格式错误，应为 YYYY-MM-DD");
-  }
-  
-  if (isPeriod) {
-    if (!dateRegex.test(args.start_date!) || !dateRegex.test(args.end_date!)) {
-      throw new Error("日期格式错误，应为 YYYY-MM-DD");
-    }
-    if (args.start_date! > args.end_date!) {
-      throw new Error("结束日期不能早于开始日期");
-    }
-  }
-}
-```
-
-### 2. 日期范围构建
-
-```typescript
-function buildDateRange(args: GitWorkReportArgs): DateRange {
-  if (args.date) {
-    // 日报模式：用户输入 "2026-1-27"，转换为完整时间范围
-    return {
-      start: `${args.date} 00:00:00`,
-      end: `${args.date} 23:59:59`,
-    };
-  } else {
-    // 周期报模式：用户输入日期范围，转换为完整时间范围
-    return {
-      start: `${args.start_date} 00:00:00`,
-      end: `${args.end_date} 23:59:59`,
-    };
-  }
-}
-```
-
-### 3. Git 命令执行
-
-```typescript
-import { exec } from "child_process";
-import { promisify } from "util";
-
-const execAsync = promisify(exec);
-
-function buildDateRange(args: GitWorkReportArgs): DateRange {
-  if (args.date) {
-    // 日报模式：单个日期转换为完整时间范围
-    return {
-      start: `${args.date} 00:00:00`,
-      end: `${args.date} 23:59:59`,
-    };
-  } else {
-    // 周期报模式：日期范围转换为完整时间范围
-    return {
-      start: `${args.start_date} 00:00:00`,
-      end: `${args.end_date} 23:59:59`,
-    };
-  }
-}
-
-async function getCommitList(dateRange: DateRange): Promise<string[]> {
-  const gitCommand = `git log --since="${dateRange.start}" --until="${dateRange.end}" --format=%H`;
-  
-  try {
-    const { stdout } = await execAsync(gitCommand);
-    return stdout.trim().split('\n').filter(Boolean);
-  } catch (error) {
-    throw new Error(`Git 命令执行失败: ${error.message}`);
-  }
-}
-
-async function getCommitDiff(hash: string): Promise<string> {
-  try {
-    const { stdout } = await execAsync(`git show ${hash}`);
-    return stdout;
-  } catch (error) {
-    throw new Error(`获取提交 ${hash} 的 diff 失败: ${error.message}`);
-  }
-}
-```
-
-### 3. Git 命令执行
-
-```typescript
-async function getCommitList(dateRange: DateRange): Promise<string[]> {
-  // 使用完整时间范围查询
-  const gitCommand = `git log --since="${dateRange.start}" --until="${dateRange.end}" --format=%H`;
-  
-  try {
-    const { stdout } = await execAsync(gitCommand);
-    return stdout.trim().split('\n').filter(Boolean);
-  } catch (error) {
-    throw new Error(`Git 命令执行失败: ${error.message}`);
-  }
-}
-
-async function getCommitDiff(hash: string): Promise<string> {
-  try {
-    const { stdout } = await execAsync(`git show ${hash}`);
-    return stdout;
-  } catch (error) {
-    throw new Error(`获取提交 ${hash} 的 diff 失败: ${error.message}`);
-  }
-}
-```
-
-### 4. AI 分析提示构建
-
-```typescript
-function buildAnalysisPrompt(diffs: string[]): string {
-  return `
-请分析以下 Git diff 内容，提取实际工作内容：
-
-${diffs.join('\n\n---\n\n')}
-
-要求：
-- 只输出「工作内容」部分
-- 每条以 - 开头
-- 中文，简洁专业，避免空话
-- 格式：做了什么 + 改了哪里/达到什么效果
-- 不输出：提交哈希、文件列表原文、统计数据、风险评估、总结段落
-
-示例输出：
-- 实现了用户认证功能，添加了 JWT token 验证中间件，提升了 API 安全性
-- 修复了订单列表分页bug，调整了 SQL 查询逻辑，解决了数据重复显示问题
-- 优化了首页加载性能，使用懒加载技术，减少了 40% 的初始加载时间
-`;
-}
-```
-
-### 4. AI 分析提示构建
-
-```typescript
-function buildAnalysisPrompt(diffs: string[]): string {
-  return `
-请分析以下 Git diff 内容，提取实际工作内容：
-
-${diffs.join('\n\n---\n\n')}
-
-要求：
-- 只输出「工作内容」部分
-- 每条以 - 开头
-- 中文，简洁专业，避免空话
-- 格式：做了什么 + 改了哪里/达到什么效果
-- 不输出：提交哈希、文件列表原文、统计数据、风险评估、总结段落
-
-示例输出：
-- 实现了用户认证功能，添加了 JWT token 验证中间件，提升了 API 安全性
-- 修复了订单列表分页bug，调整了 SQL 查询逻辑，解决了数据重复显示问题
-- 优化了首页加载性能，使用懒加载技术，减少了 40% 的初始加载时间
-`;
-}
-```
-
-### 5. 输出文件写入
-
-```typescript
-import { writeFile, mkdir } from "fs/promises";
-import { dirname } from "path";
-
-async function writeOutputFile(filePath: string, content: string): Promise<void> {
-  try {
-    // 确保目录存在
-    await mkdir(dirname(filePath), { recursive: true });
-    // 写入文件
-    await writeFile(filePath, content, 'utf-8');
-  } catch (error) {
-    throw new Error(`写入文件失败: ${error.message}`);
-  }
-}
-```
-
----
-
-## 设计决策
-
-### 决策 1: 使用 AI 分析而非规则提取
-
-**问题**: 如何从 diff 内容中提取工作描述？
-
-**选项**:
-1. **规则匹配**: 使用正则表达式和关键词匹配提取
-2. **AI 分析**: 将 diff 内容交给 AI 模型分析
-
-**决策**: 选择 AI 分析
-
-**理由**: 
-- diff 内容复杂多样，规则难以覆盖所有情况
-- AI 能理解代码语义，生成更准确的描述
-- 符合 MCP Probe Kit 的 AI 驱动理念
-- 用户可以通过 AI 模型获得更自然的语言输出
-
-### 决策 2: 返回格式 - 直接返回 AI 分析提示
-
-**问题**: 工具应该返回什么格式的内容？
-
-**选项**:
-1. **返回 text**: 返回包含 diff 和分析要求的提示文本，由 AI 生成最终报告
-2. **返回 step**: 返回委托式执行计划，需要用户再执行步骤
-
-**决策**: 选择返回 text
-
-**理由**:
-- 这是原子工具，不是编排工具（`start_*`）
-- 用户期望直接获得报告，不需要额外步骤
-- 符合项目中其他基础工具的模式（如 `gencommit`、`code_review`）
-- step 模式仅适用于需要多步骤编排的 `start_*` 工具
-
-### 决策 3: 不在工具内直接调用 AI
-
-**问题**: 工具是否应该直接调用 AI 模型？
-
-**选项**:
-1. **工具内调用**: 在工具中集成 AI SDK，直接生成报告
-2. **返回提示**: 返回分析提示，由 MCP 客户端的 AI 处理
-
-**决策**: 选择返回提示
-
-**理由**:
-- 保持工具轻量，不引入额外的 AI SDK 依赖
-- 利用 MCP 客户端已有的 AI 能力
-- 用户可以根据需要调整 AI 模型和参数
-- 符合 MCP 协议的设计理念
-
-### 决策 3: 日期时间范围处理
-
-**问题**: 如何处理日期参数的时间范围？
-
-**选项**:
-1. **仅日期**: 使用 `--since=2026-1-27 --until=2026-1-27`
-2. **完整时间**: 使用 `--since="2026-1-27 00:00:00" --until="2026-1-27 23:59:59"`
-
-**决策**: 选择完整时间
-
-**理由**:
-- 确保覆盖整个日期的所有提交（00:00:00 到 23:59:59）
-- 避免时区问题导致的遗漏
-- Git 命令支持完整时间格式
-- 用户输入简洁（只需日期），内部自动转换为完整时间范围
-
----
-
-## 风险评估
-
-| 风险 | 影响 | 缓解措施 |
-|------|------|----------|
-| Git 命令执行失败 | 高 | 完善错误处理，提供清晰的错误信息 |
-| 大量提交导致性能问题 | 中 | 限制最大提交数量，提供进度提示 |
-| Diff 内容过大 | 中 | 限制单个 diff 的大小，超过则截断 |
-| 日期格式不一致 | 低 | 严格验证日期格式，提供示例 |
-| 输出文件路径无效 | 低 | 自动创建目录，验证路径合法性 |
-
----
-
-## 检查清单
-
-- [x] 技术方案与现有架构一致
-- [x] 数据模型与接口定义清晰
-- [x] 关键设计决策已记录
-- [x] 风险评估完整
-- [x] 错误处理方案明确

package/docs/specs/git-work-report/requirements.md

@@ -1,131 +0,0 @@
-# 需求文档：git-work-report
-
-## 功能概述
-
-开发一个基于 Git diff 分析的工作报告生成工具，支持生成日报和周期报（周报、月报等）。该工具通过分析 Git 提交的实际代码变更（diff），而非仅依赖 commit message，智能提取实际工作内容，生成简洁专业的中文工作报告。
-
-**核心价值：**
-- 自动化日报/周报生成，节省手动整理时间
-- 基于实际代码变更分析，内容更准确
-- 输出格式统一规范，便于汇报和存档
-
-## 术语定义
-
-- **日报模式**: 生成单个日期的工作报告
-- **周期报模式**: 生成指定日期范围的工作报告（如周报、月报）
-- **Git diff**: Git 提交中的代码变更内容
-- **工作内容**: 从代码变更中提取的实际开发工作描述
-
----
-
-## 需求列表
-
-### 需求 1: 日报生成
-
-**用户故事:** 作为开发者，我想要生成指定日期的工作日报，以便快速汇报当天的工作内容。
-
-#### 验收标准
-
-1. WHEN 用户提供单个日期参数（如 `--date 2026-1-27`）THEN 系统 SHALL 读取该日期的所有 Git 提交
-2. WHEN 该日期有提交记录 THEN 系统 SHALL 对每个提交执行 `git show` 获取完整 diff
-3. WHEN 该日期无提交记录 THEN 系统 SHALL 输出 "- 当日无代码提交（Git 无 commit 记录）"
-4. WHEN 分析完成 THEN 系统 SHALL 输出符合格式要求的工作内容列表
-
----
-
-### 需求 2: 周期报生成
-
-**用户故事:** 作为开发者，我想要生成指定日期范围的工作报告，以便汇总一段时间的工作内容（如周报、月报）。
-
-#### 验收标准
-
-1. WHEN 用户提供日期范围参数（如 `--start_date 2026-2-1 --end_date 2026-2-6`）THEN 系统 SHALL 读取该范围内的所有 Git 提交
-2. WHEN 日期范围内有提交记录 THEN 系统 SHALL 对每个提交执行 `git show` 获取完整 diff
-3. WHEN 日期范围内无提交记录 THEN 系统 SHALL 输出 "- 当日无代码提交（Git 无 commit 记录）"
-4. WHEN 分析完成 THEN 系统 SHALL 输出符合格式要求的工作内容列表
-
----
-
-### 需求 3: Diff 内容分析
-
-**用户故事:** 作为开发者，我想要工具分析实际的代码变更内容，以便生成准确的工作描述。
-
-#### 验收标准
-
-1. WHEN 获取到提交的 diff 内容 THEN 系统 SHALL 使用 AI 分析代码变更
-2. WHEN 分析 diff THEN 系统 SHALL 识别实际的功能变更、Bug 修复、重构等工作类型
-3. WHEN 提取工作内容 THEN 系统 SHALL 忽略提交哈希、文件列表、统计数据等元信息
-4. WHEN 生成描述 THEN 系统 SHALL 使用"做了什么 + 改了哪里/达到什么效果"的格式
-
----
-
-### 需求 4: 输出格式规范
-
-**用户故事:** 作为开发者，我想要工具输出统一规范的报告格式，以便直接用于汇报。
-
-#### 验收标准
-
-1. WHEN 输出工作内容 THEN 系统 SHALL 只输出「工作内容」部分，无其他章节
-2. WHEN 输出每条内容 THEN 系统 SHALL 以 "- " 开头
-3. WHEN 生成描述 THEN 系统 SHALL 使用中文，简洁专业，避免空话
-4. WHEN 输出报告 THEN 系统 SHALL NOT 包含提交哈希、文件列表原文、统计数据、风险评估、总结段落
-
----
-
-### 需求 5: 参数验证
-
-**用户故事:** 作为开发者，我想要工具验证输入参数，以便及时发现使用错误。
-
-#### 验收标准
-
-1. WHEN 用户未提供日期参数 THEN 系统 SHALL 提示错误信息
-2. WHEN 用户同时提供 `date` 和 `start_date/end_date` THEN 系统 SHALL 提示参数冲突
-3. WHEN 用户提供的日期格式不正确 THEN 系统 SHALL 提示日期格式错误
-4. IF 周期报模式下结束日期早于开始日期 THEN 系统 SHALL 提示日期范围错误
-
----
-
-### 需求 6: 输出文件支持
-
-**用户故事:** 作为开发者，我想要将报告保存到文件，以便存档和分享。
-
-#### 验收标准
-
-1. WHEN 用户提供 `--output_file` 参数 THEN 系统 SHALL 将报告写入指定文件
-2. WHEN 输出文件已存在 THEN 系统 SHALL 覆盖原文件
-3. WHEN 输出文件路径不存在 THEN 系统 SHALL 创建必要的目录
-4. WHEN 写入文件失败 THEN 系统 SHALL 提示错误信息
-
----
-
-## 非功能需求
-
-### 性能要求
-- 单次报告生成时间应在 30 秒内完成（假设提交数量 < 50）
-- 支持处理最多 100 个提交的日期范围
-
-### 安全要求
-- 不应泄露敏感信息（如密码、密钥）到报告中
-- 执行 Git 命令时应防止命令注入
-
-### 兼容性要求
-- 支持 Git 2.0+ 版本
-- 支持 Windows、macOS、Linux 操作系统
-- 与 MCP Probe Kit 现有工具架构兼容
-
----
-
-## 依赖关系
-
-- 依赖 Git 命令行工具（需要在系统中安装）
-- 依赖 Node.js child_process 模块执行 Git 命令
-- 依赖 AI 模型进行 diff 内容分析（通过 MCP 协议）
-
----
-
-## 检查清单
-
-- [x] 需求覆盖核心场景与边界场景
-- [x] 验收标准使用 EARS 格式
-- [x] 非功能需求明确
-- [x] 依赖关系完整