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

10 KiB

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。


4. 已确认的量化问题(本文档直接核实)

4.1 main.py 短命令别名:~190 行纯样板

main.py:1300–1490 定义了 38 个 imagestudio_short_* 方法,每个都是对同名长命令的 3 行纯转发:

@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。


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/。