super-code-assistant 3.3.6__py3-none-any.whl

features/find_relevant_memories.py

@@ -0,0 +1,376 @@
+"""Step 6 — 按相关性精选记忆并注入到当轮 user message。
+
+    用户每次提问 → 扫记忆目录 → side-query 让小模型从 manifest 里挑最多 3 条 →
+    把这些记忆的**摘要**（filename + frontmatter description，每条前面拼
+    Step 4 freshness warning）打包成一个 <system-reminder> 块，附在 user message
+    前面。需要细节时由模型用 Read 工具打开记忆文件，避免把全文注入历史重复计费。
+
+为什么走 side-query 而不是简单的关键字匹配：
+    关键字（如 "auth" 命中 feedback-handler.md）会过度触发；模型挑选有上下文判断，
+    准确率高得多。max_tokens=256 + JSON schema 让 side-query 成本可忽略。
+
+为什么注入摘要而不是全文：
+    全文注入（每条至多 8000 字符）会留在对话历史里每一轮重复计费，且误选的
+    "垃圾记忆"污染面大。摘要每条仅 ~30-50 token，注入块同时给出记忆目录路径，
+    模型需要细节时用 Read 按需读取。
+
+为什么加会话级节流：
+    side-query 的价值在于"话题开始时给一次方向"；同一会话 5 分钟内反复挑选
+    边际收益低。缓存未命中 + 节流窗口内 → 跳过 side-query（不写缓存，窗口过后
+    同话题仍可重新查询）。
+
+最小改动原则：
+    - 不修改 engine / context / run_query / permissions
+    - 仅暴露 build_relevant_memories_prefix(...) 一个供 tui/app.py 调用的入口
+    - 任何失败（IO / API / JSON 解析）静默降级返回空字符串
+"""
+from __future__ import annotations
+
+import json
+import time
+from difflib import SequenceMatcher
+from pathlib import Path
+from typing import Any
+
+from features.memory_age import memory_freshness_text
+from features.memory_scan import (
+    ENTRYPOINT_NAME,
+    MemoryHeader,
+    format_memory_manifest,
+    scan_memory_files,
+)
+
+# side-query 至多挑选这么多记忆。
+MAX_SELECTED = 3
+
+# 单次 side-query 的 token 上限。返回 JSON 很短（几个 filename），256 已足够冗余。
+SELECT_MAX_TOKENS = 256
+
+# 会话级节流：距上次 side-query 不足该秒数时直接跳过（不调 LLM、不写缓存）。
+# side-query 的价值在"话题开始时给一次方向"，5 分钟内连续提问围绕同一工作
+# 上下文，重复挑选边际收益低；话题漂移也等窗口过后再查。
+THROTTLE_SECONDS = 900
+
+# 触发 side-query 的最低记忆数：少于这个数量直接全注入（不调用 LLM 反而更便宜）。
+MIN_MEMORIES_FOR_SIDE_QUERY = 2
+
+# 性能优化：跳过明显不需要记忆的输入（方案 3）
+# - 太短：上下文不足，selector 也挑不准
+# - 单 token 输入：通常是 "ok / yes / 继续 / stop" 这种确认信号
+# 阈值松一点（10 字符）覆盖大多数确认词，不会误伤"修一下 bug"这种短指令
+_SKIP_LOOKUP_MIN_CHARS = 10
+_CONFIRM_WORDS = {
+    "yes", "no", "ok", "okay", "y", "n",
+    "continue", "stop", "go", "next", "done",
+    "继续", "停", "好", "好的", "嗯", "对",
+}
+
+# 性能优化：连续提问缓存（方案 1）
+# 同一会话内连续提问大概率围绕同一话题（"看 auth.py" → "它有 bug 吗" → "修一下"），
+# 上一次精选出的记忆完全可以复用。用 SequenceMatcher 算文本相似度，> 阈值即命中。
+_CACHE_SIMILARITY_THRESHOLD = 0.6
+
+
+# 模块级缓存。封进 dict 是为了让 reset 一次性清空、也便于将来切到 LRU。
+# memory_dir 不同 → 不复用（避免切项目时拿错记忆）。
+_lookup_cache: dict[str, Any] = {
+    "memory_dir": None,   # str | None：上次查询时的 memory_dir 绝对路径
+    "query": None,        # str | None：上次查询的 user_input
+    "prefix": "",         # str：上次产出的 prefix 文本
+}
+
+# 会话级节流状态：上次实际发起 side-query（LLM 调用）的单调时钟时间戳。
+# None = 本会话尚未查询过。用 time.monotonic 而非 time.time：不受系统时钟调整影响。
+_last_side_query_at: float | None = None
+
+
+def _throttle_active() -> bool:
+    """距上次 side-query 是否仍在节流窗口内。"""
+    if _last_side_query_at is None:
+        return False
+    return time.monotonic() - _last_side_query_at < THROTTLE_SECONDS
+
+
+def _mark_side_query() -> None:
+    """记录一次 side-query 发起时刻（无论成败，只要发了 LLM 调用就算）。"""
+    global _last_side_query_at
+    _last_side_query_at = time.monotonic()
+
+
+
+_SELECT_SYSTEM_PROMPT = (
+    "You are selecting memory files that will be useful to a coding assistant "
+    "processing the user's query. You will be given the user's query and a list of "
+    "available memory files with their filenames and one-line descriptions.\n\n"
+    f"Return a JSON object with key 'selected_memories' whose value is a list of "
+    f"filenames (at most {MAX_SELECTED}). Include only memories that are clearly "
+    "useful based on their name and description. If unsure, do NOT include — "
+    "be selective. If no memory is clearly useful, return an empty list."
+)
+
+
+# ---------------------------------------------------------------------------
+# 公共数据
+# ---------------------------------------------------------------------------
+
+def _select_with_side_query(query: str, memories: list[MemoryHeader],
+                            llm_client: Any, model: str) -> list[str]:
+    """向 LLM 发起一次轻量 side-query，让它从 manifest 中挑选最多 MAX_SELECTED 个 filename。
+
+    设计要点：
+        - 直接复用主对话同款 LLMClient.create（非流式），不引入新依赖
+        - prompt 里强制要求"JSON 对象 + key=selected_memories"，本端用 json.loads 解析
+        - 任何异常（API / 解析 / 类型不符）返回空列表，调用方据此降级
+        - 返回值会被白名单过滤：只保留 manifest 中真实存在的 filename，避免幻觉
+    """
+    manifest = format_memory_manifest(memories)
+    user_msg = (
+        f"User query:\n{query}\n\n"
+        f"Available memories:\n{manifest}\n\n"
+        "Respond ONLY with a JSON object like: "
+        "{\"selected_memories\": [\"file1.md\", \"file2.md\"]}\n"
+        "Do not wrap in markdown fences. Do not add any commentary."
+    )
+
+    try:
+        result = llm_client.create(
+            model=model,
+            max_tokens=SELECT_MAX_TOKENS,
+            messages=[{"role": "user", "content": user_msg}],
+            system=_SELECT_SYSTEM_PROMPT,
+        )
+    except Exception:
+        return []
+
+    # 提取 text 块
+    text = ""
+    content = getattr(result, "content", None)
+    if isinstance(content, list):
+        for block in content:
+            if isinstance(block, dict) and block.get("type") == "text":
+                text += str(block.get("text", ""))
+
+    if not text.strip():
+        return []
+
+    # 一些模型仍会偶尔加 ```json 包装，宽容处理
+    cleaned = text.strip()
+    if cleaned.startswith("```"):
+        # 去掉第一行 ```... 与最后一行 ```
+        lines = cleaned.splitlines()
+        if len(lines) >= 2:
+            cleaned = "\n".join(lines[1:-1])
+
+    try:
+        parsed = json.loads(cleaned)
+    except (json.JSONDecodeError, ValueError):
+        return []
+
+    if not isinstance(parsed, dict):
+        return []
+    raw = parsed.get("selected_memories")
+    if not isinstance(raw, list):
+        return []
+
+    # 白名单过滤 + 去重 + 截断到 MAX_SELECTED
+    valid_filenames = {m.filename for m in memories}
+    selected: list[str] = []
+    seen: set[str] = set()
+    for item in raw:
+        if not isinstance(item, str):
+            continue
+        if item in valid_filenames and item not in seen:
+            seen.add(item)
+            selected.append(item)
+            if len(selected) >= MAX_SELECTED:
+                break
+    return selected
+
+
+def find_relevant_memories(query: str, memory_dir: Path,
+                           llm_client: Any, model: str) -> list[MemoryHeader]:
+    """返回与 query 最相关的 MemoryHeader 列表（最多 MAX_SELECTED 条）。
+
+    流程：
+        1. scan_memory_files 拿全部 header（自动排除 MEMORY.md / logs/）
+        2. 记忆数 < MIN_MEMORIES_FOR_SIDE_QUERY → 全部返回，省一次 LLM 调用
+        3. 否则走 _select_with_side_query
+    任何失败静默返回空列表。
+    """
+    if not query.strip():
+        return []
+    try:
+        memories = scan_memory_files(memory_dir)
+    except Exception:
+        return []
+    if not memories:
+        return []
+    if len(memories) < MIN_MEMORIES_FOR_SIDE_QUERY:
+        return memories
+
+    # 记录 side-query 发起时刻：只要发了 LLM 调用就计入节流（成败与否）
+    _mark_side_query()
+    selected_names = _select_with_side_query(query, memories, llm_client, model)
+    if not selected_names:
+        return []
+    by_name = {m.filename: m for m in memories}
+    return [by_name[name] for name in selected_names if name in by_name]
+
+
+# ---------------------------------------------------------------------------
+# 注入文本构造
+# ---------------------------------------------------------------------------
+
+def build_relevant_memories_prefix(query: str, memory_dir: Path,
+                                   llm_client: Any, model: str) -> str:
+    """供 tui/app.py 调用的总入口。
+
+    返回值规范：
+        - 拿不到相关记忆 / 失败 / 短输入 / 节流窗口内 → 空字符串（调用方直接
+          `prefix + user_input`，空串自然降级为 user_input）
+        - 有相关记忆 → 一段 <system-reminder>...</system-reminder> 包裹的摘要文本，
+          末尾自带 "\n\n" 分隔符，便于直接拼到 user_input 前面
+
+    性能优化（不影响功能正确性）：
+        1. _should_skip_lookup：短输入 / 确认词直接跳过，零 LLM 调用
+        2. _cache_hit：连续提问同话题命中缓存，零 LLM 调用
+        3. 命中缓存时 freshness 也是缓存的旧值——可接受，新鲜度对几秒/几分钟内的
+           话题切换没有实际差异
+        4. _throttle_active：缓存未命中 + 距上次 side-query 不足 THROTTLE_SECONDS
+           → 直接返回空串。**刻意不写缓存**：避免把节流导致的空结果永久缓存，
+           窗口过后同话题提问仍能重新查询。
+    """
+    if _should_skip_lookup(query):
+        return ""
+
+    memory_dir_key = str(memory_dir)
+    cached = _cache_hit(query, memory_dir_key)
+    if cached is not None:
+        return cached
+
+    if _throttle_active():
+        return ""
+
+    prefix = _build_prefix_uncached(query, memory_dir, llm_client, model)
+    _cache_store(query, memory_dir_key, prefix)
+    return prefix
+
+
+def _build_prefix_uncached(query: str, memory_dir: Path,
+                           llm_client: Any, model: str) -> str:
+    """实际执行精选 + 拼装的内核。从 build_relevant_memories_prefix 拆出来，
+    便于缓存包装；签名 / 行为与原函数完全一致。"""
+    selected = find_relevant_memories(query, memory_dir, llm_client, model)
+    if not selected:
+        return ""
+
+    parts: list[str] = []
+    for h in selected:
+        # MEMORY.md 不应出现（scan_memory_files 已过滤），这里再保险一道
+        if h.filename == ENTRYPOINT_NAME:
+            continue
+        # Step 4：≥2 天的记忆带 freshness 警告；新鲜的不带（freshness_text 返回 "")
+        freshness = memory_freshness_text(h.mtime_ms)
+        freshness_block = f"<system-reminder>{freshness}</system-reminder>\n" if freshness else ""
+        # 注入摘要而非全文：description 来自 frontmatter（scan 时已解析），
+        # 缺描述时降级占位，细节由模型按需 Read 记忆文件
+        desc = h.description or "(no description — read the file for details)"
+        parts.append(f"## {h.filename}\n{freshness_block}{desc}")
+
+    if not parts:
+        return ""
+
+    body = "\n\n".join(parts)
+    return (
+        "<system-reminder>\n"
+        f"Relevant memories selected for this turn ({len(parts)}):\n"
+        "Summaries only — use the Read tool to open a memory file if you need details.\n"
+        f"Memory directory: {memory_dir}\n\n"
+        f"{body}\n"
+        "</system-reminder>\n\n"
+    )
+
+
+# ---------------------------------------------------------------------------
+# 性能优化辅助函数（方案 1 + 方案 3）
+# ---------------------------------------------------------------------------
+
+def _should_skip_lookup(query: str) -> bool:
+    """判断是否跳过 side-query。方案 3：避免对确认词 / 超短输入也起 LLM 往返。
+
+    规则（任一命中即跳过）：
+        - strip 后为空
+        - 总字符数 < _SKIP_LOOKUP_MIN_CHARS
+        - 全部是确认词 / 终止词（大小写不敏感）
+    """
+    s = query.strip()
+    if not s:
+        return True
+    if len(s) < _SKIP_LOOKUP_MIN_CHARS:
+        # 短输入：再检查一次是不是确认词，是的话明确跳过；不是的话也跳过
+        # （10 字符以下不足以触发有意义的 selector 判断）
+        return True
+    # 长度够但全是确认词（如 "yes please" / "OK 继续" 这种）也跳过
+    if s.lower() in _CONFIRM_WORDS:
+        return True
+    return False
+
+
+def _cache_hit(query: str, memory_dir_key: str) -> str | None:
+    """命中返回缓存的 prefix（可能是空字符串也算命中），未命中返回 None。
+
+    命中条件：memory_dir 完全相同 + 与上次 query 文本相似度 ≥ 阈值。
+    用 str | None 而不是 (bool, str)：None 明确表示"未命中"，与"命中但 prefix=空"区分。
+    """
+    if _lookup_cache["memory_dir"] != memory_dir_key:
+        return None
+    last_query = _lookup_cache["query"]
+    if not last_query:
+        return None
+    # SequenceMatcher 在短文本上计算很快（数十微秒级），不引入新依赖
+    similarity = SequenceMatcher(None, last_query, query).ratio()
+    if similarity >= _CACHE_SIMILARITY_THRESHOLD:
+        return _lookup_cache["prefix"]
+    return None
+
+
+def _cache_store(query: str, memory_dir_key: str, prefix: str) -> None:
+    """覆盖式写入；不做 LRU——TUI 是单用户单进程，一对游标足够。"""
+    _lookup_cache["memory_dir"] = memory_dir_key
+    _lookup_cache["query"] = query
+    _lookup_cache["prefix"] = prefix
+
+
+def will_need_side_query(query: str, memory_dir: Path) -> bool:
+    """纯本地判断：`build_relevant_memories_prefix()` 是否会触发 LLM side-query。
+
+    供 TUI 层在调用前缀构建函数前决定是否显示 "Searching memories…" spinner。
+    不复用内部函数的判断结果——刻意独立实现，避免未来任一端的逻辑变更造成
+    调用层与实现层的隐性耦合。性能：仅做 scan_memory_files（内存文件数通常
+    ≤100，~ms 级），无网络 IO。
+
+    与 build_relevant_memories_prefix 的判定顺序保持一致：
+    skip_lookup → cache_hit → throttle → scan。
+    """
+    if _should_skip_lookup(query):
+        return False
+    memory_dir_key = str(memory_dir)
+    if _cache_hit(query, memory_dir_key) is not None:
+        return False
+    if _throttle_active():
+        return False
+    try:
+        memories = scan_memory_files(memory_dir)
+    except Exception:
+        return False
+    return len(memories) >= MIN_MEMORIES_FOR_SIDE_QUERY
+
+
+def reset_relevant_memories_cache() -> None:
+    """供测试 / `/clear` 命令调用，清空缓存与节流状态。生产场景换记忆目录会自动
+    失效，一般不需要手动 reset。"""
+    global _last_side_query_at
+    _lookup_cache["memory_dir"] = None
+    _lookup_cache["query"] = None
+    _lookup_cache["prefix"] = ""
+    _last_side_query_at = None

features/git_ai.py

@@ -0,0 +1,256 @@
+"""Git AI 集成 — 在 AI 编辑文件前后调用 git ai checkpoint，
+用于统计 AI 代码占比（git-ai status）。
+
+工作原理：
+  编辑前：checkpoint agent-v1 type=human  → 把上次 AI 写入到现在的人工改动标记为 human
+  编辑后：checkpoint agent-v1 type=ai_agent → 把本次 AI 编辑标记为 AI
+
+只对写操作工具（Edit、Write、Bash）触发，读操作不触发。
+git-ai 未安装时静默跳过，不影响正常使用。
+
+⚠️ git-ai daemon 要求：checkpoint 数据只存在 daemon 内存中，不持久化。
+  如果 daemon 在 checkpoint 和 git commit 之间重启（电脑重启、进程崩溃等），
+  commit 将丢失归属数据（显示 untracked 100%）。因此 super-code 在启动时
+  和每次 checkpoint 前都会主动调用 git-ai bg start 确保 daemon 在运行。
+
+调试：设置环境变量 SUPER_CODE_DEBUG_GIT_AI=1 可将错误信息打印到 stderr。
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import shutil
+import subprocess
+from datetime import datetime, timezone
+from typing import Any
+
+_log = logging.getLogger(__name__)
+
+# git-ai 可执行文件路径，优先用 PATH 查找，找不到则用已知安装路径
+_GIT_AI_EXE: str | None = None
+_GIT_AI_CHECKED = False
+
+# 缓存的 git root（本进程生命周期内不变），用于确保 repo_working_dir 和
+# commit hook 看到的路径一致。Path.cwd() 可能是子目录，必须解析为 git root。
+_GIT_ROOT: str | None = None
+
+# daemon 是否已在本 session 中启动过（避免每次 checkpoint 都调 bg start）
+_DAEMON_ENSURED = False
+
+# 只对这些工具触发 checkpoint
+WRITE_TOOLS = {"Edit", "Write", "Bash"}
+
+# 设置 SUPER_CODE_DEBUG_GIT_AI=1 可启用 stderr 诊断输出
+_DEBUG = os.environ.get("SUPER_CODE_DEBUG_GIT_AI") == "1"
+
+
+def _get_exe() -> str | None:
+    """返回 git-ai 可执行文件路径，找不到返回 None。结果缓存，只检测一次。"""
+    global _GIT_AI_EXE, _GIT_AI_CHECKED
+    if _GIT_AI_CHECKED:
+        return _GIT_AI_EXE
+    _GIT_AI_CHECKED = True
+    # 先从 PATH 查找
+    found = shutil.which("git-ai")
+    if not found:
+        # fallback：已知 Windows 安装路径
+        fallback = os.path.expanduser(r"~\.git-ai\bin\git-ai.exe")
+        if os.path.isfile(fallback):
+            found = fallback
+    if found:
+        _log.debug("git-ai found at: %s", found)
+    else:
+        _log.debug("git-ai not found – checkpoints disabled")
+    _GIT_AI_EXE = found
+    return _GIT_AI_EXE
+
+
+def _git_root(cwd_hint: str) -> str | None:
+    """通过 git rev-parse --show-toplevel 获取 git 根目录。
+
+    repo_working_dir 必须等于 git root，否则 commit hook 无法匹配 checkpoint 数据
+    导致 git-ai stats 显示 untracked 100%。结果缓存，进程生命周期内只查询一次。
+    """
+    global _GIT_ROOT
+    if _GIT_ROOT is not None:
+        return _GIT_ROOT
+    try:
+        r = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            capture_output=True, text=True, timeout=5,
+            cwd=cwd_hint or None,
+        )
+        if r.returncode == 0 and r.stdout.strip():
+            _GIT_ROOT = r.stdout.strip()
+            return _GIT_ROOT
+    except Exception:
+        pass
+    # 回退：git 不可用时用传入的目录
+    _GIT_ROOT = cwd_hint
+    return _GIT_ROOT
+
+
+def _rel_path(file_path: str, git_root: str) -> str:
+    """将 file_path 转为相对 git root 的路径，与 git diff 输出格式一致。
+
+    Windows 上 os.path.abspath 保留输入大小写，而 git rev-parse 返回实际大小写，
+    必须用 normcase 做大小写不敏感比较，否则 LLM 传小写盘符会导致 startswith 失败。
+    """
+    try:
+        abs_path = os.path.abspath(file_path)
+        root = os.path.abspath(git_root)
+        if os.path.normcase(abs_path).startswith(os.path.normcase(root)):
+            return abs_path[len(root):].lstrip(os.sep).replace("\\", "/")
+    except Exception:
+        pass
+    return file_path.replace("\\", "/")
+
+
+def _ensure_daemon(exe: str, cwd: str | None = None) -> None:
+    """确保 git-ai 后台 daemon 在运行。
+
+    git-ai 的 checkpoint 数据只存在 daemon 内存中，daemon 重启后数据丢失。
+    如果 daemon 没运行，checkpoint 命令会自动启动一个，但在某些场景下
+    （如电脑刚重启后第一次调用）可能启动不够及时导致 checkpoint 丢失。
+    主动调用 bg start 可以确保 daemon 提前就绪。
+
+    每次调用会检查 daemon 状态，如果已在运行则 no-op。
+    """
+    global _DAEMON_ENSURED
+    if _DAEMON_ENSURED:
+        return
+    try:
+        subprocess.run(
+            [exe, "bg", "start"],
+            capture_output=True, timeout=5,
+            cwd=cwd,
+        )
+        _DAEMON_ENSURED = True
+    except Exception:
+        pass
+
+
+def ensure_daemon() -> None:
+    """供外部调用（如 app.py 启动时）主动启动 daemon。"""
+    exe = _get_exe()
+    if not exe:
+        return
+    _ensure_daemon(exe)
+
+
+def _run(payload: dict, exe: str, cwd: str | None = None) -> None:
+    """把 payload 序列化为 JSON 通过 stdin 传给 git-ai checkpoint agent-v1。
+
+    失败时记录日志，绝不抛出异常影响主流程。
+    设置 SUPER_CODE_DEBUG_GIT_AI=1 可将错误打印到 stderr。
+    """
+    try:
+        data = json.dumps(payload, ensure_ascii=False)
+        r = subprocess.run(
+            [exe, "ai", "checkpoint", "agent-v1", "--hook-input", "stdin"],
+            input=data.encode("utf-8"),
+            capture_output=True,
+            timeout=10,
+            cwd=cwd,
+        )
+        if r.returncode != 0:
+            err = r.stderr.decode("utf-8", errors="replace").strip()
+            _log.debug("git-ai checkpoint agent-v1 rc=%d stderr=%s", r.returncode, err)
+            if _DEBUG:
+                import sys
+                print(f"[git-ai] checkpoint failed (rc={r.returncode}): {err}", file=sys.stderr)
+    except subprocess.TimeoutExpired:
+        _log.debug("git-ai checkpoint agent-v1 timed out after 10s")
+        if _DEBUG:
+            import sys
+            print("[git-ai] checkpoint timed out after 10s", file=sys.stderr)
+    except Exception:
+        _log.debug("git-ai checkpoint agent-v1 error", exc_info=True)
+        if _DEBUG:
+            import sys, traceback
+            traceback.print_exc(file=sys.stderr)
+
+
+def before_edit(repo_dir: str, file_path: str) -> None:
+    """编辑文件前调用：把上次 AI 写入到现在的人工改动标记为 human。"""
+    exe = _get_exe()
+    if not exe:
+        return
+    root = _git_root(repo_dir)
+    if not root:
+        return
+    _ensure_daemon(exe, root)
+    _run({
+        "type": "human",
+        "repo_working_dir": root.replace("\\", "/"),
+        # 告知 git-ai 只 diff 这个文件，速度提升 50-100x
+        "will_edit_filepaths": [_rel_path(file_path, root)] if file_path else [],
+    }, exe, root)
+
+
+def after_edit(repo_dir: str, file_path: str,
+               messages: list[dict], model: str, session_id: str) -> None:
+    """编辑文件后调用：把本次 AI 编辑标记为 AI。
+
+    messages: engine._messages，会自动过滤掉 tool_result（git-ai 不接受）。
+    """
+    exe = _get_exe()
+    if not exe:
+        return
+    root = _git_root(repo_dir)
+    if not root:
+        return
+    _ensure_daemon(exe, root)
+    transcript = _build_transcript(messages)
+    _run({
+        "type": "ai_agent",
+        "repo_working_dir": root.replace("\\", "/"),
+        "transcript": transcript,
+        "agent_name": "super-code",
+        "model": model,
+        "conversation_id": session_id,
+        "edited_filepaths": [_rel_path(file_path, root)] if file_path else [],
+    }, exe, root)
+
+
+def _build_transcript(messages: list[dict]) -> dict[str, Any]:
+    """把 engine 消息历史转换为 git-ai 要求的 transcript 格式。
+
+    规则：
+    - role=user 且 content 是 list（tool_result）→ 跳过（git-ai 不接受）
+    - role=user 且 content 是 str → type=user
+    - role=assistant → type=assistant（取文本部分）
+    - content 里的 tool_use block → type=tool_use
+    """
+    out: list[dict[str, Any]] = []
+    ts = datetime.now(timezone.utc).isoformat()
+
+    for msg in messages:
+        role = msg.get("role", "")
+        content = msg.get("content", "")
+
+        if role == "user":
+            if isinstance(content, list):
+                # tool_result 消息，跳过
+                continue
+            out.append({"type": "user", "text": str(content), "timestamp": ts})
+
+        elif role == "assistant":
+            if isinstance(content, list):
+                for block in content:
+                    if not isinstance(block, dict):
+                        continue
+                    if block.get("type") == "text":
+                        out.append({"type": "assistant", "text": block.get("text", ""), "timestamp": ts})
+                    elif block.get("type") == "tool_use":
+                        out.append({
+                            "type": "tool_use",
+                            "name": block.get("name", ""),
+                            "input": block.get("input", {}),
+                            "timestamp": ts,
+                        })
+            else:
+                out.append({"type": "assistant", "text": str(content or ""), "timestamp": ts})
+
+    return {"messages": out}