From 29bf61f7a385673bc7143614ccd10ccabaea7172 Mon Sep 17 00:00:00 2001 From: lanyuanxiaoyao Date: Mon, 1 Jun 2026 23:33:16 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=E5=BC=80=E5=8F=91?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E8=87=B3=E4=BB=A3=E7=A0=81=E6=9C=80=E6=96=B0?= =?UTF-8?q?=E7=8A=B6=E6=80=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/development/README.md | 4 +++- docs/development/architecture.md | 30 ++++++++++++++++-------------- docs/development/backend.md | 7 +++---- 3 files changed, 22 insertions(+), 19 deletions(-) diff --git a/docs/development/README.md b/docs/development/README.md index 37a169c..452122e 100644 --- a/docs/development/README.md +++ b/docs/development/README.md @@ -42,6 +42,7 @@ AI 工具必须严格遵守以下全部约束。 | `src/server/` | 后端，禁止 import src/web/ | | `src/server/db/` | 数据库层：schema、connection、migration、DAO | | `src/server/ai/` | AI Provider Registry + Agent + 工具 | +| `src/server/config/` | 配置子系统：types、variables、issues、schema | | `src/server/helpers/` | 跨路由工具：响应格式化、URL 拼接 | | `src/server/middleware/` | 参数校验 + 错误处理中间件 | | `src/web/` | 前端，禁止 import src/server/ 运行时实现 | @@ -54,7 +55,8 @@ AI 工具必须严格遵守以下全部约束。 ### 类型与配置 - 共享类型唯一源头：`src/shared/api.ts`；应用常量唯一源头：`src/shared/app.ts`；版本号唯一源头：`package.json`。 -- 配置加载流程：unknown → AuthoringConfig → NormalizedConfig → ValidatedConfig → ServerConfig。 +- 配置加载流程：unknown → AuthoringConfig → NormalizedConfig → ValidatedConfig → ResolvedConfig。 +- 配置系统入口：`src/server/config.ts`（统一配置加载、运行时校验、默认值解析）。 - Ajv 严格拒绝模式：不类型转换、不注入默认值、不删除未知字段。 - 新增/修改配置字段必须同步更新 TypeBox schema、`config.schema.json`、测试和用户文档。 diff --git a/docs/development/architecture.md b/docs/development/architecture.md index f341198..e9406a6 100644 --- a/docs/development/architecture.md +++ b/docs/development/architecture.md @@ -6,8 +6,8 @@ dev.ts / main.ts -> parseRuntimeArgs(cli args) — 必须指定 config.yaml -> bootstrap({ configPath, mode }) - -> loadServerConfig(configPath) - -> createRuntimeLogger(config.logging) + -> loadServerConfig(configPath) — 加载并校验配置（config.ts） + -> createRuntimeLogger(config.logging) — 创建 Logger 实例 -> mkdirSync(dataDir) -> 加载 migrations（生产：嵌入 bytes；开发：磁盘 drizzle/） -> createDatabase(dataDir) @@ -33,18 +33,20 @@ Request -> Bun.serve routes 声明式匹配 -> routes/*.ts handler -> helpers/ ## 主要模块 -| 模块 | 职责 | -| ------------------------- | ------------------------------------------------ | -| `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` | 应用全局常量 | +| 模块 | 职责 | +| ------------------------- | -------------------------------------------------------- | +| `src/server/bootstrap.ts` | 统一启动引导、DB 初始化、shutdown 编排 | +| `src/server/config.ts` | 配置加载入口：YAML 解析、规范化、契约校验、运行时校验 | +| `src/server/config/` | 配置子系统：types、variables、issues、normalizer、schema | +| `src/server/logger.ts` | Logger 接口 + Pino 实现 + 测试替身 | +| `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/helpers/` | 响应格式化、URL 工具 | +| `src/server/middleware/` | 参数校验 + 错误处理 | +| `src/shared/api.ts` | 前后端共享 API 类型 | +| `src/shared/app.ts` | 应用全局常量 | ## 路由分组 diff --git a/docs/development/backend.md b/docs/development/backend.md index 3319bc8..1082ab0 100644 --- a/docs/development/backend.md +++ b/docs/development/backend.md @@ -28,7 +28,7 @@ SQLite + bun:sqlite + Drizzle ORM。 | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `projects.ts` | createProject、getProject、listProjects、updateProject、deleteProject、archiveProject、restoreProject | | `providers.ts` | createProvider、getProvider、listProviders、listProviderOptions、updateProvider、deleteProvider | -| `models.ts` | createModel、getModel、listModels、getModelsByProviderId、updateModel、deleteModel | +| `models.ts` | createModel、getModel、listModels、getModelWithProvider、getModelsByProviderId、updateModel、deleteModel | | `conversations.ts` | createConversation、getConversation、listConversations、updateConversation、updateConversationTimestamp、deleteConversation、createMessage、createMessages、listMessages | 输入输出类型来自 `src/shared/api.ts`。 @@ -38,9 +38,8 @@ SQLite + bun:sqlite + Drizzle ORM。 - `src/server/ai/types.ts`：`AIProviderConfig`（name、type、baseUrl、apiKey）、`AIModelConfig`（providerId、modelId、capabilities）。 - `src/server/ai/registry.ts`： - `buildProviderRegistry(db)` — 从 DB 查询供应商构建 AI SDK Provider Registry，每次调用重建，不缓存。通过 `registry.languageModel('providerId:modelId')` 获取模型实例。 - - `testProviderConnection(config)` — 测试 Base URL 可达性 + `/models` 接口 - - `testModelConnection(config)` — 测试模型连通性 - - `countModels(db)` — 统计已配置模型数 + - `testProviderConnection(config, logger)` — 测试 Base URL 可达性 + `/models` 接口 + - `testModelConnection(config, logger)` — 测试模型连通性（需传入含 modelId 的合并配置） - `src/server/ai/agents/alfred-agent.ts`：`createAlfredAgent(model)` — ToolLoopAgent + `stepCountIs(20)` + `getCurrentTime` 工具。 - `src/server/ai/tools/`：AI 工具定义。