codebee 0.1.73 → 0.1.76

package/app/core/manager.py

@@ -589,6 +589,30 @@ def read_model(entry):
     return None
 
 
+def _atomic_write_bytes(path, data):
+    """CLI 自家配置写盘统一走临时文件 + os.replace 原子替换。
+
+    就地 write_bytes 有「截断→重写」窗口：并行评审爆发期多个 CLI 同时被
+    拉起（bind_agent 先同步配置再 spawn），正在启动的 CLI 恰好读配置就会
+    读到半截文件——opencode 对残缺 jsonc 的反应正是打一行横幅就退出码 1
+    （2026-09-30 14:56 实案）。os.replace 原地换名，读者要么见旧要么见新。
+    """
+    path = str(path)
+    d = os.path.dirname(path) or "."
+    fd, tmp = tempfile.mkstemp(prefix=os.path.basename(path) + ".",
+                               suffix=".tmp", dir=d)
+    try:
+        with os.fdopen(fd, "wb") as fh:
+            fh.write(data)
+        os.replace(tmp, path)
+    except Exception:
+        try:
+            os.remove(tmp)
+        except OSError:
+            pass
+        raise
+
+
 def write_model(entry, model):
     """写入默认模型（改动前自动备份 .bak）。支持 toml-line / toml-section /
     json / json-path / jsonc / yaml-line。"""
@@ -623,7 +647,7 @@ def write_model(entry, model):
             # settings.json、openclaw 缺失即安全默认——官方文档明确「缺失即
             # 内置默认」）；它正是用户层覆盖的落点，缺了按需创建
             Path(path).parent.mkdir(parents=True, exist_ok=True)
-            Path(path).write_bytes(b"{}" if fmt in ("json", "json-path", "jsonc") else b"")
+            _atomic_write_bytes(path, b"{}" if fmt in ("json", "json-path", "jsonc") else b"")
         if fmt == "jsonc":
             # mimo（mimocode.jsonc）有注释，整体重解析会丢注释——复用
             # _jsonc_set 做就地片段改写（只动目标键，其余原样保留）
@@ -634,7 +658,7 @@ def write_model(entry, model):
             if not ok:
                 return {"ok": False,
                         "error": "jsonc 结构异常，未能就地写入 %s（已避免覆盖）" % path}
-            Path(path).write_bytes(new_text.encode("utf-8"))
+            _atomic_write_bytes(path, new_text.encode("utf-8"))
         elif fmt == "toml-line":
             text = _read_text(path)
             new_line = 'model = "%s"' % model
@@ -642,17 +666,17 @@ def write_model(entry, model):
                 text = re.sub(r'(?m)^\s*model\s*=\s*"[^"]*"', new_line, text)
             else:
                 text = text.rstrip("\n") + "\n" + new_line + "\n"
-            Path(path).write_bytes(text.encode("utf-8"))
+            _atomic_write_bytes(path, text.encode("utf-8"))
         elif fmt == "toml-section":
             text = _read_text(path, preserve_newlines=True)
             text = _toml_write_value(text, *_dotted_key(cfg), value=model)
-            Path(path).write_bytes(text.encode("utf-8"))
+            _atomic_write_bytes(path, text.encode("utf-8"))
         elif fmt == "yaml-line":
             # newline="" 关掉通用换行转换：文本层面看不出 \r\n 就会被静默改写成 LF，
             # 用户的 Windows 配置不该因为写个模型名而整篇换行符被替换
             text = _read_text(path, preserve_newlines=True)
             text = _yaml_write_value(text, *_yaml_model_path(cfg), value=model)
-            Path(path).write_bytes(text.encode("utf-8"))
+            _atomic_write_bytes(path, text.encode("utf-8"))
         elif fmt == "json-path":
             # openclaw（agents.defaults.model.primary）：默认模型藏在嵌套对象里，
             # 且 openclaw 对未知顶层键直接拒绝启动——绝不能写顶层 "model"
@@ -662,7 +686,7 @@ def write_model(entry, model):
             except Exception:
                 return {"ok": False, "error": "配置文件不是合法 JSON，已中止（避免覆盖）"}
             _json_path_set(data, (cfg.get("model_key") or "model").split("."), model)
-            Path(path).write_bytes(
+            _atomic_write_bytes(path,
                 json.dumps(data, ensure_ascii=False, indent=2).encode("utf-8"))
         else:
             try:
@@ -673,7 +697,7 @@ def write_model(entry, model):
             except Exception:
                 return {"ok": False, "error": "配置文件不是合法 JSON，已中止（避免覆盖）"}
             data["model"] = model
-            Path(path).write_bytes(
+            _atomic_write_bytes(path,
                 json.dumps(data, ensure_ascii=False, indent=2).encode("utf-8"))
         return {"ok": True, "model": read_model(entry)}
     except Exception as e:
@@ -835,7 +859,7 @@ def _sync_dsh_settings(entry, model, base_url):
         if text2 != text:
             if os.path.isfile(path):
                 shutil.copyfile(path, path + ".bak")
-            Path(path).write_bytes(text2.encode("utf-8"))
+            _atomic_write_bytes(path, text2.encode("utf-8"))
         return None
     except Exception as e:
         return repr(e)
@@ -992,7 +1016,7 @@ def _sync_codex_settings(entry, model, cp):
         if text2 != text:
             if os.path.isfile(path):
                 shutil.copyfile(path, path + ".bak")
-            Path(path).write_bytes(text2.encode("utf-8"))
+            _atomic_write_bytes(path, text2.encode("utf-8"))
         return None
     except Exception as e:
         return repr(e)
@@ -1209,7 +1233,7 @@ def _sync_settings_env(path, updates, remove_keys=()):
         data["env"] = env
         if os.path.isfile(path):
             shutil.copyfile(path, path + ".bak")
-        Path(path).write_bytes(json.dumps(data, ensure_ascii=False, indent=2).encode("utf-8"))
+        _atomic_write_bytes(path, json.dumps(data, ensure_ascii=False, indent=2).encode("utf-8"))
         return None
     except Exception as e:
         return repr(e)
@@ -1321,7 +1345,7 @@ def _sync_mimo_settings(entry, model, prov):
                                   json.dumps("codebee/" + model))
         if not ok:
             return "mimocode.jsonc 结构异常，未能写入 model（已避免覆盖）"
-        Path(path).write_bytes(new_text.encode("utf-8"))
+        _atomic_write_bytes(path, new_text.encode("utf-8"))
         return None
     except OSError as e:
         return "写入 mimocode.jsonc 失败：%s" % str(e)[:80]
@@ -1401,7 +1425,7 @@ def _sync_opencode_settings(entry, model, prov):
                                          json.dumps(top_perms))
             if os.path.isfile(path):
                 shutil.copyfile(path, path + ".bak")
-            Path(path).write_bytes(new_text.encode("utf-8"))
+            _atomic_write_bytes(path, new_text.encode("utf-8"))
         except Exception as e:
             errs.append("%s: %r" % (path, e))
     return "；".join(errs) or None
@@ -1475,7 +1499,7 @@ def _sync_kimi_settings(entry, model, prov):
                 new_text = top + "\n" + body + "\n" + tables
             else:
                 new_text = (body + "\n" if body else "") + managed
-            Path(path).write_bytes(new_text.encode("utf-8"))
+            _atomic_write_bytes(path, new_text.encode("utf-8"))
         except Exception as e:
             errs.append("%s: %r" % (path, e))
     return "；".join(errs) or None
@@ -1516,7 +1540,7 @@ def _pi_write_json(path, mutate):
     if os.path.isfile(path):
         shutil.copyfile(path, path + ".bak")
     Path(path).parent.mkdir(parents=True, exist_ok=True)
-    Path(path).write_bytes(
+    _atomic_write_bytes(path,
         json.dumps(data, ensure_ascii=False, indent=2).encode("utf-8"))
     return None
 

package/app/core/modelhub.py

@@ -74,6 +74,9 @@ _PROTOCOL_AUTO = "auto"
 _PROTOCOL_CHOICES = _PROTOCOLS + (_PROTOCOL_AUTO,)
 # auto 挑主协议时的偏好顺序：只挑「实测过的」wire（wire_caps），不猜。
 _WIRE_PREFERENCE = ("anthropic", "openai")
+# 新鲜失败（fresh + failed）评测条目的重探间隔：失败探针会刷新 evaluated_at，
+# 实际效果=固定 15 分钟退避一次，而不是把链锁死到 24h TTL（0930 公司OpenAI 案）。
+_FAILED_REPROBE_AFTER = 15 * 60
 
 
 def _load():
@@ -264,7 +267,12 @@ def _model_payload_ok(protocol, data, wire_api=""):
 
 
 def _evaluation_is_usable(provider_id, model=""):
-    """Unknown evidence is allowed; stale evidence is never a routing green light."""
+    """Unknown evidence is allowed; stale evidence is never a routing green light.
+
+    新鲜失败（fresh + failed）不再硬卡到 24h TTL：隔 ``_FAILED_REPROBE_AFTER``
+    秒就地重探一次。失败的探针会刷新 evaluated_at，自然形成固定间隔的退避
+    节流——2026-09-30 公司OpenAI 案：一条 10:39 的失败探针把 codex 链锁到
+    次日同时刻，网关恢复后也没有任何自动回探路径（重探只对 stale 触发）。"""
     try:
         from . import evaluation
         for kind, name in (("provider", ""), ("model", model)):
@@ -280,6 +288,14 @@ def _evaluation_is_usable(provider_id, model=""):
                 return bool(probe and probe.get("ok") and probe.get("fresh"))
             if entry and (not entry.get("ok") or entry.get("status") not in
                           ("passed", "reachable", "reachable_unverified")):
+                try:
+                    age = time.time() - float(entry.get("evaluated_at") or 0)
+                except (TypeError, ValueError):
+                    age = 0.0
+                if age >= _FAILED_REPROBE_AFTER:
+                    probe = (test_model(provider_id, model) if kind == "model" and model
+                             else test_provider(provider_id))
+                    return bool(probe and probe.get("ok") and probe.get("fresh"))
                 return False
     except Exception:
         return True
@@ -2433,9 +2449,43 @@ def bindable_protocols(agent_kind_or_id):
 _LOCAL_CRED_ONLY_TARGETS = ("gemini-cli", "codebuddy", "trae-agent")
 
 
+def _dead(reasons, text):
+    """死因速记去重追加（同供应商多条链目只留一份，防文案刷屏）。"""
+    if text not in reasons:
+        reasons.append(text)
+
+
+# 死因速记（进程内）：resolve_binding 判空链时按 CLI 记最近一次逐条死因，
+# binding_dead_msg 据此把「真实死因」钉进失败/告警文案——0930 假死链案：
+# 文案只列「停用/删除/无密钥/模型停用」四种配置猜测，真凶（健康事件作废、
+# 探针失败、协议不匹配）一个都不在文案里，用户看着「明明有可用模型」无从对账。
+_DEAD_REASONS = {}
+_DEAD_REASONS_TTL = 15 * 60.0
+
+
+def _note_dead_reasons(cli_id, items):
+    with _LOCK:
+        _DEAD_REASONS[str(cli_id or "")] = {
+            "at": time.time(),
+            "items": [str(x)[:90] for x in (items or []) if str(x).strip()][:6],
+        }
+
+
+def last_dead_reasons(cli_id):
+    """该 CLI 最近一次链解析死因（超过 TTL 视为过期不复述，防陈旧误导）。"""
+    try:
+        with _LOCK:
+            rec = _DEAD_REASONS.get(str(cli_id or ""))
+            fresh = (rec is not None
+                     and time.time() - float(rec.get("at") or 0) <= _DEAD_REASONS_TTL)
+            return list(rec.get("items") or []) if fresh else []
+    except Exception:
+        return []
+
+
 def binding_dead_msg(cli_id):
     """死链失败/告警文案（pipeline 死链闸门与本模块 sync 共用）：说明为什么
-    不回落本机默认 + 该 CLI 需要什么协议的供应商。"""
+    不回落本机默认 + 该 CLI 需要什么协议的供应商 + 最近一次解析的真实死因。"""
     try:
         protos = bindable_protocols(cli_id)
     except Exception:
@@ -2444,8 +2494,12 @@ def binding_dead_msg(cli_id):
         return ("该 CLI 暂不支持绑定链（凭据注入尚未适配，使用 CLI 本机登录态与"
                 "默认模型）；请勿为其配置供应商链")
     hint = "该 CLI 仅接受 %s 协议的已启用供应商；" % "、".join(protos)
-    return ("绑定链全部失效（链上供应商已停用/删除/无密钥，或模型已停用），"
-            "本步判失败、不回落 CLI 本机默认——%s请在「模型调度（可选）」页为该 CLI 指定已启用的供应商" % hint)
+    msg = ("绑定链全部失效（链上供应商已停用/删除/无密钥，或模型已停用），"
+           "本步判失败、不回落 CLI 本机默认——%s请在「模型调度（可选）」页为该 CLI 指定已启用的供应商" % hint)
+    reasons = last_dead_reasons(cli_id)
+    if reasons:
+        msg += "。最近一次解析死因：" + "；".join(reasons)
+    return msg
 
 
 def resolve_binding(agent_kind_or_id, difficulty="default"):
@@ -2485,6 +2539,7 @@ def resolve_binding(agent_kind_or_id, difficulty="default"):
             down_set = health.down_names()
         except Exception:
             down_set = set()
+        dead_reasons = []   # 逐条死因速记：解析为空时喂给 binding_dead_msg（0930 假死链案）
         for item in chain:
             model = (item.get("model") or "").strip()
             pid = (item.get("provider_id") or "").strip()
@@ -2497,20 +2552,38 @@ def resolve_binding(agent_kind_or_id, difficulty="default"):
                                     "no_cred": True})
                 continue
             prov = provs.get(pid)
-            if not prov or not prov.get("enabled", True) or not prov.get("api_key"):
-                continue  # 该条失效：跳过（降级链的语义就是逐条顶上）
+            label = (prov or {}).get("name") or pid
+            if not prov:
+                _dead(dead_reasons, "%s：供应商已删除" % label)
+                continue
+            if not prov.get("enabled", True):
+                _dead(dead_reasons, "%s：供应商已停用" % label)
+                continue
+            if not prov.get("api_key"):
+                _dead(dead_reasons, "%s：无可用密钥" % label)
+                continue
             ep = _entry_endpoint(prov, allowed)
             if not ep:
-                continue  # 原生协议与适配过的 wire 都不匹配：跳过
+                proto = prov.get("protocol") or "auto"
+                _dead(dead_reasons, "%s：协议不匹配（%s，该 CLI 仅接受 %s）"
+                      % (label, proto if proto != "auto" else "auto 未探出可用 wire",
+                         "、".join(allowed)))
+                continue
             if prov.get("name") in down_set:
+                _dead(dead_reasons, "%s：健康监测判定 down" % label)
                 continue  # 健康监测判定 down：跳过，省掉无效等待
             if not _evaluation_is_usable(pid, model):
+                _dead(dead_reasons, "%s：评测结论不可用（健康事件作废或探针失败）"
+                      % label)
                 continue  # 旧评测结论已过期/被健康事件作废，不能冒充绿灯
             if _is_codex_target(agent_kind_or_id) and (ep[2] == "chat" or codex_wire_blocked(prov)):
+                _dead(dead_reasons, "%s：chat wire 被 codex 剔除（codex 仅讲 responses）"
+                      % label)
                 continue  # codex 0.154+ 只讲 responses wire：chat-only 供应商在起跑前
                           # 就剔除（此前撞了才冷却 30 分钟，每轮白烧一次注定失败的
                           # 尝试——2026-09-17 续4 连载 c35 实测）
             if model and not _model_bindable(prov, model):
+                _dead(dead_reasons, "%s：模型 %s 已停用/删除" % (label, model))
                 continue  # 模型被停用/删除：该条跳过（2026-09-15 告警弹框「禁用该模型」）
             # 多 KEY：同一厂商按 KEY 展开成多条，顺序即调用顺序。欠费的 KEY 被
             # 冷却跳过（切备用），全冷却时仍留一条顶上——降级复用既有尝试循环。
@@ -2524,6 +2597,7 @@ def resolve_binding(agent_kind_or_id, difficulty="default"):
             if len(entries) >= MAX_CHAIN_ATTEMPTS:
                 break
         if not entries:
+            _note_dead_reasons(agent_kind_or_id, dead_reasons)
             return None
         # 显式难度路由开启时，解析层就是唯一排序真源；关闭时保持手工链顺序。
         if routing and tier in ("easy", "hard"):
@@ -2553,16 +2627,37 @@ def resolve_binding(agent_kind_or_id, difficulty="default"):
     if not pid:
         return None
     prov = provs.get(pid)
-    if not prov or not prov.get("enabled", True) or not prov.get("api_key"):
+    single_reasons = []
+    label = (prov or {}).get("name") or pid
+    if not prov:
+        _dead(single_reasons, "%s：供应商已删除" % label)
+        _note_dead_reasons(agent_kind_or_id, single_reasons)
+        return None
+    if not prov.get("enabled", True):
+        _dead(single_reasons, "%s：供应商已停用" % label)
+        _note_dead_reasons(agent_kind_or_id, single_reasons)
+        return None
+    if not prov.get("api_key"):
+        _dead(single_reasons, "%s：无可用密钥" % label)
+        _note_dead_reasons(agent_kind_or_id, single_reasons)
         return None
     ep = _entry_endpoint(prov, allowed)
     if not ep:
+        proto = prov.get("protocol") or "auto"
+        _dead(single_reasons, "%s：协议不匹配（%s，该 CLI 仅接受 %s）"
+              % (label, proto if proto != "auto" else "auto 未探出可用 wire",
+                 "、".join(allowed)))
+        _note_dead_reasons(agent_kind_or_id, single_reasons)
         return None  # google 只登记；dsh 只接受 OpenAI 兼容端点；未适配的不硬塞
     if not _evaluation_is_usable(pid):
+        _dead(single_reasons, "%s：评测结论不可用（健康事件作废或探针失败）" % label)
+        _note_dead_reasons(agent_kind_or_id, single_reasons)
         return None
     if _is_codex_target(agent_kind_or_id) and (ep[2] == "chat" or codex_wire_blocked(prov)):
+        _dead(single_reasons, "%s：chat wire 被 codex 剔除（codex 仅讲 responses）" % label)
+        _note_dead_reasons(agent_kind_or_id, single_reasons)
         return None  # codex 0.154+ 只讲 responses：chat-only 供应商直接判不可绑
-                     # （解析为空 → 死链闸门/路由降权接手，不浪费 CLI 尝试）
+                 # （解析为空 → 死链闸门/路由降权接手，不浪费 CLI 尝试）
     names = [m["name"] for m in _enabled_models(prov)]
     model = prov.get("model_" + tier) or "" if (routing and tier) else ""
     if not model:

package/app/core/openapi.py

@@ -0,0 +1,154 @@
+"""OpenAPI 3 contract for the stable headless CodeBee integrations."""
+
+
+def document():
+    schemas = {
+        "Error": {"type": "object", "required": ["error"], "properties": {
+            "error": {"type": "string"}, "control": {"$ref": "#/components/schemas/Control"}}},
+        "Control": {"type": "object", "properties": {
+            "mode": {"type": "string", "enum": ["free", "held"]},
+            "mine": {"type": "boolean"}, "holder": {"type": "string"},
+            "expires_in": {"type": "integer", "minimum": 0}}},
+        "TaskCreate": {"type": "object", "required": ["goal"], "properties": {
+            "type": {"type": "string"}, "title": {"type": "string"},
+            "goal": {"type": "string", "maxLength": 4000}, "workdir": {"type": "string"},
+            "acceptance_criteria": {"type": "array", "maxItems": 40,
+                                     "items": {"type": "string", "maxLength": 500}},
+            "approval_required": {"type": "boolean"}}},
+        "TaskResult": {"type": "object", "required": ["task_id", "run_id"], "properties": {
+            "task_id": {"type": "string"}, "run_id": {"type": "string"}}},
+        "Evidence": {"type": "object", "required": ["status"], "properties": {
+            "id": {"type": "string"}, "criterion": {"type": "string", "maxLength": 500},
+            "status": {"type": "string", "enum": ["passed", "failed", "unknown", "not_evaluated"]},
+            "summary": {"type": "string", "maxLength": 2000},
+            "source": {"type": "string", "maxLength": 80}, "created_at": {"type": "string"}}},
+        "Contract": {"type": "object", "properties": {
+            "task_id": {"type": "string"},
+            "acceptance_criteria": {"type": "array", "items": {"type": "string"}},
+            "evidence": {"type": "array", "items": {"$ref": "#/components/schemas/Evidence"}},
+            "approval_required": {"type": "boolean"}, "approval": {"type": "object"},
+            "blocked_reason": {"type": "string"}, "completion_receipt": {"type": "object"}}},
+        "StoryChapter": {"type": "object", "properties": {
+                "op": {"type": "string"},
+                "chapter": {"type": "integer", "minimum": 1, "maximum": 5000},
+                "outline": {"type": "string", "maxLength": 12000}, "prose": {"type": "string"},
+                "facts": {"type": "array", "items": {"type": "string"}},
+                "characters": {"type": "array", "items": {"type": "string"}},
+                "timeline": {"type": "array", "items": {"type": "string"}},
+                "foreshadowing": {"type": "array", "items": {"type": "object"}},
+                "next_promises": {"type": "array", "items": {"type": "string"}},
+                "author_truth": {"type": "array", "items": {"type": "string"}},
+                "reader_known": {"type": "array", "items": {"type": "string"}}},
+            "oneOf": [
+                {"required": ["op"], "properties": {"op": {"const": "init"}}},
+                {"required": ["chapter", "outline", "prose"]},
+            ]},
+        "StoryTrackingResult": {"type": "object", "properties": {
+            "state": {"type": "object"}, "check": {"type": "object"}}},
+        "Presence": {"type": "object", "required": ["agent_id"], "properties": {
+            "agent_id": {"type": "string", "maxLength": 100}, "label": {"type": "string", "maxLength": 120},
+            "capabilities": {"type": "array", "maxItems": 30,
+                              "items": {"type": "string", "maxLength": 80}},
+            "task_id": {"type": "string", "maxLength": 100}, "status": {"type": "string", "maxLength": 30},
+            "metadata": {"type": "object"}}},
+    }
+
+    def body(schema):
+        return {"required": True, "content": {"application/json": {"schema": schema}}}
+
+    def response(description, schema=None):
+        out = {"description": description}
+        if schema is not None:
+            out["content"] = {"application/json": {"schema": schema}}
+        return out
+
+    ref = lambda name: {"$ref": "#/components/schemas/" + name}
+    security = [{"codebeeToken": []}, {"codebeeQueryToken": []}]
+    errors = {code: response(desc, ref("Error")) for code, desc in (
+        ("400", "请求无效"), ("401", "缺少或错误的访问令牌"),
+        ("404", "资源不存在"), ("409", "状态冲突或审批未完成"),
+        ("423", "其他设备持有控制权"))}
+    ok = response("成功", {"type": "object", "properties": {"ok": {"type": "boolean"}}})
+
+    paths = {
+        "/api/tasks": {"post": {"summary": "创建并启动任务", "security": security,
+            "requestBody": body(ref("TaskCreate")),
+            "responses": {"200": response("已排队", ref("TaskResult")),
+                          "503": response("运行记录或入队失败", ref("Error")), **errors}}},
+        "/api/a2a/tasks": {"post": {"summary": "A2A-lite 创建任务", "security": security,
+            "requestBody": body(ref("TaskCreate")),
+            "responses": {"200": response("已排队", ref("TaskResult")), "400": errors["400"],
+                          "401": errors["401"], "423": errors["423"]}}},
+        "/api/a2a/tasks/{task_id}": {"get": {"summary": "A2A-lite 读取任务状态", "security": security,
+            "responses": {"200": response("任务、运行和契约", {"type": "object"}),
+                          "401": errors["401"], "404": errors["404"]}}},
+        "/api/tasks/{task_id}/detail": {"get": {"summary": "读取任务详情和契约", "security": security,
+            "responses": {"200": response("任务详情", {"type": "object"}), "401": errors["401"], "404": errors["404"]}}},
+        "/api/tasks/{task_id}/contract": {
+            "get": {"summary": "读取任务契约", "security": security,
+                    "responses": {"200": response("契约", ref("Contract")), "401": errors["401"], "404": errors["404"]}},
+            "post": {"summary": "更新契约、追加证据或审批任务", "security": security,
+                     "requestBody": body({"type": "object", "properties": {
+                         "op": {"type": "string", "enum": ["update", "create", "evidence", "approve", "reject", "blocked"]},
+                         "acceptance_criteria": {"type": "array", "items": {"type": "string"}},
+                         "approval_required": {"type": "boolean"}, "evidence": ref("Evidence"),
+                         "note": {"type": "string", "maxLength": 1000}, "reason": {"type": "string", "maxLength": 1000}}}),
+                     "responses": {"200": response("契约已更新", {"type": "object", "properties": {"contract": ref("Contract")}}), **errors}}},
+        "/api/tasks/{task_id}/story-tracking": {
+            "get": {"summary": "读取小说追踪状态", "security": security,
+                    "responses": {"200": response("追踪状态", ref("StoryTrackingResult")), "401": errors["401"],
+                                  "404": errors["404"], "409": errors["409"]}},
+            "post": {"summary": "提交章节结构化状态", "security": security, "requestBody": body(ref("StoryChapter")),
+                     "responses": {"200": response("追踪状态已更新", ref("StoryTrackingResult")), **errors}}},
+        "/api/agents/presence": {
+            "get": {"summary": "Agent 在线状态", "security": security,
+                    "responses": {"200": response("在线 Agent 列表", {"type": "object"}), "401": errors["401"]}},
+            "post": {"summary": "Agent 心跳", "security": security, "requestBody": body(ref("Presence")),
+                     "responses": {"200": response("心跳已记录", {"type": "object"}), "400": errors["400"],
+                                  "401": errors["401"], "423": errors["423"]}}},
+        "/api/retrieval/search": {"get": {"summary": "本地检索", "security": security,
+            "parameters": [{"name": "q", "in": "query", "required": True,
+                            "schema": {"type": "string", "maxLength": 500}},
+                           {"name": "limit", "in": "query",
+                            "schema": {"type": "integer", "minimum": 1, "maximum": 50}}],
+            "responses": {"200": response("检索结果", {"type": "object"}), "400": errors["400"], "401": errors["401"]}}},
+        "/api/retrieval/index": {"post": {"summary": "为配置工作区/任务目录建立本地检索索引", "security": security,
+            "requestBody": body({"type": "object", "properties": {
+                "source": {"type": "string"}, "text": {"type": "string"}, "metadata": {"type": "object"},
+                "doc_id": {"type": "string"}, "root": {"type": "string"}, "task_id": {"type": "string"},
+                "limit": {"type": "integer", "minimum": 1, "maximum": 500}}}),
+            "responses": {"200": response("索引已更新", {"type": "object"}), "400": errors["400"],
+                          "401": errors["401"], "404": errors["404"], "423": errors["423"]}}},
+        "/api/analytics": {"get": {"summary": "任务成本质量分析", "security": security,
+            "responses": {"200": response("分析摘要", {"type": "object"}), "401": errors["401"]}}},
+        "/api/runs/{run_id}": {"get": {"summary": "读取运行状态", "security": security,
+            "responses": {"200": response("运行状态", {"type": "object"}), "401": errors["401"], "404": errors["404"]}}},
+        "/api/runs/{run_id}/resume_now": {"post": {"summary": "立即重试运行", "security": security,
+            "responses": {"200": ok, "400": errors["400"], "401": errors["401"], "404": errors["404"], "423": errors["423"]}}},
+        "/api/control": {
+            "get": {"summary": "读取当前控制权", "security": security,
+                    "responses": {"200": response("控制权状态", {"type": "object"}), "401": errors["401"]}},
+            "post": {"summary": "接管或释放控制权", "security": security,
+                     "requestBody": body({"type": "object", "required": ["action"], "properties": {
+                         "action": {"type": "string", "enum": ["acquire", "release"]},
+                         "force": {"type": "boolean"}}}),
+                     "responses": {"200": response("控制权已更新", {"type": "object"}),
+                                   "400": errors["400"], "401": errors["401"], "423": errors["423"]}}},
+        "/api/control/heartbeat": {
+            "get": {"summary": "续期当前控制权", "security": security,
+                    "responses": {"200": response("控制权状态", {"type": "object"}), "401": errors["401"]}},
+            "post": {"summary": "续期当前控制权", "security": security,
+                     "responses": {"200": response("控制权状态", {"type": "object"}), "401": errors["401"]}}},
+        "/api/openapi.json": {"get": {"summary": "读取 OpenAPI 文档", "security": security,
+            "responses": {"200": response("OpenAPI 文档", {"type": "object"}), "401": errors["401"]}}},
+        "/api/health": {"get": {"summary": "读取服务健康状态", "security": security,
+            "responses": {"200": response("健康状态", {"type": "object"}), "401": errors["401"]}}},
+        "/api/state": {"get": {"summary": "读取任务状态聚合", "security": security,
+            "responses": {"200": response("状态聚合", {"type": "object"}), "401": errors["401"]}}},
+    }
+    return {"openapi": "3.0.3", "info": {"title": "CodeBee API", "version": "1.0",
+        "description": "本机/局域网 API。远程请求需 X-CodeBee-Token 或 token 查询参数；本机 loopback 默认免令牌。"},
+        "servers": [{"url": "/"}], "components": {"securitySchemes": {
+            "codebeeToken": {"type": "apiKey", "in": "header", "name": "X-CodeBee-Token"},
+            "codebeeQueryToken": {"type": "apiKey", "in": "query", "name": "token"}},
+            "schemas": schemas}, "paths": paths}