Add update step logs, result consumption and stale temp file cleanup

Author: YuLaiZ

internal/cli/update.go

@@ -7,6 +7,7 @@ import (
 	"io"
 	"os"
 	goruntime "runtime"
+	"time"
 
 	"github.com/spf13/cobra"
 
@@ -102,6 +103,24 @@ func defaultUpdateServiceFactory(info buildinfo.Info, checkOnly bool) (UpdateSer
 		svc.Installer = buildUpdateInstaller()
 		svc.AssetDownloader = downloader
 		svc.VersionProbe = update.NewExecVersionProbe()
+
+		// 打开升级日志文件并注入 LogSink/LogPath + installer 的 writer/logDir。
+		// 日志打开失败是 best-effort：Apply 不依赖日志也能工作。
+		if home, herr := os.UserHomeDir(); herr == nil {
+			logDir := update.ResolveUpdateLogDir(home)
+			if f, logPath, oerr := update.OpenUpdateLogFile(logDir, time.Now()); oerr == nil {
+				svc.LogSink = f
+				svc.LogPath = logPath
+				// POSIX 安装器接收 logWriter 输出 [install] 行；Windows 安装器接收 logDir
+				// 重定向 helper stderr。经类型断言注入，使工厂无需知道安装器具体类型。
+				if s, ok := svc.Installer.(update.StepLogWriter); ok {
+					s.SetLogWriter(f)
+				}
+				if s, ok := svc.Installer.(update.HelperLogDirSetter); ok {
+					s.SetLogDir(logDir)
+				}
+			}
+		}
 	}
 	return svc, nil
 }
@@ -182,6 +201,11 @@ func runUpdate(cmd *cobra.Command, info buildinfo.Info) error {
 		return err
 	}
 
+	// 升级日志文件在工厂内打开，命令返回前关闭句柄（仅 *update.Service 有此方法）。
+	if rs, ok := svc.(*update.Service); ok {
+		defer rs.CloseLogSink()
+	}
+
 	ctx := cmdContext(cmd)
 
 	if checkOnly {
@@ -237,9 +261,16 @@ func runUpdateApply(ctx context.Context, cmd *cobra.Command, svc UpdateService,
 	res, err := svc.Apply(ctx, update.ApplyOptions{TargetTag: versionFlag})
 	if err != nil {
 		fmt.Fprintf(errOut, "更新失败: %v\n", err)
+		if res.LogPath != "" {
+			fmt.Fprintf(out, "升级日志: %s\n", res.LogPath)
+		}
 		return err
 	}
-	return renderApplyResult(out, errOut, res)
+	renderErr := renderApplyResult(out, errOut, res)
+	if res.LogPath != "" {
+		fmt.Fprintf(out, "升级日志: %s\n", res.LogPath)
+	}
+	return renderErr
 }
 
 // renderApplyResult 把 ApplyResult 翻译为面向用户的中文提示。

internal/cli/update_helper_windows.go

@@ -49,7 +49,7 @@ func runUpdateHelperCmd(ctx context.Context, planPath string) error {
 	}
 	cm := update.NewControlManager(mgr)
 
-	runner, err := update.NewHelperRunner(parent, mover, result, cm, loadConfig)
+	runner, err := update.NewHelperRunner(parent, mover, result, cm, loadConfig, os.Stderr)
 	if err != nil {
 		return fmt.Errorf("装配 helper runner 失败: %w", err)
 	}

internal/update/apply_download_test.go

@@ -99,16 +99,21 @@ func TestApply_TrustedDownloadsStageViaAssetDownloader(t *testing.T) {
 	if stagePath == "" {
 		t.Fatal("stagePath 不应为空（已注入 AssetDownloader，应下载到真实 stage）")
 	}
-	content, rerr := os.ReadFile(stagePath)
-	if rerr != nil {
-		t.Fatalf("读取 stage 失败 %s: %v", stagePath, rerr)
+	// stage 内容须在 Install 内捕获：Apply 成功后外部 stage 已删（removeRegularFile）。
+	if len(installer.stageContents) != 1 || installer.stageContents[0] == nil {
+		t.Fatalf("应在 Install 内捕获 stage 内容，stageContents=%v", installer.stageContents)
 	}
+	content := installer.stageContents[0]
 	if string(content) != string(targetBin) {
 		t.Fatalf("stage 内容不匹配，got %q want %q", string(content), string(targetBin))
 	}
 	if filepath.Dir(stagePath) != filepath.Dir(got.BinaryPath) {
 		t.Errorf("stage 目录 %q 应与 target 同目录 %q", filepath.Dir(stagePath), filepath.Dir(got.BinaryPath))
 	}
+	// 外部 stage 文件应在 Apply 后被删除。
+	if _, err := os.Stat(stagePath); !os.IsNotExist(err) {
+		t.Errorf("外部 stage 应在 Apply 后删除: %s", stagePath)
+	}
 }
 
 // TestApply_DownloadFailureRejectsInstall 目标资产下载失败（500）：

internal/update/helper_plan.go

@@ -297,7 +297,7 @@ func validateHelperPlanFields(plan helperPlan) error {
 //
 // 严格安全：只删除 (selfDir, targetBasename, nonce) 派生的精确路径，且只删普通文件
 // （拒绝 symlink / 目录）；不存在的文件视为已清理（幂等）。绝不按前缀模糊匹配。
-// 不删除 result 文件——它供下一次 update --check 展示，由后续更新覆盖或人工查看。
+// 不删除 result 文件——它供下次完整 update（Apply）在来源校验通过后消费，由后续更新覆盖或人工查看。
 func CleanupHelperTempFiles(selfDir, targetBasename, nonce string) error {
 	if selfDir == "" || targetBasename == "" || nonce == "" {
 		return errors.New("清理 helper 临时文件的 selfDir/targetBasename/nonce 不能为空")

internal/update/helper_plan_test.go

@@ -445,7 +445,7 @@ func TestIsHexNonce(t *testing.T) {
 }
 
 // TestCleanupHelperTempFiles_DeletesNonceBoundFiles 清理 helper 临时文件：
-// 删除 helper.exe/plan/stage/backup，保留 result（供下次 update --check 展示）。
+// 删除 helper.exe/plan/stage/backup，保留 result（供下次完整 update 在来源校验通过后消费）。
 func TestCleanupHelperTempFiles_DeletesNonceBoundFiles(t *testing.T) {
 	dir := t.TempDir()
 	const base = "token-usage"
@@ -466,7 +466,7 @@ func TestCleanupHelperTempFiles_DeletesNonceBoundFiles(t *testing.T) {
 			t.Errorf("临时文件 %s 应被删除", p)
 		}
 	}
-	// result 应保留（供下次 update --check 展示）。
+	// result 应保留（供下次完整 update 在来源校验通过后消费）。
 	if _, err := os.Stat(paths.Result); err != nil {
 		t.Errorf("result 文件应保留，stat err=%v", err)
 	}

internal/update/helper_runner.go

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"io"
 
 	"github.com/YuLaiZ/token-usage/internal/config"
 	"github.com/YuLaiZ/token-usage/internal/control"
@@ -17,7 +18,7 @@ import (
 //  2. 等待父进程退出（释放对旧 .exe 的句柄）；
 //  3. 在 control lock 内：确认 daemon 未在停止后意外运行 → 备份旧 target →
 //     MoveFileEx(stage→target) → 校验新 hash → 按 wasRunning 重启 daemon；
-//  4. 把执行结果写入 result 文件，供父进程下一次 update --check 展示；
+//  4. 把执行结果写入 result 文件，供下次完整 update（Apply）在来源校验通过后消费；
 //  5. 任一步失败：从 backup 回滚 target、必要时重启旧 daemon、写失败 result。
 //
 // 所有外部依赖（等待父进程、文件移动、结果写入、control lock）经字段注入，
@@ -38,15 +39,18 @@ type helperRunner struct {
 	resultWriter ResultWriter         // 写 result 文件
 	controlMgr   ControlManager       // control lock（daemon 检查 / 重启）
 	configLoader control.ConfigLoader // 锁内加载有效配置
+	helperLog    *stepLogger          // [helper] 步骤日志（从 logWriter 构造，nil=静默）
 }
 
-// NewHelperRunner 构造后台 helper 编排器。所有依赖必须非空（否则 Run 返回装配错误）。
+// NewHelperRunner 构造后台 helper 编排器。前五个依赖必须非空（否则返回装配错误）；
+// logWriter 可为 nil（静默），生产由 CLI 注入 os.Stderr（父进程 spawn 时重定向到日志文件）。
 func NewHelperRunner(
 	parentWaiter ParentWaiter,
 	fileMover FileMover,
 	resultWriter ResultWriter,
 	controlMgr ControlManager,
 	configLoader control.ConfigLoader,
+	logWriter io.Writer,
 ) (*helperRunner, error) {
 	if parentWaiter == nil || fileMover == nil || resultWriter == nil || controlMgr == nil || configLoader == nil {
 		return nil, errors.New("helperRunner 所有依赖不能为空")
@@ -57,6 +61,7 @@ func NewHelperRunner(
 		resultWriter: resultWriter,
 		controlMgr:   controlMgr,
 		configLoader: configLoader,
+		helperLog:    newStepLogger(logWriter, "helper", nil),
 	}, nil
 }
 
@@ -77,12 +82,14 @@ func (r *helperRunner) Run(ctx context.Context, selfExe, planPath string) error
 // execute 在计划校验通过后执行：等待父进程 → 加载配置 → control lock 内替换。
 func (r *helperRunner) execute(ctx context.Context, validated validatedHelperPlan) error {
 	plan, paths := validated.Plan, validated.Paths
+	r.helperLog.step("started (nonce=%s)", plan.Nonce)
 
 	// 2. 等待父进程退出（据 plan 中的显式身份，杜绝 PID 复用 TOCTOU）。
 	if err := r.parentWaiter.WaitParentExit(ctx, plan.Parent); err != nil {
 		r.fail(paths.Result, fmt.Errorf("等待父进程失败: %w", err), "")
 		return err
 	}
+	r.helperLog.step("parent exited")
 
 	// 3. 加载有效配置（control lock 内复用）。
 	cfg, err := r.configLoader()
@@ -96,9 +103,20 @@ func (r *helperRunner) execute(ctx context.Context, validated validatedHelperPla
 	}
 
 	// 4. control lock 内完成 daemon 检查 + 替换 + 重启。
-	return r.controlMgr.WithLock(ctx, func(sess ControlSession) error {
+	// WithLock 在锁获取失败（超时/context 取消）时不执行回调——此时 executeUnderLock 不会被
+	// 调用，fail/succeed 也不会写 result。用 lockEntered 跟踪回调是否已进入：未进入时补写
+	// 失败 result，使下次 update 能消费该失败（父命令已报告 Deferred，用户以为升级在进行中）；
+	// 已进入时 executeUnderLock 内部已通过 fail/succeed 写了 result，不覆盖。
+	lockEntered := false
+	lockErr := r.controlMgr.WithLock(ctx, func(sess ControlSession) error {
+		lockEntered = true
 		return r.executeUnderLock(ctx, sess, cfg, plan, paths)
 	})
+	if lockErr != nil && !lockEntered {
+		r.fail(paths.Result, fmt.Errorf("获取 control lock 失败: %w", lockErr), "")
+		return lockErr
+	}
+	return lockErr
 }
 
 // executeUnderLock 在 control lock 持有期内完成替换与 daemon 切换。
@@ -122,12 +140,14 @@ func (r *helperRunner) executeUnderLock(ctx context.Context, sess ControlSession
 		r.fail(paths.Result, errors.New("daemon 在停止后意外运行，放弃替换"), "")
 		return errors.New("daemon 运行中，放弃替换")
 	}
+	r.helperLog.step("daemon wasRunning=%v", plan.WasRunning)
 
 	// b. 备份旧 target → backup，校验旧 hash。
 	if err := backupForHelper(paths.Target, paths.Backup, plan.OldSHA256); err != nil {
 		r.fail(paths.Result, fmt.Errorf("备份旧 target 失败: %w", err), "")
 		return fmt.Errorf("备份旧 target 失败: %w", err)
 	}
+	r.helperLog.step("backup OK")
 
 	// c. MoveFileEx(stage → target)。
 	if err := r.fileMover.MoveReplace(paths.Stage, paths.Target); err != nil {
@@ -136,13 +156,15 @@ func (r *helperRunner) executeUnderLock(ctx context.Context, sess ControlSession
 		r.fail(paths.Result, fmt.Errorf("MoveFileEx 替换失败: %w", err), errToString(rbErr))
 		return fmt.Errorf("MoveFileEx 替换失败（已回滚）: %w", errors.Join(err, rbErr))
 	}
+	r.helperLog.step("MoveFileEx OK")
 
 	// 校验新 target hash（防御移动过程中损坏）。
 	if err := verifyFileHash(paths.Target, plan.NewSHA256); err != nil {
 		rbErr := rollbackForHelper(paths.Target, paths.Backup, plan.OldSHA256)
 		r.fail(paths.Result, fmt.Errorf("替换后新 target 校验失败: %w", err), errToString(rbErr))
 		return fmt.Errorf("替换后新 target 校验失败（已回滚）: %w", errors.Join(err, rbErr))
 	}
+	r.helperLog.step("hash verified")
 
 	// d. wasRunning → 启动新 daemon。
 	if plan.WasRunning {
@@ -158,6 +180,7 @@ func (r *helperRunner) executeUnderLock(ctx context.Context, sess ControlSession
 				fmt.Sprintf("rollback=%v restart=%v", rbErr, restartErr))
 			return fmt.Errorf("启动新 daemon 失败（已回滚重启）: %w", errors.Join(serr, rbErr, restartErr))
 		}
+		r.helperLog.step("daemon restarted")
 	}
 
 	// e. 成功。
@@ -190,24 +213,35 @@ func rollbackForHelper(target, backup, expectedOldHash string) error {
 	return verifyFileHash(target, expectedOldHash)
 }
 
-// succeed 写成功 result。
+// succeed 写成功 result，并据写入结果记终态日志（result=ok 或 result write failed）。
 func (r *helperRunner) succeed(resultPath string) {
-	r.writeResult(resultPath, helperResult{Success: true})
+	if err := r.writeResult(resultPath, helperResult{Success: true}); err != nil {
+		r.helperLog.step("result write failed: %v", err)
+	} else {
+		r.helperLog.step("result=ok")
+	}
 }
 
-// fail 写失败 result（error + 可选 rollback 信息）。
+// fail 写失败 result（error + 可选 rollback 信息），并据写入结果记终态日志。
+// 注意：result=ok 表示 result 文件写入成功（终态日志三态：ok/failure recorded/write failed），
+// fail 路径用 result=failure recorded 区分于 succeed 路径的 result=ok。
 func (r *helperRunner) fail(resultPath string, cause error, rollback string) {
-	r.writeResult(resultPath, helperResult{Success: false, Error: cause.Error(), Rollback: rollback})
+	if err := r.writeResult(resultPath, helperResult{Success: false, Error: cause.Error(), Rollback: rollback}); err != nil {
+		r.helperLog.step("result write failed: %v", err)
+	} else {
+		r.helperLog.step("result=failure recorded")
+	}
 }
 
-// writeResult 把 result JSON 序列化后写入 resultPath（0600 权限）。
-func (r *helperRunner) writeResult(resultPath string, res helperResult) {
+// writeResult 把 result JSON 序列化后写入 resultPath（0600 权限），返回写入错误。
+// 序列化失败或写入失败返回 error；调用方据此记终态日志。result 写入失败不改变已完成
+// 替换的主成功结果（仅记日志），下次 consume 读不到则留待人工。
+func (r *helperRunner) writeResult(resultPath string, res helperResult) error {
 	data, err := marshalHelperResult(res)
 	if err != nil {
-		// 序列化失败属于编程错误；result 写不了，只能放弃（不影响主流程错误）。
-		return
+		return fmt.Errorf("序列化 result 失败: %w", err)
 	}
-	_ = r.resultWriter.WriteResult(resultPath, data, 0o600)
+	return r.resultWriter.WriteResult(resultPath, data, 0o600)
 }
 
 // marshalHelperResult 序列化 helperResult 为 JSON。