Backend 开发文档
Backend 是平台控制面，负责 API、权限、数据持久化、AI Agent、预览 artifact、构建任务和产物托管。
文档导航
| 文档 | 内容 |
|---|---|
| API 分层与契约 | 路由、schema、service、repository 分层和接口变更规则 |
| AI Agent 运行态 | 会话、run、HITL、诊断 CLI 和模型 trace |
| AI 模型配置与目录 | 聊天模型、图片模型、Models.dev 目录和协议白名单 |
| AI 模型能力与推理策略 | 模型能力档案、三态四档、上下文预算和兼容快照 |
| AI 凭证密钥轮换与迁移 | Fernet 密钥机制、安全检查与数据库凭证平滑重密迁移 |
| AI 工具规格 | tool_specs.py 单一事实源和防漂移要求 |
| 重资源队列与复用运行态 | AI 页面变更、截图、Runtime 与 Chromium 的限流、恢复和排障 |
| 运行态存储适配器 | Redis / memory:// 契约、Lite 正式适配器边界与禁止事项 |
| 远程渲染执行服务架构设计 | Renderer 边界、调度、执行契约与发布验收设计 |
| AI Agent 图片处理机制 | 图片上传、模型水合、工具输出和历史持久化 |
| 预览 artifact 与构建任务 | 预览、截图、构建 snapshot 和产物托管 |
| 时间存储与展示 | UTC 存储、历史无时区值和 Editor 展示规则 |
| Backend 排障 | 数据库、Redis、Runtime、AI 和截图常见问题 |
修改原则
- 路由、模型、仓储和业务逻辑不要写进同一个文件。
- 新增接口前先明确路径、入参、出参、权限和错误语义。
- 涉及页面源码、组件源码和 previewSchema 导入时，必须经过 Backend 边界校验。
- AI 工具目录只以
backend/app/ai/tool_specs.py为单一事实源。