magic-agent 2.4.2 → 2.4.3

package/CLIENT-CONTRACT.md

@@ -432,6 +432,12 @@ notice     {text:"团队模式：追加 N 个补充任务（a1、a2），继续
 | 令牌下限 | 24 字符；弱令牌**拒绝启动**（自动生成的默认令牌是 32 位十六进制，够用） |
 | 无令牌访问 | `401` —— 不因为是内网就放行 |
 | 不带 `--lan` | 局域网地址**连不上**（默认就是安全的） |
+| 地址的挑选与顺序 | 虚拟网卡（容器 / 虚拟交换机 / 隧道）的地址**不报**；公网段地址在还有私有地址时也不报；剩下的按「出站主地址（默认路由那张网卡）→ 其余」排。**第一个 = 手机最可能连上的那个** —— 移动端只认 `[0]` |
+
+⚠️ **地址顺序是契约的一部分（2026-10-23 修正）**：以前直接按网卡枚举顺序返回，
+而企业 VPN 虚拟网卡常常排在真实网卡前面 —— 移动端自动补的「公司远程」环境
+就被种成了一个手机路由不到的地址，表现为「启动成功但手机连不上」。
+现在第一个地址保证是手机能连的那个。`/desk/health.lanUrls` 用同一份顺序。
 
 扫码配对在 v1 就是「扫这段 URL」（URL 自带令牌）。带 TTL 的配对码交换属于 L2（跨网）的活，
 需要服务端与令牌存储，**未做**。

package/internal/cli/session.go

@@ -425,21 +425,12 @@ func runSessions(cmd *cobra.Command, opts *askOptions) error {
 			TitleSummarized: summarized,
 			StartedAt:       r.StartedAt.Format("2006-01-02 15:04:05"),
 			UpdatedAt:       r.UpdatedAt.Format("2006-01-02 15:04:05"),
-			HasLog:          hasSessionLog(logDir, r),
+			HasLog:          session.HasSessionLogIn(logDir, r.SessionID, r.RunID),
 		})
 	}
 	return printJSON(cmd.OutOrStdout(), rows)
 }
 
-// hasSessionLog 这条记录有没有可回放的事件日志。
-//
-// 日志文件名可能是 **session_id**（终名），也可能是 **run_id** —— 引擎还没吐 id 时
-// core 先按 run_id 落盘（见 sessionlog.go 的 setRunID / renameTo），所以两个名字都试一次；
-// 决议逻辑（含 run_id → session_id 的翻译）在 session.HasSessionLog 里，读接口共用同一份。
-func hasSessionLog(dir string, rec session.Record) bool {
-	return session.HasSessionLog(dir, rec.SessionID) || session.HasSessionLog(dir, rec.RunID)
-}
-
 // runSessionLog 读一段会话的**事件历史**：`--session-log <id> [--after <seq>]`。
 //
 // 为什么这条命令必须存在：会话的「查询」原先只有 HTTP 插件能做（`/desk/session/{id}/messages`），

package/internal/client/lan.go

@@ -33,17 +33,142 @@ func ValidateLanToken(token string) error {
 	return nil
 }
 
+/* ── 局域网地址的挑选 ──
+ *
+ * ⚠️ **顺序有讲究，而且这份顺序是「能不能连上」的关键**（2026-10-23 修）。
+ *
+ * 调用方全都只认**第一个**：
+ *   · `/desk/health` 的 lanUrls → 移动端自动补的「公司远程」环境取 [0]；
+ *   · `magic-client start` 打印的**第一张**二维码 → 扫出来就是这个地址。
+ *
+ * 而一台装了企业 VPN / Hyper-V 的机器上有多张网卡，枚举顺序由系统决定，
+ * 先出来的常常是**手机根本路由不到**的那张：企业 VPN 虚拟网卡（10.x / 2.x 段）
+ * 与虚拟交换机（172.16/12 段）都属于「只在本机或专用隧道里有效」的地址，
+ * 手机在同一个 Wi-Fi 下压根到不了它们。
+ *
+ * 现象就是「启动成功、地址也打印出来了，但手机就是连不上」，而且**扫码比手抄更容易撞上**
+ * —— 扫的正是打印出来的第一张码。
+ *
+ * 现在的口径（三步，详见 orderLanAddresses）：
+ *  1. 按**名字**剔掉虚拟网卡（容器 / 虚拟交换机 / 隧道 / 回环伪接口）。
+ *  2. 再剔掉**公网段**地址（只要还有私有地址）：企业 VPN 的虚拟网卡常占一段
+ *     公网地址（这里 2.0.0.1），手机在局域网里根本路由不到那一段。
+ *  3. 剩下的里，出站主地址排最前（问一次内核要源地址，不发包）—— 那张网卡
+ *     就是本机跟外界说话用的那张，手机连它最可能通。
+ *
+ * 每一步都有兜底：真实网卡没剩就退回虚拟网卡，私有地址没剩就退回公网地址 ——
+ * 不能一个地址都不报。其余地址也会列在后面，用户可以手挑 —— 不猜、不假装。
+ */
+
+// lanCandidate 一个候选局域网地址，以及它所在的网卡。
+type lanCandidate struct {
+	ip    string
+	iface net.Interface
+}
+
+// virtualIfaceHints 虚拟 / 容器网卡的**名称特征**（子串匹配，忽略大小写）。
+//
+// 为什么按名字认：这些网卡在 Windows 上叫「vEthernet (Default Switch)」
+// （Hyper-V）、「VMware Network Adapter」；在 Linux 上叫 docker0 / veth* / virbr0；
+// 在 macOS 上叫 utun*。它们承载的地址只在本机或专用隧道内有效，手机连不到。
+var virtualIfaceHints = []string{
+	"vethernet", // Hyper-V 虚拟交换机
+	"hyper-v",
+	"vmware",
+	"virtualbox",
+	"docker",
+	"veth",
+	"virbr",
+	"br-",      // Linux 网桥
+	"loopback", // Windows「Loopback Pseudo-Interface」
+	"pseudo",
+	"npcap",
+	"bluetooth", // 蓝牙 PAN
+	"utun",      // macOS 隧道
+	"tailscale",
+	"zerotier",
+}
+
+// virtualIfaceNames 虚拟网卡的**完整**名称（小写）—— 这些是短名，
+// 用子串匹配会误伤别的网卡（"tun" 之于 "Tunnel"、"wg" 之于别的东西），所以整名匹配。
+var virtualIfaceNames = map[string]bool{
+	"tun0": true, "tun1": true,
+	"tap0": true, "tap1": true,
+	"docker0":   true,
+	"wg0":       true, // WireGuard
+	"zt0":       true, // ZeroTier
+	"zt1":       true,
+	"bridge100": true, // macOS 上的 VMware
+}
+
+// isVirtualIface 网卡是不是虚拟 / 容器网卡。
+func isVirtualIface(name string) bool {
+	n := strings.ToLower(strings.TrimSpace(name))
+	if virtualIfaceNames[n] {
+		return true
+	}
+	for _, h := range virtualIfaceHints {
+		if strings.Contains(n, h) {
+			return true
+		}
+	}
+	return false
+}
+
+// isPrivateIPv4 是不是 RFC1918 私有网段（10/8、172.16/12、192.168/16）。
+//
+// 为什么用它排序：手机在同一张局域网里拿到的也是私有地址，所以私有地址是
+// 「手机连得上」的第一嫌疑。反过来，企业 VPN 的虚拟网卡常占一段**公网**地址
+// （这台机器上 Sangfor aTrust VNIC 占的是 2.0.0.1）—— 手机在局域网里
+// 根本路由不到那一段，把公网地址排前面就是第一个就撞墙。
+func isPrivateIPv4(ip string) bool {
+	p := net.ParseIP(ip)
+	if p == nil {
+		return false
+	}
+	p = p.To4()
+	if p == nil {
+		return false
+	}
+	switch {
+	case p[0] == 10:
+		return true
+	case p[0] == 172 && p[1]&0xf0 == 16:
+		return true
+	case p[0] == 192 && p[1] == 168:
+		return true
+	}
+	return false
+}
+
+// primaryOutboundIP 返回本机对外通信时实际使用的源 IP（默认路由所在网卡的那张）。
+//
+// 怎么问内核：发起一次 UDP「连接」。UDP 的 connect 只查路由表并选定源地址，
+// **一个包都不发** —— 不是在访问外网，也就不会产生任何出网流量。
+// 问不到（没有默认路由 / 离线）时返回空串，调用方退化成保持网卡枚举顺序。
+func primaryOutboundIP() string {
+	conn, err := net.Dial("udp", "8.8.8.8:80")
+	if err != nil {
+		return ""
+	}
+	defer conn.Close()
+	host, _, err := net.SplitHostPort(conn.LocalAddr().String())
+	if err != nil {
+		return ""
+	}
+	return host
+}
+
 // LanAddresses 列出本机可用于局域网访问的 IPv4 地址（形如 `192.168.1.5:50022`）。
 //
 // 过滤掉回环、链路本地（169.254.x）与非 IPv4：这三类给手机都没用。
-// 一台机器可能有多个（有线 + 无线 + 虚拟网卡），所以返回切片让调用方全都打印出来 ——
-// 猜错网卡比多打两行地址麻烦得多。
+// 挑选与排序的口径见上面那段注释（虚拟网卡剔除 + 默认路由那张排最前）。
 func LanAddresses(port int) []string {
 	ifaces, err := net.Interfaces()
 	if err != nil {
 		return nil
 	}
-	var out []string
+	var cands []lanCandidate
 	for _, ifc := range ifaces {
 		if ifc.Flags&net.FlagUp == 0 || ifc.Flags&net.FlagLoopback != 0 {
 			continue
@@ -61,7 +186,68 @@ func LanAddresses(port int) []string {
 			if ip4 == nil || ip4.IsLoopback() || ip4.IsLinkLocalUnicast() {
 				continue
 			}
-			out = append(out, fmt.Sprintf("%s:%d", ip4.String(), port))
+			cands = append(cands, lanCandidate{ip: ip4.String(), iface: ifc})
+		}
+	}
+	return orderLanAddresses(cands, primaryOutboundIP(), port)
+}
+
+// orderLanAddresses 把候选地址按「手机最可能连得上」排好并拼上端口。
+//
+// 三步：
+//  1. 按**名字**剔掉虚拟网卡（Hyper-V / 容器 / 隧道 / 回环伪接口）——
+//     它们的地址只在本机或专用隧道里有效，手机连不到。
+//  2. 再剔掉**公网段**地址：只要还有私有地址，公网段的就不要
+//     （企业 VPN 虚拟网卡常占一段公网地址，而它在 Windows 上报的是连接别名
+//     「本地连接」这种通用名，靠名字抓不到 —— 靠网段能抓到）。
+//  3. 剩下的里，出站主地址（默认路由所在网卡）排最前。
+//
+// 每一步都有兜底：真实网卡没剩就退回虚拟网卡，私有地址没剩就退回公网地址 ——
+// **不能一个地址都不报**。
+//
+// 拆成独立函数是为了能直接喂合成数据做单测 —— 各人机器上的网卡千差万别，
+// 靠真机跑出来的用例没法覆盖「VPN 虚拟网卡恰好排在最前」这种关键情形。
+func orderLanAddresses(cands []lanCandidate, primary string, port int) []string {
+	if len(cands) == 0 {
+		return nil
+	}
+	real := make([]lanCandidate, 0, len(cands))
+	virtual := make([]lanCandidate, 0, len(cands))
+	for _, c := range cands {
+		if isVirtualIface(c.iface.Name) {
+			virtual = append(virtual, c)
+		} else {
+			real = append(real, c)
+		}
+	}
+	pool := real
+	if len(pool) == 0 {
+		// 一张真实网卡都没有：虚拟网卡也得给 —— 不能一个地址都不报。
+		pool = virtual
+	}
+	if priv := filterByPrivate(pool); len(priv) > 0 {
+		pool = priv
+	}
+	out := make([]string, 0, len(pool))
+	for _, c := range pool {
+		if c.ip == primary {
+			out = append(out, fmt.Sprintf("%s:%d", c.ip, port))
+		}
+	}
+	for _, c := range pool {
+		if c.ip != primary {
+			out = append(out, fmt.Sprintf("%s:%d", c.ip, port))
+		}
+	}
+	return out
+}
+
+// filterByPrivate 只留私有网段（RFC1918）的候选。
+func filterByPrivate(cands []lanCandidate) []lanCandidate {
+	out := make([]lanCandidate, 0, len(cands))
+	for _, c := range cands {
+		if isPrivateIPv4(c.ip) {
+			out = append(out, c)
 		}
 	}
 	return out

package/internal/client/lan_test.go

@@ -1,6 +1,7 @@
 package client
 
 import (
+	"net"
 	"strings"
 	"testing"
 )
@@ -51,3 +52,112 @@ func TestLanAddresses(t *testing.T) {
 	// 本机可能只连着回环（离线环境），所以不要求非空，只在有结果时做上面的形状断言。
 	t.Logf("局域网地址：%v", got)
 }
+
+// TestIsVirtualIface 虚拟网卡的识别。
+//
+// 回归背景（2026-10-23）：一台装了企业 VPN + Hyper-V 的机器上，网卡枚举里
+// 排最前的是 VPN 虚拟网卡，手机拿到它就连不上 —— 详见 lan.go 那段注释。
+func TestIsVirtualIface(t *testing.T) {
+	cases := []struct {
+		name string
+		want bool
+	}{
+		{"以太网", false},
+		{"Ethernet", false},
+		{"WLAN", false},
+		{"Wi-Fi", false},
+		{"本地连接", false}, // Windows 上真实网卡也可能是中文名
+		{"vEthernet (Default Switch)", true},
+		{"Hyper-V Virtual Ethernet Adapter", true},
+		{"VMware Network Adapter VMnet8", true},
+		{"docker0", true},
+		{"veth1234", true},
+		{"virbr0", true},
+		{"br-abcdef", true},
+		{"utun3", true},
+		{"tailscale0", true},
+		{"wg0", true},
+		{"Loopback Pseudo-Interface 1", true},
+		{"  以太网  ", false}, // 前后空格不算
+	}
+	for _, tc := range cases {
+		if got := isVirtualIface(tc.name); got != tc.want {
+			t.Errorf("isVirtualIface(%q) = %v，want %v", tc.name, got, tc.want)
+		}
+	}
+}
+
+// TestIsPrivateIPv4 RFC1918 判定。
+func TestIsPrivateIPv4(t *testing.T) {
+	cases := []struct {
+		ip   string
+		want bool
+	}{
+		{"192.168.31.37", true},
+		{"10.0.0.1", true},
+		{"172.16.0.1", true},
+		{"172.31.255.254", true},
+		{"172.32.0.1", false},
+		{"172.15.0.1", false},
+		{"2.0.0.1", false}, // 企业 VPN 虚拟网卡占的公网段
+		{"8.8.8.8", false},
+		{"", false},
+	}
+	for _, tc := range cases {
+		if got := isPrivateIPv4(tc.ip); got != tc.want {
+			t.Errorf("isPrivateIPv4(%q) = %v，want %v", tc.ip, got, tc.want)
+		}
+	}
+}
+
+// TestOrderLanAddresses 排序：手机最可能连上的那个必须排第一。
+//
+// 回归背景（2026-10-23）：真实机器上枚举顺序是
+//
+//	[0] 2.0.0.1     ← Sangfor aTrust VNIC（企业 VPN 虚拟网卡）
+//	[1] 172.29.64.1 ← Hyper-V 虚拟交换机
+//	[2] 192.168.31.37 ← 以太网（手机能连的只有这个）
+//
+// 移动端只取 lanUrls[0]，于是「公司远程」环境被种成了 2.0.0.1 —— 手机永远连不上。
+func TestOrderLanAddresses(t *testing.T) {
+	cands := []lanCandidate{
+		{ip: "2.0.0.1", iface: net.Interface{Name: "本地连接"}},                           // VPN 虚拟网卡（Windows 上是中文别名）
+		{ip: "172.29.64.1", iface: net.Interface{Name: "vEthernet (Default Switch)"}}, // Hyper-V
+		{ip: "192.168.31.37", iface: net.Interface{Name: "以太网"}},
+	}
+	got := orderLanAddresses(cands, "192.168.31.37", 9100)
+	if len(got) == 0 {
+		t.Fatal("不该返回空")
+	}
+	if got[0] != "192.168.31.37:9100" {
+		t.Errorf("第一个必须是手机连得上的那个（192.168.31.37），got %v", got)
+	}
+	for _, a := range got {
+		if strings.HasPrefix(a, "2.0.0.1:") || strings.HasPrefix(a, "172.29.") {
+			t.Errorf("虚拟网卡地址不该出现在列表里：%s", a)
+		}
+	}
+}
+
+// TestOrderLanAddressesVirtualOnly 只有虚拟网卡时也得给地址 —— 不能一个都不报。
+func TestOrderLanAddressesVirtualOnly(t *testing.T) {
+	cands := []lanCandidate{
+		{ip: "172.29.64.1", iface: net.Interface{Name: "vEthernet (Default Switch)"}},
+	}
+	got := orderLanAddresses(cands, "", 9100)
+	if len(got) != 1 || got[0] != "172.29.64.1:9100" {
+		t.Errorf("没有真实网卡时应退回报虚拟网卡地址，got %v", got)
+	}
+}
+
+// TestOrderLanAddressesPrimaryFirst 出站主地址在同一档里排最前。
+func TestOrderLanAddressesPrimaryFirst(t *testing.T) {
+	cands := []lanCandidate{
+		{ip: "192.168.31.10", iface: net.Interface{Name: "以太网 2"}},
+		{ip: "192.168.31.37", iface: net.Interface{Name: "以太网"}},
+	}
+	got := orderLanAddresses(cands, "192.168.31.37", 9100)
+	if len(got) != 2 || got[0] != "192.168.31.37:9100" {
+		t.Errorf("出站主地址应排最前，got %v", got)
+	}
+}

package/internal/session/sessionlog.go

@@ -104,6 +104,29 @@ func HasSessionLog(dir, id string) bool {
 	return err == nil && st.Size() > 0
 }
 
+// HasSessionLogIn 判断**给定候选 id** 里有没有可回放的日志（文件在且非空）。
+//
+// 与 HasSessionLog 的区别：**不回查登记表**。调用方（列表页）手里已经有这条记录的
+// session_id / run_id，两个都试一遍就够了；而 HasSessionLog 会走
+// ResolveLogID → Find → List，那是「把全部登记记录读一遍」——
+// 逐行调用就是 O(N²) 次文件读。2026-10-23 实测：登记表 760 条时
+// `magic-agent --sessions` 卡死数分钟、CPU 打满，移动端列表永远停在「读取中…」。
+func HasSessionLogIn(dir string, ids ...string) bool {
+	if dir == "" {
+		return false
+	}
+	for _, id := range ids {
+		id = strings.TrimSpace(id)
+		if id == "" {
+			continue
+		}
+		if st, err := os.Stat(logPath(dir, id)); err == nil && st.Size() > 0 {
+			return true
+		}
+	}
+	return false
+}
+
 func fileExists(p string) bool {
 	st, err := os.Stat(p)
 	return err == nil && !st.IsDir()

package/internal/session/sessionlog_read_test.go

@@ -623,3 +623,42 @@ func writeRecordForTest(t *testing.T, dir string, rec Record) {
 		t.Fatal(err)
 	}
 }
+
+// TestHasSessionLogIn 列表页用的「按候选 id 直接查日志」：不查登记表。
+//
+// 为什么要单独一个函数（2026-10-23）：`--sessions` 原先逐行调 HasSessionLog，
+// 而它内部走 ResolveLogID → Find → List，等于**每行都把全部登记记录读一遍**。
+// 本机登记表涨到 760 条后，整条命令卡死数分钟、CPU 打满，移动端列表永远停在
+// 「读取中…」。这里钉住新函数的行为：两个 id 都认、目录为空即 false、绝不碰登记表。
+func TestHasSessionLogIn(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "sess-a.jsonl"),
+		[]byte(`{"seq":1,"kind":"text","text":"a"}`+"\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	// 空文件不算有历史（与 HasSessionLog 同口径）。
+	if err := os.WriteFile(filepath.Join(dir, "sess-empty.jsonl"), nil, 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	if !HasSessionLogIn(dir, "sess-a") {
+		t.Error("按 session_id 应命中")
+	}
+	if !HasSessionLogIn(dir, "", "sess-a") {
+		t.Error("候选里有一个命中就算命中（空串跳过）")
+	}
+	if HasSessionLogIn(dir, "sess-empty") {
+		t.Error("空文件不算有可回放历史")
+	}
+	if HasSessionLogIn(dir, "nope", "") {
+		t.Error("都没有时应为 false")
+	}
+	if HasSessionLogIn("", "sess-a") {
+		t.Error("dir 为空应直接 false（不能去猜默认目录）")
+	}
+	// 关键：本函数**不依赖**登记表 —— 即使把 EnvDir 指到空目录也必须照常工作。
+	t.Setenv(EnvDir, t.TempDir())
+	if !HasSessionLogIn(dir, "sess-a") {
+		t.Error("HasSessionLogIn 不该依赖登记表目录")
+	}
+}

package/npm/apk/version.json

@@ -1,5 +1,5 @@
 {
   "version": "2.4.2",
   "versionCode": 20402,
-  "builtAt": "2026-10-23T11:49:45.889Z"
+  "builtAt": "2026-10-23T12:24:54.000Z"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magic-agent",
-  "version": "2.4.2",
+  "version": "2.4.3",
   "description": "专业的 agent CLI 代理工具 - 统一 claude / codebuddy / trae / llm / codex / openclaw 引擎",
   "license": "MIT",
   "bin": {