chore(cloud-claude): clean up Mutagen-facing leftovers

ZaneL1u · ZaneL1u · commit 2a382352c9d7 · 2026-04-21T19:34:14.000+08:00
Align the CLI and doctor output with the new in-process hot sync path so users are no longer sent back to obsolete Mutagen flows. Keep the legacy mount-mode value as a parsing alias while switching user-facing wording and conflict reporting to hot sync semantics.

Made-with: Cursor
diff --git a/cmd/cloud-claude/main.go b/cmd/cloud-claude/main.go
@@ -88,7 +88,7 @@ func main() {
 	// runRoot 内会手动解析并从 args 中剥离，避免透传给远端 claude。
 	// 这里注册仅用于 --help 显示与 cobra Mark Hidden 等元数据。
 	rootCmd.PersistentFlags().String("mount-mode", "auto",
-		"文件映射模式: auto|full|mutagen-only|sshfs-only")
+		"文件映射模式: auto|full|hot-only|sshfs-only（兼容 legacy: mutagen-only）")
 
 	rootCmd.AddCommand(initCmd, envCmd, sshCmd, newSyncCmd(), newSessionsCmd(), newExplainCmd(), newDoctorCmd())
 
@@ -280,7 +280,7 @@ func runRoot(cmd *cobra.Command, args []string) error {
 
 	mode, err := cloudclaude.ParseMode(mountMode)
 	if err != nil {
-		fmt.Fprintln(os.Stderr, "错误: --mount-mode 必须是 auto / full / mutagen-only / sshfs-only 之一")
+		fmt.Fprintln(os.Stderr, "错误: --mount-mode 必须是 auto / full / hot-only / sshfs-only 之一（兼容 legacy: mutagen-only）")
 		os.Exit(exitConfigError)
 	}
 
diff --git a/cmd/cloud-claude/sync.go b/cmd/cloud-claude/sync.go
@@ -2,9 +2,6 @@ package main
 
 import (
 	"fmt"
-	"os"
-	"os/exec"
-	"path/filepath"
 
 	"github.com/spf13/cobra"
 
@@ -13,21 +10,22 @@ import (
 
 // newSyncCmd 构造 cloud-claude sync 父命令树。
 //
-// Phase 31 Plan 03 仅注册 sync conflicts 子命令（CONTEXT D-28 — 最小可行版本）；
-// sync resolve / sync resume 等 wrapper 由 v3.1 落地（OOS-A2 不暴露 5 种冲突模式）。
+// 自研 hot sync 当前只暴露 conflicts 查询：
+// 读取 ~/.cloud-claude/last-session.json 的 conflict_count，提示用户最近一次会话
+// 是否出现自动 resolved 的双向冲突。逐文件清单暂未持久化。
 func newSyncCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:           "sync",
-		Short:         "Mutagen 同步管理（v3.0 三层文件映射）",
-		Long:          "查看本地 Mutagen 客户端管理的 cloud-claude 同步会话与冲突文件清单。\n注：当前仅实现 sync conflicts 子命令；sync resolve / sync resume 留 v3.1。",
+		Short:         "热同步相关工具",
+		Long:          "查看 cloud-claude 自研热同步的最近一次冲突计数等状态。\n当前仅实现 sync conflicts 子命令；逐文件冲突清单留后续版本补齐。",
 		SilenceUsage:  true,
 		SilenceErrors: true,
 	}
 
 	conflictsCmd := &cobra.Command{
 		Use:           "conflicts",
-		Short:         "查看当前 Mutagen 同步会话的冲突文件清单",
-		Long:          "调用本地 Mutagen 客户端 sync list --long 渲染所有 cloud-claude 创建的 sync session 的冲突文件（path / alpha / beta / mtime）。",
+		Short:         "查看最近一次热同步冲突计数",
+		Long:          "读取 ~/.cloud-claude/last-session.json 中的 conflict_count。\n当前自研热同步会在运行时实时提示冲突，但尚未持久化逐文件清单。",
 		SilenceUsage:  true,
 		SilenceErrors: true,
 		RunE:          runSyncConflicts,
@@ -36,35 +34,18 @@ func newSyncCmd() *cobra.Command {
 	return cmd
 }
 
-// runSyncConflicts 执行 ~/.cloud-claude/bin/mutagen sync list --long 并把结果直接打到
-// stdout / stderr。本地命令出错时返回中文错误，由 cobra runE 错误处理流程 stderr 打印。
-//
-// 行为约束：
-//   - 不发起 SSH 连接（本子命令只查本地 mutagen daemon 状态，不需要联网）
-//   - ExtractMutagenBinary 幂等保证 ~/.cloud-claude/bin/mutagen 存在
-//   - MUTAGEN_DATA_DIRECTORY 环境变量隔离与主流程一致（CONTEXT D-05）
+// runSyncConflicts 仅读取本地上次会话快照，不发起 SSH 连接。
+// 当前实现不再依赖 Mutagen daemon，也不维护逐文件冲突清单。
 func runSyncConflicts(cmd *cobra.Command, args []string) error {
-	home, err := os.UserHomeDir()
+	snap, err := cloudclaude.LoadLastSession()
 	if err != nil {
-		return fmt.Errorf("无法获取用户主目录: %w", err)
-	}
-
-	binPath := filepath.Join(home, ".cloud-claude", "bin", "mutagen")
-	if err := cloudclaude.ExtractMutagenBinary(binPath); err != nil {
-		return fmt.Errorf("无法准备 Mutagen 二进制: %w", err)
+		return fmt.Errorf("无法读取最近一次会话快照: %w", err)
 	}
-
-	env := append(os.Environ(),
-		"MUTAGEN_DATA_DIRECTORY="+filepath.Join(home, ".cloud-claude", "mutagen"),
-	)
-
-	// sync list --long 输出含每个 session 的冲突详细信息（path / alpha / beta / mtime）
-	c := exec.Command(binPath, "sync", "list", "--long")
-	c.Env = env
-	c.Stdout = os.Stdout
-	c.Stderr = os.Stderr
-	if err := c.Run(); err != nil {
-		return fmt.Errorf("查询 Mutagen 冲突清单失败: %w", err)
+	if snap.ConflictCount <= 0 {
+		fmt.Println("最近一次会话未记录热同步冲突。")
+		return nil
 	}
+	fmt.Printf("最近一次会话记录到 %d 个热同步冲突。\n", snap.ConflictCount)
+	fmt.Println("当前版本仅持久化冲突计数；逐文件冲突会在运行 cloud-claude 时实时提示。")
 	return nil
 }
diff --git a/internal/cloudclaude/doctor/doctor.go b/internal/cloudclaude/doctor/doctor.go
@@ -225,8 +225,6 @@ func RunDoctor(ctx context.Context, opts Options) (*Report, error) {
 	// 6) mount 维度
 	if want("mount") {
 		ensureRemote()
-		report.Checks = append(report.Checks, runWithTimeout(ctx, "mount", "mutagen_version_match", timeout,
-			func(c context.Context) Check { return checkMutagenVersionMatch(c, remoteRunner) }))
 		report.Checks = append(report.Checks, runWithTimeout(ctx, "mount", "mergerfs_branches", timeout,
 			func(c context.Context) Check { return checkMergerfsBranches(c, remoteRunner) }))
 		report.Checks = append(report.Checks, runWithTimeout(ctx, "mount", "sshfs_mountpoint", timeout,
@@ -241,7 +239,6 @@ func RunDoctor(ctx context.Context, opts Options) (*Report, error) {
 		report.Checks = append(report.Checks, checkLocalDisk(ctx))
 		report.Checks = append(report.Checks, runWithTimeout(ctx, "disk", "container_disk", timeout,
 			func(c context.Context) Check { return checkContainerDisk(c, remoteRunner) }))
-		report.Checks = append(report.Checks, checkMutagenDataSize(ctx))
 	}
 
 	// 8) 聚合 Summary
diff --git a/internal/cloudclaude/doctor/render.go b/internal/cloudclaude/doctor/render.go
@@ -85,7 +85,7 @@ func renderDowngradeBanner(banner *DowngradeBanner) string {
 		fmt.Fprintf(&b, "  角色: %s\n", banner.ClientRole)
 	}
 	if banner.ConflictCount > 0 {
-		fmt.Fprintf(&b, "  Mutagen 冲突: %d 个\n", banner.ConflictCount)
+		fmt.Fprintf(&b, "  热同步冲突: %d 个\n", banner.ConflictCount)
 	}
 	if banner.ReconnectCount > 0 {
 		fmt.Fprintf(&b, "  重连次数: %d\n", banner.ReconnectCount)
diff --git a/internal/cloudclaude/doctor/render_test.go b/internal/cloudclaude/doctor/render_test.go
@@ -15,15 +15,15 @@ func TestDowngradeBannerRendersChain(t *testing.T) {
 		IntendedMode:       "full",
 		ActualMode:         "sshfs-only",
 		DowngradeChain: []DowngradeStep{
-			{From: "full", To: "mutagen-only", ReasonCode: "MOUNT_MUTAGEN_VERSION_SKEW", ReasonMessage: "version skew"},
-			{From: "mutagen-only", To: "sshfs-only", ReasonCode: "MOUNT_AUTO_DOWNGRADED", ReasonMessage: "daemon died"},
+			{From: "full", To: "hot-only", ReasonCode: "MOUNT_MERGERFS_FAILED", ReasonMessage: "merge failed"},
+			{From: "hot-only", To: "sshfs-only", ReasonCode: "MOUNT_AUTO_DOWNGRADED", ReasonMessage: "hot sync failed"},
 		},
 	}
 	out := renderDowngradeBanner(banner)
 	for _, want := range []string{
-		"[降级] full → mutagen-only",
-		"[降级] mutagen-only → sshfs-only",
-		"MOUNT_MUTAGEN_VERSION_SKEW",
+		"[降级] full → hot-only",
+		"[降级] hot-only → sshfs-only",
+		"MOUNT_MERGERFS_FAILED",
 		"MOUNT_AUTO_DOWNGRADED",
 		"意图=full",
 		"实际=sshfs-only",
diff --git a/internal/cloudclaude/errcodes/explanations.go b/internal/cloudclaude/errcodes/explanations.go
@@ -111,9 +111,9 @@ func init() {
 修复路径：观察 stderr 提示的下游错误码（[CODE] 后面的部分）针对修复；运行 cloud-claude doctor mount 看完整健康度；如要锁定模式可用 --mount-mode flag 强制。
 关联文档：Phase 31 RESEARCH §6 / Phase 31 PITFALLS M13（禁止静默降级）`)
 
-	registerExplanation(MOUNT_FORCE_MODE_FAILED, `触发场景：用户通过 --mount-mode={full,mutagen-only,sshfs-only} 强制指定模式，但该模式启动失败。强制模式下 cloud-claude 不会自动降级。
-根本原因：用户显式指定模式意味着接受失败即报错的语义（M13 防御静默降级）。常见触发为 mutagen-only 模式下 daemon 不可用、sshfs-only 模式下 fuse 不可用。
-复现方式：cloud-claude --mount-mode=mutagen-only 但本机 mutagen daemon 起不来 → SeverityFatal 阻断。
+registerExplanation(MOUNT_FORCE_MODE_FAILED, `触发场景：用户通过 --mount-mode={full,hot-only,sshfs-only} 强制指定模式，但该模式启动失败。强制模式下 cloud-claude 不会自动降级。
+根本原因：用户显式指定模式意味着接受失败即报错的语义（M13 防御静默降级）。常见触发为 hot-only 模式下热同步初始化失败、sshfs-only 模式下 fuse 不可用。
+复现方式：cloud-claude --mount-mode=hot-only 但远端同路径目录不可写 → SeverityFatal 阻断。
 修复路径：移除 --mount-mode flag 让自动降级生效，或针对错误信息中的具体下游 code 修复；需要锁定模式时建议先运行 cloud-claude doctor mount 看可用层。
 关联文档：Phase 31 PLAN <errcode_registry> / Phase 31 PITFALLS M13`)
 
diff --git a/internal/cloudclaude/exitcodes.go b/internal/cloudclaude/exitcodes.go
@@ -25,5 +25,5 @@ const (
 	// 6-8：v3.0 Phase 31 新增（OAuth + mount force）
 	ExitOAuthNotFound    = 6 // /home/claude/.claude/.credentials.json 不存在或解析失败（D-22 第 3 条）
 	ExitOAuthExpired     = 7 // expiresAt < now（D-22 第 3 条）
-	ExitMountForceFailed = 8 // --mount-mode=full|mutagen-only|sshfs-only 任一档失败（D-15 / errcodes.MOUNT_FORCE_MODE_FAILED）
+	ExitMountForceFailed = 8 // --mount-mode=full|hot-only|sshfs-only 任一档失败（兼容 legacy: mutagen-only）
 )
diff --git a/internal/cloudclaude/ignore.go b/internal/cloudclaude/ignore.go
@@ -183,6 +183,17 @@ func (m *IgnoreMatcher) IsIgnoredRel(rel string, isDir bool) bool {
 	return ignored
 }
 
+// isHardcodedSkipDir 是热同步/体积统计共用的目录白名单。
+// 这些目录通常是依赖缓存或构建产物，不应进入热同步，也应在本地扫描时直接 SkipDir。
+func isHardcodedSkipDir(name string) bool {
+	switch name {
+	case "node_modules", "target", "dist", ".venv", "__pycache__",
+		".next", "build", ".cache", ".git":
+		return true
+	}
+	return false
+}
+
 // compileIgnoreRule 把一行 gitignore pattern 编译成 ignoreRule。
 // 返回 ok=false 表示该行是空、注释或无法编译，调用方应跳过。
 func compileIgnoreRule(raw string) (ignoreRule, bool) {
diff --git a/internal/cloudclaude/integration_test.go b/internal/cloudclaude/integration_test.go
@@ -178,7 +178,7 @@ func TestIntegration_F2B_KillMutagenAgent_DowngradesIn2s(t *testing.T) {
 	}
 	if !strings.Contains(stderr, string(errcodes.MOUNT_AUTO_DOWNGRADED)) &&
 		!strings.Contains(stderr, "[sshfs-only]") &&
-		!strings.Contains(stderr, "[mutagen-only]") {
+		!strings.Contains(stderr, "[hot-only]") {
 		t.Errorf("期望降级 banner，stderr: %s", stderr)
 	}
 }
diff --git a/internal/cloudclaude/last_session_test.go b/internal/cloudclaude/last_session_test.go
@@ -16,9 +16,9 @@ func Test_WriteLastSession_Schema(t *testing.T) {
 
 	snap := LastSessionSnapshot{
 		IntendedMode: "auto",
-		ActualMode:   "mutagen-only",
+		ActualMode:   "hot-only",
 		DowngradeChain: []DowngradeStep{
-			{From: "full", To: "mutagen-only", ReasonCode: "MOUNT_MERGERFS_FAILED", ReasonMessage: "mergerfs 失败"},
+			{From: "full", To: "hot-only", ReasonCode: "MOUNT_MERGERFS_FAILED", ReasonMessage: "mergerfs 失败"},
 		},
 		ConflictCount:       3,
 		ClaudeAccountID:     "acc_xyz",
@@ -44,7 +44,7 @@ func Test_WriteLastSession_Schema(t *testing.T) {
 	if v, _ := got["schema_version"].(float64); v != 1 {
 		t.Errorf("schema_version = %v, want 1", got["schema_version"])
 	}
-	if got["actual_mode"] != "mutagen-only" {
+	if got["actual_mode"] != "hot-only" {
 		t.Errorf("actual_mode = %v", got["actual_mode"])
 	}
 	if got["intended_mode"] != "auto" {
@@ -68,7 +68,7 @@ func Test_WriteLastSession_Schema(t *testing.T) {
 	if !ok {
 		t.Fatal("downgrade_chain[0] 不是 object")
 	}
-	if step["from"] != "full" || step["to"] != "mutagen-only" {
+	if step["from"] != "full" || step["to"] != "hot-only" {
 		t.Errorf("downgrade_chain[0] from/to 异常: %v", step)
 	}
 	if step["reason_code"] != "MOUNT_MERGERFS_FAILED" {
diff --git a/internal/cloudclaude/mount_strategy.go b/internal/cloudclaude/mount_strategy.go
@@ -19,6 +19,7 @@ import (
 // 状态机契约：
 //   - 入参允许 Auto / Full / MutagenOnly / SSHFSOnly
 //   - 返回时永远是 Full / MutagenOnly / SSHFSOnly / Failed 之一（Auto 仅作为入参意图）
+//   - 注意：ModeMutagenOnly 仅保留内部枚举兼容，用户可见字面值统一为 hot-only
 type Mode int
 
 const (
@@ -37,7 +38,7 @@ func (m Mode) String() string {
 	case ModeFull:
 		return "full"
 	case ModeMutagenOnly:
-		return "mutagen-only"
+		return "hot-only"
 	case ModeSSHFSOnly:
 		return "sshfs-only"
 	case ModeFailed:
@@ -55,12 +56,12 @@ func ParseMode(s string) (Mode, error) {
 		return ModeAuto, nil
 	case "full":
 		return ModeFull, nil
-	case "mutagen-only":
+	case "hot-only", "mutagen-only":
 		return ModeMutagenOnly, nil
 	case "sshfs-only":
 		return ModeSSHFSOnly, nil
 	default:
-		return ModeFailed, fmt.Errorf("非法 mount-mode 值: %q（应为 auto|full|mutagen-only|sshfs-only）", s)
+		return ModeFailed, fmt.Errorf("非法 mount-mode 值: %q（应为 auto|full|hot-only|sshfs-only；兼容 legacy: mutagen-only）", s)
 	}
 }
 
@@ -96,14 +97,6 @@ type MountConfig struct {
 	// last-session.json 的 ClientRole 写为 "secondary"（默认 "primary"）。
 	IsSecondaryClient bool
 
-	// Mutagen beta URL 需要的 SSH 连接参数，从 ConnectAndRunClaudeV3 的
-	// SSHConfig 透传过来。sshfs-only 模式下这些字段不使用（sshfs 走现有的
-	// connA/connB channel，不需要另起 ssh 子进程）。
-	SSHUser     string
-	SSHHost     string
-	SSHPort     int
-	SSHPassword string
-
 	// 测试 hook：仅用于单测注入；生产路径 nil 时走真实实现。
 	overrideCaseInsensitive *bool
 	hooks                   *strategyHooks
@@ -287,7 +280,7 @@ func MountWorkspace(connA, connB *ssh.Client, cfg MountConfig) (cleanup func(),
 
 // tryMode 按 mode 调度子层：
 //   - Full = mutagen + sshfs + merge（任一失败即失败）
-//   - MutagenOnly = mutagen 单层
+//   - MutagenOnly = hot-only 单层
 //   - SSHFSOnly = sshfs 单层（v2.0 路径）
 //
 // 测试通过 cfg.hooks 注入 mock；生产走 tryModeReal。
@@ -457,7 +450,7 @@ func printProgress(w io.Writer, mode Mode) {
 		fmt.Fprintf(w, "(2/3) 跳过 sshfs（模式: %s）\n", mode.String())
 		fmt.Fprintf(w, "(3/3) 跳过 mergerfs（模式: %s）\n", mode.String())
 	case ModeSSHFSOnly:
-		fmt.Fprintf(w, "(1/3) 跳过 Mutagen（模式: %s）\n", mode.String())
+		fmt.Fprintf(w, "(1/3) 跳过热同步（模式: %s）\n", mode.String())
 		fmt.Fprintln(w, "(2/3) 启动冷兜底…")
 		fmt.Fprintf(w, "(3/3) 跳过 mergerfs（模式: %s）\n", mode.String())
 	}
diff --git a/internal/cloudclaude/mount_strategy_test.go b/internal/cloudclaude/mount_strategy_test.go
@@ -179,7 +179,7 @@ func Test_BannerColors(t *testing.T) {
 	t.Run("contains banner text + mode", func(t *testing.T) {
 		var buf bytes.Buffer
 		printBanner(&buf, ModeMutagenOnly, true)
-		if !strings.Contains(buf.String(), "✓ 文件映射就绪 [mutagen-only]") {
+		if !strings.Contains(buf.String(), "✓ 文件映射就绪 [hot-only]") {
 			t.Errorf("banner missing mode tag: %q", buf.String())
 		}
 	})
@@ -316,7 +316,7 @@ func Test_Downgrade_CapabilityFromAuthResp(t *testing.T) {
 		}
 		cleanup()
 		if mode != ModeMutagenOnly {
-			t.Errorf("mode=%s, want mutagen-only", mode)
+			t.Errorf("mode=%s, want hot-only", mode)
 		}
 	})
 }
@@ -326,6 +326,7 @@ func Test_ParseMode(t *testing.T) {
 		"":             ModeAuto,
 		"auto":         ModeAuto,
 		"full":         ModeFull,
+		"hot-only":     ModeMutagenOnly,
 		"mutagen-only": ModeMutagenOnly,
 		"sshfs-only":   ModeSSHFSOnly,
 	}

Original file line number	Diff line number	Diff line change
`@@ -85,7 +85,7 @@ func renderDowngradeBanner(banner *DowngradeBanner) string {`
`85`	`85`	`fmt.Fprintf(&b, " 角色: %s\n", banner.ClientRole)`
`86`	`86`	`}`
`87`	`87`	`if banner.ConflictCount > 0 {`
`88`		`- fmt.Fprintf(&b, " Mutagen 冲突: %d 个\n", banner.ConflictCount)`
	`88`	`+ fmt.Fprintf(&b, " 热同步冲突: %d 个\n", banner.ConflictCount)`
`89`	`89`	`}`
`90`	`90`	`if banner.ReconnectCount > 0 {`
`91`	`91`	`fmt.Fprintf(&b, " 重连次数: %d\n", banner.ReconnectCount)`
Original file line number	Diff line number	Diff line change
`@@ -25,5 +25,5 @@ const (`
`25`	`25`	`// 6-8：v3.0 Phase 31 新增（OAuth + mount force）`
`26`	`26`	`ExitOAuthNotFound = 6 // /home/claude/.claude/.credentials.json 不存在或解析失败（D-22 第 3 条）`
`27`	`27`	`ExitOAuthExpired = 7 // expiresAt < now（D-22 第 3 条）`
`28`		`- ExitMountForceFailed = 8 // --mount-mode=full\|mutagen-only\|sshfs-only 任一档失败（D-15 / errcodes.MOUNT_FORCE_MODE_FAILED）`
	`28`	`+ ExitMountForceFailed = 8 // --mount-mode=full\|hot-only\|sshfs-only 任一档失败（兼容 legacy: mutagen-only）`
`29`	`29`	`)`
Original file line number	Diff line number	Diff line change
`@@ -178,7 +178,7 @@ func TestIntegration_F2B_KillMutagenAgent_DowngradesIn2s(t *testing.T) {`
`178`	`178`	`}`
`179`	`179`	`if !strings.Contains(stderr, string(errcodes.MOUNT_AUTO_DOWNGRADED)) &&`
`180`	`180`	`!strings.Contains(stderr, "[sshfs-only]") &&`
`181`		`- !strings.Contains(stderr, "[mutagen-only]") {`
	`181`	`+ !strings.Contains(stderr, "[hot-only]") {`
`182`	`182`	`t.Errorf("期望降级 banner，stderr: %s", stderr)`
`183`	`183`	`}`
`184`	`184`	`}`