codebee 0.1.22 → 0.1.23

package/CHANGELOG.md

@@ -6,6 +6,18 @@ README 元数据带回，供老版本在「发现新版本」时展示新版更
 
 ## 未发布
 
+## v0.1.23（2026-09-21）
+
+- 端口占用诊断（借鉴 leftopen）：启动时端口被占自动指认占用者（PID/进程/所属项目，不再让用户手跑 netstat+tasklist）；设置页新增「端口占用」面板——扫描本机全部监听端口（仅本机/本服务徽章、项目归属列），可对非自身进程发送温和关闭信号（SIGTERM 语义，关前重验 PID，系统进程与 CodeBee 服务自身拒绝关闭）
+- 经验库预算纪律：通配（wildcard）技能包单包注入限额 2400 字、项目教训保底注入——此前 39 个通配包全文注入会吃光 9000 字上限，把本机沉淀的评审教训整段挤掉；定向命中的规范包（番茄/七猫签约标准等）不受单包限额
+- AI 味检测新增叙事架构层（借鉴 sepia/StoryScope 研究：AI 小说 93.2% 靠叙事架构特征检出，人工改措辞后几乎不降）：确定性统计顿悟说教/情绪身体化/成长式收束（只扫结尾 600 字）三类架构级指纹，命中即随评审下发情节结构追问
+- 任务画像与调度统一：运行详情新增「任务画像与调度」审计——任务画像与实际选路来自同一次编译结果，难度/能力需求/降级链一目了然
+
+## v0.1.22（2026-09-21）
+
+- README 功能导览大扩容：新增知识库、自动化、帮助中心、作品信息图文介绍
+- 近期亮点回顾：语音识别词表纠偏、调研报告「结论先行」硬约束、任务默认立即启动
+
 ## v0.1.21（2026-09-21）
 
 - 任务默认直接启动，不再进入容量等待队列；达到并发保护上限立即失败并明确提示稍后重试，历史 queued 记录启动时自动接管或收口。

package/README.md

@@ -21,10 +21,11 @@ Kimi Code、MiMo Code、Grok Build、Pi、DeepSeek Harness……），提供
 不会把你的任务内容交给任何第三方。
 
 <!-- relnotes:start -->
-### 最新版更新内容（v0.1.22）
+### 最新版更新内容（v0.1.23）
 
-- README 功能导览大扩容：新增知识库、自动化、帮助中心、作品信息图文介绍
-- 近期亮点回顾：语音识别词表纠偏、调研报告「结论先行」硬约束、任务默认立即启动
+- 端口占用诊断：启动失败自动指认占用者（PID/进程/项目归属）；设置页可扫描本机全部监听端口并温和关闭（系统进程与 CodeBee 自身拒关）
+- 经验库预算纪律：通配技能包单包限额、项目教训保底注入——再多的通配包也挤不掉你沉淀的教训
+- AI 味检测新增叙事架构层：顿悟说教/情绪身体化/成长式收束等措辞改写不掉的架构级指纹，随评审下发情节结构追问
 <!-- relnotes:end -->
 
 ---

package/app/core/aiflavor.py

@@ -20,6 +20,22 @@ AI_PHRASES = (
 # 密度告警线（每千字命中次数）：超过即提示评审官重点关注
 ALERT_PER_KILO = 8.0
 
+# 叙事架构层信号（借鉴 sepia 2.7k★/StoryScope 研究 2026：AI 小说 93.2% 靠
+# 叙事架构特征检出，人工改写措辞后检出率仅从 95.5% 降到 93.9%——措辞层
+# 改不掉的架构级指纹才是真破绽）。三类可确定性检测的架构信号：
+NARRATIVE_TELLS = {
+    "顿悟说教": ("终于明白", "这才明白", "明白了，", "意识到，自己", "懂得了",
+               "原来，成长", "原来，生活", "原来，所谓"),
+    "情绪身体化": ("心脏猛地", "指尖冰凉", "指尖发凉", "喉咙发紧", "喉头发紧",
+                "胃里一阵", "胃部一阵", "后背一凉", "血液仿佛", "呼吸一滞"),
+    "成长式收束": ("释然", "和解", "放下了", "接纳了", "与自己和解", "轻轻松了口气",
+                "内心归于平静"),
+}
+# 架构信号告警线比措辞层低：这些表达在好小说里本就该稀缺
+NARRATIVE_ALERT_PER_KILO = 2.0
+# 「成长式收束」只在结尾才构成架构指纹（中段出现多半是剧情词），只扫尾部
+ENDING_SCAN_CHARS = 600
+
 
 def analyze(text):
     """统计套话命中。返回 {hits: {短语: 次数}, per_kilo: 每千字密度, alert: bool}。"""
@@ -38,14 +54,52 @@ def analyze(text):
     return {"hits": hits, "per_kilo": per_kilo, "alert": per_kilo >= ALERT_PER_KILO}
 
 
+def narrative_analyze(text):
+    """统计叙事架构层信号。返回 {cats: {类: 次数}, per_kilo, alert, ending_hits}。
+
+    - 前两类全篇统计；「成长式收束」只统计末尾 ENDING_SCAN_CHARS 字
+      （中段的「和解/放下」是剧情词，结尾的才是成长式收束指纹）。
+    - per_kilo 为三类合计密度；alert 判据：合计 ≥ 告警线 或 收束类命中 ≥ 2。
+    """
+    text = text or ""
+    total = len(text)
+    cats, ending_hits = {}, 0
+    if total:
+        tail = text[-ENDING_SCAN_CHARS:]
+        for cat, phrases in NARRATIVE_TELLS.items():
+            n = 0
+            for p in phrases:
+                if cat == "成长式收束":
+                    n += tail.count(p)
+                else:
+                    n += text.count(p)
+            if n:
+                cats[cat] = n
+        ending_hits = cats.get("成长式收束", 0)
+    per_kilo = round(sum(cats.values()) * 1000.0 / total, 2) if (total and cats) else 0.0
+    alert = bool(cats) and (per_kilo >= NARRATIVE_ALERT_PER_KILO or ending_hits >= 2)
+    return {"cats": cats, "per_kilo": per_kilo, "alert": alert, "ending_hits": ending_hits}
+
+
 def report_line(text):
-    """生成注入评审提示词的一行报告；无命中返回空串。"""
+    """生成注入评审提示词的报告行（措辞层 + 叙事架构层）；全部无命中返回空串。"""
+    lines = []
     r = analyze(text)
-    if not r["hits"]:
-        return ""
-    top = "、".join("「%s」×%d" % (k, v)
-                    for k, v in sorted(r["hits"].items(), key=lambda x: -x[1])[:8])
-    line = "- [AI味检测] 确定性统计：套话密度 %.1f/千字（%s）。" % (r["per_kilo"], top)
-    if r["alert"]:
-        line += "密度超过告警线 %.0f/千字，请重点评审译制腔与套话问题。" % ALERT_PER_KILO
-    return line
+    if r["hits"]:
+        top = "、".join("「%s」×%d" % (k, v)
+                        for k, v in sorted(r["hits"].items(), key=lambda x: -x[1])[:8])
+        line = "- [AI味检测] 确定性统计：套话密度 %.1f/千字（%s）。" % (r["per_kilo"], top)
+        if r["alert"]:
+            line += "密度超过告警线 %.0f/千字，请重点评审译制腔与套话问题。" % ALERT_PER_KILO
+        lines.append(line)
+    nr = narrative_analyze(text)
+    if nr["cats"]:
+        top = "、".join("「%s」×%d" % (k, v) for k, v in nr["cats"].items())
+        line = ("- [叙事架构信号] 确定性统计（措辞改写不掉的架构级指纹）："
+                "%s，合计 %.1f/千字。" % (top, nr["per_kilo"]))
+        if nr["alert"]:
+            line += ("出现架构级 AI 指纹（顿悟说教/情绪只写身体反应/成长式收束），"
+                     "请评审情节结构：主题是否被叙述者直接说破、情绪是否只有身体描写、"
+                     "结尾是否靠主角想通收束。")
+        lines.append(line)
+    return "\n".join(lines)

package/app/core/pipeline.py

@@ -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)
@@ -3287,6 +3406,11 @@ def execute_run(run_id):
                      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。
@@ -3366,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

@@ -106,12 +106,14 @@ def pick(agents, role, ttype, stats=None, exclude=()):
     return best[1], best_reason
 
 
-def route_plan(agents, role, task_spec, stats=None, exclude=()):
-    """生成可审计的候选排序，供运行详情展示和后续 fallback 使用。"""
+def route_plan(agents, role, task_spec, stats=None, exclude=(), selected=None,
+               participants=(), selection_reason=""):
+    """生成可审计的候选排序，并可用实际选路覆盖评分预选结果。"""
     if stats is None:
         stats = history.agent_stats()
-    real = [a for a in agents or [] if a.get("mode") == "real"]
-    pool = real if real else list(agents or [])
+    # 与 pick 保持同一候选池；绑定/健康扣分仍由 score 和 modelhub 负责，
+    # 诊断不能悄悄排除实际可能被选中的 mock 或备用 CLI。
+    pool = list(agents or [])
     rows = []
     for index, agent in enumerate(pool):
         if agent.get("id") in exclude:
@@ -127,9 +129,25 @@ def route_plan(agents, role, task_spec, stats=None, exclude=()):
                      "score": round(total, 1), "reason": reason,
                      "order": index})
     rows.sort(key=lambda x: (-x["score"], x["order"]))
-    return {"role": role, "selected": rows[0]["agent_id"] if rows else "",
+    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[1:]]}
+            "fallback": [x["agent_id"] for x in rows
+                         if x["agent_id"] not in active_ids]}
 
 
 def pick_reviewer(agents, impl, ttype, stats=None):