codebee 0.1.66 → 0.1.68

package/app/core/history.py

@@ -1,38 +1,38 @@
-# -*- coding: utf-8 -*-
-"""历史统计：从过往运行记录提取每个智能体在每种任务类型上的胜率，反哺路由。"""
-from __future__ import annotations
-
-from . import store
-
-
-def agent_stats(limit=200):
-    """返回 {agent_id: {task_type: {"runs": n, "wins": w}}}。"""
-    stats = {}
-
-    def bump(aid, ttype, win):
-        if not aid:
-            return
-        s = stats.setdefault(aid, {}).setdefault(ttype, {"runs": 0, "wins": 0})
-        s["runs"] += 1
-        if win:
-            s["wins"] += 1
-
-    for run in store.list_runs(limit):
-        if run.get("kind") != "orchestration":
-            continue
-        # 失败运行也要进历史（记为全负）：以前只数 done——常挂的 CLI 永远
-        # 「无历史记录」满血参选，2026-09-17 opencode 当日秒挂 3 次仍被换将
-        # 选中。cancelled 不算（用户取消非智能体之过）。
-        if run.get("status") not in ("done", "failed"):
-            continue
-        verdict = run.get("verdict") or {}
-        task = store.get_task(run.get("task_id")) if run.get("task_id") else None
-        ttype = (task or {}).get("type") or verdict.get("type")
-        if not ttype:
-            continue
-        win = run.get("status") == "done" and bool(
-            verdict.get("pass") or verdict.get("publishable"))
-        for s in run.get("steps") or []:
-            if s.get("role") in ("implement", "draft"):
-                bump(s.get("agent"), ttype, win)
-    return stats
+# -*- coding: utf-8 -*-
+"""历史统计：从过往运行记录提取每个智能体在每种任务类型上的胜率，反哺路由。"""
+from __future__ import annotations
+
+from . import store
+
+
+def agent_stats(limit=200):
+    """返回 {agent_id: {task_type: {"runs": n, "wins": w}}}。"""
+    stats = {}
+
+    def bump(aid, ttype, win):
+        if not aid:
+            return
+        s = stats.setdefault(aid, {}).setdefault(ttype, {"runs": 0, "wins": 0})
+        s["runs"] += 1
+        if win:
+            s["wins"] += 1
+
+    for run in store.list_runs(limit):
+        if run.get("kind") != "orchestration":
+            continue
+        # 失败运行也要进历史（记为全负）：以前只数 done——常挂的 CLI 永远
+        # 「无历史记录」满血参选，2026-09-17 opencode 当日秒挂 3 次仍被换将
+        # 选中。cancelled 不算（用户取消非智能体之过）。
+        if run.get("status") not in ("done", "failed"):
+            continue
+        verdict = run.get("verdict") or {}
+        task = store.get_task(run.get("task_id")) if run.get("task_id") else None
+        ttype = (task or {}).get("type") or verdict.get("type")
+        if not ttype:
+            continue
+        win = run.get("status") == "done" and bool(
+            verdict.get("pass") or verdict.get("publishable"))
+        for s in run.get("steps") or []:
+            if s.get("role") in ("implement", "draft"):
+                bump(s.get("agent"), ttype, win)
+    return stats

package/app/core/hooks.py

@@ -1,162 +1,162 @@
-# -*- coding: utf-8 -*-
-"""任务生命周期钩子（借鉴 ZCode hooks，收窄为三个事件——2026-09-22 用户立项）：
-
-- task_start     任务开跑前（编排/直连都触发）：stdout 可注入文本，追加进任务上下文
-- message_submit 用户消息送达前：stdout 可注入文本，随消息进提示词头
-- run_end        每轮运行结束：纯副作用型（回写知识库等），输出被忽略
-
-协议：钩子命令从 stdin 收 JSON（事件+上下文）；stdout 若为 {"inject": "..."}
-取该字段为注入文本，否则把非空 stdout 整体当注入文本。
-失败/超时一律静默跳过（外部脚本不稳绝不拖死编排主流程）。
-
-命令执行：shlex 分词（保 Windows 反斜杠）后走参数列表，不经 shell——
-不支持管道/重定向等 shell 语法，需要时写 .py/.bat 包装脚本。
-配置：DATA_DIR/hooks.json，纯本机设置。"""
-from __future__ import annotations
-
-import json
-import logging
-import os
-import shlex
-import subprocess
-
-from . import paths
-
-log = logging.getLogger(__name__)
-
-EVENTS = ("task_start", "message_submit", "run_end")
-_DEFAULT_TIMEOUT = 10
-_FILE = None          # 测试重绑（同 modelhub._FILE 惯例）
-
-_CREATE_NO_WINDOW = 0x08000000 if hasattr(subprocess, "CREATE_NO_WINDOW") else 0
-
-
-def _path():
-    return _FILE or (paths.DATA_DIR / "hooks.json")
-
-
-def _default_list():
-    return []
-
-
-def load_list():
-    """读钩子配置列表；损坏/缺省回落空表。"""
-    try:
-        data = json.loads(_path().read_text(encoding="utf-8"))
-        return data if isinstance(data, list) else _default_list()
-    except Exception:
-        return _default_list()
-
-
-def save_list(items):
-    """整表保存（UI 全量提交）。字段归一 + 事件白名单。"""
-    if not isinstance(items, list):
-        raise ValueError("hooks 必须是数组")
-    out = []
-    for i, h in enumerate(items):
-        if not isinstance(h, dict):
-            continue
-        name = str(h.get("name") or "").strip()[:60]
-        event = str(h.get("event") or "").strip()
-        cmd = str(h.get("cmd") or "").strip()
-        if not cmd:
-            continue
-        if event not in EVENTS:
-            raise ValueError("第 %d 条钩子 event 非法（%s）" % (i + 1, event))
-        try:
-            timeout = max(1, min(120, int(h.get("timeout_s") or _DEFAULT_TIMEOUT)))
-        except (TypeError, ValueError):
-            timeout = _DEFAULT_TIMEOUT
-        out.append({"id": str(h.get("id") or ("hk-%d" % (i + 1)))[:40],
-                    "name": name or ("钩子 %d" % (i + 1)),
-                    "event": event, "cmd": cmd,
-                    "enabled": bool(h.get("enabled", True)),
-                    "timeout_s": timeout})
-    tmp = _path().with_suffix(".tmp")
-    tmp.write_text(json.dumps(out, ensure_ascii=False, indent=1), encoding="utf-8")
-    tmp.replace(_path())
-    return out
-
-
-def _argv(cmd):
-    """命令串 → 参数列表。Windows 反斜杠路径保真（posix=False），支持引号分组；
-    分词后剥掉 token 首尾引号（CreateProcess 不认字面引号路径）。"""
-    toks = shlex.split(str(cmd or ""), posix=False)
-    out = []
-    for t in toks:
-        if len(t) >= 2 and t[0] == t[-1] and t[0] in ('"', "'"):
-            t = t[1:-1]
-        if t:
-            out.append(t)
-    return out
-
-
-def _run_one(h, payload):
-    """跑单条钩子。返回注入文本或 None（失败/超时/空输出）。"""
-    try:
-        argv = _argv(h.get("cmd"))
-    except ValueError as e:
-        log.warning("hook[%s %s] 命令解析失败：%s", h.get("name"), h.get("event"), str(e)[:120])
-        return None
-    if not argv:
-        return None
-    try:
-        # Hook input/output is a UTF-8 JSON/text protocol. Python subprocesses on
-        # Windows otherwise inherit the OEM code page and their Chinese stdout is
-        # decoded as mojibake below. Non-Python hooks ignore this variable.
-        env = os.environ.copy()
-        env["PYTHONIOENCODING"] = "utf-8"
-        proc = subprocess.run(
-            argv, shell=False,
-            input=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
-            capture_output=True, timeout=int(h.get("timeout_s") or _DEFAULT_TIMEOUT),
-            creationflags=_CREATE_NO_WINDOW, env=env)
-    except subprocess.TimeoutExpired:
-        log.warning("hook[%s %s] 超时，已跳过", h.get("name"), h.get("event"))
-        return None
-    except Exception as e:
-        log.warning("hook[%s %s] 执行失败：%s", h.get("name"), h.get("event"), str(e)[:120])
-        return None
-    out = (proc.stdout or b"").decode("utf-8", "replace").strip()
-    if not out:
-        return None
-    try:
-        data = json.loads(out)
-        if isinstance(data, dict):
-            return str(data.get("inject") or "") or None
-    except Exception:
-        pass
-    return out
-
-
-def run_event(event, ctx=None, task_id=None, run_id=None, text=None):
-    """触发事件：依次跑启用的钩子，合并注入文本。任何异常不外抛。
-
-    ctx 附带任务/运行摘要；text 仅 message_submit 时传用户消息原文。
-    返回拼接好的注入文本（可为空串）。"""
-    if event not in EVENTS:
-        return ""
-    try:
-        items = [h for h in load_list() if h.get("enabled") and h.get("event") == event]
-    except Exception:
-        return ""
-    if not items:
-        return ""
-    payload = {"event": event, "task_id": task_id or "", "run_id": run_id or "",
-               "text": text or ""}
-    if ctx is not None:
-        payload["ctx"] = ctx
-    outs = []
-    for h in items:
-        piece = _run_one(h, payload)
-        if piece:
-            outs.append(piece.strip())
-    return "\n\n".join(outs)
-
-
-def test_one(cmd, event="task_start", timeout_s=None):
-    """设置页「测试」：手动跑一条钩子，返回 (ok, 输出/错误人话)。"""
-    h = {"name": "test", "event": event if event in EVENTS else "task_start",
-         "cmd": cmd, "timeout_s": timeout_s or _DEFAULT_TIMEOUT}
-    piece = _run_one(h, {"event": h["event"], "task_id": "", "run_id": "", "text": ""})
-    return True, piece if piece else "（无输出，未注入）"
+# -*- coding: utf-8 -*-
+"""任务生命周期钩子（借鉴 ZCode hooks，收窄为三个事件——2026-09-22 用户立项）：
+
+- task_start     任务开跑前（编排/直连都触发）：stdout 可注入文本，追加进任务上下文
+- message_submit 用户消息送达前：stdout 可注入文本，随消息进提示词头
+- run_end        每轮运行结束：纯副作用型（回写知识库等），输出被忽略
+
+协议：钩子命令从 stdin 收 JSON（事件+上下文）；stdout 若为 {"inject": "..."}
+取该字段为注入文本，否则把非空 stdout 整体当注入文本。
+失败/超时一律静默跳过（外部脚本不稳绝不拖死编排主流程）。
+
+命令执行：shlex 分词（保 Windows 反斜杠）后走参数列表，不经 shell——
+不支持管道/重定向等 shell 语法，需要时写 .py/.bat 包装脚本。
+配置：DATA_DIR/hooks.json，纯本机设置。"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import shlex
+import subprocess
+
+from . import paths
+
+log = logging.getLogger(__name__)
+
+EVENTS = ("task_start", "message_submit", "run_end")
+_DEFAULT_TIMEOUT = 10
+_FILE = None          # 测试重绑（同 modelhub._FILE 惯例）
+
+_CREATE_NO_WINDOW = 0x08000000 if hasattr(subprocess, "CREATE_NO_WINDOW") else 0
+
+
+def _path():
+    return _FILE or (paths.DATA_DIR / "hooks.json")
+
+
+def _default_list():
+    return []
+
+
+def load_list():
+    """读钩子配置列表；损坏/缺省回落空表。"""
+    try:
+        data = json.loads(_path().read_text(encoding="utf-8"))
+        return data if isinstance(data, list) else _default_list()
+    except Exception:
+        return _default_list()
+
+
+def save_list(items):
+    """整表保存（UI 全量提交）。字段归一 + 事件白名单。"""
+    if not isinstance(items, list):
+        raise ValueError("hooks 必须是数组")
+    out = []
+    for i, h in enumerate(items):
+        if not isinstance(h, dict):
+            continue
+        name = str(h.get("name") or "").strip()[:60]
+        event = str(h.get("event") or "").strip()
+        cmd = str(h.get("cmd") or "").strip()
+        if not cmd:
+            continue
+        if event not in EVENTS:
+            raise ValueError("第 %d 条钩子 event 非法（%s）" % (i + 1, event))
+        try:
+            timeout = max(1, min(120, int(h.get("timeout_s") or _DEFAULT_TIMEOUT)))
+        except (TypeError, ValueError):
+            timeout = _DEFAULT_TIMEOUT
+        out.append({"id": str(h.get("id") or ("hk-%d" % (i + 1)))[:40],
+                    "name": name or ("钩子 %d" % (i + 1)),
+                    "event": event, "cmd": cmd,
+                    "enabled": bool(h.get("enabled", True)),
+                    "timeout_s": timeout})
+    tmp = _path().with_suffix(".tmp")
+    tmp.write_text(json.dumps(out, ensure_ascii=False, indent=1), encoding="utf-8")
+    tmp.replace(_path())
+    return out
+
+
+def _argv(cmd):
+    """命令串 → 参数列表。Windows 反斜杠路径保真（posix=False），支持引号分组；
+    分词后剥掉 token 首尾引号（CreateProcess 不认字面引号路径）。"""
+    toks = shlex.split(str(cmd or ""), posix=False)
+    out = []
+    for t in toks:
+        if len(t) >= 2 and t[0] == t[-1] and t[0] in ('"', "'"):
+            t = t[1:-1]
+        if t:
+            out.append(t)
+    return out
+
+
+def _run_one(h, payload):
+    """跑单条钩子。返回注入文本或 None（失败/超时/空输出）。"""
+    try:
+        argv = _argv(h.get("cmd"))
+    except ValueError as e:
+        log.warning("hook[%s %s] 命令解析失败：%s", h.get("name"), h.get("event"), str(e)[:120])
+        return None
+    if not argv:
+        return None
+    try:
+        # Hook input/output is a UTF-8 JSON/text protocol. Python subprocesses on
+        # Windows otherwise inherit the OEM code page and their Chinese stdout is
+        # decoded as mojibake below. Non-Python hooks ignore this variable.
+        env = os.environ.copy()
+        env["PYTHONIOENCODING"] = "utf-8"
+        proc = subprocess.run(
+            argv, shell=False,
+            input=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
+            capture_output=True, timeout=int(h.get("timeout_s") or _DEFAULT_TIMEOUT),
+            creationflags=_CREATE_NO_WINDOW, env=env)
+    except subprocess.TimeoutExpired:
+        log.warning("hook[%s %s] 超时，已跳过", h.get("name"), h.get("event"))
+        return None
+    except Exception as e:
+        log.warning("hook[%s %s] 执行失败：%s", h.get("name"), h.get("event"), str(e)[:120])
+        return None
+    out = (proc.stdout or b"").decode("utf-8", "replace").strip()
+    if not out:
+        return None
+    try:
+        data = json.loads(out)
+        if isinstance(data, dict):
+            return str(data.get("inject") or "") or None
+    except Exception:
+        pass
+    return out
+
+
+def run_event(event, ctx=None, task_id=None, run_id=None, text=None):
+    """触发事件：依次跑启用的钩子，合并注入文本。任何异常不外抛。
+
+    ctx 附带任务/运行摘要；text 仅 message_submit 时传用户消息原文。
+    返回拼接好的注入文本（可为空串）。"""
+    if event not in EVENTS:
+        return ""
+    try:
+        items = [h for h in load_list() if h.get("enabled") and h.get("event") == event]
+    except Exception:
+        return ""
+    if not items:
+        return ""
+    payload = {"event": event, "task_id": task_id or "", "run_id": run_id or "",
+               "text": text or ""}
+    if ctx is not None:
+        payload["ctx"] = ctx
+    outs = []
+    for h in items:
+        piece = _run_one(h, payload)
+        if piece:
+            outs.append(piece.strip())
+    return "\n\n".join(outs)
+
+
+def test_one(cmd, event="task_start", timeout_s=None):
+    """设置页「测试」：手动跑一条钩子，返回 (ok, 输出/错误人话)。"""
+    h = {"name": "test", "event": event if event in EVENTS else "task_start",
+         "cmd": cmd, "timeout_s": timeout_s or _DEFAULT_TIMEOUT}
+    piece = _run_one(h, {"event": h["event"], "task_id": "", "run_id": "", "text": ""})
+    return True, piece if piece else "（无输出，未注入）"

package/app/core/jobs.py

@@ -150,13 +150,13 @@ def _try_start_once(job):
     global _alive, _chat_alive, _seq
     from . import store
     run_id = job.get("run_id")
-    current = store.get_run(run_id)
-    if current:
-        # 先 CAS 认领持久化 run，再碰并发位。若先占位，两个调用可能分别看到
+    current = store.get_run(run_id)
+    if current:
+        # 先 CAS 认领持久化 run，再碰并发位。若先占位，两个调用可能分别看到
         # “容量已满”和“状态已变化”，把唯一 run 误收口为 failed 且无人执行。
-        changed = store.update_run(run_id, expected_status="queued",
-                                   status="running", started_at=_now(),
-                                   dispatch_mode="direct")
+        changed = store.update_run(run_id, expected_status="queued",
+                                   status="running", started_at=_now(),
+                                   dispatch_mode="direct")
         if changed is None:
             latest = store.get_run(run_id) or current
             raise DuplicateJobError("运行 %s 当前状态为 %s，拒绝重复启动" %
@@ -182,11 +182,26 @@ def _try_start_once(job):
         if not busy:
             _seq += 1
             seq = _seq
-    if busy:
-        CANCELS.pop(run_id, None)
-        return False
-
-    try:
+    if busy:
+        CANCELS.pop(run_id, None)
+        return False
+
+    # A queued run may have spent minutes waiting for a slot or resume timer.
+    # Only the successful slot owner starts the execution clock.  The CAS
+    # prevents a cancellation between slot claim and launch from being revived.
+    if current and current.get("task_id"):
+        task = store.get_task(current["task_id"])
+        if task:
+            budget_s = store._task_timeout_s(current.get("timeout_budget_s") or
+                                             task.get("timeout_s"))
+            if store.update_run(run_id, expected_status="running",
+                                timeout_budget_s=budget_s,
+                                deadline_at=time.time() + budget_s) is None:
+                _release_slot(job)
+                CANCELS.pop(run_id, None)
+                raise DuplicateJobError("运行 %s 已在启动前结束" % run_id)
+
+    try:
         threading.Thread(target=_run_job, args=(dict(job),),
                          name="job-direct-%d" % seq, daemon=True).start()
     except Exception:
@@ -324,17 +339,7 @@ def _requeue_await_slot(job, waits_left=None):
         # 带着全新重试额度重新入队，封顶永远打不中）。仍满载则续下一拍。
         with _timer_lock:
             _deferred_timers.pop(run_id, None)
-        try:
-            from . import store
-            run = store.get_run(run_id) or {}
-            deadline_at = run.get("deadline_at")
-            if deadline_at is not None and float(deadline_at) <= time.time():
-                store.update_run(run_id, expected_status="queued", status="timeout",
-                                 ended_at=_now(), error="任务总时限已到（排队等待期间）")
-                return
-        except (TypeError, ValueError, AttributeError):
-            pass
-        try:
+        try:
             started = _try_start_once(job)
         except DuplicateJobError:
             return   # 已被取消/接管/收口：补跑链到此为止
@@ -564,19 +569,31 @@ def _err_signature(err):
     return re.sub(r"\s+", " ", s).strip()[:400]
 
 
+def _serial_progress(run):
+    """连载运行的已过审章数——超时续跑的进度锚点（chapter_scores 长度）。"""
+    try:
+        return len(run.get("chapter_scores") or [])
+    except Exception:
+        return 0
+
+
 def _maybe_auto_resume(run_id):
-    """连载任务失败自动续跑：继承已完成章继续，最多 AUTO_RESUME_MAX 次。
+    """连载任务失败/超时自动续跑：继承已完成章继续，最多 AUTO_RESUME_MAX 次。
 
     真实长篇单次运行常因供应商拥堵超时中断；这里在执行线程收尾时自动续跑一次
     续跑（store.retry_task 会带上 inherit），让整个流程真正无人值守。
+    2026-09-24 戍边骑奴 9-20 案：「任务总时限已到」终态此前不续跑，
+    长篇在慢链天仍可能超过单次预算；超时也是应自动接着写的一种中断。
     同因连撞止损：续跑副本再失败时与本次失败的错误签名比对（2026-09-18
     重写任务 kimi 403 欠费案），一模一样说明退避没换来不同结果，直接落
-    终态写明死因，不再烧剩余的退避次数。
+    终态写明死因，不再烧剩余的退避次数。超时例外：错误签名恒为同一句
+    「任务总时限已到」，但每轮都在落章——本轮比上轮多过审了章就不算
+    「同因无效重试」，续跑交给次数上限兜底；两轮一章未进则照常止损。
     """
     try:
         from . import store
         run = store.get_run(run_id)
-        if not run or run.get("status") not in ("failed", "cancelled"):
+        if not run or run.get("status") not in ("failed", "cancelled", "timeout"):
             return False
         task = store.get_task(run.get("task_id")) if run.get("task_id") else None
         if not task or not task.get("serial"):
@@ -589,8 +606,11 @@ def _maybe_auto_resume(run_id):
         if prev_id:
             prev = store.get_run(prev_id)
             sig_now = _err_signature(run.get("error"))
+            timeout_progressed = (run.get("status") == "timeout"
+                                  and _serial_progress(run) > _serial_progress(prev or {}))
             if (prev and sig_now and prev.get("error")
-                    and sig_now == _err_signature(prev.get("error"))):
+                    and sig_now == _err_signature(prev.get("error"))
+                    and not timeout_progressed):
                 store.update_run(run_id, auto_resume_stopped="same_cause",
                                  error=(run.get("error") or "")
                                  + "｜自动续跑止损：连续两次失败原因相同，不再重试")

package/app/core/knowledge.py

@@ -29,7 +29,7 @@ import threading
 import time
 from pathlib import Path
 
-from . import paths, skills
+from . import paths, revisions, skills
 
 _LOCK = threading.RLock()
 _FILE = paths.DATA_DIR / "knowledge.json"
@@ -82,6 +82,29 @@ def list_entries(scope=None, status=None, tag=None, only_enabled=False):
     return items
 
 
+def revision_for_task(task) -> dict:
+    """Return approved knowledge references selected by task scope."""
+    scope = str((task or {}).get("type") or "*")
+    entries = list_entries(scope=scope, status="approved", only_enabled=True)
+    refs = []
+    for entry in entries:
+        body = entry.get("body") or ""
+        digest = revisions.content_sha256(body)
+        stored_digest = str(entry.get("content_sha256") or "")
+        drift = bool(stored_digest and stored_digest != digest)
+        refs.append({"id": entry.get("id") or "",
+                     "revision_id": (entry.get("revision_id")
+                                     if stored_digest == digest else
+                                     revisions.revision_id("kbrev", digest)) or
+                     revisions.revision_id("kbrev", digest),
+                     "content_sha256": digest,
+                     "revision_drift": drift})
+    payload = {"scope": scope, "entries": refs}
+    digest = revisions.stable_digest(payload)
+    return {"revision_id": revisions.revision_id("knowledge", digest),
+            "content_sha256": digest, "scope": scope, "entries": refs}
+
+
 def _title_sim(a, b):
     """标题近似度：字符 bigram 的包含度（交集 / 较短者，中文友好零分词）。
     用包含度而非 Jaccard：「X」vs「X 指南」的较短者完全被包含 →1.0，
@@ -131,13 +154,32 @@ def upsert_entry(scope, title, body, tags=None, source="", source_file="",
         if hit is not None:
             it = hit
             it["seen"] = int(it.get("seen") or 1) + 1
+            # 合并不吞变体标题（与教训库同款记忆卫生）：近似题吸收留痕——
+            # 溯源可见、变体措辞的后续检索有据；去重+封顶 8。
+            if title != str(it.get("title") or ""):
+                mt = it.setdefault("merged_titles", [])
+                if title not in mt:
+                    mt.append(title)
+                    del mt[:-8]
+            old_body = str(it.get("body") or "")
+            old_rev = it.get("revision_id") or ""
+            new_rev = revisions.make_revision("kbrev", body, source=source)
             if status == "approved" or it.get("status") != "approved":
+                if old_body and old_body != body:
+                    it.setdefault("revisions", []).append(
+                        revisions.revision_record(
+                            "kbrev", old_body, source=it.get("source") or "",
+                            extra={"body": old_body, "revision_id": old_rev or
+                                   revisions.revision_id("kbrev", revisions.content_sha256(old_body))}))
+                    it["revisions"] = it["revisions"][-5:]
                 it["body"] = body
+                it.update({k: new_rev[k] for k in ("revision_id", "content_sha256")})
                 if status == "approved":
                     it["status"] = "approved"
             else:
                 it.setdefault("revisions", []).append(
-                    {"at": _now(), "body": body, "source": source})
+                    revisions.revision_record("kbrev", body, source=source,
+                                               extra={"body": body}))
                 it["revisions"] = it["revisions"][-5:]   # 最多留 5 条修订候选
             for tg in tags:
                 if tg not in (it.get("tags") or []):
@@ -154,6 +196,7 @@ def upsert_entry(scope, title, body, tags=None, source="", source_file="",
             it["updated_at"] = _now()
             _save(data)
             return it
+        rev = revisions.make_revision("kbrev", body, source=source)
         it = {"id": kid, "scope": scope, "title": title, "body": body,
               "tags": tags, "status": status, "enabled": True,
               "source": source, "source_file": source_file,
@@ -161,6 +204,7 @@ def upsert_entry(scope, title, body, tags=None, source="", source_file="",
               "confidence": confidence or "medium",
               "revisions": [], "hits": 0, "seen": 1,
               "created_at": _now(), "updated_at": _now(), "kind": "knowledge"}
+        it.update({k: rev[k] for k in ("revision_id", "content_sha256")})
         items.append(it)
         _save(data)
         return it
@@ -197,7 +241,17 @@ def entry_op(entry_id, op, fields=None):
             if str(f.get("title") or "").strip():
                 hit["title"] = str(f["title"]).strip()[:80]
             if str(f.get("body") or "").strip():
-                hit["body"] = str(f["body"]).strip()[:1500]
+                new_body = str(f["body"]).strip()[:1500]
+                old_body = str(hit.get("body") or "")
+                if old_body != new_body:
+                    hit.setdefault("revisions", []).append(
+                        revisions.revision_record(
+                            "kbrev", old_body, source=hit.get("source") or "",
+                            extra={"body": old_body}))
+                    hit["revisions"] = hit["revisions"][-5:]
+                    hit["body"] = new_body
+                    hit.update({k: revisions.make_revision("kbrev", new_body)[k]
+                                for k in ("revision_id", "content_sha256")})
             if "tags" in f:
                 hit["tags"] = [str(t).strip()[:20]
                                for t in (f.get("tags") or []) if str(t).strip()][:8]