内容
# 智能工程管理平台 Enginuity AI
一款基于MCP的AI工程管理SaaS平台。Enginuity AI为工程领导者提供了一个实时指挥中心，用于监控健康状态、速度、风险和团队情报，并由AI管理器提供增强支持，可以通过Lovable管理的连接器查询实时Linear问题和Notion文档。
> **一句话介绍：** Enginuity AI是一个AI驱动的工程管理指挥中心，通过对话式管理器界面，提供实时团队健康状态、速度、风险和可行的情报。
## 什么是Enginuity AI？
Enginuity AI是工程经理的“仪表飞行平台”。它结合了：
- **工程健康状态和关键绩效指标（KPI）** - 单一得分以及速度、周期时间、拉取请求（PR）吞吐量和冲刺燃尽。
- **AI管理器聊天** - 对话式助手，可以获取和总结实时的Linear问题和Notion页面，并生成基于真实数据的报告。
- **规划和文档情报** - 搜索Notion页面，显示缺失的章节、过时的规格和文档质量差距。
- **风险和工作量信号** - AI生成的风险卡、团队工作量热图和合并就绪摘要。
- **MCP连接** - Linear、Notion、Jira、Slack、Postgres和Google Drive的集成卡和设置流程。
> **注意：** 当前版本使用模拟的工程数据进行仪表盘、项目、冲刺和分析。AI管理器可以选择通过Lovable连接器连接到实时的Linear和Notion工作区。
## 技术栈
- **框架：** [TanStack Start v1](https://tanstack.com/start) - 全栈React 19，支持SSR/SSG和边缘友好型服务器函数。
- **构建工具：** Vite 7
- **样式：** Tailwind CSS v4（原生CSS `@import` / 主题变量）
- **UI组件：** shadcn/ui + Radix UI基元
- **图表：** Recharts
- **后端/身份验证：** Lovable Cloud（Supabase）
- **AI：** Lovable AI网关，通过`ai-sdk`（`google/gemini-3-flash-preview`）
- **语言：** TypeScript 5.8（严格模式）
- **包管理器：** Bun（锁定文件：`bun.lock`）
## 功能
| 领域 | 功能 |
| --- | --- |
| **仪表盘** | 工程健康得分（92/100），KPI火花线，速度趋势，当前冲刺看板，AI情报流 |
| **AI管理器** | 流式聊天，线程历史，建议提示，实时Linear/Notion工具调用 |
| **项目** | 网格/列表视图，项目卡片，健康状态，风险，截止日期，团队和详情选项卡 |
| **冲刺** | 冲刺目标，燃尽图，团队工作量，AI风险卡 |
| **团队分析** | 生产力图表，性能表，工作量热图 |
| **拉取请求** | PR卡片，AI审查摘要，合并就绪，风险评分 |
| **风险** | 分类风险仪表盘 + AI预测卡 |
| **文档** | 文档情报，AI摘要，缺失章节检测 |
| **报告** | 每周/冲刺/执行/团队报告生成 + 导出操作 |
| **MCP连接** | 连接器卡片 + 5步设置向导 |
| **代理** | 多代理卡片（工程经理，PM，代码审查，DevOps），状态和准确性 |
| **通知** | 统一活动流 |
| **命令调色板** | 全局⌘K / Ctrl+K / `/` 命令调色板，用于即时导航，AI管理器和注销 |
| **设置** | 团队管理，角色，API密钥，AI提供商，MCP配置 |
## 架构概述
Enginuity AI分为三个协作层：**表示层**（TanStack Start路由 + shadcn UI），**数据层**（Lovable Cloud / Supabase + 模拟工程数据）和**AI + MCP层**（Lovable AI网关 + 连接器支持的工具）。
```text
┌──────────────────────────────────────────────────────────┐
│ 表示层 (React 19 + TanStack Start) │
│ - _authenticated/* 路由（仪表盘，冲刺，PR...） │
│ - AppShell，PageHeader，shadcn/ui，Recharts │
└───────────────┬──────────────────────────┬───────────────┘
│ │
│ 使用聊天/获取 │ 服务器函数
▼ ▼
┌──────────────────────────────┐ ┌────────────────────────┐
│ AI管理器 │ │ 数据层 │
│ /api/chat（streamText） │ │ Supabase身份验证 + RLS │
│ Lovable AI网关 │ │ 模拟/工程数据 │
│ google/gemini-3-flash │ │ createServerFn（RPC） │
└───────────────┬──────────────┘ └────────────┬───────────┘
│ 工具调用 │
▼ │
┌──────────────────────────────┐ │
│ MCP工作流 │ │
│ connector-gateway.lovable │ │
│ Linear（GraphQL） │◄─────────────┘
│ Notion（REST v1） │ 共享身份验证/会话
└──────────────────────────────┘
```
### 核心模块
**1. AI管理器（`src/routes/_authenticated/ai-manager.tsx` + `src/routes/api/chat.ts`）**
对话式界面。UI使用Vercel AI SDK的`useChat`从`/api/chat`流式传输消息，这是一个TanStack Start服务器路由，通过`createLovableAiGatewayProvider`（`src/lib/ai-gateway.server.ts`）调用Lovable AI网关。系统将模型框架为工程经理，并指示其优先使用工具而不是猜测。
**2. 数据层（`src/lib/mock/engineering-data.ts`，`src/integrations/supabase/*`）**
两个来源为UI提供数据：
- **模拟工程数据** - 冲刺，项目，PR，风险，KPI由仪表盘/分析路由消耗。确定性和SSR安全。
- **Lovable Cloud（Supabase）** - 身份验证 + 会话，带有`_authenticated/route.tsx`门控保护路由。服务器函数使用`requireSupabaseAuth`中间件（在`src/start.ts`中全局附加），因此RPC调用携带用户持有者令牌。
**3. MCP工作流（`src/routes/api/chat.ts`工具 + `src/routes/_authenticated/mcp-connections.tsx`）**
聊天路由注册两个工具系列，通过`connector-gateway.lovable.dev`代理：
- `linear_*` - Linear的GraphQL查询/变体（团队，问题，创建问题）。
- `notion_*` - Notion的REST调用，用于搜索，页面元数据和块内容。
每个工具在服务器端注入`LOVABLE_API_KEY`（网关身份验证）和每个连接器的密钥（`LINEAR_API_KEY`，`NOTION_API_KEY`）；秘密从未到达浏览器。MCP连接页面是这些连接器的用户端设置表面。
### 请求流程：读取Notion的聊天回合
1. 用户在`ai-manager.tsx`中输入问题；`useChat`将消息线程POST到`/api/chat`。
2. `streamText`通过Lovable AI网关调用Gemini模型。
3. 模型决定调用`notion_search`，然后调用`notion_get_page_content`。
4. 每个工具在服务器端运行，通过连接器网关获取并返回紧凑的JSON到模型。
5. 模型合成一个有根据的答案；令牌通过`toUIMessageStreamResponse`流式传输回UI。
### 边界和约定
- 应用内部逻辑使用 **`createServerFn`** （类型化的RPC）。公共/流式端点在`src/routes/api/`下使用**服务器路由**。
- 机密（`LOVABLE_API_KEY`，连接器密钥）仅在处理程序内部读取 - 从不在模块范围内，从不在客户端捆绑包中。
- 样式保留在语义令牌（`src/styles.css`）中；组件中没有硬编码的颜色。
## 项目结构
```text
src/
├── components/ # 可重用的UI组件（shadcn + 自定义）
│ ├── layout/ # AppShell，PageHeader等
│ └── ui/ # shadcn/ui基元
├── hooks/ # 自定义React钩子
├── integrations/ # Supabase客户端 + 身份验证，Lovable帮助程序
├── lib/ # 实用程序，模拟数据，服务器帮助程序
│ ├── mock/ # engineering-data.ts（模拟组织数据）
│ └── ai-gateway.server.ts
├── routes/ # TanStack Start基于文件的路由
│ ├── __root.tsx # 应用壳（头/身体/提供者）
│ ├── auth.tsx # 登录/注册
│ ├── reset-password.tsx
│ ├── _authenticated/ # 所有已身份验证的应用页面
│ └── api/chat.ts # AI管理器流式端点
├── styles.css # Tailwind v4主题令牌
├── router.tsx # 路由器配置
└── start.ts # TanStack Start入口配置
```
## 入门指南
### 先决条件
- [Bun](https://bun.sh/) >= 1.1
- Node.js >= 20（用于工具兼容性）
- 配置了Supabase身份验证的Lovable Cloud项目
### 安装
```bash
# 1. 克隆仓库
git clone https://github.com/YOUR_ORG/enginuity-ai.git
cd enginuity-ai
# 2. 安装依赖
bun install
# 3. 启动开发服务器
bun dev
```
在浏览器中打开 [http://localhost:8080](http://localhost:8080)。
### 构建生产版本
```bash
bun run build
```
在本地预览生产版本：
```bash
bun run preview
```
## 可用脚本
| 脚本 | 描述 |
| --- | --- |
| `bun dev` | 启动Vite开发服务器 |
| `bun run build` | 生产构建 |
| `bun run build:dev` | 开发模式构建 |
| `bun run preview` | 预览生产构建 |
| `bun run lint` | 运行ESLint |
| `bun run typecheck` | 运行TypeScript类型检查 |
| `bun run test` | 运行Bun测试 |
| `bun run format` | 使用Prettier格式化代码 |
| `bun run format:check` | 使用Prettier检查格式化 |
## CI / GitHub Actions
存储库包含 `.github/workflows/ci.yml`，在每次推送和拉取请求到 `main` 时运行：
1. **安装依赖** 使用 `bun install --frozen-lockfile`。
2. **运行lint** 使用 `bun run lint`。
3. **检查格式化** 使用 `bun run format:check`。
4. **类型检查** 使用 `bun run typecheck`。
5. **运行测试** 使用 `bun test`。
无法通过这些检查的拉取请求无法干净地合并。
## 环境变量
项目依赖于Lovable Cloud进行身份验证和后端。所需的变量在Lovable内部运行时会自动注入。对于本地开发，请确保在 `.env` 中存在这些变量：
```env
# Supabase（Lovable Cloud）
VITE_SUPABASE_URL=
VITE_SUPABASE_PUBLISHABLE_KEY=
SUPABASE_URL=
SUPABASE_PUBLISHABLE_KEY=
# Lovable AI网关
LOVABLE_API_KEY=
# 可选：实时连接器（由/api/chat工具使用）
LINEAR_API_KEY=
NOTION_API_KEY=
```
> **重要：** 服务角色密钥和数据库密码由Lovable Cloud管理，不会暴露。不要将 `.env` 或机密提交到版本控制。
## AI管理器和MCP工具
AI管理器（`/ai-manager`）通过 `/api/chat` 使用 Vercel AI SDK 和 Lovable AI网关。它公开了实时连接器的工具：
- **Linear：**
- `linear_list_teams` - 列出工作区团队
- `linear_list_issues` - 按指定人、团队、状态等筛选问题
- `linear_create_issue` - 创建新问题
- **Notion：**
- `notion_search` - 搜索页面和数据库
- `notion_get_page` - 获取页面元数据/属性
- `notion_get_page_content` - 从页面块中提取纯文本/降价内容
当用户询问有关规划、规格、PRD、运行手册或文档质量时，系统指示AI首先搜索Notion，获取相关页面，总结它们，并标记缺失的章节（例如，没有验收标准，没有上线计划，停滞> 90天）。
## 身份验证
- 通过Lovable Cloud（Supabase Auth）进行电子邮件/密码和Google OAuth身份验证。
- 已身份验证的路由位于 `_authenticated/` 下，并受 `_authenticated/route.tsx` 网关保护。
- 公共路由： `/auth`，`/reset-password`。
## 设计系统
- **主要调色板：** 翠绿色 `#10b981`，琥珀色 `#f59e0b`，锌表面
- **字体排版：** Inter Display标题 + JetBrains Mono用于数据/单色标签
- **暗色主题优先：** `src/styles.css`中的语义CSS令牌
- **动画：** 平滑的淡入动画
- **导航：** 可折叠的侧边栏，带有持久状态；用于键盘驱动导航的全局⌘K命令面板
- **响应式：** 侧边栏在较小的视口上折叠；图表标签和工具提示使用高对比度的翠绿色文本
## 部署
该项目是为Lovable Cloud / 边缘运行时构建的。部署由Lovable平台处理。当连接到GitHub时，变更双向同步：
1. 推送到您的GitHub存储库。
2. Lovable拉取变更并更新实时预览。
3. 从Lovable发布以使应用上线。
对于自托管，代码库使用标准开源包，可以在支持Vite + Node兼容的无服务器运行时的任何地方部署。您需要提供上述环境变量。
## 路线图 / 超出范围
当前在V1中实现：
- 带有模拟工程数据的完整UI
- 身份验证 + 路由保护
- 流式AI聊天
- Linear和Notion工具调用（当配置密钥时）
尚未实现：
- 真实的Jira / Slack API集成（UI存在，后端待定）
- 基于数据库的多租户组织
- 报告的PDF导出/电子邮件投递
## 贡献
这是Lovable管理的项目。对于重大变更，请在GitHub上打开问题或拉取请求。请保持贡献与现有的TanStack Start约定、shadcn/ui组件模式和语义设计令牌一致。
## 许可证
[MIT](LICENSE) — © Enginuity AI
---
使用Lovable + TanStack Start构建。
