astrbot_plugin_imagestudio/审计/findings/A6-引擎与适配器.md

35 KiB

A6 — engines/ 模型引擎 + adapters/ 平台适配器

审计范围(均已完整 Read): engines/__init__.py、engines/image_provider.py、engines/vision_provider.py、engines/single_flow.py、engines/review_flow.py、engines/character_flow.py、engines/fast_character_flow.py、engines/quick_profile_flow.py adapters/astrbot_adapter.py、adapters/astrbot_card_renderer.py、adapters/astrbot_command_adapter.py、adapters/astrbot_command_parser.py、adapters/astrbot_media_adapter.py、adapters/chat_commands.py、adapters/onebot11_adapter.py、adapters/wechat_adapter.py、adapters/webui_adapter.py backend/services/chat_workflow_service.py、backend/services/chat_session_service.py、backend/services/chat_media_import_service.py、backend/services/model_provider_runtime.py、backend/services/web_hosting_service.py(节选)、backend/services/material_service.py(节选)、backend/services/generation_service.py(节选)、backend/services/profile_service.py(节选) core/generation_errors.py、core/image_formats.py、core/identity.py、core/remote_fetch.py(节选)、main.py(节选)

摘要

图像 provider(engines/image_provider.py)这条链路的工程质量明显高于其余部分:URL 校验、响应字节上限、按图片数动态计算 JSON 上限、错误分类(core/generation_errors._category)、密钥脱敏都做到位了。问题集中在它旁边的三条"次要"链路上——vision provider、structured_text/structured_vision callable、以及聊天媒体导入——这三条都缺少图像链路已有的防护,属于典型的"主路径加固过、旁路径没跟上"。

最严重的一条是功能性死链:size 请求字段从聊天命令一路透传到 task.request,但 engines/single_flow.py:61 只读 aspect_ratio,全仓库没有任何地方把 size 转成 aspect_ratio,因此 /yp 单图 --尺寸 4K 和 /yp 高清 <id> 4K 实际全部产出 1024×1024——高清修复功能等于不生效。

其次是 ChatMediaImportService.import_image 的兜底分支把任意字符串当本地文件路径直接 read_bytes(),而输入来自聊天消息组件的 file/path 字段(adapters/astrbot_media_adapter.py),构成任意本地文件读取面。

关于"四个 flow 文件能否合并":结论是不建议合并。single_flow.py / review_flow.py 是真正的引擎(455/451 行),character_flow.py / fast_character_flow.py / quick_profile_flow.py 是纯声明式节点模板目录(145/50/32 行),三者之间真正重复的只有约 10 行 *_node_templates() 构造器样板,抽取收益远低于把不同工作流的语义强行耦合的代价。真正值得合并的重复在别处:adapters/onebot11_adapter.py 与 adapters/wechat_adapter.py 结构性重复约 90%。


发现

[P1-严重] size 请求字段全链路无人消费,聊天尺寸参数与高清修复静默失效

  • 位置:engines/single_flow.py:61(消费端)、backend/services/chat_workflow_service.py:63 与 :929(生产端)
  • 问题:SingleFlowEngine.generate 只从请求里读 aspect_ratio,而聊天单图与高清修复写入的是 size("1920x1080" / "2560x1440" / "3840x2160")。generation_service.py:733 的 runtime_generation_request = {**payload, ...} 原样透传 size,全仓库(排除 .tmp/、tests/)对 aspect_ratio 的写入只出现在 advanced_material_service.py:912、advanced_style_set_service.py、node_injection_template_service.py、prompt_expansion_service.py——没有任何一处把 size 映射成 aspect_ratio。
  • 代码:
    # engines/single_flow.py:56-61
    def generate(self, node: WorkflowNode, task: GenerationTask, request: dict[str, Any]) -> list[MockGeneratedAsset]:
        count = _bounded_count(request.get("count", 1))
        ...
        width, height = _dimensions(str(request.get("aspect_ratio") or "1:1"))
    
    # engines/single_flow.py:248-255
    def _dimensions(aspect_ratio: str) -> tuple[int, int]:
        if aspect_ratio == "3:4": return 768, 1024
        if aspect_ratio == "4:3": return 1024, 768
        if aspect_ratio == "16:9": return 1280, 720
        return 1024, 1024
    
    # backend/services/chat_workflow_service.py:925-931(高清修复)
    generation = self._data(self.dispatcher(ctx, "POST", f"nodes/{node['node_id']}/generate", payload={
        "prompt": "high resolution restoration, preserve identity, composition, clothing and original style",
        ...
        "size": size,          # <- 写入
        "count": 1,
    
    # engines/single_flow.py:154-159(真正发给 provider 的尺寸)
    result = provider.generate_image(
        ImageGenerationRequest(
            ...
            size=f"{width}x{height}",   # 永远来自 aspect_ratio,即 1024x1024
    
  • 影响:/yp 单图 ... --尺寸 4K 与 /yp 高清 <image_id> 4K 都发出 size="1024x1024";高清修复的唯一价值(提升分辨率)完全失效,用户只会得到一张同尺寸重绘图。同时 astrbot_command_parser.py:49-52 精心校验的 1K/2K/4K 参数是纯装饰。数据库里记录的 width/height 也随之全是 1024。
  • 修复建议:在 single_flow.generate 增加显式的尺寸解析优先级,并让 size 成为一等输入:
    width, height = _resolve_dimensions(request.get("size"), request.get("aspect_ratio"))
    
    def _resolve_dimensions(size: Any, aspect_ratio: Any) -> tuple[int, int]:
        text = str(size or "").strip().lower()
        if match := re.fullmatch(r"(\d{2,5})\s*[x×]\s*(\d{2,5})", text):
            w, h = int(match.group(1)), int(match.group(2))
            return min(max(w, 64), 4096), min(max(h, 64), 4096)
        return _dimensions(str(aspect_ratio or "1:1"))
    
    同时给 SIZE_ALIASES 加一条断言测试,覆盖 /yp 高清 <id> 4K 端到端产出的 ImageGenerationRequest.size。

[P1-严重] 聊天媒体导入把任意字符串当本地文件路径读取(任意本地文件读取面)

  • 位置:backend/services/chat_media_import_service.py:33-36,输入来源 adapters/astrbot_media_adapter.py:15-18 → main.py:1161,1167
  • 问题:import_image 的兜底分支在既不是 storage://、也不是 data:image/、也不是 http(s):// 时,直接把字符串当本地路径 expanduser().resolve().read_bytes(),没有任何根目录约束或白名单。而这个字符串来自聊天消息里 Image 组件的 url / file / path / image_url 属性——这几个字段在 OneBot/WeChat 协议侧是消息内容的一部分,并非可信的服务端常量。
  • 代码:
    # adapters/astrbot_media_adapter.py:12-19
    for component in chain if isinstance(chain, (list, tuple)) else []:
        if "image" not in component.__class__.__name__.lower():
            continue
        for name in ("url", "file", "path", "image_url"):
            text = str(getattr(component, name, None) or "").strip()
            if text and text not in references:
                references.append(text)
    
    # backend/services/chat_media_import_service.py:30-36
    elif text.startswith(("http://", "https://")):
        body = read_http_response_limited(text, timeout_seconds=30, max_bytes=MAX_CHAT_IMAGE_BYTES)
        extension = Path(urlsplit(text).path).suffix.lstrip(".").lower() or "jpg"
    else:
        source = Path(text).expanduser().resolve()
        body = source.read_bytes()          # <- 无任何根目录约束
        extension = source.suffix.lstrip(".").lower() or "jpg"
    
  • 影响:只要消息组件的路径字段可被影响(file:///、相对路径、~/.astrbot/...),任意宿主文件即可被读入并作为"素材"落盘到 storage://materials/chat/...,随后通过素材列表接口读回——等价于任意文件读取 + 外带。同一条链路上还有第二个缺陷:整个函数没有任何图片魔数校验(对比 engines/single_flow.py:447 _require_image_format 对 provider 返回图片做了 detect_image_format),扩展名只是被强制改写成 jpg,非图片内容会被当图片存储。data:image/ 分支的 base64.b64decode(encoded) 也在解码之后才检查 len(body) > MAX_CHAT_IMAGE_BYTES,一个超大 data URI 会先被完整解码进内存。
  • 修复建议:
    1. 删除本地路径兜底分支,或改为对一个显式配置的缓存根做 Path.resolve() 前缀约束(参考 backend/services/web_hosting_service.py:58-67 的 _resolve 写法,那里做对了)。
    2. 落盘前统一走 core.image_formats.detect_image_format(body),None 则拒绝,并用检出的 image_format.extension 而非用户扩展名。
    3. data: 分支先按 len(encoded) > ((MAX_CHAT_IMAGE_BYTES + 2) // 3) * 4 预检再解码(engines/single_flow.py:398-404 已有这个正确写法可直接复用)。

[P1-严重] 内容安全审核 provider 解析时缺 modality 与 provider_type 校验,与同文件其他两处不一致

  • 位置:backend/services/model_provider_runtime.py:285-289(对比 :131-136 与 :196-201)
  • 问题:_structured_vision_callable_for_single_route 调用 resolve_route(route_name) 不带 modality=,且没有 provider_type == "openai_compatible" 的前置判断。同文件的 _vision_provider_for_single_route 两者都有,_structured_text_callable_for_single_route 有 provider_type 判断。这个 callable 承担的是图像内容安全审核(涉政/涉恐/未成年人识别)。
  • 代码:
    # backend/services/model_provider_runtime.py:131-136(正确的对照组)
    resolved = self.model_provider_service.resolve_route(route_name, modality="vision_recognition")
    if not resolved:
        return None
    provider = resolved.get("provider") or {}
    if str(provider.get("provider_type") or "openai_compatible") != "openai_compatible":
        return None
    
    # backend/services/model_provider_runtime.py:285-289(缺两道校验)
    resolved = self.model_provider_service.resolve_route(route_name)
    if not resolved:
        return None
    provider = resolved.get("provider") or {}
    secret = resolve_secret_value(...)          # 直接进入取密钥,没有 provider_type 判断
    
    而下面 review() 硬编码 OpenAI chat/completions 报文形状(:331-341)。
  • 影响:同名路由若在 image_generation 模态下存在,会被解析成"审核模型";一个非 openai_compatible 的 provider 也会被套上 OpenAI 报文格式发送。两种情况都在审核时抛异常。而 structured_vision_callable 的 review_with_fallback(:264-271)对所有异常一律吞掉换下一条路由,全部失败后抛 RuntimeError ——上层若把"审核不可用"当作放行,就是安全审核静默绕过;若当作拒绝,则是全量误杀。无论哪种,都不该由一个可以被静态排除的配置错配触发。
  • 修复建议:与 :131-136 对齐——补 modality="vision_recognition"(或为审核新增独立 modality)与 provider_type 判断;并把三处 resolve_route + 密钥解析 + provider_type 校验 抽成一个私有方法,杜绝再次漂移。

[P2-中等] 缩略图是原图的字节级完整拷贝,存储占用直接翻倍

  • 位置:engines/single_flow.py:176-179
  • 问题:provider 返回的图片字节被原样写入 image_uri 和 thumbnail_uri 两个路径。全仓库(engines/、backend/services/generation_service.py)不存在任何降采样/缩放代码,core/image_formats.py 也只做魔数识别、不解析尺寸。
  • 代码:
    # engines/single_flow.py:176-179
    image_format = _require_image_format(image_bytes, provider_id=result.provider_id)
    image_uri, thumbnail_uri = _output_uris(task, request, index, image_format.extension)
    self._write_image(image_uri, image_bytes)
    self._write_image(thumbnail_uri, image_bytes)   # 同一份字节写两遍
    
  • 影响:单张图上限 MAX_PROVIDER_IMAGE_BYTES = 25 MiB(engines/image_provider.py:21),意味着最坏情况每张生成图占 50 MiB。候选池默认一轮 4 张、快速角色 4 节点并发,磁盘增长是设计预期的 2 倍。同时前端列表页加载"缩略图"实际拉的是全尺寸原图,网络与内存开销同样翻倍。
  • 修复建议:在 _write_image 之外新增 _write_thumbnail(uri, image_bytes, max_edge=512),用已经作为可选依赖存在的 Pillow(adapters/astrbot_card_renderer.py:56 已 from PIL import Image)做等比缩放;Pillow 不可用时退化为写原图并在 metadata 打 thumbnail_downscaled: False,便于后续补偿任务识别。

[P2-中等] vision provider 链路完全没有错误分类与可重试判定,retryable 字段是死代码

  • 位置:engines/vision_provider.py:304-326、backend/services/material_service.py:857-871
  • 问题:图像链路有 core/generation_errors.provider_failure_attribution,把 401/403 → auth_error、429 → rate_limited、5xx → provider_unavailable,并计算 retryable(core/generation_errors.py:102-125)。vision 链路没有任何等价物:_vision_provider_error 只是把 error_type 原样搬运,retryable 依赖 exc.details.get("retryable")——而 engines/vision_provider.py 全文从未往 details 里写过 retryable,因此那两行永远不会执行。
  • 代码:
    # backend/services/material_service.py:863-865
    "response_issue": str(exc)[:300],
    }
    if isinstance(exc.details.get("retryable"), bool):    # vision_provider 从不设置该键
        failure["retryable"] = exc.details["retryable"]
    
    # engines/vision_provider.py:304-312(唯一写 details 的地方,只有 body_preview / body_truncated)
    except urllib.error.HTTPError as exc:
        body = exc.read(MAX_PROVIDER_ERROR_BYTES + 1).decode("utf-8", errors="replace")
        raise VisionProviderError(
            "vision provider returned an HTTP error",
            provider_id="unknown",
            status_code=exc.code,
            error_type="http_error",          # 401 / 429 / 503 全都是 "http_error"
            details={"body_preview": body[:500], "body_truncated": len(body) > MAX_PROVIDER_ERROR_BYTES},
        ) from exc
    
  • 影响:素材识别失败时,鉴权错误(用户必须改配置)、限流(应退避重试)、上游 5xx(应重试)在 error_type 上完全无法区分;_record_recognition_failure 记录的失败态没有可操作信息,重试策略无从制定,UI 也只能给出通用文案。_vision_provider_error 还绕过了 core/generation_errors._safe_message 的密钥脱敏正则,reason(来自 str(exc.reason))与 parse_error 未经清洗即落入 ApiError.details 并返回给客户端(advanced_material_service.py:787、advanced_style_set_service.py:1283)。
  • 修复建议:把 core/generation_errors.py 的 _category / _is_retryable / _safe_details / _safe_message 提成与异常类型无关的公共函数(入参 error_type + status_code + details),让 provider_failure_attribution 与新增的 vision_failure_attribution 共用;material_service._vision_provider_error 改为调用后者,删掉那两行死代码。

[P2-中等] vision 请求体无上限,8 张 20 MB 图可构造 ~213 MB 的单次 JSON 请求

  • 位置:engines/vision_provider.py:17-19、:294;调用方 backend/services/advanced_style_set_service.py:1545-1548,1654-1657,2281-2284
  • 问题:vision_provider 只对响应设了 MAX_PROVIDER_JSON_BYTES = 4 MiB,对请求体没有任何限制。多图分析路径用 image_uris 一次传最多 MAX_VISION_IMAGES = 8 张,每张经 material_service._storage_image_data_url 转成 base64 data URI,单张原图上限是 MAX_UPLOAD_BYTES = 20 MiB(backend/services/material_service.py:43),base64 后约 27 MiB。
  • 代码:
    # engines/vision_provider.py:17-19
    MAX_PROVIDER_JSON_BYTES = 4 * 1024 * 1024      # 只约束响应
    MAX_PROVIDER_ERROR_BYTES = 64 * 1024
    MAX_VISION_IMAGES = 8
    
    # engines/vision_provider.py:294
    data = json.dumps(payload, ensure_ascii=False).encode("utf-8")   # 完整物化,无上限
    
  • 影响:单次风格集共识分析峰值内存约为 payload dict + json 字符串 + utf-8 bytes ≈ 3 份 213 MB。插件运行在 AstrBot 主进程内,OOM 会拖垮整个 Bot。且几乎所有上游都会以 413 拒收,等于一条注定失败但先把宿主打爆的路径。对比 engines/image_provider.py:392-401 的 _provider_json_limit——图像链路已经按图片数动态算过上限了,vision 没跟上。
  • 修复建议:新增 MAX_VISION_REQUEST_BYTES(如 32 MiB),在 _post_json 里 if len(data) > MAX_VISION_REQUEST_BYTES: raise VisionProviderError(..., error_type="invalid_request");更好的做法是在 _storage_image_data_url 之前按"张数 × 单张预算"约束,超限时先降采样再编码。

[P2-中等] 三处 fallback 对所有错误一视同仁地换下一个 provider,包括不该重试的鉴权/配置/内容策略错误

  • 位置:engines/image_provider.py:179-198、engines/vision_provider.py:150-184、backend/services/model_provider_runtime.py:180-189 与 :264-271
  • 问题:core/generation_errors._is_retryable(core/generation_errors.py:122-125)已经把可重试语义定义清楚了,但四个 fallback 循环没有一个使用它。
  • 代码:
    # engines/image_provider.py:191-192
    except ImageProviderError as exc:
        failures.append({"provider_id": provider.provider_id, "error_type": exc.error_type, "status_code": exc.status_code})
        # 无论 configuration_error / 401 / 400 内容策略拒绝,一律继续下一个 provider
    
    # backend/services/model_provider_runtime.py:182-186
    for completion in callables:
        try:
            return completion(request_payload)
        except Exception as exc:              # 连 ValueError/JSONDecodeError 都算"该换路由"
            failures.append(str(exc)[:500])
    
  • 影响:一个被内容策略拒绝的提示词(400)会依次打完所有已启用路由——而 image_provider_for_route 在 fallback_enabled 时会把全部启用的 image_generation 路由追加进候选(model_provider_runtime.py:60-71)。结果是一次用户请求放大成 N 次必然失败的付费调用,同时 N 倍地推高各家的限流计数。同样地,密钥填错时用户看到的是"所有候选生成服务均调用失败"而不是"鉴权失败",排障方向被彻底带偏。
  • 修复建议:让 _is_retryable 成为 fallback 的准入条件:
    from core.generation_errors import provider_failure_attribution
    except ImageProviderError as exc:
        attribution = provider_failure_attribution(exc)
        failures.append(attribution)
        if not attribution["retryable"]:
            raise            # 鉴权/配置/请求错误立即上抛,不消耗其余 provider
    
    structured_text_callable / structured_vision_callable 需要先给 HTTP 错误分类(见上一条),才能做同样的判断。

[P2-中等] structured_text_callable 用裸 json.loads 解析模型输出,缺 vision 侧已有的容错

  • 位置:backend/services/model_provider_runtime.py:244-249(对比 engines/vision_provider.py:398-429)
  • 问题:engines/vision_provider._json_from_text 实现了一套克制的修复策略——剥离 BOM、从首个 { 到末个 } 截取(处理 markdown 代码围栏)、去尾逗号,共 4 个候选依次尝试。structured_text_callable 走的是同类 OpenAI chat/completions 接口、同样带 response_format: json_object,却直接 json.loads(content)。
  • 代码:
    # backend/services/model_provider_runtime.py:244-249
    response = json.loads(raw)
    content = _completion_content(response)
    parsed = json.loads(content)               # 模型多输出一个 ```json 围栏就炸
    if not isinstance(parsed, dict):
        raise ValueError("structured completion must return an object")
    
    # engines/vision_provider.py:402-411(同一问题的正确解法,已存在)
    candidates = [text]
    start, end = text.find("{"), text.rfind("}")
    if start >= 0 and end > start:
        extracted = text[start : end + 1]
        if extracted != text:
            candidates.append(extracted)
    candidates.extend(re.sub(r",\s*([}\]])", r"\1", item) for item in list(candidates))
    
  • 影响:structured_text_callable 是提示词扩写/结构化处理的入口。大量 OpenAI 兼容网关(尤其国产模型代理)不真正支持 response_format: json_object,会返回带围栏的 JSON——这些模型在 vision 路径能用、在 text 路径必失败,且失败形态是裸 json.JSONDecodeError 冒泡,complete_with_fallback 把它当作"换路由"信号继续烧下一条路由(与上一条叠加)。
  • 修复建议:把 vision_provider._json_from_text 提到 core/(例如 core/llm_json.py),vision、structured_text、structured_vision 三处共用。

[P2-中等] 单条聊天消息内的图片数量无上限,直接放大为 N 次下载 + N 次视觉大模型调用

  • 位置:adapters/astrbot_media_adapter.py:8-20、main.py:1161-1167
  • 问题:image_references_from_event 遍历整个消息链、对每个 image 组件收集一个引用,没有任何数量截断;main.py 随后对每个引用串行执行完整的"导入 + 识别"流程,每次识别都是一次视觉大模型调用。
  • 代码:
    # main.py:1161-1167
    references = image_references_from_event(event)
    if not category.strip() or not references:
        ...
    results = [await asyncio.to_thread(self.chat_workflow_service.import_material, reference, category.strip(), context) for reference in references]
    
    # backend/services/chat_workflow_service.py:948-954(每个引用的代价)
    uri, filename, size_bytes = self.media_importer.import_image(image_reference)   # 最多 20MB 下载
    material = self._data(self.dispatcher(ctx, "POST", "materials/upload", payload={...}))
    recognized = self._data(self.dispatcher(ctx, "POST", f"materials/{material['material_id']}/recognize", payload={}))  # 视觉大模型调用
    
  • 影响:QQ 合并转发或一条多图消息可轻易携带数十张图。一条命令即触发数十次 20 MB 下载与数十次付费视觉调用,全部在 asyncio.to_thread 里串行执行,期间该用户的其它聊天命令排队等待。ChatCommandGuardService 的配额校验在 submit_single_image 里有(chat_workflow_service.py:38),import_material 路径上完全没有。
  • 修复建议:在 image_references_from_event 内部截断(MAX_CHAT_IMAGE_REFERENCES = 4,与 MAX_VISION_IMAGES 语义对齐),超出部分在回复里明示"仅处理前 N 张";并让 import_material 也走 self.guard.check_generation / self.guard.record,与单图命令一致。

[P2-中等] onebot11_adapter.py 与 wechat_adapter.py 结构性重复约 90%

  • 位置:adapters/onebot11_adapter.py:12-98、adapters/wechat_adapter.py:12-79
  • 问题:两个文件各定义一个仅字段名不同的消息 dataclass,然后逐字复制 match_workbench_command、workbench_reply、handle_message_event、quick_profile_reply、_optional_text 五个函数。除了 platform 常量、群标识字段名(group_id vs room_id)、以及回复字典的键("message" vs "text")之外没有任何差异。
  • 代码:
    # adapters/onebot11_adapter.py:53-71
    def handle_message_event(event, *, api_base=API_BASE):
        message = normalize_message_event(event)
        command = parse_chat_command(message.text)
        if command is None: return None
        if command.action == "quick_profile":
            return {"platform": "onebot11", "action": command.action, "payload": command.payload,
                    "source": message.to_dict(), "reply": quick_profile_reply(command.payload["questionnaire"]["name"])}
        return {"platform": "onebot11", "action": "open_workbench", "source": message.to_dict(), "reply": workbench_reply(api_base)}
    
    # adapters/wechat_adapter.py:49-67 —— 逐行相同,仅 "onebot11" -> "wechat"
    
  • 影响:chat_commands.py 每次新增命令,都必须记得同步改两个文件;两者已经开始漂移(onebot11 的 workbench_reply 用 "message" 键、wechat 用 "text" 键,且都额外带一个重复的 "url")。新增第三个平台(Telegram/Discord,_chat_entrypoint 已为它们预留分支)会变成第三份拷贝。
  • 修复建议:抽 adapters/chat_platform_adapter.py,定义 PlatformSpec(platform, group_field_names, user_field_names, reply_text_key) 与一个通用 handle_message_event(event, spec, *, api_base);两个现有模块退化为 spec 常量加薄封装,保持导出符号不变以免破坏 adapters/__init__.py。

[P2-中等] 聊天身份未按平台命名空间隔离,跨平台同 ID 可互相访问档案

  • 位置:backend/services/chat_workflow_service.py:1157-1164(对比 main.py:2329-2344)
  • 问题:RequestContext.from_astrbot(user_id=chat.user_id) 直接用平台原始用户 ID;ProfileService 的归属判定基于 ctx.actor_id(backend/services/profile_service.py:36,92,161),即 user_id or username。source 字段虽然带了平台(f"astrbot_chat:{chat.platform}"),但它不参与任何归属判定。
  • 代码:
    # backend/services/chat_workflow_service.py:1157-1164
    return RequestContext.from_astrbot(
        username=chat.user_id or "chat-user",
        user_id=chat.user_id or "chat-user",          # 无平台前缀
        permissions={"can_write", "can_retry_tasks", "can_manage_materials"},
        source=f"astrbot_chat:{chat.platform}",       # 平台信息只进了这里,不参与鉴权
        ...
    
    # backend/services/profile_service.py:160-163
    def _require_owner(self, profile: CharacterProfile, ctx: RequestContext) -> None:
        if ctx.actor_id and ctx.actor_id == profile.owner_user_id:
            return
    
  • 影响:QQ 号 12345 与 Telegram 用户 ID 12345(两者都是纯数字)会落进同一个 owner_user_id,互相看到并操作对方的全部角色档案、工作流、图片。WebUI 侧的 actor_id 是 AstrBot 登录名(main.py:2325-2332),与聊天 ID 共用同一命名空间,一个用户名恰好是纯数字的 WebUI 账号同样会与聊天用户撞车。ID 越界不需要任何攻击技巧,是配置巧合即触发。
  • 修复建议:_request_context 里改用带平台前缀的复合标识:user_id=f"{chat.platform or 'astrbot'}:{chat.user_id}",WebUI 侧对应用 webui: 前缀。这会改变已有数据的 owner_user_id,需要配套一次性迁移脚本(把现存无前缀记录按 source 字段回填),建议在迁移里对无法判定来源的记录保守地归入 webui:。

[P2-中等] 聊天卡片 PNG 缓存目录无淘汰机制,用户可任意撑爆磁盘

  • 位置:adapters/astrbot_card_renderer.py:55-78,调用方 main.py:524-531
  • 问题:_render_card 以内容 sha256 前 16 位为文件名缓存到 data/chat_cards/,命中即复用。缓存永不过期、永不清理,而 key 的输入完全由用户提供。
  • 代码:
    # adapters/astrbot_card_renderer.py:58-61
    CARD_DIR.mkdir(parents=True, exist_ok=True)
    target = CARD_DIR / f"{hashlib.sha256(key.encode('utf-8')).hexdigest()[:16]}.png"
    if target.exists():
        return target
    
    # main.py:526-529 —— key 的四个组成部分全部来自用户输入的角色描述
    lambda: render_profile_card(
        name=str(preview.get("name") or ""), base=str(preview.get("base_prompt") or ""),
        appearance=str(preview.get("appearance_prompt") or ""), style=str(preview.get("style_prompt") or ""),
    ),
    
  • 影响:每次 /yp 快速角色 <任意不同描述> 都产生一个新 sha256 → 一张新的 1000×560 PNG(约 50–200 KB)。反复调用可无限增长;且 height = 300 + max(len(lines), 1) * 66(:63)在 render_status_card 的 details 变长时会线性放大画布,进一步放大单文件体积。这是插件进程内的磁盘写入,撑爆的是 AstrBot 宿主的数据盘。
  • 修复建议:给 CARD_DIR 加简单的 LRU 上限——渲染前统计目录文件数,超过阈值(如 500)时按 st_mtime 删除最旧的一批;或改为渲染到内存 BytesIO 直接投递,完全不落盘(AstrBot 的图片回复支持字节流)。另外把 lines 的长度与条数做截断,避免画布尺寸被输入放大。

[P3-轻微] dispatch_extension_request 解析出了路由声明的 permission 却从不校验

  • 位置:adapters/astrbot_adapter.py:171-187
  • 问题:RouteMatch 携带 permission 字段(来自 backend/route_registry.ROUTES,实测分布为 read×62 / write×37 / materials×36 / config×22 / retry×8 / public_token×1),但 dispatch 时只用 handler 和 path_params,permission 从未参与判断。全部权限校验依赖每个 handler 自己记得调 core.security.require_*。
  • 代码:
    # adapters/astrbot_adapter.py:179-187
    match = resolve_route(method, path)
    if match is None:
        return error_response(...)
    return match.handler(*_handler_args(match, ctx, query or {}, payload or {}))
    # match.permission 在此之后再无引用
    
  • 影响:路由清单里声明的权限是纯文档,不构成任何强制力。目前抽查的 10 个"未直接调用 require_*"的 handler 都通过内层委托做了校验(如 profile_routes.archive_profile → delete_profile、image_routes.review_moderated_image 内联 ctx.has_permission),所以当下没有实际漏洞——但这是纯靠约定维系的状态,任何新增 handler 漏掉一行 require_permission 就是静默的越权入口,且没有任何测试会发现。
  • 修复建议:在 dispatch 层做统一的前置校验,把 RouteSpec.permission 映射到 core.security 的检查函数(read→require_authenticated、write→require_write、config→require_permission(ctx, "can_manage_config")、public_token→跳过),handler 内的细粒度检查保留为纵深防御。这样清单即契约,新增路由无法绕过。

[P3-轻微] review_flow.review_node 内联复制了 _candidate_warnings 的告警逻辑

  • 位置:engines/review_flow.py:141-159 与 engines/review_flow.py:362-380
  • 问题:MODEL_ROUTE_MISMATCH 与 PROMPT_MISMATCH 两条告警的判定条件、消息文案、附加字段在同一文件里写了两遍,一遍针对 selected_image、一遍针对候选图。
  • 代码:
    # engines/review_flow.py:150-159
    if selected_image and node.prompt and selected_image.positive_prompt:
        node_prompt = _normalize_prompt(node.prompt)
        image_prompt = _normalize_prompt(selected_image.positive_prompt)
        if node_prompt and image_prompt and node_prompt not in image_prompt and image_prompt not in node_prompt:
            warnings.append({"code": "PROMPT_MISMATCH", "message": "selected image prompt differs from node prompt"})
    
    # engines/review_flow.py:375-379 —— 判定与文案逐字相同,仅变量名不同
    if node.prompt and image.positive_prompt:
        node_prompt = _normalize_prompt(node.prompt)
        image_prompt = _normalize_prompt(image.positive_prompt)
        if node_prompt and image_prompt and node_prompt not in image_prompt and image_prompt not in node_prompt:
            warnings.append({"code": "PROMPT_MISMATCH", "message": "candidate prompt differs from node prompt"})
    
  • 影响:review_node 返回的 warnings 与其内部 stage_review.candidates[*].warnings 存在漂移风险——一致性规则改了一处忘了另一处,同一张图在两个字段里会给出矛盾结论,而 _candidate_score(:392)直接用 len(warnings) 打分,漂移会体现在分数上。
  • 修复建议:review_node 里对 selected_image 直接复用 _candidate_warnings(node, selected_image),删除 141-159 的内联副本(注意保留 MODEL_ROUTE_MISMATCH 在 node 级别携带的 node_model_route/image_model_route 字段,_candidate_warnings 已经带了)。

[P3-轻微] _match_endpoint 未对路由字面量做 re.escape

  • 位置:adapters/astrbot_adapter.py:224-230
  • 问题:把路由模板直接拼进正则,只替换了 {param} 占位符,字面量部分未转义。
  • 代码:
    # adapters/astrbot_adapter.py:225-227
    param_names = re.findall(r"\{([^{}]+)\}", pattern)
    regex = "^" + re.sub(r"\{([^{}]+)\}", r"([^/]+)", pattern) + "$"
    match = re.match(regex, endpoint)
    
  • 影响:实测当前 ROUTES 里没有任何 endpoint 含正则元字符(已用脚本枚举验证),所以现在是安全的。但这是一个只靠"恰好没人写带点号的路由"维持的隐性约束——将来出现 files/{name}.json 这类端点时,. 会变成任意字符匹配,产生静默的路由串台。
  • 修复建议:先 re.escape(pattern),再把被转义后的 \{name\} 换回捕获组;或改用逐段比较(split / 后按段匹配),既更快也不需要正则。

关于 flow 文件合并可行性的专项结论

文件 行数 性质 与其它 flow 的实质重复
engines/single_flow.py 455 真实生成引擎(provider 调用、字节校验、URI 布局) 无
engines/review_flow.py 451 真实审查引擎(策略校验、评分、阶段审查结果) 无(内部有自重复,见上)
engines/character_flow.py 145 声明式节点模板目录 + 遗留 node_key 别名映射 仅 gradual_node_templates() 约 15 行样板
engines/fast_character_flow.py 50 声明式节点模板目录 仅 fast_character_node_templates() 约 11 行样板
engines/quick_profile_flow.py 32 声明式节点模板目录(内联字面量) 无函数,纯字面量

三个模板目录的唯一共性是这段构造器样板:

# engines/fast_character_flow.py:40-50
return [
    {**step, "node_type": "generation", "status": "draft", "branch_name": "main",
     "metadata": {"template": "character_fast_v2", "quick_character_target": step["node_key"]}}
    for step in FAST_CHARACTER_STEPS
]
# engines/character_flow.py:131-145 —— 同形,但要额外剥离 stage_code、支持 per-step node_type 覆盖

建议不合并。 三者的 metadata 契约各不相同(character_gradual 要 stage_code + canonical_node_key 且支持 per-step node_type 覆盖;character_fast 要 quick_character_target;quick_profile 用的是 profile_draft/profile_preview 这类完全不同的 node_type),抽公共构造器需要引入配置参数把这些差异重新表达出来,代码量与理解成本都不会下降,反而把三种工作流的演进耦合在一起。这几个文件当前的形态——声明数据与业务逻辑分离、每种工作流一个独立目录——是合适的。

真正值得做的合并是本报告里的 onebot11/wechat 适配器(约 90% 重复) 与 review_flow 的内联告警副本,以及把 _json_from_text / 错误分类 / 大小预检这三段"图像链路已做对、其它链路缺失"的逻辑提取到 core/ 供全部 provider 共用。