Onboard Mate-AI驱动的项目车载助手
一个人工智能驱动的代理工作流系统，使用模型上下文协议（MCP）自动为软件项目生成全面的入职指南。
概述
机载伴侣使用：
- Next.js 用于前端UI
- MCP服务器 用于存储库检查工具
- 谷歌双子座2.5 Flash（预览版） 智能规划与综合
- 代理工作流 协调整个过程
特性
- 自动分析项目存储库
- 为信息收集制定智能计划
- 使用MCP工具检查文件和代码
- 在Markdown中生成全面的入职文档
- 显示所有工具调用和决策的透明日志
建筑
┌──────────────────────────┐
│ Next.js UI │
│ - Input repo ID │
│ - Run agent │
│ - Render output │
└───────────────┬──────────┘
│ POST /api/agent
┌───────────────▼──────────┐
│ Agent (Node.js + TS) │
│ - Calls LLM (Plan) │
│ - Discovers MCP tools │
│ - Executes tool calls │
│ - Calls LLM (Synthesis) │
└───────────────┬──────────┘
│ MCP Protocol
┌───────────────▼──────────┐
│ MCP Server │
│ - list_files │
│ - read_file │
│ - search_code │
│ *Sandboxed FS Access* │
└───────────────┬──────────┘
│
┌───────▼────────┐
│ repos/ │
└─────────────────┘设置
先决条件
- Node.js 18+
- npm 8+
- Google Gemini API密钥（免费https://makersuite.google.com/app/apikey)
安装
- 克隆存储库：
git clone
cd onboard-mate- 安装依赖项：
npm install- 配置环境变量：
cp .env.example .env编辑 .env 并添加您的Google Gemini API密钥：
GEMINI_API_KEY=your-api-key-here获取您的免费API密钥：https://makersuite.google.com/app/apikey
- 测试你的双子座连接 （推荐）：
npm run test-gemini这将验证您的API密钥，并显示您所在地区的可用模型。
运行应用程序
启动开发服务器：
npm run dev打开 http://localhost:3000 在您的浏览器中。
用法
- 输入存储库ID：键入位于以下位置的存储库文件夹的名称
/repos/（例如。，demo-repo)
- 生成指南：单击“生成指南”按钮
- 查看结果：UI将显示：
- 代理计划：人工智能分析存储库的策略 - 工具调用日志：所有MCP工具调用的详细日志 - 入职指南：最终生成的Markdown文档
演示存储库
示例存储库包含在 /repos/demo-repo这是一个简单的Express.js REST API，它演示了：
- 项目结构
- 配置文件
- 源代码组织
- 测试设置
MCP工具
系统提供三个MCP工具：
list_files
列出存储库中的所有文件（不包括node_modules、.git等）
参数：
repoId：存储库标识符
read_file
读取特定文件的内容
参数：
repoId：存储库标识符filePath：文件的相对路径maxBytes：要读取的最大字节数（默认值：50000）
search_code
使用grep搜索代码模式
参数：
repoId：存储库标识符pattern：搜索模式（支持正则表达式）filePattern：可选的文件模式过滤器（例如“\*.js”）
安全
- 存储库验证：系统在处理之前检查存储库是否存在
- 路径验证：严格的验证可防止目录遍历攻击
- 沙盒访问：MCP服务器仅访问内的文件
/repos/ - 内容截断：截断大文件以防止令牌过度使用
- 无命令执行：MCP服务器不执行任意命令
项目结构
onboard-mate/
├── app/ # Next.js app directory
│ ├── api/agent/ # API endpoint for agent execution
│ ├── layout.tsx # Root layout
│ ├── page.tsx # Home page
│ └── globals.css # Global styles
├── components/ # React components
│ ├── OnboardingAgent.tsx
│ ├── PlanDisplay.tsx
│ ├── ToolCallsDisplay.tsx
│ └── MarkdownDisplay.tsx
├── lib/ # Core libraries
│ ├── agent/ # Agent orchestrator
│ └── mcp/ # MCP client
├── mcp-server/ # MCP server implementation
│ └── index.ts
├── repos/ # Repository storage
│ └── demo-repo/ # Demo repository
└── docs/ # Documentation
└── BRD.md # Business Requirements Document发展
运行测试
npm test代码检查
npm run lint生产大楼
npm run build
npm start故障排除
找不到模型错误（404）
如果你看到一个错误，比如 models/gemini-1.5-flash is not found:
- 运行测试脚本：
npm run test-gemini这将显示哪些模型可以使用您的API密钥。
- 更新型号名称：
编辑 lib/agent/orchestrator.ts 并切换到工作模式：
- 代码当前配置为 gemini-2.5-flash-preview-09-2025 - 如果这不起作用，试试 gemini-pro 或测试脚本显示的其他模型
- 请参阅完整的故障排除指南：
检查 docs/TROUBLESHOOTING.md 详细解决方案
API关键问题
- 确保
.env文件存在于项目根目录中 - 验证密钥是否正确（无多余空格）
- 在以下位置获取新密钥：https://makersuite.google.com/app/apikey
其他问题
请参阅全面的故障排除指南：
docs/TROUBLESHOOTING.md-常见问题和解决方案docs/GEMINI_MIGRATION.md-Gemini特定细节
局限性
- 设计为概念验证（PoC）
- 无身份验证或授权
- 仅限单用户、本地文件系统访问
- LLM令牌限制可能需要截断大型存储库
- 没有GitHub/GitLab集成（仅使用本地文件系统）
未来的增强功能
- GitHub/GitLab存储库集成
- 支持多用户身份验证
- 实时流式传输代理进度
- 自定义工具插件
- 支持多个LLM提供商
- 大型存储库的缓存和优化
许可证
麻省理工学院
作者
沙姆舒丹