codebee 0.1.21 → 0.1.23

package/app/core/pipeline.py

@@ -19,7 +19,7 @@ import re
 import threading
 import time
 
-from . import aiflavor, catalog, history, jobs, knowledge, manager, modelhub, mocks, paihang, planner, registry, router, runner, skills, store, usage
+from . import aiflavor, catalog, history, jobs, knowledge, manager, modelhub, mocks, paihang, planner, registry, router, runner, skills, store, task_compile, usage
 from . import builtin_agent
 from . import diagnostics
 from . import paths as paths_mod
@@ -883,6 +883,29 @@ def _code_bestof(run, task, impl, difficulty, ev):
             pass
 
 
+def _record_actual_route(run_id, task, agents, stats, implementer,
+                         implementers=(), reviewer=None, critics=(), implement_reason="",
+                         review_reason="", direct=False):
+    """把引擎实际选中的执行者/评审者回写到可解释路由计划。"""
+    spec = task.get("_compiled_spec") or task_compile.compile_task(task)
+    impl_plan = router.route_plan(
+        agents, "implement", spec, stats, selected=implementer,
+        participants=implementers,
+        selection_reason=implement_reason)
+    if direct:
+        review_plan = {"role": "review", "selected": "", "participants": [],
+                       "selection_reason": "", "candidates": [], "fallback": []}
+    else:
+        review_group = list(critics or ())
+        actual_reviewer = reviewer or (review_group[0] if review_group else None)
+        review_plan = router.route_plan(
+            agents, "review", spec, stats, selected=actual_reviewer,
+            participants=review_group, selection_reason=review_reason)
+    store.update_run(run_id, route_plan={
+        "task": spec, "implement": impl_plan, "review": review_plan,
+    })
+
+
 def _run_code(run, task, agents, ev, stats, mode):
     run_id = run["id"]
     workdir = task["workdir"]
@@ -946,6 +969,9 @@ def _run_code(run, task, agents, ev, stats, mode):
         reviewer, route["reviewer"] = router.pick_reviewer(agents, impl, "code", stats)
     else:
         reviewer, route["reviewer"] = _pick_reviewer_legacy(agents, impl)
+    _record_actual_route(run_id, task, agents, stats, impl, reviewer=reviewer,
+                         implement_reason=route.get("implementer", ""),
+                         review_reason=route.get("reviewer", ""))
     store.update_run(run_id, route=route)
 
     def implement_all(impl_agent, prefix_note):
@@ -1038,6 +1064,11 @@ def _run_code(run, task, agents, ev, stats, mode):
                 ok2, res = _run_one(other)
                 if ok2:
                     store.update_run(run_id, error="", route_note=note)
+                    _record_actual_route(
+                        run_id, task, agents, stats, other,
+                        implementers=[other], reviewer=reviewer,
+                        implement_reason=note,
+                        review_reason=route.get("reviewer", ""))
                     return True
                 res_err = "%s；换将后仍失败：%s" % (note, (res.get("error") or "")[:200])
             else:
@@ -1074,6 +1105,13 @@ def _run_code(run, task, agents, ev, stats, mode):
                             note="自动修复第 %d 轮" % round_no,
                             resume=resume_ctx["session"] if resume_ctx else impl_sid[0],
                             require_tools=True)
+            if res["ok"]:
+                _record_actual_route(
+                    run_id, task, agents, stats, impl,
+                    implementers=[impl], reviewer=reviewer,
+                    implement_reason="修复轮由 %s 完成" %
+                    (impl.get("label") or impl.get("id")),
+                    review_reason=route.get("reviewer", ""))
             if impl.get("mode") == "mock" and res["ok"]:
                 pass  # mock 不产生真实变更
         review_json, verify_pass, verify_ran = review_and_score()
@@ -1097,6 +1135,11 @@ def _run_code(run, task, agents, ev, stats, mode):
                     impl["id"], other["id"], round_no + 1, other_reason)
                 store.update_run(run_id, error="")
                 impl = other
+                _record_actual_route(
+                    run_id, task, agents, stats, impl,
+                    implementers=[impl], reviewer=reviewer,
+                    implement_reason=note,
+                    review_reason=route.get("reviewer", ""))
                 switched = True
                 round_no += 1
                 continue
@@ -1326,6 +1369,13 @@ def _run_direct(run, task, agents, ev, stats, mode):
         store.update_run(run_id, expected_status="running", status="failed",
                          error="没有可用智能体", ended_at=_now())
         return
+    actual_impl = impl or {
+        "id": "builtin:%s:%s" % (bi.get("provider_id") or "provider", bi.get("model") or "model"),
+        "label": "CodeBee · %s" % (bi.get("model") or bi.get("provider_name") or "内置模型"),
+        "kind": "builtin",
+    }
+    _record_actual_route(run_id, task, agents, stats, actual_impl,
+                         implement_reason=route.get("implementer", ""), direct=True)
     difficulty = task.get("difficulty") or "default"
     step_wd = _resume_workdir(resume_ctx, workdir) if resume_ctx else workdir
     store.update_run(run_id, route=route, difficulty=difficulty)
@@ -1860,6 +1910,31 @@ def _run_serial_review(run, task, agents, ev, stats, mode, critics, impl, route,
     """连载流水线：大纲 → 逐章起草/评审/修订 → 全局一致性评审 → 合并成书。"""
     import json as _json
     run_id = run["id"]
+    actual_implementers = [impl]
+    actual_critics = list(critics)
+    current_impl = [impl]
+    current_impl_reason = [route.get("author", "")]
+    current_review_reason = [route.get("critics", "")]
+
+    def refresh_actual_route(primary_impl=None, implement_reason=None,
+                             review_reason=None):
+        if primary_impl is not None:
+            current_impl[0] = primary_impl
+        if implement_reason is not None:
+            current_impl_reason[0] = implement_reason
+        if review_reason is not None:
+            current_review_reason[0] = review_reason
+        _record_actual_route(
+            run_id, task, agents, stats, current_impl[0],
+            implementers=actual_implementers, critics=actual_critics,
+            implement_reason=current_impl_reason[0],
+            review_reason=current_review_reason[0])
+
+    def remember_agent(bucket, agent):
+        if agent and not any(x.get("id") == agent.get("id") for x in bucket):
+            bucket.append(agent)
+
+    refresh_actual_route(impl)
     workdir = task["workdir"]
     # 续会话步骤的 CLI 启动目录（稿件读写仍用 workdir）
     step_wd = _resume_workdir(resume_ctx, workdir) if resume_ctx else workdir
@@ -2051,6 +2126,10 @@ def _run_serial_review(run, task, agents, ev, stats, mode, critics, impl, route,
                             and cj.get("scores"):
                         cj_map[spare["id"]] = cj
                         scored += 1
+                        remember_agent(actual_critics, spare)
+                        refresh_actual_route(
+                            review_reason="章节评审补位：%s" %
+                            (spare.get("label") or spare.get("id")))
                         issues_all.extend({"chapter": i, **it}
                                           for it in (cj.get("issues") or [])[:6])
                         break
@@ -2135,6 +2214,10 @@ def _run_serial_review(run, task, agents, ev, stats, mode, critics, impl, route,
                 good = False
                 txt = ""
                 use_prompt = prompt
+                chapter_impl = impl
+                chapter_reason = route.get("author", "")
+                last_attempt_impl = impl
+                last_attempt_reason = chapter_reason
                 for draft_attempt in range(3):
                     if draft_attempt:
                         # 30s / 60s 退避；ev.wait 睡等可被取消即刻唤醒
@@ -2185,6 +2268,9 @@ def _run_serial_review(run, task, agents, ev, stats, mode, critics, impl, route,
                         if not (other and other.get("mode") == "real"):
                             break
                         tried.add(other["id"])
+                        last_attempt_impl = other
+                        last_attempt_reason = "章节起草换将：%s" % (
+                            other_reason or other.get("label") or other.get("id"))
                         res = _run_step(run_id, "draft-c%d" % i,
                                         modelhub.bind_agent(other, difficulty), use_prompt,
                                         step_wd, readonly=False, ev=ev, timeout=2400,
@@ -2201,13 +2287,20 @@ def _run_serial_review(run, task, agents, ev, stats, mode, critics, impl, route,
                                 pass
                         if good:
                             draft_sid = ""   # 换将作者无本任会话，revise 另起
+                            chapter_impl = last_attempt_impl
+                            chapter_reason = last_attempt_reason
                 if not good:
                     time.sleep(3)   # 落盘竞态宽限：CLI 崩溃退出前写的文件可能晚于
                     good, txt = _chapter_state()   # 退出检查零点几秒才可见（c34 实测）
+                    if good:
+                        chapter_impl = last_attempt_impl
+                        chapter_reason = last_attempt_reason
                 if not good:
                     store.update_run(run_id, expected_status="running", status="failed",
                                      error="第 %d 章起草失败: %s" % (i, (res or {}).get("error")), ended_at=_now())
                     return
+                remember_agent(actual_implementers, chapter_impl)
+                refresh_actual_route(chapter_impl, implement_reason=chapter_reason)
                 if not res["ok"]:
                     # 成品是文件不是退出码：CLI 超时但章稿已完整落盘（终章长文实测
                     # 反复出现——文件写完、收尾声明没等到）就送评审门把关，别整章作废
@@ -2294,6 +2387,13 @@ def _run_serial_review(run, task, agents, ev, stats, mode, critics, impl, route,
                     return
                 scored_variants.sort(key=lambda v: (-v["avg"], v["variant"]))
                 win = scored_variants[0]
+                win_agent = next((a for a in pool if a.get("id") == win["agent"]), None)
+                if win_agent is not None:
+                    remember_agent(actual_implementers, win_agent)
+                    refresh_actual_route(
+                        win_agent,
+                        implement_reason="同章多稿赛马胜出：%s" %
+                        (win_agent.get("label") or win_agent.get("id")))
                 # 收敛：赢家转正，败稿删除；胜者评审结果直接作为第 1 轮（不重评）
                 if win["file"] != ch_file:
                     try:
@@ -2401,6 +2501,10 @@ def _run_serial_review(run, task, agents, ev, stats, mode, critics, impl, route,
                 _run_step(run_id, "revise-c%d" % i, modelhub.bind_agent(impl, difficulty), prompt,
                           step_wd, readonly=False, ev=ev, timeout=2400,
                           resume=resume_ctx["session"] if resume_ctx else draft_sid)
+            remember_agent(actual_implementers, impl)
+            refresh_actual_route(
+                impl, implement_reason="章节修订：%s" %
+                (impl.get("label") or impl.get("id")))
             _check_cancel(ev)
         chapter_scores.append({"chapter": i, "title": ch["title"], "means": means,
                                "passed": bool(means) and all(v >= threshold_ch for v in means.values()),
@@ -2477,6 +2581,10 @@ def _run_serial_review(run, task, agents, ev, stats, mode, critics, impl, route,
                 gmeans_acc.setdefault(d, []).extend(xs)
             gscored += sc
             if gscored:
+                remember_agent(actual_critics, spare)
+                refresh_actual_route(
+                    review_reason="全局评审补位：%s" %
+                    (spare.get("label") or spare.get("id")))
                 break
         if not gscored:
             store.update_run(run_id, expected_status="running", status="failed",
@@ -2526,6 +2634,10 @@ def _run_serial_review(run, task, agents, ev, stats, mode, critics, impl, route,
                                 resume=resume_ctx["session"] if resume_ctx else None)
                 if not res["ok"]:
                     continue
+            remember_agent(actual_implementers, impl)
+            refresh_actual_route(
+                impl, implement_reason="全局打磨：%s" %
+                (impl.get("label") or impl.get("id")))
             # 重评该章
             cj_by_agent = {}
             for agent in critics:
@@ -2798,9 +2910,16 @@ def _run_content_review(run, task, agents, ev, stats, mode):
         store.update_run(run_id, expected_status="running", status="failed",
                          error="没有可用智能体", ended_at=_now())
         return
-    if resume_ctx is not None and mode == "auto":
-        critics, route["critics"] = router.pick_critics(
-            agents, task.get("type") or "novel", stats, impl=impl)
+    if resume_ctx is not None:
+        if mode == "auto":
+            critics, route["critics"] = router.pick_critics(
+                agents, task.get("type") or "novel", stats, impl=impl)
+        else:
+            critics = _pick_critics_manual(agents, task)
+
+    _record_actual_route(run_id, task, agents, stats, impl, critics=critics,
+                         implement_reason=route.get("author", ""),
+                         review_reason=route.get("critics", ""))
 
     # ---- 规划（小说为模板计划）
     _wait_gate(run_id, ev)
@@ -3280,6 +3399,18 @@ def execute_run(run_id):
         store.update_run(run_id, expected_status="running", status="failed",
                          error="找不到任务 %s" % run.get("task_id"), ended_at=_now())
         return
+    # 统一任务编译：旧字段继续供各引擎读取，规格作为运行级诊断与调度输入落盘。
+    task_spec = task_compile.compile_task(task)
+    store.update_run(run_id, task_spec=task_spec,
+                     task_spec_summary=task_compile.summary(task_spec),
+                     difficulty=task_spec["difficulty"])
+    task = dict(task)
+    task["_compiled_spec"] = task_spec
+    # 运行内统一使用编译后的难度；store 中历史任务常带 difficulty=auto，
+    # 不能让这个兼容值覆盖 easy/default/hard 的模型调度决策。
+    task["difficulty"] = task_spec["difficulty"]
+    # 同理，历史任务可能保存非法/过期 engine；执行以编译后的流程引擎为准。
+    task["engine"] = task_spec["engine"]
     # 代码版本检出：任务指定了基线版本时，先检出任务分支 tutti/<task-id> 再跑流水线。
     # 显式意图不容静默降级——仓库缺失/脏工作区/引用不存在一律中止运行并报错，
     # 绝不带着用户未提交改动切分支、也不悄悄退回当前 HEAD。
@@ -3319,6 +3450,11 @@ def execute_run(run_id):
     for _agent in agents:
         if isinstance(_agent, dict):
             _agent["_dispatch_task_type"] = task.get("type") or "direct"
+    store.update_run(run_id, route_plan={
+        "task": task_spec,
+        "implement": router.route_plan(agents, "implement", task_spec, stats),
+        "review": router.route_plan(agents, "review", task_spec, stats),
+    })
     mode = task.get("mode") or ("manual" if task.get("implementer") else "auto")
     store.update_run(run_id, mode=mode)
     # engine 决定流水线：code=实现/验证/评审/修复；review=起草/多维评审/修订/门禁；
@@ -3354,8 +3490,12 @@ def execute_run(run_id):
                 store.update_run(run_id, expected_status="running", status="failed",
                                  error="没有可用智能体", ended_at=_now())
                 return
-            if resume_ctx is not None and mode == "auto":
-                critics, route["critics"] = router.pick_critics(agents, task["type"], stats, impl=impl)
+            if resume_ctx is not None:
+                if mode == "auto":
+                    critics, route["critics"] = router.pick_critics(
+                        agents, task["type"], stats, impl=impl)
+                else:
+                    critics = _pick_critics_manual(agents, task)
             if task.get("serial"):
                 _run_serial_review(run, task, agents, ev, stats, mode,
                                    critics, impl, route, resume_ctx, difficulty)

package/app/core/portscan.py

@@ -0,0 +1,188 @@
+# -*- coding: utf-8 -*-
+"""端口/进程扫描与项目归属推断（借鉴 leftopen 38★）。
+
+三个机制：
+- **端口→进程→项目归属推断**：netstat/ss 拿端口→PID，再从进程 CWD 向上走找
+  .git/package.json 等项目根——知道该进程属于哪个项目/用户
+- **本地 vs LAN 区分**：127.0.0.1 与 0.0.0.0/LAN 的安全边界
+- **温和关闭**：SIGTERM only（Windows taskkill /PID 不带 /F），关闭前重验 PID
+
+跨平台（Windows netstat + PowerShell / POSIX ss + /proc）纯标准库。
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import subprocess
+
+log = logging.getLogger(__name__)
+
+_PROJECT_MARKERS = (".git", "package.json", "pyproject.toml", "Cargo.toml",
+                    "go.mod", "pom.xml", "build.gradle", ".codebee")
+_SYSTEM_PROCS = {"system", "idle", "kernel", "svchost", "launchd", "init",
+                 "systemd", "sshd", "explorer", "finder", "windowserver"}
+
+
+def _project_from_cwd(cwd):
+    """从 CWD 向上走到项目根（含标志文件的最深目录名）。"""
+    if not cwd:
+        return ""
+    cur = os.path.abspath(cwd)
+    origin = cur
+    home = os.path.abspath(os.path.expanduser("~"))
+    while cur and cur != os.path.dirname(cur):
+        # 家目录及以上散落的标志文件（package.json 等）是环境噪音不是项目；
+        # 只有进程就跑在家目录本身时才认它为归属。
+        if cur == home and cur != origin:
+            return ""
+        for marker in _PROJECT_MARKERS:
+            if os.path.exists(os.path.join(cur, marker)):
+                return os.path.basename(cur)
+        cur = os.path.dirname(cur)
+    return ""
+
+
+def _proc_detail(pid):
+    """POSIX：读 /proc/<pid>/cwd 和 comm 获取进程详情。"""
+    detail = {"name": "", "project": ""}
+    try:
+        cwd = os.readlink("/proc/%d/cwd" % pid)
+        with open("/proc/%d/comm" % pid) as f:
+            detail["name"] = f.read().strip()
+        proj = _project_from_cwd(cwd)
+        if proj:
+            detail["project"] = proj
+    except (OSError, PermissionError):
+        pass
+    return detail
+
+
+def _parse_ss(output):
+    """解析 ss/netstat -tlnp 输出为端口条目列表。"""
+    ports, pid_map = [], {}
+    for ln in output.splitlines():
+        m = re.search(r":(\d{4,5})\s", ln)
+        if not m:
+            continue
+        port = int(m.group(1))
+        pm = re.search(r"pid=(\d+)", ln)
+        pid = int(pm.group(1)) if pm else 0
+        local_only = "127.0.0.1" in ln or "[::1]" in ln or "localhost" in ln
+        if pid and pid not in pid_map:
+            pid_map[pid] = _proc_detail(pid)
+        ports.append({"port": port, "pid": pid, "local_only": local_only,
+                      "process": pid_map.get(pid, {}).get("name", ""),
+                      "project": pid_map.get(pid, {}).get("project", "")})
+    dedup = {}
+    for p in ports:
+        key = p["port"]
+        if key not in dedup or (p["pid"] and not dedup[key]["pid"]):
+            dedup[key] = p
+    return sorted(dedup.values(), key=lambda x: x["port"])
+
+
+def _ports_linux():
+    """Linux/macOS：ss 优先，netstat 兜底。"""
+    try:
+        proc = subprocess.run(["ss", "-tlnp"], capture_output=True, timeout=15)
+        if proc.returncode == 0 and proc.stdout:
+            return _parse_ss(proc.stdout.decode("utf-8", "replace"))
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+    try:
+        proc = subprocess.run(["netstat", "-tlnp"], capture_output=True, timeout=15)
+        if proc.returncode == 0 and proc.stdout:
+            return _parse_ss(proc.stdout.decode("utf-8", "replace"))
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+    return []
+
+
+def _ports_windows(with_names=True):
+    """Windows：netstat -ano -p TCP 拿端口，PowerShell 一次性补进程名。"""
+    try:
+        proc = subprocess.run(
+            ["C:\\Windows\\System32\\netstat.exe", "-ano", "-p", "TCP"],
+            capture_output=True, timeout=15)
+    except (OSError, subprocess.TimeoutExpired):
+        return []
+    ports = []
+    for ln in proc.stdout.decode("utf-8", "replace").splitlines():
+        parts = ln.split()
+        if len(parts) < 5 or parts[0] != "TCP" or parts[3] != "LISTENING":
+            continue
+        local = parts[1]
+        pid_str = parts[4]
+        if not pid_str.isdigit():
+            continue
+        addr, _, port_str = local.rpartition(":")
+        if not port_str.isdigit():
+            continue
+        ports.append({"port": int(port_str), "pid": int(pid_str),
+                      "local_only": addr in ("127.0.0.1", "[::1]", "::1"),
+                      "process": "", "project": ""})
+    if with_names and ports:
+        try:
+            pn = subprocess.run(
+                ["C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
+                 "-NoProfile", "-Command",
+                 "Get-Process | Select-Object Id,ProcessName | ConvertTo-Json -Compress"],
+                capture_output=True, timeout=15)
+            procs = json.loads(pn.stdout.decode("utf-8", "replace"))
+            if isinstance(procs, dict):
+                procs = [procs]
+            name_map = {p.get("Id"): p.get("ProcessName", "") for p in procs}
+            for p in ports:
+                p["process"] = name_map.get(p["pid"], "")
+        except Exception:
+            pass
+    dedup = {}
+    for p in ports:
+        dedup.setdefault(p["port"], p)
+    return sorted(dedup.values(), key=lambda x: x["port"])
+
+
+def listening_ports(with_names=True):
+    """扫描本机所有 LISTEN 端口，返回 [{port, pid, process, project, local_only}]。
+
+    project 从进程 CWD 推断项目根目录名（POSIX /proc 可得，Windows 留空）。
+    with_names=False：跳过进程名/归属补全（Windows 下省掉 PowerShell 一次
+    起跳，重验场景用），process/project 恒为空串。
+    结果按端口号排序，重复端口去重（保留有 PID 信息的条目）。"""
+    if os.name == "nt":
+        return _ports_windows(with_names)
+    return _ports_linux()
+
+
+def close_port(port):
+    """温和关闭端口上的进程。返回 (ok, message)。关闭前重验 PID 绑定。"""
+    for p in listening_ports():
+        if p["port"] != port:
+            continue
+        pid = p.get("pid", 0)
+        if not pid or pid <= 4:
+            return False, "系统进程，不关闭"
+        if pid == os.getpid():
+            return False, "不能关闭自身服务进程"
+        if p.get("process", "").lower() in _SYSTEM_PROCS:
+            return False, "系统服务，不关闭"
+        # 重验 PID 仍在监听该端口（防 PID 复用竞态）；轻量扫描省掉 PowerShell
+        still = any(pp["port"] == port and pp["pid"] == pid
+                    for pp in listening_ports(with_names=False))
+        if not still:
+            return False, "PID %d 已不在端口 %d 上监听（竞态）" % (pid, port)
+        if os.name == "posix":
+            try:
+                os.kill(pid, 15)   # SIGTERM
+                return True, "已发送 SIGTERM（PID %d）" % pid
+            except OSError as e:
+                return False, str(e)[:160]
+        try:
+            subprocess.run(["taskkill", "/PID", str(pid)],
+                           timeout=10, capture_output=True)
+            return True, "已发送关闭信号（PID %d）" % pid
+        except Exception as e:
+            return False, str(e)[:160]
+    return False, "端口 %d 未找到监听进程" % port

package/app/core/router.py

@@ -10,7 +10,14 @@ CAPABILITY = {
     "aider": 70, "openclaw": 60, "generic": 55, "mock": 10,
 }
 
-MAX_REPAIR_ROUNDS = 2  # 自动修复循环上限
+MAX_REPAIR_ROUNDS = 2  # 自动修复循环上限
+
+
+def _task_type(ttype):
+    """兼容旧调用的字符串与新任务规格对象。"""
+    if isinstance(ttype, dict):
+        return str(ttype.get("type") or ttype.get("dimension") or "direct")
+    return str(ttype or "direct")
 
 
 def _binding_bonus(agent_id, dispatch_mode=False):
@@ -43,11 +50,12 @@ def _history_bonus(stats, agent_id, ttype):
     return round(18.0 * win_rate + min(6.0, runs) - loss_penalty, 1)
 
 
-def score(agent, role, ttype, stats=None):
+def score(agent, role, ttype, stats=None):
     """返回 (总分, 理由字符串)。配额惩罚：catalog 里配了
     quota_tokens_per_hour 的智能体，本小时用量越接近配额分越低
     （封顶 -45，足以盖过历史加分），满额后仅在没有其他选择时才会被选中。"""
-    stats = stats or {}
+    stats = stats or {}
+    ttype = _task_type(ttype)
     base = CAPABILITY.get(agent.get("kind"), 60)
     use_dispatch = bool(agent.get("_dispatch_task_type") or
                         agent.get("dispatch_enabled"))
@@ -83,7 +91,7 @@ def score(agent, role, ttype, stats=None):
         base, affinity_txt, btxt, htxt, quota_txt, round(total, 1))
 
 
-def pick(agents, role, ttype, stats=None, exclude=()):
+def pick(agents, role, ttype, stats=None, exclude=()):
     """按分选出最优智能体。返回 (agent, 理由) 或 (None, "")。"""
     stats = stats or history.agent_stats()
     best, best_reason = None, ""
@@ -95,7 +103,51 @@ def pick(agents, role, ttype, stats=None, exclude=()):
             best, best_reason = (total, a), reason
     if best is None:
         return None, ""
-    return best[1], best_reason
+    return best[1], best_reason
+
+
+def route_plan(agents, role, task_spec, stats=None, exclude=(), selected=None,
+               participants=(), selection_reason=""):
+    """生成可审计的候选排序，并可用实际选路覆盖评分预选结果。"""
+    if stats is None:
+        stats = history.agent_stats()
+    # 与 pick 保持同一候选池；绑定/健康扣分仍由 score 和 modelhub 负责，
+    # 诊断不能悄悄排除实际可能被选中的 mock 或备用 CLI。
+    pool = list(agents or [])
+    rows = []
+    for index, agent in enumerate(pool):
+        if agent.get("id") in exclude:
+            continue
+        candidate = dict(agent)
+        if isinstance(task_spec, dict):
+            candidate["_dispatch_task_type"] = task_spec.get("type") or "direct"
+            candidate["_dispatch_role"] = role
+        total, reason = score(candidate, role, task_spec, stats)
+        rows.append({"agent_id": agent.get("id") or "",
+                     "label": agent.get("label") or agent.get("id") or "",
+                     "kind": agent.get("kind") or "generic",
+                     "score": round(total, 1), "reason": reason,
+                     "order": index})
+    rows.sort(key=lambda x: (-x["score"], x["order"]))
+    selected_id = (selected or {}).get("id") if isinstance(selected, dict) else ""
+    if selected_id and not any(x["agent_id"] == selected_id for x in rows):
+        rows.append({"agent_id": selected_id,
+                     "label": selected.get("label") or selected_id,
+                     "kind": selected.get("kind") or "builtin",
+                     "score": 0.0, "reason": selection_reason or "实际选路",
+                     "order": len(rows)})
+    chosen = selected_id or (rows[0]["agent_id"] if rows else "")
+    participant_ids = []
+    for agent in participants or ():
+        agent_id = agent.get("id") if isinstance(agent, dict) else str(agent or "")
+        if agent_id and agent_id not in participant_ids:
+            participant_ids.append(agent_id)
+    active_ids = participant_ids or ([chosen] if chosen else [])
+    return {"role": role, "selected": chosen, "participants": participant_ids,
+            "selection_reason": selection_reason,
+            "candidates": rows,
+            "fallback": [x["agent_id"] for x in rows
+                         if x["agent_id"] not in active_ids]}
 
 
 def pick_reviewer(agents, impl, ttype, stats=None):