codebee 0.1.73 → 0.1.74

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}

package/app/core/pipeline.py

@@ -2862,6 +2862,27 @@ def _run_serial_review(run, task, agents, ev, stats, mode, critics, impl, route,
 
     refresh_actual_route(impl)
     workdir = task["workdir"]
+    # Long-form state is a deterministic input to every chapter.  Bootstrap
+    # legacy serial tasks once, then refuse to write over manually edited
+    # derived views until the author reconciles the source JSON.
+    from . import story_tracking
+    try:
+        tracking_state = story_tracking.load(workdir)
+        if tracking_state is None:
+            story_tracking.init(workdir, task.get("id"), task.get("title"),
+                                premise=task.get("goal") or "")
+        tracking_check = story_tracking.check(workdir)
+    except Exception as exc:
+        store.update_run(run_id, expected_status="running", status="failed",
+                         error="故事追踪状态不可用，请先修复：%s" % str(exc)[:500],
+                         ended_at=_now())
+        return
+    if not tracking_check.get("ok"):
+        store.update_run(run_id, expected_status="running", status="failed",
+                         error="故事追踪状态存在漂移，请先修复：%s" %
+                               "；".join(tracking_check.get("errors") or [])[:500],
+                         ended_at=_now())
+        return
     # 续会话步骤的 CLI 启动目录（稿件读写仍用 workdir）
     step_wd = _resume_workdir(resume_ctx, workdir) if resume_ctx else workdir
     serial = task.get("serial") or {}
@@ -3840,6 +3861,26 @@ def _run_serial_review(run, task, agents, ev, stats, mode, critics, impl, route,
         chapter_scores.append(cs_new)
         # 每章即时持久化：长篇中断/超时后可断点续跑，不丢已完成章的分数
         store.update_run(run_id, chapter_scores=chapter_scores)
+        # Structured story state is committed alongside the chapter.  The
+        # pipeline remains compatible with legacy workdirs: a tracking failure
+        # is reported in the run evidence but never deletes a valid chapter.
+        try:
+            from . import story_tracking
+            story_tracking.commit_chapter(
+                workdir, i, outline_txt, _read_chapter(workdir, i),
+                facts=[str(x.get("note") or "") for x in issues_all
+                       if isinstance(x, dict) and x.get("chapter") == i and x.get("note")],
+                foreshadowing=[{"id": "F-%04d-%02d" % (i, n + 1),
+                                "text": str(line)[:400], "status": "active",
+                                "planted_chapter": i}
+                               for n, line in enumerate(ledger_lines[:20])],
+                next_promises=[ch.get("hook") or ch.get("highlight") or ""],
+            )
+        except Exception as exc:
+            try:
+                store.update_run(run_id, story_tracking_warning=str(exc)[:300])
+            except Exception:
+                pass
         # 资源账本（借鉴角色资源账本）：评审提出的道具/伤情/承诺/伏笔增量
         # 追加到 .codebee/resource-ledger.md，下一章起草时注入，防跨章穿帮。
         # 失败静默——账本是增强不是硬依赖。

package/app/core/presence.py

@@ -0,0 +1,77 @@
+"""Small local agent presence registry for the operator dashboard."""
+from __future__ import annotations
+
+import json
+import threading
+import time
+
+from . import paths
+
+_LOCK = threading.RLock()
+_FILE = paths.DATA_DIR / "agent_presence.json"
+_STALE_S = 180
+
+
+def _load():
+    try:
+        value = json.loads(_FILE.read_text(encoding="utf-8"))
+        return value if isinstance(value, dict) else {}
+    except Exception:
+        return {}
+
+
+def _save(value):
+    _FILE.parent.mkdir(parents=True, exist_ok=True)
+    tmp = _FILE.with_suffix(".tmp")
+    tmp.write_text(json.dumps(value, ensure_ascii=False, indent=2), encoding="utf-8")
+    tmp.replace(_FILE)
+
+
+def heartbeat(agent_id, label="", capabilities=None, task_id="", status="idle", metadata=None):
+    aid = str(agent_id or "").strip()[:100]
+    if not aid:
+        raise ValueError("agent_id 必填")
+    if capabilities is not None and not isinstance(capabilities, list):
+        raise ValueError("capabilities 必须是列表")
+    if status is not None and not isinstance(status, str):
+        raise ValueError("status 必须是文本")
+    now = time.time()
+    with _LOCK:
+        data = _load()
+        safe_meta = metadata if isinstance(metadata, dict) else {}
+        # Presence is a hot, user-controlled endpoint; keep the durable
+        # registry bounded even when an agent sends oversized diagnostics.
+        safe_meta = {str(k)[:80]: str(v)[:500] for k, v in list(safe_meta.items())[:30]}
+        data[aid] = {"agent_id": aid, "label": str(label or aid)[:120],
+                     "capabilities": [str(x)[:80] for x in (capabilities or [])][:30],
+                     "task_id": str(task_id or "")[:100], "status": str(status or "idle")[:30],
+                     "metadata": safe_meta,
+                     "last_seen": now}
+        _save(data)
+        return data[aid]
+
+
+def list_agents():
+    now = time.time()
+    with _LOCK:
+        rows = []
+        for row in _load().values():
+            item = dict(row)
+            try:
+                last_seen = float(item.get("last_seen") or 0)
+            except (TypeError, ValueError):
+                last_seen = 0.0
+            age = max(0, now - last_seen)
+            item["age_s"] = int(age)
+            item["online"] = age <= _STALE_S
+            rows.append(item)
+        return sorted(rows, key=lambda x: (not x["online"], x.get("label") or ""))
+
+
+def remove(agent_id):
+    with _LOCK:
+        data = _load()
+        existed = str(agent_id or "") in data
+        data.pop(str(agent_id or ""), None)
+        _save(data)
+        return existed

package/app/core/publish/auto.py

@@ -186,6 +186,11 @@ def publish_pending_async(task_id, platform, auto_submit=False, force=False,
     task = store.get_task(task_id)
     if not task:
         return False, "任务不存在"
+    from .. import contracts
+    contract = contracts.get(task_id)
+    if ((contract and contract.get("approval_required")) or task.get("approval_required")) \
+            and not contracts.release_allowed(task_id):
+        return False, "任务需要先完成审批，才能发布产物"
     book = ledger.book_for(task_id, platform)
     if not book:
         return False, "该任务尚未在此平台建书，请先「创建作品」"
@@ -359,6 +364,12 @@ def due_tasks(now=None):
         ap = task.get("auto_publish")
         if not isinstance(ap, dict) or not ap.get("enabled"):
             continue
+        if ap.get("auto_submit"):
+            from .. import contracts
+            contract = contracts.get(task["id"])
+            if ((contract and contract.get("approval_required")) or
+                    task.get("approval_required")) and not contracts.release_allowed(task["id"]):
+                continue
         if str(ap.get("time") or "") <= hhmm_now and fired.get(task["id"]) != today:
             plat = ap.get("platform")
             if plat and _book_ready(ledger.book_for(task["id"], plat)):

package/app/core/retrieval.py

@@ -0,0 +1,137 @@
+"""Dependency-free retrieval index with traceable keyword scoring.
+
+This is intentionally a RAG-lite layer: SQLite/vector backends can be added
+later without changing the API contract. Every hit carries its source and the
+terms that caused the match.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import threading
+from pathlib import Path
+
+from . import paths
+
+_LOCK = threading.RLock()
+_FILE = paths.DATA_DIR / "retrieval_index.json"
+_WORD_RE = re.compile(r"[A-Za-z0-9_]+|[\u4e00-\u9fff]")
+_MAX_FILES = 500
+_MAX_BYTES = 20 * 1024 * 1024
+_SKIP_DIRS = {".git", "node_modules", "__pycache__", ".venv", "venv", ".idea", ".vscode"}
+
+
+def _terms(text):
+    return [x.lower() for x in _WORD_RE.findall(str(text or ""))]
+
+
+def _load():
+    try:
+        value = json.loads(_FILE.read_text(encoding="utf-8"))
+        return value if isinstance(value, dict) else {"documents": {}}
+    except Exception:
+        return {"version": 1, "documents": {}}
+
+
+def _save(value):
+    _FILE.parent.mkdir(parents=True, exist_ok=True)
+    tmp = _FILE.with_suffix(".tmp")
+    tmp.write_text(json.dumps(value, ensure_ascii=False, indent=1), encoding="utf-8")
+    tmp.replace(_FILE)
+
+
+def upsert(source, text, metadata=None, doc_id=""):
+    source = str(source or "").strip()[:500]
+    text = str(text or "").strip()
+    if not source or not text:
+        raise ValueError("source 和 text 不能为空")
+    root_hint = ""
+    if isinstance(metadata, dict):
+        root_hint = str(metadata.get("root") or "")[:500]
+    did = str(doc_id or hashlib.sha256((root_hint + "\0" + source).encode("utf-8")).hexdigest()[:20])[:100]
+    meta = metadata if isinstance(metadata, dict) else {}
+    meta = {str(k)[:80]: str(v)[:1000] for k, v in list(meta.items())[:30]}
+    row = {"id": did, "source": source, "text": text[:200000],
+           "terms": sorted(set(_terms(text))),
+           "metadata": meta}
+    with _LOCK:
+        data = _load()
+        data.setdefault("version", 1)
+        documents = data.setdefault("documents", {})
+        # Explicit IDs are client supplied; avoid silently replacing an
+        # unrelated document when two sources reuse the same short ID.
+        if did in documents and documents[did].get("source") != source:
+            suffix = hashlib.sha256((source + "\0" + text).encode("utf-8")).hexdigest()[:12]
+            did = (did[:87] + "-" + suffix)[:100]
+            row["id"] = did
+        documents[did] = row
+        _save(data)
+    return row
+
+
+def index_directory(root, extensions=(".md", ".txt", ".json"), limit=500,
+                    allowed_roots=None, max_bytes=_MAX_BYTES):
+    root = Path(root).expanduser().resolve()
+    if not root.is_dir():
+        raise ValueError("目录不存在")
+    if allowed_roots is not None:
+        roots = [Path(p).expanduser().resolve() for p in allowed_roots if p]
+        if not any(root == p or p in root.parents for p in roots):
+            raise ValueError("只能索引任务工作目录范围内的文件")
+    try:
+        file_limit = max(1, min(_MAX_FILES, int(limit)))
+    except (TypeError, ValueError):
+        raise ValueError("limit 必须是整数")
+    try:
+        byte_limit = max(1, min(_MAX_BYTES, int(max_bytes)))
+    except (TypeError, ValueError):
+        raise ValueError("max_bytes 必须是整数")
+    count = 0
+    total_bytes = 0
+    for path in root.rglob("*"):
+        if count >= file_limit or total_bytes >= byte_limit:
+            break
+        # Never follow a symlink while indexing user-controlled trees.
+        if path.is_symlink() or any(part in _SKIP_DIRS for part in path.relative_to(root).parts):
+            continue
+        if path.is_file() and path.suffix.lower() in extensions:
+            try:
+                resolved = path.resolve()
+                if resolved != root and root not in resolved.parents:
+                    continue
+                size = path.stat().st_size
+                if size > byte_limit - total_bytes:
+                    continue
+                upsert(str(path.relative_to(root)), path.read_text(encoding="utf-8", errors="replace"),
+                       {"root": str(root)})
+                count += 1
+                total_bytes += size
+            except OSError:
+                pass
+    return {"indexed": count, "bytes": total_bytes,
+            "total": len(_load().get("documents") or {})}
+
+
+def search(query, limit=10):
+    try:
+        n = max(1, min(50, int(limit or 10)))
+    except (TypeError, ValueError):
+        raise ValueError("limit 必须是整数")
+    terms = set(_terms(str(query or "")[:500]))
+    if not terms:
+        return []
+    with _LOCK:
+        docs = list((_load().get("documents") or {}).values())
+    rows = []
+    for doc in docs:
+        matched = sorted(terms.intersection(doc.get("terms") or []))
+        if not matched:
+            continue
+        score = len(matched) / max(1, len(terms))
+        rows.append({"id": doc.get("id"), "source": doc.get("source"),
+                     "score": round(score, 4), "matched_terms": matched,
+                     "snippet": str(doc.get("text") or "")[:600],
+                     "metadata": doc.get("metadata") or {}})
+    rows.sort(key=lambda x: (-x["score"], x["source"] or ""))
+    return rows[:n]