codebee 0.1.67 → 0.1.68

package/app/core/paihang.py

@@ -1,138 +1,138 @@
-# -*- 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（调用方回落直连提示词）。"""
-    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"
-        "1. **热门题材 Top3**：各自的共同特征与上榜代表书目（跨平台重合的题材单独点出——多平台都热说明是真风口）\n"
-        "2. **高频人设/套路总结**：3-5 条，点名反复出现的元素\n"
-        "3. **差异化切入建议**：2-3 个，结合用户方向给出「题材+人设」组合与一句话理由\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（调用方回落直连提示词）。"""
+    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"
+        "1. **热门题材 Top3**：各自的共同特征与上榜代表书目（跨平台重合的题材单独点出——多平台都热说明是真风口）\n"
+        "2. **高频人设/套路总结**：3-5 条，点名反复出现的元素\n"
+        "3. **差异化切入建议**：2-3 个，结合用户方向给出「题材+人设」组合与一句话理由\n"
+        "直接输出分析报告，不要复述素材清单，不要输出与报告无关的内容。"
+        % (material, goal or "（用户未指定方向，按大盘热门分析）"))

package/app/core/paths.py

@@ -54,8 +54,8 @@ def default_data_dir(repo=None, environ=None) -> Path:
 DATA_DIR = default_data_dir()
 TASKS_DIR = DATA_DIR / "tasks"
 RUNS_DIR = DATA_DIR / "runs"
-USAGE_DIR = DATA_DIR / "usage"
-ERRORS_DIR = DATA_DIR / "errors"
+USAGE_DIR = DATA_DIR / "usage"
+ERRORS_DIR = DATA_DIR / "errors"
 PUBLISH_DIR = DATA_DIR / "publish"  # 一键发布：台账/作品登记/流程选择器覆盖/浏览器 profile
 CATALOG_FILE = DATA_DIR / "catalog.json"
 ENABLED_FILE = DATA_DIR / "orchestration.json"

package/app/core/pipeline.py

@@ -829,6 +829,7 @@ __CONTEXT__
   不要自造评分标准或质量闸门；超出任务目标的「顺手加固」一律不做。
   真实风险照样要找：发现就写进总结，由人决定要不要修。
 - 完成后只用 3-5 句话总结你改了什么、为什么。
+- 交付物从简：回复不写开场白、不复述任务、不堆与改动无关的解释——代码、说明、总结直接给干货（借鉴 claude-token-efficient：输出 token 也是真金白银）。
 __VERIFY_HINT__"""
 
 CODE_FIX_PROMPT = """你是一名高级工程师。你之前的实现没有通过验收，请在当前工作目录中直接修复（直接修改/创建文件）。创建/写入的文件一律以 UTF-8 编码保存（PowerShell 显式加 -Encoding UTF8，禁止依赖系统默认编码）。
@@ -2088,6 +2089,10 @@ CONTENT_DELIVERY_CONTRACTS = {
     "novel": ("小说作者", [
         "遵守用户给定的题材、篇幅、视角和风格；未给出的核心设定不要擅自扩张。",
         "用场景、行动和对话推进冲突，人物动机与前后因果保持一致。",
+        # Madman-Architect-Carpenter 写作框架（writing-with-agents 借鉴；Judge=评审链已有）：
+        # 先发散倾倒念头再组织结构成文，不要边写边自我审查把点子掐死在半路
+        "成文分三步：先把不设限的情节/画面/台词念头快速倾倒成素材清单，再挑出主线组织成"
+        "结构，最后按结构成文——初稿期不做质量审判。",
     ]),
     "article": ("平台内容主编", [
         "标题、开头钩子、正文层级和结尾行动建议要适配目标平台与读者。",
@@ -2129,6 +2134,9 @@ CONTENT_DELIVERY_CONTRACTS = {
         # sepia 分场合规则（PR 回复体裁）：先答再铺陈；篇幅与利害成正比
         "第一句/第一段先给结论或答复（对方要做什么、答应还是不答应），再给必要背景。",
         "请求具体到动作与截止时间；篇幅与事情轻重成正比，删掉礼节性空话与自我表扬。",
+        # agentic-inbox 借鉴（线程级交付契约）：回复是对话不是独白
+        "回复往来邮件时逐条回应对方提出的每个问题与请求（可用清单），不漏问、不回避；"
+        "行动项落到具体动作+负责人+截止时间。",
     ]),
     "tech_proposal": ("解决方案架构师", [
         "覆盖现状与目标、约束、候选方案对比、推荐架构、实施阶段、风险与回滚、验收指标。",
@@ -2167,7 +2175,9 @@ def _content_contract(task):
     return "\n\n## 本类型交付约束\n" + "\n".join("- " + item for item in spec[1])
 
 # 调研报告类稿件的追加要求（借鉴 gpt-researcher 迭代深研）：有网络/读文件工具时
-# 多源交叉验证，单源结论降权——调研的可信度来自证据链而非文采
+# 多源交叉验证，单源结论降权——调研的可信度来自证据链而非文采。
+# 来源冲突裁决借鉴 deepresearch-agent 记忆层矛盾检测（Majority/Source-Weight 消解）；
+# 子问题缺口补查借鉴 dzhng/deep-research 迭代循环
 RESEARCH_APPENDIX = """
 
 ## 调研要求（证据链）
@@ -2175,6 +2185,11 @@ RESEARCH_APPENDIX = """
   单源信息要标注「仅单一来源」。
 - 引用来源在文中用行内链接或脚注标明（域名即可，不编造 URL）。
 - 区分「事实」与「观点」：数据/时间/版本号给来源，预测/评价标明是分析。
+- 来源冲突显式裁决：同一事实多个来源说法不一致时，写明分歧点与各方依据，给出
+  倾向判断和理由（多数来源一致取多数，权威差异按来源可信度加权）——不各说一半，
+  也不悄悄只取其一。
+- 缺口驱动补查：起草前先列出报告要回答的子问题清单，逐个核对证据是否到位；
+  没找到答案的子问题明确标注「证据不足」，不用泛泛而谈填空。
 - 结构硬性要求：报告第一段必须是「**核心结论**」三行以内的要点摘要（结论先行），
   之后才展开分层论证 → 风险与局限（说明哪些结论证据不足）。"""
 

package/app/core/planner.py

@@ -140,6 +140,8 @@ hard 也不做任务没要的防御性扩展子任务（缓存/重试/监控/通
 拆解之前先用你的读文件/搜索工具**实际查看工作目录**，找到目标相关的真实文件与函数，再据此拆解。
 detail 必须点名真实存在的文件路径；files 列出该子任务会改动的文件（新建的写目标路径）。
 **没探索过就不要凭想象编路径**——计划的可执行性取决于它对真实代码库的贴合度。
+detail 的清晰度按「初级工程师测试」校验：假设执行者没有项目上下文、不做隐含判断，
+只读 detail 就能照做不跑偏（借鉴 superpowers）。
 若工作目录为空（全新项目），files 写计划新建的文件路径。
 
 ## 开发目标

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