mcp-probe-kit 2.0.0 → 2.0.1

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

@@ -0,0 +1,722 @@
+# 设计文档：project-context-modular
+
+## 概述
+
+本设计文档描述 `project-context-modular` 功能的技术实现方案。该功能将 `init_project_context` 工具从单文件模式扩展为支持模块化文档生成，通过将项目信息分类存放到多个独立文件中，优化 AI 开发时的上下文加载效率。
+
+**设计目标**：
+- 保持向后兼容，默认使用单文件模式
+- 提供模块化模式，生成索引文件和 5 个分类文档
+- 每个文档独立完整，可单独阅读
+- 使用清晰的文件夹结构组织文档
+
+---
+
+## 技术方案
+
+### 技术选型
+
+| 类别 | 选择 | 理由 |
+|------|------|------|
+| 实现语言 | TypeScript | 项目统一使用 TypeScript |
+| 文件操作 | Node.js fs/promises | 内置模块，无需额外依赖 |
+| 参数解析 | parseArgs 工具 | 项目现有工具，支持自然语言输入 |
+| 输出格式 | okStructured | 项目现有工具，支持结构化输出 |
+| 模板引擎 | 字符串模板 | 简单直接，无需引入模板库 |
+
+### 架构设计
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    init_project_context                      │
+│                                                               │
+│  ┌──────────────┐      ┌──────────────┐                     │
+│  │ 参数解析     │─────▶│ 模式判断     │                     │
+│  │ parseArgs    │      │ single/      │                     │
+│  └──────────────┘      │ modular      │                     │
+│                        └──────┬───────┘                     │
+│                               │                              │
+│                    ┌──────────┴──────────┐                  │
+│                    │                     │                  │
+│            ┌───────▼────────┐   ┌───────▼────────┐         │
+│            │  单文件模式     │   │  模块化模式     │         │
+│            │  (现有逻辑)     │   │  (新增逻辑)     │         │
+│            └───────┬────────┘   └───────┬────────┘         │
+│                    │                     │                  │
+│                    │            ┌────────▼────────┐         │
+│                    │            │ 项目信息分析     │         │
+│                    │            │ - package.json  │         │
+│                    │            │ - tsconfig.json │         │
+│                    │            │ - 目录结构      │         │
+│                    │            └────────┬────────┘         │
+│                    │                     │                  │
+│                    │            ┌────────▼────────┐         │
+│                    │            │ 生成分类文档     │         │
+│                    │            │ - tech-stack    │         │
+│                    │            │ - architecture  │         │
+│                    │            │ - coding-stds   │         │
+│                    │            │ - dependencies  │         │
+│                    │            │ - workflows     │         │
+│                    │            └────────┬────────┘         │
+│                    │                     │                  │
+│                    │            ┌────────▼────────┐         │
+│                    │            │ 生成索引文件     │         │
+│                    │            │ project-context │         │
+│                    │            └────────┬────────┘         │
+│                    │                     │                  │
+│                    └──────────┬──────────┘                  │
+│                               │                              │
+│                      ┌────────▼────────┐                    │
+│                      │ 结构化输出       │                    │
+│                      │ okStructured    │                    │
+│                      └─────────────────┘                    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 数据模型
+
+### 参数接口
+
+```typescript
+interface InitProjectContextArgs {
+  docs_dir?: string;      // 文档目录，默认 "docs"
+  mode?: "single" | "modular";  // 生成模式，默认 "single"
+}
+```
+
+### 项目信息接口
+
+```typescript
+interface ProjectInfo {
+  // 基本信息
+  name: string;
+  version: string;
+  description: string;
+  type: string;  // "MCP服务器" | "Web应用" | "库" | "CLI工具"
+  
+  // 技术栈
+  techStack: {
+    language: string;
+    runtime: string;
+    frameworks: string[];
+    buildTools: string[];
+    testFramework: string;
+    packageManager: string;
+  };
+  
+  // 架构
+  architecture: {
+    projectType: string;
+    designPatterns: string[];
+    entryFile: string;
+    directoryTree: string;
+    mainDirectories: Record<string, string>;
+  };
+  
+  // 编码规范
+  codingStandards: {
+    eslint: { enabled: boolean; configFile?: string };
+    prettier: { enabled: boolean; configFile?: string };
+    namingConventions: Record<string, string>;
+    typescript?: {
+      strict: boolean;
+      target: string;
+      module: string;
+    };
+  };
+  
+  // 依赖
+  dependencies: {
+    production: Array<{ name: string; version: string; purpose: string }>;
+    development: Array<{ name: string; version: string; purpose: string }>;
+    totalCount: number;
+  };
+  
+  // 工作流
+  workflows: {
+    commands: Record<string, string>;
+    nodeVersion?: string;
+  };
+}
+```
+
+### 输出结构
+
+```typescript
+interface ModularContextOutput extends ProjectContext {
+  files: Array<{
+    path: string;
+    purpose: string;
+    size: number;
+  }>;
+  mode: "single" | "modular";
+}
+```
+
+---
+
+## 文件结构
+
+### 模块化模式输出
+
+```
+docs/
+├── project-context.md          # 索引文件（包含 AI 引导）
+└── project-context/            # 分类文档目录
+    ├── tech-stack.md           # 技术栈
+    ├── architecture.md         # 架构
+    ├── coding-standards.md     # 编码规范
+    ├── dependencies.md         # 依赖
+    └── workflows.md            # 工作流
+```
+
+### 单文件模式输出（保持不变）
+
+```
+docs/
+└── project-context.md          # 单一文件
+```
+
+### 代码文件结构
+
+```
+src/
+└── tools/
+    ├── init_project_context.ts           # 主文件（修改）
+    └── templates/                        # 新增模板目录
+        ├── index-template.ts             # 索引文件模板（包含 AI 引导）
+        ├── tech-stack-template.ts        # 技术栈模板
+        ├── architecture-template.ts      # 架构模板
+        ├── coding-standards-template.ts  # 编码规范模板
+        ├── dependencies-template.ts      # 依赖模板
+        └── workflows-template.ts         # 工作流模板
+```
+
+---
+
+## 核心实现
+
+### 1. 参数解析
+
+```typescript
+const parsedArgs = parseArgs<InitProjectContextArgs>(args, {
+  defaultValues: {
+    docs_dir: "docs",
+    mode: "single",
+  },
+  primaryField: "docs_dir",
+  fieldAliases: {
+    docs_dir: ["dir", "output", "directory", "目录"],
+    mode: ["type", "format", "模式"],
+  },
+});
+
+const docsDir = getString(parsedArgs.docs_dir) || "docs";
+const mode = getString(parsedArgs.mode) || "single";
+```
+
+### 2. 模式分发
+
+```typescript
+if (mode === "modular") {
+  return await generateModularContext(docsDir);
+} else {
+  return await generateSingleContext(docsDir);
+}
+```
+
+### 3. 项目信息分析
+
+```typescript
+async function analyzeProject(): Promise<ProjectInfo> {
+  // 读取 package.json
+  const packageJson = await readPackageJson();
+  
+  // 分析技术栈
+  const techStack = analyzeTechStack(packageJson);
+  
+  // 分析架构
+  const architecture = await analyzeArchitecture();
+  
+  // 分析编码规范
+  const codingStandards = await analyzeCodingStandards();
+  
+  // 分析依赖
+  const dependencies = analyzeDependencies(packageJson);
+  
+  // 分析工作流
+  const workflows = analyzeWorkflows(packageJson);
+  
+  return {
+    name: packageJson.name,
+    version: packageJson.version,
+    description: packageJson.description,
+    type: inferProjectType(packageJson),
+    techStack,
+    architecture,
+    codingStandards,
+    dependencies,
+    workflows,
+  };
+}
+```
+
+### 4. 模板渲染
+
+```typescript
+function renderTemplate(template: string, data: ProjectInfo): string {
+  return template
+    .replace(/\{name\}/g, data.name)
+    .replace(/\{version\}/g, data.version)
+    .replace(/\{description\}/g, data.description)
+    // ... 更多替换
+    ;
+}
+```
+
+### 5. 文件生成
+
+```typescript
+async function generateModularContext(docsDir: string) {
+  const projectInfo = await analyzeProject();
+  
+  // 创建目录
+  const contextDir = path.join(docsDir, "project-context");
+  await fs.mkdir(contextDir, { recursive: true });
+  
+  // 生成分类文档
+  const files = [
+    { name: "tech-stack.md", template: techStackTemplate },
+    { name: "architecture.md", template: architectureTemplate },
+    { name: "coding-standards.md", template: codingStandardsTemplate },
+    { name: "dependencies.md", template: dependenciesTemplate },
+    { name: "workflows.md", template: workflowsTemplate },
+  ];
+  
+  for (const file of files) {
+    const content = renderTemplate(file.template, projectInfo);
+    const filePath = path.join(contextDir, file.name);
+    await fs.writeFile(filePath, content, "utf-8");
+  }
+  
+  // 生成索引文件
+  const indexContent = renderTemplate(indexTemplate, projectInfo);
+  const indexPath = path.join(docsDir, "project-context.md");
+  await fs.writeFile(indexPath, indexContent, "utf-8");
+  
+  return okStructured(/* ... */);
+}
+```
+
+---
+
+## 模板设计
+
+### 设计原则
+
+**MCP 工具的职责**：
+- 提供文件列表（要生成哪些文档）
+- 提供格式模板（每个文档的结构框架）
+- 使用占位符标记需要填充的内容
+
+**AI 的职责**：
+- 决定分析哪些项目文件
+- 决定提取什么信息
+- 决定如何填充模板
+
+### 工具返回内容
+
+当用户执行 `init_project_context mode=modular` 时，工具返回：
+
+```markdown
+✅ 请生成以下项目上下文文档
+
+## 📋 需要生成的文档
+
+### 文件结构
+\`\`\`
+docs/
+├── project-context.md          # 索引文件
+└── project-context/            # 分类文档
+    ├── tech-stack.md           # 技术栈
+    ├── architecture.md         # 架构
+    ├── coding-standards.md     # 编码规范
+    ├── dependencies.md         # 依赖
+    └── workflows.md            # 工作流
+\`\`\`
+
+---
+
+## 📄 文档模板
+
+### 1. docs/project-context.md（索引文件）
+
+**文件用途**: 项目上下文的唯一入口，提供概览和导航
+
+**模板格式**:
+\`\`\`markdown
+# 项目上下文
+
+> 本文档是项目上下文的索引文件，提供项目概览和导航链接。
+
+## 项目概览
+
+| 属性 | 值 |
+|------|-----|
+| 名称 | [项目名称] |
+| 版本 | [版本号] |
+| 类型 | [项目类型] |
+| 描述 | [项目描述] |
+
+## 📚 文档导航
+
+### [技术栈](./project-context/tech-stack.md)
+了解项目使用的语言、框架、构建工具等技术选型。
+
+### [架构设计](./project-context/architecture.md)
+了解项目的目录结构、入口文件、模块划分和设计模式。
+
+### [编码规范](./project-context/coding-standards.md)
+了解项目的代码风格、命名规范和 TypeScript 配置。
+
+### [依赖管理](./project-context/dependencies.md)
+了解项目的依赖包及其用途。
+
+### [开发流程](./project-context/workflows.md)
+了解项目的开发、构建、测试等命令。
+
+---
+*生成时间: [时间戳]*
+*生成工具: MCP Probe Kit - init_project_context (modular mode)*
+\`\`\`
+
+---
+
+### 2. docs/project-context/tech-stack.md
+
+**文件用途**: 记录项目使用的语言、框架、构建工具等技术选型
+
+**模板格式**:
+\`\`\`markdown
+# 技术栈
+
+> 本文档描述 [项目名称] 的技术栈信息。
+
+## 项目信息
+
+| 属性 | 值 |
+|------|-----|
+| 项目名称 | [项目名称] |
+| 版本 | [版本号] |
+
+## 技术栈
+
+| 类别 | 技术 |
+|------|------|
+| 语言 | [填写] |
+| 运行时 | [填写] |
+| 框架 | [填写] |
+| 构建工具 | [填写] |
+| 包管理器 | [填写] |
+| 测试框架 | [填写] |
+
+## 技术选型说明
+
+[根据项目实际情况填写技术选型的原因和说明]
+
+---
+*生成时间: [时间戳]*
+*返回索引: [../project-context.md](../project-context.md)*
+\`\`\`
+
+---
+
+### 3. docs/project-context/architecture.md
+
+**文件用途**: 记录项目的目录结构、入口文件、模块划分和设计模式
+
+**模板格式**:
+\`\`\`markdown
+# 架构设计
+
+> 本文档描述 [项目名称] 的架构和项目结构。
+
+## 项目信息
+
+| 属性 | 值 |
+|------|-----|
+| 项目名称 | [项目名称] |
+| 版本 | [版本号] |
+
+## 项目结构
+
+\`\`\`
+[生成目录树]
+\`\`\`
+
+## 主要目录说明
+
+| 目录 | 用途 |
+|------|------|
+| [目录名] | [用途说明] |
+
+## 入口文件
+
+- 主入口: [入口文件路径]
+
+## 架构模式
+
+- **项目类型**: [项目类型]
+- **设计模式**: [使用的设计模式]
+- **模块划分**: [模块划分说明]
+
+---
+*生成时间: [时间戳]*
+*返回索引: [../project-context.md](../project-context.md)*
+\`\`\`
+
+---
+
+### 4. docs/project-context/coding-standards.md
+
+**文件用途**: 记录项目的代码风格、命名规范和配置
+
+**模板格式**:
+\`\`\`markdown
+# 编码规范
+
+> 本文档描述 [项目名称] 的编码规范。
+
+## 项目信息
+
+| 属性 | 值 |
+|------|-----|
+| 项目名称 | [项目名称] |
+| 版本 | [版本号] |
+
+## 代码风格
+
+| 工具 | 状态 | 配置文件 |
+|------|------|----------|
+| ESLint | [启用/未配置] | [配置文件路径] |
+| Prettier | [启用/未配置] | [配置文件路径] |
+
+## 命名规范
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| 文件命名 | [规范] | [示例] |
+| 变量命名 | camelCase | userName |
+| 常量命名 | UPPER_SNAKE_CASE | MAX_COUNT |
+| 函数命名 | camelCase | getUserInfo |
+| 类/接口命名 | PascalCase | UserService |
+
+## TypeScript 配置
+
+[如果是 TypeScript 项目，填写相关配置信息]
+
+---
+*生成时间: [时间戳]*
+*返回索引: [../project-context.md](../project-context.md)*
+\`\`\`
+
+---
+
+### 5. docs/project-context/dependencies.md
+
+**文件用途**: 记录项目的依赖包及其用途
+
+**模板格式**:
+\`\`\`markdown
+# 依赖管理
+
+> 本文档描述 [项目名称] 的依赖管理。
+
+## 项目信息
+
+| 属性 | 值 |
+|------|-----|
+| 项目名称 | [项目名称] |
+| 版本 | [版本号] |
+
+## 主要生产依赖
+
+| 依赖 | 版本 | 用途 |
+|------|------|------|
+| [依赖名] | [版本号] | [用途说明] |
+
+## 主要开发依赖
+
+| 依赖 | 版本 | 用途 |
+|------|------|------|
+| [依赖名] | [版本号] | [用途说明] |
+
+## 依赖统计
+
+- 生产依赖: [数量] 个
+- 开发依赖: [数量] 个
+- 总计: [数量] 个
+
+---
+*生成时间: [时间戳]*
+*返回索引: [../project-context.md](../project-context.md)*
+\`\`\`
+
+---
+
+### 6. docs/project-context/workflows.md
+
+**文件用途**: 记录项目的开发、构建、测试等命令
+
+**模板格式**:
+\`\`\`markdown
+# 开发流程
+
+> 本文档描述 [项目名称] 的开发流程和命令。
+
+## 项目信息
+
+| 属性 | 值 |
+|------|-----|
+| 项目名称 | [项目名称] |
+| 版本 | [版本号] |
+
+## 常用命令
+
+| 命令 | 用途 |
+|------|------|
+| [命令] | [用途说明] |
+
+## 开发环境要求
+
+- Node.js: [版本要求]
+- 包管理器: [包管理器名称]
+
+---
+*生成时间: [时间戳]*
+*返回索引: [../project-context.md](../project-context.md)*
+\`\`\`
+```
+
+### 模板使用说明
+
+1. **占位符约定**：
+   - `[填写]` - 需要 AI 填充的内容
+   - `[项目名称]` - 从项目信息中提取
+   - `[时间戳]` - 生成时的时间戳
+
+2. **AI 的工作**：
+   - 分析项目文件（package.json、tsconfig.json、目录结构等）
+   - 提取相关信息
+   - 按照模板格式填充内容
+   - 生成最终的 Markdown 文件
+
+3. **模板特点**：
+   - 只定义结构，不指导分析
+   - 使用标准 Markdown 格式
+   - 每个文档独立完整
+   - 包含返回索引的链接
+
+---
+
+## 设计决策
+
+### 决策 1: 文件夹命名
+
+**问题**: 分类文档应该放在哪个目录？
+
+**选项**:
+1. `docs/context/` - 简短的名称
+2. `docs/project-context/` - 与索引文件名称一致
+3. `docs/.context/` - 隐藏目录
+
+**决策**: 选择 `docs/project-context/`
+
+**理由**:
+- 与索引文件 `project-context.md` 名称一致，易于理解
+- 不使用隐藏目录，保持透明性
+- 符合项目现有的文档组织方式
+
+### 决策 2: 默认模式
+
+**问题**: 默认应该使用哪种模式？
+
+**选项**:
+1. `single` - 单文件模式
+2. `modular` - 模块化模式
+
+**决策**: 选择 `single`
+
+**理由**:
+- 保持向后兼容，不影响现有用户
+- 单文件模式更简单，适合小型项目
+- 用户可以根据需要选择模块化模式
+
+### 决策 3: 模板实现方式
+
+**问题**: 如何实现文档模板？
+
+**选项**:
+1. 使用模板引擎（如 Handlebars、EJS）
+2. 使用字符串模板和简单替换
+3. 使用函数生成
+
+**决策**: 选择字符串模板和简单替换
+
+**理由**:
+- 无需引入额外依赖
+- 模板逻辑简单，不需要复杂的条件和循环
+- 易于维护和调试
+
+### 决策 4: 错误处理策略
+
+**问题**: 当某些信息无法获取时如何处理？
+
+**选项**:
+1. 抛出错误，停止生成
+2. 使用默认值或"未配置"标记
+3. 跳过该部分内容
+
+**决策**: 选择使用默认值或"未配置"标记
+
+**理由**:
+- 保证文档生成的完整性
+- 提供明确的信息缺失提示
+- 不影响其他部分的生成
+
+---
+
+## 风险评估
+
+| 风险 | 影响 | 概率 | 缓解措施 |
+|------|------|------|----------|
+| 文件路径冲突 | 中 | 低 | 生成前检查文件是否存在，提供覆盖选项 |
+| 大型项目分析慢 | 中 | 中 | 限制目录树深度，忽略大型目录 |
+| 模板维护成本 | 低 | 高 | 模板代码模块化，易于扩展 |
+| 向后兼容性破坏 | 高 | 低 | 默认使用单文件模式，充分测试 |
+
+---
+
+## 性能优化
+
+1. **并行文件写入**: 使用 `Promise.all` 并行写入多个文件
+2. **缓存项目信息**: 分析一次，多次使用
+3. **限制目录扫描深度**: 避免扫描 `node_modules` 等大型目录
+4. **延迟加载模板**: 只在需要时加载对应的模板
+
+---
+
+## 测试策略
+
+1. **单元测试**: 测试每个分析函数和模板渲染函数
+2. **集成测试**: 测试完整的文档生成流程
+3. **契约测试**: 验证结构化输出符合 Schema 定义
+4. **兼容性测试**: 验证单文件模式保持不变
+
+---
+
+*设计版本: 1.0.0*  
+*创建时间: 2026-01-27*  
+*维护者: MCP Probe Kit Team*