54 KiB
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.<key> 引用做交叉。
| # | 方法 | 端点 | 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 三条路由指向同一个函数体:
# 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<T>("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。 -
代码:
后端:
# 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前端(同一套规则,第二份实现):
// 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// frontend/standalone-web/src/App.vue:927 const CHARACTER_WORKFLOW_PROGRESSION_VERSION = "character_gradual_sequential_v1"根因是后端从不下发进度:
# 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的降级分支,等于把后端的向后兼容策略也复制了一份,双份都要维护。 -
修复建议:
- 在
list_workflow_nodes返回体外层加progression字段(CharacterGradualProgression.to_dict()已经现成,含current_node_id/completed_node_ids/all_completed/import_confirmed):
(返回结构变更需同步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) - 删除
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 -
问题:两条独立的"这个节点还能不能写"规则,条件集合不同;前端多判了一个不存在的字段,少判了两个真实条件。
-
代码:
前端:
// 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) }后端:
# 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返回空。它只存在于前端和前端测试里。 -
影响:三处真实分歧。
node.selected_image_id已设但status != "selected"时(例如adopt-image后 status 仍为completed),前端认为可写并放行"再跑一轮",后端返回VALIDATION_FAILED / required_action: create_branch,用户看到一个无法自恢复的报错。- 节点已进入
progression.completed_node_ids(通过skipped或 planning 节点completed)时同理。 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):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之前: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 分支):// 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七个后端不认识的别名。 -
影响:
- 快速角色流的模型标签会直接说谎:用户设了本次覆盖,UI 显示"本次覆盖 → route-X",后端实际按
assigned_route出图。 - 对
quick_*节点,workflowModelAssignmentKey("quick_avatar","generation")返回"quick_avatar"(fallback 到canonical),去model_assignments里查不到,UI 显示"角色默认/系统默认",后端实际用quick_generation分配的路由。 - 前端读取的是配置文件的原始结构(
currentSettings.value.config.model_assignments、config.generation.default_model,App.vue:2218/2231-2233),后端换个配置键名前端就静默失准。
- 快速角色流的模型标签会直接说谎:用户设了本次覆盖,UI 显示"本次覆盖 → route-X",后端实际按
-
修复建议:新增
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):"retry": { "auth_required": True, "required_permission": "can_retry_tasks", "required_permissions": ["can_write", "can_retry_tasks"], "description": "task retry management (write + retry capabilities)", },# 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):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统一走它: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/,却没有忽略这两个实际的输出目录。 - 代码:
// frontend/standalone-web/vite.config.ts:9-15 base: "/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/", build: { outDir: resolve(rootDir, "../../web"), emptyOutDir: true },// frontend/plugin-page/vite.config.ts:11-15 base: "./", build: { outDir: resolve(rootDir, "../../pages/imagestudio"), emptyOutDir: true },
两份 dist 内容同源——# backend/services/web_hosting_service.py:14-15 PLUGIN_PAGE_DIR = REPO_ROOT / "pages" / "imagestudio" STANDALONE_WEB_DIR = REPO_ROOT / "web"frontend/plugin-page/src/App.vue全文只有:
git 事实:<script setup lang="ts"> import WorkbenchApp from "../../standalone-web/src/App.vue" </script> <template><WorkbenchApp /></template>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。 - 影响:
- 每个 UI 改动的 diff 被 2MB 二进制级噪音淹没,code review 无法看清真实变更;
git status首屏就是二十多行D web/assets/...。 - 产物与源码可能不同步:目前没有任何 CI 校验
web/是当前frontend/的构建结果。一个只改源码忘记 build 的提交,会让线上跑的仍是旧 JS,而WebHostingService.manifest()只检查index.html是否存在(web_hosting_service.py:33/38),报告built: true,无法发现版本错位。 - 内容哈希文件名 +
emptyOutDir让每次构建产生全新路径,git 历史里累积了大量永不复用的 blob,仓库体积单向膨胀。 - 两份 dist 意味着任何 UI 修复都必须记得跑两次构建,漏一次就出现"插件页正常、独立页是旧版"的诡异现象——git 历史里
fix: recover material library after stale asset token、fix: load material library page without expiring asset chunk两条修复正是这一类症状。
- 每个 UI 改动的 diff 被 2MB 二进制级噪音淹没,code review 无法看清真实变更;
- 修复建议:
.gitignore增加/web/与/pages/imagestudio/(保留.gitkeep),git rm -r --cached web pages/imagestudio。- 发布流程改为 CI 构建 + 打包进 release artifact;仓库只保留源码。若插件分发形态要求产物随包,则用一次性的 release 分支/tag 承载,不进主干历史。
- 若因 AstrBot 插件安装方式必须保留产物在主干,则退而求其次:加一条 CI 检查
npm run build && git diff --exit-code web pages,保证产物永远与源码一致;并把两个 vite 配置合并为一次构建两个 base(或让 plugin-page 直接复用 standalone 产物),消除"两份 dist"。 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 通道):# 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), }前端:
// 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两个字段每次都白白序列化传输且被前端丢弃。 -
修复建议:
EventStreamService.recent_events增加after_event_id: str | None,在_history中定位后返回其后全部事件(配合limit上限 200),并返回truncated: bool告知客户端是否发生了窗口溢出。- 前端改传
{ after_event_id: lastEventStreamId, limit: 200 };收到truncated: true时退化为一次全量刷新(loadJobs + loadDashboard + 当前视图),而不是静默少刷。 content_type/body两个字段要么删掉(JSON 通道用不上),要么单独开一条真正的 SSE 路由;现在这样两边都不是。
[P2-中等] 队列状态枚举在前后端共 4 处独立硬编码
-
位置:
backend/services/queue_service.py:31-34vsfrontend/standalone-web/src/App.vue:3285、3293、frontend/shared/utils/presentation.ts:5 -
问题:后端已经把任务状态分类抽成了具名常量,前端把这些集合的字面量抄了三份,还多出一个后端没有的分类。
-
代码:
后端唯一真相:
# 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))前端三份拷贝:
// 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])// 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;前端零引用 - 问题:后端为"内容审核隔离图片"实现了完整闭环——列表过滤、管理员可见开关、隐藏计数、管理员复核端点——前端一个都没接。
- 代码:
# 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"])
前端验证:# 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-49vsbackend/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):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 命中)。 而声明处一律写成:// advanced-material.ts:168 status: AdvancedMaterialImportStatus | stringTypeScript 会把
"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这两个幽灵值说明漂移已经发生过至少一次且无人察觉。 -
修复建议:
- 把
| string去掉,改为status: AdvancedMaterialImportStatus,让联合类型真正生效;确实需要容忍未知值的地方用显式as string或在解析边界处收窄。 - 状态集合从后端生成而非手抄:把各
*_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.pyvsbackend/services/advanced_style_set_service.pyvsfrontend/shared/types/advanced-material.ts -
问题:TS 类型里大量字段在 DTO 的
to_dict()中不存在,而路由层的序列化只补了*_url。 -
代码:
路由层只做签名 URL 增强,不加业务字段:
# 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 无此字段 实际来源 AdvancedStyleSourceexcluded、filename、image_uri、thumbnail_uri、retry_countadvanced_style_set_service.py:409/414手工构造的 metadata / view dictAdvancedStyleValidationCasescenario、title、style_prompt、style_scores、rendering_layers、content_noveltyadvanced_style_set_service.py:2330/2354/3345/3422AdvancedMaterialImporttask_id、workflow_kind、sources、consensus、validation_casesadvanced_style_set_service.py:389/1152AdvancedStyleConsensus整个接口无对应 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-66vsfrontend/standalone-web/src/features/settings/model-route-chain.ts:27-39 - 问题:这不是"逻辑重复",而是同一个序列化格式的两份独立实现——前端写出的字符串要被后端解析,任何一边的细节改动都会破坏另一边,而目前正确性完全依赖手工对齐
json.dumps与JSON.stringify的输出细节。 - 代码:
# 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)
目前能对上,靠的是三个巧合同时成立:Python// frontend/standalone-web/src/features/settings/model-route-chain.ts:33 return `${MODEL_ROUTE_CHAIN_PREFIX}${JSON.stringify({ astrbot, plugin })}`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-20vsfrontend/standalone-web/src/features/workflow/workflow-node-catalog.ts:23-32vsfrontend/standalone-web/src/features/workflow/workflow-model-route.ts:61-74 - 问题:同一张"legacy node_key → canonical node_key"映射表存在三份,其中两份在同一个前端目录下且映射结果不同。
- 代码:
# 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", }// 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", }
另外 11 个节点的// workflow-model-route.ts:61-74 —— 同一前端内的第三份,expression_sheet 映射不同 const canonicalAliases: Record<string, string> = { 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", }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 秒预算"在后端并不存在。
- 代码:
// 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)(?:\/|$)/
而// frontend/shared/config/timeouts.ts export const LONG_TASK_TIMEOUT_SECONDS = 900grep -rn "\b900\b" --include=*.py(排除 tests/release/.tmp)在后端只有一处命中,且与生成任务无关:
生成任务的真实预算是 180 秒(# backend/services/advanced_style_set_service.py:57 STYLE_VALIDATION_TIMEOUT_SECONDS = 900generation_service.py:2308request.get("timeout_seconds") or settings.get("timeout_seconds") or 180;config.yaml:25/42timeout_seconds: 180)。 号称守护一致性的测试其实只读前端文件:// 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/) ... }) - 影响:
- 正则里
probe-model、renormalize、renormalize-batch、import-pack对应的端点前端根本不调用(见表 ①),说明这份列表已经和实际调用面脱节,无人维护。 - 测试名字断言"后端 900 秒预算",但测试没有读过任何后端文件——它固化的是一个虚构的契约。后端把
timeout_seconds从 180 调到 600,前端不会知道;反过来前端这个 900 也没有任何后端依据。 - 新增一个慢端点(例如
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 -
问题:契约自检机制已经存在且数据完备,但没有被任何一方真正用起来。
-
代码:
# 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": {...}, }// SystemManagementPanel.vue:8 —— 唯一消费点,拉下来直接 JSON.stringify 塞进 <pre> 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():# backend/route_registry.py:365-377 —— 现成的自检,无人调用 def assert_unique_routes() -> None: ... def assert_known_permissions() -> None: ... -
影响:契约漂移目前没有任何自动化拦截。本报告里的表 ①(14 条死接口)、P1-4(权限漏判)、P2-9(状态枚举漂移)全部是人工比对才发现的,任何一条都本可以由 CI 自动发现。
-
修复建议:这是本维度投入产出比最高的一条,建议优先做。三条测试即可覆盖大部分问题:
-
后端自检(
tests/test_route_contract.py,我已实测 166 条 handler 全部可导入,此测试当前会通过):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 -
跨语言路由比对(
frontend/tests/api-contract.test.mjs):解析backend/route_registry.py的RouteSpec("METHOD", "endpoint"与endpoints.ts的模板字符串(把${...}与{...}都归一为{}),断言 endpoints.ts ⊆ ROUTES(阻止表 ② 出现),并把当前 14 条死接口写成显式 allowlist,新增未使用路由时测试失败——逼迫作者要么接上要么删掉。 -
权限门禁比对:前端所有按钮的
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 把它下发给前端,前端却只拿它拼提示文案。
- 代码:
# backend/services/ui_service.py:10(被 contract_service / astrbot_adapter 复用,后端侧是单点) API_BASE = "/api/v1/plugins/extensions/astrbot_plugin_imagestudio"// frontend/shared/api/endpoints.ts:1 export const API_BASE = "/api/v1/plugins/extensions/astrbot_plugin_imagestudio"
前端拿到// frontend/standalone-web/vite.config.ts:11 base: "/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/",bootstrap.api_base之后的唯一用途:
实际请求路径始终来自编译期常量:// frontend/standalone-web/src/App.vue:4330 : `已通过同源 API ${loadedBootstrap.api_base} 调用后端,写入动作会进入工作流并落库。`,// 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-21vsbackend/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 声明:
而 SQL 表达式只可能产出三个值:// frontend/shared/types/profile.ts:18 generation_kind?: "ungenerated" | "quick" | "detailed" | "profile_card"-- 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-52vsbackend/services/workflow_round_service.py:1159-1171 - 问题:TS 把候选数收窄为字面量联合
4 | 5,后端接受的区间取决于轮次类型。 - 代码:
// frontend/shared/types/workflow-round.ts:48-52 export interface WorkflowRoundNextRequest { count: 4 | 5 idempotency_key: string model_route?: string }# 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 选项跟着轮次类型走。