AI Code Helper

智能代码辅助工具 - 支持两种使用方式：CLI 工具（本地开发）和 MCP Server（Codewiz 集成）。

🎯 核心功能

方式 1: CLI 工具（命令行）

本地开发自动化工具，支持以下功能：

1. 项目初始化 📸

   • 扫描项目结构
   • 识别文件和组件
   • 生成项目配置

2. 需求分析 📋

   • 读取需求文档
   • 生成 TODO 列表
   • 提取测试场景

3. 测试生成 🧪

   • 根据 TODO 生成测试代码
   • 创建测试文件
   • 输出测试模板

4. 测试执行 ✅

   • 执行所有测试
   • 统计通过率
   • 生成测试报告

5. 代码审查 🔍

   • 执行 git diff
   • 分析代码质量
   • 生成审查报告

方式 2: MCP Server（Codewiz 集成）

AI 自动化工作流，支持以下工具：

1. init-project - 初始化项目
2. read-requirements - 读取需求并生成 TODO
3. generate-baseline-tests - 生成基线测试
4. generate-requirement-tests - 生成需求测试
5. compare-and-review - 对比和代码审查
6. publish-test-platform - 发布到测试平台

特性

• 🚀 AI 驱动 - 与 CodeWiz 深度集成
• ⚙️ 灵活配置 - 支持多种配置文件格式
• 📦 TypeScript 支持 - 完整的类型定义
• 🔌 模块化设计 - 可单独使用各个模块
• 🛠️ 强大的 CLI - 支持多种命令和工作流

安装

方式 1: NPX（推荐 - 无需安装）

# 直接运行，自动下载最新版本
npx ai-code-helper-mcp

方式 2: 项目级安装

# 使用 npm
npm install ai-code-helper

# 使用 pnpm
pnpm add ai-code-helper

# 使用 yarn
yarn add ai-code-helper

方式 3: 全局安装

npm install -g ai-code-helper

安装 Playwright（可选）

如果需要使用截图和测试功能：

npm install -D @playwright/test
npx playwright install

📌 两种使用方式

方式 1: CLI 工具（本地开发）

命令行调用，适合本地开发和调试：

# 初始化项目
ai-code-helper init

# 分析需求
ai-code-helper analyze

# 生成测试
ai-code-helper generate-tests

# 执行测试
ai-code-helper test

# 代码审查
ai-code-helper review

# 完整流程
ai-code-helper full

详见 SKILL.md - 方式 1: CLI 工具

方式 2: MCP Server（Codewiz 集成）

MCP 协议调用，适合 AI 自动化工作流：

配置

编辑 .vscode/settings.json：

{
  "codewiz.mcpServers": {
    "ai-code-helper": {
      "command": "npx",
      "args": ["ai-code-helper-mcp"]
    }
  }
}

使用

在 Codewiz 中调用工具：

// 一键启动完整工作流
await autoCompleteFeature(
  '/path/to/project',
  './docs/requirements.md'
);

详见 SKILL.md - 方式 2: MCP Server

📊 方式对比

| 特性 | CLI 工具 | MCP Server | |------|---------|-----------| | 调用方式 | 命令行 | MCP 协议 | | 使用场景 | 本地开发 | Codewiz 集成 | | 自动化程度 | 分步执行 | 完全自动化 | | 适用人群 | 开发者 | AI 助手 | | 工作流 | 手动执行 | 一键启动 |

详见 SKILL.md - 两种方式对比

快速开始

1. 创建配置文件

在项目根目录创建 ai-code-helper.config.js：

module.exports = {
  projectName: 'my-project',
  
  // Playwright 配置
  playwright: {
    browser: 'chromium',
    headless: false,
    baseURL: 'http://localhost:3000',
    routes: ['/', '/login', '/dashboard'],
    cookies: [
      {
        name: 'session_token',
        value: 'your-token',
        domain: 'localhost',
      },
    ],
  },
  
  // 需求文档配置
  requirement: {
    docPath: './docs/requirements.md',
    docType: 'markdown',
  },
  
  // 测试生成配置
  testGeneration: {
    framework: 'playwright',
    testDir: './tests',
  },
  
  // 代码审查配置
  codeReview: {
    enabled: true,
  },
};

2. 运行工具

# 运行完整工作流
ai-code-helper

# 或者分步执行
ai-code-helper init              # 初始化项目
ai-code-helper analyze           # 分析需求
ai-code-helper generate-tests    # 生成测试
ai-code-helper review            # 代码审查

工作流程

完整工作流程图

初始化阶段
    ↓
AI 调用 Playwright 对路由截图 → AI 收集项目代码组织 → 运行测试了解测试规范
    ↓
获取需求阶段
    ↓
AI 查找需求文档 → 总结成 TODO → 生成 Playwright 测试
    ↓
AI 修改代码阶段
    ↓
AI 写代码 → 运行 Playwright 测试 → 是否通过？
    ├─ 是 → 重新检查代码 → 符合标准？
    │        ├─ 是 → 最终代码
    │        └─ 否 → 重干
    └─ 否 → 进行代码审查

详细步骤

步骤 1: 初始化

ai-code-helper init

• 使用 Playwright 访问配置的路由并截图
• 分析项目文件结构（组件、页面等）
• 生成初始化报告

步骤 2: 需求分析

ai-code-helper analyze

• 读取需求文档
• AI 提取功能需求
• 生成 TODO 列表
• 识别测试场景

步骤 3: 生成测试

ai-code-helper generate-tests

• 根据 TODO 生成测试用例
• 生成 Playwright 测试代码
• 保存到测试目录

步骤 4: 代码审查

ai-code-helper review

• 检查代码质量
• 验证代码规范
• 生成审查报告

命令说明

主要命令

| 命令 | 说明 | 示例 | |------|------|------| | init | 项目初始化 | ai-code-helper init | | analyze | 需求分析 | ai-code-helper analyze | | generate-tests | 生成测试 | ai-code-helper generate-tests | | review | 代码审查 | ai-code-helper review | | full | 完整流程 | ai-code-helper full |

选项

| 选项 | 说明 | |------|------| | -c, --config <path> | 指定配置文件路径 | | --verbose | 显示详细输出 | | --skip-init | 跳过初始化步骤 | | --skip-tests | 跳过测试生成步骤 | | --skip-review | 跳过代码审查步骤 | | -v, --version | 显示版本号 | | -h, --help | 显示帮助信息 |

配置说明

完整配置示例

module.exports = {
  projectName: 'my-project',
  
  // Playwright 配置
  playwright: {
    browser: 'chromium',           // 浏览器类型
    headless: false,               // 是否无头模式
    baseURL: 'http://localhost:3000',
    screenshotDir: './screenshots',
    routes: ['/', '/login'],       // 要截图的路由
    cookies: [...],                // Cookie 配置
  },
  
  // 需求管理
  requirement: {
    docPath: './docs/requirements.md',  // 需求文档路径
    docType: 'markdown',                 // 文档类型
    todoOutput: './todos',               // TODO 输出目录
  },
  
  // 测试生成
  testGeneration: {
    framework: 'playwright',
    testDir: './tests',
    testPattern: '**/*.spec.ts',
  },
  
  // 代码审查
  codeReview: {
    enabled: true,
    reportPath: './code-review-report.md',
    rules: {
      maxComplexity: 10,
      maxLines: 100,
    },
  },
  
  // 部署配置
  deployment: {
    platform: 'vercel',
    env: 'test',
    preDeploy: ['npm run build'],
    postDeploy: ['npm run smoke-test'],
  },
  
  // 输出配置
  output: {
    directory: './output',
    format: 'json',
    verbose: true,
  },
};

与 AI (CodeWiz) 集成

本工具设计为与 CodeWiz 协作使用：

AI 的角色

1. 智能分析

   • 解析需求文档内容
   • 提取关键功能点
   • 生成合理的 TODO 列表

2. 代码生成

   • 根据 TODO 编写代码
   • 生成测试用例
   • 实现业务逻辑

3. 质量保证

   • 执行测试验证代码
   • 进行代码审查
   • 自动修复问题

工具提供的能力

1. 结构化数据

   • 标准化的配置格式
   • 清晰的 TODO 结构
   • 测试用例模板

2. 自动化流程

   • 路由截图
   • 项目分析
   • 报告生成

3. 集成接口

   • 配置加载
   • 文件管理
   • 结果输出

TypeScript 支持

完整的 TypeScript 类型定义：

import type {
  AICodeHelperConfig,
  TodoItem,
  TestCase,
  CodeReviewResult,
} from 'ai-code-helper';

const config: AICodeHelperConfig = {
  projectName: 'my-project',
  playwright: {
    browser: 'chromium',  // 类型安全
    routes: ['/'],
  },
};

编程 API

import {
  initializeProject,
  analyzeRequirement,
  generateTests,
  reviewCode,
} from 'ai-code-helper';

// 单独使用各个模块
const initResult = await initializeProject(config);
const analysis = await analyzeRequirement(config);
const testResult = await generateTests(config, testCases);
const reviewResult = await reviewCode(config);

示例

完整工作流示例

# 1. 初始化配置
cp ai-code-helper.config.example.js ai-code-helper.config.js

# 2. 编辑配置（设置路由、需求文档路径等）
vi ai-code-helper.config.js

# 3. 运行完整流程
ai-code-helper full --verbose

# 4. 查看结果
ls -la output/
ls -la screenshots/
ls -la todos/
ls -la tests/

只生成测试

ai-code-helper analyze          # 先分析需求
ai-code-helper generate-tests   # 再生成测试

跳过某些步骤

# 跳过初始化和审查，只做需求分析和测试生成
ai-code-helper full --skip-init --skip-review

项目结构

ai-code-helper/
├── src/
│   ├── config/          # 配置加载
│   ├── types/           # TypeScript 类型
│   ├── mcp/             # MCP Server 模块 ✨
│   │   ├── server.ts    # MCP Server 主入口
│   │   ├── types.ts     # MCP 类型定义
│   │   └── tools/       # 6 个工具实现
│   ├── modules/         # 核心功能模块
│   │   ├── initialization.ts
│   │   ├── requirement.ts
│   │   ├── test-generation.ts
│   │   └── code-review.ts
│   └── utils/           # 工具函数
├── bin/
│   ├── ai-code-helper.js    # CLI 入口
│   └── mcp-server.js        # MCP Server 启动脚本 ✨
├── docs/
│   ├── MCP_GUIDE.md         # MCP 完整指南
│   ├── MCP_QUICK_START.md   # MCP 快速开始
│   ├── NPM_PUBLISH_GUIDE.md # NPM 发布指南 ✨
│   └── NPM_QUICK_REFERENCE.md # NPM 快速参考 ✨
└── dist/                # 编译输出

开发

# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建
pnpm build

# 测试
pnpm test

最佳实践

1. 配置 Cookie - 确保 Playwright 能访问需要登录的页面
2. 详细需求文档 - 提供清晰的需求文档以获得更好的 TODO 生成
3. 定期审查 - 使用 review 命令保持代码质量
4. 逐步执行 - 复杂项目建议分步执行而非一次性运行完整流程
5. 版本控制 - 将生成的测试文件纳入版本控制

FAQ

为什么需要 Playwright？

Playwright 用于自动化浏览器操作，包括截图和测试执行。如果只使用需求分析功能，可以不安装。

如何提供在线需求文档？

配置中使用 URL：

requirement: {
  docPath: 'https://your-docs.com/requirements',
}

如何自定义代码审查规则？

在配置文件中添加规则：

codeReview: {
  rules: {
    maxComplexity: 10,
    maxLines: 100,
    checkTypes: true,
  },
}

License

MIT

贡献

欢迎提交 Issue 和 Pull Request！

Made with ❤️ for AI-Assisted Development