codebee 0.1.0

package/app/core/catalog.py

@@ -0,0 +1,319 @@
+# -*- coding: utf-8 -*-
+"""智能体目录（catalog）：本机可管理/可编排的 CLI 清单。
+
+data/catalog.json 是唯一事实来源，首次运行自动生成；用户可直接编辑补充
+安装命令（install/upgrade）与编排模板（orch.argv_template），保存后点 UI 的
+"重新加载"或重启生效。
+"""
+from __future__ import annotations
+
+import copy
+import json
+import re
+import threading
+
+from . import paths
+
+# config.format 取值:
+#   toml-line : 按行正则读写 `model = "..."`（适合 codex config.toml）
+#   json      : 整体 JSON 读写 "model" 键（适合 claude settings.json）
+#   jsonc     : 正则读写 "model": "..."（适合 opencode.jsonc，显示为主）
+#   toml-section: 读写 TOML 指定 [section] 表下的键；model_key 写点号路径（表.键）
+#               （适合 grok 的 "models.default"）
+#   yaml-line : 按行读写 YAML 嵌套标量；model_key 写点号路径（段.键）
+#               （适合 dsh 的 "agent-default-model.model"）
+# orch.kind 取值: codex | claude | opencode | qwen | aider | generic | null
+#   null = 仅管理，不参与编排（桌面端等）
+# launch 字段（「一键打开」）：kind=web 后台起服务并自动开浏览器（command 里
+#   自带 --port 时必须与 port 一致，port 同时是就绪探测的依据）；
+#   kind=console 新开终端窗口跑交互 TUI。command 是完整命令行（cmd /c 执行）。
+DEFAULT_CATALOG = [
+    {
+        "id": "codex-cli", "name": "Codex CLI", "cli_group": "installed",
+        "note": "ChatGPT 官方编程智能体；本机走自定义 provider（gpt-5.5）",
+        "detect": {"cli": "codex"},
+        "orch": {"kind": "codex", "command": "codex"},
+        "config": {"path": "~/.codex/config.toml", "format": "toml-line", "model_key": "model"},
+        "install": "npm install -g @openai/codex",
+        "upgrade": "npm install -g @openai/codex@latest",
+        "default_enabled": True,
+    },
+    {
+        "id": "claude-code", "name": "Claude Code", "cli_group": "installed",
+        "note": "Anthropic 官方 CLI；无头调用自动注入 Git Bash 路径与输出上限",
+        "detect": {"cli": "claude"},
+        "orch": {"kind": "claude", "command": "claude"},
+        "config": {"path": "~/.claude/settings.json", "format": "json", "model_key": "model"},
+        "install": "winget install -e --id Anthropic.ClaudeCode",
+        "upgrade": "winget upgrade -e --id Anthropic.ClaudeCode",
+        "default_enabled": True,
+    },
+    {
+        "id": "opencode", "name": "OpenCode CLI", "cli_group": "installable",
+        "note": "无头模式：opencode run（stdin 传入提示词）",
+        "detect": {"cli": "opencode"},
+        "orch": {"kind": "opencode", "command": "opencode"},
+        "config": {"path": "~/.config/opencode/opencode.jsonc", "format": "jsonc", "model_key": "model"},
+        "install": "npm install -g opencode-ai",
+        "upgrade": "npm install -g opencode-ai@latest",
+        "default_enabled": False,
+    },
+    {
+        "id": "qwencode", "name": "QwenCode", "cli_group": "installable",
+        "note": "通义千问编码 CLI（gemini-cli 系）；无头走 stdin；绑定凭据经打开注入"
+                "写 settings.json 的 env 段（OPENAI_*，qwen 存在即优先 openai 兼容通道）",
+        "detect": {"cli": "qwen"},
+        "orch": {"kind": "qwen", "command": "qwen"},
+        # settings.json 顶层 "model" 已是 legacy（qwen 忽略并告警，新格式是
+        # model.name）——模型落盘由打开注入器写 OPENAI_MODEL env 负责，
+        # 这里不再走 write_model
+        "config": {"path": "~/.qwen/settings.json", "format": None, "model_key": None},
+        "install": "npm install -g @qwen-code/qwen-code",
+        "upgrade": "npm install -g @qwen-code/qwen-code@latest",
+        "default_enabled": False,
+    },
+    {
+        "id": "aider", "name": "Aider", "cli_group": "installable",
+        "note": "Python 系结对编程 CLI；用 py -3.13 安装，模型经其配置/环境变量设置",
+        "detect": {"cli": "aider"},
+        "orch": {"kind": "aider", "command": "aider"},
+        "config": {"path": "~/.aider.conf.yml", "format": None, "model_key": None},
+        "install": "py -3.13 -m pip install -U aider-chat",
+        "upgrade": "py -3.13 -m pip install -U aider-chat",
+        "default_enabled": False,
+    },
+    {
+        "id": "openclaw", "name": "OpenClaw", "cli_group": "installable",
+        "note": "网关型个人 AI 智能体（原 Clawdbot）；编排模板装好后需验证",
+        "detect": {"cli": "openclaw"},
+        "orch": {"kind": "generic", "command": "openclaw", "argv_template": ["{prompt}"]},
+        "config": {"path": "~/.openclaw/openclaw.json", "format": "json", "model_key": None},
+        "install": "npm install -g openclaw",
+        "upgrade": "npm install -g openclaw@latest",
+        "default_enabled": False,
+    },
+    {
+        "id": "kimi-code", "name": "Kimi Code", "cli_group": "installable",
+        "note": "月之暗面 Kimi 编码 CLI（TypeScript 版，需 Node ≥22.19）；旧 Python 版 kimi-cli 正在下线",
+        "detect": {"cli": "kimi"},
+        "orch": {"kind": "generic", "command": "kimi", "argv_template": ["-p", "{prompt}"]},
+        "config": {"path": "~/.kimi/config.json", "format": "json", "model_key": None},
+        "install": "npm install -g @moonshot-ai/kimi-code",
+        "upgrade": "npm install -g @moonshot-ai/kimi-code@latest",
+        "default_enabled": False,
+    },
+    {
+        "id": "mimo-code", "name": "MiMo Code", "cli_group": "installable",
+        "note": "小米 MiMo Code（opencode 衍生）；无头调用是子命令 mimo run \"提示词\"，-p 在该 CLI 是 --password",
+        "detect": {"cli": "mimo"},
+        "orch": {"kind": "generic", "command": "mimo", "argv_template": ["run", "{prompt}"],
+                 "resume_argv_template": ["run", "-s", "{session}"]},
+        "config": {"path": "~/.mimo/config.json", "format": "json", "model_key": None},
+        "install": "npm install -g @mimo-ai/cli",
+        "upgrade": "npm install -g @mimo-ai/cli@latest",
+        "default_enabled": False,
+    },
+    {
+        "id": "grok-build", "name": "Grok Build", "cli_group": "installable",
+        "note": "xAI 终端编码智能体；可执行名是 grok（不是 grok-build）；"
+                "默认模型在 ~/.grok/config.toml 的 [models] default（JSON 版配置不存在）",
+        "detect": {"cli": "grok"},
+        "orch": {"kind": "generic", "command": "grok", "argv_template": ["-p", "{prompt}"]},
+        "config": {"path": "~/.grok/config.toml", "format": "toml-section",
+                   "model_key": "models.default"},
+        "install": "npm install -g @xai-official/grok",
+        "upgrade": "npm install -g @xai-official/grok@latest",
+        "default_enabled": False,
+    },
+    {
+        "id": "pi", "name": "Pi", "cli_group": "installable",
+        "note": "Earendil Works 的 Pi 编码 CLI（需 Node ≥22.19）；包名必须带 @earendil-works/ 前缀",
+        "detect": {"cli": "pi"},
+        "orch": {"kind": "generic", "command": "pi", "argv_template": ["-p", "{prompt}"]},
+        "config": {"path": "~/.pi/config.json", "format": "json", "model_key": None},
+        "install": "npm install -g --ignore-scripts @earendil-works/pi-coding-agent",
+        "upgrade": "npm install -g --ignore-scripts @earendil-works/pi-coding-agent@latest",
+        "default_enabled": False,
+    },
+    {
+        "id": "deepseek-harness", "name": "DeepSeek Harness", "cli_group": "installable",
+        "note": "DeepSeek 官方 agent harness（dsh，profile 插件架构）；无头是「一次性任务」——"
+                "答完即退、无交互后续、不支持会话恢复；任务只走位置参数（超长提示词受 Windows "
+                "命令行上限约 32k 约束）；模型写进 ~/.dsh/settings.yaml 的 agent-default-model.model；"
+                "密钥由「CLI 绑定」注入 DEEPSEEK_API_KEY（优先级最高）；端点注入 DEEPSEEK_BASE_URL，"
+                "但若 settings.yaml 已固定 llm-deepseek.baseURL，则以它为准（settings 高于 env）",
+        "detect": {"cli": "dsh"},
+        "orch": {"kind": "generic", "command": "dsh",
+                 "argv_template": ["--profile", "headless", "{prompt}"]},
+        "config": {"path": "~/.dsh/settings.yaml", "format": "yaml-line",
+                   "model_key": "agent-default-model.model"},
+        "install": "npm install -g @deepseek-ai/dsh",
+        "upgrade": "npm install -g @deepseek-ai/dsh@latest",
+        "default_enabled": False,
+    },
+]
+
+_LOCK = threading.RLock()
+_CACHE = {"entries": None}
+
+# generic 类 CLI 实测出会话恢复方式后在这里登记（{session}/{prompt} 占位），
+# load() 幂等补进已有 data/catalog.json——用户手改过的字段不覆盖。
+ORCH_RESUME_PATCH = {
+    "mimo-code": ["run", "-s", "{session}"],
+}
+
+# 「一键打开」配置（{id: launch 字段}）：load() 幂等补进没有 launch 的条目，
+# 用户在 data/catalog.json 里手写过的 launch 不覆盖。
+LAUNCH_PATCH = {    "codex-cli": {"kind": "console", "command": "codex"},
+    "claude-code": {"kind": "console", "command": "claude"},
+    "opencode": {"kind": "console", "command": "opencode"},
+    "qwencode": {"kind": "console", "command": "qwen"},
+    "aider": {"kind": "console", "command": "aider"},
+    "openclaw": {"kind": "console", "command": "openclaw"},
+    "kimi-code": {"kind": "console", "command": "kimi"},
+    "mimo-code": {"kind": "console", "command": "mimo"},
+    "grok-build": {"kind": "console", "command": "grok"},
+    "pi": {"kind": "console", "command": "pi"},
+    # dsh 自带浏览器 UI（dsh web）；端口固定以便「已在运行就直接开页面」的复用
+    # 判断，18790 避开 CodeBee 自身与常用测试端口。--no-open 关掉 dsh 自己开浏览器
+    # 的行为（否则它会和 CodeBee 就绪后各开一个标签页）
+    "deepseek-harness": {"kind": "web",
+                         "command": "dsh web --port 18790 --no-open", "port": 18790},
+}
+
+
+# config.format 修正（{id: config 字段}）：load() 幂等覆盖。qwen 的 settings.json
+# 顶层 "model" 是 legacy（被忽略并告警）——老用户的 catalog.json 里 qwencode 还是
+# format=json，不修正的话每次打开都会写无效字段；覆盖无风险（写了也不生效）。
+CONFIG_PATCH = {
+    "qwencode": {"path": "~/.qwen/settings.json", "format": None, "model_key": None},
+    # grok 实测配置是 TOML（config.toml 的 [models] default）；早期版本错标成
+    # config.json + format=json，文件永远不存在导致「保存默认模型」必然失败——
+    # 必须覆盖修正（写 config.json 无任何效果，覆盖无风险）。
+    "grok-build": {"path": "~/.grok/config.toml", "format": "toml-section",
+                   "model_key": "models.default"},
+}
+
+
+def npm_pkg_name(cmd):
+    """从 npm 安装命令里取包名（支持 @scope/name@latest）。
+
+    跳过包名之前的 flag：`npm install -g --ignore-scripts @scope/pkg` 必须取到
+    @scope/pkg，否则「检查更新」会拿 flag 当包名去查 registry。
+    """
+    m = re.search(r"npm\s+(?:install|i)\s+(.+)$", cmd or "")
+    if not m:
+        return None
+    for tok in m.group(1).split():
+        if tok.startswith("-"):
+            continue
+        if tok.startswith("@"):
+            m2 = re.match(r"(@[^/]+/[^@]+)", tok)
+            return m2.group(1) if m2 else None
+        return tok.split("@")[0]
+    return None
+
+
+def derive_uninstall(cmd):
+    """从安装命令推导卸载命令（npm / winget / pip 三种本机渠道）。
+
+    卸载命令不单独维护一份，避免与安装命令不同步；认不出渠道返回 None，
+    此时条目可显式配置 uninstall 字段覆盖。
+    """
+    c = (cmd or "").strip()
+    m = re.search(r"npm\s+(?:install|i)\s+(.+)$", c)
+    if m:
+        pkg = npm_pkg_name(c)
+        return "npm uninstall -g %s" % pkg if pkg else None
+    m = re.search(r"winget\s+install\b(.*)$", c)
+    if m:
+        return ("winget uninstall" + m.group(1)).strip() or None
+    m = re.search(r"((?:py\s+-[\d.]+|python3?|pip3?)\s+(?:-m\s+)?pip\s+install)\s+(.+)$", c)
+    if m:
+        # 去掉 -U / --upgrade 等 flag，只留包名
+        pkgs = [t for t in m.group(2).split() if not t.startswith("-")]
+        if pkgs:
+            head = m.group(1).replace("pip install", "pip uninstall")
+            return "%s -y %s" % (head, pkgs[0])
+    return None
+
+
+def uninstall_command(entry):
+    """该条目的卸载命令：catalog 显式配置优先，否则由 install/upgrade 推导。"""
+    explicit = (entry.get("uninstall") or "").strip()
+    if explicit:
+        return explicit
+    return derive_uninstall(entry.get("install") or entry.get("upgrade") or "")
+
+
+def _apply_resume_patch(entries):
+    for e in entries:
+        tmpl = ORCH_RESUME_PATCH.get(e.get("id"))
+        orch = e.get("orch")
+        if tmpl and isinstance(orch, dict) and orch.get("kind") == "generic" \
+                and "resume_argv_template" not in orch:
+            orch["resume_argv_template"] = list(tmpl)
+
+
+def _apply_launch_patch(entries):
+    for e in entries:
+        if e.get("id") in LAUNCH_PATCH and not e.get("launch"):
+            e["launch"] = dict(LAUNCH_PATCH[e["id"]])
+
+
+def _apply_config_patch(entries):
+    for e in entries:
+        patch = CONFIG_PATCH.get(e.get("id"))
+        if patch and e.get("config") != patch:
+            e["config"] = dict(patch)
+
+
+def _merge_new_defaults(entries):
+    """把内置默认里「新增的」条目补进已加载清单（同 id 已存在则原样保留）。
+
+    data/catalog.json 一旦生成就不会再重写，因此后来版本新增的智能体（如
+    deepseek-harness）不会自动出现在老用户的清单里；这里按 id 做幂等补齐。
+    只补缺失的 id，不动已有条目，也不回写用户文件（与 _apply_resume_patch 一致）。
+
+    深拷贝是必须的：_apply_resume_patch 会就地改 entry["orch"]，浅拷贝会让
+    这些改动写回 DEFAULT_CATALOG，进而污染 reset_to_default() 的产物。
+    """
+    have = {e.get("id") for e in entries}
+    for d in DEFAULT_CATALOG:
+        if d.get("id") not in have:
+            entries.append(copy.deepcopy(d))
+
+
+def load(force=False):
+    with _LOCK:
+        if _CACHE["entries"] is not None and not force:
+            return _CACHE["entries"]
+        paths.ensure_dirs()
+        if not paths.CATALOG_FILE.exists():
+            paths.CATALOG_FILE.write_text(
+                json.dumps(DEFAULT_CATALOG, ensure_ascii=False, indent=2), encoding="utf-8")
+        try:
+            entries = json.loads(paths.CATALOG_FILE.read_text(encoding="utf-8"))
+        except Exception:
+            entries = copy.deepcopy(DEFAULT_CATALOG)
+        _merge_new_defaults(entries)
+        _apply_resume_patch(entries)
+        _apply_launch_patch(entries)
+        _apply_config_patch(entries)
+        _CACHE["entries"] = entries
+        return entries
+
+
+def by_id(entry_id):
+    for e in load():
+        if e.get("id") == entry_id:
+            return e
+    return None
+
+
+def reset_to_default():
+    """把 catalog.json 恢复为内置默认（用户改坏时的逃生门）。"""
+    with _LOCK:
+        paths.CATALOG_FILE.write_text(
+            json.dumps(DEFAULT_CATALOG, ensure_ascii=False, indent=2), encoding="utf-8")
+        _CACHE["entries"] = None

package/app/core/compaction.py

@@ -0,0 +1,186 @@
+# -*- coding: utf-8 -*-
+"""三段式上下文压缩：工具结果剪枝 → LLM 摘要 → surface replace。
+
+设计稿：docs/migration/02-context-compaction.md §1B。
+参考 dsh：
+  packages/compaction/compaction-basic/src/region.ts:117-155（selectCompactableRange：
+    跳过 system 头、保留尾预算、不切断 tool call/result 配对）
+  packages/compaction/compaction-tool-result-pruner/src/index.ts:83-122（头尾剪枝）
+  packages/compaction/compaction-basic/src/region.ts:173-275（压缩事务四件事件：
+    compaction/start → summary → user/message(replace) → end；失败仍写 end 保证日志可见）
+
+触发：maybe_compact() 检查 token_meter 压力比 ≥ 阈值才动手。
+"""
+from __future__ import annotations
+
+import logging
+
+from .token_meter import token_meter, DEFAULT_PRESSURE_THRESHOLD
+
+log = logging.getLogger(__name__)
+
+# 工具结果剪枝参数（字符数；dsh 默认 8192/4096，单行 marker）
+PRUNE_HEAD = 8192
+PRUNE_TAIL = 4096
+PRUNE_MARKER = "\n…[中间内容已剪枝，原文见会话日志]…\n"
+
+# 尾部保留预算（估算 token）
+RETAIN_TAIL_TOKENS = 8000
+# 单次压缩区域上限（事件数，防一次吞太多）
+MAX_REGION_EVENTS = 50
+
+
+def estimate_tokens(text: str) -> int:
+    """极简估算：4 字符/token（中文偏低估，偏保守触发）。"""
+    return max(1, len(text or "") // 4)
+
+
+def _ev_text(ev) -> str:
+    return str(ev.data.get("content") or ev.data.get("stdout") or "")
+
+
+def prune_text(text: str, *, head=PRUNE_HEAD, tail=PRUNE_TAIL, marker=PRUNE_MARKER) -> str:
+    """超长文本头尾剪枝（纯无 LLM 调用）。"""
+    if text is None:
+        return ""
+    if len(text) <= head + tail + len(marker):
+        return text
+    return text[:head] + marker + text[-tail:]
+
+
+def select_range(session, *, retain_tail_tokens=RETAIN_TAIL_TOKENS,
+                 max_region_events=MAX_REGION_EVENTS):
+    """选可压缩区域 [start_seq, end_seq]（闭区间）。
+
+    规则（仿 dsh selectCompactableRange）：
+      1. 跳过 system 头节点（从第一条 user_message 起）；
+      2. 尾部保留 retain_tail_tokens 预算不参与压缩（retain<=0 表示尾部不保留）；
+      3. 全部内容都在尾预算内 → 无可压缩区域，返回 (0, 0)；
+      4. 区域末端不能落在 tool 配对中间（回退到配对完成处）；
+      5. 区域不超过 max_region_events 个事件。
+    返回 (start_seq, end_seq)；无可压缩区域返回 (0, 0)。
+    """
+    events = session.events()
+    surface_events = [e for e in events if e.type in
+                      ("system_message", "user_message", "assistant_message")]
+    if not surface_events:
+        return 0, 0
+    first_user_seq = next((e.seq for e in surface_events
+                           if e.type == "user_message"), 0)
+    if not first_user_seq:
+        return 0, 0
+    # 尾部保留：倒推预算。tail_start_seq = 保留尾段的第一个 seq。
+    last_seq = surface_events[-1].seq
+    if retain_tail_tokens <= 0:
+        tail_start_seq = last_seq + 1  # 尾部不保留：全部可压
+    else:
+        tail_budget = 0
+        tail_start_seq = 0  # 0 表示"全部都在预算内"（无区域）
+        for ev in reversed(surface_events):
+            tail_budget += estimate_tokens(_ev_text(ev))
+            if tail_budget >= retain_tail_tokens:
+                tail_start_seq = ev.seq
+                break
+        if not tail_start_seq:
+            return 0, 0  # 预算从未被突破 → 无可压缩区域
+    # 候选区域 = [first_user_seq, tail_start_seq)
+    all_events = session.events()
+    by_seq = {e.seq: e for e in all_events}
+    end_seq = tail_start_seq - 1
+    # 不切断 tool 配对：末端若是 tool_call/tool_result，回退到最近的非 tool 事件
+    while end_seq >= first_user_seq:
+        ev = by_seq.get(end_seq)
+        if ev is None or ev.type not in ("tool_call", "tool_result"):
+            break
+        end_seq -= 1
+    # 区域事件数上限
+    region_events = [e for e in all_events
+                     if first_user_seq <= e.seq <= end_seq]
+    if len(region_events) > max_region_events:
+        end_seq = region_events[max_region_events - 1].seq
+        # 再做一次配对回退
+        while end_seq >= first_user_seq:
+            ev = by_seq.get(end_seq)
+            if ev is None or ev.type not in ("tool_call", "tool_result"):
+                break
+            end_seq -= 1
+    if end_seq < first_user_seq:
+        return 0, 0
+    return first_user_seq, end_seq
+
+
+_SUMMARY_SYSTEM = (
+    "你是会话压缩器。把以下对话历史压缩成简洁摘要，必须保留：\n"
+    "1. 关键决策与结论；2. 涉及的文件路径与命令；3. 未完成事项；\n"
+    "4. 错误信息原文。直接输出摘要正文，不要客套。"
+)
+
+
+def compact_region(session, start_seq: int, end_seq: int, llm_caller,
+                   *, reason: str = "pressure"):
+    """执行一次压缩事务（四件事件，失败仍写 compaction_end 保证日志可见）。
+
+    llm_caller(messages: list[dict]) -> str：一次 LLM 调用，返回摘要文本。
+    """
+    tx = session.append("compaction_start",
+                        {"start_seq": start_seq, "end_seq": end_seq, "reason": reason},
+                        surface_op="shadow")
+    summary = ""
+    error = ""
+    try:
+        region_events = [e for e in session.events()
+                         if start_seq <= e.seq <= end_seq]
+        # 第一段：工具结果先剪枝（省摘要调用的输入 token）
+        parts = []
+        for ev in region_events:
+            text = _ev_text(ev)
+            if ev.type == "tool_result":
+                text = prune_text(text)
+            if text.strip():
+                parts.append(f"[{ev.type}#{ev.seq}] {text}")
+        region_text = "\n\n".join(parts)
+        raw_tokens = estimate_tokens(region_text)
+        summary = llm_caller([
+            {"role": "system", "content": _SUMMARY_SYSTEM},
+            {"role": "user", "content": region_text},
+        ])
+        session.append("compaction_summary",
+                       {"raw_tokens": raw_tokens,
+                        "summary_tokens": estimate_tokens(summary),
+                        "start_seq": start_seq, "end_seq": end_seq},
+                       surface_op="shadow")
+        # surface replace：把区域折叠为一条 user 摘要消息
+        session.append("user_message", {
+            "content": f"[系统压缩摘要 {start_seq}-{end_seq}，原因 {reason}]\n{summary}",
+        }, surface_op={"op": "replace", "start_seq": start_seq, "end_seq": end_seq})
+    except Exception as e:
+        error = repr(e)
+        log.warning("compact_region failed: %s", error)
+        session.append("compaction_summary", {"error": error}, surface_op="shadow")
+    finally:
+        session.append("compaction_end",
+                       {"tx_seq": tx.seq, "error": error},
+                       surface_op="shadow")
+    return not error
+
+
+def maybe_compact(session, *, model: str = "", llm_caller=None,
+                  threshold: float = DEFAULT_PRESSURE_THRESHOLD,
+                  run_id: str = None,
+                  retain_tail_tokens: int = RETAIN_TAIL_TOKENS) -> bool:
+    """压力比 ≥ 阈值时触发一次压缩。返回是否执行了压缩。
+
+    llm_caller 缺省直接跳过（没有摘要能力就不压）。
+    """
+    if llm_caller is None:
+        return False
+    rid = run_id or session.run_id
+    ratio = token_meter.pressure_ratio(rid, model=model)
+    if ratio < threshold:
+        return False
+    start, end = select_range(session, retain_tail_tokens=retain_tail_tokens)
+    if not start:
+        return False
+    log.info("compaction triggered run=%s ratio=%.2f region=[%d,%d]",
+             rid, ratio, start, end)
+    return compact_region(session, start, end, llm_caller, reason=f"pressure={ratio:.2f}")

package/app/core/diagnostics.py

@@ -0,0 +1,115 @@
+# -*- coding: utf-8 -*-
+"""运行时不变量注册表：质量闸门从 pytest 测试期提升到运行时。
+
+设计稿：docs/migration/01-defense-patterns.md §5F。
+参考 dsh packages/runtime-diagnostics/invariants/src/index.ts：
+  enabled/package_allowlist/package_blocklist 三过滤；失败抛 InvariantError 含 packageName。
+
+CodeBee 实施简化为单文件 + pytest 钩子（设计稿说明）；register(name, fn) 注册断言，
+run_for(source, ctx) 在指定 source 下跑所有断言并返回失败列表。
+"""
+from __future__ import annotations
+
+import logging
+import threading
+from typing import Optional
+
+log = logging.getLogger(__name__)
+
+
+class InvariantError(Exception):
+    def __init__(self, source: str, check_name: str, msg: str):
+        super().__init__(f"[{source}/{check_name}] {msg}")
+        self.source = source
+        self.check_name = check_name
+
+
+class InvariantRegistry:
+    """按 source 分组的运行时断言注册表。
+
+    source 是来源标识（如 "pipeline"/"store"），name 是断言名；
+    fn(ctx) -> Optional[str] 返回 None 表示通过，返回字符串即失败消息。
+    """
+
+    def __init__(self):
+        self._lock = threading.Lock()
+        self._checks: dict = {}  # source -> {name: fn}
+
+    def register(self, source: str, name: str, fn):
+        with self._lock:
+            self._checks.setdefault(source, {})[name] = fn
+            log.debug("invariant registered: %s/%s", source, name)
+
+    def unregister(self, source: str, name: str = None):
+        """移除断言；name=None 时清空整个 source。"""
+        with self._lock:
+            if source not in self._checks:
+                return
+            if name is None:
+                del self._checks[source]
+            else:
+                self._checks[source].pop(name, None)
+
+    def run_for(self, source: str, ctx: dict, *, fail_fast: bool = False):
+        """在 source 下跑所有断言。
+
+        Returns:
+            [(source, name, message), ...] 失败列表（空 = 全过）。
+
+        Raises:
+            InvariantError: fail_fast=True 且首个失败。
+        """
+        fails = []
+        with self._lock:
+            checks = dict(self._checks.get(source, {}))
+        for name, fn in checks.items():
+            try:
+                msg = fn(ctx)
+            except Exception as e:
+                msg = f"check raised: {e!r}"
+            if msg:
+                fails.append((source, name, msg))
+                log.warning("invariant FAIL: %s/%s: %s", source, name, msg)
+                if fail_fast:
+                    raise InvariantError(source, name, msg)
+        return fails
+
+    def list(self, source: Optional[str] = None):
+        """列出已注册的 source/name；source=None 时全部。"""
+        with self._lock:
+            if source is None:
+                return [(s, n) for s, m in self._checks.items() for n in m]
+            return [(source, n) for n in self._checks.get(source, {})]
+
+
+invariants = InvariantRegistry()  # 单例
+
+
+# === 默认 invariants ===
+def register_default_checks():
+    """注册 CodeBee 默认运行时断言。"""
+
+    def review_no_all_fail_zero(ctx):
+        """评审全部 0 分但 run 标 success → 不允许（已锁 test_quality_gates:62-75）。"""
+        if (ctx.get("review_scores")
+                and all(s == 0 for s in ctx["review_scores"])
+                and ctx.get("final_status") == "success"):
+            return "评审全部 0 分但 run 标 success"
+        return None
+
+    def step_count_consistency(ctx):
+        """实际 step 数与预期不一致。"""
+        if ctx.get("actual_steps") != ctx.get("expected_steps"):
+            return f"step count {ctx.get('actual_steps')} != expected {ctx.get('expected_steps')}"
+        return None
+
+    def ok_but_error_code(ctx):
+        """step 级：ok=True 却带非空 error_code —— 解析降级（如 codex 空输出
+        回落 stdout 尾部）被当成功，值得告警复核。"""
+        if ctx.get("ok") and ctx.get("error_code"):
+            return "step 标记成功但携带 error_code=%s（疑似降级输出）" % ctx["error_code"]
+        return None
+
+    invariants.register("pipeline", "review_no_all_fail_zero", review_no_all_fail_zero)
+    invariants.register("pipeline", "step_count_consistency", step_count_consistency)
+    invariants.register("step", "ok_but_error_code", ok_but_error_code)