Frontier Agent Workbench

面向 Vue 前端项目的 AI 驱动、受控 Mock API 工程助手。

它使用 OpenAI Agents SDK 编排 DeepSeek 模型和本地仓库工具，读取已有的 Vue SFC、TypeScript 类型和请求代码，从页面实际需求反推出接口契约，生成可运行的 Mock CRUD 接口。所有代码改动都会先以 diff 展示，只有在用户批准后才写入目标项目，并在完成后执行类型检查。

解决的问题

前端开发常常会遇到页面、类型已经存在，但后端接口尚未完成的情况。手动编写 Mock 数据时，字段、请求地址、分页格式和页面类型容易不一致。

Frontier 将这条链路收敛为一个受控工作流：

选择 Vue 项目
  -> 分析源码和类型
  -> 推导接口契约
  -> 生成 MSW Mock CRUD 补丁
  -> 展示 diff 并等待批准
  -> 写入文件
  -> 运行受控 TypeScript 检查
  -> 验证 MSW CRUD 接口

当前功能

0. AI Agent 运行时

• OpenAI Agents SDK 负责 Agent 循环和工具调用
• DeepSeek deepseek-v4-flash 负责理解自然语言任务、分析仓库证据和制定修改计划
• inspect_repository 工具读取技术栈、类型、请求地址和相关源码
• prepare_mock_proposal 工具生成待审批补丁，不直接写入文件
• Agent 按 inspect_repository → prepare_mock_proposal → 最终说明 循环执行，工具结果会回传给模型
• 单次请求最多执行 6 轮；生成 proposal 后会关闭工具，等待用户审批，不会重复生成补丁
• OpenAI tracing 默认关闭，DeepSeek Key 只发送给 DeepSeek API

1. Vue 项目分析

Agent 在指定工作区内扫描 src 或 app 目录中的 .vue、.ts、.tsx、.js 和 .jsx 文件，并识别：

• 项目技术栈，例如 Vue 3 + Vite
• 包管理器，例如 npm、pnpm 或 yarn
• 请求方式，例如 fetch、axios 或 TanStack Query
• 页面使用的实体 TypeScript 类型及其字段
• 请求代码中的 /api/... 接口地址

Vue 单文件组件中的 <script setup lang="ts"> 会参与分析。

1.5 上传工作区与导出

控制台支持浏览器选择并上传一个项目文件夹。上传内容会写入独立的 .agent-workspaces/<uuid> 目录，完成修改后可以点击“导出 ZIP”下载该隔离工作区。导出接口只接受服务端生成的 UUID，不会读取工作区之外的文件。

2. Mock API 契约推导

根据找到的实体类型和请求地址，Agent 会为一个资源生成：

• 列表接口，支持 page、pageSize 和 keyword
• 新增接口：POST /api/resource
• 修改接口：PUT /api/resource/:id
• 删除接口：DELETE /api/resource/:id
• 与页面实体类型一致的种子数据
• 目标项目必须已经声明 msw 依赖；Agent 不会自动安装依赖

当前生成器会把 MSW 完整接入目标前端，产物通常包括：

src/mocks/<entity>.handlers.ts
src/mocks/browser.ts
public/mockServiceWorker.js
src/main.ts（或检测到的应用入口）

生成方案会检查目标项目是否声明 msw 依赖，并在检测到的入口文件中加入 worker.start({ onUnhandledRequest: "bypass" })。这些文件都会先以 diff 展示，只有批准后才会写入。

3. 审批式修改

生成结果不会立刻写入磁盘。控制台会先展示：

• 推导出的字段契约
• 生成计划
• 每个文件的 unified diff
• 将创建或修改的文件列表

用户点击“批准并应用补丁”后，服务端才会写入这些已经展示过的文件。

4. 验证与执行轨迹

补丁应用后，Agent 使用后端宿主项目中固定的检查器验证目标项目：

• Vue 项目使用宿主的 vue-tsc
• 其他 TypeScript 项目使用宿主的 tsc
• 参数固定为 --noEmit --pretty false --project tsconfig.json
• 通过 execFile、shell: false 和 60 秒超时执行
• 不读取、不执行上传项目 package.json 中的 typecheck 脚本
• 随后使用 msw/node 受控启动本次生成的 handler，依次验证 GET、POST、PUT、DELETE
• 验证前会确认入口包含 worker.start()、Service Worker 文件有效，且 handler 内容没有被审批后替换
• 控制台会显示成功或失败状态、命令和输出

安全边界

• 只能读取和写入当前工作区内的项目
• 拒绝路径穿越，不能写到目标项目之外
• 补丁在批准前只保存在内存中
• 只执行受控的类型检查命令
• 不会自动安装依赖、删除文件或修改未出现在 diff 中的应用文件
• API Key 只在后端读取，不会暴露给前端；生成真实 DeepSeek Agent proposal 需要配置 DEEPSEEK_API_KEY

技术栈

• Vue 3 + Vite
• TypeScript + vue-tsc
• Express
• OpenAI Agents SDK
• DeepSeek OpenAI-compatible Chat Completions API
• OpenAI Node SDK，用于连接 DeepSeek 兼容端点
• TypeScript Compiler API，用于类型结构分析
• MSW，用于浏览器 Mock API
• Vitest，用于 Agent 流程测试

目录组织

src/                 Vue 工作台界面、API 客户端和前端类型
server/index.ts      Express HTTP 入口与审批、验证路由
server/services/     DeepSeek Agent、仓库分析与 Mock 补丁生成
server/shared/       路径安全策略与服务端领域类型
server/tests/        服务端单元测试
samples/             可用于演示完整流程的 Vue 示例项目

快速开始

要求：Node.js 22 或更高版本。

npm install

复制环境变量模板并配置仅后端使用的 DeepSeek Key：

copy .env.example .env

DEEPSEEK_API_KEY=your_key
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-v4-flash

然后启动：

npm run dev

打开 http://localhost:5173。默认项目路径为 samples/product-admin，这是一个 Vue 商品管理示例，可演示分析、生成、审批和验证流程；上传项目后还可以导出修改后的 ZIP。

也可以独立运行完整示例项目：

cd samples/product-admin
npm install
npm run dev

然后打开 http://127.0.0.1:5174。示例入口会先启动 MSW Service Worker，再挂载商品列表页面；页面请求 /api/products 会由本地 handler 返回，不需要真实后端。

常用命令

# 启动前端控制台和 Agent API
npm run dev

# 仅启动 Agent API
npm run server

# 开发 Agent API（监听后端文件变化）
npm run server:watch

# Vue 类型检查
npm run typecheck

# 运行测试（单 worker，降低 MSW 动态加载时的内存峰值）
npm run test

# 生产构建
npm run build

HTTP 接口

方法	路径	说明
GET	/api/health	检查 Agent API 服务是否正常
GET	/api/agent/status	检查 DeepSeek Agent 是否已配置
POST	/api/workspaces/upload	上传项目文件夹到隔离工作区
GET	/api/workspaces/:id/export	下载指定上传工作区的 ZIP
POST	/api/inspect	分析目标项目，识别技术栈、类型和请求地址
POST	/api/proposals	生成待审批的 Mock API 补丁
POST	/api/proposals/:id/apply	应用已展示且待审批的补丁
POST	/api/proposals/:id/verify	使用受控检查器验证目标项目

请求体示例：

{
  "projectPath": "samples/product-admin",
  "task": "根据商品页面和类型生成 CRUD Mock API"
}

示例流程

示例项目定义了 Product 类型，并通过 axios 请求 /api/products。运行 Agent 后会识别这些证据，并生成：

GET    /api/products?page=1&pageSize=10&keyword=...
POST   /api/products
PUT    /api/products/:id
DELETE /api/products/:id

生成的处理器会返回与 Product 类型匹配的字段，并提供内存中的分页、筛选、创建、更新和删除行为。

第一阶段范围

第一阶段专注于“根据 Vue 页面、类型和请求代码生成 Mock API、接入 MSW Worker，并完成审批和验证”的单一闭环。

尚未包含的能力包括：OpenAPI 双向同步、向量检索、真实后端服务生成、自动修复构建错误和多 Agent 编排。这些适合在当前流程稳定后再逐步加入。