astrbot_plugin_imagestudio/审计/01-总览与架构.md

202 行
10 KiB
Markdown

此文件含有模棱两可的 Unicode 字符

此文件含有可能会与其他字符混淆的 Unicode 字符。 如果您是想特意这样的,可以安全地忽略该警告。 使用 Escape 按钮显示他们。

# 01 · 总览与架构
> 审计对象:`AstrBot ImageStudio` 插件仓库
> 分支:`codex/character-profile-document-import` @ `8040a1b`
> 审计日期:2026-07-27
> 排除范围:`.tmp/`、`.tmp_pytest_*`、`node_modules/`、`__pycache__/`、构建产物
---
## 1. 规模统计
### 1.1 代码体量
| 层 | 文件数 | 行数 | 备注 |
|---|---:|---:|---|
| `main.py` | 1 | **2,580** | 插件入口 + 全部聊天命令 |
| `backend/services/` | 70 | 36,736(含 routes/dto) | 业务层 |
| `backend/routes/` | 35 | — | HTTP 路由层 |
| `backend/dto/` | 13 | — | 数据传输对象 |
| `database/` | 15 repo + models + 18 migration | 9,805 | 数据层 |
| `core/` | 23 | 2,494 | 横切基础设施 |
| `engines/` | 8 | 2,026 | 模型调用流程 |
| `adapters/` | 10 | 910 | 平台适配(AstrBot/OneBot11/WeChat/WebUI) |
| **后端小计** | **223** | **~64,100** | |
| `frontend/` | 85 | **39,254** | Vue3 + TS |
| `tests/` | 45 | 11,559 | pytest |
| **总计** | **~350** | **~115,000** | |
### 1.2 关键"巨石"文件
| 文件 | 行数 | 性质 |
|---|---:|---|
| `frontend/standalone-web/src/App.vue` | **22,563** | 单文件组件,全仓最大 |
| `backend/services/advanced_style_set_service.py` | **4,491** | 后端最大 service |
| `main.py` | 2,580 | 插件入口 |
| `backend/services/generation_service.py` | 2,432 | |
| `database/repositories/advanced_material_repository.py` | 2,123 | |
| `frontend/.../AdvancedMaterialImportPage.vue` | 2,024 | |
| `backend/services/advanced_material_service.py` | 1,856 | |
| `backend/services/workflow_round_service.py` | 1,596 | |
| `database/repositories/workflow_cross_review_repository.py` | 1,467 | |
| `database/repositories/workflow_round_repository.py` | 1,381 | |
**`App.vue` 内部构成**(22,563 行):
| 区段 | 行号 | 行数 | 占比 |
|---|---|---:|---:|
| `<script setup>` | 1–11,357 | 11,356 | 50.3% |
| `<template>` | 11,359–14,143 | 2,784 | 12.3% |
| `<style>` | 14,145–22,540 | **8,395** | **37.2%** |
script 段内含(**两种口径并列,后续报告一律以「声明式计数」为准**):
| 指标 | 字面量计数(`grep -o`) | 声明式计数(`= ref(` / `= computed(`,含 `ref<T>(`) |
|---|---:|---:|
| `ref` | 133 | **206** |
| `computed` | 135 | **203** |
另:`watch(` × 20、顶层函数定义 × 365、`endpoints.` 引用 × **183**(`grep -o "endpoints\." \| wc -l` 实测)。
> ⚠️ 本表两列的差异来自 `ref<Type>(...)` 这类带泛型参数的写法不含 `ref(` 子串。04 报告的 206/203 与本表第二列一致;若见到 133/135 请理解为字面量口径。
---
## 2. 架构分层
```
┌─────────────────────────────────────────────────────────────┐
│ 接入层 │
│ ┌──────────────┐ ┌──────────────┐ ┌───────────────────┐ │
│ │ main.py │ │ adapters/ │ │ frontend/ │ │
│ │ 聊天命令 ×77 │ │ AstrBot │ │ standalone-web │ │
│ │ (+38 短别名) │ │ OneBot11 │ │ plugin-page │ │
│ │ │ │ WeChat/WebUI │ │ shared/ │ │
│ └──────┬───────┘ └──────┬───────┘ └────────┬──────────┘ │
└─────────┼─────────────────┼───────────────────┼─────────────┘
│ │ │ HTTP
┌─────────▼─────────────────▼───────────────────▼─────────────┐
│ 路由层 backend/routes/ (35 文件) │
│ backend/route_registry.py — 166 条 RouteSpec │
│ PERMISSION_MATRIX: read/write/config/materials/ │
│ retry/public_token │
└─────────┬───────────────────────────────────────────────────┘
│ backend/dto/ (13) 出入参
┌─────────▼───────────────────────────────────────────────────┐
│ 服务层 backend/services/ (70 文件) │
│ workflow 簇 · material 簇 · generation 簇 · chat 簇 │
└─────────┬───────────────────────────────────────────────────┘
│
┌─────────▼───────────────────────────────────────────────────┐
│ 引擎层 engines/ — character_flow / fast_character_flow / │
│ quick_profile_flow / single_flow / review_flow / │
│ image_provider / vision_provider │
└─────────┬───────────────────────────────────────────────────┘
│
┌─────────▼───────────────────────────────────────────────────┐
│ 数据层 database/ — models.py · db_helper.py · │
│ repositories/ (15) · migrations/ (0001–0018) │
└─────────────────────────────────────────────────────────────┘
横切:core/ (23) — identity · security · storage · config_service ·
audit_service · event_bus · fsm · queue_manager ·
model_router · media_proxy · remote_fetch · secret_service
```
---
## 3. 依赖热点(扇入 Top10)
按 `from X import` 出现次数统计:
| 排名 | 模块 | 被引用次数 | 评价 |
|---:|---|---:|---|
| 1 | `core.identity` | 65 | 合理(ID 生成为纯工具) |
| 2 | `database.db_helper` | 56 | ⚠️ 数据访问入口,几乎人人依赖 |
| 3 | `backend.dto.common` | 54 | 合理 |
| 4 | `core.security` | 31 | 合理 |
| 5 | `backend.routes.common` | 31 | 合理 |
| 6 | `core.audit_service` | 30 | ⚠️ 审计横切散布在业务代码中 |
| 7 | `database.repositories.workflow_repository` | 19 | ⚠️ 跨层直接引用 |
| 8 | `database.repositories.profile_repository` | 16 | ⚠️ 同上 |
| 9 | `backend.routes.params` | 16 | 合理 |
| 10 | `backend.services.workflow_service` | 15 | ⚠️ service 间强耦合中心 |
> 详细耦合分析见 [03-耦合分析.md](03-耦合分析.md)。
---
## 4. 已确认的量化问题(本文档直接核实)
### 4.1 `main.py` 短命令别名:~190 行纯样板
`main.py:1300–1490` 定义了 38 个 `imagestudio_short_*` 方法,每个都是对同名长命令的 3 行纯转发:
```python
@imagestudio_short_command.command("状态")
async def imagestudio_short_status(self, event: AstrMessageEvent, workflow_id: str = ""):
async for result in self.imagestudio_status(event, workflow_id):
yield result
```
38 个 × ~4 行 ≈ **190 行**,零业务逻辑。可用一个命令表 + 工厂函数生成,削减约 175 行。
### 4.2 仓库卫生:2.6 GB 本地垃圾 + 38 MB 已入库产物
| 目录 | 体积 | 是否入库 | 说明 |
|---|---:|---|---|
| `.tmp/` | **2.1 GB** | 否(已 gitignore) | 8 份整仓快照 + 22 个发布包 + 60+ 临时脚本,共 **6,303 个文件** |
| `.tmp_pytest_*`(根目录 19 个) | **~515 MB** | 否(已 gitignore) | 单个 `.tmp_pytest_full_1022` 就 69 MB |
| `release/` | **38 MB** | **是(20 个 zip 已提交)** | ⚠️ 二进制发布包进版本库 |
| `web/assets/`、`pages/imagestudio/assets/` | — | **是(38 个文件)** | ⚠️ 前端构建产物进版本库 |
`.git` 目录已达 **51 MB**,主要由 `release/*.zip` 的历史版本贡献。
`.gitignore` 已正确忽略 `.tmp/` 与 `.tmp_pytest*/`,但**未忽略 `release/`**,且构建产物是有意提交的(插件分发需要)。
### 4.3 异常处理
- `except Exception` × **180**(后端)
- 裸 `except:` × 0 ✅
- `except ...: pass`(静默吞掉)× **22** ⚠️
- `async def` 仅 **93** 个 —— 64k 行后端中异步占比很低,需核查是否有同步阻塞调用混在 async 路径上
### 4.4 循环依赖信号
函数体内 `import`(规避循环导入的典型手法)共 **36 处**,集中在:
| 文件 | 次数 |
|---|---:|
| `main.py` | 16 |
| `database/db_helper.py` | 4 |
| `backend/services/model_provider_runtime.py` | 3 |
| `backend/routes/job_routes.py` | 3 |
| `backend/services/generation_service.py` | 2 |
---
## 5. 前后端契约面
- 后端注册端点:**166** 条(`backend/route_registry.py` 的 `RouteSpec`)
- 前端声明端点:**143** 条(`frontend/shared/api/endpoints.ts`)
- 前端类型定义:`frontend/shared/types/` 共 15+ 文件,与 `backend/dto/`(13 文件)**手工同步**,无代码生成
- `App.vue` 中 `endpoints.` 引用 **183** 次、覆盖 85 个不同端点,**未发现硬编码 `/api/` 字符串** ✅(全前端唯一的 `/api/` 字面量就是 `endpoints.ts:1` 的 `API_BASE` 定义本身)
> 端点差集、类型漂移逐字段比对见 [03-耦合分析.md](03-耦合分析.md)。
---
## 6. 技术栈
| 层 | 技术 |
|---|---|
| 后端 | Python 3、AstrBot Star 插件框架、SQL(迁移脚本手写 SQL) |
| 前端 | Vue 3.5(`<script setup>`)、TypeScript 5.7、Vite 6、Pinia 2.3、Vue Router 4.5 |
| 构建 | 双入口:`plugin-page`(嵌入 AstrBot WebUI)+ `standalone-web`(独立站) |
| 测试 | pytest(45 文件 / 11,559 行)、`node --test`(前端契约测试) |
> ⚠️ `frontend/package.json` 的 `devDependencies` 为空,`typescript`/`vite`/`vue-tsc`/`@vitejs/plugin-vue` 全部错放在 `dependencies`。
---
*本文档由人工核实数据写成;各维度详细发现见 [findings/](findings/)。*