clash-controller 0.0.2__tar.gz → 0.2.0__tar.gz

clash_controller-0.2.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: clash_controller
+Version: 0.2.0
+Summary: A Textual TUI for managing Clash proxy instances
+Author-email: Moha-Master <hongkongreporter@outlook.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Moha-Master/Clash-Controller
+Project-URL: Repository, https://github.com/Moha-Master/Clash-Controller.git
+Project-URL: GitHub, https://github.com/Moha-Master/Clash-Controller
+Project-URL: Issues, https://github.com/Moha-Master/Clash-Controller/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests
+Requires-Dist: requests_unixsocket
+Requires-Dist: paramiko
+Requires-Dist: textual>=8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+
+# Clash Controller
+
+一个基于 [Textual](https://github.com/Textualize/textual) 构建的、功能丰富的 `clash` 文本用户界面（TUI）控制器，方便在终端中管理和监控一个或多个 `clash` 实例。
+
+## 功能特性
+
+- **现代 TUI 界面**：统一页面骨架（顶栏返回 / 折叠菜单 / 底部提示栏 + 状态栏），全键盘 + 全鼠标操作，单击数据行即执行，非阻塞异步加载与应用内日志。
+- **多端点管理**：
+    - 自动保存连接过的 Clash 端点（地址与密钥）。
+    - 启动时进入类似首页的居中大 LOGO 档案选择页，支持新增 / 编辑 / 删除。
+    - 支持 HTTP 与 Unix Domain Socket 连接。
+    - 远程端点支持 SSH 部署（密码 / 私钥文件 / 私钥文本三种认证）。
+- **实时监控面板**：
+    - **概览**：合并流式监控与连接管理，在一个页面同时显示上/下行流量、内存使用、内核版本，并带每秒自动刷新的当前活动连接表与累计流量。
+- **配置管理**：维护配置提供方列表，一键拉取远端配置、比对时间戳/哈希、部署到目标端点（本地或 SSH）并重载。
+- **设置菜单**：端点名称置于顶栏，TUN 与规则/全局/直连模式在面板内直接通过 Switch 和 Select 下拉列表即时生效切换（无需手动保存）、重载 GEO、重启 Clash、在线升级内核 / UI / GEO，以及查看运行日志。
+
+## 界面与快捷键
+
+| 场景 | 快捷键 | 作用 |
+|---|---|---|
+| **端点选择（根屏）** | `↑` / `↓` · `回车` 或 **单击** | 移动光标 · 连接所选端点 |
+| | `1-9` | 按数字直达连接第 N 个端点 |
+| | `Ctrl+N` / `Ctrl+E` / `Ctrl+D` | 新增 / 编辑 / 删除端点配置 |
+| | `Ctrl+R` | 刷新列表 |
+| | `Esc` / `Ctrl+C` | 退出程序 |
+| **主菜单** | `1` / `2` / `3` / `4` | 直达概览 / 配置管理 / 设置 / 切换端点 |
+| | `↑` / `↓` · `回车` | 移动光标 · 确认 |
+| | `Esc` / `Ctrl+C` | 退出程序（切换端点请按 `4`） |
+| **配置管理** | `↑` / `↓` · `回车` 或 **单击行** | 移动光标 · 部署所选提供方 |
+| | `Ctrl+N` / `Ctrl+E` / `Ctrl+D` | 新增 / 编辑 / 删除提供方 |
+| | `Ctrl+R` | 刷新 |
+| **功能页通用** | `Home` / `End` / `PgUp` / `PgDn` | 页面 / 表格滚动 |
+| | `Tab` / `Shift+Tab` | 表单字段轮切焦点 |
+| | `Esc` / `Ctrl+C` | 返回上一页 |
+| | `Ctrl+Q` | 任意界面直接退出程序 |
+| **弹窗** | `回车` | 提交（表单）/ 确认（危险操作需点按「确认」） |
+| | `Esc` / `Ctrl+C` / 「取消」 | 取消并关闭 |
+
+> 表单类弹窗统一为三段式：标题栏 / 字段区（单行紧凑输入，密码框留空 = 保持原值，开关为单行 Switch）/ 底部按钮栏 `[取消] [保存] [危险操作置右]`。
+> 焦点进入输入框即切换为**文本编辑模式**：使用控件原生编辑键（`Home`/`End`、`Ctrl+Shift+A` 全选、`Ctrl+X/C/V` 剪切 / 复制 / 粘贴，`TextArea` 另有 `Ctrl+Z/Y` 撤销 / 重做），底部提示栏同步切换，此时 `Ctrl+R` 刷新让位给输入框；`Ctrl+C` 有选中则复制、无选中则返回 / 取消。
+> 「查看应用日志」位于设置页右上角 `菜单 ▾` 折叠浮层中。
+
+## 安装
+
+```bash
+pip install clash-controller
+```
+
+安装后，可以通过以下命令启动程序：
+
+```bash
+clashctl
+```
+
+> 需要 Python 3.10 及以上版本。
+
+可选参数：
+
+```bash
+clashctl -D /path/to/config/dir   # 指定配置目录（默认 ~/.config/clash-controller）
+clashctl --debug                  # 启用 API / SSH 调试日志（显示在应用日志页）
+```
+
+## 开发者安装
+
+```bash
+git clone https://github.com/Moha-Master/clash-controller.git
+cd clash-controller
+
+python -m venv venv
+source venv/bin/activate  # 在 Windows 上使用 venv\Scripts\activate
+
+pip install -e ".[dev]"
+
+python -m clash_controller
+```
+
+## 要求
+
+- Python 3.10+
+- 运行中的 Clash 实例，已开启外部控制 API
+
+## 许可证
+
+MIT

clash_controller-0.2.0/README.md

@@ -0,0 +1,86 @@
+# Clash Controller
+
+一个基于 [Textual](https://github.com/Textualize/textual) 构建的、功能丰富的 `clash` 文本用户界面（TUI）控制器，方便在终端中管理和监控一个或多个 `clash` 实例。
+
+## 功能特性
+
+- **现代 TUI 界面**：统一页面骨架（顶栏返回 / 折叠菜单 / 底部提示栏 + 状态栏），全键盘 + 全鼠标操作，单击数据行即执行，非阻塞异步加载与应用内日志。
+- **多端点管理**：
+    - 自动保存连接过的 Clash 端点（地址与密钥）。
+    - 启动时进入类似首页的居中大 LOGO 档案选择页，支持新增 / 编辑 / 删除。
+    - 支持 HTTP 与 Unix Domain Socket 连接。
+    - 远程端点支持 SSH 部署（密码 / 私钥文件 / 私钥文本三种认证）。
+- **实时监控面板**：
+    - **概览**：合并流式监控与连接管理，在一个页面同时显示上/下行流量、内存使用、内核版本，并带每秒自动刷新的当前活动连接表与累计流量。
+- **配置管理**：维护配置提供方列表，一键拉取远端配置、比对时间戳/哈希、部署到目标端点（本地或 SSH）并重载。
+- **设置菜单**：端点名称置于顶栏，TUN 与规则/全局/直连模式在面板内直接通过 Switch 和 Select 下拉列表即时生效切换（无需手动保存）、重载 GEO、重启 Clash、在线升级内核 / UI / GEO，以及查看运行日志。
+
+## 界面与快捷键
+
+| 场景 | 快捷键 | 作用 |
+|---|---|---|
+| **端点选择（根屏）** | `↑` / `↓` · `回车` 或 **单击** | 移动光标 · 连接所选端点 |
+| | `1-9` | 按数字直达连接第 N 个端点 |
+| | `Ctrl+N` / `Ctrl+E` / `Ctrl+D` | 新增 / 编辑 / 删除端点配置 |
+| | `Ctrl+R` | 刷新列表 |
+| | `Esc` / `Ctrl+C` | 退出程序 |
+| **主菜单** | `1` / `2` / `3` / `4` | 直达概览 / 配置管理 / 设置 / 切换端点 |
+| | `↑` / `↓` · `回车` | 移动光标 · 确认 |
+| | `Esc` / `Ctrl+C` | 退出程序（切换端点请按 `4`） |
+| **配置管理** | `↑` / `↓` · `回车` 或 **单击行** | 移动光标 · 部署所选提供方 |
+| | `Ctrl+N` / `Ctrl+E` / `Ctrl+D` | 新增 / 编辑 / 删除提供方 |
+| | `Ctrl+R` | 刷新 |
+| **功能页通用** | `Home` / `End` / `PgUp` / `PgDn` | 页面 / 表格滚动 |
+| | `Tab` / `Shift+Tab` | 表单字段轮切焦点 |
+| | `Esc` / `Ctrl+C` | 返回上一页 |
+| | `Ctrl+Q` | 任意界面直接退出程序 |
+| **弹窗** | `回车` | 提交（表单）/ 确认（危险操作需点按「确认」） |
+| | `Esc` / `Ctrl+C` / 「取消」 | 取消并关闭 |
+
+> 表单类弹窗统一为三段式：标题栏 / 字段区（单行紧凑输入，密码框留空 = 保持原值，开关为单行 Switch）/ 底部按钮栏 `[取消] [保存] [危险操作置右]`。
+> 焦点进入输入框即切换为**文本编辑模式**：使用控件原生编辑键（`Home`/`End`、`Ctrl+Shift+A` 全选、`Ctrl+X/C/V` 剪切 / 复制 / 粘贴，`TextArea` 另有 `Ctrl+Z/Y` 撤销 / 重做），底部提示栏同步切换，此时 `Ctrl+R` 刷新让位给输入框；`Ctrl+C` 有选中则复制、无选中则返回 / 取消。
+> 「查看应用日志」位于设置页右上角 `菜单 ▾` 折叠浮层中。
+
+## 安装
+
+```bash
+pip install clash-controller
+```
+
+安装后，可以通过以下命令启动程序：
+
+```bash
+clashctl
+```
+
+> 需要 Python 3.10 及以上版本。
+
+可选参数：
+
+```bash
+clashctl -D /path/to/config/dir   # 指定配置目录（默认 ~/.config/clash-controller）
+clashctl --debug                  # 启用 API / SSH 调试日志（显示在应用日志页）
+```
+
+## 开发者安装
+
+```bash
+git clone https://github.com/Moha-Master/clash-controller.git
+cd clash-controller
+
+python -m venv venv
+source venv/bin/activate  # 在 Windows 上使用 venv\Scripts\activate
+
+pip install -e ".[dev]"
+
+python -m clash_controller
+```
+
+## 要求
+
+- Python 3.10+
+- 运行中的 Clash 实例，已开启外部控制 API
+
+## 许可证
+
+MIT

clash_controller-0.2.0/clash_controller/__init__.py

@@ -0,0 +1,5 @@
+"""
+Clash Controller - A Textual TUI for managing Clash proxy instances.
+"""
+
+__version__ = "0.2.0"

clash_controller-0.2.0/clash_controller/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running the CLI with `python -m clash_controller`."""
+
+from .main import main
+
+if __name__ == "__main__":
+    main()

{clash_controller-0.0.2 → clash_controller-0.2.0}/clash_controller/api.py

@@ -1,12 +1,19 @@
-import requests
 from urllib.parse import quote
 
+import requests
+
+
+def _noop(_message: str) -> None:
+    pass
+
+
 class ClashAPI:
     # Special sentinel returned when the request was sent but the connection
     # was interrupted (server closed connection / connection reset) and the
     # client cannot determine final outcome. Caller should prompt user to verify.
     SENT_BUT_DISCONNECTED = "SENT_BUT_DISCONNECTED"
-    def __init__(self, base_url, secret=None, timeout=10, working_directory=None, debug=False):
+
+    def __init__(self, base_url, secret=None, timeout=10, working_directory=None, debug=False, log=None):
         """
         Initializes the Clash API client.
 
@@ -15,20 +22,24 @@ class ClashAPI:
         :param secret: The secret for API authentication.
         :param timeout: Request timeout in seconds.
         :param working_directory: The working directory of the Clash core, used for config paths.
+        :param debug: When True, emit raw request/response info via ``log``.
+        :param log: Callable receiving debug strings (defaults to no-op; never prints).
         """
         self.base_url = base_url
         self.timeout = timeout
         self.headers = {}
         self.working_directory = working_directory
-        # When debug is True, the client will print raw request/response info
         self.debug = bool(debug)
+        # Debug output is routed to this callback (never stdout) so it cannot
+        # corrupt the TUI.
+        self._log = log or _noop
         if secret:
             self.headers['Authorization'] = f'Bearer {secret}'
 
         if self.base_url.startswith('unix://'):
             import requests_unixsocket
             self.session = requests_unixsocket.Session()
-            encoded_path = quote(self.base_url.lstrip('unix://'), safe='')
+            encoded_path = quote(self.base_url.removeprefix('unix://'), safe='')
             self.base_url = f'http+unix://{encoded_path}'
         else:
             self.session = requests.Session()
@@ -50,7 +61,7 @@ class ClashAPI:
         - Retries once on ReadTimeout with a longer timeout.
         - Treats PUT /configs ReadTimeout conservatively as success (server-side reload may have completed).
         - For streaming requests (stream=True) returns the raw response object so callers can iterate.
-        - When debug=True, prints basic request/response information to stdout.
+        - When debug=True, emits basic request/response information via the log callback.
         """
         url = f"{self.base_url}{endpoint}"
 
@@ -68,7 +79,7 @@ class ClashAPI:
         try:
             if self.debug:
                 try:
-                    print(f"[DEBUG] Request: {method} {url}\n  headers={self.headers}\n  params={params}\n  json={json_data}\n  stream={stream}\n  timeout={self.timeout}")
+                    self._log(f"[DEBUG] Request: {method} {url}\n  headers={self.headers}\n  params={params}\n  json={json_data}\n  stream={stream}\n  timeout={self.timeout}")
                 except Exception:
                     pass
 
@@ -77,7 +88,7 @@ class ClashAPI:
             # If caller requested streaming, return the raw response so the caller can iterate
             if stream:
                 if self.debug:
-                    print(f"[DEBUG] Response: status={response.status_code} headers={dict(response.headers)} (streaming)")
+                    self._log(f"[DEBUG] Response: status={response.status_code} headers={dict(response.headers)} (streaming)")
                 return response, None
 
             # For non-stream responses: always return the API-provided body (prefer JSON),
@@ -85,7 +96,7 @@ class ClashAPI:
             # encodes operation result details in the response body.
             if response.status_code == 204 or not response.content:
                 if self.debug:
-                    print(f"[DEBUG] Response: status={response.status_code} (no content)")
+                    self._log(f"[DEBUG] Response: status={response.status_code} (no content)")
                 return {"status": "success", "status_code": response.status_code}, None
 
             # Try JSON first, fall back to text
@@ -96,7 +107,7 @@ class ClashAPI:
 
             if self.debug:
                 raw = (response.text or '')[:4096]
-                print(f"[DEBUG] Response: status={response.status_code} headers={dict(response.headers)} body(<=4k)={raw}")
+                self._log(f"[DEBUG] Response: status={response.status_code} headers={dict(response.headers)} body(<=4k)={raw}")
 
             # If the parsed result is a dict, inject status_code for caller convenience
             if isinstance(parsed, dict):
@@ -109,30 +120,33 @@ class ClashAPI:
             # connection problems and the API is local, return the sentinel so
             # caller can ask user to verify the outcome manually.
             try:
-                longer_timeout = max(self.timeout * 3, 15)
+                longer_timeout = 15
                 if self.debug:
-                    print(f"[DEBUG] ReadTimeout occurred, retrying with timeout={longer_timeout}")
+                    self._log(f"[DEBUG] ReadTimeout occurred, retrying with timeout={longer_timeout}")
                 response = do_request(longer_timeout)
                 response.raise_for_status()
 
                 if stream:
                     if self.debug:
-                        print(f"[DEBUG] Response after retry: status={response.status_code} headers={dict(response.headers)} (streaming)")
+                        self._log(f"[DEBUG] Response after retry: status={response.status_code} headers={dict(response.headers)} (streaming)")
                     return response, None
 
                 if response.status_code == 204 or not response.content:
                     if self.debug:
-                        print(f"[DEBUG] Response after retry: status={response.status_code} (no content)")
+                        self._log(f"[DEBUG] Response after retry: status={response.status_code} (no content)")
                     return {"status": "success"}, None
 
                 if self.debug:
                     raw = response.text[:4096]
-                    print(f"[DEBUG] Response after retry: status={response.status_code} headers={dict(response.headers)} body(<=4k)={raw}")
+                    self._log(f"[DEBUG] Response after retry: status={response.status_code} headers={dict(response.headers)} body(<=4k)={raw}")
                 return response.json(), None
 
             except requests.exceptions.RequestException as exc:
                 if self.debug:
-                    print(f"[DEBUG] ReadTimeout retry failed: {exc}")
+                    self._log(f"[DEBUG] ReadTimeout retry failed: {exc}")
+                # Reload config may legitimately finish server-side while client times out.
+                if method.upper() == 'PUT' and endpoint.startswith('/configs'):
+                    return None, self.SENT_BUT_DISCONNECTED
                 # If this is a local API, we conservatively cannot determine the final
                 # state (server may have applied the operation then closed the connection),
                 # so inform the caller to verify manually.
@@ -144,7 +158,9 @@ class ClashAPI:
             # Connection errors/remote close — if local, return sentinel so caller
             # can prompt user to manually verify; otherwise return the error.
             if self.debug:
-                print(f"[DEBUG] Connection error: {e}")
+                self._log(f"[DEBUG] Connection error: {e}")
+            if method.upper() == 'PUT' and endpoint.startswith('/configs'):
+                return None, self.SENT_BUT_DISCONNECTED
             if self._is_local():
                 return None, self.SENT_BUT_DISCONNECTED
             return None, str(e)
@@ -165,9 +181,9 @@ class ClashAPI:
 
                 if self.debug:
                     try:
-                        print(f"[DEBUG] Error Response: status={resp.status_code} headers={dict(resp.headers)} body(<=4k)={(resp.text or '')[:4096]}")
+                        self._log(f"[DEBUG] Error Response: status={resp.status_code} headers={dict(resp.headers)} body(<=4k)={(resp.text or '')[:4096]}")
                     except Exception:
-                        print(f"[DEBUG] Error Response: status={getattr(resp, 'status_code', 'unknown')}")
+                        self._log(f"[DEBUG] Error Response: status={getattr(resp, 'status_code', 'unknown')}")
 
                 # Return the response body as the result, do not treat as exception
                 if isinstance(body, dict):
@@ -177,7 +193,7 @@ class ClashAPI:
 
             # No response available: transport-level error
             if self.debug:
-                print(f"[DEBUG] RequestException without response (transport error): {e}")
+                self._log(f"[DEBUG] RequestException without response (transport error): {e}")
             return None, str(e)
 
     # === Real-time Data ===
@@ -218,7 +234,7 @@ class ClashAPI:
     def reload_configs(self, path="", payload=""):
         """Reload configuration from path."""
         return self._request('PUT', '/configs', params={'force': 'true'}, json_data={"path": path, "payload": payload} or {})
-    
+
     def set_mode(self, mode: str):
         """Sets the connection mode ('rule', 'global', 'direct')."""
         return self.update_configs({"mode": mode.lower()})
@@ -252,7 +268,7 @@ class ClashAPI:
     def get_proxy(self, name: str):
         """Get a specific proxy or group's information."""
         return self._request('GET', f'/proxies/{quote(name)}')
-        
+
     def select_proxy_in_group(self, group_name: str, proxy_name: str):
         """Select a proxy for a specific group."""
         return self._request('PUT', f'/proxies/{quote(group_name)}', json_data={"name": proxy_name})
@@ -278,7 +294,7 @@ class ClashAPI:
         """Test the delay of all proxies in a group."""
         params = {'url': url, 'timeout': str(timeout)}
         return self._request('GET', f'/group/{quote(name)}/delay', params=params)
-    
+
     # === Providers ===
     def get_proxy_providers(self):
         """Get all proxy providers."""
@@ -295,7 +311,7 @@ class ClashAPI:
     def healthcheck_proxy_provider(self, name: str):
         """Trigger a health check for a proxy provider."""
         return self._request('GET', f'/providers/proxies/{quote(name)}/healthcheck')
-    
+
     def get_rule_providers(self):
         """Get all rule providers."""
         return self._request('GET', '/providers/rules')
@@ -325,4 +341,62 @@ class ClashAPI:
     # === DNS ===
     def query_dns(self, name: str, query_type: str = 'A'):
         """Query DNS."""
-        return self._request('GET', '/dns/query', params={'name': name, 'type': query_type}) 
+        return self._request('GET', '/dns/query', params={'name': name, 'type': query_type})
+
+
+def interpret_api_result(action_desc: str, result, error) -> tuple[str, str]:
+    """把 ClashAPI 的 ``(result, error)`` 解释为 ``(message, severity)``。
+
+    severity ∈ {"ok", "warn", "err"}；纯逻辑、无副作用，供界面层展示。
+    保留 ``SENT_BUT_DISCONNECTED`` 的「已发送但断连」语义。
+    """
+
+    def _clean(raw: str) -> str:
+        if not raw:
+            return ''
+        s = raw.strip()
+        for prefix in ('update error:', 'error:', 'message:', 'update:'):
+            if s.lower().startswith(prefix):
+                s = s[len(prefix):].strip()
+                break
+        if s:
+            s = s[0].upper() + s[1:]
+        return s
+
+    if error is None:
+        if isinstance(result, dict):
+            status_val = str(result.get('status', '')).lower()
+            status_code = result.get('status_code')
+            if 'message' in result:
+                short_msg = _clean(str(result['message']))
+            elif 'info' in result:
+                short_msg = _clean(str(result['info']))
+            elif isinstance(result.get('body'), str):
+                short_msg = _clean(result['body'])
+            else:
+                short_msg = ''
+
+            success = status_val in ('success', 'ok', 'done', 'true') or (
+                isinstance(status_code, int) and status_code in (200, 201, 202, 204)
+            )
+            if success:
+                return (f"已成功{action_desc}。" + (f" 提示：{short_msg}" if short_msg else ""), "ok")
+            if short_msg:
+                return (f"{action_desc}: {short_msg}", "warn")
+            return (f"{action_desc}已完成（请查看详情）。", "ok")
+
+        text = str(result) if result is not None else ''
+        return (f"{action_desc}: {text}" if text else f"已成功{action_desc}。", "ok")
+
+    if error == ClashAPI.SENT_BUT_DISCONNECTED:
+        return (
+            f"请求“{action_desc}”已发送，但在读取最终响应前连接中断；"
+            "该操作可能已生效，请手动检查 Clash 日志 / 状态确认。",
+            "warn",
+        )
+
+    if isinstance(result, dict) and result.get('info'):
+        return (f"{action_desc}完成：{str(result.get('info'))[:2000]}", "ok")
+
+    return (f"{action_desc}失败：{error}", "err")
+

clash_controller-0.2.0/clash_controller/app.py

@@ -0,0 +1,116 @@
+"""Textual 应用入口：全局档案 / 客户端、状态栏、日志与启动流程。"""
+from datetime import datetime
+from pathlib import Path
+
+from textual import work
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.widgets import Static
+
+from .api import ClashAPI
+
+
+class StatusBar(Static):
+    """底部状态栏：展示最近一次操作结果 / 进行中提示。"""
+
+
+class ClashControllerApp(App):
+    """Clash 管理 TUI。"""
+
+    CSS_PATH = Path(__file__).parent / "app.tcss"
+    TITLE = "Clash Controller"
+    ENABLE_COMMAND_PALETTE = False
+
+    BINDINGS = [
+        Binding("ctrl+q", "quit", "退出", priority=True),
+    ]
+
+    def __init__(self, debug: bool = False) -> None:
+        super().__init__()
+        self.debug_mode = bool(debug)
+        self.profile: dict | None = None
+        self._api: ClashAPI | None = None
+        self.app_logs: list[str] = []
+
+    # ------------------------------------------------------------ 日志
+
+    def add_log(self, message: str) -> None:
+        timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        self.app_logs.append(f"[{timestamp}] {message}")
+
+    # ------------------------------------------------------------ 档案 / 客户端
+
+    def set_profile(self, profile: dict) -> None:
+        self.profile = profile
+        self._api = None
+
+    def clear_profile(self) -> None:
+        self.profile = None
+        self._api = None
+
+    def get_api(self) -> ClashAPI:
+        if self.profile is None:
+            raise RuntimeError("尚未选择端点档案")
+        if self._api is None:
+            debug = self.debug_mode or bool(self.profile.get("debug_ssh"))
+            self._api = ClashAPI(
+                base_url=self.profile["url"],
+                secret=self.profile.get("secret"),
+                working_directory=self.profile.get("config_directory"),
+                debug=debug,
+                log=self.add_log,
+            )
+        return self._api
+
+    # ------------------------------------------------------------ 状态栏 / 提示
+
+    def compose(self) -> ComposeResult:
+        yield StatusBar("", id="status")
+
+    def status(self, message: str, kind: str = "") -> None:
+        try:
+            bar = self.query_one("#status", StatusBar)
+        except Exception:
+            return
+        bar.update_classes({"ok": kind == "ok", "warn": kind == "warn", "err": kind == "err"})
+        bar.update(message)
+
+    def notify_ok(self, message: str) -> None:
+        self.status(message, "ok")
+        self.notify(message, severity="success", timeout=4)
+
+    def notify_err(self, message: str) -> None:
+        self.status(message, "err")
+        self.notify(message, severity="error", timeout=8)
+
+    def notify_warn(self, message: str) -> None:
+        self.status(message, "warn")
+        self.notify(message, severity="warning", timeout=5)
+
+    def report(self, action_desc: str, result, error) -> str:
+        """统一解释 ClashAPI 结果并反馈到状态栏 / 通知 / 日志，返回严重级别。"""
+        from .api import interpret_api_result
+
+        message, severity = interpret_api_result(action_desc, result, error)
+        self.add_log(message)
+        if self.debug_mode:
+            self.add_log(f"[DEBUG] result={result!r} error={error!r}")
+        if severity == "ok":
+            self.notify_ok(message)
+        elif severity == "warn":
+            self.notify_warn(message)
+        else:
+            self.notify_err(message)
+        return severity
+
+    # ------------------------------------------------------------ 启动
+
+    def on_mount(self) -> None:
+        self.add_log("Application started.")
+        self._bootstrap()
+
+    @work(exclusive=True)
+    async def _bootstrap(self) -> None:
+        from .screens.profiles import ProfileListScreen
+
+        self.push_screen(ProfileListScreen())