sdev 0.7.2__tar.gz → 0.7.5__tar.gz

{sdev-0.7.2/sdev.egg-info → sdev-0.7.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sdev
-Version: 0.7.2
+Version: 0.7.5
 Summary: 串口控制器工具包
 Home-page: https://github.com/klrc/sdev
 Author: klrc
@@ -57,34 +57,41 @@ pip install sdev
 
 ## 命令行快速上手
 
-安装后会提供一个 `sdev` 命令，包括：
-
-- `sdev list`：扫描本地 / 远程可用串口；
-- `sdev run`：在选定设备上执行命令；
-- `sdev server`：启动/停止本机串口共享服务；
+安装后提供一个 `sdev` 命令，核心功能包括：
+
+- **`sdev list [scope] [filters...]`**：扫描本地 / 远程可用串口。
+  - `scope`: `local`, `remote` 或不填。
+  - `filters`: 如 `type=XC01` 或 `host=192.168.1.101`。
+  - `-f, --fast`: 快速模式，找到第一个符合条件的设备后立即输出（适合脚本）。
+- **`sdev run [cmd...]`**：执行命令。
+  - `-i, --interrupt-only`: 仅发送一次 Ctrl-C，随后被动收集输出（不发送新命令）。
+  - `-t, --timeout`: 整体超时限制。
+  - `-w, --wait-forever`: 永久等待输出，直至整体超时或手动中断。
+- **`sdev server [action]`**：管理本机串口共享服务。
+  - `action`: `start`, `stop`, `restart`, `status`。
+- **`sdev mcp [action]`**：AI 集成（Model Context Protocol）。
+  - `action`: `install` (一键配置到 IDE), `run` (由 IDE 调起的后台服务)。
 - `sdev set` / `sdev show` / `sdev reset`：管理默认设备与缓存。
 
 典型流程：
 
 ```bash
-# 1. （可选）在“串口所在机器”上启动 server
+# 1. 在“串口所在机器”上启动 server
 sdev server start
 
-# 2. 扫描可用设备
-sdev list
+# 2. 扫描并筛选可用设备
+sdev list remote              # 仅扫描远程
+sdev list type=XC01           # 仅列出特定型号
+sdev list -f type=XC01        # 快速模式：找到第一个 XC01 立即返回（适合脚本）
 
-# 3. （推荐）选中一块板，配置为默认设备
+# 3. 选中一块板，配置为默认设备
 sdev set default <DEVICE_ID>
 
-# 4. 之后即可直接执行命令
-sdev run 'cat /proc/meminfo'
-sdev run -t 10 'dmesg | tail'
+# 4. 执行命令
+sdev run 'cat /proc/meminfo'  # 执行完整交互
+sdev run -i                   # 仅发送 Ctrl-C (用于中断正在跑的任务并查看输出)
 ```
 
-更详细的 CLI 用法与行为说明，参考项目内的 skill 文档：
-
-- `docs/skills/serial-sdev-cli/SKILL.md`
-
 ---
 
 ## Python API 快速上手（SerialNotebook）
@@ -125,6 +132,25 @@ with SerialNotebook(device=SERIAL_PORT, baudrate=115200, host=HOST, port=7000) a
 
 ---
 
+## AI 集成 (MCP)
+
+`sdev` 支持 **Model Context Protocol (MCP)**，允许 AI 助手（如 Cursor、Claude Desktop）直接操作串口，执行命令并感知设备状态。
+
+### 1. 获取配置信息
+在本地环境执行：
+```bash
+sdev mcp install
+```
+该命令会自动生成可用于粘贴的 JSON 配置片段，并提示 Cursor 或 Claude Desktop 的配置路径。
+
+### 2. 提供的能力 (Tools)
+安装后，AI 助手将获得以下工具：
+- `sdev_list`: 获取本地及远程可用设备列表。
+- `sdev_run`: 在指定设备上执行命令并获取输出。
+- `sdev_set_default`: 设置当前会话的默认设备。
+
+---
+
 ## 适用 / 不适用的场景
 
 **适用：**
@@ -143,9 +169,6 @@ with SerialNotebook(device=SERIAL_PORT, baudrate=115200, host=HOST, port=7000) a
 ## 更多文档
 
 - **内部架构与设计说明**：`docs/arch_design.md`
-- **技能（在 Cursor 里集成使用方式）**：
-  - `docs/skills/serial-sdev-cli/SKILL.md`
-  - `docs/skills/serial-sdev-api/SKILL.md`
 
 源码结构概览（仅列出现行实现）：
 
@@ -153,5 +176,6 @@ with SerialNotebook(device=SERIAL_PORT, baudrate=115200, host=HOST, port=7000) a
   - `serial_rw.py`：本地串口读写与锁管理（`SerialRW`）、运行控制器（`SerialRunner`）、端口扫描与快速探测；
   - `serial_rw_server.py`：远程串口共享服务与客户端（`SerialRWServer` / `SerialRWClient`），以及主机发现逻辑；
   - `serial_notebook.py`：Notebook / 脚本场景下的最高层 Python 入口（`SerialNotebook`），基于 `SerialRW` / `SerialRWClient` 实现。
-- `sdev/cli/`：命令行入口 `sdev`（`__init__.py` 中的 `main()`），直接基于 `SerialRW` / `SerialRunner` 与 `SerialRWClient` 实现 `run / list / server` 等子命令。
+- `sdev/cli/`：命令行入口 `sdev`（`__init__.py` 中的 `main()`），以 `SerialNotebook` 作为上层统一入口，并通过 `SerialRWServer`/`SerialRWClient` 实现远程 `run / list / server` 等子命令。
+
 

{sdev-0.7.2 → sdev-0.7.5}/README.md

@@ -22,34 +22,41 @@ pip install sdev
 
 ## 命令行快速上手
 
-安装后会提供一个 `sdev` 命令，包括：
-
-- `sdev list`：扫描本地 / 远程可用串口；
-- `sdev run`：在选定设备上执行命令；
-- `sdev server`：启动/停止本机串口共享服务；
+安装后提供一个 `sdev` 命令，核心功能包括：
+
+- **`sdev list [scope] [filters...]`**：扫描本地 / 远程可用串口。
+  - `scope`: `local`, `remote` 或不填。
+  - `filters`: 如 `type=XC01` 或 `host=192.168.1.101`。
+  - `-f, --fast`: 快速模式，找到第一个符合条件的设备后立即输出（适合脚本）。
+- **`sdev run [cmd...]`**：执行命令。
+  - `-i, --interrupt-only`: 仅发送一次 Ctrl-C，随后被动收集输出（不发送新命令）。
+  - `-t, --timeout`: 整体超时限制。
+  - `-w, --wait-forever`: 永久等待输出，直至整体超时或手动中断。
+- **`sdev server [action]`**：管理本机串口共享服务。
+  - `action`: `start`, `stop`, `restart`, `status`。
+- **`sdev mcp [action]`**：AI 集成（Model Context Protocol）。
+  - `action`: `install` (一键配置到 IDE), `run` (由 IDE 调起的后台服务)。
 - `sdev set` / `sdev show` / `sdev reset`：管理默认设备与缓存。
 
 典型流程：
 
 ```bash
-# 1. （可选）在“串口所在机器”上启动 server
+# 1. 在“串口所在机器”上启动 server
 sdev server start
 
-# 2. 扫描可用设备
-sdev list
+# 2. 扫描并筛选可用设备
+sdev list remote              # 仅扫描远程
+sdev list type=XC01           # 仅列出特定型号
+sdev list -f type=XC01        # 快速模式：找到第一个 XC01 立即返回（适合脚本）
 
-# 3. （推荐）选中一块板，配置为默认设备
+# 3. 选中一块板，配置为默认设备
 sdev set default <DEVICE_ID>
 
-# 4. 之后即可直接执行命令
-sdev run 'cat /proc/meminfo'
-sdev run -t 10 'dmesg | tail'
+# 4. 执行命令
+sdev run 'cat /proc/meminfo'  # 执行完整交互
+sdev run -i                   # 仅发送 Ctrl-C (用于中断正在跑的任务并查看输出)
 ```
 
-更详细的 CLI 用法与行为说明，参考项目内的 skill 文档：
-
-- `docs/skills/serial-sdev-cli/SKILL.md`
-
 ---
 
 ## Python API 快速上手（SerialNotebook）
@@ -90,6 +97,25 @@ with SerialNotebook(device=SERIAL_PORT, baudrate=115200, host=HOST, port=7000) a
 
 ---
 
+## AI 集成 (MCP)
+
+`sdev` 支持 **Model Context Protocol (MCP)**，允许 AI 助手（如 Cursor、Claude Desktop）直接操作串口，执行命令并感知设备状态。
+
+### 1. 获取配置信息
+在本地环境执行：
+```bash
+sdev mcp install
+```
+该命令会自动生成可用于粘贴的 JSON 配置片段，并提示 Cursor 或 Claude Desktop 的配置路径。
+
+### 2. 提供的能力 (Tools)
+安装后，AI 助手将获得以下工具：
+- `sdev_list`: 获取本地及远程可用设备列表。
+- `sdev_run`: 在指定设备上执行命令并获取输出。
+- `sdev_set_default`: 设置当前会话的默认设备。
+
+---
+
 ## 适用 / 不适用的场景
 
 **适用：**
@@ -108,9 +134,6 @@ with SerialNotebook(device=SERIAL_PORT, baudrate=115200, host=HOST, port=7000) a
 ## 更多文档
 
 - **内部架构与设计说明**：`docs/arch_design.md`
-- **技能（在 Cursor 里集成使用方式）**：
-  - `docs/skills/serial-sdev-cli/SKILL.md`
-  - `docs/skills/serial-sdev-api/SKILL.md`
 
 源码结构概览（仅列出现行实现）：
 
@@ -118,5 +141,6 @@ with SerialNotebook(device=SERIAL_PORT, baudrate=115200, host=HOST, port=7000) a
   - `serial_rw.py`：本地串口读写与锁管理（`SerialRW`）、运行控制器（`SerialRunner`）、端口扫描与快速探测；
   - `serial_rw_server.py`：远程串口共享服务与客户端（`SerialRWServer` / `SerialRWClient`），以及主机发现逻辑；
   - `serial_notebook.py`：Notebook / 脚本场景下的最高层 Python 入口（`SerialNotebook`），基于 `SerialRW` / `SerialRWClient` 实现。
-- `sdev/cli/`：命令行入口 `sdev`（`__init__.py` 中的 `main()`），直接基于 `SerialRW` / `SerialRunner` 与 `SerialRWClient` 实现 `run / list / server` 等子命令。
+- `sdev/cli/`：命令行入口 `sdev`（`__init__.py` 中的 `main()`），以 `SerialNotebook` 作为上层统一入口，并通过 `SerialRWServer`/`SerialRWClient` 实现远程 `run / list / server` 等子命令。
+
 

{sdev-0.7.2 → sdev-0.7.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sdev"
-version = "0.7.2"
+version = "0.7.5"
 description = "串口控制器工具包"
 readme = "README.md"
 license = {text = "MIT"}

{sdev-0.7.2 → sdev-0.7.5}/sdev/cli/__init__.py

@@ -23,12 +23,11 @@ from datetime import datetime
 from typing import Any, Dict, List, Optional, Tuple
 
 from ..modules import (
-    SerialRW,
-    SerialRunner,
     check_port_alive_nonblock,
     scan_serial_ports,
     DEFAULT_SERVICE_PORT,
 )
+from ..modules.serial_notebook import SerialNotebook
 from ..modules.serial_rw_server import (
     SerialRWClient,
     fetch_boards_from_host,
@@ -141,9 +140,9 @@ def _read_default() -> Optional[Dict[str, Any]]:
         return None
 
 
-def _write_default(host: str, port: str, device_id: str) -> None:
+def _write_default(host: str, device: str, device_id: str) -> None:
     with open(_default_config_path(), "w", encoding="utf-8") as f:
-        json.dump({"host": host, "port": port, "device_id": device_id}, f, ensure_ascii=False)
+        json.dump({"host": host, "device": device, "device_id": device_id}, f, ensure_ascii=False)
 
 
 def _clear_default() -> None:
@@ -153,10 +152,10 @@ def _clear_default() -> None:
 
 
 def _resolve_device_to_host_port(device_id: str) -> Optional[Tuple[str, str]]:
-    """从 list 缓存中按 device_id 解析出 (host, port)；未找到返回 None。"""
+    """从 list 缓存中按 device_id 解析出 (host, device)；未找到返回 None。"""
     for e in _read_list_cache():
         if (e.get("device_id") or "").lower() == device_id.lower():
-            return (e.get("host", "localhost"), e.get("port", ""))
+            return (e.get("host", "localhost"), e.get("device", ""))
     return None
 
 
@@ -279,6 +278,14 @@ def _build_parser() -> argparse.ArgumentParser:
         help="status 时显示的最近日志行数，默认 10",
     )
 
+    # sdev mcp run | install
+    mcp_p = subparsers.add_parser("mcp", help="MCP (Model Context Protocol) 相关工具")
+    mcp_p.add_argument(
+        "action",
+        choices=["run", "install"],
+        help="run=启动 MCP 服务(stdio传输)；install=获取可粘贴的配置信息",
+    )
+
     return parser
 
 
@@ -299,52 +306,60 @@ def _handle_run(args: argparse.Namespace) -> int:
         if not default_cfg:
             raise SystemExit("sdev run: 未指定 --port 且未配置默认设备，请先执行 sdev set default <device_id> 或 sdev set <host> <serial_device>")
         host = (default_cfg.get("host") or "").strip() or "localhost"
-        port = (default_cfg.get("port") or "").strip()
-        if not port:
-            raise SystemExit("sdev run: 默认配置缺少 port")
+        device = (default_cfg.get("device") or default_cfg.get("port") or "").strip()
+        if not device:
+            raise SystemExit("sdev run: 默认配置缺少 device")
     else:
         host = "localhost"
+        device = port
 
-    if (host or "").lower() == "localhost":
-        core: Any = SerialRW(port, args.baud)
+    overall_timeout: Optional[float] = args.timeout
+    # 若未显式指定整体超时，CLI 默认给一个有限的响应超时，避免在无输出设备上永久挂起。
+    if args.wait_forever:
+        response_timeout: Optional[float] = None
     else:
-        # 远程场景直接使用新的 SerialRWClient 内核
-        core = SerialRWClient(host, DEFAULT_SERVICE_PORT, port, args.baud)
-    runner = SerialRunner(core)
+        response_timeout = overall_timeout if overall_timeout is not None else 2.0
 
-    overall_timeout: Optional[float] = args.timeout
-    response_timeout: Optional[float] = None if args.wait_forever else overall_timeout
+    # CLI 统一通过 SerialNotebook 作为上层入口：
+    # - 本地：直接使用本机串口；
+    # - 远程：通过 SerialRWClient 由 SerialNotebook 内部接管。
+    if (host or "").lower() == "localhost":
+        nb = SerialNotebook(device=device, baudrate=args.baud)
+    else:
+        nb = SerialNotebook(device=device, baudrate=args.baud, host=host, port=DEFAULT_SERVICE_PORT)
 
-    with core:
-        # CLI 下每条命令（或一次 interrupt-only）前空一行，便于与上一次输出隔离；脚本/API 不经过此处，无多余空行。
-        print()
+    with nb:
         try:
             if interrupt_only:
-                # 仅发送一次中断信号，然后调用 run(cmd=None, ...) 等待提示符与后续输出。
-                runner.send_interrupt()
-                runner.run(
-                    None,
-                    prompt_flag=args.prompt_flag,
-                    overall_timeout=overall_timeout,
-                    response_timeout=response_timeout,
-                    wait_forever=args.wait_forever,
-                    stream=False,
-                    display=True,
-                )
+                # 仅发送一次中断信号，然后在较短窗口内被动收集输出。
+                nb.send_interrupt()
+                lines = nb.wait_for_silence(timeout=response_timeout or 1.0)
+                # 为保持行为简单，这里仅以灰色输出剩余行，不再额外做提示符高亮。
+                GREY = "\033[90m"
+                RESET = "\033[0m"
+                for line in lines:
+                    text = getattr(line, "text", str(line))
+                    sys.stdout.write(f"{GREY}{text}{RESET}")
+                sys.stdout.flush()
             else:
                 # 正常执行命令。
-                runner.run(
-                    cmd_str,
-                    prompt_flag=args.prompt_flag,
+                ret = nb.run(
+                    cmd=cmd_str,
+                    end_flag=args.prompt_flag,
                     overall_timeout=overall_timeout,
                     response_timeout=response_timeout,
-                    wait_forever=args.wait_forever,
                     stream=False,
-                    display=True,
+                    verbose=False,
+                    keep_type=True,
                 )
+                for line in ret:
+                    if line.kind == 'body' or line.kind == 'error':
+                        sys.stdout.write(line.text)
+                        sys.stdout.flush()
+            print()
         except KeyboardInterrupt:
             # 捕获本地 Ctrl-C：向开发板发送一次中断信号（Ctrl-C），尽量中断远端前台命令。
-            runner.send_interrupt()
+            nb.send_interrupt()
             # 提示用户本次为主动中断（黄色）。
             YELLOW = "\033[33m"
             RESET = "\033[0m"
@@ -425,13 +440,8 @@ def _handle_list(args: argparse.Namespace) -> int:
 
         def _model_one(port: str) -> Tuple[str, str]:
             try:
-                core = SerialRW(port, 115200)
-                runner = SerialRunner(core)
-                core.connect()
-                try:
-                    return (port, runner.check_model_type(timeout=2.0) or "unknown")
-                finally:
-                    core.disconnect()
+                with SerialNotebook(device=port, baudrate=115200) as nb:
+                    return (port, nb.get_model_type(timeout=2.0, verbose=False) or "unknown")
             except Exception as e:
                 return (port, f"error: {e}")
 
@@ -445,7 +455,7 @@ def _handle_list(args: argparse.Namespace) -> int:
             for port, device_type in model_results:
                 entries.append({
                     "host": "localhost",
-                    "port": port,
+                    "device": port,
                     "device_id": _device_id("localhost", port),
                     "device_type": device_type if not device_type.startswith("error:") else "unknown",
                     "last_update": now,
@@ -455,32 +465,32 @@ def _handle_list(args: argparse.Namespace) -> int:
     def _scan_remote_task() -> List[Dict[str, Any]]:
         entries: List[Dict[str, Any]] = []
         hosts = get_remote_hosts()
+        # print(f"[debug] remote hosts found by discovery: {hosts}")
         if not hosts:
             return entries
         for host, service_port in hosts:
+            # print(f"[debug] fetching boards from {host}:{service_port}...")
             boards = fetch_boards_from_host(host, service_port, timeout=10.0)
+            # print(f"[debug] host {host} returned {len(boards)} boards")
             for b in boards:
                 if not b.get("available"):
                     continue
-                serial_port = (b.get("port") or "").strip()
-                if not serial_port:
+                serial_dev = (b.get("device") or b.get("port") or "").strip()
+                if not serial_dev:
                     continue
                 baud = int(b.get("baudrate") or 115200)
                 device_type = "unknown"
                 try:
-                    core = SerialRWClient(host, service_port, serial_port, baud)
-                    runner = SerialRunner(core)
-                    core.connect()
-                    try:
-                        device_type = runner.check_model_type(timeout=2.0) or "unknown"
-                    finally:
-                        core.disconnect()
-                except Exception:
+                    with SerialNotebook(device=serial_dev, baudrate=baud, host=host, port=service_port) as nb:
+                        device_type = nb.get_model_type(timeout=3.0, verbose=False) or "unknown"
+                except Exception as e:
+                    # 如果报错，说明连接或者握手阶段就出问题了
+                    # print(f"[debug] failed to get model type from {host}:{serial_dev}: {e}")
                     device_type = "unknown"
                 entries.append({
                     "host": host,
-                    "port": serial_port,
-                    "device_id": _device_id(host, serial_port),
+                    "device": serial_dev,
+                    "device_id": _device_id(host, serial_dev),
                     "device_type": device_type if not device_type.startswith("error:") else "unknown",
                     "last_update": now,
                 })
@@ -532,6 +542,9 @@ def _handle_list(args: argparse.Namespace) -> int:
         entries = [e for e in entries if (e.get("device_type") or "").lower() == filters["type"].lower()]
     if "host" in filters:
         entries = [e for e in entries if (e.get("host") or "").lower() == filters["host"].lower()]
+
+    # 默认展示所有探测到的设备，即便型号识别为 unknown。
+    # entries = [e for e in entries if (e.get("device_type") or "").lower() != "unknown"]
     if fast and len(entries) > 1:
         entries = entries[:1]
 
@@ -548,7 +561,7 @@ def _handle_list(args: argparse.Namespace) -> int:
     for e in entries:
         print(
             f"{e.get('host', ''):<{col_host}} "
-            f"{e.get('port', ''):<{col_port}} "
+            f"{e.get('device', ''):<{col_port}} "
             f"{e.get('device_id', ''):<{col_id}} "
             f"{e.get('device_type', 'unknown'):<{col_type}} "
             f"{e.get('last_update', ''):<{col_time}}"
@@ -726,7 +739,7 @@ def _handle_reset(args: argparse.Namespace) -> int:
         if _server_is_running() is not None:
             _handle_server_stop()
         _clear_default()
-        list_path = os.path.join(_sdev_cache_dir(), "list_cache.json")
+        list_path = _list_cache_path()
         if os.path.isfile(list_path):
             os.remove(list_path)
             print(f"[{_ts()}] list cache cleared")
@@ -734,6 +747,63 @@ def _handle_reset(args: argparse.Namespace) -> int:
     return 0
 
 
+def _handle_mcp(args: argparse.Namespace) -> int:
+    action = getattr(args, "action", None)
+    if action == "run":
+        # 启动 MCP 服务
+        from ..modules.mcp_server import mcp
+        mcp.run()
+        return 0
+    if action == "install":
+        return _mcp_show_config()
+    return 1
+
+
+def _mcp_show_config() -> int:
+    import platform
+    import json
+    
+    # 确定 Python 路径
+    py_path = sys.executable
+    # 确定项目根目录（用于 PYTHONPATH）
+    project_root = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    
+    # 封装配置对象
+    sdev_config = {
+        "command": py_path,
+        "args": ["-m", "sdev.modules.mcp_server"],
+        "env": {
+            "PYTHONPATH": project_root
+        }
+    }
+    
+    system = platform.system()
+    home = os.path.expanduser("~")
+    
+    print(f"\n[{_ts()}] === SDEV MCP 配置指南 ===")
+    
+    # 1. 针对 Cursor
+    print(f"\n[Cursor 推荐路径]:")
+    if system == "Linux":
+        print(f"  {home}/.cursor/mcp.json")
+    elif system == "Darwin":
+        print(f"  ~/Library/Application Support/Cursor/User/globalStorage/rosebud.cursor-ide-browser/mcp.json")
+    
+    print(f"\n[Cursor/Claude 粘贴内容 (sdev 字段)]: ")
+    print(json.dumps(sdev_config, indent=2, ensure_ascii=False))
+    
+    print(f"\n[完整示例 (mcp.json)]: ")
+    full_example = {
+        "mcpServers": {
+            "sdev": sdev_config
+        }
+    }
+    print(json.dumps(full_example, indent=2, ensure_ascii=False))
+    
+    print(f"\n[{_ts()}] 请将上述内容添加到你的 MCP 配置文件中，并重启 AI 客户端。")
+    return 0
+
+
 def main(argv: Optional[list[str]] = None) -> int:
     parser = _build_parser()
     args = parser.parse_args(argv)
@@ -750,6 +820,8 @@ def main(argv: Optional[list[str]] = None) -> int:
         return _handle_reset(args)
     if args.command == "server":
         return _handle_server(args)
+    if args.command == "mcp":
+        return _handle_mcp(args)
 
     parser.error(f"未知子命令: {args.command}")
     return 1

{sdev-0.7.2 → sdev-0.7.5}/sdev/deprecated/demoboard.py

@@ -105,17 +105,15 @@ class Demoboard:
         response_timeout = None if wait_forever else timeout
 
         def _iter_cmd() -> Generator[str, None, None]:
-            for line in self._nb.run(
+            return self._nb.run(
                 cmd=cmd,
                 end_flag=flag,
                 overall_timeout=timeout,
                 response_timeout=response_timeout,
                 stream=True,
                 verbose=True,
-            ):
-                text = getattr(line, "text", str(line))
-                yield text
-
+            )
+            
         if stream:
             return _iter_cmd()
         return list(_iter_cmd())

{sdev-0.7.2 → sdev-0.7.5}/sdev/modules/__init__.py

@@ -1,12 +1,11 @@
 from __future__ import annotations
 
-from .serial_rw import SerialRW, scan_serial_ports, check_port_alive_nonblock
-from .serial_rw_server import SerialRWClient, SerialRWServer, DEFAULT_SERVICE_PORT
+from .serial_rw import scan_serial_ports, check_port_alive_nonblock
+from .serial_rw_server import  DEFAULT_SERVICE_PORT, SerialRWServer
 from .serial_notebook import SerialNotebook
 
 __all__ = [
-    "SerialRW",
-    "SerialRWClient",
+    "SerialNotebook",
     "SerialRWServer",
     "scan_serial_ports",
     "check_port_alive_nonblock",

sdev-0.7.5/sdev/modules/mcp_server.py

@@ -0,0 +1,124 @@
+from mcp.server.fastmcp import FastMCP
+from .serial_notebook import SerialNotebook
+from .serial_rw_server import get_remote_hosts, fetch_boards_from_host, DEFAULT_SERVICE_PORT
+from .serial_rw import scan_serial_ports, check_port_alive_nonblock
+import logging
+import os
+import sys
+
+# 初始化 FastMCP
+mcp = FastMCP("sdev")
+
+@mcp.tool()
+def sdev_list(scope: str = "all") -> str:
+    """
+    获取可用串口设备列表。
+    scope: "all" (默认), "local" (仅本地), "remote" (仅远程)。
+    返回格式化的设备列表字符串。
+    """
+    from ..cli import _device_id
+    
+    local_ports = []
+    if scope in ("all", "local"):
+        local_ports = scan_serial_ports()
+        
+    remote_hosts = []
+    if scope in ("all", "remote"):
+        try:
+            remote_hosts = get_remote_hosts()
+        except:
+            pass
+        
+    results = []
+    
+    # 本地扫描
+    for p in local_ports:
+        r = check_port_alive_nonblock(p, timeout=1.0)
+        if r.get("available"):
+            # 尝试读型号
+            try:
+                with SerialNotebook(device=p) as nb:
+                    model = nb.get_model_type(timeout=2.0) or "unknown"
+            except:
+                model = "unknown"
+            results.append(f"HOST: localhost, DEVICE: {p}, ID: {_device_id('localhost', p)}, TYPE: {model}")
+            
+    # 远程扫描
+    for host, port in remote_hosts:
+        try:
+            boards = fetch_boards_from_host(host, port)
+            for b in boards:
+                if b.get("available"):
+                    dev = b.get("device") or b.get("port")
+                    try:
+                        with SerialNotebook(device=dev, host=host, port=port) as nb:
+                            model = nb.get_model_type(timeout=2.0) or "unknown"
+                    except:
+                        model = "unknown"
+                    results.append(f"HOST: {host}, DEVICE: {dev}, ID: {_device_id(host, dev)}, TYPE: {model}")
+        except:
+            continue
+                
+    if not results:
+        return "未发现可用设备。"
+    return "\n".join(results)
+
+@mcp.tool()
+def sdev_run(cmd: str, device_id: str = None, timeout: float = 10.0) -> str:
+    """
+    在指定设备上执行命令。
+    cmd: 要执行的 shell 命令。
+    device_id: 设备 ID（从 sdev_list 获取）。如果不指定，则尝试使用默认设备。
+    timeout: 整体超时时间（秒）。
+    """
+    from ..cli import _read_default, _resolve_device_to_host_port
+    
+    host = "localhost"
+    device = None
+    
+    if device_id:
+        res = _resolve_device_to_host_port(device_id)
+        if res:
+            host, device = res
+        else:
+            return f"错误：未找到 ID 为 {device_id} 的设备。"
+    else:
+        cfg = _read_default()
+        if cfg:
+            host = cfg.get("host", "localhost")
+            device = cfg.get("device") or cfg.get("port")
+        else:
+            return "错误：未指定 device_id 且没有配置默认设备。"
+            
+    if not device:
+        return "错误：无法确定串口路径。"
+        
+    try:
+        # 使用 SerialNotebook 执行
+        if host == "localhost":
+            nb = SerialNotebook(device=device)
+        else:
+            nb = SerialNotebook(device=device, host=host, port=DEFAULT_SERVICE_PORT)
+            
+        with nb:
+            lines = nb.run(cmd, overall_timeout=timeout, stream=False, verbose=False)
+            return "".join(lines).strip()
+    except Exception as e:
+        return f"执行失败：{e}"
+
+@mcp.tool()
+def sdev_set_default(device_id: str) -> str:
+    """
+    设置默认操作的设备。
+    device_id: 设备 ID。
+    """
+    from ..cli import _resolve_device_to_host_port, _write_default
+    res = _resolve_device_to_host_port(device_id)
+    if not res:
+        return f"错误：未找到 ID 为 {device_id} 的设备。"
+    host, device = res
+    _write_default(host, device, device_id)
+    return f"成功：已将默认设备设置为 {host}:{device} (ID: {device_id})"
+
+if __name__ == "__main__":
+    mcp.run()

{sdev-0.7.2 → sdev-0.7.5}/sdev/modules/serial_notebook.py

@@ -3,7 +3,7 @@ import sys
 import time
 from loguru import logger
 
-from .serial_rw import SerialRW, SerialLine, CTRL_C
+from .serial_rw import SerialLine, CTRL_C
 
 GREY = "\033[90m"
 YELLOW = "\033[33m"
@@ -13,9 +13,10 @@ RESET = "\033[0m"
 class SerialNotebook():
     def __init__(self, device: str, baudrate: int = 115200, host=None, port=None, default_flag=" #"):
         if host is not None and port is not None:
-            from serial_rw_server import SerialRWClient
+            from .serial_rw_server import SerialRWClient
             self._core = SerialRWClient(host, port, device, baudrate)
         else:
+            from .serial_rw import SerialRW
             self._core = SerialRW(device, baudrate)
         self.default_flag = default_flag
         self._muted = False
@@ -40,7 +41,7 @@ class SerialNotebook():
     def __exit__(self, exc_type, exc_value, traceback):
         self._core.disconnect()
 
-    def run(self, cmd: str, end_flag=None, allow_fold=True, max_fold_lines=4, strip_echo=True, stream=False, verbose=True, overall_timeout=None, response_timeout=None):
+    def run(self, cmd: str, end_flag=None, allow_fold=True, max_fold_lines=4, strip_echo=True, stream=False, verbose=True, overall_timeout=None, response_timeout=None, keep_type=False):
         # 先清理残留输出，避免前一次命令的尾巴影响本次结果。
         assert cmd is not None
         self._core.drain_buffer()
@@ -73,12 +74,15 @@ class SerialNotebook():
                 ):
                     _check_overall_timeout()
                     line: SerialLine
-                    if line.kind == 'timeout':
+                    if line.kind == 'error' and line.text == '<sdev timeout>\n':
                         raise TimeoutError
                     # print(line.kind, line.line, show_log, isinstance(line, SerialLine), line.kind == 'body')
                     if show_log and isinstance(line, SerialLine) and line.kind == 'body':
                         self._write_raw(f"{GREY}{line.text}{RESET}")
-                    yield line
+                    if keep_type:
+                        yield line
+                    else:
+                        yield line.text
                 # 整个命令结束后，如启用 display，则额外输出一个空行（两个换行），
                 # 便于与后续命令在视觉上明显隔离。
                 if show_log:
@@ -137,12 +141,27 @@ class SerialNotebook():
             self.run(cmd="reboot", end_flag=reboot_finish_when_see)
 
 
-    def get_model_type(self, prompt_flag=" #", timeout=2.0, verbose=False) -> bool:
+    def get_model_type(self, prompt_flag=None, timeout=3.0, verbose=False):
+        """
+        读取设备树型号前缀：
+        - 命令：cat /proc/device-tree/model 2>/dev/null; echo
+        - 若 prompt_flag 为 None，则尝试使用较宽泛的匹配。
+        """
+        if prompt_flag is None:
+            # 常见提示符结尾：#, $, >
+            prompt_flag = "[#$>]"
         try:
             cmd = "cat /proc/device-tree/model 2>/dev/null; echo"
-            lines = self.run(cmd=cmd, end_flag=prompt_flag, stream=False, overall_timeout=timeout, verbose=verbose)
-            if lines and len(lines) > 2:
-                return lines[-2].text.strip()
+            lines = self.run(
+                cmd=cmd,
+                end_flag=prompt_flag,
+                stream=False,
+                overall_timeout=timeout,
+                response_timeout=timeout,
+                verbose=verbose,
+            )
+            if lines and len(lines) >= 2:
+                return lines[-2].strip()
         except Exception:
             pass
         return None

{sdev-0.7.2 → sdev-0.7.5}/sdev/modules/serial_rw.py

@@ -105,9 +105,17 @@ def _content_contains_ctrl_c(text: str) -> bool:
     return CTRL_C in n or "^C" in n
 
 def scan_serial_ports() -> list[str]:
-    """扫描系统可用串口。"""
+    """扫描系统可用串口，并按平台做基础筛选。
+
+    - POSIX：仅保留以 /dev/tty 开头的设备（忽略 /dev/cu.* 等非目标设备）；
+    - 其他平台：直接返回 list_ports 结果。
+    """
     import serial.tools.list_ports
-    return [p.device for p in serial.tools.list_ports.comports()]
+
+    ports = [p.device for p in serial.tools.list_ports.comports()]
+    if os.name == "posix":
+        ports = [d for d in ports if d.startswith("/dev/tty")]
+    return ports
 
 def check_port_alive_nonblock(port: str, baudrate: int = 115200, timeout: float = 1.0) -> dict:
     """快速探测串口是否可用（不阻塞）。"""
@@ -244,7 +252,7 @@ class SerialRW():
             for line in self._flag_stopper(lines, flag, allow_fold, max_fold_lines):
                 yield SerialLine(kind='body', text=line)
         except TimeoutError:
-            yield SerialLine(kind='timeout', text='<sdev timeout>\n')
+            yield SerialLine(kind='error', text='<sdev timeout>\n')
             
     def drain_buffer(self) -> None:
         while True:

{sdev-0.7.2 → sdev-0.7.5}/sdev/modules/serial_rw_server.py

@@ -9,6 +9,8 @@ import time
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from typing import Any, Generator, Optional, List, Tuple, Dict
 
+from loguru import logger
+
 from .serial_rw import SerialRW, SerialLine, scan_serial_ports, check_port_alive_nonblock
 
 DEFAULT_SERVICE_PORT = 7000
@@ -218,6 +220,7 @@ class SerialRWServer:
             if isinstance(init, dict):
                 cmd = init.get("cmd")
                 if cmd == "list":
+                    logger.info(f"[server] list request from {addr}")
                     ports = scan_serial_ports()
                     boards: List[dict] = []
                     if ports:
@@ -226,14 +229,18 @@ class SerialRWServer:
                         with ThreadPoolExecutor(max_workers=min(8, len(ports))) as ex:
                             futs = {ex.submit(_probe, p): p for p in ports}
                             for fut in as_completed(futs):
-                                r = fut.result()
-                                boards.append({
-                                    "port": r["port"],
-                                    "baudrate": r["baudrate"],
-                                    "available": r["available"],
-                                    "reason": r.get("reason", ""),
-                                })
+                                try:
+                                    r = fut.result()
+                                    boards.append({
+                                        "port": r["port"],
+                                        "baudrate": r["baudrate"],
+                                        "available": r["available"],
+                                        "reason": r.get("reason", ""),
+                                    })
+                                except Exception as e:
+                                    logger.error(f"[server] probe error for port: {e}")
                     conn.sendall(json.dumps({"boards": boards}, ensure_ascii=False).encode("utf-8") + b"\n")
+                    logger.info(f"[server] list response sent to {addr} (count={len(boards)})")
                     return
                 if cmd == "probe":
                     port = (init.get("device") or init.get("port") or "").strip()
@@ -251,10 +258,13 @@ class SerialRWServer:
                 conn.sendall(b'{"ok":false,"error":"missing device"}\n')
                 return
 
+            logger.info(f"[server] session from {addr}: port={device_val}, baudrate={baudrate_val}")
             dev = SerialRW(device_val, baudrate_val)
             try:
                 dev.connect()
+                logger.info(f"[server] connected to {device_val} for {addr}")
             except Exception as e:
+                logger.error(f"[server] connect failed for {device_val}: {e}")
                 err = json.dumps({"ok": False, "error": str(e)}, ensure_ascii=False).encode("utf-8") + b"\n"
                 conn.sendall(err)
                 return
@@ -340,6 +350,7 @@ class SerialRWServer:
 
         while True:
             conn, addr = sock.accept()
+            logger.info(f"[server] TCP connection from {addr}")
             threading.Thread(target=self._session_loop, args=(conn, addr), daemon=True).start()
 
     @staticmethod
@@ -401,17 +412,51 @@ def discover_hosts_via_zeroconf(timeout: float = 0.8) -> List[Tuple[str, int]]:
         return []
 
 def discover_hosts_via_udp(timeout: float = 1.5) -> List[Tuple[str, int]]:
+    """
+    通过 UDP 广播 / 定向探测发现远程 sdev server：
+    - 优先读取环境变量 SDEV_DISCOVERY_TARGETS="host[:port],host2[:port2],..."
+      按指定目标发送 discovery 报文；
+    - 未指定时，退回到对 255.255.255.255:DISCOVERY_UDP_PORT 的广播。
+    """
     sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
     try:
         sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
         sock.settimeout(timeout)
         sock.bind(("", 0))
-        sock.sendto(b"SDEV_DISCOVERY", ("255.255.255.255", DISCOVERY_UDP_PORT))
+
+        # 解析 SDEV_DISCOVERY_TARGETS 作为定向探测目标
+        targets: List[Tuple[str, int]] = []
+        raw = os.environ.get("SDEV_DISCOVERY_TARGETS", "").strip()
+        if raw:
+            for item in raw.split(","):
+                item = item.strip()
+                if not item:
+                    continue
+                if ":" in item:
+                    h, ps = item.rsplit(":", 1)
+                    try:
+                        targets.append((h.strip(), int(ps)))
+                    except ValueError:
+                        targets.append((h.strip(), DISCOVERY_UDP_PORT))
+                else:
+                    targets.append((item, DISCOVERY_UDP_PORT))
+        if not targets:
+            targets.append(("255.255.255.255", DISCOVERY_UDP_PORT))
+
+        for host, port in targets:
+            try:
+                sock.sendto(b"SDEV_DISCOVERY", (host, port))
+            except OSError:
+                continue
+
         hosts: set = set()
         deadline = time.monotonic() + timeout
         while time.monotonic() < deadline:
             try:
+                sock.settimeout(max(0.0, deadline - time.monotonic()))
                 data, addr = sock.recvfrom(4096)
+                if not data:
+                    continue
                 obj = json.loads(data.decode("utf-8"))
                 if obj.get("magic") == "sdev-remote-v1":
                     hosts.add((addr[0], int(obj.get("port") or DEFAULT_SERVICE_PORT)))
@@ -454,13 +499,46 @@ def get_remote_hosts(service_port: int = DEFAULT_SERVICE_PORT) -> List[Tuple[str
     return list(merged)
 
 
-if __name__ == "__main__":
+def _server_log_path() -> str:
+    """
+    与 CLI `_server_log_path` 保持一致：
+    - 优先使用 XDG_RUNTIME_DIR/sdev/server.log
+    - 否则使用 ~/.cache/sdev/server.log
+    """
+    base = os.environ.get("XDG_RUNTIME_DIR") or os.path.join(os.path.expanduser("~"), ".cache")
+    d = os.path.join(base, "sdev")
+    os.makedirs(d, mode=0o700, exist_ok=True)
+    return os.path.join(d, "server.log")
+
+
+def main() -> int:
     import sys
+
     port = DEFAULT_SERVICE_PORT
     if len(sys.argv) > 1:
         try:
             port = int(sys.argv[1])
         except ValueError:
             pass
+
+    # 与旧实现保持一致的日志行为：只写到 server.log，不打印到前台。
+    log_path = _server_log_path()
+    logger.remove()
+    logger.add(
+        log_path,
+        rotation="1 MB",
+        retention=5,
+        encoding="utf-8",
+        enqueue=True,
+        backtrace=False,
+        diagnose=False,
+    )
+    logger.info(f"[server] listening TCP 0.0.0.0:{port}, UDP 0.0.0.0:{DISCOVERY_UDP_PORT}")
+
     server = SerialRWServer(port=port)
     server.serve_forever()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{sdev-0.7.2 → sdev-0.7.5/sdev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sdev
-Version: 0.7.2
+Version: 0.7.5
 Summary: 串口控制器工具包
 Home-page: https://github.com/klrc/sdev
 Author: klrc
@@ -57,34 +57,41 @@ pip install sdev
 
 ## 命令行快速上手
 
-安装后会提供一个 `sdev` 命令，包括：
-
-- `sdev list`：扫描本地 / 远程可用串口；
-- `sdev run`：在选定设备上执行命令；
-- `sdev server`：启动/停止本机串口共享服务；
+安装后提供一个 `sdev` 命令，核心功能包括：
+
+- **`sdev list [scope] [filters...]`**：扫描本地 / 远程可用串口。
+  - `scope`: `local`, `remote` 或不填。
+  - `filters`: 如 `type=XC01` 或 `host=192.168.1.101`。
+  - `-f, --fast`: 快速模式，找到第一个符合条件的设备后立即输出（适合脚本）。
+- **`sdev run [cmd...]`**：执行命令。
+  - `-i, --interrupt-only`: 仅发送一次 Ctrl-C，随后被动收集输出（不发送新命令）。
+  - `-t, --timeout`: 整体超时限制。
+  - `-w, --wait-forever`: 永久等待输出，直至整体超时或手动中断。
+- **`sdev server [action]`**：管理本机串口共享服务。
+  - `action`: `start`, `stop`, `restart`, `status`。
+- **`sdev mcp [action]`**：AI 集成（Model Context Protocol）。
+  - `action`: `install` (一键配置到 IDE), `run` (由 IDE 调起的后台服务)。
 - `sdev set` / `sdev show` / `sdev reset`：管理默认设备与缓存。
 
 典型流程：
 
 ```bash
-# 1. （可选）在“串口所在机器”上启动 server
+# 1. 在“串口所在机器”上启动 server
 sdev server start
 
-# 2. 扫描可用设备
-sdev list
+# 2. 扫描并筛选可用设备
+sdev list remote              # 仅扫描远程
+sdev list type=XC01           # 仅列出特定型号
+sdev list -f type=XC01        # 快速模式：找到第一个 XC01 立即返回（适合脚本）
 
-# 3. （推荐）选中一块板，配置为默认设备
+# 3. 选中一块板，配置为默认设备
 sdev set default <DEVICE_ID>
 
-# 4. 之后即可直接执行命令
-sdev run 'cat /proc/meminfo'
-sdev run -t 10 'dmesg | tail'
+# 4. 执行命令
+sdev run 'cat /proc/meminfo'  # 执行完整交互
+sdev run -i                   # 仅发送 Ctrl-C (用于中断正在跑的任务并查看输出)
 ```
 
-更详细的 CLI 用法与行为说明，参考项目内的 skill 文档：
-
-- `docs/skills/serial-sdev-cli/SKILL.md`
-
 ---
 
 ## Python API 快速上手（SerialNotebook）
@@ -125,6 +132,25 @@ with SerialNotebook(device=SERIAL_PORT, baudrate=115200, host=HOST, port=7000) a
 
 ---
 
+## AI 集成 (MCP)
+
+`sdev` 支持 **Model Context Protocol (MCP)**，允许 AI 助手（如 Cursor、Claude Desktop）直接操作串口，执行命令并感知设备状态。
+
+### 1. 获取配置信息
+在本地环境执行：
+```bash
+sdev mcp install
+```
+该命令会自动生成可用于粘贴的 JSON 配置片段，并提示 Cursor 或 Claude Desktop 的配置路径。
+
+### 2. 提供的能力 (Tools)
+安装后，AI 助手将获得以下工具：
+- `sdev_list`: 获取本地及远程可用设备列表。
+- `sdev_run`: 在指定设备上执行命令并获取输出。
+- `sdev_set_default`: 设置当前会话的默认设备。
+
+---
+
 ## 适用 / 不适用的场景
 
 **适用：**
@@ -143,9 +169,6 @@ with SerialNotebook(device=SERIAL_PORT, baudrate=115200, host=HOST, port=7000) a
 ## 更多文档
 
 - **内部架构与设计说明**：`docs/arch_design.md`
-- **技能（在 Cursor 里集成使用方式）**：
-  - `docs/skills/serial-sdev-cli/SKILL.md`
-  - `docs/skills/serial-sdev-api/SKILL.md`
 
 源码结构概览（仅列出现行实现）：
 
@@ -153,5 +176,6 @@ with SerialNotebook(device=SERIAL_PORT, baudrate=115200, host=HOST, port=7000) a
   - `serial_rw.py`：本地串口读写与锁管理（`SerialRW`）、运行控制器（`SerialRunner`）、端口扫描与快速探测；
   - `serial_rw_server.py`：远程串口共享服务与客户端（`SerialRWServer` / `SerialRWClient`），以及主机发现逻辑；
   - `serial_notebook.py`：Notebook / 脚本场景下的最高层 Python 入口（`SerialNotebook`），基于 `SerialRW` / `SerialRWClient` 实现。
-- `sdev/cli/`：命令行入口 `sdev`（`__init__.py` 中的 `main()`），直接基于 `SerialRW` / `SerialRunner` 与 `SerialRWClient` 实现 `run / list / server` 等子命令。
+- `sdev/cli/`：命令行入口 `sdev`（`__init__.py` 中的 `main()`），以 `SerialNotebook` 作为上层统一入口，并通过 `SerialRWServer`/`SerialRWClient` 实现远程 `run / list / server` 等子命令。
+
 

{sdev-0.7.2 → sdev-0.7.5}/sdev.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ sdev/cli/__init__.py
 sdev/cli/__main__.py
 sdev/deprecated/demoboard.py
 sdev/modules/__init__.py
+sdev/modules/mcp_server.py
 sdev/modules/serial_notebook.py
 sdev/modules/serial_rw.py
 sdev/modules/serial_rw_server.py

{sdev-0.7.2 → sdev-0.7.5}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="sdev",
-    version="0.7.2",
+    version="0.7.5",
     author="klrc",
     author_email="144069824@qq.com",
     description="串口控制器工具包",
@@ -32,6 +32,7 @@ setup(
         "pyserial>=3.5",
         "loguru>=0.6.0",
         "zeroconf>=0.39.0",
+        "mcp>=1.0.0",
     ],
     entry_points={
         "console_scripts": ["sdev=sdev.cli:main"],