振动 Vibe

说明文档

功能概述

• 研究：探讨现代 JavaScript 框架
• 生成规则：为移动银行应用创建开发准则
• 生成产品需求文档（PRD）：制定任务管理应用的 PRD
• 生成用户故事：为电子商务网站编写用户故事
• 生成任务列表：基于用户故事生成天气应用程序的任务清单
• 顺序思考：构思微服务架构的电子商务平台
• 全栈启动套件：创建 React/Node.js 博客应用的启动套件，含用户认证功能
• 生成代码片段：编写名为 calculate_discount 的 Python 函数 stub，传入价格和折扣率
• 重构代码：将代码重构为使用 async/await 的形式
• 分析依赖项：审查 package.json 中的依赖关系
• 显示未提交更改：查看 Git 未提交的修改
• 运行工作流：执行 newProjectSetup 工作流，输入参数包括 "projectName": "my-new-app" 和 "description": "A simple task manager"

安装指南

先决条件

1. Node.js：需安装 Node.js 14 或以上版本。
2. npm：确保 npm 已正确安装。

安装步骤

1. 克隆仓库

   git clone https://github.com/yourusername/yourrepo.git
   cd yourrepo
   

2. 安装依赖

   npm install
   

3. 构建项目

   npm run build
   

4. 启动服务
   • 生产模式：

     npm start
     

   • 开发模式：

     npm run dev
     

配置指南

环境变量

1. API 密钥
   • OpenRouter API Key：在 .env 文件中设置 OPENROUTER_API_KEY，确保密钥有效且有足够额度。
2. 日志级别
   • 在 .env 中添加 LOG_LEVEL=debug 以启用调试模式。

工作流配置

1. 创建工作流文件：在 workflows/ 目录下新建 JSON 文件，定义工作流步骤和参数。
2. 注册工作流：

   {
     "id": "newProjectSetup",
     "name": "新项目设置",
     "description": "初始化新项目的必需工具",
     "steps": [
       { "tool": "projectName", "input": "{ \"projectName\": \"my-new-app\" }" },
       { "tool": "description", "input": "{ \"description\": \"A simple task manager\" }" }
     ]
   }
   

运行模式

标准输入（AI 代理）

• 生产模式：

  npm start
  

  • 日志输出至标准错误流，模拟 AI 代理启动。
  • 使用 NODE_ENV=production 环境变量。

• 开发模式：

  npm run dev
  

  • 日志以彩色格式输出，便于调试。
  • 需要安装 nodemon 和 pino-pretty。

HTTP 接口（SSE 模式）

• 生产模式：

  npm run start:sse
  

• 开发模式：

  npm run dev:sse
  

  • 使用 HTTP 协议通信，默认监听端口 3000。
  • 访问地址：http://localhost:3000。

故障排除

连接问题

MCP 服务器未被 AI 代理识别

1. 检查配置路径：

   • 确认 args 数组中的绝对路径正确无误。
   • 使用全斜杠 /，即使在 Windows 上。
   • 直接运行 node <path-to-build/index.js> 测试 Node 是否能找到该路径。

2. 检查配置格式：

   • 确保 JSON 语法正确，无语句错误。
   • 核对 mcpServers 对象中的服务器配置是否完整。

3. 重启代理程序：

   • 完全关闭（而非最小化）应用后重新打开。

服务器运行但工具不可用

1. 检查禁用标志：

   • 确认 "disabled": false 设置正确。
   • 移除任何可能导致此值为 true 的因素。

2. 检查工作流注册：

   • 确保所有自定义工作流已正确加载，特别是 newProjectSetup。

工具列表

1. 项目名称

   • 描述：输入新项目的名称。
   • 示例："my-new-app"

2. 项目描述

   • 描述：简要概述项目用途或目标。
   • 示例："A simple task manager"

3. 研究工具

   • 支持查询技术趋势、框架特性等。

4. 生成规则工具

   • 依据输入生成具体的开发规范文档。

5. 生成 PRD 工具

   • 输出结构化的项目需求文档。

6. 生成用户故事工具

   • 制定用户角色和对应需求。

7. 生成任务列表工具

   • 产出项目相关的任务清单，可排序和优先级设定。

8. 顺序思考工具

   • 辅助进行系统架构设计或技术选型。

9. 全栈启动套件工具

   • 提供基础项目搭建模板，包括依赖管理、配置文件等。

10. 生成代码片段工具

    • 依据输入参数生成相应的代码逻辑。

11. 重构代码工具

    • 将现有代码转换为异步处理形式。

12. 分析依赖工具

    • 审查项目依赖，识别潜在风险或优化机会。

13. 显示未提交更改工具

    • 展示 Git 仓库中的未提交修改。

示例工作流

初始化新项目

{
  "id": "newProjectSetup",
  "name": "新项目设置",
  "description": "初始化新项目的必需配置和依赖",
  "steps": [
    { "tool": "projectName", "input": "{ \"projectName\": \"my-new-app\" }" },
    { "tool": "description", "input": "{ \"description\": \"A simple task manager\" }" }
  ]
}

生成开发规范

{
  "id": "generateDevelopmentGuidelines",
  "name": "生成开发准则",
  "description": "为项目制定详细的技术规范和最佳实践",
  "steps": [
    { "tool": "generateRules", "input": "{ \"project\": \"my-new-app\" }" }
  ]
}

日志与监控

1. 日志级别

   • 调试模式：DEBUG=true
   • 信息模式：默认
   • 错误模式：NODE_ENV=production

2. 监控工具

   • 使用 pm2 或其他进程管理器，确保服务稳定运行。
   • 配置日志文件，便于排查问题。

安全注意事项

1. 环境变量安全：

   • 确保敏感信息如 API 密钥不写入版本控制系统。

2. 输入验证：

   • 对所有外部输入进行严格验证和 sanitization，防止注入攻击或其他安全漏洞。

3. 日志管理：

   • 避免在日志中记录敏感信息，确保合规性。

升级指南

1. 依赖升级

   npm update
   

2. 工作流更新

   • 检查并更新 workflows/ 目录下的所有 JSON 文件。
   • 确保新增或修改的工作流与现有系统兼容。

3. 配置调整

   • 更新 .env 文件中的参数，如新密钥或日志级别。
   • 重启服务以应用更改。

贡献指南

1. 代码贡献

   • Fork 仓库后提交 Pull Request。
   • 遵循项目编码规范和提交指南。