后端开发

共享工具

src/server/helpers/:

response.ts：createApiError(error, status)、createHeaders(mode, init)、createMetaResponse(version)、formatDuration(ms)、jsonResponse(body, options)
url.ts：parseIdFromUrl(url)

src/server/middleware/:

validate.ts：validateIdParam(idStr, mode) — 校验 ID 格式（字母数字 + _-）；validatePagination(pageParam, pageSizeParam, mode) — page≥1, pageSize≤200；validateTimeRange(from, to, mode)
error-handler.ts：AppError — 业务异常类（含 statusCode）；withErrorHandler(fn, mode, logger?) — 包裹 handler 捕获异常

SQLite + bun:sqlite + Drizzle ORM。

src/server/db/schema.ts：Drizzle 表结构，列名 snake_case，TS 类型 camelCase。
src/server/db/connection.ts：createDatabase(dataDir, logger) 打开 alfred.db，PRAGMA：foreign_keys=ON、journal_mode=WAL、busy_timeout=5000。wrap(db) 转为 Drizzle 实例。paginateQuery() 分页工具。
Migration：开发期 drizzle-kit generate 产出到 drizzle/；生产期嵌入可执行文件，启动时自动应用。备份到 <dataDir>/backups/，事务中执行，失败回滚。

文件	函数
`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
`conversations.ts`	createConversation、getConversation、listConversations、updateConversation、updateConversationTimestamp、deleteConversation、createMessage、createMessages、listMessages

输入输出类型来自 src/shared/api.ts。

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) — 统计已配置模型数
src/server/ai/agents/alfred-agent.ts：createAlfredAgent(model) — ToolLoopAgent + stepCountIs(20) + getCurrentTime 工具。
src/server/ai/tools/：AI 工具定义。

type	AI SDK factory
`openai`	`createOpenAI({ apiKey, baseURL })`
`anthropic`	`createAnthropic({ apiKey, baseURL })`
`openai-compatible`	`createOpenAICompatible({ name, apiKey, baseURL })`

POST /api/providers/test — 用未保存配置测试，不写入 DB，不阻止保存。Base URL 不可达或 API Key 无效返回 ok: false；/models 不支持返回 ok: true + 提示。
POST /api/models/test — 用模型关联供应商 + modelId 测试。

方法	路径	说明
GET	`/api/projects/:id/conversations`	列出项目下所有会话
POST	`/api/projects/:id/conversations`	创建新会话
GET	`/api/projects/:id/conversations/:cid`	获取会话详情
PATCH	`/api/projects/:id/conversations/:cid`	更新会话
DELETE	`/api/projects/:id/conversations/:cid`	删除会话及消息
GET	`/api/projects/:id/conversations/:cid/messages`	获取消息列表
POST	`/api/projects/:id/chat`	发送消息，SSE 回复

send.ts：验证会话归属 → 保存用户消息 → createAlfredAgent → createAgentUIStreamResponse → onFinish 持久化 AI 回复。

唯一来源：package.json。开发模式从 package.json 运行时读取；生产模式构建时烘焙为字面量。

修改后端模块 API、共享工具、数据库 schema、AI 服务层或聊天 API 时，必须更新本文档。