forked from boos/BoosAPI
Cita
8ebfc39745
* refactor: add harness engineering guardrails * fix: address harness review feedback --------- Co-authored-by: apple <apple@appledeMacBook-Pro.local>
106 lines
4.7 KiB
Markdown
106 lines
4.7 KiB
Markdown
# Metapi 项目结构
|
||
|
||
本文档只说明当前仓库里长期维护的主目录，帮助贡献者快速判断代码、脚本和文档应当放在哪里。
|
||
|
||
## 顶层目录
|
||
|
||
```text
|
||
metapi/
|
||
├── build/ # 打包静态资源（如 Electron 图标）
|
||
├── data/ # 默认运行时数据目录（SQLite、日志、导出文件）
|
||
├── dist/ # 构建产物（web / server / desktop）
|
||
├── docker/ # Dockerfile、Compose 与部署模板
|
||
├── docs/ # VitePress 文档、截图、Logo 与社区规范
|
||
├── drizzle/ # Drizzle SQL 迁移与 meta 快照
|
||
├── scripts/ # 开发脚本、桌面打包钩子、一次性 codemod
|
||
├── src/
|
||
│ ├── desktop/ # Electron 主进程与桌面运行时
|
||
│ ├── server/ # Fastify 服务、数据库、代理路由与业务服务
|
||
│ └── web/ # React 管理后台
|
||
├── tmp/ # 临时调试文件（已 gitignore）
|
||
├── restart.bat # Windows 快捷重启入口，转发到 scripts/dev/restart.bat
|
||
├── package.json # 脚本入口与依赖清单
|
||
├── electron-builder.yml # 桌面打包配置
|
||
├── drizzle.config.ts # Drizzle 配置
|
||
├── vite.config.ts # Web 构建配置
|
||
└── tsconfig*.json # TypeScript 配置
|
||
```
|
||
|
||
## 源码目录
|
||
|
||
### `src/server`
|
||
|
||
```text
|
||
src/server/
|
||
├── index.ts # Fastify 启动、运行时初始化、启动摘要输出
|
||
├── config.ts # 环境变量解析与 Fastify 配置
|
||
├── desktop.ts # 桌面模式下的静态资源与公开路由适配
|
||
├── nativeModuleGuard.ts # better-sqlite3 ABI 兼容检查
|
||
├── db/ # schema、连接、迁移、兼容列修复
|
||
├── middleware/ # 认证等通用中间件
|
||
├── routes/
|
||
│ ├── api/ # 管理端 API（sites / accounts / tokens / settings ...）
|
||
│ └── proxy/ # OpenAI / Claude / Gemini 兼容代理入口
|
||
├── services/ # 业务服务、平台适配器、日志 / 文件 / 路由 / 迁移能力
|
||
└── transformers/ # 协议转换与共享归一化层
|
||
```
|
||
|
||
- 新的管理接口优先放在 `routes/api/`。
|
||
- 新的 `/v1/*`、多模态、文件、视频等兼容代理逻辑放在 `routes/proxy/`。
|
||
- 协议格式转换或跨协议共享归一化，优先落在 `transformers/` 而不是路由文件里。
|
||
|
||
### `src/web`
|
||
|
||
```text
|
||
src/web/
|
||
├── main.tsx # Vite 入口
|
||
├── App.tsx # 路由与页面装配
|
||
├── api.ts # 管理端 API 客户端
|
||
├── authSession.ts # 登录态管理
|
||
├── appLocalState.ts # 本地安装 / UI 状态
|
||
├── docsLink.ts # 文档链接映射
|
||
├── i18n*.ts* # 国际化
|
||
├── components/ # 通用组件与图表组件
|
||
├── pages/ # 路由页与页面级 helpers
|
||
└── public/ # Web 静态资源
|
||
```
|
||
|
||
- 页面级测试和 helper 与页面代码同目录维护。
|
||
- 通用展示组件放 `components/`；只被单页消费的纯逻辑优先放 `pages/helpers/`。
|
||
|
||
### `src/desktop`
|
||
|
||
```text
|
||
src/desktop/
|
||
├── main.ts # Electron 主进程入口
|
||
├── runtime.ts # 桌面运行时端口 / 路径解析
|
||
└── runtime.test.ts # 桌面运行时测试
|
||
```
|
||
|
||
## 脚本与文档目录
|
||
|
||
```text
|
||
scripts/
|
||
├── dev/ # 本地开发脚本（run-server.ts / restart.bat / db-smoke.ts）
|
||
├── desktop/ # Electron 打包钩子（afterPack / afterSign）
|
||
└── codemods/ # 一次性仓库级重构脚本
|
||
```
|
||
|
||
```text
|
||
docs/
|
||
├── .vitepress/ # 文档站导航与主题配置
|
||
├── community/ # 社区贡献规范
|
||
├── engineering/ # 仓库级工程规则、harness 与漂移治理说明
|
||
├── public/ # 文档站公开静态资源
|
||
├── logos/ # 可编辑 Logo 源文件与草稿
|
||
├── screenshots/ # 文档截图
|
||
└── *.md # 面向用户和维护者的文档页面
|
||
```
|
||
|
||
## 放置规则
|
||
|
||
- 测试文件尽量与被测源码同目录，命名使用 `*.test.ts` 或 `*.test.tsx`。
|
||
- 运行时数据放 `data/`，临时排障文件放 `tmp/`，不要散落在仓库根目录。
|
||
- 桌面打包脚本统一放 `scripts/desktop/`，不要把一次性签名或打包命令写进根目录批处理。
|
||
- 文档站真正对外可访问的静态资源放 `docs/public/`；仍需继续编辑的素材保留在 `docs/logos/` 或 `docs/screenshots/`。
|