specops 0.2.5 → 0.3.2

package/skills/requirement-analysis/README.md

@@ -0,0 +1,464 @@
+# 需求分析技能使用指南
+
+## 快速开始
+
+### 基本用法
+
+```typescript
+import { V1Integration } from '../src/requirement-analysis/integrations/v1-integration.js';
+
+const analyzer = new V1Integration();
+
+// 分析项目需求
+const result = await analyzer.analyzeRequirements('/path/to/project', {
+  includeTechStack: true,
+  generatePRD: true,
+  depth: 'medium'
+});
+
+console.log('分析完成:', result.id);
+console.log('项目名称:', result.projectInfo.name);
+console.log('功能数量:', result.featureMapping.summary.totalFeatures);
+console.log('质量评分:', result.qualityScore.overall);
+```
+
+### 命令行使用
+
+```bash
+# 基本分析
+npm run analyze-requirements /path/to/project
+
+# 深度分析并生成PRD
+npm run analyze-requirements /path/to/project --depth=deep --prd
+
+# 仅技术栈分析
+npm run analyze-requirements /path/to/project --tech-only
+
+# 导出到v1系统
+npm run analyze-requirements /path/to/project --export-v1
+```
+
+## 详细功能
+
+### 1. 项目信息分析
+
+```typescript
+import { RepositoryParser } from '../src/requirement-analysis/analyzers/repository-parser.js';
+
+const parser = new RepositoryParser();
+
+// 解析项目基本信息
+const projectInfo = await parser.parseProjectInfo('/path/to/project');
+
+console.log('项目类型:', projectInfo.type);
+console.log('主要语言:', projectInfo.primaryLanguages);
+console.log('代码行数:', projectInfo.codebaseStats.totalLines);
+console.log('项目成熟度:', projectInfo.maturity);
+```
+
+**支持的项目类型：**
+- `web-app` - Web应用
+- `mobile-app` - 移动应用  
+- `desktop-app` - 桌面应用
+- `api-service` - API服务
+- `library` - 代码库
+- `cli-tool` - 命令行工具
+- `microservice` - 微服务
+- `monorepo` - 单体仓库
+
+### 2. PRD文档生成
+
+```typescript
+import { PRDGenerator } from '../src/requirement-analysis/generators/prd-generator.js';
+
+const generator = new PRDGenerator('./custom-template.md');
+
+// 生成PRD文档
+const prd = await generator.generatePRD(projectInfo, featureMapping, techStack);
+
+console.log('PRD内容:', prd.content);
+console.log('质量评分:', prd.qualityScore);
+console.log('章节数量:', prd.sections.length);
+```
+
+**PRD模板变量：**
+- `{{projectName}}` - 项目名称
+- `{{projectDescription}}` - 项目描述
+- `{{totalFeatures}}` - 功能总数
+- `{{totalHours}}` - 总工作量
+- `{{overviewSection}}` - 概述章节
+- `{{featuresSection}}` - 功能章节
+- `{{technicalSection}}` - 技术章节
+- `{{timelineSection}}` - 时间线章节
+- `{{resourcesSection}}` - 资源章节
+
+### 3. v1系统集成
+
+```typescript
+import { V1Integration } from '../src/requirement-analysis/integrations/v1-integration.js';
+
+const integration = new V1Integration();
+
+// 创建v1项目
+const v1Project = await integration.createV1Project(analysisResult);
+
+// 创建v1任务
+const v1Tasks = await integration.createV1Tasks(analysisResult);
+
+// 导出完整格式
+const v1Export = await integration.exportToV1Format(analysisResult);
+```
+
+## 配置选项
+
+### 分析选项
+
+```typescript
+interface AnalysisOptions {
+  // 是否包含技术栈分析（默认：true）
+  includeTechStack?: boolean;
+  
+  // 是否生成PRD文档（默认：true）
+  generatePRD?: boolean;
+  
+  // PRD模板路径（默认：内置模板）
+  prdTemplate?: string;
+  
+  // 分析深度（默认：medium）
+  depth?: 'shallow' | 'medium' | 'deep';
+  
+  // 排除的文件模式
+  excludePatterns?: string[];
+  
+  // 自定义配置
+  customConfig?: Record<string, any>;
+}
+```
+
+### 深度级别说明
+
+**shallow（浅层）**
+- 仅分析项目结构和基本信息
+- 适合大型项目的快速概览
+- 分析时间：< 30秒
+
+**medium（中等）**
+- 包含功能映射和技术栈分析
+- 平衡分析质量和性能
+- 分析时间：1-3分钟
+
+**deep（深度）**
+- 完整的代码分析和依赖关系
+- 最高质量的分析结果
+- 分析时间：3-10分钟
+
+### 排除模式
+
+```typescript
+const options = {
+  excludePatterns: [
+    'node_modules',
+    '*.test.js',
+    'coverage',
+    'dist',
+    '.git',
+    'tmp'
+  ]
+};
+```
+
+## 自定义模板
+
+### PRD模板格式
+
+创建自定义PRD模板文件 `custom-prd-template.md`：
+
+```markdown
+# {{projectName}} 产品需求文档
+
+## 项目信息
+- **项目名称**: {{projectName}}
+- **项目描述**: {{projectDescription}}
+- **功能总数**: {{totalFeatures}}
+- **预估工作量**: {{totalHours}} 小时
+
+{{overviewSection}}
+
+{{featuresSection}}
+
+{{technicalSection}}
+
+{{timelineSection}}
+
+{{resourcesSection}}
+
+## 附录
+- 生成时间: {{timestamp}}
+- 分析工具: v1需求分析技能
+```
+
+### 使用自定义模板
+
+```typescript
+const generator = new PRDGenerator('./templates/custom-prd-template.md');
+const prd = await generator.generatePRD(projectInfo, featureMapping, techStack);
+```
+
+## 输出示例
+
+### 分析结果概览
+
+```json
+{
+  "id": "analysis-1640995200000-abc123def",
+  "projectPath": "/Users/admin/my-project",
+  "timestamp": "2023-12-31T12:00:00.000Z",
+  "projectInfo": {
+    "name": "my-awesome-app",
+    "type": "web-app",
+    "primaryLanguages": ["TypeScript", "JavaScript"],
+    "maturity": "development"
+  },
+  "featureMapping": {
+    "summary": {
+      "totalFeatures": 8,
+      "totalEstimatedHours": 320,
+      "complexityDistribution": {
+        "3": 4,
+        "4": 3,
+        "5": 1
+      }
+    }
+  },
+  "qualityScore": {
+    "overall": 85,
+    "dimensions": {
+      "featureCompleteness": 90,
+      "technicalFeasibility": 85,
+      "requirementClarity": 80,
+      "complexityReasonableness": 85
+    }
+  }
+}
+```
+
+### 功能映射示例
+
+```json
+{
+  "id": "core-auth",
+  "name": "用户认证系统",
+  "description": "实现用户登录、注册、权限管理功能",
+  "priority": 5,
+  "complexity": 3,
+  "estimatedHours": 40,
+  "category": "core",
+  "userStories": [
+    {
+      "id": "auth-login",
+      "asA": "用户",
+      "iWant": "能够登录系统",
+      "soThat": "访问个人功能",
+      "priority": 5
+    }
+  ],
+  "acceptanceCriteria": [
+    "用户可以使用邮箱和密码登录",
+    "登录失败时显示错误信息",
+    "登录成功后跳转到主页"
+  ]
+}
+```
+
+## 错误处理
+
+### 常见错误及解决方案
+
+**1. 项目路径无效**
+```
+错误: 无法访问项目路径 /invalid/path
+解决: 检查路径是否存在且有读取权限
+```
+
+**2. 内存不足**
+```
+错误: JavaScript heap out of memory
+解决: 使用 shallow 分析深度或增加排除模式
+```
+
+**3. 模板加载失败**
+```
+错误: 无法加载模板文件
+解决: 检查模板文件路径和格式
+```
+
+**4. v1集成失败**
+```
+错误: v1系统连接失败
+解决: 检查v1系统状态和网络连接
+```
+
+### 错误处理最佳实践
+
+```typescript
+try {
+  const result = await analyzer.analyzeRequirements(projectPath, options);
+  console.log('分析成功:', result.id);
+} catch (error) {
+  if (error.code === 'ENOENT') {
+    console.error('项目路径不存在:', projectPath);
+  } else if (error.code === 'EACCES') {
+    console.error('权限不足，无法访问:', projectPath);
+  } else {
+    console.error('分析失败:', error.message);
+  }
+}
+```
+
+## 性能优化
+
+### 大型项目处理
+
+```typescript
+// 对于大型项目，使用浅层分析
+const options = {
+  depth: 'shallow',
+  excludePatterns: [
+    'node_modules',
+    'dist',
+    'build',
+    '*.min.js',
+    'coverage'
+  ]
+};
+
+const result = await analyzer.analyzeRequirements(projectPath, options);
+```
+
+### 缓存机制
+
+```typescript
+// 启用分析结果缓存
+const options = {
+  customConfig: {
+    enableCache: true,
+    cacheDir: './analysis-cache',
+    cacheTTL: 3600 // 1小时
+  }
+};
+```
+
+### 并行处理
+
+```typescript
+// 批量分析多个项目
+const projects = ['/path/to/project1', '/path/to/project2'];
+const results = await Promise.all(
+  projects.map(path => analyzer.analyzeRequirements(path))
+);
+```
+
+## 集成示例
+
+### 与CI/CD集成
+
+```yaml
+# .github/workflows/requirement-analysis.yml
+name: Requirement Analysis
+on:
+  push:
+    branches: [main]
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Setup Node.js
+        uses: actions/setup-node@v2
+        with:
+          node-version: '18'
+      - name: Install dependencies
+        run: npm install
+      - name: Run requirement analysis
+        run: npm run analyze-requirements . --export-v1
+      - name: Upload results
+        uses: actions/upload-artifact@v2
+        with:
+          name: analysis-results
+          path: analysis-results.json
+```
+
+### 与Webhook集成
+
+```typescript
+// webhook-handler.js
+import express from 'express';
+import { V1Integration } from './src/requirement-analysis/integrations/v1-integration.js';
+
+const app = express();
+const analyzer = new V1Integration();
+
+app.post('/analyze', async (req, res) => {
+  try {
+    const { projectPath, options } = req.body;
+    const result = await analyzer.analyzeRequirements(projectPath, options);
+    
+    // 发送结果到v1系统
+    await sendToV1System(result);
+    
+    res.json({ success: true, analysisId: result.id });
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+```
+
+## 故障排除
+
+### 调试模式
+
+```typescript
+// 启用详细日志
+const options = {
+  customConfig: {
+    debug: true,
+    logLevel: 'verbose'
+  }
+};
+
+const result = await analyzer.analyzeRequirements(projectPath, options);
+```
+
+### 性能监控
+
+```typescript
+// 监控分析性能
+console.time('analysis');
+const result = await analyzer.analyzeRequirements(projectPath);
+console.timeEnd('analysis');
+
+console.log('分析统计:', {
+  filesAnalyzed: result.projectInfo.codebaseStats.totalFiles,
+  linesAnalyzed: result.projectInfo.codebaseStats.totalLines,
+  featuresGenerated: result.featureMapping.summary.totalFeatures
+});
+```
+
+## 更新日志
+
+### v1.0.0 (2024-01-01)
+- 初始版本发布
+- 支持基本项目分析
+- PRD文档生成
+- v1系统集成
+
+### v1.1.0 (计划中)
+- 增强代码分析能力
+- 支持更多项目类型
+- 改进PRD模板系统
+- 性能优化
+
+---
+
+如有问题或建议，请提交Issue或联系开发团队。

package/skills/requirement-analysis/SKILL.md

@@ -0,0 +1,224 @@
+# 需求分析技能 (Requirement Analysis Skill)
+
+## 技能概述
+
+需求分析技能是一个智能化的项目需求分析工具，能够通过分析现有代码库自动生成功能映射、技术栈分析和产品需求文档(PRD)。该技能专门为 v1 看板系统设计，提供从代码到需求的逆向工程能力。
+
+## 核心功能
+
+### 1. 项目信息解析
+- 自动识别项目类型（Web应用、API服务、CLI工具等）
+- 分析代码库规模和语言分布
+- 评估项目成熟度和技术债务
+
+### 2. 功能映射生成
+- 基于代码结构推断功能模块
+- 生成用户故事和验收标准
+- 建立功能依赖关系图
+- 评估开发复杂度和工作量
+
+### 3. 技术栈分析
+- 检测现有技术栈和版本信息
+- 分析技术栈兼容性
+- 提供技术升级建议
+- 识别潜在技术风险
+
+### 4. PRD 自动生成
+- 生成结构化的产品需求文档
+- 包含项目概述、功能需求、技术需求
+- 提供实施时间线和资源需求
+- 支持自定义模板
+
+### 5. v1 系统集成
+- 与 v1 任务管理系统无缝集成
+- 自动创建项目和任务
+- 支持现有项目的需求补充
+- 提供质量评分和改进建议
+
+## 使用场景
+
+### 场景1：新项目需求分析
+当用户提供一个项目路径，需要生成完整的需求文档时：
+
+```
+用户：请分析 /path/to/project 的需求，生成PRD文档
+助手：我来为您分析项目需求并生成PRD文档...
+```
+
+### 场景2：现有项目功能梳理
+当用户需要梳理现有项目的功能模块时：
+
+```
+用户：帮我分析这个项目有哪些功能模块，生成功能清单
+助手：我来分析项目的功能模块结构...
+```
+
+### 场景3：技术栈评估
+当用户需要评估项目的技术栈选择时：
+
+```
+用户：分析一下这个项目的技术栈，给出优化建议
+助手：我来分析项目的技术栈并提供优化建议...
+```
+
+### 场景4：项目迁移到v1
+当用户想要将现有项目迁移到v1管理时：
+
+```
+用户：我想把这个项目迁移到v1系统管理
+助手：我来分析项目并创建v1项目和任务...
+```
+
+## 触发条件
+
+该技能在以下情况下被触发：
+
+1. **关键词触发**：
+   - "需求分析"、"requirement analysis"
+   - "生成PRD"、"产品需求文档"
+   - "功能映射"、"feature mapping"
+   - "技术栈分析"、"tech stack analysis"
+   - "项目分析"、"project analysis"
+
+2. **路径触发**：
+   - 用户提供项目路径并要求分析
+   - 用户上传项目文件并要求分析
+
+3. **集成触发**：
+   - 用户要求创建v1项目
+   - 用户要求从代码生成任务
+
+## 工作流程
+
+### 阶段1：项目信息收集
+1. 验证项目路径有效性
+2. 解析项目基本信息
+3. 分析代码库结构和统计信息
+4. 识别主要编程语言和框架
+
+### 阶段2：深度分析
+1. 生成功能映射和依赖关系
+2. 分析技术栈兼容性
+3. 评估项目复杂度和风险
+4. 计算工作量估算
+
+### 阶段3：文档生成
+1. 根据模板生成PRD文档
+2. 创建功能清单和用户故事
+3. 生成技术建议和架构指导
+4. 提供实施时间线
+
+### 阶段4：系统集成
+1. 创建v1兼容的项目结构
+2. 生成任务列表和依赖关系
+3. 设置项目配置和元数据
+4. 提供质量评分和改进建议
+
+## 配置选项
+
+```typescript
+interface AnalysisOptions {
+  includeTechStack?: boolean;     // 是否包含技术栈分析
+  generatePRD?: boolean;          // 是否生成PRD文档
+  prdTemplate?: string;           // PRD模板路径
+  depth?: 'shallow' | 'medium' | 'deep';  // 分析深度
+  excludePatterns?: string[];     // 排除的文件模式
+  customConfig?: Record<string, any>;     // 自定义配置
+}
+```
+
+## 输出格式
+
+### 分析结果结构
+```typescript
+interface RequirementAnalysisResult {
+  id: string;                     // 分析ID
+  projectPath: string;            // 项目路径
+  timestamp: Date;                // 分析时间
+  projectInfo: ProjectInfo;       // 项目基本信息
+  featureMapping: FeatureMappingResult;  // 功能映射
+  techStack: TechStackAnalysis;   // 技术栈分析
+  prd: PRDResult;                 // PRD文档
+  qualityScore: QualityScore;     // 质量评分
+}
+```
+
+### PRD文档章节
+1. **项目概述** - 项目基本信息和目标
+2. **功能需求** - 详细功能列表和用户故事
+3. **技术需求** - 技术栈要求和架构建议
+4. **实施时间线** - 开发阶段和里程碑
+5. **资源需求** - 人力资源和技术资源需求
+
+## 质量保证
+
+### 分析质量评分
+- **功能完整性** (0-100)：功能识别的完整程度
+- **技术可行性** (0-100)：技术方案的可行性
+- **需求清晰度** (0-100)：需求描述的清晰程度
+- **复杂度合理性** (0-100)：复杂度评估的合理性
+
+### 改进建议
+系统会根据质量评分自动生成改进建议：
+- 功能模块补充建议
+- 技术栈优化建议
+- 需求文档完善建议
+- 复杂度调整建议
+
+## 扩展能力
+
+### 自定义模板
+支持自定义PRD模板，用户可以：
+- 修改文档结构和章节
+- 添加特定行业的需求模板
+- 集成企业标准文档格式
+
+### 插件机制
+支持扩展分析器和生成器：
+- 自定义代码分析规则
+- 添加特定框架的识别逻辑
+- 集成第三方分析工具
+
+### API集成
+提供标准API接口：
+- RESTful API for 外部系统集成
+- Webhook支持实时通知
+- 批量分析接口
+
+## 最佳实践
+
+### 使用建议
+1. **项目准备**：确保项目代码完整且可访问
+2. **配置优化**：根据项目规模选择合适的分析深度
+3. **模板定制**：为不同类型项目准备专用模板
+4. **结果验证**：人工审核自动生成的需求文档
+
+### 常见问题
+1. **分析失败**：检查项目路径和权限
+2. **结果不准确**：调整分析深度和排除模式
+3. **性能问题**：对大型项目使用浅层分析
+4. **集成问题**：确保v1系统版本兼容
+
+## 技术实现
+
+### 核心模块
+- `RepositoryParser`：项目解析器
+- `PRDGenerator`：PRD文档生成器
+- `V1Integration`：v1系统集成
+- `TechStackAnalyzer`：技术栈分析器
+
+### 依赖关系
+- Node.js文件系统API
+- TypeScript类型系统
+- v1核心模块
+- 模板引擎
+
+### 性能优化
+- 异步文件处理
+- 智能缓存机制
+- 增量分析支持
+- 并行处理优化
+
+---
+
+*该技能为v1看板系统的核心功能之一，持续优化中。如有问题或建议，请联系开发团队。*