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