codebee 0.1.48 → 0.1.50

package/app/core/settings.py

@@ -25,7 +25,11 @@ DEFAULTS = {"max_concurrent_jobs": 12, "default_workdir": "", "hooks_token": "",
             "telemetry_errors": True, "publish_daily_cap": 10,
             "publish_fail_streak": 3, "notify_webhook": "", "notify_base_url": "",
             "pet_enabled": True, "pet_mode": "always", "pet_skin": "plush",
-            "cleanup_enabled": True, "cleanup_retention_days": 14}
+            "cleanup_enabled": True, "cleanup_retention_days": 14,
+            # claude_config_sync：打开/运行前防线是否直写 ~/.claude/settings.json。
+            # 关闭后交互 claude 配置归用户手动管理（cc-switch 等），编排步骤经
+            # runner 一次性 --settings 注入绑定链，路由不受影响（manager 读取）
+            "claude_config_sync": True}
 # 桌宠形象白名单（与 app/pet.py 的 SKINS 对齐；这里不 import pet 模块，避免
 # core 反向依赖 app 根目录脚本）
 PET_SKINS = ("plush", "robot")
@@ -127,6 +131,8 @@ def save(patch):
             cur["pet_skin"] = ps
         if "cleanup_enabled" in patch:
             cur["cleanup_enabled"] = bool(patch.get("cleanup_enabled"))
+        if "claude_config_sync" in patch:
+            cur["claude_config_sync"] = bool(patch.get("claude_config_sync"))
         if "cleanup_retention_days" in patch:
             try:
                 cur["cleanup_retention_days"] = int(patch.get("cleanup_retention_days"))

package/app/core/store.py

@@ -24,6 +24,12 @@ LOCK = threading.RLock()
 _TASKS = {}
 _RUNS = {}
 
+# 流式实时落盘的节流表：(run_id, 步骤号) -> 上次落盘时刻。步骤收尾即清，
+# 长跑也不会无限增长（finish_step 里调 clear_stream_state）。
+_STREAM_LOCK = threading.Lock()
+_STREAM_TS = {}
+LIVE_TEXT_MAX = 20000   # 单步骤实时思考/正文的保留上限（与 builtin_agent 同口径）
+
 # ---------------------------------------------------------------- 状态版本（SSE 事件驱动）
 # 任何落盘写都算状态变化：SSE 连接等版本号变化才构建/推送全量状态，
 # 空闲时连接零开销（此前每连接每 0.8s 盲构建全量 payload，多端并发会放大成假死）
@@ -218,11 +224,10 @@ def create_task(payload):
                 # 不会因分批而错位。
                 vol_spec = volumes.norm_spec(serial.get("volumes"))
                 if not vol_spec:
-                    # 表单没填卷表时，从目标/上下文文字里识别用户手写的
-                    # 「第一卷 少年初入江湖 第1-20章」式分卷信息（保守识别，
-                    # 认不出就返回空，绝不会把普通文字误判成分卷）。
-                    vol_spec = volumes.parse_spec_text(goal) \
-                        or volumes.parse_spec_text(serial.get("volumes_text")) \
+                    # 否则从文字里识别：表单「指定卷结构」框 > 任务目标 > 上下文。
+                    # 保守识别——认不出返回空，绝不把普通文字误判成分卷。
+                    vol_spec = volumes.parse_spec_text(serial.get("volumes_text")) \
+                        or volumes.parse_spec_text(goal) \
                         or volumes.parse_spec_text(task.get("context") or "")
                 if vol_spec:
                     s["volumes"] = vol_spec
@@ -548,6 +553,9 @@ def create_run(kind, title, task_id=None, entry_id=None, op=None):
             _RUNS.pop(run["id"], None)
             raise
         _RUNS[run["id"]] = run
+    # 新 run（排队/起跑）必须唤醒 SSE：否则侧栏 task_latest 感知不到
+    # 「最新一次运行」已易主，字形/时间停在上一轮（2026-09-22 侧栏假在跑案）
+    bump_state()
     return run
 
 
@@ -738,7 +746,13 @@ def update_run(run_id, expected_status=None, **fields):
                                     "error": str(run.get("error") or "")[:300]}}).start()
             except Exception:
                 pass
-        return run
+    # 每次成功写入都唤醒 SSE：run 的状态/步骤变化从前只能靠无关操作
+    # （自动化落盘、删记录）顺带广播，空闲时侧栏 task_latest 会冻在
+    # 「在跑」直到下一次无关 bump（2026-09-22 侧栏假在跑案）。
+    # 调用都是步骤级边界，不会形成推送风暴；CAS 拒绝/无此 run 的早退
+    # 路径不动版本号。
+    bump_state()
+    return run
 
 
 def run_dir(run_id):
@@ -1525,9 +1539,58 @@ def add_step(run_id, role, agent_id, agent_label, note=""):
         return step, log_abs
 
 
+def stream_step(run_id, n, thinking=None, text=None, activity=None, min_secs=0.6):
+    """步骤运行中实时落一段「思考过程/正文/活动」——对话时间线边跑边打印。
+
+    直连对话此前整轮只有三点打字动画（32 秒黑箱，用户 2026-09-22 反馈）；
+    模型的思维链与正文在流式回调里到达，这里节流落盘（默认 0.6s 一次），
+    前端 2s 轮询一次读到的就是「它正在想什么」。
+
+    节流按步骤记忆上次落盘时刻；收尾时 finish_step 会写入最终值并清掉
+    live 标记。返回是否真的落盘（调用方可据此决定要不要做下一步）。
+    """
+    key = (run_id, int(n))
+    now = time.time()
+    with _STREAM_LOCK:
+        last = _STREAM_TS.get(key, 0)
+        if min_secs and now - last < min_secs:
+            return False
+        _STREAM_TS[key] = now
+    with LOCK:
+        run = _RUNS.get(run_id)
+        if not run:
+            return False
+        for s in run["steps"]:
+            if s["n"] != n:
+                continue
+            if thinking is not None:
+                s["thinking"] = str(thinking)[-LIVE_TEXT_MAX:]
+            if text is not None:
+                s["stream"] = str(text)[-LIVE_TEXT_MAX:]
+            if activity:
+                acts = list(s.get("activity") or [])
+                if not acts or acts[-1] != activity:
+                    acts.append(str(activity)[:200])
+                s["activity"] = acts[-8:]
+            s["live"] = int(s.get("live") or 0) + 1   # 前端重绘签名（内容变即刷新）
+            _save_json(paths.RUNS_DIR / run_id / "run.json", run)
+            return True
+    return False
+
+
+def clear_stream_state(run_id=None, n=None):
+    """清掉流式节流状态（步骤收尾/测试收场用），避免字典随长跑无限增长。"""
+    with _STREAM_LOCK:
+        if run_id is None:
+            _STREAM_TS.clear()
+            return
+        for key in [k for k in _STREAM_TS if k[0] == run_id and (n is None or k[1] == n)]:
+            _STREAM_TS.pop(key, None)
+
+
 def finish_step(run_id, n, status, summary="", exit_code=None,
                 cost_usd=0.0, tokens=0.0, duration_s=None, model=None, output=None,
-                followups=None):
+                followups=None, thinking=None):
     with LOCK:
         run = _RUNS.get(run_id)
         if not run:
@@ -1550,12 +1613,20 @@ def finish_step(run_id, n, status, summary="", exit_code=None,
                     # output 是智能体正文（对话气泡直读）：只剥 ANSI，不做噪声折叠
                     # ——正文里的装饰性长串是作者写的，不能替它省略
                     s["output"] = runner.strip_ansi(str(output))[:6000]
+                if thinking is not None:
+                    s["thinking"] = runner.strip_ansi(str(thinking))[:LIVE_TEXT_MAX]
                 if followups:
                     s["followups"] = list(followups)[:3]
+                # 收尾即清运行中态：stream/activity/live 只是过程快照，留着会让
+                # 前端把「已结束」的步骤仍当实时流渲染（也白占 run.json 体积）
+                s.pop("stream", None)
+                s.pop("activity", None)
+                s.pop("live", None)
                 break
         run["cost_usd"] = round(run.get("cost_usd", 0.0) + cost_usd, 4)
         run["tokens"] = run.get("tokens", 0) + tokens
         _save_json(paths.RUNS_DIR / run_id / "run.json", run)
+    clear_stream_state(run_id, n)
 
 
 # ---------------------------------------------------------------- 运行中指挥（消息信箱）

package/app/core/volumes.py

@@ -169,8 +169,10 @@ def parse_spec_text(text):
     「第一卷 少年初入江湖 第1-20章；卷二 风云再起 21-40章」）。
 
     保守策略：必须出现 ≥1 个卷标记（第X卷/卷X/第X部/第X篇）才认为用户在
-    分卷，且除末卷外每个卷段都要有章号范围或章数（末卷可省 = 开放到书末）。
-    识别不到就返回 []，绝不猜——误判会把普通文字里的「第一卷」当成分卷要求。
+    分卷；且**每个卷段都必须带边界**（章号范围 / 章数 / 「N章起」开放标记）。
+    缺边界的段一律判为「不是分卷信息」——「第一卷要吸引人」这类句子里的
+    「第一卷」是修辞不是结构，绝不能据此把全书切成一个卷。正常写法都带边界
+    （「第一卷 少年初入江湖 20章」「第1-20章」「21章起」），因此不受影响。
 
     切段方式：按**卷标记出现位置**切（而非按行/分号），这样「卷一 甲 20章，
     卷二 乙 25章」这种同一行多卷也能正确拆开。"""
@@ -191,7 +193,7 @@ def parse_spec_text(text):
         end = marks[i + 1].start() if i + 1 < len(marks) else len(text)
         segs.append((text[m.start():end], key))
     out = []
-    for idx, (seg, _num) in enumerate(segs):
+    for seg, _num in segs:
         m = _VOL_RE.match(seg)     # seg 以卷标记起头，相对位置 0
         if not m:
             continue
@@ -208,8 +210,8 @@ def parse_spec_text(text):
             m2 = _COUNT_RE.search(body) or _COUNT_RE.search(seg[:m.start()])
             chapters = _to_int(m2.group(1)) if m2 else None
             start, end = None, None
-        if idx < len(segs) - 1 and not (chapters or (start and end)):
-            # 非末卷却没有边界：整段解析不可信，放弃（避免半数卷无边界的错切）
+        if not (chapters or (start and end) or (op and start)):
+            # 该卷段没有可用的边界：整段判为不是分卷信息（见 docstring）
             return []
         out.append({"title": _clean_title(seg, m), "start": start,
                     "end": end, "chapters": chapters})

package/app/core/zentao.py

@@ -4,7 +4,7 @@
 数据落盘 <data>/zentao.json（tmp + os.replace 原子写；TUTTI_DATA 环境变量感知）。
 修复走与 /api/tasks 完全相同的链路（store.create_task → store.create_run →
 jobs.enqueue，code 引擎=实现→验证→评审→修复），不自造运行器。调度挂在
-automation._tick（同 publish/auto.fire_due 模式），内部按 interval_hours 节流。
+automation._tick（同 publish/auto.fire_due 模式），内部按 interval_minutes 节流。
 
 禅道 REST API v1（开源版 15.x+；请求头 Token: <token>）：
   POST {base}/api.php/v1/tokens               {account, password} → {token}
@@ -76,7 +76,9 @@ PAGE_LIMIT = 100
 MAX_BUGS = 500
 RESOLVE_MAX_ATTEMPTS = 3
 RETRY_DELAY_MIN = 30
-INTERVAL_MIN, INTERVAL_MAX = 1, 168
+INTERVAL_MIN, INTERVAL_MAX = 5, 10080   # 扫描间隔（分钟）：5 分钟 ~ 7 天
+INTERVAL_DEFAULT = 5
+_LEGACY_INTERVAL_HOURS_DEFAULT = 2      # 老配置 interval_hours 缺省值（迁移用）
 
 SIDES = ("backend", "frontend")
 TRIAGE_SIDES = ("backend", "frontend", "both", "not_ours")   # unknown 单列
@@ -91,7 +93,7 @@ _CFG_DEFAULTS = {
     "auto_merge": True,
     "triage_ai": True,         # 模块路由未命中时用 AI 兜底排查
     "poll_enabled": False,
-    "interval_hours": 2,
+    "interval_minutes": INTERVAL_DEFAULT,
 }
 
 _REPO_DEFAULTS = {"workdir": "", "git_rev": "", "verify_command": ""}
@@ -109,7 +111,7 @@ _PROFILE_DEFAULTS = {
 
 _UPDATABLE = ("base_url", "account", "password", "product_profiles",
               "auto_resolve", "auto_merge", "triage_ai",
-              "poll_enabled", "interval_hours")
+              "poll_enabled", "interval_minutes")
 
 
 # ---------------------------------------------------------------- 出网边界（SSRF）
@@ -232,6 +234,17 @@ def load(force=False):
         # 必须在按 _CFG_DEFAULTS 过滤之前完成迁移）
         if isinstance(cfg, dict) and not cfg.get("product_profiles"):
             cfg = _migrate_legacy(dict(cfg))
+        # 老配置用 interval_hours（小时），新配置改用 interval_minutes（分钟）：
+        # 用户没动过间隔（还是老默认 2 小时）就跟随新默认 5 分钟；真改过的按小时换算保留。
+        if isinstance(cfg, dict) and "interval_minutes" not in cfg \
+                and "interval_hours" in cfg:
+            try:
+                hours = int(cfg.get("interval_hours") or _LEGACY_INTERVAL_HOURS_DEFAULT)
+            except (TypeError, ValueError):
+                hours = _LEGACY_INTERVAL_HOURS_DEFAULT
+            cfg = dict(cfg)
+            mins = INTERVAL_DEFAULT if hours == _LEGACY_INTERVAL_HOURS_DEFAULT else hours * 60
+            cfg["interval_minutes"] = max(INTERVAL_MIN, min(INTERVAL_MAX, mins))
         merged = dict(_CFG_DEFAULTS)
         if isinstance(cfg, dict):
             merged.update({k: v for k, v in cfg.items() if k in _CFG_DEFAULTS})
@@ -623,7 +636,8 @@ def _pairs_to_list(pairs, id_key, name_key):
 def _module_items(d):
     """老版模块树形状兼容（2026-09-21 真机反馈「响应形状不认识」）：
     sons/modules 数组、{id: {name,...}} 字典、children/sons 嵌套树，统一
-    递归展开成 [{id,name}] 平铺清单（id=0 是树根容器，跳过）。"""
+    递归展开成 [{id,name}] 平铺清单（id=0 是树根容器，跳过）；全数字键的
+    {id: 名字} 扁平映射也认（部分版本的模块摘要形状）。"""
     out = []
 
     def walk(node):
@@ -637,11 +651,19 @@ def _module_items(d):
                     if isinstance(node.get(k), (list, dict)):
                         walk(node[k])
             else:
+                if node and all(str(k).isdigit() for k in node.keys()):
+                    flat = [{"id": k, "name": str(v)}
+                            for k, v in node.items() if str(v or "").strip()]
+                    if flat:
+                        out.extend(flat)
+                        return
                 for v in node.values():
                     walk(v)
 
     if isinstance(d, dict):
-        walk(d.get("sons") or d.get("modules") or d.get("tree") or d)
+        # tree 优先：真机 tree=带 children 的完整嵌套树，sons 只有顶层扁平表
+        # （走 sons 会漏子模块）
+        walk(d.get("tree") or d.get("sons") or d.get("modules") or d)
     elif isinstance(d, list):
         walk(d)
     return out
@@ -724,8 +746,27 @@ def _old_route(api, method, p, q, body):
 
     m = re.match(r"^/products/(\d+)/modules$", p)
     if m and method == "GET":
-        d = go(get("/tree-browse-%s-module.json" % m.group(1)), "（拉模块清单）")
-        return {"_list": [x for x in _module_items(d) if isinstance(x, dict) and x.get("id")]}
+        # 2026-09-22 真机实探：该版模块行 type=story，viewType=module 查出空树
+        # （status 仍 success）——「响应形状不认识」的真根因。改按 bug 视图拉
+        # （bug 表单模块下拉用的就是这棵树），story/case 兜底。
+        pid = m.group(1)
+        last, saw_js = None, False
+        for vt in ("bug", "story", "case"):
+            d = go(get("/tree-browse-%s-%s.json" % (pid, vt)), "（拉模块清单）")
+            last = d
+            if isinstance(d, dict) and d.get("_js"):
+                saw_js = True            # 接口回了页面脚本：换视图再试
+                continue
+            items = [x for x in _module_items(d) if isinstance(x, dict) and x.get("id")]
+            if items:
+                return {"_list": items}
+        if saw_js:
+            raise ZenError("禅道老接口（拉模块清单）：回了页面脚本而不是数据"
+                           "（模块树接口不在或被重定向）——请在禅道产品视图 URL 里查模块 ID 手工填写")
+        keys = ",".join(sorted(str(k) for k in last.keys())) \
+            if isinstance(last, dict) else type(last).__name__
+        raise ZenError("该产品模块树为空（bug/story/case 三个视图都没拉到模块，"
+                       "响应顶层键：%s）——请到禅道确认产品下建过模块，或手工填模块 ID" % keys)
 
     if p == "/products" and method == "GET":
         d = go(get("/api-getmodel-product-getpairs.json"), "（拉产品清单）")
@@ -847,8 +888,12 @@ def fetch_modules(product_id):
     try:
         d = _call("GET", "/products/%s/modules" % product_id, cfg=cfg)
     except ZenError as e:
-        return {"ok": False,
-                "error": "%s——也可能你的禅道没有该接口：请在禅道产品视图 URL 里查模块 ID 手工填写" % e}
+        msg = str(e)
+        # 只有「接口不存在」类错误才补「没有该接口」提示；老通道自己报的
+        # 空树/脚本回包已带人话结论，别再叠一层误导
+        if "404" in msg or "不认识" in msg:
+            msg += "——也可能你的禅道没有该接口：请在禅道产品视图 URL 里查模块 ID 手工填写"
+        return {"ok": False, "error": msg}
     # 形状兼容器（{_list} / {modules:[...]} / {id:{...}} 字典 / 裸数组）
     items = _list_items(d, "modules")
     if items is None:
@@ -858,6 +903,11 @@ def fetch_modules(product_id):
         if isinstance(m, dict) and m.get("id"):
             out.append({"id": m.get("id"), "name": str(m.get("name") or "")})
     if not out:
+        if isinstance(d, dict) and set(d.keys()) == {"_list"}:
+            # 自家归一包装（裸数组进 _api/_old_route 时打的包）：空清单=
+            # 产品真没模块，不是形状问题，别拿顶层键吓人
+            return {"ok": False,
+                    "error": "禅道回了空模块清单（该产品可能没建模块）——请手工填模块 ID"}
         # 带响应形状摘要帮排查（顶层键名，不吐正文——用户实测反馈
         # 「响应形状不认识」却看不到真实形状，没法报修）
         keys = ",".join(sorted(str(k) for k in d.keys())) if isinstance(d, dict) else type(d).__name__
@@ -1627,7 +1677,7 @@ def _poll(force=False):
         err = "扫描失败：%s" % e
         log.warning("zentao: %s", err)
     now = datetime.now()
-    delay = timedelta(hours=max(INTERVAL_MIN, int(cfg.get("interval_hours") or 2)))
+    delay = timedelta(minutes=max(INTERVAL_MIN, int(cfg.get("interval_minutes") or INTERVAL_DEFAULT)))
     if err:
         delay = timedelta(minutes=RETRY_DELAY_MIN)
     with _LOCK:
@@ -1770,11 +1820,11 @@ def save_config(patch):
                 v = _norm_profiles(v)
                 if v is None:
                     continue
-            elif k == "interval_hours":
+            elif k == "interval_minutes":
                 try:
                     v = max(INTERVAL_MIN, min(INTERVAL_MAX, int(v)))
                 except (TypeError, ValueError):
-                    raise ValueError("interval_hours 必须是 %d-%d 的整数"
+                    raise ValueError("interval_minutes 必须是 %d-%d 的整数"
                                      % (INTERVAL_MIN, INTERVAL_MAX))
             elif k in ("auto_resolve", "auto_merge", "triage_ai", "poll_enabled"):
                 v = bool(v)

package/app/main.py

@@ -20,7 +20,17 @@ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from pathlib import Path
 from urllib.parse import parse_qs, unquote, urlparse
 
-from core import automation, catalog, flows, jobs, manager, market, market_remote, registry, remote, settings, store
+# 测试主目录隔离（TUTTI_ISOLATE_HOME=1）：必须先于 core.* 导入生效——
+# modelhub/manager 在 import 期就绑定 ~ 路径。launch/运行前防线会直写
+# ~/.claude 等真实 CLI 配置（2026-09-22 a.test 毒配置案），测试服务一律带上
+# 本开关，绝不落真实用户目录。
+if os.environ.get("TUTTI_ISOLATE_HOME", "").strip() == "1":
+    import tempfile as _tempfile
+    _fake_home = _tempfile.mkdtemp(prefix="tutti-home-")
+    os.environ["USERPROFILE"] = _fake_home
+    os.environ["HOME"] = _fake_home
+
+from core import automation, catalog, flows, jobs, manager, market, market_remote, preview, registry, remote, settings, store
 from core import paths
 from core import health
 import pick_dialog
@@ -196,6 +206,10 @@ class Handler(BaseHTTPRequestHandler):
         # 静态页不设防（无敏感信息）：远程裸地址打开时由前端令牌门引导输入
         if path in ("/", "/index.html"):
             return self._static("index.html")
+        # 运行预览：工作目录里网页成品的只读挂载，供 iframe/新窗口直接打开。
+        # 令牌走路径段（子资源继承不了查询串），鉴权复用 remote.request_authed。
+        if path == preview.BASE or path.startswith(preview.BASE + "/"):
+            return self._api_preview(path)
         if path.startswith("/api/"):
             if not self._authed():
                 return self._json(401, {"error": "需要访问令牌（启动 CodeBee 时控制台会显示）"})
@@ -390,6 +404,10 @@ class Handler(BaseHTTPRequestHandler):
                     files = []
                 return self._json(200, {"workdir": wd, "files": files,
                                         "task_id": run.get("task_id") or ""})
+            m = re.match(r"^/api/runs/([^/]+)/preview$", path)
+            if m:
+                # 网页成品预览：入口 HTML + 同目录代码文件（前端渲染「预览」页签）
+                return self._json(200, preview.list_app(m.group(1), remote.token()))
             m = re.match(r"^/api/tasks/([^/]+)/side$", path)
             if m:
                 # 任务检查器（右缘停靠列）专用：轻量聚合、可轮询，不带 diff 文本
@@ -1892,6 +1910,7 @@ class Handler(BaseHTTPRequestHandler):
             body = s.get("output") or ""
             if not body:
                 body = s.get("summary") or ""
+            running = (s.get("status") or "") == "running"
             items.append({
                 "kind": "agent",
                 "at": s.get("ended_at") or s.get("started_at") or "",
@@ -1904,6 +1923,13 @@ class Handler(BaseHTTPRequestHandler):
                 "run": run_id_of_step,
                 "log": s.get("log") or "",
                 "followups": s.get("followups") or [],
+                # 思考过程（2026-09-22 用户诉求）：内置智能体流式抓的思维链随步骤
+                # 落库，收尾保留；运行中另有 stream（正文实时预览）与 activity
+                # （工具活动行）——前端边跑边打印，不再只有三点打字动画。
+                "thinking": s.get("thinking") or "",
+                "stream": (s.get("stream") or "") if running else "",
+                "activity": (s.get("activity") or []) if running else [],
+                "live": s.get("live") or 0,
             })
 
         for r in runs:
@@ -2269,6 +2295,45 @@ class Handler(BaseHTTPRequestHandler):
         suffix = p.suffix.lower()
         self._send(200, p.read_bytes(), MIME.get(suffix, "application/octet-stream"))
 
+    # ------------------------------------------------------------ 运行预览
+    def _api_preview(self, path):
+        """GET /preview/<run_id>/<令牌>/<相对路径>：工作目录网页成品的只读挂载。
+
+        令牌放路径段而不是查询串：iframe 里的 style.css / script.js 是浏览器按
+        文档 URL 相对解析的，查询串不会被子资源继承（令牌会掉）。
+        """
+        rest = path[len(preview.BASE):].lstrip("/")
+        parts = rest.split("/")
+        if len(parts) < 2:
+            return self._json(404, {"error": "not found"})
+        run_id, tok = unquote(parts[0]), unquote(parts[1])
+        rel = unquote("/".join(parts[2:]))
+        # 令牌直接交给 remote.request_authed：与 /api/* 同一把尺子（本机豁免、
+        # 代理下带转发头的 loopback 算远程），不另写一套鉴权
+        ip, fw = self._forwarded_ip()
+        if not remote.request_authed(ip, fw, tok, self.headers.get("X-CodeBee-Token") or ""):
+            return self._json(401, {"error": "需要访问令牌（启动 CodeBee 时控制台会显示）"})
+        if not rel or rel.endswith("/"):
+            # 目录地址（/<令牌>/ 或 /<令牌>/web/）：回落到该目录的入口页
+            app = preview.list_app(run_id, tok)
+            if not app.get("ok"):
+                return self._json(404, {"error": "没有可预览的页面"})
+            rel = app["entry"]
+            if not self._preview_dir_ok(path, rel):
+                return self._json(404, {"error": "not found"})
+        data, ctype, err = preview.serve(run_id, rel, tok)
+        if err:
+            return self._json(404, {"error": err})
+        return self._send(200, data, ctype)
+
+    def _preview_dir_ok(self, path, entry):
+        """目录请求只允许回落到该目录自己的入口（/x/ 只解析 x/index.html），
+        免得 /sub/ 悄悄把根入口当子目录入口发出去。"""
+        want = urlparse(path).path[len(preview.BASE):].strip("/").split("/")[2:]
+        want = "/".join(unquote(p) for p in want if p)
+        edir = entry.rsplit("/", 1)[0] if "/" in entry else ""
+        return want == edir
+
 
 def _state_payload(client_id="", ver=None):
     agents = registry.effective_agents(catalog.load(), manager.detect_all())