codebee 0.1.101 → 0.1.103

package/app/core/paihang.py

@@ -1,145 +1,145 @@
-# -*- coding: utf-8 -*-
-"""扫榜选材：抓取公开排行榜页，产出选题分析素材。
-
-数据源（四源聚合，任一失败不影响其余源；2026-09-24 实测全 200）：
-- 七猫：www.qimao.com/paihang/（106KB）
-- 番茄 Web 版：fanqienovel.com/rank（题材分类+书名在中文 a 标签里；
-  App 端接口有 SecuritySign/X-Argus 签名——那才是难路，Web 版榜单页
-  不需要签名，别走弯路）
-- 起点移动版：m.qidian.com/rank（106KB，直接出书名；主站 www.qidian.com
-  被 WAF 拦 202/209B，移动页不需要签名）
-- 纵横：www.zongheng.com/rank（65KB，书名+统计标签混排，靠噪音词过滤）
-
-下载走 curl 子进程（与 covergen 同款），解析用宽松正则——页面结构变了
-宁可返回空（调用方回落普通直连提示词），不做脆弱的强解析。
-"""
-from __future__ import annotations
-
-import logging
-import re
-
-log = logging.getLogger(__name__)
-
-QIMAO_RANK_URL = "https://www.qimao.com/paihang/"
-FANQIE_RANK_URL = "https://fanqienovel.com/rank"
-QIDIAN_M_RANK_URL = "https://m.qidian.com/rank/"
-ZONGHENG_RANK_URL = "https://www.zongheng.com/rank/"
-_UA = ("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
-       "(KHTML, like Gecko) Chrome/126 Safari/537.36")
-
-# 页面 UI 噪音词（非书目/分类）：页面 chrome、导航、tab 名、登录/搜索、
-# 榜单 tab 与统计标签（起点移动版 tab 名、纵横月票/人气/点击等）
-_NOISE = {"加入书架", "立即阅读", "开始阅读", "免费阅读", "全部", "分类", "排行",
-          "排行榜", "完本", "连载中", "阅读", "书城", "男生", "女生",
-          "帮助中心", "作家助手", "客服", "登录", "注册", "立即登录",
-          "搜索", "热门作品排行", "大热榜", "新书榜", "完结榜", "收藏榜",
-          "更新榜", "日榜", "月榜", "蝉联", "榜首", "热度", "免费", "畅销",
-          "下载", "客户端", "首页", "我的", "设置", "更多", "返回", "关于",
-          "月票榜", "阅读榜", "书友榜", "推荐榜", "签约榜", "新人榜",
-          "畅销榜", "大家都在搜", "男生小说排行榜", "女生小说排行榜",
-          "男频阅读榜", "女频阅读榜", "男频新书榜", "番茄小说",
-          "登录后获得更多特色功能", "安装起点读书客户端", "看更多正版好书",
-          "月票", "人气", "点击", "万字", "推荐", "收藏", "鲜花", "打赏", "推荐票"}
-
-_CJK_RE = re.compile(r">([\u4e00-\u9fa5]{2,12})<")
-
-
-def _curl_text(url):
-    """curl 子进程抓页面文本；失败返回空串。"""
-    from . import runner
-    try:
-        r = runner.run_process(
-            argv=["curl", "-sS", "--max-time", "20", "-A", _UA, url],
-            timeout=30)
-    except Exception:
-        return ""
-    if not r.get("ok"):
-        return ""
-    return r.get("stdout") or ""
-
-
-def _extract_cjk(html, limit):
-    """从 HTML 提取中文元素材（去 UI 噪音、保序去重）。"""
-    items, seen = [], set()
-    for t in _CJK_RE.findall(html or ""):
-        if t in _NOISE or t in seen:
-            continue
-        seen.add(t)
-        items.append(t)
-        if len(items) >= limit:
-            break
-    return items
-
-
-def fetch_qimao_rank(limit=30):
-    """七猫排行榜：返回元素列表，抓取失败返回 []。"""
-    return _extract_cjk(_curl_text(QIMAO_RANK_URL), limit)
-
-
-def fetch_fanqie_rank(limit=30):
-    """番茄 Web 版榜单：返回元素列表，抓取失败返回 []。"""
-    return _extract_cjk(_curl_text(FANQIE_RANK_URL), limit)
-
-
-def fetch_qidian_rank(limit=30):
-    """起点移动版榜单：返回元素列表，抓取失败返回 []。"""
-    return _extract_cjk(_curl_text(QIDIAN_M_RANK_URL), limit)
-
-
-def fetch_zongheng_rank(limit=30):
-    """纵横排行榜：返回元素列表，抓取失败返回 []。"""
-    return _extract_cjk(_curl_text(ZONGHENG_RANK_URL), limit)
-
-
-# 源清单：顺序即素材拼接顺序（七猫/番茄为元老源保持在前）。
-# 存函数名、调用期 globals() 解析——mock.patch 换模块属性才能生效
-# （存函数引用会把定义期原函数钉死，测试会穿透打真网络）。
-_SOURCES = (
-    ("七猫排行榜素材", "fetch_qimao_rank"),
-    ("番茄排行榜素材", "fetch_fanqie_rank"),
-    ("起点排行榜素材", "fetch_qidian_rank"),
-    ("纵横排行榜素材", "fetch_zongheng_rank"),
-)
-
-
-def fetch_rank_items(limit=40):
-    """四源聚合：各抓一份（跨源去重合并，按源清单顺序）。
-
-    全部失败才返回 []——单源挂了其余源仍可用，扫榜永不因单点挡任务。"""
-    merged, seen = [], set()
-    for _label, fname in _SOURCES:
-        for t in globals()[fname](limit):
-            if t not in seen:
-                seen.add(t)
-                merged.append(t)
-    return merged
-
-
-def rank_scan_prompt(goal):
-    """组装扫榜选材分析提示词。四源全空返回 None（调用方回落直连提示词）。
-
-    报告契约含逐条 A-E 跨平台证据分级（借鉴 career-ops 的分级报告交付形态）：
-    分级只认素材实际出现情况——抑制单源孤证被模型放大成「大热题材」。"""
-    blocks, seen = [], set()
-    for label, fname in _SOURCES:
-        items = [t for t in globals()[fname](30) if t not in seen]
-        seen.update(items)
-        if items:
-            blocks.append("### %s\n%s" % (label, "、".join(items)))
-    if not blocks:
-        return None
-    material = "\n\n".join(blocks)
-    return (
-        "你是网文选题分析师。以下是刚刚抓取的各平台排行榜页面的书目与分类素材：\n\n"
-        "## 榜单元素材\n%s\n\n"
-        "## 用户想写的方向\n%s\n\n"
-        "## 你的产出（Markdown 报告）\n"
-        "报告第一行给图例（一行）：「证据分级：A=三平台及以上重合，B=两平台重合，"
-        "C=单平台多次出现，D=单平台仅一次，E=素材无直接证据、系推断」。\n"
-        "1. **热门题材 Top3**：各自的共同特征与上榜代表书目（跨平台重合的题材单独点出——多平台都热说明是真风口）\n"
-        "2. **高频人设/套路总结**：3-5 条，点名反复出现的元素\n"
-        "3. **差异化切入建议**：2-3 个，结合用户方向给出「题材+人设」组合与一句话理由\n"
-        "以上每一项结论末尾标注【证据X】（X 为 A-E 之一）。分级只看素材里真实出现的"
-        "情况：组合条目按其组成元素的较低档取值，拿不准就降一档、不升级。\n"
-        "直接输出分析报告，不要复述素材清单，不要输出与报告无关的内容。"
-        % (material, goal or "（用户未指定方向，按大盘热门分析）"))
+# -*- coding: utf-8 -*-
+"""扫榜选材：抓取公开排行榜页，产出选题分析素材。
+
+数据源（四源聚合，任一失败不影响其余源；2026-09-24 实测全 200）：
+- 七猫：www.qimao.com/paihang/（106KB）
+- 番茄 Web 版：fanqienovel.com/rank（题材分类+书名在中文 a 标签里；
+  App 端接口有 SecuritySign/X-Argus 签名——那才是难路，Web 版榜单页
+  不需要签名，别走弯路）
+- 起点移动版：m.qidian.com/rank（106KB，直接出书名；主站 www.qidian.com
+  被 WAF 拦 202/209B，移动页不需要签名）
+- 纵横：www.zongheng.com/rank（65KB，书名+统计标签混排，靠噪音词过滤）
+
+下载走 curl 子进程（与 covergen 同款），解析用宽松正则——页面结构变了
+宁可返回空（调用方回落普通直连提示词），不做脆弱的强解析。
+"""
+from __future__ import annotations
+
+import logging
+import re
+
+log = logging.getLogger(__name__)
+
+QIMAO_RANK_URL = "https://www.qimao.com/paihang/"
+FANQIE_RANK_URL = "https://fanqienovel.com/rank"
+QIDIAN_M_RANK_URL = "https://m.qidian.com/rank/"
+ZONGHENG_RANK_URL = "https://www.zongheng.com/rank/"
+_UA = ("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+       "(KHTML, like Gecko) Chrome/126 Safari/537.36")
+
+# 页面 UI 噪音词（非书目/分类）：页面 chrome、导航、tab 名、登录/搜索、
+# 榜单 tab 与统计标签（起点移动版 tab 名、纵横月票/人气/点击等）
+_NOISE = {"加入书架", "立即阅读", "开始阅读", "免费阅读", "全部", "分类", "排行",
+          "排行榜", "完本", "连载中", "阅读", "书城", "男生", "女生",
+          "帮助中心", "作家助手", "客服", "登录", "注册", "立即登录",
+          "搜索", "热门作品排行", "大热榜", "新书榜", "完结榜", "收藏榜",
+          "更新榜", "日榜", "月榜", "蝉联", "榜首", "热度", "免费", "畅销",
+          "下载", "客户端", "首页", "我的", "设置", "更多", "返回", "关于",
+          "月票榜", "阅读榜", "书友榜", "推荐榜", "签约榜", "新人榜",
+          "畅销榜", "大家都在搜", "男生小说排行榜", "女生小说排行榜",
+          "男频阅读榜", "女频阅读榜", "男频新书榜", "番茄小说",
+          "登录后获得更多特色功能", "安装起点读书客户端", "看更多正版好书",
+          "月票", "人气", "点击", "万字", "推荐", "收藏", "鲜花", "打赏", "推荐票"}
+
+_CJK_RE = re.compile(r">([\u4e00-\u9fa5]{2,12})<")
+
+
+def _curl_text(url):
+    """curl 子进程抓页面文本；失败返回空串。"""
+    from . import runner
+    try:
+        r = runner.run_process(
+            argv=["curl", "-sS", "--max-time", "20", "-A", _UA, url],
+            timeout=30)
+    except Exception:
+        return ""
+    if not r.get("ok"):
+        return ""
+    return r.get("stdout") or ""
+
+
+def _extract_cjk(html, limit):
+    """从 HTML 提取中文元素材（去 UI 噪音、保序去重）。"""
+    items, seen = [], set()
+    for t in _CJK_RE.findall(html or ""):
+        if t in _NOISE or t in seen:
+            continue
+        seen.add(t)
+        items.append(t)
+        if len(items) >= limit:
+            break
+    return items
+
+
+def fetch_qimao_rank(limit=30):
+    """七猫排行榜：返回元素列表，抓取失败返回 []。"""
+    return _extract_cjk(_curl_text(QIMAO_RANK_URL), limit)
+
+
+def fetch_fanqie_rank(limit=30):
+    """番茄 Web 版榜单：返回元素列表，抓取失败返回 []。"""
+    return _extract_cjk(_curl_text(FANQIE_RANK_URL), limit)
+
+
+def fetch_qidian_rank(limit=30):
+    """起点移动版榜单：返回元素列表，抓取失败返回 []。"""
+    return _extract_cjk(_curl_text(QIDIAN_M_RANK_URL), limit)
+
+
+def fetch_zongheng_rank(limit=30):
+    """纵横排行榜：返回元素列表，抓取失败返回 []。"""
+    return _extract_cjk(_curl_text(ZONGHENG_RANK_URL), limit)
+
+
+# 源清单：顺序即素材拼接顺序（七猫/番茄为元老源保持在前）。
+# 存函数名、调用期 globals() 解析——mock.patch 换模块属性才能生效
+# （存函数引用会把定义期原函数钉死，测试会穿透打真网络）。
+_SOURCES = (
+    ("七猫排行榜素材", "fetch_qimao_rank"),
+    ("番茄排行榜素材", "fetch_fanqie_rank"),
+    ("起点排行榜素材", "fetch_qidian_rank"),
+    ("纵横排行榜素材", "fetch_zongheng_rank"),
+)
+
+
+def fetch_rank_items(limit=40):
+    """四源聚合：各抓一份（跨源去重合并，按源清单顺序）。
+
+    全部失败才返回 []——单源挂了其余源仍可用，扫榜永不因单点挡任务。"""
+    merged, seen = [], set()
+    for _label, fname in _SOURCES:
+        for t in globals()[fname](limit):
+            if t not in seen:
+                seen.add(t)
+                merged.append(t)
+    return merged
+
+
+def rank_scan_prompt(goal):
+    """组装扫榜选材分析提示词。四源全空返回 None（调用方回落直连提示词）。
+
+    报告契约含逐条 A-E 跨平台证据分级（借鉴 career-ops 的分级报告交付形态）：
+    分级只认素材实际出现情况——抑制单源孤证被模型放大成「大热题材」。"""
+    blocks, seen = [], set()
+    for label, fname in _SOURCES:
+        items = [t for t in globals()[fname](30) if t not in seen]
+        seen.update(items)
+        if items:
+            blocks.append("### %s\n%s" % (label, "、".join(items)))
+    if not blocks:
+        return None
+    material = "\n\n".join(blocks)
+    return (
+        "你是网文选题分析师。以下是刚刚抓取的各平台排行榜页面的书目与分类素材：\n\n"
+        "## 榜单元素材\n%s\n\n"
+        "## 用户想写的方向\n%s\n\n"
+        "## 你的产出（Markdown 报告）\n"
+        "报告第一行给图例（一行）：「证据分级：A=三平台及以上重合，B=两平台重合，"
+        "C=单平台多次出现，D=单平台仅一次，E=素材无直接证据、系推断」。\n"
+        "1. **热门题材 Top3**：各自的共同特征与上榜代表书目（跨平台重合的题材单独点出——多平台都热说明是真风口）\n"
+        "2. **高频人设/套路总结**：3-5 条，点名反复出现的元素\n"
+        "3. **差异化切入建议**：2-3 个，结合用户方向给出「题材+人设」组合与一句话理由\n"
+        "以上每一项结论末尾标注【证据X】（X 为 A-E 之一）。分级只看素材里真实出现的"
+        "情况：组合条目按其组成元素的较低档取值，拿不准就降一档、不升级。\n"
+        "直接输出分析报告，不要复述素材清单，不要输出与报告无关的内容。"
+        % (material, goal or "（用户未指定方向，按大盘热门分析）"))

package/app/core/pipeline.py

@@ -586,6 +586,8 @@ def _external_sandbox_block_reason(agent, workdir, sandbox):
     from . import policy
     root = os.path.realpath(workdir or ".")
     normalized = policy.normalize_sandbox(sandbox, root)
+    if normalized.get("backend") == "docker":
+        return "沙箱拒绝：Docker 目前仅接入内置命令工具，外部 CLI 未验证容器启动，拒绝运行"
     if (agent or {}).get("kind") == "codex":
         if normalized.get("network") is False:
             return "沙箱拒绝：该 CLI 后端未接入网络隔离，拒绝运行网络受限任务"
@@ -912,7 +914,8 @@ def _finish_step_result(run_id, step, res, role, agent, start):
                       followups=res.get("followups"),
                       # 思考过程（内置智能体流式抓取）：落进步骤记录，对话气泡折叠展示
                       thinking=res.get("reasoning") or None,
-                      partial=bool(res.get("partial")))
+                      partial=bool(res.get("partial")),
+                      acp_events=(raw.get("acp_events") or []))
     try:
         checkpoint_status = ("unknown" if raw.get("unknown") else
                              "timeout" if status == "timeout" else
@@ -2308,8 +2311,8 @@ def _run_direct(run, task, agents, ev, stats, mode):
         if first:
             prompt = ""
             if task.get("type") == "rank_scan" and bi is not None:
-                # 扫榜选材（借鉴 oh-story 扫榜）：抓七猫排行榜公开数据注入，
-                # AI 做选题洞察；抓取失败回落普通直连提示词
+                # 扫榜选材（借鉴 oh-story 扫榜）：抓七猫/番茄/起点/纵横四平台排行榜
+                # 公开数据注入，AI 做选题洞察；抓取失败回落普通直连提示词
                 prompt = paihang.rank_scan_prompt(task.get("goal") or "") or ""
             if task.get("type") == "defect_retro" and bi is not None:
                 # 缺陷复盘（借鉴 test-defect-retrospective）：三视角分析框架

package/app/core/policy.py

@@ -50,9 +50,18 @@ def normalize_sandbox(spec=None, workdir=None):
     else:
         # Invalid policy input must never silently widen network access.
         network = False
+    backend = str(spec.get("backend") or "native").strip().lower()
+    if backend not in ("native", "docker"):
+        raise ValueError("沙箱 backend 必须是 native 或 docker")
+    image = str(spec.get("docker_image") or "").strip()[:240]
+    if backend == "docker":
+        import re
+        if not image or not re.match(r"^[A-Za-z0-9][A-Za-z0-9._/:@-]*$", image):
+            raise ValueError("Docker 镜像名无效")
     return {"allowed_roots": [str(x) for x in roots], "env_allowlist": env,
             "network": network, "timeout_s": timeout,
             "max_output_bytes": output,
+            "backend": backend, "docker_image": image,
             "disabled_tools": normalize_disabled_tools(spec.get("disabled_tools"))}
 
 

package/app/core/portguard.py

@@ -1,111 +1,111 @@
-# -*- coding: utf-8 -*-
-"""启动端口清场（用户拍板 2026-09-21）：端口被占时先清场再启动。
-
-- **自家旧实例**（命令行含本包 main.py 完整路径，或 npm 包内 app/main.py）
-  → 杀树（TerminateProcess 直杀）——升级/重启最常见的占用者就是没退干净
-  的 CodeBee 自己；控制台进程对温和信号（WM_CLOSE）无反应，温和关不掉
-  正是用户「旧进程太难杀」的痛点，所以自家实例直接强杀。
-- **别人的进程** → 只报告占用者，不发送任何信号；启动流程不得替用户
-  关闭可能正在开发中的服务。
-- 系统/自身进程拒关（portscan 内置护栏）。
-"""
-from __future__ import annotations
-
-import logging
-import os
-import shlex
-import subprocess
-
-from . import portscan, runner
-
-log = logging.getLogger(__name__)
-
-PS_EXE = "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"
-
-
-def proc_cmdline(pid):
-    """读进程命令行；失败返回空串。仅用于确认旧 CodeBee 实例身份。"""
-    try:
-        pid = int(pid)
-    except (TypeError, ValueError):
-        return ""
-    if pid <= 0:
-        return ""
-    if os.name != "nt":
-        try:
-            with open("/proc/%d/cmdline" % pid, "rb") as fh:
-                return fh.read().decode("utf-8", "replace").replace("\x00", " ").strip()
-        except Exception:
-            return ""
-    try:
-        r = subprocess.run(
-            [PS_EXE, "-NoProfile", "-Command",
-             "(Get-CimInstance Win32_Process -Filter 'ProcessId = %d').CommandLine" % pid],
-            capture_output=True, timeout=10)
-        return r.stdout.decode("utf-8", "replace").strip() if r.returncode == 0 else ""
-    except Exception:
-        return ""
-
-
-def _command_tokens(cmdline):
-    try:
-        return [token.strip().strip('"').strip("'")
-                for token in shlex.split(str(cmdline or ""), posix=False)]
-    except (TypeError, ValueError):
-        return []
-
-
-def is_own_instance(cmdline, main_script, port=None):
-    """按启动器、脚本独立参数和端口精确确认 CodeBee 实例。"""
-    tokens = _command_tokens(cmdline)
-    if len(tokens) < 2:
-        return False
-    launcher = os.path.splitext(os.path.basename(tokens[0]))[0].lower()
-    if launcher not in ("python", "python3", "py"):
-        return False
-    script = ""
-    for token in tokens[1:]:
-        if token.startswith("-"):
-            continue
-        script = token
-        break
-    if not script or not os.path.isabs(script):
-        return False
-    actual = os.path.normcase(os.path.normpath(os.path.abspath(script)))
-    expected = os.path.normcase(os.path.normpath(os.path.abspath(str(main_script))))
-    packaged = actual.replace("\\", "/").lower().endswith(
-        "/node_modules/codebee/app/main.py")
-    if actual != expected and not packaged:
-        return False
-    if port is None:
-        return True
-    try:
-        wanted = str(int(port))
-    except (TypeError, ValueError):
-        return False
-    explicit_port = None
-    for i, token in enumerate(tokens):
-        if token == "--port" and i + 1 < len(tokens):
-            explicit_port = tokens[i + 1]
-        elif token.startswith("--port="):
-            explicit_port = token.split("=", 1)[1]
-    # argparse 默认端口可不出现在旧实例参数中；非默认端口必须显式相符。
-    return ((explicit_port == wanted) if explicit_port is not None
-            else wanted == "8765")
-
-
-def clear_stale_port(port, main_script):
-    """清掉占用端口的进程。返回 (是否清掉, 人话说明)。"""
-    holders = [p for p in portscan.listening_ports() if p.get("port") == int(port)]
-    if not holders:
-        return True, ""
-    pid = int(holders[0].get("pid") or 0)
-    if pid <= 4 or pid == os.getpid():
-        return False, "占用者是系统进程/自身，拒绝清理"
-    if is_own_instance(proc_cmdline(pid), main_script, port=port):
-        try:
-            runner._kill_tree(pid)
-            return True, "已结束旧实例 PID %d" % pid
-        except Exception as e:
-            return False, "旧实例 PID %d 清理失败 %s" % (pid, str(e)[:80])
-    return False, "占用者非 CodeBee（PID %d），未自动关闭" % pid
+# -*- coding: utf-8 -*-
+"""启动端口清场（用户拍板 2026-09-21）：端口被占时先清场再启动。
+
+- **自家旧实例**（命令行含本包 main.py 完整路径，或 npm 包内 app/main.py）
+  → 杀树（TerminateProcess 直杀）——升级/重启最常见的占用者就是没退干净
+  的 CodeBee 自己；控制台进程对温和信号（WM_CLOSE）无反应，温和关不掉
+  正是用户「旧进程太难杀」的痛点，所以自家实例直接强杀。
+- **别人的进程** → 只报告占用者，不发送任何信号；启动流程不得替用户
+  关闭可能正在开发中的服务。
+- 系统/自身进程拒关（portscan 内置护栏）。
+"""
+from __future__ import annotations
+
+import logging
+import os
+import shlex
+import subprocess
+
+from . import portscan, runner
+
+log = logging.getLogger(__name__)
+
+PS_EXE = "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"
+
+
+def proc_cmdline(pid):
+    """读进程命令行；失败返回空串。仅用于确认旧 CodeBee 实例身份。"""
+    try:
+        pid = int(pid)
+    except (TypeError, ValueError):
+        return ""
+    if pid <= 0:
+        return ""
+    if os.name != "nt":
+        try:
+            with open("/proc/%d/cmdline" % pid, "rb") as fh:
+                return fh.read().decode("utf-8", "replace").replace("\x00", " ").strip()
+        except Exception:
+            return ""
+    try:
+        r = subprocess.run(
+            [PS_EXE, "-NoProfile", "-Command",
+             "(Get-CimInstance Win32_Process -Filter 'ProcessId = %d').CommandLine" % pid],
+            capture_output=True, timeout=10)
+        return r.stdout.decode("utf-8", "replace").strip() if r.returncode == 0 else ""
+    except Exception:
+        return ""
+
+
+def _command_tokens(cmdline):
+    try:
+        return [token.strip().strip('"').strip("'")
+                for token in shlex.split(str(cmdline or ""), posix=False)]
+    except (TypeError, ValueError):
+        return []
+
+
+def is_own_instance(cmdline, main_script, port=None):
+    """按启动器、脚本独立参数和端口精确确认 CodeBee 实例。"""
+    tokens = _command_tokens(cmdline)
+    if len(tokens) < 2:
+        return False
+    launcher = os.path.splitext(os.path.basename(tokens[0]))[0].lower()
+    if launcher not in ("python", "python3", "py"):
+        return False
+    script = ""
+    for token in tokens[1:]:
+        if token.startswith("-"):
+            continue
+        script = token
+        break
+    if not script or not os.path.isabs(script):
+        return False
+    actual = os.path.normcase(os.path.normpath(os.path.abspath(script)))
+    expected = os.path.normcase(os.path.normpath(os.path.abspath(str(main_script))))
+    packaged = actual.replace("\\", "/").lower().endswith(
+        "/node_modules/codebee/app/main.py")
+    if actual != expected and not packaged:
+        return False
+    if port is None:
+        return True
+    try:
+        wanted = str(int(port))
+    except (TypeError, ValueError):
+        return False
+    explicit_port = None
+    for i, token in enumerate(tokens):
+        if token == "--port" and i + 1 < len(tokens):
+            explicit_port = tokens[i + 1]
+        elif token.startswith("--port="):
+            explicit_port = token.split("=", 1)[1]
+    # argparse 默认端口可不出现在旧实例参数中；非默认端口必须显式相符。
+    return ((explicit_port == wanted) if explicit_port is not None
+            else wanted == "8765")
+
+
+def clear_stale_port(port, main_script):
+    """清掉占用端口的进程。返回 (是否清掉, 人话说明)。"""
+    holders = [p for p in portscan.listening_ports() if p.get("port") == int(port)]
+    if not holders:
+        return True, ""
+    pid = int(holders[0].get("pid") or 0)
+    if pid <= 4 or pid == os.getpid():
+        return False, "占用者是系统进程/自身，拒绝清理"
+    if is_own_instance(proc_cmdline(pid), main_script, port=port):
+        try:
+            runner._kill_tree(pid)
+            return True, "已结束旧实例 PID %d" % pid
+        except Exception as e:
+            return False, "旧实例 PID %d 清理失败 %s" % (pid, str(e)[:80])
+    return False, "占用者非 CodeBee（PID %d），未自动关闭" % pid