# B1 · 前后端耦合 > 审计范围(实际读过的文件): > > **后端**:`main.py`、`backend/route_registry.py`、`backend/services/contract_service.py`、`backend/services/ui_service.py`、`backend/services/web_hosting_service.py`、`backend/services/workflow_progression_service.py`、`backend/services/workflow_round_service.py`、`backend/services/queue_service.py`、`backend/services/generation_service.py`、`backend/services/node_injection_template_service.py`、`backend/services/event_stream_service.py`、`backend/services/image_service.py`、`backend/services/advanced_style_set_service.py`、`backend/routes/{contract,api_discovery,node,node_material,round,profile,image,advanced_material,event,job}_routes.py`、`backend/dto/{common,workflow,workflow_round,profile,job,image,advanced_material}_dto.py`、`core/model_route_chain.py`、`core/config_service.py`、`core/security.py`、`core/event_bus.py`、`engines/character_flow.py`、`database/repositories/profile_repository.py`、`adapters/astrbot_adapter.py` > > **前端**:`frontend/shared/api/{endpoints,client,astrbot-page-bridge}.ts`、`frontend/shared/config/timeouts.ts`、`frontend/shared/utils/{presentation,storage-uri}.ts`、`frontend/shared/types/{api,bootstrap,profile,workflow,workflow-round,job,image,advanced-material}.ts`、`frontend/standalone-web/src/App.vue`、`frontend/standalone-web/src/features/workflow/{workflow-lock-state,workflow-model-route,workflow-node-catalog}.ts`、`frontend/standalone-web/src/features/workflow/WorkflowCandidatePool.vue`、`frontend/standalone-web/src/features/materials/advanced-material-state.ts`、`frontend/standalone-web/src/features/settings/{SystemManagementPanel.vue,model-route-chain.ts}`、`frontend/{plugin-page,standalone-web}/vite.config.ts`、`frontend/package.json`、`frontend/tests/*.test.mjs` > > **已按要求忽略**:`.tmp/`、`.tmp_pytest_*`、`release/`、`node_modules/`、`__pycache__/`、`web/assets/`、`pages/imagestudio/assets/`(仅在"构建产物入库"一节中作为 git 事实引用,未读其内容) ## 摘要 **URL 层面的耦合治理是这个仓库做得最好的部分**:`backend/route_registry.py` 是 166 条路由的唯一真相来源(`adapters/astrbot_adapter.py:44` 的 `resolve_route` 直接消费它),前端 143 个端点全部集中在 `frontend/shared/api/endpoints.ts`,逐条比对后**零个前端调用会 404**,也**几乎没有绕过 endpoints.ts 的硬编码 URL**(表 ③ 只有 vite base 一条)。这一维度可以给高分。 **问题全部集中在"语义契约"层**:URL 对上了,但 URL 背后的规则没对上。前端在 `App.vue`、`workflow-lock-state.ts`、`workflow-model-route.ts` 里重新实现了后端的顺序进度状态机、节点写锁规则、模型路由解析链、队列状态枚举和 retry 权限矩阵——每一处都与后端存在可举证的不一致(`sealed_at` 后端根本不产出;节点写锁少判两个条件;快速角色流的路由优先级后端是反的;retry 按钮漏判 `can_write`)。后端明明有 `character_gradual_progression().to_dict()`、`PERMISSION_MATRIX`、`ContractService` 这些"可下发的真相",却没有一条路由把它们送到前端,前端只能靠复刻。 `GET contract` 已提供完整的路由 + 权限 + 错误码自检数据,但前端唯一的消费点是 `SystemManagementPanel.vue:8` 的一个 JSON dump 诊断框,**没有任何自动化测试拿它做契约校验**——而这恰恰是最低成本、最高收益的修复方向(我实测 166 条路由的 handler 全部可导入,做成 CI 断言只需十几行)。 另外,`web/` 与 `pages/imagestudio/` 两份 1.1MB 的 vite dist 产物被提交进 git,80 次提交里每次改一行 UI 源码都会带上一批内容哈希文件名的增删,这是耦合与仓库卫生的双重问题。 --- ## 一、路由比对三张表 ### 表 ① 后端注册但前端从不调用(死接口) 比对方法:从 `backend/route_registry.py:55-342` 提取 166 条 `RouteSpec`,与 `endpoints.ts` 143 个键 + 全前端 `endpoints.` 引用做交叉。 | # | 方法 | 端点 | handler | 判定 | |---|---|---|---|---| | 1 | DELETE | `profiles/{profile_id}` | `profile_routes.delete_profile` | 死。UI「删除角色」实际调 `profileArchive`(`App.vue:6300`) | | 2 | POST | `profiles/{profile_id}/delete` | `profile_routes.delete_profile_via_post` | 死。`endpoints.profileDelete` 零引用 | | 3 | POST | `images/{image_id}/moderation-review` | `image_routes.review_moderated_image` | 死。见 P1-6 | | 4 | POST | `advanced-material-imports/{import_id}/cancel` | `advanced_material_routes.cancel_advanced_material_import` | 死。endpoints.ts 里连键都没有 | | 5 | POST | `nodes/{node_id}/mark-completed` | `node_routes.mark_node_completed` | 死。是 `nodes/{id}/complete` 的同 handler 别名 | | 6 | POST | `nodes/{node_id}/select-image` | `node_routes.select_node_image` | 死。前端只用 `images/{id}/select` | | 7 | POST | `prompts/expand` | `prompt_routes.expand_prompt` | 死。前端只用 `prompts/governance-preview` | | 8 | GET | `profile-cards/{card_id}` | `profile_card_routes.get_profile_card` | 死 | | 9 | DELETE | `profiles/{profile_id}/wardrobe/{wardrobe_item_id}` | `wardrobe_routes.delete_wardrobe_item` | 死。legacy 别名,前端只用 `/wardrobe/items/{id}` | | 10 | GET | `materials/analytics` | `material_routes.material_analytics` | 死 | | 11 | POST | `materials/renormalize-batch` | `material_routes.renormalize_materials_batch` | 死 | | 12 | POST | `materials/{material_id}/renormalize` | `material_routes.renormalize_material` | 死 | | 13 | GET | `integrations/logs` | `integration_routes.list_integration_logs` | 死。前端只用 `logs/integrations` | | 14 | POST | `api-discovery/probe-model` | `api_discovery_routes.probe_model` | 死。前端只用 `probe-provider` | > 说明:`GET media/fetch` 虽不在 endpoints.ts 中,但通过 `MediaService.sign_media()` 返回的签名 URL 被间接消费(`round_routes.py:196`、`image_routes.py:229`),**不算死接口**。 其中 #1/#2 与 `POST profiles/{id}/archive` 三条路由指向同一个函数体: ```python # backend/routes/profile_routes.py:101-114 def delete_profile_via_post(ctx, profile_id, payload=None, service=None) -> dict: return delete_profile(ctx, profile_id, service) def archive_profile(ctx, profile_id, service=None) -> dict: return delete_profile(ctx, profile_id, service) ``` ### 表 ② 前端调用但后端不存在(会 404) **空表。** 143 个 endpoints.ts 路径模板逐条与 `route_registry.ROUTES` 比对,全部命中,无一遗漏。这是本次审计中最值得肯定的一点。 ### 表 ③ 前端绕过 endpoints.ts 硬编码 URL | 位置 | 内容 | 判定 | |---|---|---| | `frontend/standalone-web/vite.config.ts:11` | `base: "/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/"` | 真实重复,见 P2-13 | | `frontend/shared/api/astrbot-page-bridge.ts:119-120` | `request("api:get" ...)` | 误报,是 postMessage 的 kind 常量,不是 HTTP 路径 | 除此之外全前端**没有任何**业务组件直接拼 API 路径:所有 `getJson/postJson/putJson/deleteJson` 的第一参数都来自 `endpoints.*`,`buildUrl` 是唯一的 URL 构造点(`client.ts:297-306`)。 --- ## 发现 ### [P1-严重] 前端复刻了后端的顺序进度状态机,且后端从不下发权威结果 - **位置**:`frontend/standalone-web/src/App.vue:10836-10861`,对应后端 `backend/services/workflow_progression_service.py:175-199` - **问题**:后端 `is_character_gradual_node_completed()` 是"节点是否已完成"的唯一权威判定,包含 status 白名单、node_type 特例、profile_card 别名归一、legacy 元数据兼容四层规则。前端逐条重写了这四层,连"legacy 兼容只对没有 sequential-v1 标记的工作流生效"这种极细的分支都手工复刻,并把版本号字面量抄进了 `App.vue:927`。 - **代码**: 后端: ```python # backend/services/workflow_progression_service.py:180-199 if node.status in PROGRESSION_COMPLETED_NODE_STATUSES: # {"selected","skipped"} return True if node.status == "completed" and ( node.node_type in {"planning", "reference_binding"} or canonical_gradual_node_key(node.node_key) == "profile_card" ): return True if allow_legacy_planning_metadata: if node.node_key == "prompt_plan": return "prompt_plan" in metadata and metadata.get("prompt_plan") is not None if node.node_key == "material_bind": return "material_bindings" in metadata and metadata.get("material_bindings") is not None return False ``` 前端(同一套规则,第二份实现): ```ts // frontend/standalone-web/src/App.vue:10843-10859 const status = normalizeStatus(backendNode.status) if (status === "selected" || status === "skipped") return true if (status === "completed" && (backendNode.node_type === "planning" || backendNode.node_type === "reference_binding" || canonicalCharacterWorkflowNodeKey(backendNode.node_key) === "profile_card")) return true const execution = selectedCharacterWorkflow.value?.metadata?.character_execution const legacyProgression = isRecord(execution) && execution.progression_version !== CHARACTER_WORKFLOW_PROGRESSION_VERSION if (!legacyProgression) return false if (backendNode.node_key === "prompt_plan") return backendNode.metadata?.prompt_plan != null if (backendNode.node_key === "material_bind") return backendNode.metadata?.material_bindings != null ``` ```ts // frontend/standalone-web/src/App.vue:927 const CHARACTER_WORKFLOW_PROGRESSION_VERSION = "character_gradual_sequential_v1" ``` 根因是后端从不下发进度: ```python # backend/routes/node_routes.py:52-63 —— 只返回裸节点数组,无 progression def action() -> list[dict[str, Any]]: require_authenticated(ctx) return [node.to_dict() for node in workflow_service.list_nodes(workflow_id)] ``` 全仓库 `progression.to_dict()` 只有一个调用点:`backend/services/character_workflow_service.py:339`(`execute-character` 的响应体),列表接口拿不到。 - **影响**:后端改一条进度规则(例如给 `style_lock` 加一个完成条件、或让 `skipped` 不再算完成),前端不会报错也不会失效,只会静默地在"下一步应该点哪个节点"上给出与服务端相反的答案:UI 显示节点可用 → 用户点击 → 后端 `ensure_character_gradual_node_access` 抛 `character_gradual_progression_locked`。反之 UI 灰掉一个后端允许的节点,用户彻底卡死且无提示。前端还有一份 `execution.progression_version` 的降级分支,等于把后端的向后兼容策略也复制了一份,双份都要维护。 - **修复建议**: 1. 在 `list_workflow_nodes` 返回体外层加 `progression` 字段(`CharacterGradualProgression.to_dict()` 已经现成,含 `current_node_id`/`completed_node_ids`/`all_completed`/`import_confirmed`): ```python def action() -> dict[str, Any]: require_authenticated(ctx) nodes = workflow_service.list_nodes(workflow_id) workflow = workflow_service.get_workflow(workflow_id) progression = character_gradual_progression(workflow, nodes) return { "items": [n.to_dict() for n in nodes], "progression": progression.to_dict() if progression else None, } ``` (返回结构变更需同步 `frontend/shared/types/workflow.ts` 并升 `contract_version`) 2. 删除 `App.vue:10836-10861` 与 `App.vue:927`,改为 `progression.completed_node_ids.includes(node.node_id)` / `node.node_id === progression.current_node_id`。 --- ### [P1-严重] 节点写锁规则前后端不一致,且前端判据里有一个后端从不产出的字段 - **位置**:`frontend/standalone-web/src/features/workflow/workflow-lock-state.ts:4-27`,对应后端 `backend/services/workflow_round_service.py:1145-1155` - **问题**:两条独立的"这个节点还能不能写"规则,条件集合不同;前端多判了一个不存在的字段,少判了两个真实条件。 - **代码**: 前端: ```ts // frontend/standalone-web/src/features/workflow/workflow-lock-state.ts:8-27 export function isWorkflowSealed(workflowStatus, metadata) { const status = normalizedStatus(workflowStatus) return ( status === "archived" || status === "cancelled" || Boolean(metadata?.final_archive_history_id || metadata?.sealed_at) // ← sealed_at ) } export function isWorkflowNodeWriteLocked(nodeStatus, workflowStatus, workflowMetadata) { return normalizedStatus(nodeStatus) === "selected" || isWorkflowSealed(workflowStatus, workflowMetadata) } ``` 后端: ```python # backend/services/workflow_round_service.py:1145-1155 if node.status == "selected" or node.selected_image_id or ( progression is not None and node.node_id in progression.completed_node_ids ): raise ApiError(ErrorCode.VALIDATION_FAILED, "confirmed workflow node is locked; create a branch before adding another round", {"node_id": node.node_id, "required_action": "create_branch"}) ``` `sealed_at` 在整个 Python 源码树(`main.py`/`backend/`/`core/`/`database/`/`engines/`/`adapters/`)**零匹配**——`grep -rn "sealed_at" --include=*.py` 返回空。它只存在于前端和前端测试里。 - **影响**:三处真实分歧。 1. `node.selected_image_id` 已设但 `status != "selected"` 时(例如 `adopt-image` 后 status 仍为 `completed`),前端认为可写并放行"再跑一轮",后端返回 `VALIDATION_FAILED / required_action: create_branch`,用户看到一个无法自恢复的报错。 2. 节点已进入 `progression.completed_node_ids`(通过 `skipped` 或 planning 节点 `completed`)时同理。 3. `metadata.sealed_at` 是一个永远为 `undefined` 的死判据,给读代码的人制造"存在这个封存机制"的错觉。而 `frontend/tests/workflow-model-route.test.mjs` 只断言 `final_archive_history_id` 分支,`sealed_at` 连测试都没覆盖。 - **修复建议**:把锁状态改为服务端下发而非客户端推导。最小改动是在 `WorkflowNode.to_dict()` 增加 `writable: bool` 与 `lock_reason: str | None`(`backend/services/workflow_node_material_service` 返回的 `WorkflowNodeMaterialBindingDetail` 已经有 `writable` + `lock` 结构,直接复用同一形状即可,见 `frontend/shared/types/workflow.ts:108-123`);前端 `workflow-lock-state.ts` 退化为读 `node.writable`。若暂不改协议,至少立刻删掉 `sealed_at`,并补上 `selected_image_id` 判据。 --- ### [P1-严重] 模型路由解析链在前端重实现,优先级与后端不一致(快速角色流方向相反) - **位置**:`frontend/standalone-web/src/features/workflow/workflow-model-route.ts:33-88` + `App.vue:2211-2245`,对应后端 `backend/services/generation_service.py:167-176`、`605-643`、`2022-2044` - **问题**:前端为了显示"当前生效模型 / 来源标签",把后端的整条路由回退链复刻了一遍——包括 `node_key → model_assignments` 键的映射表——并且直接读取原始配置文件结构 `config.model_assignments` / `config.generation.default_model`。三处不一致。 - **代码**: 后端普通节点(`generation_service.py:169-176`): ```python requested_model_route = str( payload.get("model_route") or node.model_route or assigned_route or profile_model_route or self.default_model_route or "image_low") ``` 后端**快速角色**节点(`generation_service.py:617-624`)—— 优先级反转,`assigned_route` 抢在 `payload.model_route` 之前: ```python if quick_character: route_candidate = str( assigned_route or payload.get("model_route") or profile_model_route or self.default_model_route or "image_low") ``` 前端(唯一一条链,多了 `round` 层,少了 `"image_low"` 兜底,没有 quick_character 分支): ```ts // frontend/standalone-web/src/features/workflow/workflow-model-route.ts:36-48 const candidates: Array<[WorkflowModelRouteSource, unknown]> = [ ["override", input.overrideRoute], ["round", input.roundRoute], ["node", input.nodeRoute], ["assignment", input.assignmentRoute], ["profile", input.profileRoute], ["system", input.systemRoute], ] for (const [source, value] of candidates) { const route = normalizeWorkflowModelRoute(value) if (route) return { route, source, explicitOverride: source === "override" } } return { route: "", source: "backend", explicitOverride: false } ``` 前端自带的第二份 `node_key → assignment` 映射(`workflow-model-route.ts:61-84`)与后端 `generation_service.py:2026-2038` 也不同步:后端有 `quick_avatar/quick_bust/quick_stand/quick_sheet → "quick_generation"`、`questionnaire`、`preview`,前端一个都没有;前端多了 `portrait/avatar/standing/three_view/character_sheet/halfbody/fullbody` 七个后端不认识的别名。 - **影响**: 1. **快速角色流的模型标签会直接说谎**:用户设了本次覆盖,UI 显示"本次覆盖 → route-X",后端实际按 `assigned_route` 出图。 2. 对 `quick_*` 节点,`workflowModelAssignmentKey("quick_avatar","generation")` 返回 `"quick_avatar"`(fallback 到 `canonical`),去 `model_assignments` 里查不到,UI 显示"角色默认/系统默认",后端实际用 `quick_generation` 分配的路由。 3. 前端读取的是**配置文件的原始结构**(`currentSettings.value.config.model_assignments`、`config.generation.default_model`,`App.vue:2218/2231-2233`),后端换个配置键名前端就静默失准。 - **修复建议**:新增 `GET nodes/{node_id}/effective-model-route`,或在 `nodeDependencyContext` 响应里加 `{ effective_model_route, source }`,由 `generation_service` 抽出一个纯函数 `resolve_model_route(node, workflow, profile, assignments, default)` 同时供生成路径与该端点调用。前端 `resolveWorkflowModelRoute` 只保留"用户 override 是否非空"的判断,其余全部读服务端字段。同时删除 `workflow-model-route.ts:61-84` 的别名/分配表。 --- ### [P1-严重] retry 类操作的前端权限门禁漏判 `can_write`,而后端要求两个权限 - **位置**:`frontend/standalone-web/src/App.vue:2786` + `3076` + `3139`,对应 `backend/route_registry.py:22-27` 与 `core/security.py:31-33` - **问题**:`route_registry` 已经把 retry 定义为**复合权限**并通过 `GET contract` 对外发布,前端却只判了其中一个。 - **代码**: 后端权限矩阵(`backend/route_registry.py:22-27`): ```python "retry": { "auth_required": True, "required_permission": "can_retry_tasks", "required_permissions": ["can_write", "can_retry_tasks"], "description": "task retry management (write + retry capabilities)", }, ``` ```python # core/security.py:31-33 def require_task_retry(ctx: RequestContext) -> None: require_write(ctx) # ← 先判 can_write require_permission(ctx, "can_retry_tasks") ``` 前端节点重试按钮(`App.vue:2786`、`3073-3077`): ```ts const canRetry = Boolean(permissions?.can_retry_tasks) ... state: canRetry ? "可重试" : "无权限", tone: canRetry ? "warn" : "neutral", enabled: Boolean(canRetry && !selectedNodeWriteLocked && !workflowNodeActionExecuting.value), ``` 同文件 `3373` 处的队列面板反而判对了(`const canManageQueue = canWrite && canRetry`),说明这是遗漏而非有意设计。 - **影响**:持有 `can_retry_tasks` 但无 `can_write` 的账号,在工作流面板看到"可重试"的可用按钮(`portrait-retry` 卡片与 `3139` 处的同类卡片),点击后 `nodes/{id}/retry` 与 `nodes/{id}/generate` 一律被 `require_write` 拒为 `FORBIDDEN`。同一份权限模型在同一个文件里出现两种实现,说明这类漏判还会再犯。 - **修复建议**:不要在前端逐个手写权限组合。`GET contract` 返回的 `routes[].required_permissions` 已经是完整数组,在 bootstrap 之后拉一次 contract,构造 `canCall(endpointKey)` 工具函数,所有按钮的 `enabled` 统一走它: ```ts const contractRoutes = new Map(contract.routes.map(r => [`${r.method} ${r.endpoint}`, r.required_permissions])) function canCall(method: string, endpoint: string) { return (contractRoutes.get(`${method} ${endpoint}`) ?? []).every(p => permissions?.[p]) } ``` --- ### [P1-严重] 编译产物 `web/` 与 `pages/imagestudio/` 被提交进 git,且是两份重复的 dist - **位置**:`frontend/standalone-web/vite.config.ts:12-15`、`frontend/plugin-page/vite.config.ts:12-15`、`backend/services/web_hosting_service.py:14-17`、`.gitignore` - **问题**:两个 vite 构建把产物直接写进受版本控制的目录,且 `emptyOutDir: true`,每次构建都会整批删除并重建内容哈希文件名。`.gitignore` 忽略了 `frontend/**/dist/`,却没有忽略这两个实际的输出目录。 - **代码**: ```ts // frontend/standalone-web/vite.config.ts:9-15 base: "/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/", build: { outDir: resolve(rootDir, "../../web"), emptyOutDir: true }, ``` ```ts // frontend/plugin-page/vite.config.ts:11-15 base: "./", build: { outDir: resolve(rootDir, "../../pages/imagestudio"), emptyOutDir: true }, ``` ```python # backend/services/web_hosting_service.py:14-15 PLUGIN_PAGE_DIR = REPO_ROOT / "pages" / "imagestudio" STANDALONE_WEB_DIR = REPO_ROOT / "web" ``` 两份 dist 内容同源——`frontend/plugin-page/src/App.vue` 全文只有: ```vue ``` git 事实:`git ls-files web/ pages/` = 38 个文件,`du -sh` 各 1.1MB;`git log --oneline -- web/assets | wc -l` = **80 次提交**;最近 15 次改 `frontend/standalone-web/src/App.vue` 的提交**每一次**都同时改了 `web/assets` 与 `pages/imagestudio/assets`。 - **影响**: 1. **每个 UI 改动的 diff 被 2MB 二进制级噪音淹没**,code review 无法看清真实变更;`git status` 首屏就是二十多行 `D web/assets/...`。 2. **产物与源码可能不同步**:目前没有任何 CI 校验 `web/` 是当前 `frontend/` 的构建结果。一个只改源码忘记 build 的提交,会让线上跑的仍是旧 JS,而 `WebHostingService.manifest()` 只检查 `index.html` 是否存在(`web_hosting_service.py:33/38`),报告 `built: true`,无法发现版本错位。 3. 内容哈希文件名 + `emptyOutDir` 让每次构建产生全新路径,git 历史里累积了大量永不复用的 blob,仓库体积单向膨胀。 4. 两份 dist 意味着**任何 UI 修复都必须记得跑两次构建**,漏一次就出现"插件页正常、独立页是旧版"的诡异现象——git 历史里 `fix: recover material library after stale asset token`、`fix: load material library page without expiring asset chunk` 两条修复正是这一类症状。 - **修复建议**: 1. `.gitignore` 增加 `/web/` 与 `/pages/imagestudio/`(保留 `.gitkeep`),`git rm -r --cached web pages/imagestudio`。 2. 发布流程改为 CI 构建 + 打包进 release artifact;仓库只保留源码。若插件分发形态要求产物随包,则用一次性的 release 分支/tag 承载,不进主干历史。 3. 若因 AstrBot 插件安装方式**必须**保留产物在主干,则退而求其次:加一条 CI 检查 `npm run build && git diff --exit-code web pages`,保证产物永远与源码一致;并把两个 vite 配置合并为一次构建两个 base(或让 plugin-page 直接复用 standalone 产物),消除"两份 dist"。 4. `WebHostingService.manifest()` 增加一个来自构建时注入的 `build_hash`,与 `metadata.yaml` 版本比对,让版本错位可被观测。 --- ### [P1-严重] `events/stream` 无游标:后端把 SSE 载荷塞进 JSON,前端 5 秒轮询 20 条,事件会静默丢失 - **位置**:`backend/services/event_stream_service.py:22-32`、`backend/routes/event_routes.py:22-28`、`frontend/standalone-web/src/App.vue:4561-4608` - **问题**:后端把事件流做成"返回最近 N 条 + 一段预渲染 SSE 文本"的普通 JSON 接口,没有 `after_event_id` / `since` 参数;前端只能轮询固定窗口,靠在返回数组里查找上次的 `event_id` 来切出增量。窗口一旦被冲掉,增量计算就退化。 - **代码**: 后端(无游标,且 `body`/`content_type` 是给 SSE 用的但走的是 JSON 通道): ```python # backend/services/event_stream_service.py:22-32 def recent_events(self, *, event_type: str | None = None, limit: int = 50) -> dict[str, Any]: events = self.event_bus.history(event_type) selected = events[-_limit(limit):] webhook_events = [_event_to_webhook(event) for event in selected] return { "content_type": "text/event-stream", "events": [event.to_dict() for event in webhook_events], "body": "".join(to_sse(event) for event in webhook_events), "count": len(webhook_events), } ``` 前端: ```ts // frontend/standalone-web/src/App.vue:4566-4577, 4608 const stream = await getJson<{ events: Array<{ event_id?: string; ... }> }>( endpoints.eventStream, { limit: 20 }) const newest = stream.events.at(-1)?.event_id ?? "" if (!newest || newest === lastEventStreamId) return const previousIndex = hadPrevious ? stream.events.findIndex((event) => event.event_id === lastEventStreamId) : -1 const freshEvents = hadPrevious ? stream.events.slice(previousIndex >= 0 ? previousIndex + 1 : -1) // ← 找不到时只取最后 1 条 : [] ... eventStreamTimer = window.setInterval(poll, 5000) ``` - **影响**:一轮 4~8 张候选图的生成会在几秒内产生远超 20 条 `generation.*` / `workflow.*` 事件。此时 `findIndex` 返回 `-1`,`slice(-1)` 只留下**最后一条**事件,`eventTypes` 只有一个元素,于是 `generationChanged` / `workflowChanged` 的判定基于 1/20 的样本——`loadJobs()` / `loadDashboard()` / `loadWorkflowRoundDetail()` 该刷的不刷,UI 停在旧状态直到用户手动刷新。这正是"生成完了界面不动"类问题的结构性来源。同时 `body` 与 `content_type` 两个字段每次都白白序列化传输且被前端丢弃。 - **修复建议**: 1. `EventStreamService.recent_events` 增加 `after_event_id: str | None`,在 `_history` 中定位后返回其后全部事件(配合 `limit` 上限 200),并返回 `truncated: bool` 告知客户端是否发生了窗口溢出。 2. 前端改传 `{ after_event_id: lastEventStreamId, limit: 200 }`;收到 `truncated: true` 时退化为一次全量刷新(`loadJobs + loadDashboard + 当前视图`),而不是静默少刷。 3. `content_type` / `body` 两个字段要么删掉(JSON 通道用不上),要么单独开一条真正的 SSE 路由;现在这样两边都不是。 --- ### [P2-中等] 队列状态枚举在前后端共 4 处独立硬编码 - **位置**:`backend/services/queue_service.py:31-34` vs `frontend/standalone-web/src/App.vue:3285`、`3293`、`frontend/shared/utils/presentation.ts:5` - **问题**:后端已经把任务状态分类抽成了具名常量,前端把这些集合的字面量抄了三份,还多出一个后端没有的分类。 - **代码**: 后端唯一真相: ```python # backend/services/queue_service.py:31-34 RETRYABLE_TASK_STATUSES = {"failed", "dead_letter", "cancelled"} FAILED_TASK_STATUSES = ("failed", "dead_letter", "cancelled") COMPLETED_TASK_STATUSES = ("completed", "succeeded", "superseded") DELETABLE_TASK_STATUSES = frozenset((*FAILED_TASK_STATUSES, *COMPLETED_TASK_STATUSES)) ``` 前端三份拷贝: ```ts // App.vue:3284-3286 const failedJobs = computed(() => queueItems.value.filter((job) => ["failed", "dead_letter", "cancelled"].includes(normalizeStatus(job.status)))) // App.vue:3292-3295 const completedQueueJobs = computed(() => queueItems.value.filter((job) => ["completed", "succeeded", "superseded"].includes(normalizeStatus(job.status)))) const terminalQueueJobs = computed(() => [...failedJobs.value, ...completedQueueJobs.value]) ``` ```ts // frontend/shared/utils/presentation.ts:5 —— 第四份,且集合与后端任何一个常量都不完全相等 const TERMINAL_JOB_STATUSES = new Set(["completed", "succeeded", "failed", "cancelled", "dead_letter", "superseded"]) ``` 另有 `App.vue:3628` 第五次内联同一个 `["failed","dead_letter","cancelled"]`。 - **影响**:`TASK_STATUSES`(`queue_service.py:18-29`)新增一个终态(例如 `expired`)时,后端会正确把它算进 `DELETABLE`,而前端四处判定全部漏掉:任务永远停在"运行中"分组、`waitTime()` 里 `terminal` 为 false 导致耗时读数无限增长、"清理终态任务"按钮的 `enabled` 计数与后端实际清理数量对不上。 - **修复建议**:把这四个集合加进 `GET ui/bootstrap` 的返回体(`UiService.get_bootstrap` 已经在下发 `permissions` 和 `feature_flags`,加 `task_statuses: {retryable, failed, completed, terminal}` 是同一性质的元数据),前端建一个 `taskStatusSets.ts` 从 bootstrap 初始化;或退一步,至少把四份合并成 `frontend/shared/config/task-status.ts` 一份,并加一条像 `task-timeout-consistency.test.mjs` 那样的正则测试断言它与 `queue_service.py` 的字面量一致。 --- ### [P2-中等] `images/{id}/moderation-review` + `include_restricted` 是一条完整但前端零对接的功能链 - **位置**:`backend/routes/image_routes.py:41-49`、`68-73`、`90-91`、`145-160`;前端零引用 - **问题**:后端为"内容审核隔离图片"实现了完整闭环——列表过滤、管理员可见开关、隐藏计数、管理员复核端点——前端一个都没接。 - **代码**: ```python # backend/routes/image_routes.py:41-49 include_restricted = as_bool(params.get("include_restricted"), default=False, non_string_truthiness=True) if include_restricted and not (ctx.has_permission("can_manage_materials") or ctx.has_permission("*")): include_restricted = False payload = _serialize_image_list(result, signer) if not include_restricted: visible = [item for item in payload["items"] if not _is_restricted_image(item)] payload["restricted_hidden"] = len(payload["items"]) - len(visible) payload["items"] = visible payload["total"] = max(len(visible), int(payload.get("total") or 0) - payload["restricted_hidden"]) ``` ```python # backend/services/image_service.py:135-143 —— approve/reject 会真实改写可见性 update = {"metadata": {**metadata, "quarantined": False if action == "approve" else True, "gallery_visibility": "normal" if action == "approve" else "restricted", "moderation_admin_review": review}, **({"is_archived": True} if action == "reject" else {})} ``` 前端验证:`grep -rn "include_restricted\|restricted_hidden\|quarantined\|gallery_visibility" frontend/` 全树仅命中 `App.vue:4526` 的 `include_archived: true`,与本功能无关。`frontend/shared/types/image.ts:28-33` 的 `ImageListResult` 也没有 `restricted_hidden` 字段。 - **影响**:`generation_service.py:491` / `968` 会把审核不通过的图打上 `gallery_visibility: "restricted"`。这些图对所有人(含管理员)永久不可见、不可复核、不可解除——UI 既不显示"有 N 张被隐藏",也没有任何入口调用 approve。用户视角是"生成成功了但图库里没有",没有任何解释。这是一条**后端做完、前端未接、因此在生产中表现为数据丢失**的功能链。 - **修复建议**:图库页加"显示受限图片"开关(仅 `can_manage_materials` 可见)→ 传 `include_restricted=true`;列表底部读 `restricted_hidden` 显示"另有 N 张待复核";受限图详情弹窗加 approve/reject,调 `endpoints` 新增的 `imageModerationReview(imageId)`。同时把 `restricted_hidden?: number` 补进 `ImageListResult`。 --- ### [P2-中等] `AdvancedMaterialImportStatus` 双向漂移,且 `Union | string` 写法让所有状态联合类型在编译期失效 - **位置**:`frontend/shared/types/advanced-material.ts:1-49` vs `backend/services/advanced_style_set_service.py:384/527/539/787/1366` 等 - **问题**:两个方向都对不上,而且类型声明方式使 TS 完全无法发现这类漂移。 - **代码**: 后端实际写入 import.status 的取值(扫描 `update_import(..., {"status": ...})` 得到): ``` adjustment_required, cancelled, ready_for_validation, recognition_failed, recognition_queued, recognizing_style_sources, style_consensus_failed, style_consensus_queued, style_consensus_running, style_source_recognition_queued, style_source_review_required, validating, validation_failed, validation_queued ``` 前端联合类型(`advanced-material.ts:1-18`): ```ts export type AdvancedMaterialImportStatus = | "recognition_queued" | "pending_recognition" | "recognizing" | "pending_validation" | "ready_for_validation" | "validation_queued" | "validating" | "validation_failed" | "recognition_failed" | "pending_review" | "awaiting_review" | "adjustment_required" | "accepted" | "rejected" | "failed" | "cancelled" | "archived" ``` **前端缺 6 个**:`recognizing_style_sources`、`style_consensus_failed`、`style_consensus_queued`、`style_consensus_running`、`style_source_recognition_queued`、`style_source_review_required`(整个 style-set 流程的状态一个没有)。 **前端多 2 个后端根本不产出的**:`pending_validation`、`pending_review`(`grep -rn '"pending_validation"' --include=*.py backend/ database/` → 0 命中)。 而声明处一律写成: ```ts // advanced-material.ts:168 status: AdvancedMaterialImportStatus | string ``` TypeScript 会把 `"a" | "b" | string` 折叠成 `string`,**联合类型完全不产生任何类型检查**。同样的写法出现在 `AdvancedStyleSource.status`、`AdvancedStyleValidationCase.status`、`AdvancedMaterial.status`、`workflow-round.ts:73/112`(`round_kind`、`preference_status`)等十余处。 - **影响**:运行时目前靠 `advanced-material-state.ts:24-67` 的 switch 兜住(它确实手工覆盖了 style_* 状态,甚至还处理了一个后端只在两处出现的 `validation_partial_failed`),但类型层面完全没有护栏:后端加一个新状态,TS 编译通过、review 看不出、只有用户看到"未知状态"文案(`advanced-material-state.ts:65`)才暴露。`pending_validation`/`pending_review` 这两个幽灵值说明漂移已经发生过至少一次且无人察觉。 - **修复建议**: 1. 把 `| string` 去掉,改为 `status: AdvancedMaterialImportStatus`,让联合类型真正生效;确实需要容忍未知值的地方用显式 `as string` 或在解析边界处收窄。 2. 状态集合从后端生成而非手抄:把各 `*_STATUSES` 常量集中到一个 Python 模块,加一个生成脚本产出 `frontend/shared/types/generated-enums.ts`,CI 校验 `git diff --exit-code`。 --- ### [P2-中等] `backend/dto/advanced_material_dto.py` 已不是进阶素材接口的响应真相来源 - **位置**:`backend/dto/advanced_material_dto.py` vs `backend/services/advanced_style_set_service.py` vs `frontend/shared/types/advanced-material.ts` - **问题**:TS 类型里大量字段在 DTO 的 `to_dict()` 中不存在,而路由层的序列化只补了 `*_url`。 - **代码**: 路由层只做签名 URL 增强,不加业务字段: ```python # backend/routes/advanced_material_routes.py:387-392 def _serialize_style_source(payload: dict[str, Any]) -> dict[str, Any]: return {**payload, "source_image_url": _signed_url(payload.get("source_image_uri")), "source_thumbnail_url": _signed_url(payload.get("source_thumbnail_uri"))} ``` 但 TS 声明了这些 DTO 里没有的字段(`advanced-material.ts:58-86`、`125-158`、`160-187`): | TS 接口 | DTO 无此字段 | 实际来源 | |---|---|---| | `AdvancedStyleSource` | `excluded`、`filename`、`image_uri`、`thumbnail_uri`、`retry_count` | `advanced_style_set_service.py:409/414` 手工构造的 metadata / view dict | | `AdvancedStyleValidationCase` | `scenario`、`title`、`style_prompt`、`style_scores`、`rendering_layers`、`content_novelty` | `advanced_style_set_service.py:2330/2354/3345/3422` | | `AdvancedMaterialImport` | `task_id`、`workflow_kind`、`sources`、`consensus`、`validation_cases` | `advanced_style_set_service.py:389/1152` | | `AdvancedStyleConsensus` | 整个接口无对应 DTO(`AdvancedStyleConsensusRun` 字段名完全不同:`consensus_style`/`version_id`/`variable_style_features` 都不在 DTO 里) | `advanced_style_set_service.py:1723` | 反向也有:DTO 输出但 TS 未声明的 `idempotency_key`(import)、`recognition_model_route`/`provider_id`/`provider_model`(style source)、`width`/`height`/`completed_at`(validation case)。 - **影响**:`backend/dto/` 这一层对进阶素材已经名存实亡——响应形状实际由散落在 3600 行 `advanced_style_set_service.py` 各处的 dict 字面量决定。想知道接口返回什么,只能全文搜索;改动时没有任何单点可以对照。这也是前面状态枚举漂移的同一个根因。 - **修复建议**:为 style-set 流程补 DTO(`AdvancedStyleSourceView`、`AdvancedStyleValidationCaseView`、`AdvancedStyleConsensusView`),让 service 返回 DTO 实例而非裸 dict,路由层只调 `to_dict()` + 加签名 URL。这样"接口返回什么"重新有唯一定义点,也让 `contract` 有机会未来发布响应 schema。 --- ### [P2-中等] `route-chain:` 线格式编解码器被逐字移植到 TS,无任何跨语言一致性测试 - **位置**:`core/model_route_chain.py:52-66` vs `frontend/standalone-web/src/features/settings/model-route-chain.ts:27-39` - **问题**:这不是"逻辑重复",而是**同一个序列化格式的两份独立实现**——前端写出的字符串要被后端解析,任何一边的细节改动都会破坏另一边,而目前正确性完全依赖手工对齐 `json.dumps` 与 `JSON.stringify` 的输出细节。 - **代码**: ```python # core/model_route_chain.py:61-66 return ROUTE_CHAIN_PREFIX + json.dumps( {"plugin": plugin_route, "astrbot": astrbot_route}, ensure_ascii=False, separators=(",", ":"), sort_keys=True) ``` ```ts // frontend/standalone-web/src/features/settings/model-route-chain.ts:33 return `${MODEL_ROUTE_CHAIN_PREFIX}${JSON.stringify({ astrbot, plugin })}` ``` 目前能对上,靠的是三个巧合同时成立:Python `sort_keys=True` 产出 `astrbot` 在前 ≡ TS 对象字面量恰好写成 `{ astrbot, plugin }` 的插入顺序;`separators=(",", ":")` ≡ `JSON.stringify` 默认无空格;`ensure_ascii=False` ≡ `JSON.stringify` 默认不转义非 ASCII。 - **影响**:把 TS 那行写成 `JSON.stringify({ plugin, astrbot })`(更符合"plugin 优先"的语义直觉)就会产出 `{"plugin":...,"astrbot":...}`。Python 端 `parse_model_route_chain` 用 `json.loads` 读 dict,解析仍然成功——所以**不会立刻报错**,但两端产出的字符串不再逐字节相等,任何做字符串比较的地方(配置 diff、快照对比、`settings/diff`)都会把"没变的配置"报成"变了"。现有测试 `tests/test_model_route_chain.py` 只验 Python 内部往返,`frontend/tests/workflow-model-route.test.mjs` 根本没测这个模块,**没有一条测试断言两语言的编码结果相同**。 - **修复建议**:加一条黄金样本测试固定线格式。Python 侧断言 `encode_model_route_chain("p","astrbot:a") == 'route-chain:{"astrbot":"astrbot:a","plugin":"p"}'`,TS 侧 `frontend/tests/` 里用同一字符串断言 `encodeModelRouteChain({plugin:"p",astrbot:"astrbot:a"})`,并加反向 `parse` 用例。更彻底的做法是别让前端编码:新增 `POST settings/encode-model-route` 或让 settings 保存接口接受 `{plugin, astrbot}` 结构体、由后端编码。 --- ### [P2-中等] `character_flow` 节点目录与 legacy 别名表在前端重复,且两份前端拷贝之间也不一致 - **位置**:`engines/character_flow.py:15-20` vs `frontend/standalone-web/src/features/workflow/workflow-node-catalog.ts:23-32` vs `frontend/standalone-web/src/features/workflow/workflow-model-route.ts:61-74` - **问题**:同一张"legacy node_key → canonical node_key"映射表存在三份,其中两份在同一个前端目录下且映射结果不同。 - **代码**: ```python # engines/character_flow.py:15-20 LEGACY_CHARACTER_GRADUAL_NODE_KEYS: dict[str, str] = { "half_body": "upper_body", "expression_sheet": "turnaround", # ← turnaround "pose_sheet": "design_sheet", "final_pack": "profile_card", } ``` ```ts // workflow-node-catalog.ts:23-28 —— 与后端一致 export const LEGACY_CHARACTER_WORKFLOW_NODE_KEYS = { half_body: "upper_body", expression_sheet: "turnaround", pose_sheet: "design_sheet", final_pack: "profile_card", } ``` ```ts // workflow-model-route.ts:61-74 —— 同一前端内的第三份,expression_sheet 映射不同 const canonicalAliases: Record = { portrait: "headshot", avatar: "headshot", half_body: "upper_body", halfbody: "upper_body", standing: "full_body", fullbody: "full_body", three_view: "turnaround", three_views: "turnaround", character_sheet: "design_sheet", expression_sheet: "design_sheet", // ← design_sheet,与另两处冲突 pose_sheet: "design_sheet", hires_fix: "style_lock", } ``` 另外 11 个节点的 `node_key` 与展示文案在 `engines/character_flow.py:22-115`(`CHARACTER_GRADUAL_STEPS`,含 title/description/sort_order/stage_code)和 `workflow-node-catalog.ts:64-153`(`CHARACTER_WORKFLOW_PREVIEW_NODE_SPECS`,含 title/detail/badge/phase)各存一份,两边的中文标题也不同(后端"拆解人设/预选素材"vs 前端"LLM 拆解设定/参考素材绑定")。 - **影响**:`expression_sheet` 的冲突目前不产生可见 bug(`turnaround` 和 `design_sheet` 恰好都映射到 `sheet_generation`),但这是巧合而非设计。真正的风险是:`engines/character_flow.py` 加一个新节点或改一个别名,前端两份表都不会更新,`workflowUiNodeIdForNodeKey` 返回 `undefined`,该节点在工作流面板直接不显示——用户看到的步骤列表比后端实际创建的节点少一个。 - **修复建议**:`ui/bootstrap` 或新增 `GET workflows/node-catalog` 下发 `gradual_node_templates()` + `LEGACY_CHARACTER_GRADUAL_NODE_KEYS`(后端已有 `gradual_node_templates()`,`character_flow.py:131-145`,几乎可以直接返回)。前端 `workflow-node-catalog.ts` 只保留纯展示增强(badge/phase/detail 这些后端没有的字段),键与别名从接口取。同时删除 `workflow-model-route.ts:61-74` 那张私有别名表,改用 `canonicalCharacterWorkflowNodeKey`。 --- ### [P2-中等] `LONG_TASK_ENDPOINT` 正则在前端重复两份,并把"哪些后端端点慢"编码进了客户端 - **位置**:`frontend/shared/api/client.ts:14` 与 `frontend/shared/api/astrbot-page-bridge.ts:6`(逐字符相同) - **问题**:一条 18 个分支的正则,枚举了所有"耗时长"的后端端点段,在两个文件里各存一份;而它声称对齐的"后端 900 秒预算"在后端并不存在。 - **代码**: ```ts // client.ts:14 与 astrbot-page-bridge.ts:6 —— 完全相同的两份 const LONG_TASK_ENDPOINT = /(?:^|\/)(?:generate|retry|review|execute-character|expand|governance-preview|probe-provider|probe-model|recognize|re-recognize|renormalize|renormalize-batch|import-pack|migrate|restore)(?:\/|$)/ ``` ```ts // frontend/shared/config/timeouts.ts export const LONG_TASK_TIMEOUT_SECONDS = 900 ``` 而 `grep -rn "\b900\b" --include=*.py`(排除 tests/release/.tmp)在后端只有一处命中,且与生成任务无关: ```python # backend/services/advanced_style_set_service.py:57 STYLE_VALIDATION_TIMEOUT_SECONDS = 900 ``` 生成任务的真实预算是 180 秒(`generation_service.py:2308` `request.get("timeout_seconds") or settings.get("timeout_seconds") or 180`;`config.yaml:25/42` `timeout_seconds: 180`)。 号称守护一致性的测试其实只读前端文件: ```js // frontend/tests/task-timeout-consistency.test.mjs:11-25 test("uses the backend 900 second task budget throughout the plugin bridge UI", async () => { const [timeouts, client, bridge, app] = await Promise.all([...]) // ← 四个文件全在 frontend/ assert.match(timeouts, /LONG_TASK_TIMEOUT_SECONDS = 900/) ... }) ``` - **影响**: 1. 正则里 `probe-model`、`renormalize`、`renormalize-batch`、`import-pack` 对应的端点前端**根本不调用**(见表 ①),说明这份列表已经和实际调用面脱节,无人维护。 2. 测试名字断言"后端 900 秒预算",但测试没有读过任何后端文件——它固化的是一个虚构的契约。后端把 `timeout_seconds` 从 180 调到 600,前端不会知道;反过来前端这个 900 也没有任何后端依据。 3. 新增一个慢端点(例如 `advanced-material-imports/{id}/style-consensus`,实际走 900 秒的样式校验)不在正则里,客户端 30 秒就超时报错,而后端任务其实还在跑。 - **修复建议**:正则提到 `frontend/shared/config/timeouts.ts` 一份,两个 transport 共同 import。更好的做法是让后端在 `ui/bootstrap` 下发 `{ long_task_endpoint_patterns: [...], long_task_timeout_seconds: N }`,N 取 `config.generation.provider.timeout_seconds` 的上界;测试改为读 `config.yaml` / `generation_service.py` 与前端常量做真实比对。 --- ### [P2-中等] `contract` 端点只被用作诊断 JSON dump,没有任何自动化契约测试消费它 - **位置**:`backend/services/contract_service.py:12-30`、`backend/routes/contract_routes.py:13-23`、唯一前端消费点 `frontend/standalone-web/src/features/settings/SystemManagementPanel.vue:8` - **问题**:契约自检机制**已经存在且数据完备**,但没有被任何一方真正用起来。 - **代码**: ```python # backend/services/contract_service.py:13-30 —— 数据已经很全 return { "contract_version": "3.0", "api_base": API_BASE, "routes": route_manifest(), # 166 条:method/endpoint/handler/permission/required_permissions "permissions": permission_matrix(), "error_codes": [code.value for code in ErrorCode], "response_shape": {...}, } ``` ```ts // SystemManagementPanel.vue:8 —— 唯一消费点,拉下来直接 JSON.stringify 塞进
  else if(props.mode==="diagnostics"){
    const [contract,actions,manifest]=await Promise.all([
      getJson(endpoints.contract),getJson(endpoints.uiActions),getJson(endpoints.webManifest)]);
    result.value={contract,actions,manifest}}
  ```
  `route_registry.py` 已经写好了两个自检函数,但 `grep -rln "route_manifest\|route_registry\|ROUTES" tests/` 只命中 `test_profile_card_finalize.py` 和 `test_workflow_generation_cross_review.py`(都是间接 import),**没有任何测试调用 `assert_unique_routes()` / `assert_known_permissions()`**:
  ```python
  # backend/route_registry.py:365-377  —— 现成的自检,无人调用
  def assert_unique_routes() -> None: ...
  def assert_known_permissions() -> None: ...
  ```
- **影响**:契约漂移目前没有任何自动化拦截。本报告里的表 ①(14 条死接口)、P1-4(权限漏判)、P2-9(状态枚举漂移)全部是人工比对才发现的,任何一条都本可以由 CI 自动发现。
- **修复建议**:**这是本维度投入产出比最高的一条,建议优先做**。三条测试即可覆盖大部分问题:

  1. **后端自检**(`tests/test_route_contract.py`,我已实测 166 条 handler 全部可导入,此测试当前会通过):
     ```python
     import importlib
     from backend.route_registry import ROUTES, assert_unique_routes, assert_known_permissions

     def test_route_manifest_is_wellformed():
         assert_unique_routes()
         assert_known_permissions()
         for route in ROUTES:
             mod, _, fn = route.handler.rpartition(".")
             assert hasattr(importlib.import_module(mod), fn), route.handler
     ```

  2. **跨语言路由比对**(`frontend/tests/api-contract.test.mjs`):解析 `backend/route_registry.py` 的 `RouteSpec("METHOD", "endpoint"` 与 `endpoints.ts` 的模板字符串(把 `${...}` 与 `{...}` 都归一为 `{}`),断言 endpoints.ts ⊆ ROUTES(阻止表 ② 出现),并把当前 14 条死接口写成显式 allowlist,新增未使用路由时测试失败——逼迫作者要么接上要么删掉。

  3. **权限门禁比对**:前端所有按钮的 `enabled` 统一走 P1-4 建议的 `canCall(method, endpoint)`,该函数的输入直接来自 contract 的 `required_permissions`,从此权限矩阵不需要在前端复写。

  另外 `contract` 目前只发布路由与权限,不发布**请求/响应 schema**。若把 `backend/dto/*.py` 的 `to_dict()` 字段清单也纳入(DTO 都是 frozen dataclass,用 `dataclasses.fields()` 自动生成即可),就能把 P2-9、P2-10、P3-16 这类字段级漂移一并自动化——但前提是先修 P2-10(让 DTO 重新成为真相来源)。

---

### [P2-中等] `API_BASE` 硬编码三份,而 `bootstrap.api_base` 下发了却没人用

- **位置**:`backend/services/ui_service.py:10`、`frontend/shared/api/endpoints.ts:1`、`frontend/standalone-web/vite.config.ts:11`
- **问题**:同一个字符串三处独立字面量;后端已经通过 bootstrap 把它下发给前端,前端却只拿它拼提示文案。
- **代码**:
  ```python
  # backend/services/ui_service.py:10(被 contract_service / astrbot_adapter 复用,后端侧是单点)
  API_BASE = "/api/v1/plugins/extensions/astrbot_plugin_imagestudio"
  ```
  ```ts
  // frontend/shared/api/endpoints.ts:1
  export const API_BASE = "/api/v1/plugins/extensions/astrbot_plugin_imagestudio"
  ```
  ```ts
  // frontend/standalone-web/vite.config.ts:11
  base: "/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/",
  ```
  前端拿到 `bootstrap.api_base` 之后的唯一用途:
  ```ts
  // frontend/standalone-web/src/App.vue:4330
  : `已通过同源 API ${loadedBootstrap.api_base} 调用后端,写入动作会进入工作流并落库。`,
  ```
  实际请求路径始终来自编译期常量:
  ```ts
  // frontend/shared/api/client.ts:299
  const url = new URL(`${API_BASE}/${trimmed}`, window.location.origin)
  ```
- **影响**:插件名一旦变更(`metadata.yaml` 改 name、或 AstrBot 调整挂载前缀),后端 `API_BASE` 改一处即可,前端要改两处且其中一处是 vite 构建配置——漏掉 vite base 会导致所有 chunk 404(这类"资产 404"症状在 git 历史里已经出现过:`fix: load material library page without expiring asset chunk`)。而 `bootstrap.api_base` 这个正确的解耦通道就在那里没被使用。
- **修复建议**:`client.ts` 的 `buildUrl` 改为优先使用运行期值:模块内维护 `let runtimeApiBase = API_BASE`,bootstrap 成功后调 `setApiBase(bootstrap.api_base)`。vite base 保持编译期常量(静态资源必须编译期确定),但加一条 `frontend/tests/` 断言 `vite.config.ts` 的 base 以 `endpoints.ts` 的 `API_BASE` 开头。

---

### [P3-轻微] `CharacterProfile` TS 类型缺 owner 四字段,`generation_kind` 联合含后端不产出的值

- **位置**:`frontend/shared/types/profile.ts:3-21` vs `backend/dto/profile_dto.py:32-52` 与 `database/repositories/profile_repository.py:32-56`
- **问题**:DTO 输出 20 个字段,TS 声明 16 个;且 TS 的枚举值比后端 SQL 实际产出的多一个。
- **代码**:
  后端 `to_dict()` 输出但 TS 未声明:`owner_platform`、`owner_context_id`、`owner_user_id`、`owner_session_key`(`profile_dto.py:42-45`)。
  TS 声明:
  ```ts
  // frontend/shared/types/profile.ts:18
  generation_kind?: "ungenerated" | "quick" | "detailed" | "profile_card"
  ```
  而 SQL 表达式只可能产出三个值:
  ```sql
  -- database/repositories/profile_repository.py:32-56
  CASE WHEN EXISTS (... profile_card.status = 'sealed') THEN 'detailed'
       WHEN EXISTS (... final_archive_history_id ...)   THEN 'detailed'
       WHEN EXISTS (... character_fast ...)             THEN 'quick'
       ELSE 'ungenerated' END AS generation_kind
  ```
- **影响**:owner 四字段是多租户归属信息,随每个 profile 响应传输但前端不认识——将来若要做"仅显示我创建的角色"这类过滤,会有人再造一份类型。`"profile_card"` 是死枚举值,`switch (profile.generation_kind)` 里为它写的分支永远不执行,读代码的人会误以为存在这个状态(`profile_category` 才有 `profile_card`)。
- **修复建议**:DTO 与 TS 字段做一次对齐(不需要的字段就从 `to_dict()` 里删,别只在 TS 侧省略);删掉 `generation_kind` 里的 `"profile_card"`。长期看应由 P2-14 建议的 DTO schema 导出自动生成。

---

### [P3-轻微] `WorkflowRoundNextRequest.count` 类型比后端窄,掩盖了 cross_review 的 1..8 区间

- **位置**:`frontend/shared/types/workflow-round.ts:48-52` vs `backend/services/workflow_round_service.py:1159-1171`
- **问题**:TS 把候选数收窄为字面量联合 `4 | 5`,后端接受的区间取决于轮次类型。
- **代码**:
  ```ts
  // frontend/shared/types/workflow-round.ts:48-52
  export interface WorkflowRoundNextRequest {
    count: 4 | 5
    idempotency_key: string
    model_route?: string
  }
  ```
  ```python
  # backend/services/workflow_round_service.py:1159-1171
  def _requested_count(value: Any, round_kind: str) -> int:
      count = int(value) if value is not None else 4
      maximum = 8 if round_kind == "cross_review" else 5
      if count < 1 or count > maximum:
          raise ApiError(ErrorCode.VALIDATION_FAILED,
              "round candidate count is outside the supported range",
              {"field": "count", "minimum": 1, "maximum": maximum})
  ```
- **影响**:目前是安全方向的收窄(前端发的值后端一定接受),不会产生 400。但把"业务上只允许 4 或 5"这条产品规则固化在了 TS 类型里而后端并不这么认为,两边对同一规则的理解已经分叉;将来要支持"生成 8 张交叉复核候选"时,类型会成为改动的隐性阻碍,且改动方向不明确(因为没人记得后端其实早就支持)。
- **修复建议**:改为 `count: number`,把"4 或 5"的选择限制放在 UI 控件层(下拉框选项),并在 `WorkflowGenerationRoundDetail` 或 `round.metadata` 里由后端下发 `allowed_count_range: [min, max]`,让 UI 选项跟着轮次类型走。