mcp-probe-kit 2.3.0 → 2.5.0

package/docs/specs/project-context-modular/example-output.md

@@ -1,123 +0,0 @@
-# 索引文件示例输出
-
-这是新版本 `init_project_context` 生成的索引文件示例（针对库/MCP Server 项目）：
-
----
-
-# mcp-probe-kit - 项目上下文
-
-> 本文档是项目上下文的索引文件，提供项目概览和文档导航。
-
-## 📊 项目概览
-
-| 属性 | 值 |
-|------|-----|
-| 项目名称 | mcp-probe-kit |
-| 版本 | 2.1.0 |
-| 语言 | javascript |
-| 框架 | mcp-server |
-| 类型 | library |
-| 描述 | MCP Probe Kit - 开发工具集 |
-
-## 📚 文档导航
-
-### [技术栈](./project-context/tech-stack.md)
-项目使用的语言、框架、工具
-
-### [架构设计](./project-context/architecture.md)
-项目结构、目录说明、设计模式
-
-### [如何添加新工具](./project-context/how-to-add-tool.md)
-添加新功能/工具的步骤
-
-### [如何编写测试](./project-context/how-to-test.md)
-测试框架和测试编写规范
-
-## 🚀 快速开始
-
-1. 阅读 [技术栈](./project-context/tech-stack.md) 了解项目使用的技术
-2. 阅读 [架构设计](./project-context/architecture.md) 了解项目结构
-3. 根据需要查看具体的操作指南
-
-## 💡 开发时查看对应文档
-
-根据你要做的事情，查看对应的文档：
-
-### 添加新功能
-- **如何添加新工具**: [how-to-add-tool.md](./project-context/how-to-add-tool.md)
-
-### 调试问题
-- **架构设计**: [architecture.md](./project-context/architecture.md) - 了解项目结构
-- **技术栈**: [tech-stack.md](./project-context/tech-stack.md) - 了解使用的技术
-
-### 编写测试
-- **如何编写测试**: [how-to-test.md](./project-context/how-to-test.md)
-
----
-*生成时间: 2026-01-28T10:49:00.000Z*  
-*生成工具: MCP Probe Kit - init_project_context v2.1*
-
----
-
-# 对于后端 API 项目的示例
-
-如果是后端 API 项目，"开发时查看对应文档"部分会是这样：
-
-## 💡 开发时查看对应文档
-
-根据你要做的事情，查看对应的文档：
-
-### 添加新功能
-- **如何添加新接口**: [how-to-add-api.md](./project-context/how-to-add-api.md)
-
-### 修改现有代码
-- **如何操作数据库**: [how-to-database.md](./project-context/how-to-database.md)
-- **如何处理认证**: [how-to-auth.md](./project-context/how-to-auth.md)
-
-### 调试问题
-- **架构设计**: [architecture.md](./project-context/architecture.md) - 了解项目结构
-- **技术栈**: [tech-stack.md](./project-context/tech-stack.md) - 了解使用的技术
-
----
-
-# 对于前端 SPA 项目的示例
-
-如果是前端 SPA 项目，"开发时查看对应文档"部分会是这样：
-
-## 💡 开发时查看对应文档
-
-根据你要做的事情，查看对应的文档：
-
-### 添加新功能
-- **如何创建新页面**: [how-to-new-page.md](./project-context/how-to-new-page.md)
-
-### 修改现有代码
-- **如何调用 API**: [how-to-call-api.md](./project-context/how-to-call-api.md)
-- **如何管理状态**: [how-to-state.md](./project-context/how-to-state.md)
-
-### 调试问题
-- **架构设计**: [architecture.md](./project-context/architecture.md) - 了解项目结构
-- **技术栈**: [tech-stack.md](./project-context/tech-stack.md) - 了解使用的技术
-
----
-
-## 核心改进
-
-新增的 **"💡 开发时查看对应文档"** 部分会：
-
-1. **按开发场景分类**：
-   - 添加新功能
-   - 修改现有代码
-   - 调试问题
-   - 编写测试
-   - 部署上线
-
-2. **智能匹配文档**：
-   - 根据项目类型（后端/前端/全栈/库）自动分类
-   - 只显示该项目类型相关的文档
-
-3. **提供直接链接**：
-   - 每个场景下列出相关文档的直接链接
-   - 开发者可以快速找到需要的文档
-
-这样开发者在开发时就能快速找到对应的文档，不用在所有文档中翻找了！

package/docs/specs/project-context-modular/implementation-v2.md

@@ -1,275 +0,0 @@
-# init_project_context 重新设计 - v2.1 实现
-
-## 问题分析
-
-### 原有实现的问题
-
-1. **"分析任务"系统过于复杂**
-   - Discover → Analyze → Generate 三步流程太抽象
-   - AI 难以理解如何执行这些任务
-   - 生成的内容仍然很泛化，不够实用
-
-2. **缺少索引文件**
-   - 没有 `project-context.md` 作为入口
-   - 用户反馈：索引文件是"项目的灵魂"
-
-3. **项目检测工作正常**
-   - 实际测试显示项目检测功能正常
-   - 能正确识别 JavaScript + MCP Server + Library 类型
-
-4. **用户反馈**
-   - "生成的文件太泛了，第一眼看很牛逼，仔细看就不行了"
-   - 需要任务导向的文档（如"如何添加新接口"）
-   - 希望简单直接，不要过度复杂
-
----
-
-## 新设计方案
-
-### 核心理念
-
-**简单、直接、实用**
-
-- ✅ 始终生成索引文件作为入口
-- ✅ 提供清晰的模板结构
-- ✅ 直接的填写指导（不是抽象的"分析任务"）
-- ✅ 强调从项目中提取真实示例
-- ✅ 根据项目类型生成 4-6 个实用文档
-
-### 文件结构
-
-```
-docs/
-├── project-context.md          # 索引文件（必须首先生成）
-└── project-context/            # 分类文档目录
-    ├── tech-stack.md           # 技术栈（所有项目）
-    ├── architecture.md         # 架构设计（所有项目）
-    └── [类型特定文档]
-        ├── how-to-add-api.md       # 后端项目
-        ├── how-to-database.md      # 后端项目
-        ├── how-to-new-page.md      # 前端项目
-        ├── how-to-call-api.md      # 前端项目
-        ├── how-to-add-tool.md      # 库项目
-        └── ...
-```
-
-### 文档数量
-
-| 项目类型 | 文档数量 | 文档列表 |
-|---------|---------|---------|
-| backend-api | 6 个 | 索引 + 技术栈 + 架构 + 添加接口 + 数据库 + 认证 |
-| frontend-spa | 6 个 | 索引 + 技术栈 + 架构 + 新页面 + 调用API + 状态管理 |
-| fullstack | 6 个 | 索引 + 技术栈 + 架构 + 新功能 + 添加接口 + 新页面 |
-| library | 5 个 | 索引 + 技术栈 + 架构 + 添加工具 + 测试 |
-| cli | 5 个 | 索引 + 技术栈 + 架构 + 添加命令 + 测试 |
-| unknown | 5 个 | 索引 + 技术栈 + 架构 + 开发 + 测试 |
-
----
-
-## 实现细节
-
-### 1. 移除的模块
-
-删除了过于复杂的"分析任务"系统：
-- ❌ `src/lib/analysis-tasks.ts` - 不再使用
-- ❌ `src/lib/task-generator.ts` - 不再使用
-- ❌ `src/lib/document-templates.ts` - 不再使用
-
-### 2. 保留的模块
-
-- ✅ `src/lib/project-detector.ts` - 项目类型检测（工作正常）
-- ✅ `src/tools/init_project_context.ts` - 主工具（重写）
-
-### 3. 新的实现逻辑
-
-```typescript
-// 1. 检测项目类型
-const detection = detectProjectType(projectRoot);
-
-// 2. 获取项目基本信息
-const projectInfo = getProjectInfo(projectRoot);
-
-// 3. 根据项目类型获取文档列表
-const docs = getDocumentList(detection.category);
-
-// 4. 生成指导文本（包含模板）
-const guide = generateGuideText(detection, projectInfo, docs, docsDir);
-
-// 5. 返回结构化数据
-return okStructured(guide, structuredData, { schema });
-```
-
-### 4. 模板设计
-
-**原则**：
-- 提供完整的 Markdown 模板
-- 使用 `[填写]` 标记需要 AI 填充的内容
-- 提供清晰的"填写指导"
-- 强调从项目中提取真实代码
-
-**示例**（tech-stack.md）：
-
-```markdown
-# 技术栈
-
-## 基本信息
-| 属性 | 值 |
-|------|-----|
-| 项目名称 | [从 package.json 提取] |
-| 版本 | [从 package.json 提取] |
-
-## 技术栈详情
-[从项目中分析并填写]
-
-**填写指导**:
-1. 读取 package.json 获取依赖信息
-2. 列出最重要的 5-10 个依赖包
-3. 说明每个依赖的用途
-```
-
-### 5. 索引文件的重要性
-
-索引文件 `project-context.md` 是整个系统的**灵魂**：
-
-- 📍 **唯一入口** - 所有文档的导航中心
-- 📊 **项目概览** - 快速了解项目基本信息
-- 🔗 **文档导航** - 链接到所有分类文档
-- 🚀 **快速开始** - 指导如何使用这些文档
-
-**必须首先生成**，其他文档都链接回索引文件。
-
----
-
-## 与原设计的对比
-
-| 方面 | 原设计（分析任务） | 新设计（简单模板） |
-|------|------------------|------------------|
-| 复杂度 | 高（三步流程） | 低（直接模板） |
-| AI 理解难度 | 难（抽象概念） | 易（具体指导） |
-| 生成质量 | 泛化、不实用 | 具体、可操作 |
-| 索引文件 | 无 | 有（必须） |
-| 文档数量 | 动态（4-5个） | 固定（5-6个） |
-| 模板方式 | 抽象任务描述 | 具体 Markdown 模板 |
-| 填写指导 | 问题列表 | 直接步骤 |
-
----
-
-## 测试结果
-
-所有测试通过：
-
-```bash
-✓ init_project_context 工具 (9 tests)
-  ✓ 应该返回包含 content 和 structuredContent 的响应
-  ✓ structuredContent 应该符合 ProjectContext schema
-  ✓ 应该包含 _meta 字段和 schema 信息
-  ✓ 应该正确处理默认参数
-  ✓ 应该正确处理自定义 docs_dir
-  ✓ 应该根据项目类型生成相应的文档
-```
-
-项目检测测试：
-
-```json
-{
-  "language": "javascript",
-  "category": "library",
-  "framework": "mcp-server",
-  "confidence": 80,
-  "indicators": [
-    "package.json",
-    "dependency: @modelcontextprotocol/sdk"
-  ]
-}
-```
-
----
-
-## 使用示例
-
-### 调用工具
-
-```javascript
-await initProjectContext({
-  docs_dir: "docs"
-});
-```
-
-### 生成的指导文本
-
-工具会返回清晰的指导，包括：
-
-1. **项目信息** - 检测到的项目类型、语言、框架
-2. **文件结构** - 需要生成的文件列表
-3. **生成步骤** - 逐个文档的模板和填写指导
-4. **完成标准** - 检查清单
-
-### AI 的工作流程
-
-1. 阅读指导文本
-2. 首先创建索引文件 `project-context.md`
-3. 逐个创建分类文档
-4. 从项目中提取真实代码示例
-5. 填充模板中的占位符
-
----
-
-## 优势
-
-### 1. 简单直接
-- 不需要理解复杂的"分析任务"概念
-- 直接看到要生成什么内容
-
-### 2. 质量保证
-- 提供完整的模板结构
-- 明确的填写指导
-- 强调真实示例
-
-### 3. 用户友好
-- 索引文件作为入口
-- 清晰的文档导航
-- 任务导向的内容
-
-### 4. 可维护性
-- 代码简单，易于理解
-- 模板易于扩展
-- 减少了抽象层次
-
----
-
-## 后续优化方向
-
-### 短期（v2.1.x）
-- [ ] 收集用户反馈
-- [ ] 优化模板内容
-- [ ] 添加更多项目类型支持
-
-### 中期（v2.2.x）
-- [ ] 支持自定义模板
-- [ ] 提供模板变量系统
-- [ ] 增强项目检测能力
-
-### 长期（v3.x）
-- [ ] AI 自动填充部分内容
-- [ ] 支持增量更新
-- [ ] 多语言文档支持
-
----
-
-## 总结
-
-新的实现方案通过**简化设计、提供清晰模板、强调真实示例**，解决了原有"分析任务"系统过于复杂、生成内容泛化的问题。
-
-**核心改进**：
-1. ✅ 始终生成索引文件（项目的灵魂）
-2. ✅ 简单直接的模板（不是抽象任务）
-3. ✅ 清晰的填写指导（具体步骤）
-4. ✅ 强调真实示例（从项目提取）
-
-这个方案在保持灵活性的同时，大幅提升了生成文档的实用性和可操作性。
-
----
-
-*文档版本: 2.0*  
-*创建时间: 2026-01-28*  
-*实现版本: v2.1.0*

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

@@ -1,234 +0,0 @@
-# 需求文档：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*