codebee 0.1.63 → 0.1.64

package/CHANGELOG.md

@@ -6,6 +6,14 @@ README 元数据带回，供老版本在「发现新版本」时展示新版更
 
 ## 未发布
 
+- **禅道失败回写三连修（#27783 案）**：修复任务失败若是 CodeBee 自身崩溃（运行错误为内部异常形态，如 0.1.63 的 `_TRANSIENT` NameError），不再转派端负责人——只评论+群通知人工，评论注明「工具自身异常，不代表修复结论」；只评论（未配负责人/内部崩溃）时改为先取当前指派人再回写——禅道编辑接口缺 assignedTo 会清空指派，杜绝「指派给(空)」记录；负责人未配置的失败认领备注点名未转派原因。
+
+## v0.1.64（2026-09-24）
+
+- 禅道看图排查自动降级链：Bug 截图进排查与修复链，编排模型不会看图就自动换将并落标记，不再甩人工处理
+- 排查读图守卫：读不到图留人工判断，不盲判定论（#27754 案）
+- runner 瞬态错误热回退修复
+
 ## v0.1.63（2026-09-24）
 
 - 0.1.62 被并行发布占位（旧 HEAD，不含 runner 修复）；本版为完整版

package/README.md

@@ -21,9 +21,12 @@ Kimi Code、MiMo Code、Grok Build、Pi、DeepSeek Harness……），提供
 不会把你的任务内容交给任何第三方。
 
 
-### 最新版更新内容（v0.1.63）
+<!-- relnotes:start -->
+### 最新版更新内容（v0.1.64）
 
-- 修复评审「命令行太长」（垫片漏判）；修复步超时提至 2400 秒
+- 禅道 Bug 截图自动进排查/修复链：模型不会看图就自动换将，读不到留人工不盲判
+- runner 瞬态错误热回退修复
+<!-- relnotes:end -->
 
 
 ---

package/app/core/artifacts.py

@@ -0,0 +1,148 @@
+"""工作目录成品扫描：剪枝遍历 + 短 TTL 缓存 + 在飞合并。
+
+历史实现用 Path.rglob("*") 全量展开再逐文件 is_file()/stat() 过滤，几万文件的
+工作目录单次要 1.6~4 秒；而详情页/侧栏在任务运行中是轮询调用——每次轮询都是
+一次全仓扫描，UI 整体被拖卡（2026-09-24 详情页卡顿案）。这里改为 os.walk
+剪枝（跳过类目录整个不进入），并给重复轮询加 (workdir, t0, 任务状态) 键的短 TTL 缓存
+与在飞合并：并发同键只扫一次，后到者等结果。
+"""
+from __future__ import annotations
+
+import os
+import threading
+import time
+
+# 过滤语义与历史 rglob 版逐条对齐：
+# - SKIP_DIRS：任意路径段（含文件名本身）命中即剔除；
+# - BUILD_DIRS：仅祖先目录命中即剔除（文件名叫 dist 不受影响）；
+# - 点开头：仅祖先目录算「隐藏」（根下的 .gitignore 这类隐藏文件仍是候选）。
+SKIP_DIRS = {".git", "node_modules", "__pycache__", ".venv", "venv", ".idea", ".vscode"}
+
+# 构建产物/依赖缓存目录：里面的文件是工具链再生成的，不是任务成品
+BUILD_DIRS = {
+    "target", "build", "dist", "out", "bin", "obj",           # 通用构建输出
+    "surefire", "failsafe-reports", "test-output", "reports",  # 测试/报告输出
+    ".next", ".nuxt", ".output", ".gradle", ".gradle-home",    # 前端/Gradle
+    "__MACOSX",
+}
+
+# CLI 自身的历史/评审中间件不属于用户成果。它们通常落在工作目录根部，
+# 只按隐藏目录过滤会漏掉 Aider 的 .aider.* 与流程生成的 *_review.json。
+_PROCESS_ARTIFACT_NAMES = {
+    ".aider.chat.history.md", ".aider.input.history", ".aider.input.history.md",
+    ".aider.tags.cache.v4", ".aider.tags.cache.v3", ".aider.conf.yml",
+}
+_PROCESS_ARTIFACT_SUFFIXES = ("_review.json", ".review.json")
+_PROCESS_ARTIFACT_PREFIXES = ("tutti_prompt_", "_tutti_prompt_")
+
+SCAN_CAP = 800             # 防超大目录拖垮接口；截断后再排序取最新
+CACHE_TTL_RUNNING = 2.0    # 任务在跑：轮询热，新鲜期要短
+CACHE_TTL_IDLE = 10.0      # 终态任务：详情反复开关/检查器同刷，可稍长
+_CACHE_KEEP = 128          # 缓存条目上限（按时间淘汰最旧）
+
+_now = time.monotonic      # 模块级别名，测试可替换时钟
+
+_LOCK = threading.Lock()
+_CACHE = {}     # (root, t0, running) -> (时间戳, files)；files 恒为全量候选
+_INFLIGHT = {}  # (root, t0, running) -> Lock；同键并发只跑一次扫描
+
+
+def _is_process_artifact(rel_name):
+    """判断工作目录文件是否为 CLI/评审过程产物，而非可交付成果。"""
+    name = str(rel_name or "").replace("\\", "/")
+    base = name.rsplit("/", 1)[-1].lower()
+    if base in _PROCESS_ARTIFACT_NAMES:
+        return True
+    if base.startswith(".") and base.startswith(".aider"):
+        return True
+    if base.endswith(_PROCESS_ARTIFACT_SUFFIXES):
+        return True
+    if base.startswith(_PROCESS_ARTIFACT_PREFIXES):
+        return True
+    return False
+
+
+def _walk_files(root, t0):
+    """剪枝遍历：跳过类目录整个不进入；返回 mtime>=t0 的候选（无序）。"""
+    files = []
+    for dp, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames
+                       if d not in SKIP_DIRS and d not in BUILD_DIRS
+                       and not d.startswith(".")]
+        done = False
+        for name in filenames:
+            if name in SKIP_DIRS:   # 历史语义：文件名本身命中也剔除
+                continue
+            try:
+                st = os.stat(os.path.join(dp, name))
+            except OSError:
+                continue
+            if st.st_mtime < t0:
+                continue
+            rel_dir = os.path.relpath(dp, root)
+            rel = name if rel_dir == "." else \
+                rel_dir.replace("\\", "/") + "/" + name
+            if _is_process_artifact(rel):
+                continue
+            files.append({"name": rel,
+                          "size": st.st_size, "mtime": int(st.st_mtime)})
+            if len(files) >= SCAN_CAP:
+                done = True
+                break
+        if done:
+            break
+    return files
+
+
+def _cache_get(key, ttl):
+    with _LOCK:
+        ent = _CACHE.get(key)
+        if ent and _now() - ent[0] < ttl:
+            return ent[1]
+    return None
+
+
+def _cache_put(key, files):
+    with _LOCK:
+        _CACHE[key] = (_now(), files)
+        while len(_CACHE) > _CACHE_KEEP:
+            _CACHE.pop(min(_CACHE, key=lambda k: _CACHE[k][0]), None)
+
+
+def _inflight_lock(key):
+    with _LOCK:
+        lock = _INFLIGHT.get(key)
+        if lock is None:
+            lock = _INFLIGHT[key] = threading.Lock()
+        return lock
+
+
+def scan(root, t0, limit=200, running=False, cache=False):
+    """扫工作目录成品，按 mtime 新→旧取前 limit 条，返回文件字典列表。
+
+    cache=True 时同键 (root, t0, running) 在 TTL 内直接复用上次结果，运行中
+    任务用短 TTL；无论是否缓存，同键在飞扫描都会合并——轮询方只会等一次扫描。
+    """
+    # 运行态和终态必须分开缓存：任务刚结束时不能沿用运行中缓存里的旧
+    # 文件列表，否则终态较长 TTL 会把最后写入的产物遮住。
+    key = (str(root), t0, bool(running))
+    ttl = CACHE_TTL_RUNNING if running else CACHE_TTL_IDLE
+    if cache:
+        hit = _cache_get(key, ttl)
+        if hit is not None:
+            return hit[:limit]
+    klock = _inflight_lock(key)
+    try:
+        with klock:
+            if cache:   # 排到锁时他人可能已扫完入缓存
+                hit = _cache_get(key, ttl)
+                if hit is not None:
+                    return hit[:limit]
+            files = sorted(_walk_files(root, t0), key=lambda f: -f["mtime"])
+            if cache:
+                _cache_put(key, files)
+    finally:
+        with _LOCK:
+            if _INFLIGHT.get(key) is klock:
+                _INFLIGHT.pop(key, None)
+    return files[:limit]

package/app/core/bookmeta.py

@@ -4,12 +4,13 @@
 用户在详情页「成果」分区点按钮触发（不做自动生成），后台线程调编排者模型
 提炼 大纲 + 故事圣经 + 已有章节 的精华，按平台表单字段归一化后存任务
 book_meta 字段，同时在工作目录落一份 Markdown 归档。降级链与大纲一致：
-编排者 API → 作者 CLI → 模板兜底（模板只做搬运归纳，字段留待用户补）。
+编排者 API → 作者 CLI → 模板兜底（模板只做搬运归纳，必填字段仍保证可建书）。
 """
 from __future__ import annotations
 
-import os
-import time
+import os
+import re
+import time
 from pathlib import Path
 
 PLATFORMS = {
@@ -25,7 +26,8 @@ def template_only():
     """只走模板兜底（跳过编排者/作者 CLI）：env TUTTI_BOOKMETA_TEMPLATE_ONLY=1。
 
     离线环境、不想为开书资料再花一次模型调用、以及测试要确定性输出时使用；
-    产出仍是结构完整的字段，只是书名/简介直接取大纲与目标，其余留「待补充」。"""
+    产出仍是结构完整的字段，书名/简介直接取大纲与目标，平台必填字段由生成阶段
+    的官方目录兜底补齐。"""
     return str(os.environ.get("TUTTI_BOOKMETA_TEMPLATE_ONLY") or "").strip() in ("1", "true", "yes")
 
 
@@ -376,7 +378,7 @@ def _material_text(task, outline):
     return material
 
 
-def _fill_tag_gaps(task, platform, meta, outline):
+def _fill_tag_gaps(task, platform, meta, outline):
     """llm 归一化后仍为空的标签组：用素材词面扫描补一轮（命中多少算多少）。
 
     模型偶尔整组漏给（实测 codex-cli 只填了内容标签前两组）；空着用户就得
@@ -400,7 +402,137 @@ def _fill_tag_gaps(task, platform, meta, outline):
     for key, table, limit in pairs:
         if not meta.get(key):
             meta[key] = _scan_table(material, table, limit)
-    return meta
+    return meta
+
+
+def _material_names(material):
+    """从圣经/大纲/章节里提取明确标注的人物名。
+
+    只接受带人物语义的短语（如“女主：阿禾”或“男主叫陆沉”），避免把
+    普通句子里的名词误当成主角。返回顺序去重后的最多两个名字。
+    """
+    text = str(material or "")
+    out = []
+    patterns = (
+        r"(?:主角|主人公|男主(?:角)?|女主(?:角)?|男一|女一|姓名|名字)"
+        r"\s*(?:是|叫|为|：|:)\s*([\u4e00-\u9fffA-Za-z][\u4e00-\u9fffA-Za-z·]{1,7})",
+        r"人物\s*[：:]\s*([^\n。；;]{2,40})",
+    )
+    for pat in patterns:
+        for m in re.finditer(pat, text):
+            raw = m.group(1)
+            chunks = re.split(r"[、,，/和及与]|\s+", raw)
+            for chunk in chunks:
+                name = re.sub(r"[^\u4e00-\u9fffA-Za-z·]", "", chunk)
+                if 2 <= len(name) <= 8 and name not in out:
+                    out.append(name[:5])
+                if len(out) >= 2:
+                    return out
+    return out
+
+
+def _pick_option(material, table, keywords=()):
+    """从官方选项表中按素材命中词选择一个，完全命中不到时用首项。"""
+    text = str(material or "")
+    for item in table:
+        if len(item) >= 2 and item in text:
+            return item
+    for key, item in keywords:
+        if key and key in text and item in table:
+            return item
+    return table[0] if table else ""
+
+
+def _has_value(value):
+    """判断建书字段是否真正有值（兼容列表和历史占位文本）。"""
+    placeholders = {"待补充", "（待补充）", "(待补充)"}
+    if isinstance(value, list):
+        return any((text := str(x or "").strip()) and text not in placeholders
+                   for x in value)
+    text = str(value or "").strip()
+    return bool(text) and text not in placeholders
+
+
+def _fill_required_fields(task, platform, meta, outline, material):
+    """生成阶段的必填字段闸门。
+
+    ``_norm`` 仍保持“表外值清空”的纯校验语义，供旧数据修复和单测使用；
+    这里仅在真正交付作品信息前补齐平台建书表单的必填项，避免 UI 展示一整
+    屏“待补充”而无法直接复制建书。所有分类/标签仍来自官方目录。
+    """
+    from . import bookmeta_catalog as cat
+
+    material = str(material or "")
+    names = _material_names(material)
+    female_words = ("女频", "女生", "女主", "言情", "古言", "恋爱")
+    female = any(x in ((task.get("goal") or "") + material) for x in female_words)
+    defaults = ("沈知微", "顾砚川", "林知夏") if female else ("陆沉", "苏晚", "程野")
+    if not _has_value(meta.get("protagonist_1")):
+        meta["protagonist_1"] = names[0] if names else defaults[0]
+    if not _has_value(meta.get("protagonist_2")):
+        candidate = names[1] if len(names) > 1 else defaults[1]
+        if candidate == meta["protagonist_1"]:
+            candidate = next((name for name in defaults if name != meta["protagonist_1"]), defaults[2])
+        meta["protagonist_2"] = candidate
+
+    if platform == "fanqie":
+        reader = meta.get("target_reader") or ("女频" if female else "男频")
+        if reader not in ("男频", "女频"):
+            reader = "女频" if female else "男频"
+        meta["target_reader"] = reader
+        cats, theme, role, plot = _fq_tables(reader)
+        c_plot, c_emo, c_char, c_world = _fq_content_tables()
+        if meta.get("category") not in cats:
+            meta["category"] = _pick_option(
+                material, cats,
+                (("戍边", "古风世情"), ("边关", "古风世情"),
+                 ("军", "抗战谍战"), ("悬疑", "女频悬疑" if female else "悬疑脑洞"),
+                 ("种田", "种田"), ("都市", "都市脑洞")))
+        groups = (("tags_theme", theme, 2), ("tags_role", role, 2),
+                  ("tags_plot", plot, 2), ("content_plot", c_plot, 4),
+                  ("content_emotion", c_emo, 2), ("content_character", c_char, 4),
+                  ("content_world", c_world, 1))
+    else:
+        reader = meta.get("target_reader") or ("女生" if female else "男生")
+        if reader not in ("男生", "女生"):
+            reader = "女生" if female else "男生"
+        meta["target_reader"] = reader
+        channel = cat.QIMAO_CATS.get(reader) or cat.QIMAO_CATS["男生"]
+        main = meta.get("category_main")
+        if main not in channel:
+            main = _pick_option(
+                material, list(channel),
+                (("戍边", "古代言情"), ("边关", "古代言情"),
+                 ("古代", "古代言情"), ("军事", "军事"),
+                 ("军", "军事"), ("都市", "都市"),
+                 ("玄幻", "玄幻奇幻"), ("悬疑", "奇闻异事")))
+            meta["category_main"] = main
+        subs = channel.get(main) or []
+        sub = meta.get("category_sub")
+        if sub not in subs:
+            located = cat.qimao_locate_sub(sub)
+            if located:
+                reader, main = located
+                meta["target_reader"] = reader
+                meta["category_main"] = main
+                subs = cat.QIMAO_CATS[reader][main]
+            else:
+                sub = ""
+        if sub not in subs:
+            meta["category_sub"] = _pick_option(material, subs)
+        groups = (("tags_style", cat.QIMAO_TAG_GROUPS["风格"], 3),
+                  ("tags_role", cat.QIMAO_TAG_GROUPS["角色"], 3),
+                  ("tags_plot", cat.QIMAO_TAG_GROUPS["情节"], 3),
+                  ("tags_bg", cat.QIMAO_TAG_GROUPS["背景"], 3))
+    for key, table, limit in groups:
+        values = meta.get(key)
+        if not isinstance(values, list):
+            values = []
+        values = [str(v).strip() for v in values if str(v or "").strip() in table]
+        if not values:
+            values = [_pick_option(material, table)]
+        meta[key] = values[:limit]
+    return meta
 
 
 def store_read_bible(task):
@@ -455,11 +587,12 @@ def make_book_meta(task, platform, author_agent=None, log_path=None):
         planner._log_usage("bookmeta", "bookmeta", task, res, model=model,
                            provider=prov.get("name", prov.get("id", "")),
                            provider_id=prov.get("id", ""))
-        if res["ok"]:
-            meta = _norm(runner.extract_json(res.get("text") or ""), platform, goal)
-            if meta:
-                return _fill_tag_gaps(task, platform, meta, outline), \
-                    "编排者(%s · %s)" % (prov.get("name", prov["id"]), model)
+        if res["ok"]:
+            meta = _norm(runner.extract_json(res.get("text") or ""), platform, goal)
+            if meta:
+                meta = _fill_tag_gaps(task, platform, meta, outline)
+                return _fill_required_fields(task, platform, meta, outline, material), \
+                    "编排者(%s · %s)" % (prov.get("name", prov["id"]), model)
         orch_err = str(res.get("error") or "返回内容无法解析为作品信息")[:200]
 
     if author_agent and author_agent.get("mode") == "real" and not template_only():
@@ -467,14 +600,16 @@ def make_book_meta(task, platform, author_agent=None, log_path=None):
                                workdir=task.get("workdir"), readonly=True,
                                timeout=BOOKMETA_TIMEOUT, log_path=log_path)
         planner._log_usage("bookmeta", "bookmeta", task, res, agent=author_agent)
-        if res["ok"]:
-            meta = _norm(runner.extract_json(res.get("text") or ""), platform, goal)
-            if meta:
-                return _fill_tag_gaps(task, platform, meta, outline), "llm(%s)" % author_agent["id"]
+        if res["ok"]:
+            meta = _norm(runner.extract_json(res.get("text") or ""), platform, goal)
+            if meta:
+                meta = _fill_tag_gaps(task, platform, meta, outline)
+                return _fill_required_fields(task, platform, meta, outline, material), "llm(%s)" % author_agent["id"]
         orch_err = orch_err or str(res.get("error") or "")[:200]
 
-    meta = _template_meta(task, platform, outline)
-    meta["source"] = ("模板兜底（编排者不可用：%s）" % orch_err) if orch_err else "模板兜底"
+    meta = _template_meta(task, platform, outline)
+    meta = _fill_required_fields(task, platform, meta, outline, material)
+    meta["source"] = ("模板兜底（编排者不可用：%s）" % orch_err) if orch_err else "模板兜底"
     return meta, meta["source"]
 
 
@@ -528,7 +663,7 @@ def generate_async(task_id, platform, author_agent=None):
     store.set_book_meta(task_id, platform, entry)
 
 
-def recover_orphans():
+def recover_orphans():
     """启动收尸：后台生成线程随进程重启死掉后，落盘的 running 无人写终态——
     前端永远「生成中」（按钮禁用）+ 接口幂等拒绝，卡死不可自愈。启动时把
     遗留 running 统一改判 failed，交还「重试」按钮。返回改判条数。"""
@@ -542,4 +677,65 @@ def recover_orphans():
                     "error": "生成随服务重启中断，请点重试",
                     "at": time.strftime("%Y-%m-%d %H:%M:%S")})
                 n += 1
-    return n
+    return n
+
+
+def repair_existing():
+    """补齐历史已生成记录中的必填字段。
+
+    旧版本允许分类/主角为空并把结果标成 done；只要字段缺失就按当前官方
+    目录和已有素材补一次，已有非空字段保持不变。返回修复条数，供启动日志
+    和升级诊断使用。
+    """
+    from . import store
+    repaired = 0
+    for task in store.list_tasks(limit=10 ** 9):
+        book_meta = task.get("book_meta") or {}
+        for platform in PLATFORMS:
+            entry = book_meta.get(platform) or {}
+            if entry.get("status") != "done" or not isinstance(entry.get("data"), dict):
+                continue
+            data = dict(entry["data"])
+            if platform == "fanqie":
+                reader = data.get("target_reader")
+                cats, _, _, _ = _fq_tables(reader if reader in ("男频", "女频") else "男频")
+                required_ok = (
+                    data.get("category") in cats
+                    and all(_has_value(data.get(key)) for key in (
+                        "tags_theme", "tags_role", "tags_plot", "content_plot",
+                        "content_emotion", "content_character", "content_world"))
+                    and _has_value(data.get("protagonist_1"))
+                    and _has_value(data.get("protagonist_2")))
+            else:
+                from . import bookmeta_catalog as cat
+                reader = data.get("target_reader")
+                channel = cat.QIMAO_CATS.get(reader) or {}
+                main = data.get("category_main")
+                required_ok = (
+                    main in channel
+                    and data.get("category_sub") in (channel.get(main) or [])
+                    and all(_has_value(data.get(key)) for key in (
+                        "tags_style", "tags_role", "tags_plot", "tags_bg"))
+                    and _has_value(data.get("protagonist_1"))
+                    and _has_value(data.get("protagonist_2")))
+            if required_ok:
+                continue
+            try:
+                material, outline = _collect_material(task)
+                fixed = _fill_required_fields(task, platform, data, outline, material)
+                if fixed == entry["data"]:
+                    continue
+                payload = dict(entry)
+                payload["data"] = fixed
+                payload["source"] = (str(entry.get("source") or "") + "；已补齐必填字段").lstrip("；")
+                store.set_book_meta(task["id"], platform, payload)
+                try:
+                    fp = Path(task.get("workdir") or "") / PLATFORMS[platform]["file"]
+                    if fp.parent.is_dir():
+                        fp.write_text(render_markdown(task, platform, fixed), encoding="utf-8")
+                except OSError:
+                    pass
+                repaired += 1
+            except Exception:
+                continue
+    return repaired

package/app/core/modelhub.py

@@ -2037,6 +2037,35 @@ def _model_image_in(prov, model):
     return False
 
 
+def vision_candidates(prefer_provider_id="", prefer_model=""):
+    """全库搜「能看图」的候选模型，供图类调用自动降级（编排模型不支持看图时
+    自己换将，不甩人工）。返回有序 [(prov, model_name, inferred)]：
+    声明 image_in 的在先；仅名字推断（_auto_image_in）的在后（inferred=True，
+    调用方实测成功后应 set_model_caps 落标记）。编排者供应商排最前，
+    编排模型本身若可看图排整个列表第一。"""
+    out, seen = [], set()
+    provs = [p for p in providers()
+             if isinstance(p, dict) and p.get("enabled", True) and p.get("api_key")]
+    provs.sort(key=lambda p: 0 if p.get("id") == prefer_provider_id else 1)
+    for p in provs:
+        for m in _enabled_models(p):
+            name = str(m.get("name") or "")
+            if not name or (p.get("id"), name) in seen:
+                continue
+            if bool(m.get("image_in")):
+                inferred = False
+            elif _auto_image_in(name):
+                inferred = True
+            else:
+                continue
+            seen.add((p.get("id"), name))
+            out.append((p, name, inferred))
+    if prefer_model:
+        out.sort(key=lambda x: 0 if (x[0].get("id") == prefer_provider_id
+                                     and x[1] == prefer_model) else 1)
+    return out
+
+
 def bind_agent(agent, difficulty="default", task_type="", role=""):
     """按绑定生成应用了供应商/模型覆盖的 agent 副本；无绑定时原样返回。
 
@@ -3096,32 +3125,68 @@ def resolve_orchestrator():
     return prov, model
 
 
-def _chat_cache_path(provider_id, model_name, prompt, max_tokens, reasoning_effort=""):
-    """§07 T2.2：精确匹配响应缓存的落盘路径（只缓存 ok 的幂等调用）。"""
+def _chat_user_content(proto, prompt, images):
+    """images=[(mime, b64)] 时构造多模态 user content；无图返回原样文本。
+
+    openai/anthropic 的 content 变数组块，google 走 parts；形状与
+    builtin_agent 的对话消息一致（图只进 user 消息）。"""
+    if not images:
+        return [{"text": prompt}] if proto == "google" else prompt
+    if proto == "google":
+        parts = [{"text": prompt}]
+        for mime, b64 in images:
+            parts.append({"inline_data": {"mime_type": mime, "data": b64}})
+        return parts
+    blocks = [{"type": "text", "text": prompt}]
+    for mime, b64 in images:
+        if proto == "anthropic":
+            blocks.append({"type": "image",
+                           "source": {"type": "base64", "media_type": mime,
+                                      "data": b64}})
+        else:
+            blocks.append({"type": "image_url",
+                           "image_url": {"url": "data:%s;base64,%s" % (mime, b64)}})
+    return blocks
+
+
+def _chat_cache_path(provider_id, model_name, prompt, max_tokens, reasoning_effort="",
+                     images=None):
+    """§07 T2.2：精确匹配响应缓存的落盘路径（只缓存 ok 的幂等调用）。
+    images 参与键（同 prompt 不同图的响应可能不同）。"""
     import hashlib as _h
+    img_sig = ""
+    if images:
+        try:
+            img_sig = _h.sha256("|".join("%s|%s" % (m, b) for m, b in images)
+                                .encode("utf-8")).hexdigest()[:16]
+        except Exception:
+            img_sig = "err"
     key = "|".join([str(provider_id), str(model_name), str(max_tokens),
-                    str(reasoning_effort or ""), str(prompt)])
+                    str(reasoning_effort or ""), str(prompt), img_sig])
     name = _h.sha256(key.encode("utf-8")).hexdigest()[:24]
     return paths.DATA_DIR / "chat_cache" / (name + ".json")
 
 
 def chat(provider_id, model_name, prompt, max_tokens=2048, timeout=120, cache_ttl=0,
-         on_delta=None, reasoning_effort=""):
+         on_delta=None, reasoning_effort="", images=None):
     """直连供应商 API 做一次对话（编排者规划 / 连通性测试）。
 
     支持 anthropic / openai / google 三种协议；复用 SSRF 防护。
+    images=[(mime, b64)] 时随 user 消息传图（三协议形状见 _chat_user_content；
+    图只在非流式路径验证过，流式 on_delta 与图并用未验证）。
     返回 {ok, text, tokens, usage, error}；usage 为细分 {input, output, cached, reasoning, total}。
-    cache_ttl>0 启用精确匹配响应缓存（key=供应商+模型+prompt+max_tokens，只缓存
-    ok 结果）——仅限幂等调用（连通性测试等）；创作类调用不要开，否则同一 prompt
+    cache_ttl>0 启用精确匹配响应缓存（key=供应商+模型+prompt+max_tokens+图签名，
+    只缓存 ok 结果）——仅限幂等调用（连通性测试等）；创作类调用不要开，否则同一 prompt
     的二次请求会屏蔽模型的新输出。
     on_delta 给定时走 SSE 流式：每收到一段增量文本回调一次。编排者直连调用
     不经 run_process、原本生成全程日志只有一行标题，靠它把「正在吐字」实时
     写进步骤日志（planner._log_streamer 节流落盘）。
     """
+    images = [(str(m), str(b)) for m, b in (images or [])] or None
     if cache_ttl > 0:
         try:
             cache_path = _chat_cache_path(provider_id, model_name, prompt, max_tokens,
-                                          reasoning_effort)
+                                          reasoning_effort, images)
             if cache_path.is_file():
                 age = time.time() - cache_path.stat().st_mtime
                 if age <= cache_ttl:
@@ -3157,7 +3222,7 @@ def chat(provider_id, model_name, prompt, max_tokens=2048, timeout=120, cache_tt
             else:
                 url = base + "/v1beta/models/%s:generateContent" % model_name
             headers = {"x-goog-api-key": use_key}
-            body = {"contents": [{"parts": [{"text": prompt}]}],
+            body = {"contents": [{"parts": _chat_user_content(proto, prompt, images)}],
                     "generationConfig": {"maxOutputTokens": max_tokens}}
         else:
             path = "/messages" if proto == "anthropic" else "/chat/completions"
@@ -3167,7 +3232,8 @@ def chat(provider_id, model_name, prompt, max_tokens=2048, timeout=120, cache_tt
             else:
                 headers = {"Authorization": "Bearer " + use_key}
             body = {"model": model_name, "max_tokens": max_tokens,
-                    "messages": [{"role": "user", "content": prompt}]}
+                    "messages": [{"role": "user",
+                                  "content": _chat_user_content(proto, prompt, images)}]}
             effort = str(reasoning_effort or "").strip().lower()
             if proto == "openai" and effort in ("low", "medium", "high"):
                 body["reasoning_effort"] = effort
@@ -3255,7 +3321,7 @@ def chat(provider_id, model_name, prompt, max_tokens=2048, timeout=120, cache_tt
     if cache_ttl > 0:
         try:
             cache_path = _chat_cache_path(provider_id, model_name, prompt, max_tokens,
-                                          reasoning_effort)
+                                          reasoning_effort, images)
             cache_path.parent.mkdir(parents=True, exist_ok=True)
             tmp = cache_path.with_suffix(".tmp")
             import json as _json