PE Agent 前端二次开发指南¶
文档版本：v1.0 文档初稿
适用范围：PE Agent 前端私有化部署与二次开发
读者对象：前端开发、系统集成、部署和维护人员
最后核对日期：2026-08-13
代码事实来源：PE Agent 前端当前仓库
1. 文档边界¶
本文只说明 PE Agent 前端项目：
- Next.js 页面、组件和布局；
- 浏览器状态管理；
- 前端 Service 与同源 API 代理；
- 登录状态在前端的处理；
- SSE 流式交互；
- 运行时配置、品牌定制、构建和容器部署；
- 前端日志、健康检查和常见故障。
本文不说明：
- PowerCore 或其他后端服务的内部实现；
- 智能体工作流后台的编排方法；
- 数据库结构；
- 后端部署、扩容和数据备份。
涉及 /server/* 时，仅描述前端的代理行为与接口假设，后端接口契约以对应后端文档为准。
2. 技术栈¶
| 类别 | 当前实现 |
|---|---|
| 应用框架 | Next.js App Router、React 19、TypeScript 5 |
| UI | Ant Design、Ant Design X |
| 样式 | Tailwind CSS 4、Ant Design Theme Token |
| 状态管理 | Zustand |
| HTTP | Axios、Fetch、SSE |
| 构建输出 | Next.js standalone，输出目录为 build/ |
| 生产运行 | Node.js 24、Docker Compose |
| 包管理器 | pnpm 10 |
具体依赖版本以当前代码中的 package.json 和 pnpm-lock.yaml 为准，不要只依赖本文中的概括。
3. 阅读顺序¶
4. 实现事实优先级¶
代码和文档发生不一致时，按以下优先级核对：
- 当前
src/app页面和 Route Handler； - 当前组件、Service、Store 和运行时配置代码；
package.json、next.config.js、Dockerfile和 Compose；- 前端仓库中的架构与专题文档；
- README 中的历史说明。
当前 README 中部分旧路由在 src/app 已不存在，二开时不要根据旧路由清单恢复或链接页面，除非项目需求明确要求重新开发。
5. 二开基本原则¶
- 路由入口保持轻量，复杂 UI 放在
src/components/； - 后端接口调用集中在
src/services/； - 共享读模型和跨组件状态放在 Zustand Store；
- 一次性提交操作优先使用
useServiceRequest； - 后端接口通过同源
/server/*访问； - 前端自有 Route Handler 使用
/api/*； - 服务端私密配置只能从 server-only 模块读取；
- 浏览器可见的运行时配置不允许放密钥；
- 页面跳转和静态资源必须兼容
APP_BASE_PATH； - 日志使用统一 logger，不直接散落
console.*； - 修改后至少执行构建和与改动相关的手工验证。