codebee 0.1.6 → 0.1.8

package/app/core/store.py

@@ -67,14 +67,24 @@ def create_task(payload):
     type 必须是 flows.py 里的有效流程 ID；流程参数（引擎/维度/阈值/轮数/产出
     文件/提示词覆盖）在创建时固化到任务上，之后修改流程定义不影响已建任务。
     """
+    if not isinstance(payload, dict):
+        raise ValueError("任务参数必须是 JSON 对象")
+
+    def _text(value, field):
+        if value is None:
+            return ""
+        if not isinstance(value, str):
+            raise ValueError("%s 必须是文本" % field)
+        return value.strip()
+
     from . import flows as flows_mod
     flow = flows_mod.get_flow(payload.get("type"))
     if flow is None:
         raise ValueError("未知任务类型：%s（可选：%s）"
                          % (payload.get("type"), "、".join(f["id"] for f in flows_mod.list_flows())))
-    title = (payload.get("title") or "").strip()
-    goal = (payload.get("goal") or "").strip()
-    workdir = (payload.get("workdir") or "").strip()
+    title = _text(payload.get("title"), "title")
+    goal = _text(payload.get("goal"), "goal")
+    workdir = _text(payload.get("workdir"), "workdir")
     if not goal:
         raise ValueError("目标描述不能为空")
     title = title or goal.splitlines()[0][:30]  # 标题可省略，自动取目标首行
@@ -102,7 +112,7 @@ def create_task(payload):
     task = {
         "id": _new_id("t"), "type": flow["id"], "engine": flow["engine"],
         "title": title, "goal": goal,
-        "context": (payload.get("context") or "").strip(),
+        "context": _text(payload.get("context"), "context"),
         "workdir": str(wd),
         "mode": mode,
         "difficulty": difficulty,
@@ -113,7 +123,7 @@ def create_task(payload):
     }
     # 代码版本：仅当引用合法才固化（流水线执行前据此检出任务分支）
     from . import gitmod
-    git_rev = (payload.get("git_rev") or "").strip()
+    git_rev = _text(payload.get("git_rev"), "git_rev")
     if git_rev:
         # 前端下拉值带 kind 前缀（branch:main / tag:v1 / commit:abc），此处归一为纯 rev；
         # git 分支/标签名本身允许含冒号（罕见），前缀剥离只认这三种已知 kind
@@ -122,11 +132,12 @@ def create_task(payload):
             raise ValueError("非法的代码版本引用：%s" % git_rev[:40])
         task["git_rev"] = git_rev
     if flow["engine"] == "code":
-        task["verify_command"] = (payload.get("verify_command") or "").strip()
+        task["verify_command"] = _text(payload.get("verify_command"), "verify_command")
     elif flow["engine"] == "direct":
         pass  # 直连任务：无验证命令也无评审参数，目标+附件即全部输入
     else:
-        ms = (payload.get("manuscript") or flow.get("manuscript") or "manuscript.md").strip()
+        ms = _text(payload.get("manuscript") or flow.get("manuscript") or "manuscript.md",
+                   "manuscript")
         ms = re.sub(r"[\\/]", "_", ms)  # 只允许工作目录内的相对文件名
         ms = re.sub(r"\.{2,}", "_", ms).lstrip(".")  # 顺带清掉残留的 ..
         task["manuscript"] = ms
@@ -134,6 +145,11 @@ def create_task(payload):
             task["rounds"] = max(1, min(5, int(payload.get("rounds") or flow.get("rounds") or 2)))
         except Exception:
             task["rounds"] = 2
+        try:
+            # Best-of-N 赛马候选数（非连载单稿；连载走 serial.variants 的同章赛马）
+            task["best_of"] = max(1, min(3, int(payload.get("best_of") or flow.get("best_of") or 1)))
+        except Exception:
+            task["best_of"] = 1
         try:
             task["threshold"] = max(1.0, min(10.0,
                                              float(payload.get("threshold") or flow.get("threshold") or 7.0)))
@@ -147,8 +163,18 @@ def create_task(payload):
         for key in ("draft_prompt", "critique_prompt"):  # 自定义流程的提示词覆盖
             if flow.get(key):
                 task[key] = flow[key]
-        # 连载模式：逐章起草/评审/修订（任务级 serial 覆盖流程默认）
-        serial = payload.get("serial") if isinstance(payload.get("serial"), dict) else flow.get("serial")
+        # 连载模式：逐章起草/评审/修订（任务级 serial 覆盖流程默认）。
+        # payload 中显式传 null 表示关闭流程默认连载；字段缺失才沿用流程默认，
+        # 这样前端把章节清空时不会被 serial_novel 的默认值悄悄重新打开。
+        serial_unset = object()
+        serial_value = payload.get("serial", serial_unset)
+        if serial_value is None or (isinstance(serial_value, dict) and
+                                    serial_value.get("enabled") is False):
+            serial = None
+        elif isinstance(serial_value, dict):
+            serial = serial_value
+        else:
+            serial = flow.get("serial")
         if isinstance(serial, dict) and serial.get("chapters"):
             try:
                 s = {
@@ -182,6 +208,15 @@ def create_task(payload):
     critics = payload.get("critics")
     if isinstance(critics, list) and critics:
         task["critics"] = [str(c) for c in critics]
+    # 初始故事圣经必须在任务入队前落盘，保证首个章节步骤就能读到设定。
+    # 只对带连载引擎的任务接收；已有不同内容的圣经拒绝覆盖，避免新任务误伤旧书设定。
+    initial_bible = str(payload.get("story_bible") or "").strip()
+    if initial_bible:
+        if not task.get("serial"):
+            raise ValueError("初始故事圣经仅适用于连载小说任务")
+        if len(initial_bible) > BIBLE_MAX_CHARS:
+            raise ValueError("故事圣经超长（最大 %d 字符，当前 %d 字符）" %
+                             (BIBLE_MAX_CHARS, len(initial_bible)))
     resume = payload.get("resume")
     if isinstance(resume, dict) and resume.get("agent") and resume.get("session"):
         task["resume"] = {"agent": str(resume["agent"])[:40],
@@ -191,6 +226,11 @@ def create_task(payload):
         proj = str(resume.get("project") or "")[:260]
         if proj:
             task["resume"]["project"] = proj
+    # 初始圣经先于附件提交：如果目录已有设定，尽早拒绝，避免附件已移动却
+    # 因故事圣经冲突导致任务创建失败。相同内容的重试是幂等的（例如附件
+    # 提交中断后重试），不会覆盖已有设定。
+    if initial_bible:
+        _write_initial_story_bible(str(wd), initial_bible)
     # 附件：把待提交文件移入工作目录 _attachments/，清单注入 context（__CONTEXT__ 全链路可见）。
     # 两种形态：字符串 id = 待提交区文件（新建任务）；dict 清单 = 已落盘的附件
     # （继续连载/重试沿用同目录同文件，直接复制清单，不再移文件）。
@@ -388,8 +428,15 @@ def create_run(kind, title, task_id=None, entry_id=None, op=None):
     rdir = paths.RUNS_DIR / run["id"]
     (rdir / "steps").mkdir(parents=True, exist_ok=True)
     with LOCK:
+        # 先完成原子落盘，再发布到内存索引。旧顺序在 _save_json 失败时会
+        # 留下只存在于 _RUNS 的“幽灵 run”，后续 UI 看到排队记录却永远无法
+        # 读取/恢复其 run.json。
+        try:
+            _save_json(rdir / "run.json", run)
+        except Exception:
+            _RUNS.pop(run["id"], None)
+            raise
         _RUNS[run["id"]] = run
-        _save_json(rdir / "run.json", run)
     return run
 
 
@@ -615,6 +662,39 @@ def recover_orphaned_runs():
     return recovered
 
 
+def recover_interrupted_mgmt():
+    """启动时调用：把崩溃遗留的 queued 管理操作 run 标记为 failed。
+
+    running 的 mgmt run 已由 recover_orphaned_runs 统一收尸；queued 不在
+    其候选里——通用恢复故意留着 queued 给连载任务的 resume_interrupted
+    复活，但 mgmt job 只存在于内存队列，重启后永远没人认领，留着还会
+    堵住同条目的去重闸门。workers 尚未启动，此时 queued 必是遗留。
+    """
+    now = time.strftime("%Y-%m-%d %H:%M:%S")
+    with LOCK:
+        candidates = [r["id"] for r in _RUNS.values()
+                      if r.get("kind") == "mgmt" and r.get("status") == "queued"]
+    for run_id in candidates:
+        update_run(run_id, status="failed", ended_at=now,
+                   error="interrupted at startup (mgmt auto-recovered)")
+    return len(candidates)
+
+
+def active_mgmt_run(entry_id):
+    """该目录条目当前进行中（queued/running）的管理操作 run；没有则 None。
+
+    供「同条目同时只跑一个安装/升级/卸载」去重闸使用：两个同名全局 npm
+    并发装同一包会互锁（2026-09-18 codex 双开案）。内存索引即真源——
+    重启后 recover_* 已把遗留 run 收成终态。
+    """
+    with LOCK:
+        for r in _RUNS.values():
+            if r.get("kind") == "mgmt" and r.get("entry_id") == entry_id \
+                    and r.get("status") in ("queued", "running"):
+                return dict(r)
+    return None
+
+
 def run_workdir(run_id):
     """该 run 的工作目录（经其 task 关联）；无任务的 run（如管理操作）返回空串。"""
     run = get_run(run_id)
@@ -732,6 +812,52 @@ def _bible_path(workdir):
     return p
 
 
+def _write_initial_story_bible(workdir, text):
+    """创建任务时安全播种故事圣经。
+
+    初始圣经写入发生在任务入队之前，多个请求可能同时指向同一个工作目录。
+    旧逻辑先在锁外检查、再在锁外写入，两个请求都能通过检查，后写请求会
+    覆盖先写的设定。这里把检查和写入放进同一进程锁，并在文件不存在时用
+    ``O_EXCL`` 做最后一道独占创建；已有不同内容的文件始终拒绝覆盖。
+    """
+    p = _bible_path(workdir)
+    if p is None:
+        raise ValueError("故事圣经写入失败：工作目录不可用")
+    with LOCK:
+        try:
+            p.parent.mkdir(parents=True, exist_ok=True)
+            if p.exists():
+                if not p.is_file():
+                    raise ValueError("故事圣经写入失败：目标路径不是文件")
+                existing = runner.read_text_any_enc(p).strip()
+                if existing:
+                    if existing == text:
+                        return
+                    raise ValueError("工作目录已有 story-bible.md，请清空初始圣经输入或先编辑已有设定")
+                # 空文件是合法的旧占位文件；在锁内覆盖，避免本服务内的并发写入。
+                p.write_text(text, encoding="utf-8")
+                return
+            try:
+                fd = os.open(str(p), os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)
+            except FileExistsError:
+                # 其他进程可能刚创建了文件。相同内容可幂等返回；空文件仍可
+                # 完成播种，非空不同内容绝不静默覆盖。
+                if p.is_file():
+                    existing = runner.read_text_any_enc(p).strip()
+                    if existing == text:
+                        return
+                    if not existing:
+                        p.write_text(text, encoding="utf-8")
+                        return
+                raise ValueError("工作目录已有 story-bible.md，请清空初始圣经输入或先编辑已有设定")
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                fh.write(text)
+        except ValueError:
+            raise
+        except OSError as e:
+            raise ValueError("故事圣经写入失败：%s" % e)
+
+
 def read_story_bible(task_id):
     """读取任务工作目录里的故事圣经。返回 (文件路径, 文本内容, None) 或
     (None, None, 错误信息)。"""
@@ -757,23 +883,26 @@ def write_story_bible(task_id, text):
     - 文本超长（BIBLE_MAX_CHARS）→ 拒绝；
     - 写入失败 → 报错。
     返回 (ok, 错误信息)。"""
-    task = get_task(task_id)
-    if not task:
-        return False, "任务不存在"
-    if task.get("status") in ("queued", "running"):
-        return False, "任务正在运行，不能修改故事圣经（请等运行结束后再编辑）"
-    p = _bible_path(task.get("workdir"))
-    if p is None:
-        return False, "工作目录不存在或路径越界"
-    text = (text or "").strip()
-    if len(text) > BIBLE_MAX_CHARS:
-        return False, "故事圣经超长（最大 %d 字符，当前 %d 字符）" % (BIBLE_MAX_CHARS, len(text))
-    try:
-        p.parent.mkdir(parents=True, exist_ok=True)
-        p.write_text(text, encoding="utf-8")
-        return True, ""
-    except OSError as e:
-        return False, "写入失败: %s" % e
+    with LOCK:
+        task = get_task(task_id)
+        if not task:
+            return False, "任务不存在"
+        if task.get("status") in ("queued", "running"):
+            return False, "任务正在运行，不能修改故事圣经（请等运行结束后再编辑）"
+        p = _bible_path(task.get("workdir"))
+        if p is None:
+            return False, "工作目录不存在或路径越界"
+        text = (text or "").strip()
+        if len(text) > BIBLE_MAX_CHARS:
+            return False, "故事圣经超长（最大 %d 字符，当前 %d 字符）" % (BIBLE_MAX_CHARS, len(text))
+        try:
+            p.parent.mkdir(parents=True, exist_ok=True)
+            p.write_text(text, encoding="utf-8")
+        except OSError as e:
+            return False, "写入失败: %s" % e
+    # 故事圣经是提示词输入，写入后让 SSE/轮询端尽快看到新状态。
+    bump_state()
+    return True, ""
 
 
 def read_run_file(run_id, rel):
@@ -1144,7 +1273,8 @@ def add_step(run_id, role, agent_id, agent_label, note=""):
 
 
 def finish_step(run_id, n, status, summary="", exit_code=None,
-                cost_usd=0.0, tokens=0.0, duration_s=None, model=None, output=None):
+                cost_usd=0.0, tokens=0.0, duration_s=None, model=None, output=None,
+                followups=None):
     with LOCK:
         run = _RUNS.get(run_id)
         if not run:
@@ -1163,6 +1293,8 @@ def finish_step(run_id, n, status, summary="", exit_code=None,
                     s["duration_s"] = round(duration_s, 1)
                 if output is not None:
                     s["output"] = str(output)[:6000]
+                if followups:
+                    s["followups"] = list(followups)[:3]
                 break
         run["cost_usd"] = round(run.get("cost_usd", 0.0) + cost_usd, 4)
         run["tokens"] = run.get("tokens", 0) + tokens

package/app/core/telemetry.py

@@ -0,0 +1,291 @@
+# -*- coding: utf-8 -*-
+"""遥测回传（L2）+ 版本 ping（L3）+ 诊断包构建（L1）。
+
+设计原则：
+- 默认只传「匿名错误元数据」：errorlog 台账里的结构化失败记录（厂商/模型/原因码/
+  脱敏摘录/版本/OS），不含任何任务正文、章节内容、密钥、绝对路径；
+- 上传前对每条记录再兜一道 scrub_text（不信任入台账时的第一道）；
+- 开关 settings.telemetry_errors（默认开）；关掉后什么都不出机器（含版本 ping）；
+- 网络失败静默吞掉：遥测永远不影响业务，也不制造新错误；
+- 端点：CloudBase HTTP 函数（国内可达、零运维），可用环境变量
+  TUTTI_TELEMETRY_URL 覆盖；端点为空/未配置时整个模块自动休眠。
+
+SSRF 防线（端点可被 env 覆盖，所以请求前必须自证安全）：
+  https 限定 + 域名后缀白名单 + 解析 IP 拒绝私网/环回/链路本地。
+
+线程模型：start_background() 起一条 daemon 线程，首轮延迟 45s（不挡启动），
+之后每 6 小时一轮（ping 每轮一次，错误按游标增量上传）。
+"""
+from __future__ import annotations
+
+import io
+import ipaddress
+import json
+import os
+import platform
+import socket
+import threading
+import time
+import urllib.request
+import zipfile
+
+from . import errorlog, paths, settings
+
+# 端点：部署后把 CloudBase HTTP 函数 URL 填到这里（见 cloudfunctions/telemetry-collect/）
+ENDPOINT = os.environ.get("TUTTI_TELEMETRY_URL", "").strip()
+
+# 请求只允许发往我们自己的收集域（后缀匹配，大小写不敏感）；
+# 测试需要假端点时 monkeypatch 本常量或直接 patch _post。
+ALLOWED_SUFFIXES = (".tcloudbase.com", ".tencentyun.com", ".tencentcs.com")
+
+FIRST_DELAY_S = 45
+INTERVAL_S = 6 * 3600
+BATCH_LIMIT = 200
+TIMEOUT_S = 10
+
+_thread_started = False
+
+
+def _cursor_path():
+    """游标文件路径惰性计算：测试会把 paths.ERRORS_DIR 重定向到临时目录，
+    import 期绑定会钉死在真实数据目录（与 settings._FILE 同一个坑）。"""
+    return paths.ERRORS_DIR / "upload.cursor"
+
+
+def enabled():
+    try:
+        return bool(settings.load().get("telemetry_errors", True))
+    except Exception:
+        return False
+
+
+def _os_tag():
+    return {"win32": "windows", "darwin": "macos"}.get(platform.system().lower(),
+                                                      platform.system().lower())
+
+
+def _version():
+    try:
+        from . import selfupdate
+        return str(selfupdate.package_version() or "dev")
+    except Exception:
+        return "dev"
+
+
+def _endpoint_safe(url):
+    """端点自证安全：https + 域名后缀白名单 + 解析 IP 全部公网。
+    不合格返回 ""（调用方静默跳过——遥测绝不为安全边界让步）。"""
+    if not url:
+        return ""
+    try:
+        from urllib.parse import urlparse
+        p = urlparse(url)
+        if p.scheme != "https" or not p.hostname:
+            return ""
+        host = p.hostname.lower()
+        if not any(host == s.lstrip(".") or host.endswith(s)
+                   for s in ALLOWED_SUFFIXES):
+            return ""
+        for info in socket.getaddrinfo(host, 443, proto=socket.IPPROTO_TCP):
+            ip = ipaddress.ip_address(str(info[4][0]))
+            if (ip.is_private or ip.is_loopback or ip.is_link_local
+                    or ip.is_reserved or ip.is_multicast or ip.is_unspecified):
+                return ""
+        return url
+    except Exception:
+        return ""
+
+
+def _post(url, payload):
+    """POST JSON 到已通过 _endpoint_safe 校验的 URL；返回状态码，异常返回 0。"""
+    safe = _endpoint_safe(url)
+    if not safe:
+        return 0
+    try:
+        req = urllib.request.Request(
+            safe, data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
+            headers={"Content-Type": "application/json",
+                     "User-Agent": "CodeBee-Telemetry/1"},
+            method="POST")
+        with urllib.request.urlopen(req, timeout=TIMEOUT_S) as resp:
+            return int(resp.status or 0)
+    except Exception:
+        return 0
+
+
+# ---------------------------------------------------------------- 上报循环
+
+def _read_cursor():
+    try:
+        return _cursor_path().read_text(encoding="utf-8").strip()
+    except Exception:
+        return ""
+
+
+def _write_cursor(v):
+    try:
+        p = _cursor_path()
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(str(v), encoding="utf-8")
+    except Exception:
+        pass
+
+
+def _sanitize_record(r):
+    """上传前的最后一道闸：只挑白名单字段，detail 再过一次 scrub。"""
+    keep = ("id", "ts", "day", "category", "reason", "provider", "model",
+            "tool", "role", "run_id", "task_id", "step", "exit_code",
+            "app_version", "os")
+    out = {k: r.get(k) for k in keep if k in r}
+    out["detail"] = errorlog.scrub_text(r.get("detail") or "", limit=600)
+    return out
+
+
+def run_once():
+    """一轮上报：版本 ping + 增量错误批量。返回 (ping_ok, uploaded_n)。"""
+    if not enabled() or not ENDPOINT:
+        return (False, 0)
+    ping_ok = _post(ENDPOINT, {
+        "kind": "ping", "app": "codebee", "version": _version(),
+        "os": _os_tag(), "python": "%d.%d" % platform.python_version_tuple()[:2],
+        "ts": time.strftime("%Y-%m-%d %H:%M:%S"),
+    }) == 200
+    uploaded = 0
+    cursor = _read_cursor()
+    batch, new_cursor = errorlog.pending_since(cursor, limit=BATCH_LIMIT)
+    if batch:
+        payload = {"kind": "errors", "records": [_sanitize_record(r) for r in batch]}
+        if _post(ENDPOINT, payload) == 200:
+            _write_cursor(new_cursor)
+            uploaded = len(batch)
+    return (ping_ok, uploaded)
+
+
+def _loop():
+    while True:
+        try:
+            run_once()
+        except Exception:
+            pass
+        time.sleep(INTERVAL_S)
+
+
+def start_background():
+    """启动上报线程（daemon，首轮延迟 45s）。重复调用安全；未配端点直接休眠。"""
+    global _thread_started
+    if _thread_started or not ENDPOINT:
+        return
+    _thread_started = True
+
+    def _delayed():
+        time.sleep(FIRST_DELAY_S)
+        try:
+            run_once()
+        except Exception:
+            pass
+        _loop()
+
+    threading.Thread(target=_delayed, name="telemetry-up", daemon=True).start()
+
+
+# ---------------------------------------------------------------- 诊断包（L1）
+
+def build_bundle_bytes(days=30):
+    """构建「诊断包」zip 字节流：脱敏错误台账 + 用量台账 + 环境元信息。
+
+    只装可安全外发的聚合数据——绝不打包 tasks/runs/models.json（后者含密钥）。
+    错误记录出包前再 scrub 一遍（与上传同一道闸，出机器的东西不过两道不放行）。
+    """
+    meta = {
+        "app": "CodeBee",
+        "version": _version(),
+        "os": _os_tag(),
+        "os_version": platform.platform(),
+        "python": platform.python_version(),
+        "telemetry_enabled": enabled(),
+        "generated_at": time.strftime("%Y-%m-%d %H:%M:%S"),
+        "note": "此包只含匿名错误元数据与用量统计；已剥离密钥、路径与任务内容。",
+    }
+    errors = [_sanitize_record(r) for r in errorlog.iter_records(days)]
+    buf = io.BytesIO()
+    stamp = time.strftime("%Y%m%d-%H%M%S")
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as z:
+        z.writestr("codebee-diag-%s/meta.json" % stamp,
+                   json.dumps(meta, ensure_ascii=False, indent=2))
+        z.writestr("codebee-diag-%s/errors-%ddays.jsonl" % (stamp, days),
+                   "\n".join(json.dumps(r, ensure_ascii=False) for r in errors))
+        usage_lines = []
+        try:
+            from . import usage
+            for r in usage._iter_records(days):
+                usage_lines.append(json.dumps(r, ensure_ascii=False))
+        except Exception:
+            pass
+        z.writestr("codebee-diag-%s/usage-%ddays.jsonl" % (stamp, days),
+                   "\n".join(usage_lines))
+    return buf.getvalue()
+
+
+# ---------------------------------------------------------------- 一键反馈 Issue（免费通道）
+
+# 反馈目标仓库（Issue 预填正文，由用户在浏览器亲手提交——不自动回传）
+ISSUE_URL = "https://github.com/Vercel-By-WXP/CodeBee/issues/new"
+
+
+def issue_report(days=30, max_groups=8, max_recent=10, detail_chars=120):
+    """本地错误台账 → GitHub Issue 预填摘要。返回 {title, body}。
+
+    聚合 + 明细全部来自已脱敏的 errorlog 台账，出正文前再 scrub 一道
+    （与上传/诊断包同一纪律：出机器的东西过两道不放行）。明细压成单行，
+    方便 URL 预填。days=0 表示全部历史。
+    """
+    errors = errorlog.iter_records(days)
+    groups = {}
+    for r in errors:
+        key = (str(r.get("reason") or "UNKNOWN"),
+               str(r.get("provider") or "-"),
+               str(r.get("model") or "-"))
+        g = groups.setdefault(key, {"n": 0, "last": ""})
+        g["n"] += 1
+        if str(r.get("ts") or "") > g["last"]:
+            g["last"] = str(r.get("ts") or "")
+    top = sorted(groups.items(), key=lambda kv: -kv[1]["n"])[:max_groups]
+    version = _version()
+
+    if top:
+        t_reason, t_prov, t_model = top[0][0]
+        title = "错误反馈：%s ×%d（v%s / %s）" % (
+            t_reason, top[0][1]["n"], version, _os_tag())
+    else:
+        title = "CodeBee 错误反馈（无自动记录的错误）"
+
+    lines = [
+        "## CodeBee 错误反馈", "",
+        "- 版本：v%s（%s）" % (version, _os_tag()),
+        "- Python：%s" % platform.python_version(),
+        "- 生成时间：%s" % time.strftime("%Y-%m-%d %H:%M:%S"),
+        "",
+        ("近 %d 天失败聚合（原因 × 次数）" % days) if days
+        else "全部历史失败聚合（原因 × 次数）",
+    ]
+    if top:
+        lines.append("| 原因 | 供应商/模型 | 次数 | 最近一次 |")
+        lines.append("|---|---|---|---|")
+        for (reason, prov, model), g in top:
+            lines.append("| %s | %s/%s | %d | %s |" % (reason, prov, model,
+                                                       g["n"], g["last"]))
+    else:
+        lines.append("（本机错误台账为空）")
+    lines += ["", "## 最近失败明细（最多 %d 条，已脱敏）" % max_recent]
+    if errors:
+        for r in errors[-max_recent:]:
+            detail = errorlog.scrub_text(r.get("detail") or "", limit=detail_chars)
+            detail = detail.replace("\r", " ").replace("\n", " ")
+            lines.append("- `%s` %s [%s/%s] %s" % (
+                str(r.get("ts") or ""), str(r.get("reason") or "UNKNOWN"),
+                str(r.get("provider") or "-"), str(r.get("model") or "-"), detail))
+    else:
+        lines.append("（无）")
+    lines += ["", "> 提示：可在 设置 → 关于与更新 → 导出诊断包 生成 zip 附在本 Issue"
+              "（含更完整的脱敏错误记录与用量统计）。", ""]
+    return {"title": title, "body": "\n".join(lines)}

package/app/core/token_meter.py

@@ -121,6 +121,24 @@ class TokenMeter:
         cap = cap_table.get(m, cap_table.get("", 128_000))
         return self.used(run_id) / max(cap, 1)
 
+    def capacity(self, model: str = "") -> int:
+        """模型上下文容量（未命中用默认行）。"""
+        cap_table = self._capacity()
+        return cap_table.get(model or "", cap_table.get("", 128_000))
+
+    def last_context(self, run_id: str) -> int:
+        """最近一次调用的 input+output+reasoning——下个请求要重发的上下文锚点。
+
+        used() 是窗口累计（多次调用叠加，系统性偏大，适合做响应式预算闸）；
+        事前预检判断「这个请求会不会被拒」要用最近一次的真实上下文体量，
+        两者口径不同不可混用（借鉴 freebuff base-chat 每步容量重估）。"""
+        with self._lock:
+            window = self._windows.get(run_id)
+            if not window:
+                return 0
+            _, i, o, r, _ = window[-1]
+            return i + o + r
+
     def reset(self, run_id: str):
         with self._lock:
             self._windows.pop(run_id, None)

package/app/core/usage.py

@@ -214,7 +214,10 @@ def agent_tokens_recent(agent, hours=1):
                 if str(r.get("ts") or "") < bound:
                     continue
                 a = str(r.get("agent") or "")
-                total[a] = total.get(a, 0) + max(0, _parse_int((r.get("usage") or {}).get("total")))
+                # record() 将规范化后的 token 总数落在顶层 ``total``；旧实现
+                # 误读不存在的嵌套 usage 字段，导致配额路由永远认为本小时
+                # 用量为 0，超过供应商额度也不会降权。
+                total[a] = total.get(a, 0) + max(0, _parse_int(r.get("total")))
             _HOURLY_CACHE.update(ts=now, val=total)
         return int(_HOURLY_CACHE["val"].get(agent) or 0)
     except Exception:
@@ -448,3 +451,50 @@ def summary(days=30, recent_limit=30):
         "by_task_type": _dim_rows(records, "task_type"),
         "recent": recent,
     }
+
+
+def estimate(task_type="", days=90):
+    """同类任务开跑前成本预估（借鉴 omnigent 的 pre-run estimate；数据源就是本台账）。
+
+    同一 run 的多条步骤记录加总为一个样本，优先用成功 run，给中位数/平均/P90。
+    task_type 为空=全类型。无样本时 samples=0，前端不展示。"""
+    span = max(1, min(3650, int(days or 90)))
+    with LOCK:
+        records = _iter_records(span)
+    runs = {}
+    for r in records:
+        tt = str(r.get("task_type") or "unknown")
+        if task_type and tt != task_type:
+            continue
+        rid = str(r.get("run_id") or "")
+        if not rid:
+            continue
+        g = runs.setdefault(rid, {"tokens": 0, "cost": 0.0, "ok": False})
+        g["tokens"] += _num(r, "total")
+        g["cost"] += _parse_float(r.get("cost_usd"))
+        if r.get("ok"):
+            g["ok"] = True
+    ok_runs = [g for g in runs.values() if g["ok"]]
+    basis = ok_runs or list(runs.values())
+    if not basis:
+        return {"task_type": task_type or "", "days": span, "samples": 0}
+    toks = sorted(g["tokens"] for g in basis)
+    costs = sorted(g["cost"] for g in basis)
+    n = len(toks)
+    mid = n // 2
+    med = toks[mid] if n % 2 else (toks[mid - 1] + toks[mid]) / 2.0
+    med_c = costs[mid] if n % 2 else (costs[mid - 1] + costs[mid]) / 2.0
+    import datetime
+    import math
+    return {
+        "task_type": task_type or "",
+        "days": span,
+        "samples": n,
+        "ok_samples": len(ok_runs),
+        "avg_tokens": int(sum(toks) / n),
+        "median_tokens": int(med),
+        "p90_tokens": toks[max(0, min(n - 1, math.ceil(0.9 * n) - 1))],
+        "avg_cost_usd": round(sum(costs) / n, 4),
+        "median_cost_usd": round(med_c, 4),
+        "since": (datetime.date.today() - datetime.timedelta(days=span - 1)).isoformat(),
+    }