codebee 0.1.68 → 0.1.70

package/app/core/flows.py

@@ -9,10 +9,12 @@
 """
 from __future__ import annotations
 
+import base64
 import hashlib
 import json
 import re
 import threading
+import time
 
 from . import paths, volumes
 
@@ -50,7 +52,7 @@ BUILTIN_FLOWS = [
      "threshold": 7.0, "rounds": 2,
      "serial": {"chapters": 8, "words_per_chapter": 2500},
      "goal_hint": "题材/受众/卖点 + 总字数（例：2 万字都市女频，可签约平台）",
-     "note": "大纲 → 逐章起草 → 每章多维评审修订 → 全局一致性评审 → 合并（可断点续跑）"},
+     "note": "大纲 → 逐章起草 → 签约质量门禁（开篇/推进/文风/情感/节奏）→ 全局一致性评审 → 合并（可断点续跑）"},
     {"id": "article", "name": "自媒体文章", "icon": "i-news", "engine": "review", "builtin": True,
      "manuscript": "article.md",
      "rubric": ["选题与标题", "开头吸引力", "结构节奏", "平台适配", "传播性"],
@@ -296,11 +298,13 @@ def flow_drift(task):
     return {"flow": cur.get("id") or "", "pinned": pinned, "current": current}
 
 
-def upsert_flow(payload):
+def upsert_flow(payload, source="manual"):
     """新增/更新流程。返回 (flow, 错误)。
 
     - 预置流程 id：写入 overrides（可编辑、可恢复默认）；
-    - 新 id：创建自定义流程——**只需 name + engine**，其余字段留空走引擎默认。
+    - 新 id：创建自定义流程——**只需 name + engine**，其余字段留空走引擎默认；
+    - source：覆盖成因，进版本历史（manual=手动改 / import=分享码导入 /
+      restore=恢复操作顶下旧版）；语义与名字都相同则不产生历史噪音。
     """
     fid = str(payload.get("id") or "").strip()
     name = str(payload.get("name") or "").strip()
@@ -319,6 +323,7 @@ def upsert_flow(payload):
         ov.pop("id", None)
         ov["engine"] = base["engine"]   # 引擎不可改（避免语义错乱）
         merged = _apply_overrides(base, ov)
+        _push_history(fid, merged, source)
         with _LOCK:
             data = _read()
             ovs = data.get("overrides") if isinstance(data.get("overrides"), dict) else {}
@@ -362,6 +367,7 @@ def upsert_flow(payload):
     elif engine == "code":
         flow["verify_command"] = str(payload.get("verify_command") or "")[:200]
     # direct：无流程参数（目标+附件即全部输入）
+    _push_history(fid, flow, source)
     with _LOCK:
         data = _read()
         flows = data.get("flows") if isinstance(data.get("flows"), list) else []
@@ -399,3 +405,222 @@ def reset_flow(flow_id):
             data["overrides"] = ovs
             _write(data)
     return None
+
+
+# ---- 流程分享码（参考 Dify 模板中心 / n8n workflow 模板的可分发思路）----
+# 把「流程」变成可分发资产：导出为一段可粘贴的分享码，对方在任务类型管理里
+# 粘贴导入即装。码体 = 前缀 + urlsafe base64(JSON)，无签名——分享码本来就
+# 是明文可读的信封，导入时过 upsert_flow 全套规范化，坏数据进不来。
+
+_SHARE_PREFIX = "CBFLOW1."
+_SHARE_KIND = "codebee-flow"
+# 导出字段白名单：与 _EDITABLE 对齐 + 身份/展示字段。builtin 标记不导出
+# （对端是否预置由对端的 BUILTIN_FLOWS 决定，不能跨机携带）。
+_SHARE_FIELDS = ("id", "name", "engine", "icon", "goal_hint", "note",
+                 "manuscript", "rubric", "threshold", "rounds", "best_of",
+                 "serial", "draft_prompt", "critique_prompt", "verify_command")
+
+
+def export_flow_code(flow_id):
+    """导出流程为分享码。返回 (code, 错误)。"""
+    f = get_flow(str(flow_id or "").strip())
+    if not f:
+        return None, "流程不存在"
+    payload = {"kind": _SHARE_KIND, "v": 1,
+               "flow": {k: f.get(k) for k in _SHARE_FIELDS if k in f}}
+    blob = json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
+    return _SHARE_PREFIX + base64.urlsafe_b64encode(blob.encode("utf-8")).decode("ascii"), None
+
+
+def _decode_share_code(code):
+    """分享码 → (flow_in, 错误)。解码与校验共用（preview / import 两步走）。"""
+    if not isinstance(code, str) or not code.strip().startswith(_SHARE_PREFIX):
+        return None, "不是有效的 CodeBee 流程分享码（应以 %s 开头）" % _SHARE_PREFIX
+    raw = code.strip()[len(_SHARE_PREFIX):].strip()
+    try:
+        blob = base64.urlsafe_b64decode(raw + "=" * (-len(raw) % 4))
+        payload = json.loads(blob.decode("utf-8"))
+    except Exception:
+        return None, "分享码解析失败（可能被截断或篡改）"
+    if not isinstance(payload, dict) or payload.get("kind") != _SHARE_KIND:
+        return None, "分享码内容不是 CodeBee 流程"
+    flow_in = payload.get("flow")
+    if not isinstance(flow_in, dict):
+        return None, "分享码缺少流程定义"
+    if not str(flow_in.get("id") or "").strip():
+        return None, "分享码缺少流程 ID"
+    return flow_in, None
+
+
+def preview_flow_code(code):
+    """分享码两步导入的第一步：解析并预览，不落盘。
+
+    返回 (预览, 错误)：预览带流程定义摘要 + 与现有同 ID 流程的冲突提示。"""
+    flow_in, err = _decode_share_code(code)
+    if err:
+        return None, err
+    fid = str(flow_in.get("id") or "").strip()
+    existed = get_flow(fid)
+    preview = {"id": fid,
+               "name": str(flow_in.get("name") or "")[:20],
+               "engine": str(flow_in.get("engine") or "review"),
+               "rubric": flow_in.get("rubric") if isinstance(flow_in.get("rubric"), list) else [],
+               "threshold": flow_in.get("threshold"),
+               "rounds": flow_in.get("rounds"),
+               "has_prompts": bool(str(flow_in.get("draft_prompt") or "").strip()
+                                   or str(flow_in.get("critique_prompt") or "").strip()),
+               "serial": bool(isinstance(flow_in.get("serial"), dict)
+                              and flow_in.get("serial", {}).get("chapters")),
+               "exists": bool(existed),
+               "existing_name": (existed or {}).get("name") or "",
+               "builtin": bool(existed and existed.get("builtin"))}
+    return preview, None
+
+
+def import_flow_code(code):
+    """导入分享码。返回 (result, 错误)；result = {id, name, status, builtin}。
+
+    status：created=新建自定义流程；updated=覆盖已有定义（预置流程写
+    overrides，可「恢复默认」回滚）；noop=内容与现状完全一致。UI 走
+    preview_flow_code 预览确认后再进这里。"""
+    flow_in, err = _decode_share_code(code)
+    if err:
+        return None, err
+    fid = str(flow_in.get("id") or "").strip()
+    existed = get_flow(fid)
+    existed_digest = flow_digest(existed) if existed else ""
+    flow, err = upsert_flow(flow_in, source="import")
+    if err:
+        return None, err
+    if existed and flow_digest(flow) == existed_digest \
+            and flow.get("name") == existed.get("name"):
+        status = "noop"
+    else:
+        status = "updated" if existed else "created"
+    return {"id": fid, "name": flow.get("name"), "status": status,
+            "builtin": bool(existed and existed.get("builtin"))}, None
+
+
+# ---- 版本历史（Langfuse prompt management 借鉴）：提示词/参数改动可回滚 ----
+# 覆盖前的当前版自动快照进 data/flows_history.json（每流程 ≤_HISTORY_MAX 条），
+# 恢复=把历史版重新 upsert 回来；runs 已按 flow_revision（digest 前 16）对账，
+# 每版顺手给出实测战绩——「哪版提示词好用」不再靠感觉。
+
+_HISTORY_MAX = 10          # 每流程保留的历史版本数（新的顶旧的）
+
+
+def _history_read():
+    try:
+        data = json.loads((paths.DATA_DIR / "flows_history.json").read_text(encoding="utf-8"))
+        return data if isinstance(data, dict) else {}
+    except Exception:
+        return {}
+
+
+def _history_write(data):
+    paths.DATA_DIR.mkdir(parents=True, exist_ok=True)
+    tmp = paths.DATA_DIR / "flows_history.json.tmp"
+    tmp.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+    tmp.replace(paths.DATA_DIR / "flows_history.json")
+
+
+def _push_history(fid, new_flow, source):
+    """把「即将被覆盖的当前版」存进历史；语义与名字都相同则跳过（不产噪音）。"""
+    try:
+        cur = get_flow(fid)
+        if not cur:
+            return                                # 首次创建没有旧版可存
+        if flow_digest(cur) == flow_digest(new_flow) \
+                and cur.get("name") == new_flow.get("name"):
+            return
+        with _LOCK:
+            data = _history_read()
+            versions = data.get(fid) if isinstance(data.get(fid), list) else []
+            versions.insert(0, {"ts": time.strftime("%Y-%m-%d %H:%M:%S"),
+                                "source": str(source or "manual")[:16],
+                                "flow": {k: cur.get(k) for k in _SHARE_FIELDS if k in cur}})
+            data[fid] = versions[:_HISTORY_MAX]
+            _history_write(data)
+    except Exception:
+        pass                                       # 历史是增强，永远不挡保存
+
+
+_RUNS_PROVIDER = None      # main.py 启动注入 store.list_runs；flows(L0) 不反向
+                           # 依赖 store(L1)——静态图不成环（同 set_run_estimator 模式）
+
+
+def set_runs_provider(fn):
+    """注入 run 遍历器（应用入口传 store.list_runs）；未注入时版本无战绩。"""
+    global _RUNS_PROVIDER
+    _RUNS_PROVIDER = fn if callable(fn) else None
+
+
+def _flow_stats(digest16):
+    """该流程修订的实测战绩：任务数/通过率/均分（按 run 钉的 flow_revision 对账）。
+
+    均分分母只算有评分的 run；无记录返回 None。"""
+    try:
+        if not _RUNS_PROVIDER:
+            return None
+        runs = wins = scored_n = 0
+        total = 0.0
+        for run in (_RUNS_PROVIDER(limit=None) or []):
+            if not isinstance(run, dict):
+                continue
+            rev = str(((run.get("execution_snapshot") or {}).get("flow_revision")) or "")
+            if rev[:16] != digest16:
+                continue
+            runs += 1
+            v = run.get("verdict") or {}
+            if v.get("publishable") is True:
+                wins += 1
+            if isinstance(v.get("overall"), (int, float)):
+                total += float(v["overall"])
+                scored_n += 1
+        if not runs:
+            return None
+        return {"runs": runs, "pass_rate": round(wins / runs, 2),
+                "avg_overall": round(total / scored_n, 1) if scored_n else None}
+    except Exception:
+        return None
+
+
+def flow_versions(flow_id):
+    """给 UI 的版本清单：当前版在前，历史版新→旧；每版带 digest 与实测战绩。"""
+    fid = str(flow_id or "").strip()
+    out = []
+    cur = get_flow(fid)
+    if cur:
+        d = flow_digest(cur)[:16]
+        out.append({"current": True, "ts": "", "source": "current", "name": cur.get("name"),
+                    "digest": d, "stats": _flow_stats(d)})
+    for snap in _history_read().get(fid) or []:
+        d = flow_digest(snap.get("flow") or {})[:16]
+        out.append({"current": False, "ts": str(snap.get("ts") or ""),
+                    "source": str(snap.get("source") or "manual"),
+                    "name": (snap.get("flow") or {}).get("name"),
+                    "digest": d, "stats": _flow_stats(d)})
+    return out
+
+
+def restore_flow_version(flow_id, ts):
+    """恢复历史版本。返回 (flow, 错误)。
+
+    恢复动作本身也会把「被顶下来的当前版」存进历史（source=restore），
+    恢复错了还能再恢复回去；目标条目先从历史中消费掉再做 upsert——
+    ts 是秒级精度，顺序反了同秒快照会被误删。"""
+    fid = str(flow_id or "").strip()
+    ts = str(ts or "")
+    with _LOCK:
+        data = _history_read()
+        versions = data.get(fid) if isinstance(data.get(fid), list) else []
+        snap = next((s for s in versions if s.get("ts") == ts), None)
+        if snap:
+            data[fid] = [s for s in versions if s.get("ts") != ts]
+            _history_write(data)
+    if not snap:
+        return None, "历史版本不存在（可能已被消费）"
+    flow, err = upsert_flow(dict(snap.get("flow") or {}), source="restore")
+    if err:
+        return None, err
+    return flow, None

package/app/core/goal_service.py

@@ -1,168 +1,168 @@
-# -*- coding: utf-8 -*-
-"""Goal 状态外置：跨轮目标（title/描述/phase/轮次）独立于 LLM 调用持久化。
-
-设计稿：docs/migration/03-state-externalization.md §2A。
-参考 dsh packages/goal/goal/：状态 100% 来自事件溯源（goal/change 事件），
-唯一当前 goal，revision 走 CAS 拒绝陈旧引用。
-
-与 planner.py 的关系：planner 继续负责「LLM 拆解」；GoalService 只管
-「目标状态」——谁都可以读（UI/续行驱动器/流水线），变更必须过 CAS。
-"""
-from __future__ import annotations
-
-import json
-import threading
-import time
-import uuid
-from pathlib import Path
-
-_LOCK = threading.RLock()
-# goal_id -> dict（内存缓存；磁盘为唯一事实来源）
-_GOALS = {}
-_FILE = None  # 由 init() 注入
-
-
-def init(data_dir=None):
-    """注入存储路径并从磁盘加载。测试可传临时目录。"""
-    global _FILE, _GOALS
-    with _LOCK:
-        base = Path(data_dir) if data_dir else Path(_default_dir())
-        base.mkdir(parents=True, exist_ok=True)
-        _FILE = base / "goals.json"
-        _GOALS = {}
-        try:
-            data = json.loads(_FILE.read_text(encoding="utf-8"))
-            for g in data.get("goals") or []:
-                if isinstance(g, dict) and g.get("goal_id"):
-                    _GOALS[g["goal_id"]] = g
-        except (OSError, json.JSONDecodeError):
-            pass
-
-
-def _default_dir():
-    from . import paths
-    return str(paths.DATA_DIR)
-
-
-def _persist():
-    """原子写盘（tmp + replace）。调用方必须已持有 _LOCK。"""
-    if _FILE is None:
-        return
-    tmp = _FILE.with_suffix(".tmp")
-    tmp.write_text(json.dumps({"goals": list(_GOALS.values())},
-                              ensure_ascii=False, indent=2), encoding="utf-8")
-    tmp.replace(_FILE)
-
-
-class StaleRevisionError(Exception):
-    """CAS 失败：调用方持有的是陈旧 revision。"""
-
-
-class GoalExistsError(Exception):
-    """已有未完结的当前 goal，需先 complete/abandon。"""
-
-
-class GoalNotFoundError(Exception):
-    pass
-
-
-def _valid_phase(p):
-    return p in ("active", "paused", "complete", "abandoned")
-
-
-def current():
-    """返回唯一「当前」goal（未 complete/abandoned 的最新一个）；无则 None。"""
-    with _LOCK:
-        open_goals = [g for g in _GOALS.values()
-                      if g.get("phase") in ("active", "paused")]
-        if not open_goals:
-            return None
-        return max(open_goals, key=lambda g: g.get("created_at", 0))
-
-
-def get(goal_id: str):
-    with _LOCK:
-        g = _GOALS.get(goal_id)
-        return dict(g) if g else None
-
-
-def create(title: str, description: str = "", *, rounds_max: int | None = None,
-           metadata: dict | None = None) -> dict:
-    """创建新 goal。已有未完结 goal 时拒绝（单一当前目标，仿 dsh）。
-
-    rounds_max 缺省读 settings_v2 orchestrator.max_goal_rounds（读不到回落 5）。"""
-    if rounds_max is None:
-        try:
-            from .settings_schema import get as ss_get, register_default_namespaces
-            register_default_namespaces()
-            rounds_max = int(ss_get("orchestrator", "max_goal_rounds") or 5)
-        except Exception:
-            rounds_max = 5
-    with _LOCK:
-        cur = current()
-        if cur is not None:
-            raise GoalExistsError(
-                "已有进行中的 goal %s（%s），请先 complete/abandon"
-                % (cur["goal_id"], cur["title"]))
-        goal = {
-            "goal_id": "g" + uuid.uuid4().hex[:12],
-            "title": (title or "").strip(),
-            "description": (description or "").strip(),
-            "phase": "active",
-            "revision": 1,
-            "rounds_started": 0,
-            "rounds_max": max(1, int(rounds_max)),
-            "created_at": time.strftime("%Y-%m-%d %H:%M:%S"),
-            "updated_at": time.strftime("%Y-%m-%d %H:%M:%S"),
-            "metadata": dict(metadata or {}),
-        }
-        _GOALS[goal["goal_id"]] = goal
-        _persist()
-        return dict(goal)
-
-
-def update(goal_id: str, expected_revision: int, **changes) -> dict:
-    """CAS 更新：expected_revision 不匹配即抛 StaleRevisionError。
-
-    允许变更的字段：title/description/phase/rounds_max/metadata。
-    phase 只允许合法值；complete/abandoned 为终态不可再改回。
-    """
-    with _LOCK:
-        g = _GOALS.get(goal_id)
-        if not g:
-            raise GoalNotFoundError(goal_id)
-        if g["revision"] != expected_revision:
-            raise StaleRevisionError(
-                "%s 期望 rev %d，实际 %d" % (goal_id, expected_revision, g["revision"]))
-        if g["phase"] in ("complete", "abandoned"):
-            raise ValueError("goal 已终态（%s），不可再变更" % g["phase"])
-        allowed = {"title", "description", "phase", "rounds_max",
-                   "rounds_started", "metadata"}
-        for k, v in changes.items():
-            if k not in allowed:
-                raise ValueError("不可变更字段：%s" % k)
-            if k == "phase" and not _valid_phase(v):
-                raise ValueError("非法 phase：%s" % v)
-            if k == "rounds_max":
-                v = max(1, int(v))
-            g[k] = v
-        g["revision"] += 1
-        g["updated_at"] = time.strftime("%Y-%m-%d %H:%M:%S")
-        _persist()
-        return dict(g)
-
-
-def increment_rounds(goal_id: str, expected_revision: int) -> dict:
-    """轮次 +1（Goal Round Driver 专用 CAS 入口）。"""
-    with _LOCK:
-        g = _GOALS.get(goal_id)
-        if not g:
-            raise GoalNotFoundError(goal_id)
-        return update(goal_id, expected_revision, rounds_started=g["rounds_started"] + 1)
-
-
-def list_goals(limit: int = 50) -> list:
-    with _LOCK:
-        goals = sorted(_GOALS.values(),
-                       key=lambda g: g.get("created_at", ""), reverse=True)
+# -*- coding: utf-8 -*-
+"""Goal 状态外置：跨轮目标（title/描述/phase/轮次）独立于 LLM 调用持久化。
+
+设计稿：docs/migration/03-state-externalization.md §2A。
+参考 dsh packages/goal/goal/：状态 100% 来自事件溯源（goal/change 事件），
+唯一当前 goal，revision 走 CAS 拒绝陈旧引用。
+
+与 planner.py 的关系：planner 继续负责「LLM 拆解」；GoalService 只管
+「目标状态」——谁都可以读（UI/续行驱动器/流水线），变更必须过 CAS。
+"""
+from __future__ import annotations
+
+import json
+import threading
+import time
+import uuid
+from pathlib import Path
+
+_LOCK = threading.RLock()
+# goal_id -> dict（内存缓存；磁盘为唯一事实来源）
+_GOALS = {}
+_FILE = None  # 由 init() 注入
+
+
+def init(data_dir=None):
+    """注入存储路径并从磁盘加载。测试可传临时目录。"""
+    global _FILE, _GOALS
+    with _LOCK:
+        base = Path(data_dir) if data_dir else Path(_default_dir())
+        base.mkdir(parents=True, exist_ok=True)
+        _FILE = base / "goals.json"
+        _GOALS = {}
+        try:
+            data = json.loads(_FILE.read_text(encoding="utf-8"))
+            for g in data.get("goals") or []:
+                if isinstance(g, dict) and g.get("goal_id"):
+                    _GOALS[g["goal_id"]] = g
+        except (OSError, json.JSONDecodeError):
+            pass
+
+
+def _default_dir():
+    from . import paths
+    return str(paths.DATA_DIR)
+
+
+def _persist():
+    """原子写盘（tmp + replace）。调用方必须已持有 _LOCK。"""
+    if _FILE is None:
+        return
+    tmp = _FILE.with_suffix(".tmp")
+    tmp.write_text(json.dumps({"goals": list(_GOALS.values())},
+                              ensure_ascii=False, indent=2), encoding="utf-8")
+    tmp.replace(_FILE)
+
+
+class StaleRevisionError(Exception):
+    """CAS 失败：调用方持有的是陈旧 revision。"""
+
+
+class GoalExistsError(Exception):
+    """已有未完结的当前 goal，需先 complete/abandon。"""
+
+
+class GoalNotFoundError(Exception):
+    pass
+
+
+def _valid_phase(p):
+    return p in ("active", "paused", "complete", "abandoned")
+
+
+def current():
+    """返回唯一「当前」goal（未 complete/abandoned 的最新一个）；无则 None。"""
+    with _LOCK:
+        open_goals = [g for g in _GOALS.values()
+                      if g.get("phase") in ("active", "paused")]
+        if not open_goals:
+            return None
+        return max(open_goals, key=lambda g: g.get("created_at", 0))
+
+
+def get(goal_id: str):
+    with _LOCK:
+        g = _GOALS.get(goal_id)
+        return dict(g) if g else None
+
+
+def create(title: str, description: str = "", *, rounds_max: int | None = None,
+           metadata: dict | None = None) -> dict:
+    """创建新 goal。已有未完结 goal 时拒绝（单一当前目标，仿 dsh）。
+
+    rounds_max 缺省读 settings_v2 orchestrator.max_goal_rounds（读不到回落 5）。"""
+    if rounds_max is None:
+        try:
+            from .settings_schema import get as ss_get, register_default_namespaces
+            register_default_namespaces()
+            rounds_max = int(ss_get("orchestrator", "max_goal_rounds") or 5)
+        except Exception:
+            rounds_max = 5
+    with _LOCK:
+        cur = current()
+        if cur is not None:
+            raise GoalExistsError(
+                "已有进行中的 goal %s（%s），请先 complete/abandon"
+                % (cur["goal_id"], cur["title"]))
+        goal = {
+            "goal_id": "g" + uuid.uuid4().hex[:12],
+            "title": (title or "").strip(),
+            "description": (description or "").strip(),
+            "phase": "active",
+            "revision": 1,
+            "rounds_started": 0,
+            "rounds_max": max(1, int(rounds_max)),
+            "created_at": time.strftime("%Y-%m-%d %H:%M:%S"),
+            "updated_at": time.strftime("%Y-%m-%d %H:%M:%S"),
+            "metadata": dict(metadata or {}),
+        }
+        _GOALS[goal["goal_id"]] = goal
+        _persist()
+        return dict(goal)
+
+
+def update(goal_id: str, expected_revision: int, **changes) -> dict:
+    """CAS 更新：expected_revision 不匹配即抛 StaleRevisionError。
+
+    允许变更的字段：title/description/phase/rounds_max/metadata。
+    phase 只允许合法值；complete/abandoned 为终态不可再改回。
+    """
+    with _LOCK:
+        g = _GOALS.get(goal_id)
+        if not g:
+            raise GoalNotFoundError(goal_id)
+        if g["revision"] != expected_revision:
+            raise StaleRevisionError(
+                "%s 期望 rev %d，实际 %d" % (goal_id, expected_revision, g["revision"]))
+        if g["phase"] in ("complete", "abandoned"):
+            raise ValueError("goal 已终态（%s），不可再变更" % g["phase"])
+        allowed = {"title", "description", "phase", "rounds_max",
+                   "rounds_started", "metadata"}
+        for k, v in changes.items():
+            if k not in allowed:
+                raise ValueError("不可变更字段：%s" % k)
+            if k == "phase" and not _valid_phase(v):
+                raise ValueError("非法 phase：%s" % v)
+            if k == "rounds_max":
+                v = max(1, int(v))
+            g[k] = v
+        g["revision"] += 1
+        g["updated_at"] = time.strftime("%Y-%m-%d %H:%M:%S")
+        _persist()
+        return dict(g)
+
+
+def increment_rounds(goal_id: str, expected_revision: int) -> dict:
+    """轮次 +1（Goal Round Driver 专用 CAS 入口）。"""
+    with _LOCK:
+        g = _GOALS.get(goal_id)
+        if not g:
+            raise GoalNotFoundError(goal_id)
+        return update(goal_id, expected_revision, rounds_started=g["rounds_started"] + 1)
+
+
+def list_goals(limit: int = 50) -> list:
+    with _LOCK:
+        goals = sorted(_GOALS.values(),
+                       key=lambda g: g.get("created_at", ""), reverse=True)
         return [dict(g) for g in goals[:limit]]