lanyuanxiaoyao/Alfred
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 文档全面审查更新与规范集中化重构

Browse Source
This commit is contained in:
兰缘小妖
2026-06-01 13:13:52 +08:00
parent 897fad95eb
commit d765f86b65
8 changed files with 324 additions and 331 deletions
Download Patch File Download Diff File Expand all files Collapse all files

95
docs/development/architecture.md
View File

@@ -11,8 +11,19 @@ src/
server/
bootstrap.ts 统一启动引导（loadServerConfig -> DB 初始化 -> startServer）
config.ts CLI 参数解析与配置文件加载 facade
config/ 配置解析模块（types、issues、variables、normalizer、schema）
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
@@ -20,8 +31,7 @@ src/
projects.ts 项目数据访问函数
providers.ts 供应商数据访问函数
models.ts 模型数据访问函数
conversations.ts 会话数据访问函数
index.ts 数据库模块导出
conversations.ts 会话与消息数据访问函数
ai/ AI 服务层
types.ts AI 配置类型定义
registry.ts AI Provider Registry 构建与连接测试
@@ -33,28 +43,47 @@ src/
main.ts 生产模式启动入口
server.ts HTTP server 启动工厂（Bun.serve routes 声明式路由）
static.ts 生产模式静态资源服务
helpers.ts 共享响应格式化工具
middleware.ts API 参数校验中间件
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 路由处理器
providers/ 供应商 CRUD 路由
models/ 模型 CRUD 路由
chat/ 聊天会话与消息路由
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 入口
app.tsx 根组件
routes.tsx 路由配置
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/ 页面组件
models/ 模型管理页面
components/ UI 组件
hooks/ React Hooks
utils/ 前端工具函数
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/ 项目文档
@@ -85,7 +114,7 @@ dev.ts / main.ts
Request
-> Bun.serve routes 声明式匹配
-> routes/*.ts handler
-> helpers.ts 响应格式化
-> helpers/ 响应格式化
-> Response
```
@@ -102,17 +131,29 @@ Request
## 主要模块职责
| 模块 | 职责 |
| ------------------------- | --------------------------------------------- |
| `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、schema） |
| `src/web/` | React 前端 |
| `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，按资源端点拆分（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` | 应用全局常量 |
### 路由按资源分组
| 资源分组 | 路径前缀 | 路由文件 |
| --------- | ------------------------------------------------------------- | ---------------------------- |
| 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 文件) |
## 更新触发条件