mcp-probe-kit 2.0.0 → 2.0.1

package/docs/specs/project-context-modular/requirements.md

@@ -0,0 +1,234 @@
+# 需求文档：project-context-modular
+
+## 功能概述
+
+改进 `init_project_context` 工具，将单一的 `project-context.md` 文件重构为模块化的文档结构。通过将项目信息分类存放到多个独立的 Markdown 文件中，并使用索引文件进行导航，从而优化 AI 开发时的上下文加载效率。
+
+**核心价值**：
+- 减少单次上下文加载量，提高 AI 响应速度
+- 按需加载相关文档，提高开发效率
+- 保持文档的可维护性和可读性
+- 向后兼容现有的单文件模式
+
+---
+
+## 术语定义
+
+- **项目上下文 (Project Context)**: 描述项目技术栈、架构、规范等核心信息的文档集合
+- **索引文件 (Index File)**: 提供项目概览和导航链接的入口文档
+- **模块化模式 (Modular Mode)**: 将项目信息分类存放到多个独立文件的组织方式
+- **单文件模式 (Single Mode)**: 将所有项目信息存放在一个文件中的传统方式
+- **EARS**: Easy Approach to Requirements Syntax，一种结构化的需求编写格式
+
+---
+
+## 需求列表
+
+### 需求 1: 支持模块化文档生成
+
+**用户故事:** 作为开发者，我想要生成模块化的项目上下文文档，以便 AI 可以按需加载相关信息，避免一次性读入过多内容。
+
+#### 验收标准
+
+1. WHEN 用户调用 `init_project_context` 工具并指定 `mode: "modular"` THEN 系统 SHALL 生成索引文件和 5 个分类文档
+2. THE 系统 SHALL 在 `docs/project-context/` 目录下生成以下文件：
+   - `tech-stack.md` - 技术栈信息
+   - `architecture.md` - 架构和项目结构
+   - `coding-standards.md` - 编码规范
+   - `dependencies.md` - 依赖管理
+   - `workflows.md` - 开发流程和命令
+3. THE 系统 SHALL 在 `docs/` 目录下生成索引文件 `project-context.md`
+4. WHEN 生成完成 THEN 系统 SHALL 返回结构化输出，包含所有生成文件的路径
+
+---
+
+### 需求 2: 索引文件设计
+
+**用户故事:** 作为开发者，我想要一个清晰的索引文件，以便快速了解项目概况并导航到具体的文档。
+
+#### 验收标准
+
+1. THE 索引文件 SHALL 包含项目概览表格，包括：名称、版本、类型、描述
+2. THE 索引文件 SHALL 包含文档导航部分，列出所有分类文档及其用途说明
+3. THE 索引文件 SHALL 使用相对路径链接到分类文档
+4. THE 索引文件 SHALL 包含使用指南，说明何时查看哪个文档
+5. THE 索引文件 SHALL 包含生成时间和工具信息
+
+---
+
+### 需求 3: 技术栈文档
+
+**用户故事:** 作为开发者，我想要独立的技术栈文档，以便 AI 在需要了解项目技术选型时快速获取信息。
+
+#### 验收标准
+
+1. THE `tech-stack.md` SHALL 包含语言、运行时、框架信息
+2. THE `tech-stack.md` SHALL 包含构建工具和包管理器信息
+3. THE `tech-stack.md` SHALL 包含测试框架和代码规范工具信息
+4. THE `tech-stack.md` SHALL 从 `package.json` 自动识别主要依赖
+5. THE `tech-stack.md` SHALL 包含技术选型说明（如果可识别）
+
+---
+
+### 需求 4: 架构文档
+
+**用户故事:** 作为开发者，我想要独立的架构文档，以便 AI 在需要理解项目结构时快速获取信息。
+
+#### 验收标准
+
+1. THE `architecture.md` SHALL 包含项目目录树（深度 2-3 层）
+2. THE `architecture.md` SHALL 标注主要目录的用途
+3. THE `architecture.md` SHALL 识别并标注入口文件
+4. THE `architecture.md` SHALL 描述项目类型（MCP服务器/Web应用/库等）
+5. THE `architecture.md` SHALL 识别设计模式（如工具模式、MVC等）
+6. THE `architecture.md` SHALL 描述模块划分方式
+
+---
+
+### 需求 5: 编码规范文档
+
+**用户故事:** 作为开发者，我想要独立的编码规范文档，以便 AI 在生成代码时遵循项目规范。
+
+#### 验收标准
+
+1. THE `coding-standards.md` SHALL 包含代码风格工具配置（ESLint、Prettier）
+2. THE `coding-standards.md` SHALL 包含命名规范表格（文件、变量、常量、函数、类）
+3. THE `coding-standards.md` SHALL 包含 TypeScript 配置（如果是 TS 项目）
+4. THE `coding-standards.md` SHALL 从配置文件自动提取规范信息
+5. IF 配置文件不存在 THEN 系统 SHALL 标注为"未配置"
+
+---
+
+### 需求 6: 依赖管理文档
+
+**用户故事:** 作为开发者，我想要独立的依赖管理文档，以便 AI 在需要了解项目依赖时快速获取信息。
+
+#### 验收标准
+
+1. THE `dependencies.md` SHALL 列出主要生产依赖（前 10 个）及其用途
+2. THE `dependencies.md` SHALL 列出主要开发依赖（前 10 个）及其用途
+3. THE `dependencies.md` SHALL 包含依赖统计信息
+4. THE `dependencies.md` SHALL 自动识别关键依赖的用途
+5. THE `dependencies.md` SHALL 包含依赖版本信息
+
+---
+
+### 需求 7: 工作流文档
+
+**用户故事:** 作为开发者，我想要独立的工作流文档，以便 AI 在需要执行开发任务时快速获取命令。
+
+#### 验收标准
+
+1. THE `workflows.md` SHALL 列出常用开发命令及其用途
+2. THE `workflows.md` SHALL 从 `package.json` 的 `scripts` 字段提取命令
+3. THE `workflows.md` SHALL 识别开发、构建、测试、部署等关键命令
+4. THE `workflows.md` SHALL 包含开发环境要求（Node.js 版本等）
+5. THE `workflows.md` SHALL 包含命令执行说明
+
+---
+
+### 需求 8: 向后兼容性
+
+**用户故事:** 作为开发者，我想要保持向后兼容，以便现有的工作流不受影响。
+
+#### 验收标准
+
+1. WHEN 用户未指定 `mode` 参数 THEN 系统 SHALL 默认使用 `single` 模式
+2. WHEN 用户指定 `mode: "single"` THEN 系统 SHALL 生成单一的 `project-context.md` 文件
+3. THE 单文件模式 SHALL 保持与 v2.0 版本完全相同的行为
+4. THE 系统 SHALL 支持 `mode` 参数的别名：`type`、`format`、`模式`
+
+---
+
+### 需求 9: 文档独立性
+
+**用户故事:** 作为开发者，我想要每个分类文档都是独立完整的，以便可以单独阅读和理解。
+
+#### 验收标准
+
+1. THE 每个分类文档 SHALL 包含必要的上下文信息（项目名称、版本）
+2. THE 每个分类文档 SHALL 有清晰的标题和说明
+3. THE 每个分类文档 SHALL 使用标准的 Markdown 格式
+4. THE 每个分类文档 SHALL 包含生成时间和工具信息
+5. THE 每个分类文档 SHALL 可以独立阅读，无需依赖其他文档
+
+---
+
+### 需求 10: 文档模板提供
+
+**用户故事:** 作为执行 `init_project_context` 工具的 AI 助手，我想要看到需要生成的文件列表和每个文件的格式模板，以便知道要创建哪些文档以及它们的结构。
+
+#### 验收标准
+
+1. THE 工具返回 SHALL 包含"需要生成的文档"列表
+2. THE 列表 SHALL 说明每个文档的文件路径
+3. THE 列表 SHALL 说明每个文档的用途
+4. THE 列表 SHALL 提供每个文档的格式模板（包含结构框架，不包含分析指导）
+5. THE 模板 SHALL 只展示文档结构（标题、表格、章节），不指导如何分析项目
+6. THE 模板 SHALL 使用占位符标记需要填充的内容（如 [填写]、{项目名称}）
+7. THE 工具返回 SHALL 简洁明了，专注于"要生成什么"而非"如何分析"
+
+---
+
+### 需求 11: 错误处理
+
+**用户故事:** 作为开发者，我想要清晰的错误提示，以便在生成失败时快速定位问题。
+
+#### 验收标准
+
+1. IF 无法读取 `package.json` THEN 系统 SHALL 返回错误信息并提示检查文件
+2. IF 无法创建目录 THEN 系统 SHALL 返回错误信息并提示权限问题
+3. IF 无法写入文件 THEN 系统 SHALL 返回错误信息并提示磁盘空间或权限
+4. THE 错误信息 SHALL 包含具体的失败原因和建议的解决方案
+5. THE 系统 SHALL 在结构化输出中标注错误状态
+
+---
+
+## 非功能需求
+
+### 性能要求
+- 文档生成时间应在 2 秒内完成
+- 支持大型项目（1000+ 依赖）的分析
+- 目录树生成应忽略 `node_modules`、`.git` 等大型目录
+
+### 可用性要求
+- 文档格式清晰，易于阅读
+- 索引文件提供清晰的导航
+- 每个文档都有明确的用途说明
+
+### 兼容性要求
+- 支持 Node.js 16.0.0+
+- 支持 Windows、macOS、Linux 平台
+- 兼容所有 MCP 客户端（Cursor、Claude Desktop、Cline 等）
+
+### 可维护性要求
+- 模板代码与业务逻辑分离
+- 支持未来扩展新的文档分类
+- 代码注释清晰，易于理解
+
+---
+
+## 依赖关系
+
+- 依赖现有的 `parseArgs` 工具进行参数解析
+- 依赖现有的 `okStructured` 工具返回结构化输出
+- 依赖 `ProjectContext` Schema 定义（可能需要扩展）
+- 不依赖外部 npm 包，使用 Node.js 内置模块
+
+---
+
+## 优先级
+
+| 需求 | 优先级 | 理由 |
+|------|--------|------|
+| 需求 1-7 | P0 | 核心功能，必须实现 |
+| 需求 8 | P0 | 向后兼容，避免破坏现有用户 |
+| 需求 9 | P1 | 提高文档质量 |
+| 需求 10 | P0 | 核心功能，提供模板 |
+| 需求 11 | P1 | 错误处理 |
+
+---
+
+*文档版本: 1.0.0*  
+*创建时间: 2026-01-27*  
+*维护者: MCP Probe Kit Team*

package/docs/specs/project-context-modular/tasks.md

@@ -0,0 +1,291 @@
+# 任务清单：project-context-modular
+
+## 概述
+
+实现 `project-context-modular` 功能的任务分解。本功能将 `init_project_context` 工具扩展为支持模块化文档生成。
+
+**核心职责划分**：
+- **MCP 工具**: 提供文件列表和格式模板
+- **AI**: 决定分析什么、提取什么、如何填充
+
+**预估总工作量**: 6-10 小时  
+**预估完成时间**: 1-2 个工作日
+
+---
+
+## 任务列表
+
+### 阶段 1: 准备工作（1 小时）
+
+- [x] **1.1 创建模板目录结构**
+  - 在 `src/tools/` 下创建 `templates/` 目录
+  - 创建 6 个模板文件的空文件
+  - _需求: 需求 1_
+  - _预估: 15 分钟_
+
+- [x] **1.2 设计并实现索引文件模板**
+  - 编写 `templates/index-template.ts`
+  - 包含项目概览表格
+  - 包含文档导航部分
+  - 只提供结构模板，不包含分析指导
+  - _需求: 需求 2, 需求 10_
+  - _预估: 30 分钟_
+
+- [x] **1.3 设计并实现技术栈模板**
+  - 编写 `templates/tech-stack-template.ts`
+  - 包含技术栈表格结构
+  - 使用占位符标记需要填充的内容
+  - _需求: 需求 3_
+  - _预估: 15 分钟_
+
+- [x] **1.4 设计并实现架构模板**
+  - 编写 `templates/architecture-template.ts`
+  - 包含目录树、入口文件、设计模式的结构
+  - _需求: 需求 4_
+  - _预估: 15 分钟_
+
+- [x] **1.5 设计并实现编码规范模板**
+  - 编写 `templates/coding-standards-template.ts`
+  - 包含代码风格、命名规范的表格结构
+  - _需求: 需求 5_
+  - _预估: 15 分钟_
+
+- [x] **1.6 设计并实现依赖管理模板**
+  - 编写 `templates/dependencies-template.ts`
+  - 包含依赖表格和统计信息的结构
+  - _需求: 需求 6_
+  - _预估: 10 分钟_
+
+- [x] **1.7 设计并实现工作流模板**
+  - 编写 `templates/workflows-template.ts`
+  - 包含命令表格和环境要求的结构
+  - _需求: 需求 7_
+  - _预估: 10 分钟_
+
+---
+
+### 阶段 2: 核心实现（3-5 小时）✅ 已完成
+
+- [x] **2.1 扩展参数接口**
+  - 在 `init_project_context.ts` 中添加 `mode` 参数支持
+  - 更新 `parseArgs` 调用，添加 `mode` 字段别名
+  - 添加参数验证逻辑
+  - _需求: 需求 1, 需求 8_
+  - _预估: 30 分钟_
+  - _完成时间: 2026-01-27_
+
+- [x] **2.2 实现模板组装函数**
+  - 创建 `assembleTemplates()` 函数
+  - 组装所有模板为结构化输出
+  - 包含文件列表和每个文件的模板内容
+  - _需求: 需求 10_
+  - _预估: 1 小时_
+  - _完成时间: 2026-01-27_
+
+- [x] **2.3 实现模块化模式生成逻辑**
+  - 创建 `generateModularContext()` 函数
+  - 返回包含文档模板的结构化输出
+  - 模板只包含文件结构和格式，不包含分析指导
+  - _需求: 需求 1, 需求 9, 需求 10_
+  - _预估: 1 小时_
+  - _依赖: 任务 2.2_
+  - _完成时间: 2026-01-27_
+
+- [x] **2.4 重构单文件模式逻辑**
+  - 将现有逻辑提取为 `generateSingleContext()` 函数
+  - 保持完全相同的行为
+  - _需求: 需求 8_
+  - _预估: 30 分钟_
+  - _完成时间: 2026-01-27_
+
+- [x] **2.5 实现模式分发逻辑**
+  - 根据 `mode` 参数调用对应的生成函数
+  - 添加错误处理
+  - _需求: 需求 1, 需求 8, 需求 11_
+  - _预估: 20 分钟_
+  - _依赖: 任务 2.3, 2.4_
+  - _完成时间: 2026-01-27_
+
+- [x] **2.6 更新 Schema 定义**
+  - 扩展 `ProjectContext` Schema（如需要）
+  - 添加 `mode` 字段记录使用的模式
+  - 更新实现代码以包含 mode 字段
+  - _需求: 需求 1_
+  - _预估: 30 分钟_
+  - _完成时间: 2026-01-27_
+
+---
+
+### 阶段 3: 错误处理和优化（30 分钟）✅ 已完成
+
+- [x] **3.1 实现错误处理**
+  - 添加参数验证错误处理
+  - 添加模板加载错误处理
+  - 提供清晰的错误信息和建议
+  - 修复作用域问题（mode 变量）
+  - _需求: 需求 11_
+  - _预估: 20 分钟_
+  - _完成时间: 2026-01-27_
+
+- [x] **3.2 代码重构和注释**
+  - 提取公共函数
+  - 添加详细的代码注释
+  - 优化代码结构
+  - 更新文件头部文档
+  - _非功能需求: 可维护性_
+  - _预估: 10 分钟_
+  - _完成时间: 2026-01-27_
+
+---
+
+### 阶段 4: 测试和文档（1-2 小时）
+
+- [ ] **4.1 编写单元测试**
+  - 测试参数解析逻辑
+  - 测试模板组装函数
+  - 测试模式分发逻辑
+  - _预估: 40 分钟_
+
+- [ ] **4.2 编写集成测试**
+  - 测试单文件模式生成
+  - 测试模块化模式生成
+  - 测试错误处理
+  - _预估: 40 分钟_
+
+- [ ] **4.3 编写契约测试**
+  - 验证结构化输出符合 Schema
+  - 测试向后兼容性
+  - _预估: 20 分钟_
+
+- [ ] **4.4 更新工具文档**
+  - 更新 README.md 中的工具说明
+  - 更新在线文档
+  - 添加使用示例
+  - _预估: 20 分钟_
+
+---
+
+### 阶段 5: 验收和发布（30 分钟）
+
+- [ ] **5.1 手动测试**
+  - 在真实项目中测试单文件模式
+  - 在真实项目中测试模块化模式
+  - 测试错误场景
+  - _预估: 15 分钟_
+
+- [ ] **5.2 代码审查**
+  - 自我审查代码质量
+  - 检查代码规范
+  - 检查注释完整性
+  - _预估: 10 分钟_
+
+- [ ] **5.3 更新 CHANGELOG**
+  - 记录新功能
+  - 记录 API 变更
+  - _预估: 5 分钟_
+
+---
+
+## 检查点
+
+### 阶段 1 完成后 ✅
+- [x] 所有模板文件已创建
+- [x] 模板内容完整，格式正确
+- [x] 模板可以正确渲染
+
+### 阶段 2 完成后 ✅
+- [x] 参数解析正确支持 `mode` 参数
+- [x] 模板组装函数正常工作
+- [x] 模块化模式可以返回正确的模板
+- [x] 单文件模式保持原有行为
+- [x] 结构化输出正确
+
+### 阶段 3 完成后 ✅
+- [x] 错误处理完善
+- [x] 代码质量良好
+
+### 阶段 4 完成后
+- [ ] 所有测试通过
+- [ ] 测试覆盖率 > 80%
+- [ ] 文档更新完成
+
+### 阶段 5 完成后
+- [ ] 手动测试通过
+- [ ] 代码审查通过
+- [ ] CHANGELOG 更新完成
+- [ ] 准备发布
+
+---
+
+## 文件变更清单
+
+| 文件 | 操作 | 说明 |
+|------|------|------|
+| `src/tools/init_project_context.ts` | 修改 | 添加模块化模式支持 |
+| `src/tools/templates/index-template.ts` | 新建 | 索引文件模板 |
+| `src/tools/templates/tech-stack-template.ts` | 新建 | 技术栈模板 |
+| `src/tools/templates/architecture-template.ts` | 新建 | 架构模板 |
+| `src/tools/templates/coding-standards-template.ts` | 新建 | 编码规范模板 |
+| `src/tools/templates/dependencies-template.ts` | 新建 | 依赖模板 |
+| `src/tools/templates/workflows-template.ts` | 新建 | 工作流模板 |
+| `src/schemas/output/project-tools.ts` | 修改 | 扩展 ProjectContext Schema |
+| `tests/integration/init_project_context.test.ts` | 新建 | 集成测试 |
+| `tests/contracts/init_project_context.test.ts` | 修改 | 更新契约测试 |
+| `README.md` | 修改 | 更新工具说明 |
+| `CHANGELOG.md` | 修改 | 记录新功能 |
+| `docs/pages/all-tools.html` | 修改 | 更新工具文档 |
+
+---
+
+## 依赖任务
+
+- 无外部依赖任务
+- 所有任务都在本功能范围内
+
+---
+
+## 风险和注意事项
+
+### 风险 1: 向后兼容性
+- **描述**: 修改可能影响现有用户
+- **缓解**: 默认使用单文件模式，充分测试
+
+### 风险 2: 模板维护
+- **描述**: 多个模板文件增加维护成本
+- **缓解**: 模板代码模块化，提取公共部分
+
+### 风险 3: AI 理解模板
+- **描述**: AI 可能不理解如何使用模板
+- **缓解**: 模板格式清晰，使用明确的占位符
+
+---
+
+## 工作量估算
+
+| 阶段 | 预估时间（小时） |
+|------|------------------|
+| 阶段 1: 准备工作 | 1 |
+| 阶段 2: 核心实现 | 3-5 |
+| 阶段 3: 错误处理和优化 | 0.5 |
+| 阶段 4: 测试和文档 | 1-2 |
+| 阶段 5: 验收和发布 | 0.5 |
+| **总计** | **6-9** |
+
+**乐观估计**: 6 小时（1 个工作日）  
+**正常估计**: 7.5 小时（1 个工作日）  
+**悲观估计**: 9 小时（1.5 个工作日）
+
+---
+
+## 下一步
+
+1. 按照任务清单顺序执行
+2. 每完成一个阶段，进行检查点验证
+3. 遇到问题及时记录和调整
+4. 保持与需求文档和设计文档的一致性
+
+---
+
+*任务版本: 1.0.0*  
+*创建时间: 2026-01-27*  
+*维护者: MCP Probe Kit Team*