docs: 开发文档面向AI精简重构，补充文档编撰规范
This commit is contained in:
@@ -1,159 +1,60 @@
|
||||
# 架构与边界
|
||||
|
||||
本文档说明 alfred 的项目结构、启动链路、运行时流程、HTTP 请求流程和前后端边界。
|
||||
|
||||
适用场景：修改目录边界、启动流程、运行时调度、HTTP server、前后端集成方式或主要模块职责。
|
||||
|
||||
## 项目结构
|
||||
|
||||
```text
|
||||
src/
|
||||
server/
|
||||
bootstrap.ts 统一启动引导（loadServerConfig -> DB 初始化 -> startServer）
|
||||
config.ts CLI 参数解析与配置文件加载 facade
|
||||
config/ 配置解析模块
|
||||
index.ts 配置模块导出
|
||||
types.ts 配置类型定义
|
||||
issues.ts 配置问题收集
|
||||
variables.ts 变量解析
|
||||
normalizer.ts 配置标准化
|
||||
schema/ JSON Schema 生成与校验
|
||||
builder.ts
|
||||
export.ts
|
||||
fragments.ts
|
||||
validate.ts
|
||||
db/ SQLite 数据库模块
|
||||
index.ts 数据库模块导出
|
||||
schema.ts Drizzle ORM schema 定义
|
||||
connection.ts 数据库连接与 PRAGMA 设置
|
||||
load-migrations.ts 从文件系统加载 migration SQL
|
||||
migrate.ts migration 执行器（备份 + 事务应用）
|
||||
projects.ts 项目数据访问函数
|
||||
providers.ts 供应商数据访问函数
|
||||
models.ts 模型数据访问函数
|
||||
conversations.ts 会话与消息数据访问函数
|
||||
ai/ AI 服务层
|
||||
types.ts AI 配置类型定义
|
||||
registry.ts AI Provider Registry 构建与连接测试
|
||||
agents/ Agent 工厂
|
||||
alfred-agent.ts Agent 工厂（ToolLoopAgent + 工具）
|
||||
tools/ 工具定义
|
||||
get-current-time.ts 获取当前时间工具
|
||||
dev.ts 开发模式启动入口
|
||||
main.ts 生产模式启动入口
|
||||
server.ts HTTP server 启动工厂（Bun.serve routes 声明式路由）
|
||||
static.ts 生产模式静态资源服务
|
||||
helpers/ 共享工具模块
|
||||
index.ts 模块导出
|
||||
response.ts 响应格式化工具
|
||||
url.ts URL 拼接工具
|
||||
middleware/ API 中间件模块
|
||||
index.ts 模块导出
|
||||
validate.ts 参数校验中间件
|
||||
error-handler.ts 错误处理中间件
|
||||
logger.ts 结构化日志（基于 pino + pino-roll）
|
||||
version.ts 运行时版本号读取
|
||||
routes/ API 路由处理器
|
||||
meta.ts 应用元信息路由
|
||||
providers/ 供应商 CRUD 与测试路由
|
||||
models/ 模型 CRUD 与测试路由
|
||||
projects/ 项目 CRUD、归档与恢复路由
|
||||
chat/ 聊天会话与消息路由（含 SSE 流式发送）
|
||||
shared/
|
||||
api.ts 前后端共享 TypeScript 类型定义
|
||||
app.ts 应用全局常量（name、title、subtitle、description）
|
||||
web/ React 前端（通过 Vite 构建）
|
||||
index.html HTML 入口
|
||||
main.tsx React 入口（StrictMode + ErrorBoundary + QueryClientProvider + BrowserRouter）
|
||||
app.tsx 根组件（设置 document 标题和 meta）
|
||||
routes.tsx 路由配置（Admin + Workbench 两大控制台）
|
||||
menu.tsx 共享菜单项类型定义
|
||||
styles.css 全局样式
|
||||
css.d.ts CSS Modules 类型声明
|
||||
pages/ 页面组件
|
||||
dashboard/ 总览页面
|
||||
projects/ 项目管理页面及其子组件
|
||||
models/ 模型管理页面及其子组件
|
||||
404/ 404 页面
|
||||
components/ 共享 UI 组件
|
||||
ErrorBoundary.tsx 错误边界
|
||||
ConsoleShell/ 通用控制台外壳（ConsoleShell、ConsoleOutlet、types）
|
||||
Sidebar/ 侧边栏导航组件
|
||||
consoles/ 控制台入口
|
||||
admin/ Admin 管理台（AdminConsoleLayout、菜单配置）
|
||||
workbench/ Workbench 工作台（ProjectGate、ConsoleLayout、菜单配置、ChatPage 等）
|
||||
hooks/ React Hooks（use-meta、use-projects、use-providers、use-models、use-conversations、主题/侧边栏偏好）
|
||||
utils/ 前端工具函数（fetch 封装、时间格式化）
|
||||
scripts/ 独立运行脚本
|
||||
tests/ 测试文件（镜像 src 目录结构）
|
||||
docs/ 项目文档
|
||||
openspec/ OpenSpec 规格、变更与 fast-drive workflow schema
|
||||
```
|
||||
|
||||
## 启动流程
|
||||
|
||||
```text
|
||||
dev.ts / main.ts
|
||||
-> parseRuntimeArgs(cli args)
|
||||
-> 必须指定 config.yaml
|
||||
-> parseRuntimeArgs(cli args) — 必须指定 config.yaml
|
||||
-> bootstrap({ configPath, mode })
|
||||
-> loadServerConfig(configPath)
|
||||
-> createRuntimeLogger(config.logging)
|
||||
-> 确保 dataDir 就绪（mkdirSync）
|
||||
-> 加载 migrations（生产：嵌入的 bytes；开发：磁盘 drizzle/ 目录）
|
||||
-> createDatabase(dataDir)
|
||||
-> runMigrations(db, migrations)（pending migration 存在时先备份 DB）
|
||||
-> startServer({ config, logger, db })
|
||||
-> logger 记录启动成功
|
||||
-> loadServerConfig(configPath)
|
||||
-> createRuntimeLogger(config.logging)
|
||||
-> mkdirSync(dataDir)
|
||||
-> 加载 migrations（生产：嵌入 bytes；开发：磁盘 drizzle/）
|
||||
-> createDatabase(dataDir)
|
||||
-> runMigrations(db, migrations) — pending 时先备份 DB
|
||||
-> startServer({ config, logger, db })
|
||||
-> SIGINT/SIGTERM -> db.close() -> logger.flush() -> exit
|
||||
```
|
||||
|
||||
## HTTP 请求流程
|
||||
|
||||
```text
|
||||
Request
|
||||
-> Bun.serve routes 声明式匹配
|
||||
-> routes/*.ts handler
|
||||
-> helpers/ 响应格式化
|
||||
-> Response
|
||||
Request -> Bun.serve routes 声明式匹配 -> routes/*.ts handler -> helpers/ 响应格式化 -> Response
|
||||
```
|
||||
|
||||
生产模式下，非 API 路径由 fetch fallback 处理：有文件扩展名的返回静态资源或 404，无扩展名的返回 SPA index.html。
|
||||
|
||||
开发模式下，Vite proxy 将 /api 请求转发到 Bun API server。
|
||||
- 生产模式：非 API 路径由 fetch fallback 处理，有扩展名返回静态资源或 404，无扩展名返回 SPA index.html。
|
||||
- 开发模式：Vite proxy 将 /api 转发到 Bun。
|
||||
|
||||
## 前后端边界
|
||||
|
||||
- 前端只通过 HTTP 调用后端，API 路径为 /api/\*。
|
||||
- 共享类型放在 src/shared/。
|
||||
- 前端不得 import src/server/ 的运行时实现。
|
||||
- 后端不得依赖 src/web/ 运行时代码，HTML import 集成除外。
|
||||
- 前端只通过 HTTP /api/\* 调用后端。
|
||||
- 共享类型在 `src/shared/`。
|
||||
- 前端禁止 import `src/server/` 运行时实现；后端禁止依赖 `src/web/` 运行时代码（HTML import 集成除外）。
|
||||
|
||||
## 主要模块职责
|
||||
## 主要模块
|
||||
|
||||
| 模块 | 职责 |
|
||||
| ------------------------- | ---------------------------------------------------------------------- |
|
||||
| `src/server/bootstrap.ts` | 统一启动引导、DB 初始化和 shutdown 编排 |
|
||||
| `src/server/server.ts` | Bun HTTP server 和 routes 注册 |
|
||||
| `src/server/routes/` | API handler，按资源端点拆分（meta、providers、models、projects、chat） |
|
||||
| `src/server/db/` | SQLite 连接、schema、migration 和 data access |
|
||||
| `src/server/ai/` | AI Provider Registry 构建与 Agent 流式调用 |
|
||||
| `src/server/config/` | 配置解析模块（types、variables、normalizer、schema） |
|
||||
| `src/server/helpers/` | 共享响应格式化和 URL 工具 |
|
||||
| `src/server/middleware/` | API 参数校验和错误处理中间件 |
|
||||
| `src/web/` | React 前端（Admin + Workbench 双控制台架构） |
|
||||
| `src/shared/api.ts` | 前后端共享 API 类型 |
|
||||
| `src/shared/app.ts` | 应用全局常量 |
|
||||
| 模块 | 职责 |
|
||||
| ------------------------- | ------------------------------------------------ |
|
||||
| `src/server/bootstrap.ts` | 统一启动引导、DB 初始化、shutdown 编排 |
|
||||
| `src/server/server.ts` | Bun HTTP server + routes 注册 |
|
||||
| `src/server/routes/` | API handler，按资源端点拆分 |
|
||||
| `src/server/db/` | SQLite 连接、schema、migration、data access |
|
||||
| `src/server/ai/` | AI Provider Registry + Agent 流式调用 |
|
||||
| `src/server/config/` | 配置解析（types、variables、normalizer、schema） |
|
||||
| `src/server/helpers/` | 响应格式化、URL 工具 |
|
||||
| `src/server/middleware/` | 参数校验 + 错误处理 |
|
||||
| `src/shared/api.ts` | 前后端共享 API 类型 |
|
||||
| `src/shared/app.ts` | 应用全局常量 |
|
||||
|
||||
### 路由按资源分组
|
||||
## 路由分组
|
||||
|
||||
| 资源分组 | 路径前缀 | 路由文件 |
|
||||
| --------- | ------------------------------------------------------------- | ---------------------------- |
|
||||
| meta | `/api/meta` | `routes/meta.ts` |
|
||||
| providers | `/api/providers` | `routes/providers/` (7 文件) |
|
||||
| models | `/api/models` | `routes/models/` (6 文件) |
|
||||
| projects | `/api/projects` | `routes/projects/` (7 文件) |
|
||||
| chat | `/api/projects/:id/conversations` 和 `/api/projects/:id/chat` | `routes/chat/` (7 文件) |
|
||||
| 资源 | 路径前缀 | 文件目录 |
|
||||
| --------- | ----------------------------------------------- | ------------------- |
|
||||
| meta | `/api/meta` | `routes/meta.ts` |
|
||||
| providers | `/api/providers` | `routes/providers/` |
|
||||
| models | `/api/models` | `routes/models/` |
|
||||
| projects | `/api/projects` | `routes/projects/` |
|
||||
| chat | `/api/projects/:id/conversations` 和 `:id/chat` | `routes/chat/` |
|
||||
|
||||
## 更新触发条件
|
||||
|
||||
|
||||
Reference in New Issue
Block a user