codebee 0.1.23 → 0.1.25

package/app/core/selfupdate.py

@@ -161,8 +161,21 @@ def check(force=False):
     return out
 
 
-def apply_upgrade():
-    """发起升级：建 mgmt run 异步跑 npm install -g @latest。返回 {run_id} 或 {error}。"""
+_PENDING_PORT = None   # apply_upgrade 记下的服务端口，升级成功后自动重启用
+
+
+def apply_upgrade(port=None):
+    """发起升级：建 mgmt run 异步跑 npm install -g @latest。返回 {run_id} 或 {error}。
+
+    port=服务端口：升级成功且版本真变时会自动就地重启（用户拍板 2026-09-21：
+    升级完不该再要求手动点「重启服务生效」——旧进程滞留是 unknown api/界面
+    闪烁/老宠物一类「升级了没生效」事故的总根子）。拿不到端口或运行环境不
+    具备时自动跳过，回落版本页的手动重启按钮。"""
+    global _PENDING_PORT
+    try:
+        _PENDING_PORT = int(port) if port else None
+    except (TypeError, ValueError):
+        _PENDING_PORT = None
     if install_mode() != "npm":
         return {"error": "当前安装方式不支持自动升级（见版本页说明）"}
     from . import store, jobs
@@ -176,15 +189,15 @@ def apply_upgrade():
     try:
         jobs.enqueue({"kind": "selfupgrade", "run_id": run["id"]})
     except Exception:
-        # run 已持久化；启动失败时显式收口，版本页不能停在误导性的待启动状态。
-        log.exception("selfupdate: 升级任务启动失败 run=%s", run["id"])
+        # run 已持久化；启动失败时显式收口，版本页不能停在误导性的待启动状态。
+        log.exception("selfupdate: 升级任务启动失败 run=%s", run["id"])
         try:
             store.update_run(run["id"], status="failed",
-                             error="升级任务启动失败，本次未排队，请稍后重试",
+                             error="升级任务启动失败，本次未排队，请稍后重试",
                              ended_at=time.strftime("%Y-%m-%d %H:%M:%S"))
         except Exception:
             log.exception("selfupdate: 升级运行失败收口失败 run=%s", run["id"])
-        return {"error": "升级任务启动失败，本次未排队，请稍后重试", "run_id": run["id"]}
+        return {"error": "升级任务启动失败，本次未排队，请稍后重试", "run_id": run["id"]}
     return {"run_id": run["id"]}
 
 
@@ -209,39 +222,85 @@ def _log_note(log_path, text):
         pass
 
 
-def run_upgrade(run_id, log_path, cancel_event=None):
+def _maybe_auto_relaunch(old_pkg, log_path):
+    """升级成功后的自动重启（三道守卫，任一不满足就回落手动按钮）：
+    ①知道服务端口（apply_upgrade 传入）；②版本真的变了（同版本重装不折腾）；
+    ③没有用户任务在跑（jobs._alive 只剩本升级任务自己）——正在干活的任务
+    不能被升级重启打断，此时留给用户挑自己合适的时间手动重启。"""
+    import threading
+    from . import jobs
+    if not _PENDING_PORT:
+        _log_note(log_path, "未记录服务端口，跳过自动重启——请在版本页手动重启生效")
+        return
+    new_pkg = package_version()
+    if not old_pkg or new_pkg == old_pkg:
+        _log_note(log_path, "版本未变化（%s），无需重启" % (new_pkg or "?"))
+        return
+    if getattr(jobs, "_alive", 0) > 1:
+        _log_note(log_path, "检测到还有 %d 个任务在运行，不自动重启——"
+                  "完成后请在版本页手动点「重启服务生效」" % (jobs._alive - 1))
+        return
+    port = _PENDING_PORT
+
+    def _go():
+        drain_started = False
+        try:
+            time.sleep(3.0)   # 留出日志收尾/浏览器看到「升级完成」的窗口
+            drain_started = jobs.begin_restart_drain()
+            if not drain_started:
+                _log_note(log_path, "延时窗口内有新任务进入，不自动重启——"
+                          "完成后请在版本页手动点「重启服务生效」")
+                return
+            _log_note(log_path, "自动重启服务以应用新版本 %s …" % new_pkg)
+            if relaunch(port):
+                self_quit()
+        except Exception:
+            log.exception("selfupdate: 自动重启失败，请在版本页手动重启")
+        finally:
+            # 正常 self_quit 会直接结束进程；若拉起失败、异常或测试替身返回，必须
+            # 释放停止接单闸，避免当前实例永久拒绝新任务。
+            if drain_started:
+                jobs.cancel_restart_drain()
+    threading.Thread(target=_go, name="selfupdate-relaunch",
+                     daemon=True).start()
+
+
+def run_upgrade(run_id, log_path, cancel_event=None):
     """worker 线程里执行升级命令（run/step 生命周期由 jobs 层管）。
 
     包目录被其他进程占用（EBUSY/EPERM：打开包目录的资源管理器/终端窗口、
     杀毒或索引扫描）是升级失败的最常见原因，且多为暂时性——自动重试
-    _RETRY_DELAYS 轮，仍败则给人话结论（原始 npm 输出在步骤日志里可查）。"""
-    res = {}
-    for attempt, delay in enumerate((0,) + _RETRY_DELAYS):
-        if cancel_event is not None and cancel_event.is_set():
-            return {"ok": False, "exit_code": None, "error": "用户主动取消",
-                    "cancelled": True}
-        if delay:
-            _log_note(log_path, "目录被占用（EBUSY/EPERM），%d 秒后自动重试（第 %d/%d 次）"
-                      % (delay, attempt, len(_RETRY_DELAYS)))
-            if cancel_event is not None and cancel_event.wait(delay):
-                return {"ok": False, "exit_code": None, "error": "用户主动取消",
-                        "cancelled": True}
-            if cancel_event is None:
-                time.sleep(delay)
-        res = runner.run_process(
+    _RETRY_DELAYS 轮，仍败则给人话结论（原始 npm 输出在步骤日志里可查）。
+    成功且版本真变时自动重启服务（_maybe_auto_relaunch，守卫见其 docstring）。"""
+    old_pkg = package_version()
+    res = {}
+    for attempt, delay in enumerate((0,) + _RETRY_DELAYS):
+        if cancel_event is not None and cancel_event.is_set():
+            return {"ok": False, "exit_code": None, "error": "用户主动取消",
+                    "cancelled": True}
+        if delay:
+            _log_note(log_path, "目录被占用（EBUSY/EPERM），%d 秒后自动重试（第 %d/%d 次）"
+                      % (delay, attempt, len(_RETRY_DELAYS)))
+            if cancel_event is not None and cancel_event.wait(delay):
+                return {"ok": False, "exit_code": None, "error": "用户主动取消",
+                        "cancelled": True}
+            if cancel_event is None:
+                time.sleep(delay)
+        res = runner.run_process(
             argv=_npm_argv("install", "-g", _PKG_NAME + "@latest"),
             # Windows 上 npm 换版本靠把包目录整体改名（codebee → .codebee-xxx）；
             # cwd 若落在本包内，目录被自身进程占用，rename 必报 EBUSY——钉在包外
-            cwd=str(Path.home()), timeout=900, log_path=log_path,
-            cancel_event=cancel_event)
-        if res.get("cancelled"):
-            return {"ok": False, "exit_code": res.get("exit_code"),
-                    "error": "用户主动取消", "cancelled": True}
+            cwd=str(Path.home()), timeout=900, log_path=log_path,
+            cancel_event=cancel_event)
+        if res.get("cancelled"):
+            return {"ok": False, "exit_code": res.get("exit_code"),
+                    "error": "用户主动取消", "cancelled": True}
         if res["ok"] or not _locked_error(res):
             break
     if res["ok"]:
         with _LOCK:  # 装完即过期查新缓存，重启后自然拿到新版本
             _CHECK_CACHE["result"] = None
+        _maybe_auto_relaunch(old_pkg, log_path)
         return {"ok": True, "exit_code": res["exit_code"], "error": ""}
     stderr = res["stderr"] or ""
     if _locked_error(res):

package/app/core/store.py

@@ -246,10 +246,8 @@ def create_task(payload):
                 raise ValueError("附件落盘失败: %s" % e)
         if items:
             task["attachments"] = items
-            blk = att_mod.context_block(items)
-            # 复制清单场景下 context 已含附件块（随旧任务沿用），别重复追加
-            if blk and "## 附件材料" not in task["context"]:
-                task["context"] = (task["context"] + blk).strip()
+            task["context"] = att_mod.merge_context(
+                task["context"], items, workdir=str(wd))
     with LOCK:
         _TASKS[task["id"]] = task
         _save_json(paths.TASKS_DIR / (task["id"] + ".json"), task)
@@ -684,11 +682,33 @@ def update_run(run_id, expected_status=None, **fields):
         return run
 
 
-def run_dir(run_id):
-    return paths.RUNS_DIR / run_id
-
-
-def delete_run(run_id):
+def run_dir(run_id):
+    return paths.RUNS_DIR / run_id
+
+
+def _schedule_run_dir_cleanup(run_id):
+    """把运行目录快速移出可见路径，再后台删除大日志目录。
+
+    删除任务/运行记录不能让 HTTP 请求同步递归扫描数千个日志文件。
+    同盘 rename 是 O(1)，原路径立即消失；后台失败也不会影响内存状态。
+    """
+    source = paths.RUNS_DIR / str(run_id)
+    if not source.exists():
+        return
+    target = paths.RUNS_DIR / (".deleting-%s-%s" % (run_id, secrets.token_hex(4)))
+    try:
+        source.rename(target)
+    except OSError:
+        target = source
+
+    def _remove():
+        shutil.rmtree(target, ignore_errors=True)
+
+    threading.Thread(target=_remove, name="codebee-delete-%s" % run_id[:12],
+                     daemon=True).start()
+
+
+def delete_run(run_id):
     """删除一条运行记录（内存 + 磁盘目录）。返回 (ok, 错误信息)。"""
     if not _valid_id(run_id):
         return False, "非法的记录 ID"
@@ -699,7 +719,7 @@ def delete_run(run_id):
         if run.get("status") in ("queued", "running"):
             return False, "运行中的记录不能删除，请先取消"
         del _RUNS[run_id]
-    shutil.rmtree(paths.RUNS_DIR / run_id, ignore_errors=True)
+    _schedule_run_dir_cleanup(run_id)
     bump_state()
     return True, ""
 
@@ -1032,7 +1052,7 @@ def delete_runs(run_ids):
                 skipped += 1
                 continue
             del _RUNS[rid]
-        shutil.rmtree(paths.RUNS_DIR / rid, ignore_errors=True)
+        _schedule_run_dir_cleanup(rid)
         deleted += 1
     if deleted:
         bump_state()
@@ -1051,7 +1071,7 @@ def clear_runs():
         for rid in targets:
             del _RUNS[rid]
     for rid in targets:
-        shutil.rmtree(paths.RUNS_DIR / rid, ignore_errors=True)
+        _schedule_run_dir_cleanup(rid)
     bump_state()
     return len(targets), skipped
 
@@ -1090,9 +1110,9 @@ def delete_task(task_id):
         del _TASKS[task_id]
         for rid in run_ids:
             _RUNS.pop(rid, None)
-    for rid in run_ids:
-        shutil.rmtree(paths.RUNS_DIR / rid, ignore_errors=True)
-    (paths.TASKS_DIR / (task_id + ".json")).unlink(missing_ok=True)
+    for rid in run_ids:
+        _schedule_run_dir_cleanup(rid)
+    (paths.TASKS_DIR / (task_id + ".json")).unlink(missing_ok=True)
     bump_state()
     return True, ""
 

package/app/core/usage.py

@@ -10,8 +10,9 @@
 """
 from __future__ import annotations
 
-import json
-import threading
+import json
+import math
+import threading
 import time
 
 from . import paths
@@ -32,8 +33,12 @@ FIELDS = ("ts", "day", "run_id", "step", "task_id", "task_type", "role", "agent"
           "input", "output", "cached", "reasoning", "total", "cost_usd", "source")
 
 
-def _month_file(day):
-    return paths.USAGE_DIR / ("usage-%s.jsonl" % day[:7].replace("-", ""))
+def _month_file(day):
+    return paths.USAGE_DIR / ("usage-%s.jsonl" % day[:7].replace("-", ""))
+
+
+def _quality_file(day):
+    return paths.USAGE_DIR / ("routing-quality-%s.jsonl" % day[:7].replace("-", ""))
 
 
 def _parse_int(v):
@@ -93,10 +98,13 @@ def record(source="", run_id="", task_id="", task_type="", role="", step=0,
         rec.update({"input": inp, "output": out, "cached": cach,
                     "reasoning": reas, "total": total})
         line = json.dumps(rec, ensure_ascii=False)
-        with LOCK:
-            paths.USAGE_DIR.mkdir(parents=True, exist_ok=True)
-            with open(_month_file(rec["day"]), "a", encoding="utf-8") as f:
-                f.write(line + "\n")
+        with LOCK:
+            paths.USAGE_DIR.mkdir(parents=True, exist_ok=True)
+            with open(_month_file(rec["day"]), "a", encoding="utf-8") as f:
+                f.write(line + "\n")
+            _ROUTING_CACHE["data"].clear()
+            _ROUTING_RECORDS_CACHE.clear()
+            _HOURLY_CACHE["ts"] = 0.0
     except Exception:
         pass
 
@@ -196,8 +204,11 @@ def _tool_of(agent_id):
     return a or "unknown"
 
 
-_HOURLY_CACHE = {"ts": 0.0, "val": {}}
-_HOURLY_TTL = 60.0   # 秒：路由调用频繁但台账追加低频，60s 缓存足够新鲜
+_HOURLY_CACHE = {"ts": 0.0, "val": {}}
+_HOURLY_TTL = 60.0   # 秒：路由调用频繁但台账追加低频，60s 缓存足够新鲜
+_ROUTING_CACHE = {"data": {}}
+_ROUTING_RECORDS_CACHE = {}
+_ROUTING_TTL = 15.0
 
 
 def agent_tokens_recent(agent, hours=1):
@@ -224,7 +235,7 @@ def agent_tokens_recent(agent, hours=1):
         return 0
 
 
-def _iter_records(days):
+def _iter_records(days):
     """按时间范围读取台账（days=0 表示全部）。返回按写入顺序的记录列表。"""
     out = []
     try:
@@ -232,11 +243,14 @@ def _iter_records(days):
     except Exception:
         return out
     since_day = ""
-    if days:
-        import datetime
-        d = (datetime.date.today() - datetime.timedelta(days=int(days) - 1)).isoformat()
-        since_day = d
-    for p in files:
+    if days:
+        import datetime
+        d = (datetime.date.today() - datetime.timedelta(days=int(days) - 1)).isoformat()
+        since_day = d
+    since_month = since_day[:7].replace("-", "") if since_day else ""
+    for p in files:
+        if since_month and p.stem.rsplit("-", 1)[-1] < since_month:
+            continue
         try:
             for line in p.read_text(encoding="utf-8", errors="replace").splitlines():
                 line = line.strip()
@@ -253,14 +267,202 @@ def _iter_records(days):
                 out.append(r)
         except Exception:
             continue
-    return out
-
-
-def _num(r, key):
-    return _parse_int(r.get(key))
-
-
-def _group(records, key):
+    return out
+
+
+def _iter_quality_records(days):
+    """读取独立质量台账；不混入用量统计的调用数、token 和成本。"""
+    out = []
+    try:
+        files = sorted(paths.USAGE_DIR.glob("routing-quality-*.jsonl")) \
+            if paths.USAGE_DIR.is_dir() else []
+    except Exception:
+        return out
+    since_day = ""
+    if days:
+        import datetime
+        since_day = (datetime.date.today()
+                     - datetime.timedelta(days=int(days) - 1)).isoformat()
+    since_month = since_day[:7].replace("-", "") if since_day else ""
+    for path in files:
+        if since_month and path.stem.rsplit("-", 1)[-1] < since_month:
+            continue
+        try:
+            for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+                try:
+                    row = json.loads(line)
+                except Exception:
+                    continue
+                if isinstance(row, dict) and (not since_day or row.get("day", "") >= since_day):
+                    out.append(row)
+        except Exception:
+            continue
+    return out
+
+
+def _routing_records(days):
+    """同一轮候选评分共享一次台账解析，避免每个候选重复扫全盘。"""
+    key = (str(paths.USAGE_DIR), int(days))
+    now = time.time()
+    with LOCK:
+        cached = _ROUTING_RECORDS_CACHE.get(key)
+        if cached and now - cached[0] <= _ROUTING_TTL:
+            return list(cached[1]), list(cached[2])
+    calls, quality = _iter_records(days), _iter_quality_records(days)
+    with LOCK:
+        _ROUTING_RECORDS_CACHE[key] = (now, list(calls), list(quality))
+    return calls, quality
+
+
+def record_quality_for_run(run_id, quality_ok, agent=""):
+    """把验收结论归因到最终实际产出者，不重复计入用量。"""
+    try:
+        run_id = str(run_id or "")[:64]
+        if not run_id:
+            return 0
+        calls = [r for r in _iter_records(2)
+                 if r.get("run_id") == run_id and r.get("ok") is True]
+        prefixes = ("implement", "fix", "draft", "revise", "polish", "direct", "author")
+        calls = [r for r in calls if str(r.get("role") or "").lower().startswith(prefixes)]
+        agent = str(agent or "")[:40]
+        unique = {}
+        for row in calls:
+            key = tuple(str(row.get(k) or "") for k in
+                        ("task_id", "task_type", "role", "agent", "model", "provider"))
+            unique[key] = row
+        if not unique:
+            return 0
+        existing = {(r.get("run_id"), r.get("role"), r.get("agent"),
+                     r.get("model"), r.get("provider"))
+                    for r in _iter_quality_records(2)}
+        day = time.strftime("%Y-%m-%d")
+        rows = []
+        for row in unique.values():
+            identity = (run_id, row.get("role"), row.get("agent"),
+                        row.get("model"), row.get("provider"))
+            if identity in existing:
+                continue
+            # 成功调用不等于产出通过。换将前的实现者即使传输成功，也已被质量
+            # 门淘汰，必须留下负样本；最终实际产出者才继承本次验收结论。
+            row_quality_ok = bool(quality_ok)
+            if agent and str(row.get("agent") or "") != agent:
+                row_quality_ok = False
+            rows.append({"ts": time.strftime("%Y-%m-%d %H:%M:%S"), "day": day,
+                         "run_id": run_id, "task_id": row.get("task_id") or "",
+                         "task_type": row.get("task_type") or "unknown",
+                         "role": row.get("role") or "unknown",
+                         "agent": row.get("agent") or "unknown",
+                         "model": row.get("model") or "(默认)",
+                         "provider": row.get("provider") or "",
+                         "quality_ok": row_quality_ok})
+        if not rows:
+            return 0
+        with LOCK:
+            paths.USAGE_DIR.mkdir(parents=True, exist_ok=True)
+            with open(_quality_file(day), "a", encoding="utf-8") as handle:
+                for row in rows:
+                    handle.write(json.dumps(row, ensure_ascii=False) + "\n")
+            _ROUTING_CACHE["data"].clear()
+            _ROUTING_RECORDS_CACHE.clear()
+        return len(rows)
+    except Exception:
+        return 0
+
+
+def _num(r, key):
+    return _parse_int(r.get(key))
+
+
+def _percentile(values, percentile):
+    """线性插值百分位，空样本返回 0。"""
+    if not values:
+        return 0.0
+    ordered = sorted(float(v) for v in values)
+    if len(ordered) == 1:
+        return round(ordered[0], 2)
+    pos = (len(ordered) - 1) * float(percentile)
+    lo = int(math.floor(pos))
+    hi = int(math.ceil(pos))
+    if lo == hi:
+        return round(ordered[lo], 2)
+    return round(ordered[lo] + (ordered[hi] - ordered[lo]) * (pos - lo), 2)
+
+
+def routing_stats(task_type="", role="", agent="", model="", provider="",
+                  days=90, min_samples=3):
+    """返回路由用的近期真实运行指标。
+
+    只读取脱敏用量台账；精确维度样本不足时依次回退到任务+角色、任务、
+    全局，成功率使用 Beta(3, 1) 平滑，避免单次失败永久压低新候选。
+    """
+    try:
+        task_type = str(task_type or "")[:32]
+        role = str(role or "")[:40]
+        agent = str(agent or "")[:40]
+        model = str(model or "")[:80]
+        provider = str(provider or "")[:60]
+        days = max(0, int(days))
+        min_samples = max(1, int(min_samples))
+    except (TypeError, ValueError):
+        days, min_samples = 90, 3
+    # DATA_DIR 可在测试、多实例或运行时配置切换；纳入缓存键，避免跨目录
+    # 复用另一套台账的线上指标。
+    key = (str(paths.DATA_DIR), task_type, role, agent, model, provider,
+           days, min_samples)
+    now = time.time()
+    with LOCK:
+        cached = _ROUTING_CACHE["data"].get(key)
+        if cached and now - cached[0] <= _ROUTING_TTL:
+            return dict(cached[1])
+    records, quality_records = _routing_records(days)
+
+    def matches(record, filters):
+        return all(str(record.get(field) or "") == value
+                   for field, value in filters.items() if value)
+
+    # 先保留所有已提供的维度；后续逐层放宽，确保模型和 CLI 都能共享一套查询。
+    exact = {"task_type": task_type, "role": role, "agent": agent,
+             "model": model, "provider": provider}
+    fallbacks = [(exact, "exact")]
+    task_role = {"task_type": task_type, "role": role}
+    if task_role != exact:
+        fallbacks.append((task_role, "task-role"))
+    if task_type:
+        fallbacks.append(({"task_type": task_type}, "task"))
+    fallbacks.append(({}, "global"))
+    selected, label = [], "global"
+    for filters, candidate_label in fallbacks:
+        candidate = [r for r in records if matches(r, filters)]
+        if len(candidate) >= min_samples or (candidate_label == "global" and candidate):
+            selected, label = candidate, candidate_label
+            break
+    chosen_filters = next((filters for filters, candidate_label in fallbacks
+                           if candidate_label == label), {})
+    quality_selected = [r for r in quality_records if matches(r, chosen_filters)]
+    success_rows = quality_selected or selected
+    success_key = "quality_ok" if quality_selected else "ok"
+    successes = sum(1 for r in success_rows if bool(r.get(success_key)))
+    durations = [max(0.0, _parse_float(r.get("duration_s"))) for r in selected]
+    costs = [max(0.0, _parse_float(r.get("cost_usd"))) for r in selected]
+    samples = len(selected)
+    success_samples = len(success_rows)
+    result = {
+        "samples": samples,
+        "quality_samples": len(quality_selected),
+        "success_samples": success_samples,
+        "successes": successes,
+        "success_rate": round((successes + 3.0) / (success_samples + 4.0), 4),
+        "p50_duration_s": _percentile(durations, 0.50),
+        "p95_duration_s": _percentile(durations, 0.95),
+        "avg_cost_usd": round(sum(costs) / samples, 6) if samples else 0.0,
+        "fallback": label,
+    }
+    with LOCK:
+        _ROUTING_CACHE["data"][key] = (now, dict(result))
+    return result
+
+
+def _group(records, key):
     """按 key 聚合：{name: {calls, ok, tokens, input, output, cached, cache_rate, cost_usd, duration_s}}。"""
     groups = {}
     for r in records:

package/app/main.py

@@ -284,6 +284,18 @@ class Handler(BaseHTTPRequestHandler):
                 except ValueError:
                     edays = 90
                 return self._json(200, usage.estimate(task_type=ttype, days=edays))
+            if path == "/api/dispatch/replay":
+                from core import dispatch_log
+                q = parse_qs(urlparse(self.path).query)
+                try:
+                    limit = max(1, min(1000, int((q.get("limit") or ["100"])[0])))
+                except (TypeError, ValueError):
+                    limit = 100
+                events = dispatch_log.replay(
+                    run_id=(q.get("run_id") or [""])[0],
+                    task_type=(q.get("task_type") or [""])[0],
+                    limit=limit)
+                return self._json(200, {"events": events, "count": len(events)})
             if path == "/api/diagnostics/bundle":
                 # 诊断包（zip）：脱敏错误台账 + 用量台账 + 环境元信息，供用户贴 Issue
                 from core import telemetry
@@ -741,14 +753,13 @@ class Handler(BaseHTTPRequestHandler):
         if path == "/api/selfupdate/apply":
             from core import selfupdate
             try:
-                res = selfupdate.apply_upgrade()
+                res = selfupdate.apply_upgrade(PORT)
             except Exception:
                 log.exception("自更新任务创建失败")
                 return self._json(503, {"error": "升级任务创建失败，请稍后重试"})
             return self._json(400, res) if res.get("error") else self._json(200, dict(res, ok=True))
         if path == "/api/selfupdate/restart":
             from core import selfupdate
-            global PORT
             if not selfupdate.relaunch(PORT):
                 return self._json(400, {"error": "重启参数非法"})
             def _bye():
@@ -2066,8 +2077,9 @@ class Handler(BaseHTTPRequestHandler):
                   "每个问题给出 2-4 个最常见的选项。只输出 JSON 数组，不要输出其他内容：\n"
                   '[{"q": "问题", "options": ["选项1", "选项2"]}]' % (ttype, goal[:200]))
         try:
+            # 澄清是可选增强，不能占住创建请求；主流程有自己的执行超时。
             res = builtin_agent.run(bi, prompt, os.getcwd() if hasattr(os, "getcwd") else ".",
-                                    timeout=60)
+                                    timeout=8)
             import json as _json
             arr = None
             text = (res.get("text") or "").strip()
@@ -2435,27 +2447,47 @@ def main():
         # 分发，表现为"时好时坏"）；加独占锁后双起在这里干净失败并指路。
         # （此处不能局部 import os：会让 os 变 main() 的局部名，后面 2127 行
         #  的 os.name 直接 UnboundLocalError——顶部已有全局导入，直接用）
-        hint = ""
-        if os.name == "nt":
-            hint = ("（Windows 排查：netstat -ano | findstr :%d 找到 PID，"
-                    "tasklist /FI \"PID eq <PID>\" 看是谁；旧进程杀掉或换 --port）"
-                    % args.port)
-        # 端口占用自动指认（借鉴 leftopen 38★）：直接报出 PID/进程/项目归属，
-        # 用户不用再手跑 netstat+tasklist 两连。识别不出时回落上面的手工指路。
+        # 端口占用自动清场（用户拍板 2026-09-21）：升级/重启最常见的占用者是
+        # 没退干净的 CodeBee 自家旧实例——先杀再起，别让用户手动 netstat+taskkill。
+        # 判定（main.py 完整路径/npm 打包路径）与清场在 core.portguard。
+        from core import portscan as _ps, portguard as _pg
+        _hint = ""
         try:
-            from core import portscan as _ps
-            for _h in _ps.listening_ports():
-                if _h.get("port") != args.port:
-                    continue
-                _who = _h.get("process") or "未知进程"
-                _proj = ("，项目 %s" % _h["project"]) if _h.get("project") else ""
-                hint = ("占用者：PID %d（%s%s）；旧进程杀掉或换 --port 重启"
-                        % (_h.get("pid") or 0, _who, _proj))
-                break
+            _cleared, _hint = _pg.clear_stale_port(
+                args.port, paths.APP_DIR / "main.py")
         except Exception:
-            pass
-        raise SystemExit("[CodeBee] 端口 %d 已被占用，无法启动：%s %s"
-                         % (args.port, e, hint))
+            _cleared, _hint = False, ""
+        if _cleared:
+            try:
+                print("[CodeBee] 端口 %d 被旧实例占用，已自动清场，正在重新绑定…"
+                      % args.port, flush=True)
+                time.sleep(1.0)   # 让被清进程的监听 socket 完全释放
+                httpd = ThreadedServer((args.host, args.port), Handler)
+            except OSError:
+                httpd = None
+        else:
+            httpd = None
+        if httpd is None:
+            # 清场没成：带占用者指认退出（识别不出回落手工排查提示）
+            hint = ""
+            if os.name == "nt":
+                hint = ("（Windows 排查：netstat -ano | findstr :%d 找到 PID，"
+                        "tasklist /FI \"PID eq <PID>\" 看是谁；旧进程杀掉或换 --port）"
+                        % args.port)
+            try:
+                for _h in _ps.listening_ports():
+                    if _h.get("port") != args.port:
+                        continue
+                    _who = _h.get("process") or "未知进程"
+                    _proj = ("，项目 %s" % _h["project"]) if _h.get("project") else ""
+                    hint = ("占用者：PID %d（%s%s）%s"
+                            % (_h.get("pid") or 0, _who, _proj,
+                               ("；" + _hint) if _hint else "；旧进程杀掉或换 --port 重启"))
+                    break
+            except Exception:
+                pass
+            raise SystemExit("[CodeBee] 端口 %d 已被占用，无法启动：%s %s"
+                             % (args.port, e, hint))
 
     def _announce_public(url):
         print("[CodeBee] 公网     %s/?token=%s" % (url, tok))