codebee 0.1.5 → 0.1.7

package/app/core/router.py

@@ -14,9 +14,10 @@ MAX_REPAIR_ROUNDS = 2  # 自动修复循环上限
 
 
 def _binding_bonus(agent_id):
-    """绑定链可用性加分/减分：链上有可用条目 +8，解析为空（回落 CLI 本机默认）
-    -25。2026-09-16 实测：静态能力基线让配额烧干的 codex 永远压过健康备用 CLI，
-    绑定空的 CLI 更是连用户配置的模型都没用上——先按「能不能按配置跑起来」校准。"""
+    """绑定链可用性加分/减分：链上有可用条目 +8，解析为空 -25。2026-09-16 实测：
+    静态能力基线让配额烧干的 codex 永远压过健康备用 CLI，绑定空的 CLI 更是连
+    用户配置的模型都没用上——先按「能不能按配置跑起来」校准。2026-09-17 起
+    空链步骤在 pipeline 直接判失败（不再静默回落本机默认），此处只管排序。"""
     try:
         from . import modelhub
         b = modelhub.resolve_binding(agent_id)
@@ -49,7 +50,7 @@ def score(agent, role, ttype, stats=None):
     if bb > 0:
         btxt = "，绑定链可用（+%s）" % bb
     elif bb < 0:
-        btxt = "，绑定链为空将回落 CLI 本机默认配置（%s）" % bb
+        btxt = "，绑定链为空：相关步骤将判失败（%s）" % bb
     hb = _history_bonus(stats, agent.get("id"), ttype)
     total = base + bb + hb
     hs = (stats.get(agent.get("id")) or {}).get(ttype)

package/app/core/runner.py

@@ -16,6 +16,7 @@ import json
 import os
 import re
 import shutil
+import signal
 import subprocess
 import threading
 import time
@@ -23,7 +24,9 @@ import time
 from .env_scrub import scrub_env
 from .error_codes import ErrorCode
 
-CREATE_NO_WINDOW = 0x08000000
+# 非 Windows 必须置 0：POSIX 的 Popen 对非零 creationflags 直接抛 ValueError，
+# 置 0 则两边通用（remote.py 同款守卫）。
+CREATE_NO_WINDOW = 0x08000000 if os.name == "nt" else 0
 DEFAULT_TIMEOUT = 1200  # 单步 20 分钟
 
 _BASH_CANDIDATES = [
@@ -35,6 +38,11 @@ _bash_cache = {"path": None, "done": False}
 
 
 def find_git_bash():
+    """Windows 专供：claude 原生 exe 找不到 bash 会拒绝启动，指给 Git Bash。
+    macOS/Linux 有系统 bash，claude 自会找到；强行设 CLAUDE_CODE_GIT_BASH_PATH
+    反而可能指错（/bin/bash 与 Git Bash 行为有差异），故非 Windows 一律 None。"""
+    if os.name != "nt":
+        return None
     if _bash_cache["done"]:
         return _bash_cache["path"]
     _bash_cache["done"] = True
@@ -81,6 +89,19 @@ def _npm_shim_bypass(argv):
 
 
 def _kill_tree(pid):
+    """杀整棵进程树。Windows 用 taskkill /T；POSIX 靠 spawn 时的
+    start_new_session（子进程自成一个进程组，pgid==pid）用 killpg 连孙带杀。"""
+    if os.name != "nt":
+        try:
+            os.killpg(pid, signal.SIGKILL)
+            return
+        except Exception:
+            pass
+        try:
+            os.kill(pid, signal.SIGKILL)
+        except Exception:
+            pass
+        return
     try:
         subprocess.run(
             ["taskkill", "/F", "/T", "/PID", str(pid)],
@@ -295,7 +316,8 @@ def run_process(argv=None, shell_cmd=None, stdin_text=None, cwd=None, env=None,
     返回 {ok, exit_code, stdout, stderr, duration, cancelled, timed_out, stalled}。
     """
     if shell_cmd:
-        argv = ["cmd", "/c", shell_cmd]
+        # shell 串的解析器随平台：重定向/引号语法两边通用，只是解释器不同
+        argv = ["cmd", "/c", shell_cmd] if os.name == "nt" else ["/bin/sh", "-c", shell_cmd]
     if argv is None:
         return {"ok": False, "exit_code": None, "stdout": "", "stderr": "argv 为空",
                 "duration": 0.0, "cancelled": False, "timed_out": False, "stalled": False}
@@ -327,7 +349,8 @@ def run_process(argv=None, shell_cmd=None, stdin_text=None, cwd=None, env=None,
                 [str(a) for a in argv], cwd=cwd, env=full_env,
                 stdin=subprocess.PIPE if stdin_text is not None else subprocess.DEVNULL,
                 stdout=subprocess.PIPE, stderr=subprocess.PIPE,
-                creationflags=CREATE_NO_WINDOW)
+                creationflags=CREATE_NO_WINDOW,
+                start_new_session=(os.name != "nt"))  # POSIX 需独立进程组供 killpg 杀树；Windows 忽略该参数
         except Exception as e:
             return {"ok": False, "exit_code": None, "stdout": "",
                     "stderr": "启动失败: %r" % e, "duration": 0.0,
@@ -824,9 +847,18 @@ def run_agent(agent, prompt, workdir=None, readonly=True,
     if orch_timeout_ms:
         timeout = float(orch_timeout_ms) / 1000.0
     kind = agent.get("kind", "generic")
-    stall_t = (_stall_timeout("TUTTI_CODEX_STALL_TIMEOUT", 600) if kind == "codex"
-               else _stall_timeout("TUTTI_CLAUDE_STALL_TIMEOUT", 600)
-               if kind == "claude" else 0)
+    if kind == "codex":
+        stall_t = _stall_timeout("TUTTI_CODEX_STALL_TIMEOUT", 600)
+    elif kind == "claude":
+        stall_t = _stall_timeout("TUTTI_CLAUDE_STALL_TIMEOUT", 600)
+    else:
+        # 数据驱动：catalog orch.stall_timeout_s——给 kimi 这类边写边吐进度行的
+        # CLI 配置后，静默挂死 10 分钟即杀（不必耗满总超时）；qwen/mimo 这类
+        # 结束才一次性输出的留 0（开了必误杀），靠总超时兜底
+        try:
+            stall_t = max(0, int((agent.get("orch") or {}).get("stall_timeout_s") or 0))
+        except Exception:
+            stall_t = 0
     # 5G：approval NEVER 一线（无人值守不静默降级）
     ok, reason = _check_approval(agent)
     if not ok:

package/app/core/selfupdate.py

@@ -18,18 +18,22 @@ SSE 可看进度）。npm 替换的是包目录文件，当前进程已加载进
 """
 from __future__ import annotations
 
-import json
-import os
+import json
+import logging
+import os
 import re
 import socket
 import subprocess
 import sys
 import threading
 import time
+from pathlib import Path
 
-from . import paths, runner
-
-_PKG_NAME = "codebee"   # npm 发布名；必须与 package.json 的 name 一致（单测断言）
+from . import paths, runner
+
+log = logging.getLogger(__name__)
+
+_PKG_NAME = "codebee"   # npm 发布名；必须与 package.json 的 name 一致（单测断言）
 _UPDATE_TTL = 600   # 查新结果缓存（秒）
 _LOCK = threading.Lock()
 _CHECK_CACHE = {"ts": 0.0, "result": None}
@@ -72,13 +76,21 @@ def _relnotes(readme):
     return m.group(1).strip() if m else ""
 
 
+def _npm_argv(*args):
+    """npm 命令 argv：Windows 的 npm 是 .cmd 垫片须经 cmd /c；POSIX 直接跑。"""
+    if os.name == "nt":
+        return ["cmd", "/c", "npm"] + list(args)
+    return ["npm"] + list(args)
+
+
 def _npm_meta():
     """npm view <pkg> --json；返回 (latest, relnotes, err)。
 
     relnotes 来自 registry 元数据里的 README（与查新同一条 npm 通道，不依赖
-    GitHub 连通性），展示「新版本更新内容」用。"""
+    GitHub 连通性），展示「新版本更新内容」用。部分 npm 版本 --json 不带
+    readme 字段，此时回退到 `npm view <pkg> readme` 纯文本再提取。"""
     r = runner.run_process(
-        argv=["cmd", "/c", "npm", "view", _PKG_NAME, "--json"], timeout=60)
+        argv=_npm_argv("view", _PKG_NAME, "--json"), timeout=60)
     if not r["ok"]:
         return "", "", (r["stderr"] or r["stdout"] or "")[-200:] or "npm 命令失败"
     ver, notes = "", ""
@@ -92,6 +104,11 @@ def _npm_meta():
     if not ver:  # 旧 npm --json 失败时退回纯文本解析
         m = re.search(r"\d+\.\d+\.\d+[\w.\-]*", r["stdout"] or "")
         ver = m.group(0) if m else ""
+    if ver and not notes:
+        r2 = runner.run_process(
+            argv=_npm_argv("view", _PKG_NAME, "readme"), timeout=60)
+        if r2["ok"]:
+            notes = _relnotes(r2["stdout"] or "")
     return ver, notes, ("" if ver else "npm 输出无法解析")
 
 
@@ -144,22 +161,41 @@ def check(force=False):
     return out
 
 
-def apply_upgrade():
+def apply_upgrade():
     """发起升级：建 mgmt run 异步跑 npm install -g @latest。返回 {run_id} 或 {error}。"""
     if install_mode() != "npm":
         return {"error": "当前安装方式不支持自动升级（见版本页说明）"}
     from . import store, jobs
-    run = store.create_run("mgmt", "升级 CodeBee 本体（npm install -g %s@latest）" % _PKG_NAME,
-                           entry_id="__self__", op="selfupgrade")
-    jobs.enqueue({"kind": "selfupgrade", "run_id": run["id"]})
-    return {"run_id": run["id"]}
+    try:
+        run = store.create_run(
+            "mgmt", "升级 CodeBee 本体（npm install -g %s@latest）" % _PKG_NAME,
+            entry_id="__self__", op="selfupgrade")
+    except Exception:
+        log.exception("selfupdate: 创建升级运行记录失败")
+        return {"error": "升级任务创建失败，请稍后重试"}
+    try:
+        jobs.enqueue({"kind": "selfupgrade", "run_id": run["id"]})
+    except Exception:
+        # The run is already durable when enqueue fails. Close it explicitly so
+        # the upgrade panel cannot remain in a misleading queued state.
+        log.exception("selfupdate: 升级任务入队失败 run=%s", run["id"])
+        try:
+            store.update_run(run["id"], status="failed",
+                             error="升级任务入队失败，请稍后重试",
+                             ended_at=time.strftime("%Y-%m-%d %H:%M:%S"))
+        except Exception:
+            log.exception("selfupdate: 升级运行失败收口失败 run=%s", run["id"])
+        return {"error": "升级任务入队失败，请稍后重试", "run_id": run["id"]}
+    return {"run_id": run["id"]}
 
 
 def run_upgrade(run_id, log_path):
     """worker 线程里执行升级命令（run/step 生命周期由 jobs 层管）。"""
     res = runner.run_process(
-        argv=["cmd", "/c", "npm", "install", "-g", _PKG_NAME + "@latest"],
-        cwd=str(paths.ROOT), timeout=900, log_path=log_path)
+        argv=_npm_argv("install", "-g", _PKG_NAME + "@latest"),
+        # Windows 上 npm 换版本靠把包目录整体改名（codebee → .codebee-xxx）；
+        # cwd 若落在本包内，目录被自身进程占用，rename 必报 EBUSY——钉在包外
+        cwd=str(Path.home()), timeout=900, log_path=log_path)
     if res["ok"]:
         with _LOCK:  # 装完即过期查新缓存，重启后自然拿到新版本
             _CHECK_CACHE["result"] = None
@@ -194,9 +230,10 @@ def relaunch(port):
     if port < 1 or port > 65535:
         return False
     subprocess.Popen(
-        [sys.executable, "main.py", "--port", str(port),
+        [sys.executable, str(paths.APP_DIR / "main.py"), "--port", str(port),
          "--wait-port", "--no-browser"],
-        cwd=str(paths.APP_DIR),
+        # 新实例 CWD 同样不得落在包内，否则下次升级 npm 改名包目录再撞 EBUSY
+        cwd=str(Path.home()),
         stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
         close_fds=True,
         creationflags=(0x00000008 | 0x00000200) if os.name == "nt" else 0)

package/app/core/store.py

@@ -61,20 +61,30 @@ def _safe_name(s):
 
 # ---------------------------------------------------------------- 任务
 
-def create_task(payload):
+def create_task(payload):
     """校验并创建任务。payload 至少含 type/goal/workdir。
 
     type 必须是 flows.py 里的有效流程 ID；流程参数（引擎/维度/阈值/轮数/产出
     文件/提示词覆盖）在创建时固化到任务上，之后修改流程定义不影响已建任务。
     """
-    from . import flows as flows_mod
+    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
@@ -147,8 +158,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 = {
@@ -180,8 +201,17 @@ def create_task(payload):
                     s["variants"] = v
                 task["serial"] = s
     critics = payload.get("critics")
-    if isinstance(critics, list) and critics:
-        task["critics"] = [str(c) for c in 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,11 +221,16 @@ def create_task(payload):
         proj = str(resume.get("project") or "")[:260]
         if proj:
             task["resume"]["project"] = proj
-    # 附件：把待提交文件移入工作目录 _attachments/，清单注入 context（__CONTEXT__ 全链路可见）。
+    # 初始圣经先于附件提交：如果目录已有设定，尽早拒绝，避免附件已移动却
+    # 因故事圣经冲突导致任务创建失败。相同内容的重试是幂等的（例如附件
+    # 提交中断后重试），不会覆盖已有设定。
+    if initial_bible:
+        _write_initial_story_bible(str(wd), initial_bible)
+    # 附件：把待提交文件移入工作目录 _attachments/，清单注入 context（__CONTEXT__ 全链路可见）。
     # 两种形态：字符串 id = 待提交区文件（新建任务）；dict 清单 = 已落盘的附件
     # （继续连载/重试沿用同目录同文件，直接复制清单，不再移文件）。
     att_ids = payload.get("attachments")
-    if isinstance(att_ids, list) and att_ids:
+    if isinstance(att_ids, list) and att_ids:
         from . import attachments as att_mod
         items = [a for a in att_ids if isinstance(a, dict) and a.get("path")]
         if not items:  # 纯 id 形态 → 从待提交区移入工作目录
@@ -208,9 +243,9 @@ def create_task(payload):
             task["attachments"] = items
             blk = att_mod.context_block(items)
             # 复制清单场景下 context 已含附件块（随旧任务沿用），别重复追加
-            if blk and "## 附件材料" not in task["context"]:
-                task["context"] = (task["context"] + blk).strip()
-    with LOCK:
+            if blk and "## 附件材料" not in task["context"]:
+                task["context"] = (task["context"] + blk).strip()
+    with LOCK:
         _TASKS[task["id"]] = task
         _save_json(paths.TASKS_DIR / (task["id"] + ".json"), task)
     return task
@@ -384,13 +419,20 @@ def create_run(kind, title, task_id=None, entry_id=None, op=None):
         "started_at": None, "ended_at": None,
         "cost_usd": 0.0, "tokens": 0, "error": "",
         "verdict": None, "summary": "",
-    }
-    rdir = paths.RUNS_DIR / run["id"]
-    (rdir / "steps").mkdir(parents=True, exist_ok=True)
-    with LOCK:
-        _RUNS[run["id"]] = run
-        _save_json(rdir / "run.json", run)
-    return run
+    }
+    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
+    return run
 
 
 def get_run(run_id):
@@ -716,11 +758,11 @@ def task_step_count(task_id):
 
 # ---------------------------------------------------------------- 故事圣经（story-bible.md）
 
-BIBLE_FILE = "story-bible.md"
-BIBLE_MAX_CHARS = 20000
+BIBLE_FILE = "story-bible.md"
+BIBLE_MAX_CHARS = 20000
 
 
-def _bible_path(workdir):
+def _bible_path(workdir):
     """工作目录内圣经文件绝对路径；目录穿越直接返回 None（不读外面任何东西）。"""
     wd = str(workdir or "").strip()
     if not wd or not os.path.isdir(wd):
@@ -729,7 +771,53 @@ def _bible_path(workdir):
     p = (root / BIBLE_FILE).resolve()
     if root != p and root not in p.parents:
         return None
-    return p
+    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):
@@ -750,30 +838,33 @@ def read_story_bible(task_id):
         return None, None, "读取失败: %s" % e
 
 
-def write_story_bible(task_id, text):
+def write_story_bible(task_id, text):
     """写入故事圣经到任务工作目录。守卫：
     - 任务不存在/工作目录越界 → 拒绝；
     - 任务正在运行（queued/running）→ 拒绝（圣经是中流砥柱，运行中不能换骨架）；
     - 文本超长（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):

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(),
+    }