Update app.py

app.py

@@ -7,13 +7,9 @@ import termios
 import asyncio
 import json
 import base64
-import glob
 import logging
 import shutil
 import subprocess
-import tarfile
-import zipfile
-from pathlib import Path
 
 import spaces
 import httpx
@@ -38,8 +34,6 @@ LLAMA_SERVER_BIN = os.path.join(LLAMA_BIN_DIR, "llama-server")
 LLAMA_RELEASE_TAG = "b10536"
 LLAMA_CPP_URL = f"https://github.com/ggml-org/llama.cpp/releases/download/{LLAMA_RELEASE_TAG}/llama-{LLAMA_RELEASE_TAG}-bin-ubuntu-x64.tar.gz"
 
-# 改用「無 MTP」版本的權重 —— MTP 分支在部分環境下不穩定，改走一般解碼路徑，
-# 靠其他手段（flash-attn、連續批次、量化 KV cache、GPU 全卸載等）把 token 速度衝高。
 MODEL_DIR = os.path.join(HOME, "models")
 MODEL_PATH = os.path.join(MODEL_DIR, "Qwen3.6-35B-A3B-UD-Q4_K_M.gguf")
 MODEL_URL = "https://huggingface.co/unsloth/Qwen3.6-35B-A3B-GGUF/resolve/main/Qwen3.6-35B-A3B-UD-Q4_K_M.gguf"
@@ -49,13 +43,10 @@ MMPROJ_URL = "https://huggingface.co/unsloth/Qwen3.6-35B-A3B-GGUF/resolve/main/m
 LLAMA_PORT = 8081
 LLAMA_LOG = os.path.join(HOME, "llama-server.log")
 
-# pi coding agent（earendil-works/pi）：終端機 AI 編碼助手，設定後透過本機 llama.cpp
-# 的 OpenAI 相容 API 運作，完全離線、免金鑰。
 PI_MODELS_JSON = os.path.join(HOME, ".pi", "agent", "models.json")
 PI_PROVIDER_ID = "llama-cpp-local"
 PI_MODEL_ID = "qwen3.6-35b-a3b"
 
-llama_process: "asyncio.subprocess.Process | None" = None
 llama_ready = asyncio.Event()
 llm_status = {"stage": "not_started", "detail": ""}
 
@@ -122,7 +113,6 @@ function wsUrl() {
   return `${p}//${location.host}/ws`;
 }
 
-// 每個 tab 自行連線；連線意外中斷時會自動重連，不會拖累其他分頁
 function connect(tabObj) {
   const ws = new WebSocket(wsUrl());
   tabObj.ws = ws;
@@ -227,7 +217,7 @@ function closeTab(id) {
   const i = tabs.findIndex(t => t.id === id);
   if (i < 0) return;
   const t = tabs[i];
-  t.closed = true;               // 避免關閉後觸發自動重連
+  t.closed = true;
   if (t.ws) t.ws.close();
   t.term.dispose();
   t.el.remove();
@@ -291,8 +281,6 @@ fileInput.onchange = (e) => {
   fileInput.value = '';
 };
 
-// 📥 下載：改走原生 HTTP 串流下載（不再塞進 WebSocket + base64），
-// 大檔案（例如模型檔）也不會卡住整個伺服器或造成無法重新連線。
 downloadBtn.onclick = () => {
   const t = activeTab();
   if (!t) return;
@@ -362,12 +350,9 @@ async def download_route(path: str):
         return JSONResponse({"error": "path not allowed"}, status_code=403)
     if not os.path.isfile(safe):
         return JSONResponse({"error": "file not found"}, status_code=404)
-    # FileResponse 會以串流方式送出，不會把整個檔案讀進記憶體或卡住 event loop，
-    # 即使是幾十 GB 的模型檔也可以正常下載。
     return FileResponse(safe, filename=os.path.basename(safe))
 
 
-# ── 代理 llama-server 的 OpenAI-相容 API，讓外部只需打這個 Space 的網址即可 ──
 @app.api_route("/v1/{path:path}", methods=["GET", "POST", "OPTIONS"])
 async def llm_proxy(path: str, request: Request):
     if not llama_ready.is_set():
@@ -385,15 +370,13 @@ async def llm_proxy(path: str, request: Request):
                 async for chunk in resp.aiter_bytes():
                     yield chunk
 
-    # 先用一次非串流探測狀態碼/標頭比較麻煩，這裡直接假設 200，串流轉發內容即可涵蓋
-    # /v1/chat/completions?stream=true 的 SSE 情境。
     return StreamingResponse(relay(), media_type="text/event-stream")
 
 
 # ──────────────────────────── 背景安裝流程 ────────────────────────────
 
 async def _run(cmd, cwd=None, env=None):
-    """非阻塞地執行一個 shell 指令，回傳 (returncode, stdout, stderr)。"""
+    """非阻塞地执行一个 shell 指令，回传 (returncode, stdout, stderr)。"""
     proc = await asyncio.create_subprocess_shell(
         cmd, cwd=cwd, env=env,
         stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE,
@@ -403,52 +386,53 @@ async def _run(cmd, cwd=None, env=None):
 
 
 async def install_opencode():
-    log.info("正在背景安裝 opencode...")
+    log.info("正在背景安装 opencode...")
     rc, out, err = await _run("curl -fsSL https://opencode.ai/install | bash")
     if rc == 0:
-        log.info("✅ opencode 安裝成功")
+        log.info("✅ opencode 安装成功")
     else:
-        log.warning("⚠️ opencode 安裝失敗或已存在: %s", err[-500:])
+        log.warning("⚠️ opencode 安装失败或已存在: %s", err[-500:])
 
 
 async def install_editors():
-    """安裝 vim / neovim（操作手感與 vim 一致），apt 不可用時記錄清楚原因而非靜默失敗。"""
-    log.info("正在安裝 vim / neovim ...")
+    """安装 vim / neovim。"""
+    log.info("正在安装 vim / neovim ...")
     for prefix in ("", "sudo "):
         rc, out, err = await _run(f"{prefix}apt-get update -y && {prefix}apt-get install -y vim neovim")
         if rc == 0:
-            log.info("✅ vim / neovim 安裝成功 (prefix=%r)", prefix)
+            log.info("✅ vim / neovim 安装成功 (prefix=%r)", prefix)
             await _run("update-alternatives --set editor /usr/bin/vim.basic || true")
             with open(os.path.join(HOME, ".bashrc"), "a") as f:
                 f.write('\nexport EDITOR=vim\nalias vi="vim"\n')
             return
-    log.error("❌ vim / neovim 安裝失敗（apt 與 sudo apt 皆失敗），請檢查容器權限與套件來源")
-
-
-async def install_pi_agent():
-    """安裝 pi coding agent (earendil-works/pi) 並設定使用本機 llama.cpp 的 OpenAI API。"""
-    log.info("正在安裝 pi coding agent ...")
-    rc, out, err = await _run("npm install -g --ignore-scripts @earendil-works/pi-coding-agent")
-    if rc != 0:
-        log.warning("npm 安裝 pi 失敗，改用官方安裝腳本備援: %s", err[-300:])
-        rc, out, err = await _run("curl -fsSL https://pi.dev/install.sh | sh")
-    if rc != 0:
-        log.error("❌ pi coding agent 安裝失敗: %s", err[-500:])
-        return
+    log.error("❌ vim / neovim 安装失败（apt 与 sudo apt 皆失败），请检查容器权限与套件来源")
+
 
-    os.makedirs(os.path.dirname(PI_MODELS_JSON), exist_ok=True)
-    models_config = {
+def _has_gpu() -> bool:
+    return shutil.which("nvidia-smi") is not None and subprocess.run(
+        ["nvidia-smi"], capture_output=True
+    ).returncode == 0
+
+
+OPENCODE_WORKDIR = os.path.join(HOME, "opencode-llm-setup")
+OPENCODE_LOG = os.path.join(HOME, "opencode-llm-setup.log")
+LLAMA_PID_FILE = os.path.join(LLAMA_DIR, "llama-server.pid")
+# OPENCODE_MODEL = "opencode/grok-code"   # 已移除，改用预设模型
+
+
+def _build_install_task_prompt() -> str:
+    pi_models_config = {
         "providers": {
             PI_PROVIDER_ID: {
                 "baseUrl": f"http://127.0.0.1:{LLAMA_PORT}/v1",
                 "api": "openai-completions",
-                "apiKey": "not-needed",   # llama-server 預設不驗證金鑰，這裡只是佔位字串
+                "apiKey": "not-needed",
                 "models": [
                     {
                         "id": PI_MODEL_ID,
-                        "name": "Qwen3.6 35B A3B (本機 llama.cpp)",
+                        "name": "Qwen3.6 35B A3B (本机 llama.cpp)",
                         "reasoning": False,
-                        "input": ["text", "image"] if os.path.isfile(MMPROJ_PATH) else ["text"],
+                        "input": ["text", "image"],
                         "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
                         "contextWindow": 16384,
                         "maxTokens": 4096,
@@ -457,215 +441,116 @@ async def install_pi_agent():
             }
         }
     }
-    with open(PI_MODELS_JSON, "w") as f:
-        json.dump(models_config, f, ensure_ascii=False, indent=2)
+    pi_models_json_str = json.dumps(pi_models_config, ensure_ascii=False, indent=2)
 
-    with open(os.path.join(HOME, ".bashrc"), "a") as f:
-        f.write(f'\nalias pi-local="pi --provider {PI_PROVIDER_ID} --model {PI_MODEL_ID}"\n')
+    return f"""你是系统维运助手，请在这台 Linux 主机上完成以下目标。过程中遇到任何错误（如文件不存在、路径不同、缺函数库、权限不足等），请自行判断原因并尝试修正、改用替代方案或重试，直到成功为止。不要因为单次失败就放弃。
 
-    log.info("✅ pi coding agent 已設定完成，可用 `pi-local` 指令連上本機 llama.cpp OpenAI API")
+**目标清单：**
 
+1. **安装并启动 llama.cpp**：让 llama-server 在端口 {LLAMA_PORT} 上运行，并提供 OpenAI 兼容 API。
+   - 你可以从官方 release 下载，或从源码编译，或使用 apt/pip 等其他方式，只要能成功运行即可。
+   - 模型文件请从 {MODEL_URL} 下载（支持断点续传），保存到 {MODEL_PATH}。
+   - 如果下载失败，可以尝试其他镜像源或使用其他兼容模型。
+   - mmproj 文件 {MMPROJ_URL} 可选，如果下载失败不影响纯文本功能。
+   - 启动参数请根据本机硬件（CPU/内存/GPU）自行优化，确保服务稳定运行。
+   - 服务启动后，轮询 http://127.0.0.1:{LLAMA_PORT}/health 直到返回 200。
 
-def _find_binary(root: str, name: str) -> str | None:
-    for path in glob.glob(os.path.join(root, "**", name), recursive=True):
-        if os.access(path, os.X_OK) or path.endswith(name):
-            return path
-    return None
+2. **安装 pi coding agent**：执行 `curl -fsSL https://pi.dev/install.sh | sh` 安装。
 
+3. **配置 pi 使用本机 llama.cpp**：将以下配置写入 {PI_MODELS_JSON}（如果文件已存在，请合并而非覆盖）：
+   ```json
+   {pi_models_json_str}
+添加便捷别名：在 ~/.bashrc 中添加 alias pi-local="pi --provider {PI_PROVIDER_ID} --model {PI_MODEL_ID}"（如果尚未存在）。
 
-async def _extract_archive(archive_path: str, dest: str):
-    os.makedirs(dest, exist_ok=True)
-    if archive_path.endswith(".zip"):
-        with zipfile.ZipFile(archive_path) as z:
-            z.extractall(dest)
-    else:
-        with tarfile.open(archive_path) as t:
-            t.extractall(dest)
+约束条件：
 
+llama-server 必须以后台守护进程方式运行（使用 nohup、systemd 或 screen 等方式），不依附于当前 session。
 
-async def install_llama_cpp() -> bool:
-    global LLAMA_SERVER_BIN
-    if os.path.isfile(LLAMA_SERVER_BIN) and os.access(LLAMA_SERVER_BIN, os.X_OK):
-        return True
+服务进程的 PID 请写入 {LLAMA_PID_FILE}，方便后续管理。
 
-    os.makedirs(LLAMA_DIR, exist_ok=True)
-    archive = os.path.join(LLAMA_DIR, "llama-cpp-release.archive")
+日志输出到 {LLAMA_LOG} 以便调试。
 
-    llm_status.update(stage="downloading_llama_cpp", detail=LLAMA_CPP_URL)
-    log.info("下載 llama.cpp: %s", LLAMA_CPP_URL)
-    rc, out, err = await _run(f"curl -fL --retry 3 -o {archive} '{LLAMA_CPP_URL}'")
+完成标准：
 
-    if rc != 0 or not os.path.exists(archive) or os.path.getsize(archive) < 1024:
-        log.warning("指定版本下載失敗，改用 GitHub API 尋找可用的 ubuntu-x64 資產作為備援")
-        llm_status.update(stage="downloading_llama_cpp_fallback", detail="")
-        rc2, out2, err2 = await _run(
-            f"curl -fsSL https://api.github.com/repos/ggml-org/llama.cpp/releases/tags/{LLAMA_RELEASE_TAG}"
-        )
-        asset_url = None
-        if rc2 == 0:
-            try:
-                data = json.loads(out2)
-                for a in data.get("assets", []):
-                    n = a.get("name", "")
-                    if "ubuntu-x64" in n and ("cpu" in n.lower() or "vulkan" not in n.lower()) and (n.endswith(".tar.gz") or n.endswith(".zip")):
-                        asset_url = a.get("browser_download_url")
-                        break
-                if not asset_url:
-                    for a in data.get("assets", []):
-                        n = a.get("name", "")
-                        if "ubuntu-x64" in n and (n.endswith(".tar.gz") or n.endswith(".zip")):
-                            asset_url = a.get("browser_download_url")
-                            break
-            except Exception as e:
-                log.error("解析 GitHub release JSON 失敗: %s", e)
-        if not asset_url:
-            log.error("❌ 找不到可用的 llama.cpp ubuntu-x64 release，安裝終止")
-            llm_status.update(stage="failed", detail="no matching llama.cpp release asset")
-            return False
-        archive = os.path.join(LLAMA_DIR, os.path.basename(asset_url))
-        rc3, out3, err3 = await _run(f"curl -fL --retry 3 -o {archive} '{asset_url}'")
-        if rc3 != 0:
-            log.error("❌ 備援下載也失敗: %s", err3[-500:])
-            llm_status.update(stage="failed", detail="llama.cpp download failed")
-            return False
-
-    log.info("解壓縮 llama.cpp ...")
-    try:
-        await _extract_archive(archive, LLAMA_DIR)
-    except Exception as e:
-        log.error("❌ 解壓縮失敗: %s", e)
-        llm_status.update(stage="failed", detail=f"extract failed: {e}")
-        return False
+所有目标都已达成。
 
-    found = _find_binary(LLAMA_DIR, "llama-server")
-    if not found:
-        log.error("❌ 解壓後找不到 llama-server 執行檔")
-        llm_status.update(stage="failed", detail="llama-server binary not found after extract")
-        return False
+请用简短的条列式总结每项目标的最终状态（成功/失败及原因）。"""
 
-    LLAMA_SERVER_BIN = found
-    os.chmod(LLAMA_SERVER_BIN, 0o755)
-    # 讓同目錄下的 .so 也可被找到
-    libdir = os.path.dirname(LLAMA_SERVER_BIN)
-    env_file = os.path.join(HOME, ".bashrc")
-    with open(env_file, "a") as f:
-        f.write(f'\nexport LD_LIBRARY_PATH="{libdir}:$LD_LIBRARY_PATH"\n')
-    log.info("✅ llama.cpp 就緒: %s", LLAMA_SERVER_BIN)
-    return True
 
+async def run_opencode_install_task() -> bool:
+    """委派 opencode agent 自动完成 llama.cpp + pi 的安装与设定（使用预设模型与 --auto 模式）。"""
+    llm_status.update(stage="waiting_for_opencode", detail="")
+    opencode_bin_dir = os.path.expanduser("~/.opencode/bin")
+    env = {**os.environ, "PATH": f"{os.environ.get('PATH', '')}:{opencode_bin_dir}"}
 
-async def _download_with_resume(url: str, dest: str, label: str) -> bool:
-    if os.path.isfile(dest) and os.path.getsize(dest) > 1024 * 1024:
-        log.info("%s 已存在，略過下載", label)
-        return True
-    log.info("下載 %s（支援中斷續傳）: %s", label, url)
-    # -C - 支援中斷續傳；即使下載中途失敗，重啟後也能接續，不需重頭來過
-    rc, out, err = await _run(f"curl -fL --retry 5 --retry-delay 5 -C - -o {dest} '{url}'")
-    if rc != 0:
-        log.error("❌ %s 下載失敗: %s", label, err[-800:])
-        llm_status.update(stage="failed", detail=f"{label} download failed: {err[-300:]}")
+    # 等待 opencode 安装完成（最长 10 分钟）
+    for _ in range(120):
+        rc, _out, _err = await _run("command -v opencode", env=env)
+        if rc == 0:
+            break
+        await asyncio.sleep(5)
+    else:
+        log.error("❌ opencode 尚未安装完成，无法委派安装任务")
+        llm_status.update(stage="failed", detail="opencode not available")
         return False
-    log.info("✅ %s 下載完成", label)
-    return True
-
 
-async def download_model() -> bool:
-    os.makedirs(MODEL_DIR, exist_ok=True)
-    llm_status.update(stage="downloading_model", detail=MODEL_URL)
-    if not await _download_with_resume(MODEL_URL, MODEL_PATH, "主模型 (GGUF)"):
-        return False
-    llm_status.update(stage="downloading_mmproj", detail=MMPROJ_URL)
-    if not await _download_with_resume(MMPROJ_URL, MMPROJ_PATH, "mmproj (視覺投影層)"):
-        # mmproj 失敗不致命，純文字推論仍可運作，記錄警告即可繼續
-        log.warning("⚠️ mmproj 下載失敗，將以純文字模式啟動（不支援圖片輸入）")
-        llm_status.update(stage="downloading_model", detail="mmproj failed, continuing text-only")
-    return True
+    # 不再写入配置文件，依靠 --auto 实现自动权限
 
+    os.makedirs(OPENCODE_WORKDIR, exist_ok=True)
+    prompt = _build_install_task_prompt()
 
-def _has_gpu() -> bool:
-    return shutil.which("nvidia-smi") is not None and subprocess.run(
-        ["nvidia-smi"], capture_output=True
-    ).returncode == 0
+    log.info("委派 opencode 安装 llama.cpp / pi ，过程请见 %s", OPENCODE_LOG)
+    llm_status.update(stage="opencode_installing", detail=f"log: {OPENCODE_LOG}")
 
+    with open(OPENCODE_LOG, "ab", buffering=0) as logf:
+        proc = await asyncio.create_subprocess_exec(
+            "opencode", "run", "--auto", prompt,   # 使用预设模型，启用 --auto
+            cwd=OPENCODE_WORKDIR, env=env,
+            stdout=logf, stderr=subprocess.STDOUT,
+        )
+        await proc.wait()
 
-async def start_llama_server():
-    global llama_process
-    cpu_count = os.cpu_count() or 4
-    gpu = _has_gpu()
+    if proc.returncode != 0:
+        log.warning("opencode 安装任务结束，returncode=%s（不一定失败，详请见 %s）", proc.returncode, OPENCODE_LOG)
+    else:
+        log.info("✅ opencode 安装任务执行完毕，详请见 %s", OPENCODE_LOG)
+    return True
 
-    cmd = [
-        LLAMA_SERVER_BIN,
-        "--model", MODEL_PATH,
-        "--host", "127.0.0.1",
-        "--port", str(LLAMA_PORT),
-        "--mlock",                       # 要求鎖住模型於實體記憶體，避免被 swap 拖慢速度
-        "--ctx-size", "32767",
-        "--batch-size", "2048",          # 提高 prompt processing 吞吐量
-        "--ubatch-size", "512",
-        "--threads", str(cpu_count),
-        "--threads-batch", str(cpu_count),
-        "--jinja",                       # 使用內建 chat template
-        "--cache-type-k", "q8_0",        # 量化 KV cache：省記憶體、可撐更長 context 而不掉太多品質
-        "--cache-type-v", "q8_0",
-        "--parallel", "2",               # 已不用 MTP，開放併發 slot 拉高整體吞吐量
-        "--no-mmap",                     # 搭配 --mlock 使用，避免 mmap 造成的延遲抖動
-    ]
-    cmd += ["--n-gpu-layers", "99" if gpu else "0"]
-    if os.path.isfile(MMPROJ_PATH):
-        cmd += ["--mmproj", MMPROJ_PATH]
-        if gpu:
-            cmd += ["--mmproj-offload"]
-
-    log.info("啟動 llama-server (GPU=%s): %s", gpu, " ".join(cmd))
-    llm_status.update(stage="starting_server", detail="")
-
-    logf = open(LLAMA_LOG, "ab", buffering=0)
-    llama_process = await asyncio.create_subprocess_exec(
-        *cmd, stdout=logf, stderr=subprocess.STDOUT,
-        cwd=os.path.dirname(LLAMA_SERVER_BIN),
-    )
 
-    # 等待 server 就緒（輪詢 health endpoint），最多等 20 分鐘（大模型載入需要時間）
+async def wait_for_llama_ready(timeout_seconds: int = 3600):
+    """不管 llama-server 是被谁启动的，这里只负责轮询 /health 直到就绪或逾时。"""
+    llm_status.update(stage="waiting_for_llama_server", detail="")
+    gpu = _has_gpu()
     async with httpx.AsyncClient() as client:
-        for _ in range(400):
-            if llama_process.returncode is not None:
-                log.error("❌ llama-server 提前結束，returncode=%s，詳見 %s", llama_process.returncode, LLAMA_LOG)
-                llm_status.update(stage="failed", detail="llama-server exited early")
-                return
+        for _ in range(timeout_seconds // 5):
             try:
-                r = await client.get(f"http://127.0.0.1:{LLAMA_PORT}/health", timeout=2)
+                r = await client.get(f"http://127.0.0.1:{LLAMA_PORT}/health", timeout=3)
                 if r.status_code == 200:
-                    log.info("✅ llama-server 已就緒，OpenAI API: http://127.0.0.1:%s/v1", LLAMA_PORT)
+                    log.info("✅ llama-server 已就绪，OpenAI API: http://127.0.0.1:%s/v1", LLAMA_PORT)
                     llm_status.update(stage="ready", detail=f"gpu={gpu}")
                     llama_ready.set()
                     return
             except Exception:
                 pass
-            await asyncio.sleep(3)
-
-    log.error("❌ llama-server 逾時未就緒")
-    llm_status.update(stage="failed", detail="startup timeout")
+            await asyncio.sleep(5)
+    log.error("❌ 等待 llama-server 就绪逾时，请检查 %s 与 %s 的内容", OPENCODE_LOG, LLAMA_LOG)
+    llm_status.update(stage="failed", detail="llama-server did not become ready in time; check logs")
 
 
 async def setup_llm_pipeline():
     try:
-        # 確保代理需要的 httpx 已安裝（一般環境已具備，這裡是保險）
-        ok = await install_llama_cpp()
+        ok = await run_opencode_install_task()
         if not ok:
             return
-        ok = await download_model()
-        if not ok:
-            return
-        asyncio.create_task(install_pi_agent())  # 不需等待 server 啟動即可設定
-        await start_llama_server()
+        await wait_for_llama_ready()
     except Exception:
-        log.exception("LLM 安裝/啟動流程發生未預期錯誤")
+        log.exception("LLM 安装/启动流程发生未预期错误")
         llm_status.update(stage="failed", detail="unexpected exception, see server log")
 
 
 @spaces.GPU(duration=1, queue=False)
 def dummy_gpu():
-    """空函數，僅用於讓平台識別到 GPU 裝飾器，滿足 Hugging Face 要求"""
+    """空函数，仅用于让平台识别到 GPU 装饰器，满足 Hugging Face 要求"""
     return
 
 
@@ -679,23 +564,25 @@ async def startup_event():
 
 @app.on_event("shutdown")
 async def shutdown_event():
-    if llama_process and llama_process.returncode is None:
-        try:
-            llama_process.terminate()
-        except Exception:
-            pass
+    try:
+        if os.path.isfile(LLAMA_PID_FILE):
+            with open(LLAMA_PID_FILE) as f:
+                pid = int(f.read().strip())
+            os.kill(pid, signal.SIGTERM)
+    except Exception:
+        pass
 
 
 # ──────────────────────────── Terminal WebSocket ──────────────────────────────
 
 async def _reap_process(pid: int, loop: asyncio.AbstractEventLoop):
-    """非阻塞地終止並回收子行程，避免卡住整個 event loop（此為修正 bug1 的關鍵）。"""
+    """非阻塞地终止并回收子行程，避免卡住整个 event loop。"""
     for sig in (signal.SIGTERM, signal.SIGKILL):
         try:
             os.kill(pid, sig)
         except ProcessLookupError:
             return
-        for _ in range(20):  # 最多輪詢約 2 秒，期間不阻塞其他連線
+        for _ in range(20):
             await asyncio.sleep(0.1)
             try:
                 wpid, _status = os.waitpid(pid, os.WNOHANG)
@@ -703,7 +590,6 @@ async def _reap_process(pid: int, loop: asyncio.AbstractEventLoop):
                     return
             except ChildProcessError:
                 return
-    # 最後手段：拿到獨立執行緒去做阻塞式 waitpid，不會拖住主 event loop
     try:
         await loop.run_in_executor(None, os.waitpid, pid, 0)
     except Exception:
@@ -717,10 +603,9 @@ async def terminal_ws(websocket: WebSocket):
     try:
         pid, fd = pty.fork()
     except OSError as e:
-        # 例如 pty/行程數已達上限；明確告知使用者而不是讓連線悄悄失敗
         await websocket.send_text(json.dumps({
             "type": "system",
-            "data": f"\r\n\x1b[31m[❌ 無法建立新終端機 (pty.fork 失敗: {e})，請稍後再試或關閉其他分頁]\x1b[0m\r\n",
+            "data": f"\r\n\x1b[31m[❌ 无法建立新终端机 (pty.fork 失败: {e})，请稍后再试或关闭其他分页]\x1b[0m\r\n",
         }))
         await websocket.close()
         return
@@ -735,10 +620,9 @@ async def terminal_ws(websocket: WebSocket):
         if opencode_bin not in current_path:
             os.environ["PATH"] = f"{current_path}:{opencode_bin}"
 
-        # 智能目錄追蹤：每次顯示提示符時透過 OSC 0 序列回報目前目錄
         banner = (
-            'echo -e "\\033[36m歡迎使用 Web Terminal｜vim/nvim 已安裝｜'
-            f'本機 LLM OpenAI API: /v1 (llama.cpp, 就緒後可用)｜輸入 pi-local 啟動 pi coding agent\\033[0m";'
+            'echo -e "\\033[36m欢迎使用 Web Terminal｜vim/nvim 已安装｜'
+            f'本机 LLM OpenAI API: /v1 (llama.cpp, 就绪后可用)｜输入 pi-local 启动 pi coding agent\\033[0m";'
         )
         bash_cmd = (
             f"{banner} "
@@ -814,29 +698,27 @@ async def terminal_ws(websocket: WebSocket):
                         with open(path, "wb") as f:
                             f.write(data)
 
-                    # 搬到執行緒池執行，避免大檔案上傳時卡住整個 event loop
                     await asyncio.to_thread(_write)
                     await websocket.send_text(json.dumps({
                         "type": "system",
-                        "data": f"\r\n\x1b[32m[✅ 檔案已成功上傳至: {filepath}]\x1b[0m\r\n",
+                        "data": f"\r\n\x1b[32m[✅ 档案已成功上传至: {filepath}]\x1b[0m\r\n",
                     }))
                 except Exception as e:
                     await websocket.send_text(json.dumps({
                         "type": "system",
-                        "data": f"\r\n\x1b[31m[❌ 上傳失敗: {e}]\x1b[0m\r\n",
+                        "data": f"\r\n\x1b[31m[❌ 上传失败: {e}]\x1b[0m\r\n",
                     }))
 
     except (WebSocketDisconnect, RuntimeError):
         pass
     except Exception:
-        log.exception("terminal_ws 迴圈發生未預期錯誤")
+        log.exception("terminal_ws 循环发生未预期错误")
     finally:
         try:
             loop.remove_reader(fd)
         except Exception:
             pass
         sender.cancel()
-        # ✅ 非阻塞回收子行程：修正「關閉分頁後新分頁無法使用」的核心 bug
         await _reap_process(pid, loop)
         try:
             os.close(fd)